الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

يوفّر Plugin oc-path المضمّن CLI openclaw path لمخطط عنونة ملفات مساحة العمل oc://. يُشحن ضمن مستودع OpenClaw تحت extensions/oc-path/ لكنه اختياري التفعيل؛ إذ يظل خاملاً بعد التثبيت/البناء إلى أن تفعّله. تشير عناوين oc:// إلى ورقة واحدة (أو مجموعة أوراق بعلامة بدل) داخل ملف مساحة عمل. يفهم الـPlugin اليوم ثلاثة أنواع من الملفات:
  • markdown (.md, .mdx): بيانات المقدمة، الأقسام، العناصر، الحقول
  • jsonc (.jsonc, .json5, .json): تُحفَظ التعليقات والتنسيق
  • jsonl (.jsonl, .ndjson): سجلات موجّهة بالأسطر
يستخدم المستضيفون ذاتياً وإضافات المحررات الـCLI لقراءة ورقة واحدة أو كتابتها من دون البرمجة مباشرةً مقابل الـSDK؛ وتتعامل الوكلاء والخطافات معه كطبقة حتمية بحيث تنطبق جولات الذهاب والإياب المطابقة على مستوى البايت وحارس مؤشر التنقيح بشكل موحّد عبر الأنواع.

​
لماذا تفعّله

فعّل oc-path عندما تريد من السكربتات أو الخطافات أو أدوات الوكيل المحلية أن تشير إلى جزء دقيق من حالة مساحة العمل من دون اختراع محلّل لكل شكل ملف. يمكن لعنوان oc:// واحد أن يسمّي مفتاح بيانات مقدمة في Markdown، أو عنصر قسم، أو ورقة إعداد JSONC، أو حقل حدث JSONL. هذا مهم في سير عمل الصيانة حيث يجب أن يكون التغيير صغيراً، وقابلاً للتدقيق، وقابلاً للتكرار: افحص قيمة واحدة، وابحث عن السجلات المطابقة، وشغّل كتابة تجريبية، ثم طبّق تلك الورقة فقط مع ترك التعليقات ونهايات الأسطر والتنسيق القريب كما هو. إبقاء هذا كـPlugin اختياري يمنح المستخدمين المتقدمين طبقة العنونة من دون إدخال تبعيات المحللات أو سطح CLI إلى النواة لعمليات التثبيت التي لا تحتاجها أبداً. أسباب شائعة لتفعيله:
  • الأتمتة المحلية: يمكن لسكربتات الصدفة حل قيمة واحدة في مساحة العمل أو تحديثها باستخدام openclaw path … --json بدلاً من حمل شيفرة تحليل منفصلة لـMarkdown وJSONC وJSONL.
  • تعديلات مرئية للوكيل: يمكن للوكيل عرض فرق تشغيل تجريبي لورقة معنونة واحدة قبل الكتابة، ما يجعل مراجعته أسهل من إعادة كتابة ملف حرّة الشكل.
  • تكاملات المحررات: يمكن للمحرر ربط oc://AGENTS.md/tools/gh بعقدة Markdown الدقيقة ورقم السطر من دون التخمين من نص العنوان.
  • التشخيصات: يمرّر emit ملفاً ذهاباً وإياباً عبر المحلل والمُخرِج، بحيث يمكنك التحقق مما إذا كان نوع ملف معيّن مستقراً على مستوى البايت قبل الاعتماد على التعديلات الآلية.
أمثلة ملموسة: 
# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
ليس المقصود من الـPlugin أن يكون مالك الدلالات الأعلى مستوى. ما تزال Plugins الذاكرة تملك كتابات الذاكرة، وما تزال أوامر الإعداد تملك إدارة الإعداد الكاملة، وما يزال منطق LKG يملك الاستعادة/الترقية. oc-path هو طبقة العنونة الضيقة وعمليات الملفات الحافظة للبايت التي تستطيع تلك الأدوات الأعلى مستوى البناء حولها.

​
أين يعمل

يعمل الـPlugin داخل عملية CLI openclaw على المضيف الذي تستدعي عليه الأمر. لا يحتاج إلى Gateway قيد التشغيل ولا يفتح أي مقابس شبكة؛ فكل فعل هو تحويل صرف على ملف تشير إليه. توجد بيانات تعريف الـPlugin في extensions/oc-path/openclaw.plugin.json: 
{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}
يبقي onStartup: false الـPlugin خارج المسار الساخن للـGateway. يخبر onCommands: ["path"] الـCLI بأن يحمّل الـPlugin بكسل عند أول مرة تشغّل فيها openclaw path …، بحيث لا تدفع عمليات التثبيت التي لا تستخدم الفعل أبداً أي تكلفة.

​
التفعيل

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

​
التبعيات

كل تبعيات المحللات محلية للـPlugin؛ فتفعيل oc-path لا يسحب حزماً جديدة إلى وقت تشغيل النواة:
التبعيةالغرض
commanderتوصيل الأوامر الفرعية لـresolve وfind وset وvalidate وemit.
jsonc-parserتحليل JSONC + تعديلات الأوراق مع إبقاء التعليقات والفواصل اللاحقة.
markdown-itتقسيم Markdown إلى رموز لنموذج القسم / العنصر / الحقل.
يبقى JSONL منفذاً يدوياً؛ فالتحليل الموجّه بالأسطر أبسط من أي تبعية، كما أن تحليل JSONC لكل سطر يمر أصلاً عبر jsonc-parser.

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

السطحيوفّره
CLI openclaw pathextensions/oc-path/cli-registration.ts
محلل / منسّق oc://extensions/oc-path/src/oc-path/oc-path.ts
التحليل / الإخراج / التحرير لكل نوعextensions/oc-path/src/oc-path/{md,jsonc,jsonl}
الحل / البحث / الضبط العامextensions/oc-path/src/oc-path/{resolve,find,edit}.ts
حارس مؤشر التنقيحextensions/oc-path/src/oc-path/sentinel.ts
الـCLI هو السطح العام الوحيد اليوم. أفعال الطبقة خاصة بالـPlugin؛ يستخدم المستهلكون الـCLI (أو يبنون Plugin خاصاً بهم مقابل الـSDK).

​
العلاقة مع Plugins الأخرى

  • memory-*: تمر كتابات الذاكرة عبر Plugins الذاكرة، وليس عبر oc-path. oc-path طبقة ملفات عامة؛ وتضع Plugins الذاكرة دلالاتها الخاصة فوقها.
  • LKG: لا يعرف path شيئاً عن استعادة إعداد Last-Known-Good. إذا كان ملف ما متتبعاً عبر LKG، فإن استدعاء observe التالي يقرر ما إذا كان سيرقّي أو يستعيد؛ أما set --batch للضبط المتعدد الذري عبر دورة حياة ترقية/استرداد LKG فمخطط له إلى جانب طبقة استرداد LKG.

​
السلامة

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

​
ذو صلة