أدوات الملفات

في سطر واحد: مرجع أدوات الملفات التي تعمل على مسار — القراءة، والتعديل في الموضع، والاستبدال الكامل، والإنشاء، والحذف، والإضافة في النهاية، والبحث.

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

هذه هي المجموعة التي تلمس المسوّدة فعلًا. وما يجمعها أن كل واحدة منها تأخذ path، وأن كل عملية كتابة تنتج commit. لا توجد خطوة حفظ، والمؤلف يرى commits التي أنشأتها بجوار commits التي أنشأها هو في سجل الإصدارات.

الأداة	ما تفعله	الوسائط
read_file	قراءة ملف واحد	book_token، path
edit_file	إيجاد مقطع واستبداله	path، old_string، new_string، replace_all?، commit_message?
write_file	استبدال الملف كله	path، content، commit_message?
create_file	إنشاء ملف جديد	path، content?، content_type?، commit_message?
delete_file	حذف ملف أو مجلد	path، recursive?، commit_message?
append_to_file	الإضافة إلى نهاية ملف	path، content، commit_message?
search_content	البحث النصي الكامل	query، file_types?، limit?، include_structured?

أما رؤية خريطة العلاقات فأداة أخرى — انظر دعِ الـ AI يرى خريطة العلاقات.

للمراجعات، امدد يدك إلى edit_file

هي الأكثر استخدامًا في المجموعة، والكتابة الوحيدة التي تفشل بصوت مسموع بدل أن تطمس، حين يكون المؤلف يحرّر الملف نفسه.

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

replace_all قيمته الافتراضية false، فيستبدل أول تطابق وحده. ومرِّر new_string فارغًا لحذف المقطع.

write_file يستبدل كل شيء

مناسبٌ لإعادة كتابة شاملة حقيقية. وهو يأخذ معه أيضًا ما كتبه المؤلف قبل دقيقة، فاختر edit_file كلّما كان edit_file كافيًا.

create_file: الوسيط content_type يحدّد إن كانت الكلمات تُحتسب

تكتب فصلًا؟ مرِّر content_type: "manuscript". بدونه يورث الملف الجديد نوع المجلد الحاوي، وفي الجذر يكون reference افتراضيًا — وتلك الكلمات لا تصل إلى عدد كلمات المؤلف ولا سلسلته ولا تصدير المخطوطة. والقيم المتاحة: manuscript وreference وcharacter وlocation وstoryline.

المجلدات غير الموجودة في المسار تُنشأ لك، فلا توجد خطوة إنشاء مجلد منفصلة. انظر المخطوطة مقابل المرجع.

delete_file: المجلد غير الفارغ يجب أن يُقال بصوت عالٍ

حذف مجلد ما زال فيه أشياء مرفوضٌ افتراضيًا، والرسالة تخبرك بعدد ما بداخله. مرِّر recursive: true حين تعني الشجرة كلها فعلًا.

هذه الحماية موجودة بسبب حادث حقيقي: أزِل صفّ المجلد وحده فتفقد محتوياته أباها، فيعرض التطبيق الشجرة كلها في المستوى الأعلى من الكتاب. المؤلف يرى ملفاته مبعثرة، والخادم قد أجاب بالنجاح.

والحذف commit أيضًا، فالملف باقٍ في سجل الإصدارات ويمكن استعادته من هناك — انظر استعد الكتاب الكامل أو ملفًا واحدًا.

search_content: هذه الوسائط، ولا وجود لـ scope

search_content({
  "book_token": "bk_...",
  "query": "فرن الحروف",
  "file_types": ["md"],
  "limit": 20
})

file_types يقبل الامتدادات بنقطة أو بغيرها (["md", ".txt"]).

في كتب 4.0، وسيط file_types أهمّ مما يبدو. الـ JSON الخام للملفات المهيكلة يُبحث هو الآخر، فكلمة شائعة مثل name أو title قد تعود بصفحة من أسماء الحقول. اكتب file_types: ["md"] حين تريد النثر. وكتب استوديو السيناريو القديمة تعمل بالعكس: الملفات المهيكلة فيها مستثناة افتراضيًا، وinclude_structured: true يعيدها. انظر أدوات تسلك سلوكًا مختلفًا مع ملفات بعينها.

ما لا تستطيع هذه المجموعة لمسه

• النثر (.md / .markdown / .txt) — المجموعة كلها تعمل.
• الأنواع المهيكلة الخمسة (.map / .beats / .timeline / .script / .geomap) — write_file وedit_file وappend_to_file مرفوضة، والرفض يسمّي أداة update_* التي تستخدمها بدلًا منها. واستثناءان يجب تذكّرهما: create_file يعمل فعلًا، لكن المحتوى الذي ترسله يُتجاهَل (يكتب الخادم هيكلًا فارغًا)، وdelete_file يعمل هو الآخر (الحذف لا يفحص سياسة النوع، بل الخطة فقط). والكتابة والحذف كلاهما يخصّ خطط الاشتراك.
• .character / .location / .json / .yaml — غير قابلة للكتابة إطلاقًا، وبلا مسار حقلي كذلك.

ولتغيير ملف مهيكل، امضِ من أدوات التحرير المهيكل. والقائمة المرجعية دائمًا هي الجدول الذي يعيده get_capabilities.

commit_message يستحقّ أن تملأه

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

ذات صلة

• Docs: أدوات التحرير المهيكل
• Docs: دعِ الـ AI يرى خريطة العلاقات
• Docs: ما الذي يستطيعه MCP مع كل نوع ملف
• Docs: رفض الكتابة: ما العمل
• Docs: قواعد النسخ التلقائي