> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin مسار OC

يضيف Plugin `oc-path` المضمّن [`openclaw path`](/ar/cli/path) CLI من أجل
مخطط عنونة ملفات مساحة العمل `oc://`. يُشحن ضمن مستودع OpenClaw تحت
`extensions/oc-path/` لكنه اختياري — يتركه التثبيت/البناء خاملاً إلى أن
تفعّله.

تشير عناوين `oc://` إلى ورقة واحدة (أو مجموعة أوراق بحرف بدل) داخل
ملف مساحة عمل. يفهم Plugin حالياً أربعة أنواع من الملفات:

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

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

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

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

هذا مهم لتدفقات عمل الصيانة حيث يجب أن يكون التغيير صغيراً وقابلاً للتدقيق
وقابلاً للتكرار: افحص قيمة واحدة، وابحث عن السجلات المطابقة، ونفّذ تجربة
كتابة جافة، ثم طبّق تلك الورقة فقط مع ترك التعليقات ونهايات الأسطر والتنسيق
القريب كما هي. إبقاء هذا كـ Plugin اختياري يمنح المستخدمين المتقدمين طبقة
العنونة الأساسية من دون إدخال اعتماديات المحللات أو سطح CLI إلى النواة
للتثبيتات التي لا تحتاجه أبداً.

أسباب شائعة لتفعيله:

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

أمثلة ملموسة:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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 **داخل العملية ضمن `openclaw` CLI** على المضيف الذي تستدعي منه
الأمر. لا يحتاج إلى Gateway قيد التشغيل ولا يفتح أي مقابس شبكة — كل فعل هو
تحويل صرف فوق ملف تشير إليه.

توجد بيانات Plugin الوصفية في `extensions/oc-path/openclaw.plugin.json`:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 …`، لذلك لا تدفع التثبيتات التي لا تستخدم الفعل أي تكلفة.

## التفعيل

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins enable oc-path
```

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

عطّله باستخدام:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins disable oc-path
```

## الاعتماديات

كل اعتماديات المحللات محلية داخل Plugin — لا يسحب تفعيل `oc-path` حزماً
جديدة إلى وقت تشغيل النواة:

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

يبقى JSONL مطبّقاً يدوياً — التحليل الموجّه بالأسطر أبسط من أي اعتمادية،
وتحليل JSONC لكل سطر يمر أصلاً عبر `jsonc-parser`.

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

| السطح                         | موفّر من                                                |
| ----------------------------- | ------------------------------------------------------- |
| `openclaw path` CLI           | `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 هو السطح العام الوحيد اليوم. أفعال طبقة الأساس خاصة بـ 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]` لكي
لا تسرّب لقطات الطرفية والأنابيب العلامة أبداً.

## ذو صلة

* [مرجع `openclaw path` CLI](/ar/cli/path)
* [إدارة Plugins](/ar/plugins/manage-plugins)
* [بناء Plugins](/ar/plugins/building-plugins)