أدوات التحرير المهيكل (update_*)

في سطر واحد: كيف تتيح أدوات update_* لأداة AI خارجية أن تعدّل لوحة الإيقاعات أو الخط الزمني أو السيناريو أو خريطة العلاقات أو خريطة العالم، من دون أن تُسقط الأجزاء التي لم ترَها قطّ.

ما الذي يحلّه هذا

ملف النثر يُعاد كتابته كاملًا بلا خطر. قرأ الـ AI ملف .md كله، فيستطيع أن يعيده كله، وأسوأ ما قد يحدث كتابة رديئة تتراجع عنها من سجل الإصدارات.

الملفات المهيكلة بلا هذه الشبكة. ملف .beats واحد يحمل فصولًا وإيقاعات وبطاقات فصول المخطوطة التي سحبها المؤلف بنفسه إلى اللوحة. وملف .map يحمل عُقدًا وخطوط علاقات وصناديق تجميع وموضع كل عقدة على مساحة الرسم. أن تطلب من AI أن يعيد الـ JSON كاملًا يعني أن تطلب منه إعادة ما لم يُعرض عليه أصلًا. سيحاول، والفشل هنا صامت: الملف يفتح كالمعتاد، لكنّ فيه من عمل المؤلف أقلّ مما كان.

لهذا أغلق خادم 4.0 الكتابة الكاملة على هذه الامتدادات الخمسة. write_file وedit_file وappend_to_file تُرفض جميعًا، وتحلّ محلّها أداةٌ حقلية واحدة لكل نوع، تعمل بعملية واحدة في كل مرة.

الامتداد	الأداة	العمليات
.beats لوحة الإيقاعات	update_beat_board	add_act / update_act / remove_act / add_beat / update_beat / remove_beat / move_beat
.timeline الخط الزمني	update_timeline	add_entry / update_entry / remove_entry / set_config
.script السيناريو	update_script	add_scene / update_scene_heading / remove_scene / add_element / update_element / remove_element
.map خريطة العلاقات	update_relationship_map	add_node / update_node / move_node / remove_node / add_edge / update_edge / remove_edge / add_group / update_group / remove_group / set_meta
.geomap خريطة العالم	update_world_map	add_place / update_place / add_label / update_label / remove_element / add_river / add_border / paint_region / set_meta

لا تحفظ هذا الجدول عن ظهر قلب، ولا تعامله كمرجع نهائي: get_capabilities يعيد ما يقبله هذا الخادم فعلًا في هذه اللحظة، وهو ما تشرحه صفحة الأدلة ومهارات الكتابة.

قواعد تسري عليها جميعًا

اقرأ الملف أولًا. كل مُعرّف ترسله لا بدّ أن يأتي من تلك القراءة. لا تُعِد كتابة مُعرّف من الذاكرة، ولا تخترع واحدًا. المُعرّف المجهول يُرفَض ومعه قائمة بالمُعرّفات الحقيقية، فيكلّفك الخطأ جولةً واحدة بدل أن يكلّف المؤلف بياناته.

عملية واحدة لكل تغيير. كل عملية تأخذ وسائطها هي وحدها. الحقل الذي يخصّ عملية أخرى يُرفَض صراحةً، ولا يُتجاهَل في صمت.

op_ref يربط داخل الدفعة الواحدة فقط. ضع على ما تُنشئه العملية وسمًا مثل op_ref: "A2"، فتستطيع عملية لاحقة في الدفعة نفسها أن تشير إليه بـ "@A2". الإشارة إلى الخلف فقط، وداخل تلك الدفعة فقط؛ أما النداء التالي فيحتاج المُعرّف الحقيقي، وقد عاد إليك في applied.

الدفعة كلٌّ لا يتجزأ. إن فشلت عملية واحدة لا يُكتب شيء، فلا تضطر أبدًا إلى تخمين إلى أين وصلت. والنداء الواحد يحمل 200 عملية كحدّ أقصى، وما زاد يُرفض مع طلب تقسيمه إلى دفعات.

مثال كامل

update_relationship_map({
  "book_token": "bk_...",
  "path": "بناء العالم/خريطة العلاقات.map",
  "intent": "وضع ون يون بجانب بي جاو وإضافة علاقة زمالة بينهما",
  "operations": [
    { "op": "add_node", "label": "ون يون", "op_ref": "N1",
      "position": { "near_id": "n-peizhao", "direction": "right" } },
    { "op": "add_edge", "source_id": "n-peizhao", "target_id": "@N1", "label": "زميلان" }
  ]
})

intent ليس تعليقًا. إنه اسم الـ commit، أي السطر الذي سيقرأه المؤلف في سجل الإصدارات بعد أسابيع. اكتب ما فعلته هذه الدفعة تحديدًا؛ عبارة «تحديث مجمّع» ليست ذلك، والفقرة الطويلة تُرفَض قبل أن يُكتب أي شيء.

يحمل الردّ ثلاثة عناصر: المُعرّفات الحقيقية لما أنشأته، وما حدث تبعًا لذلك (حذف عقدة يحذف خطوطها معها)، ورمز الـ commit. العنصر الأوسط تحديدًا انقله إلى المؤلف؛ فتلك تغييرات سيراها على الشاشة ولم يطلبها.

لا توجد لوحة مراجعة هنا

داخل التطبيق، حين يعدّل مدرب AI ملفًا مهيكلًا، يظهر التعديل أولًا كبطاقة بحدود متقطّعة يقبلها المؤلف أو يتجاوزها (انظر Change Review: مراجعة تعديلات AI).

MCP لا يملك هذه الطبقة. الدفعة القادمة من أداة خارجية هي commit، وتدخل سجل الإصدارات فورًا. قل ما ستفعله قبل أن تفعله، ثم قل ما فعلته بعده، ولا ترسل التعديل ثم تسأل: «هل هذا مقبول؟» التراجع يمرّ من سجل الإصدارات، تمامًا كالتراجع عن فقرة كتبتها بنفسك. ولا شيء في سجل الإصدارات يُعلِّم الـ commit بأنه جاء من أداة خارجية: يظهر في السطر النصُّ ووقتُه وعدد الكلمات، ولا شيء غير ذلك. سطر intent الذي كتبته هو الأثر الوحيد، ولهذا بالضبط يجب أن يقول شيئًا.

إنشاء ملف مهيكل

create_file يعمل على هذه الامتدادات الخمسة، لكن المحتوى الذي ترسله يُتجاهَل: يكتب الخادم هيكلًا فارغًا، ويصير اسم الملف اسمَ المستند بداخله. والردّ يقول بوضوح إن محتواك استُبدل.

فالعملية خطوتان: create_file للحصول على ملف فارغ، ثم دفعات update_* لملئه.

من يستطيع فعل ذلك

الكتابة في هذه الأنواع الخمسة — وحذفها كذلك — تخصّ خطط الاشتراك في Slima. الحساب المجاني يتلقى 403 برمز SUBSCRIPTION_REQUIRED، والرسالة تنصّ صراحةً على أن القراءة غير مقيّدة: اقرأ الملف، وصِف التعديل الذي توصي به بالكلمات، وللمؤلف أن ينفّذه في التطبيق، أو أن يشترك فيدع الـ AI ينفّذه مباشرة.

ملاحظات تخصّ كل نوع

.map خريطة العلاقات. الموضع محتوى، لا تنسيق. update_node لا يحرّك شيئًا؛ التحريك هو move_node، حتى تكون جملة «نقلتُها إلى جانبه» تغييرًا قائمًا بذاته يمكن مراجعته. فضّل {near_id, direction} على حساب الإحداثيات بنفسك. العقد الموجودة لا تُزاح، والإحداثيات النهائية تعود إليك في الردّ. صناديق التجميع تُحسب من member_ids، فلا ترسل لها عرضًا ولا ارتفاعًا ولا إحداثيات.

.geomap خريطة العالم. الإحداثيات خلايا شبكة لا بكسلات: x من 0 إلى 519، وy من 0 إلى 363. وread_file يعيد الخريطة وقد استُبدلت شبكات التضاريس الثلاث بسطر توضيحي؛ فهي مُرمّزة للآلة ولا حاجة لك بها. paint_region يعمل بالخلايا أيضًا. التضاريس بلا تراجع، فالتصحيح يكون بالطلاء فوقها. وremove_element يقبل أي مُعرّف عنصر (pl_ للمكان، lb_ للوسم، rv_ للنهر، bd_ للحدود). لتحريك مكان استخدم update_place، لا الحذف ثم الإضافة.

.timeline الخط الزمني. ربط مُدخَل بفصل من فصول المخطوطة لا يتمّ من هنا؛ حقول الربط تُرفَض مع شرح السبب.

.beats لوحة الإيقاعات. حذف فصل لا يحذف الإيقاعات التي بداخله. تصير بلا فصل، والردّ يخبرك بعددها.

.script السيناريو. حلقة واحدة لكل ملف. عناوين المشاهد (داخلي/خارجي، المكان، الوقت) تمرّ عبر update_scene_heading، أما الحركة والشخصية والحوار والتعليق بين قوسين والانتقال ولقطة الكاميرا فتمرّ عبر add_element / update_element.

ذات صلة

• Docs: أدوات الملفات
• Docs: ما الذي يستطيعه MCP مع كل نوع ملف
• Docs: حماية الملفات المهيكلة
• Docs: ما لوحة الإيقاعات ومتى تستخدمها
• Docs: ما هو الخط الزمني (.timeline)
• Docs: ما هي خريطة العالم (.geomap)