openclaw path
وصول إلى الصدفة يوفّره Plugin إلى طبقة العنونة oc://: مخطط مسارات واحد
موجّه حسب النوع لفحص وتحرير ملفات مساحة العمل القابلة للعنونة
(markdown، jsonc، jsonl، yaml/yml/lobster). يستخدمه المستضيفون ذاتيًا ومؤلفو
Plugin وامتدادات المحرر لقراءة موقع ضيق أو العثور عليه أو تحديثه
من دون بناء محللات مخصصة لكل ملف.
يعكس CLI الأفعال العامة للطبقة:
resolveمحدد وذو تطابق واحد.findهو فعل التطابقات المتعددة لأحرف البدل والاتحادات والمسندات والتوسيع الموضعي.setلا يقبل إلا المسارات المحددة أو علامات الإدراج؛ وتُرفض أنماط أحرف البدل قبل الكتابة.
path من خلال Plugin الاختياري المضمّن oc-path. فعّله قبل
أول استخدام:
لماذا تستخدمه
تتوزع حالة OpenClaw عبر ملفات markdown محررة يدويًا، وإعدادات JSONC المعلّقة، وسجلات JSONL الإلحاقية فقط، وملفات سير العمل/المواصفات بصيغة YAML. غالبًا ما تحتاج سكربتات الصدفة والخطافات والوكلاء إلى قيمة صغيرة واحدة من تلك الملفات: مفتاح frontmatter، أو إعداد Plugin، أو حقل سجل، أو خطوة YAML، أو عنصر تعداد نقطي تحت قسم مسمّى. يمنحopenclaw path هؤلاء المستدعين عنوانًا ثابتًا بدلًا من grep أو regex أو
محلل مخصص لكل نوع ملف. يمكن التحقق من مسار oc:// نفسه وحله والبحث فيه
وتجربته دون كتابة وكتابته من الطرفية، ما يجعل الأتمتة الضيقة أسهل في المراجعة
وأكثر أمانًا عند إعادة تشغيلها. وهو مفيد خصوصًا عندما تريد تحديث ورقة واحدة مع
الحفاظ على بقية تعليقات الملف ونهايات الأسطر والتنسيق المحيط.
استخدمه عندما يكون للشيء الذي تريده عنوان منطقي، لكن شكل الملف الفعلي يختلف:
- يريد خطاف قراءة إعداد واحد من JSONC معلّق من دون فقدان التعليقات عند كتابة القيمة مرة أخرى.
- يريد سكربت صيانة العثور على كل حقل حدث مطابق في سجل JSONL من دون تحميل السجل كله في محلل مخصص.
- يريد امتداد محرر الانتقال إلى قسم markdown أو عنصر تعداد نقطي بحسب slug، ثم عرض السطر الدقيق الذي حُل إليه.
- يريد وكيل تجربة تعديل صغير جدًا في مساحة العمل دون كتابة قبل تطبيقه، مع ظهور البايتات المتغيرة في المراجعة.
openclaw path لتعديلات الملفات الكاملة العادية، أو ترحيلات
الإعدادات الغنية، أو عمليات الكتابة الخاصة بالذاكرة. يجب أن تستخدم تلك أمر
المالك أو Plugin. path مخصص لعمليات الملفات الصغيرة القابلة للعنونة عندما
يكون أمر طرفية قابل للتكرار أوضح من محلل مخصص آخر.
كيفية استخدامه
اقرأ قيمة واحدة من ملف إعدادات محرر يدويًا:--json عندما
يحتاج المستدعي إلى مخرجات منظمة و--human عندما يفحص شخص النتيجة.
كيف يعمل
ينفذopenclaw path أربعة أشياء:
- يحلل عنوان
oc://إلى خانات: الملف، والقسم، والعنصر، والحقل، والجلسة الاختيارية. - يختار محوّل نوع الملف من امتداد الهدف (
.md، و.jsonc، و.jsonl، و.yaml، و.yml، و.lobster، والأسماء البديلة المرتبطة). - يحل الخانات مقابل AST الخاص بذلك النوع من الملفات: عناوين/عناصر markdown، أو مفاتيح كائنات/فهارس مصفوفات JSONC، أو سجلات أسطر JSONL، أو عقد الخرائط/التسلسلات في YAML.
- بالنسبة إلى
set، يصدر البايتات المعدّلة عبر المحوّل نفسه بحيث تحتفظ الأجزاء غير الملموسة من الملف بتعليقاتها ونهايات أسطرها وتنسيقها القريب حيث يدعم النوع ذلك.
resolve وset هدفًا محددًا واحدًا. أما find فهو فعل استكشافي:
يوسّع أحرف البدل والاتحادات والمسندات والترتيبيات إلى التطابقات المحددة التي
يمكنك فحصها قبل اختيار واحد للكتابة.
الأوامر الفرعية
| الأمر الفرعي | الغرض |
|---|---|
resolve <oc-path> | اطبع التطابق المحدد عند المسار (أو “غير موجود”). |
find <pattern> | عدّد التطابقات لمسار حرف بدل / اتحاد / مسند. |
set <oc-path> <value> | اكتب ورقة أو هدف إدراج عند مسار محدد. يدعم --dry-run. |
validate <oc-path> | تحليل فقط؛ اطبع التفكيك البنيوي (ملف / قسم / عنصر / حقل). |
emit <file> | مرّر ملفًا ذهابًا وإيابًا عبر parseXxx + emitXxx (تشخيص وفاء البايتات). |
الأعلام العامة
| العلم | الغرض |
|---|---|
--cwd <dir> | حل خانة الملف مقابل هذا الدليل (الافتراضي: process.cwd()). |
--file <path> | تجاوز المسار المحلول لخانة الملف (وصول مطلق). |
--json | فرض مخرجات JSON (الافتراضي عندما لا يكون stdout عبارة عن TTY). |
--human | فرض مخرجات بشرية (الافتراضي عندما يكون stdout عبارة عن TTY). |
--dry-run | (على set فقط) اطبع البايتات التي كانت ستُكتب من دون كتابة. |
--diff | (مع set --dry-run) اطبع فرقًا موحدًا بدلًا من البايتات الكاملة. |
صياغة oc://
field وجود item، ويتطلب item وجود section. عبر
الخانات الأربع كلها:
- المقاطع المقتبسة — يبقى
"a/b.c"سالمًا عبر فواصل/و.. المحتوى حرفي على مستوى البايت؛ لا يُسمح بوجود"و\داخل علامات الاقتباس. خانة الملف واعية بالاقتباس أيضًا: يعاملoc://"skills/email-drafter"/Tools/$lastskills/email-drafterكمسار ملف واحد. - المسندات —
[k=v]، و[k!=v]، و[k<v]، و[k<=v]، و[k>v]، و[k>=v]. تتطلب العمليات الرقمية أن يتحول الطرفان إلى أعداد منتهية. - الاتحادات —
{a,b,c}يطابق أيًا من البدائل. - أحرف البدل —
*(مقطع فرعي واحد) و**(صفر أو أكثر، تكراري). يقبلهاfind؛ ويرفضهاresolveوsetلأنها ملتبسة. - الموضعي — يُحل
$first/$lastإلى الفهرس الأول / الأخير أو المفتاح المعلن. - الترتيبي —
#Nللتطابق رقم N بحسب ترتيب المستند. - علامات الإدراج —
+، و+key، و+nnnللإدراج ذي المفتاح / ذي الفهرس (استخدمها معset). - نطاق الجلسة —
?session=cron-dailyوما شابه. مستقل عن تداخل الخانات. قيم الجلسة خام، وليست مفكوكة ترميز النسبة المئوية؛ ولا يجوز أن تحتوي على محارف تحكم أو فواصل استعلام محجوزة (?، و&، و%).
?، و&، و%) خارج المقاطع المقتبسة أو المسندة أو
المتحدة. تُرفض محارف التحكم (U+0000-U+001F، U+007F) في أي مكان، بما في ذلك
قيمة استعلام session.
يُضمن أن formatOcPath(parseOcPath(path)) === path للمسارات القياسية.
تُتجاهل معاملات الاستعلام غير القياسية باستثناء أول قيمة session= غير فارغة.
العنونة حسب نوع الملف
| النوع | نموذج العنونة |
|---|---|
| Markdown | أقسام H2 بحسب slug، وعناصر التعداد بحسب slug أو #N، وfrontmatter عبر [frontmatter]. |
| JSONC/JSON | مفاتيح الكائنات وفهارس المصفوفات؛ تقسم النقاط المقاطع الفرعية المتداخلة ما لم تكن مقتبسة. |
| JSONL | عناوين الأسطر العليا (L1، وL2، و$first، و$last)، ثم نزول بأسلوب JSONC داخل السطر. |
| YAML/YML/.lobster | مفاتيح الخرائط وفهارس التسلسلات؛ تُعالج التعليقات ونمط التدفق عبر API مستند YAML. |
resolve تطابقًا منظمًا: root، أو node، أو leaf، أو
insertion-point، مع رقم سطر يبدأ من 1. تُعرض قيم الأوراق كنص
إضافة إلى leafType حتى يتمكن مؤلفو Plugin من عرض المعاينات من دون الاعتماد
على شكل AST الخاص بكل نوع.
عقد التعديل
يكتبset هدفًا محددًا واحدًا:
- قيم frontmatter في Markdown وحقول العناصر
- key: valueهي أوراق نصية. تُلحق إدراجات Markdown الأقسام أو مفاتيح frontmatter أو عناصر الأقسام وتعرض شكل markdown قياسيًا للملف المتغير. - تُحوّل كتابات أوراق JSONC قيمة السلسلة إلى نوع الورقة الحالي
(
string، أوnumberمنته، أوtrue/false، أوnull). استخدم--value-jsonعندما يجب أن يحلل استبدال ورقة JSONC/JSON/JSONL<value>كـ JSON وقد يغيّر الشكل، مثل استبدال اختصار SecretRef النصي بكائن. تحلل إدراجات كائنات ومصفوفات JSONC<value>كـ JSON وتستخدم مسار تحريرjsonc-parserلكتابات الأوراق العادية، مع الحفاظ على التعليقات والتنسيق القريب. - تُحوّل كتابات أوراق JSONL مثل JSONC داخل السطر. يحلل استبدال السطر الكامل
والإلحاق
<value>كـ JSON. يحافظ JSONL المعروض على اصطلاح نهايات الأسطر السائد في الملف LF/CRLF. - تُحوّل كتابات أوراق YAML إلى نوع العدد القياسي الحالي (
string، أوnumberمنته، أوtrue/false، أوnull). تستخدم إدراجات YAML API المستند الخاص بحزمةyamlالمضمّنة لتحديثات الخرائط/التسلسلات. تُرفض مستندات YAML المشوهة ذات أخطاء المحلل قبل التعديل معparse-error.
--dry-run قبل عمليات الكتابة المرئية للمستخدم عندما تهم البايتات
الدقيقة. تحفظ الطبقة مخرجات مطابقة على مستوى البايت في عمليات parse/emit ذهابًا
وإيابًا، لكن التعديل قد يقيس منطقة التحرير أو الملف بحسب النوع.
أضف --diff عندما تريد المعاينة كرقعة قبل/بعد مركزة بدلًا من الملف المعروض
بالكامل.
أمثلة
وصفات حسب نوع الملف
تعمل الأفعال الخمسة نفسها عبر الأنواع؛ يوجّه مخطط العنونة حسب امتداد الملف. تستخدم الأمثلة أدناه التجهيزات من وصف PR.Markdown
[frontmatter] إلى كتلة واجهة YAML الأمامية؛ ويطابق tools
عنوان ## Tools عبر slug، وتحتفظ أوراق العناصر بصيغة slug الخاصة بها
حتى عندما يستخدم المصدر شرطات سفلية (send_email → send-email).
JSONC
jsonc-parser، لذلك تبقى التعليقات والمسافات البيضاء
بعد تنفيذ set. شغّل باستخدام --dry-run أولاً لفحص البايتات قبل الاعتماد.
JSONL
[event=action]) عندما لا تعرف
رقم السطر، أو باستخدام مقطع LN المعياري عندما تعرفه.
YAML
Document من حزمة yaml بدلاً من محلل مكتوب يدوياً،
لذلك تحفظ دورات التحليل/الإصدار العادية التعليقات وشكل التأليف، بينما
تستخدم المسارات المحلولة نموذج مفتاح الخريطة / فهرس التسلسل نفسه كما في
JSONC. يتعامل المحوّل نفسه مع ملفات .yaml و.yml و.lobster.
مرجع الأوامر الفرعية
resolve <oc-path>
اقرأ ورقة أو عقدة واحدة. تُرفض أحرف البدل — استخدم find لها.
يخرج بالرمز 0 عند وجود تطابق، و1 عند عدم وجود تطابق نظيف، و2 عند
خطأ تحليل أو نمط مرفوض.
find <pattern>
عدّد كل تطابق لنمط حرف بدل / محدِّد / اتحاد. يخرج بالرمز 0
عند وجود تطابق واحد على الأقل، و1 عند عدم وجود أي تطابق. تُرفض أحرف
البدل في خانة الملف مع OC_PATH_FILE_WILDCARD_UNSUPPORTED — مرّر ملفاً
محدداً (مطابقة الأنماط متعددة الملفات ميزة لاحقة).
set <oc-path> <value>
اكتب ورقة. اقرنه مع --dry-run لمعاينة البايتات التي ستُكتب دون لمس
الملف. أضف --diff لمعاينة فرق موحّد. يخرج بالرمز 0 عند نجاح الكتابة،
و1 إذا رفضت الطبقة التحتية العملية (مثلاً عند إصابة حارس sentinel)، و2
عند أخطاء التحليل.
+key الابن المسمى إذا لم يكن موجوداً بالفعل؛ وتعمل
+nnn و+ المجردة للإدراج المفهرس والإلحاق على التوالي.
validate <oc-path>
فحص تحليل فقط. لا يوجد وصول إلى نظام الملفات. مفيد عندما تريد تأكيد أن
مسار قالب حسن التكوين قبل استبدال المتغيرات، أو عندما تريد التفكيك البنيوي
للتصحيح:
0 عندما يكون صالحاً، و1 عندما يكون غير صالح (مع code و
message منظّمين)، و2 عند أخطاء الوسائط.
emit <file>
مرّر ملفاً ذهاباً وإياباً عبر المحلل والمُصدِر الخاصين بكل نوع. يجب أن
يكون الخرج مطابقاً للمدخل بالبايت في الملف السليم — يشير الاختلاف إلى خطأ
في المحلل أو إصابة sentinel. مفيد لتصحيح سلوك الطبقة التحتية على مدخلات
واقعية.
رموز الخروج
| الرمز | المعنى |
|---|---|
0 | نجاح. (resolve / find: تطابق واحد على الأقل. set: نجحت الكتابة.) |
1 | لا يوجد تطابق، أو رفضت الطبقة التحتية set (لا يوجد خطأ على مستوى النظام). |
2 | خطأ في الوسائط أو التحليل. |
وضع الخرج
يدركopenclaw path وجود TTY: خرج قابل للقراءة البشرية على الطرفية، وJSON
عندما يُمرَّر stdout عبر أنبوب أو يُعاد توجيهه. يتجاوز --json و--human
الاكتشاف التلقائي.
ملاحظات
- يكتب
setالبايتات عبر مسار الإصدار الخاص بالطبقة التحتية، الذي يطبّق حارس sentinel للتنقيح تلقائياً. تُرفض عند وقت الكتابة أي ورقة تحمل__OPENCLAW_REDACTED__(حرفياً أو كسلسلة فرعية). - يستخدم تحليل JSONC وتعديلات الأوراق اعتمادية
jsonc-parserالمحلية في Plugin، لذلك تُحفظ التعليقات والتنسيقات في كتابات الأوراق العادية بدلاً من المرور عبر مسار محلل/إعادة تصيير مكتوب يدوياً. - لا يعرف
pathعن LKG. إذا كان الملف متتبعاً بواسطة LKG، فإن استدعاء المراقبة التالي يقرر ما إذا كان سيرقّي / يستعيد. من المخطط إضافةset --batchللتعيين المتعدد الذري عبر دورة حياة ترقية/استعادة LKG إلى جانب الطبقة التحتية لاستعادة LKG.