Plugin مسار OC

تضيف إضافة oc-path المضمّنة واجهة CLI المسماة openclaw path لمخطط عنونة ملفات مساحة العمل oc://. تُشحن ضمن مستودع OpenClaw تحت extensions/oc-path/، لكنها اختيارية: يتركها التثبيت/البناء غير نشطة حتى تفعّلها. تشير عناوين oc:// إلى ورقة طرفية واحدة (أو مجموعة أوراق طرفية مطابقة لحرف بدل) داخل ملف مساحة عمل. تفهم الإضافة أربعة أنواع من الملفات:

markdown (.md): البيانات الوصفية الأمامية، والأقسام، والعناصر، والحقول
jsonc (.jsonc، .json): مع الحفاظ على التعليقات والتنسيق
jsonl (.jsonl، .ndjson): سجلات موجّهة حسب الأسطر
yaml (.yaml، .yml، .lobster): عُقد الخرائط/التسلسلات/القيم القياسية عبر واجهة Document الخاصة بحزمة yaml

يستخدم المستضيفون ذاتيًا وامتدادات المحررات واجهة CLI لقراءة ورقة طرفية واحدة أو كتابتها دون البرمجة مباشرةً مقابل SDK؛ وتتعامل معها الوكلاء والخطافات باعتبارها طبقة أساسية حتمية، بحيث تُطبَّق بصورة موحّدة ضمانات الرحلات ذهابًا وإيابًا المطابقة للبايتات وحماية العلامة الحارسة للتنقيح عبر جميع الأنواع. راجع مرجع CLI للاطلاع على القواعد النحوية الكاملة، وقائمة الخيارات لكل فعل، وأمثلة تطبيقية لكل نوع ملف؛ وتشرح هذه الصفحة سبب تفعيل الإضافة وكيفيته.

لماذا ينبغي تفعيلها

فعّل oc-path عندما تحتاج البرامج النصية أو الخطافات أو أدوات الوكيل المحلية إلى الإشارة إلى جزء دقيق من حالة مساحة العمل دون محلّل مخصص لكل بنية ملف. يمكن لعنوان oc:// واحد تسمية مفتاح في البيانات الوصفية الأمامية لملف Markdown، أو عنصر في قسم، أو ورقة طرفية لإعداد JSONC، أو حقل حدث JSONL، أو خطوة في سير عمل YAML. يهم ذلك في مهام سير عمل المشرفين التي ينبغي أن يظل فيها التغيير صغيرًا وقابلًا للتدقيق والتكرار: افحص قيمة واحدة، واعثر على السجلات المطابقة، ونفّذ محاكاة للكتابة، ثم طبّق التغيير على تلك الورقة الطرفية فقط مع ترك التعليقات ونهايات الأسطر والتنسيق المجاور دون تغيير. أسباب شائعة لتفعيلها:

الأتمتة المحلية: تحل البرامج النصية للقشرة قيمة واحدة في مساحة العمل أو تحدّثها باستخدام openclaw path … --json بدلًا من تضمين شيفرات منفصلة لتحليل Markdown وJSONC وJSONL وYAML.
تعديلات مرئية للوكيل: يعرض الوكيل فرق محاكاة لورقة طرفية معنونة واحدة قبل الكتابة، ما يجعل مراجعته أسهل من إعادة كتابة الملف بصيغة حرة.
تكاملات المحررات: يربط المحرر oc://AGENTS.md/tools/gh بعقدة Markdown ورقم السطر الدقيقين دون التخمين من نص العنوان.
التشخيصات: يُجري emit رحلة ذهاب وإياب للملف عبر المحلّل والمُصدِر، ما يتيح لك التحقق مما إذا كان نوع الملف مستقرًا على مستوى البايتات قبل الاعتماد على التعديلات المؤتمتة.

# هل إضافة GitHub مفعّلة في هذا الإعداد؟
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# ما أسماء استدعاءات الأدوات التي تظهر في سجل الجلسة هذا؟
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# ما البايتات التي سيكتبها هذا التعديل الصغير على الإعداد؟
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

لا يُقصد من oc-path امتلاك الدلالات ذات المستوى الأعلى. تظل إضافات الذاكرة مالكة لعمليات كتابة الذاكرة، وتظل أوامر الإعداد مالكة للإدارة الكاملة للإعداد، ويظل استرداد إعداد آخر حالة سليمة معروفة (LKG) مالكًا للاستعادة/الترقية. تمثّل oc-path طبقة عنونة ضيقة وعمليات ملفات محافظة على البايتات يمكن لتلك الأدوات ذات المستوى الأعلى البناء حولها.

أين تعمل

تعمل الإضافة داخل العملية ضمن واجهة CLI المسماة openclaw على المضيف الذي تستدعي الأمر منه. ولا تحتاج إلى Gateway قيد التشغيل، ولا تفتح أي مقابس شبكة؛ فكل فعل عبارة عن تحويل محض يُطبَّق على ملف تشير إليه. توجد البيانات الوصفية للإضافة في extensions/oc-path/openclaw.plugin.json:

{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}

تُبقي onStartup: false الإضافة خارج مسار بدء تشغيل Gateway. وتوجّه commandAliases وactivation.onCommands واجهة CLI إلى تحميل الإضافة تحميلًا كسولًا عند تشغيل openclaw path … للمرة الأولى، وبذلك لا تتحمل عمليات التثبيت التي لا تستخدم هذا الفعل أي تكلفة.

التفعيل

openclaw plugins enable oc-path

أعد تشغيل Gateway (إن كنت تشغّل واحدًا) حتى تلتقط لقطة البيان الحالة الجديدة. تعمل استدعاءات openclaw path المجردة فورًا على المضيف نفسه؛ إذ تحمّل واجهة CLI الإضافة عند الطلب. عطّلها باستخدام:

openclaw plugins disable oc-path

التبعيات

جميع تبعيات المحلّل محلية للإضافة؛ ولا يؤدي تفعيل oc-path إلى إدخال حزم جديدة إلى بيئة التشغيل الأساسية:

التبعية	الغرض
`commander`	توصيل الأوامر الفرعية `resolve` و`find` و`set` و`validate` و`emit`.
`jsonc-parser`	تحليل JSONC وتعديل الأوراق الطرفية مع الاحتفاظ بالتعليقات والفواصل الختامية.
`markdown-it`	تقسيم Markdown إلى رموز لنموذج القسم / العنصر / الحقل.
`yaml`	تحليل / إصدار / تعديل `Document` في YAML مع الاحتفاظ بالتعليقات ونمط التدفق.

يظل JSONL منفّذًا يدويًا: فالتحليل الموجّه حسب الأسطر أبسط من استخدام أي تبعية، كما أن تحليل كل سطر يمر أصلًا عبر jsonc-parser.

ما الذي توفره

السطح	يوفَّر بواسطة
واجهة CLI المسماة `openclaw path`	`extensions/oc-path/cli-registration.ts`
محلّل / منسّق `oc://`	`extensions/oc-path/src/oc-path/oc-path.ts`
التحليل / الإصدار / التعديل لكل نوع	`extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}`
الحل / البحث / الضبط الشامل	`extensions/oc-path/src/oc-path/{resolve,find,edit}.ts`
حماية العلامة الحارسة للتنقيح	`extensions/oc-path/src/oc-path/sentinel.ts`

واجهة CLI هي السطح العام الوحيد حاليًا. أفعال الطبقة الأساسية خاصة بالإضافة؛ ويستخدم المستهلكون واجهة CLI (أو يبنون إضافتهم الخاصة مقابل SDK).

العلاقة بالإضافات الأخرى

memory-*: تمر عمليات كتابة الذاكرة عبر إضافات الذاكرة، لا عبر oc-path. تمثّل oc-path طبقة ملفات أساسية عامة؛ وتضيف إضافات الذاكرة دلالاتها الخاصة فوقها.
LKG: لا يعرف path شيئًا عن استعادة إعداد آخر حالة سليمة معروفة. إذا كان الملف الذي تعدّله عبر path خاضعًا أيضًا لتتبّع LKG، فستقرر دورة مراقبة الإعداد التالية ما إذا كانت ستُرقّيه أو تسترده؛ تعامل مع تعديل path بالطريقة نفسها التي تتعامل بها مع أي كتابة مباشرة أخرى إلى ذلك الملف.

السلامة

يكتب set البايتات الخام عبر مسار الإصدار في الطبقة الأساسية، والذي يطبّق تلقائيًا حماية العلامة الحارسة للتنقيح. تُرفض عند وقت الكتابة، مع الخطأ OC_EMIT_SENTINEL، أي ورقة طرفية تحمل __OPENCLAW_REDACTED__ (حرفيًا أو كسلسلة فرعية). كما تزيل واجهة CLI العلامة الحارسة الحرفية من أي مخرجات بشرية أو بصيغة JSON تطبعها، وتستبدلها بـ[REDACTED] حتى لا تسرّب لقطات الطرفية وخطوط الأنابيب العلامة أبدًا.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Plugin مسار OC

لماذا ينبغي تفعيلها

أين تعمل

التفعيل

التبعيات

ما الذي توفره

العلاقة بالإضافات الأخرى

السلامة

ذو صلة

​لماذا ينبغي تفعيلها

​أين تعمل

​التفعيل

​التبعيات

​ما الذي توفره

​العلاقة بالإضافات الأخرى

​السلامة

​ذو صلة

لماذا ينبغي تفعيلها

أين تعمل

التفعيل

التبعيات

ما الذي توفره

العلاقة بالإضافات الأخرى

السلامة

ذو صلة