OmeniaClaw path

وصول صدفي موفَّر من Plugin إلى طبقة العنونة oc://: مخطط مسارات واحد يفرّق حسب النوع لفحص ملفات مساحة العمل القابلة للعنونة وتحريرها (markdown، jsonc، jsonl). يستخدمه مستضيفو الذات، ومؤلفو Plugin، وإضافات المحررات لقراءة موقع ضيق أو العثور عليه أو تحديثه دون كتابة محللات خاصة بكل ملف يدويا.

يعكس CLI الأفعال العامة للطبقة:

• resolve ملموس ويطابق نتيجة واحدة.
• find هو فعل المطابقات المتعددة لأحرف البدل والاتحادات والمسندات والتوسيع الموضعي.
• set لا يقبل إلا المسارات الملموسة أو علامات الإدراج؛ وتُرفض أنماط أحرف البدل قبل الكتابة.

يوفّر Plugin الاختياري المضمّن oc-path الأمر path. فعّله قبل أول استخدام:

OmeniaClaw plugins enable oc-path

لماذا تستخدمه

تتوزع حالة OmeniaClaw عبر ملفات markdown يحررها البشر، وإعدادات JSONC المعلّقة، وسجلات JSONL للإلحاق فقط. غالبا ما تحتاج سكربتات الصدفة والخطافات والوكلاء إلى قيمة صغيرة واحدة من تلك الملفات: مفتاح frontmatter، أو إعداد Plugin، أو حقل سجل، أو عنصر تعداد نقطي تحت قسم مسمّى.

يوفر OmeniaClaw path لهؤلاء المستدعين عنوانا مستقرا بدلا من grep أو تعبير نمطي أو محلل منفرد لكل نوع ملف. يمكن التحقق من مسار oc:// نفسه، وحله، والبحث فيه، وتجربته دون كتابة، والكتابة إليه من الطرفية، مما يجعل الأتمتة الضيقة أسهل مراجعة وأكثر أمانا عند إعادة التشغيل. وهو مفيد خاصة عندما تريد تحديث ورقة واحدة مع الحفاظ على بقية تعليقات الملف ونهايات أسطره وتنسيقه المحيط.

استخدمه عندما يكون للشيء الذي تريده عنوان منطقي، لكن شكل الملف الفعلي يختلف:

• يريد خطاف قراءة إعداد واحد من JSONC معلّق دون فقدان التعليقات عند كتابة القيمة مرة أخرى.
• يريد سكربت صيانة العثور على كل حقل حدث مطابق في سجل JSONL دون تحميل السجل كله في محلل مخصص.
• تريد إضافة محرر الانتقال إلى قسم markdown أو عنصر تعداد نقطي حسب slug، ثم عرض السطر الدقيق الذي حُل إليه.
• يريد وكيل تجربة تعديل صغير لمساحة العمل دون كتابة قبل تطبيقه، مع إظهار البايتات المتغيرة في المراجعة.

غالبا لا تحتاج إلى OmeniaClaw path لتعديلات الملفات الكاملة العادية، أو ترحيلات الإعدادات الغنية، أو الكتابات الخاصة بالذاكرة. يجب أن تستخدم تلك أمر المالك أو Plugin المالك. path مخصص لعمليات الملفات الصغيرة القابلة للعنونة عندما يكون أمر طرفية قابل للتكرار أوضح من محلل مخصص آخر.

كيف يُستخدم

اقرأ قيمة واحدة من ملف إعدادات يحرره البشر:

OmeniaClaw path resolve 'oc://config.jsonc/plugins/github/enabled'

عاين كتابة دون لمس القرص:

OmeniaClaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

اعثر على سجلات مطابقة في سجل JSONL للإلحاق فقط:

OmeniaClaw path find 'oc://session.jsonl/[event=tool_call]/name'

عنون تعليمة في markdown حسب القسم والعنصر بدلا من رقم السطر:

OmeniaClaw path resolve 'oc://AGENTS.md/runtime-safety/OmeniaClaw-gateway'

تحقق من مسار في CI أو سكربت تمهيدي قبل أن يقرأ السكربت أو يكتب:

OmeniaClaw path validate 'oc://AGENTS.md/tools/$last/risk'

هذه الأوامر مصممة لتكون قابلة للنسخ إلى سكربتات الصدفة. استخدم --json عندما يحتاج المستدعي إلى خرج منظّم، و--human عندما يفحص شخص النتيجة.

كيف يعمل

ينفذ OmeniaClaw path أربعة أشياء:

1. يحلل عنوان oc:// إلى خانات: ملف، قسم، عنصر، حقل، وجلسة اختيارية.
2. يختار محوّل نوع الملف من امتداد الهدف (.md و.jsonc و.jsonl والأسماء البديلة ذات الصلة).
3. يحل الخانات مقابل AST الخاص بذلك النوع من الملفات: عناوين/عناصر markdown، أو مفاتيح كائنات/فهارس مصفوفات JSONC، أو سجلات أسطر JSONL.
4. بالنسبة إلى set، ينتج بايتات محررة عبر المحوّل نفسه بحيث تحتفظ الأجزاء غير الممسوسة من الملف بتعليقاتها ونهايات أسطرها وتنسيقها القريب حيث يدعم النوع ذلك.

يتطلب resolve وset هدفا ملموسا واحدا. find هو الفعل الاستكشافي: يوسع أحرف البدل والاتحادات والمسندات والترتيبيات إلى المطابقات الملموسة التي يمكنك فحصها قبل اختيار واحدة للكتابة.

الأوامر الفرعية

الأعلام العامة

صياغة oc://

oc://FILE/SECTION/ITEM/FIELD?session=SCOPE

قواعد الخانات: يتطلب field وجود item، ويتطلب item وجود section. عبر الخانات الأربع كلها:

• المقاطع المقتبسة — يبقى "a/b.c" سليما عبر فواصل / و.. المحتوى حرفي على مستوى البايت؛ ولا يُسمح بوجود " و\ داخل الاقتباسات. خانة الملف واعية بالاقتباس أيضا: يعامل oc://"skills/email-drafter"/Tools/$last skills/email-drafter كمسار ملف واحد.
• المسندات — [k=v] و[k!=v] و[k<v] و[k<=v] و[k>v] و [k>=v]. تتطلب العمليات الرقمية تحويل الجانبين إلى أرقام منتهية.
• الاتحادات — يطابق {a,b,c} أي بديل من البدائل.
• أحرف البدل — * (مقطع فرعي واحد) و** (صفر أو أكثر، تكراري). يقبل find هذه؛ ويرفضها resolve وset باعتبارها ملتبسة.
• الموضعي — يحل $last إلى آخر فهرس / آخر مفتاح مُصرّح به.
• الترتيبي — #N للمطابقة N حسب ترتيب المستند.
• علامات الإدراج — + و+key و+nnn للإدراج بالمفتاح / بالفهرس (تُستخدم مع set).
• نطاق الجلسة — ?session=cron-daily إلخ. مستقل عن تداخل الخانات. قيم الجلسة خام، ولا تُفك ترميزاتها المئوية؛ ولا يجوز أن تحتوي على محارف تحكم أو فواصل استعلام محجوزة (? و& و%).

تُرفض المحارف المحجوزة (? و& و%) خارج المقاطع المقتبسة أو المسندات أو الاتحادات. تُرفض محارف التحكم (U+0000-U+001F وU+007F) في أي مكان، بما في ذلك قيمة استعلام session.

يُضمن أن formatOcPath(parseOcPath(path)) === path للمسارات القياسية. تُتجاهل معاملات الاستعلام غير القياسية باستثناء أول قيمة session= غير فارغة.

العنونة حسب نوع الملف

يرجع resolve مطابقة منظّمة: root أو node أو leaf أو insertion-point، مع رقم سطر يبدأ من 1. تظهر قيم الأوراق كنص مع leafType بحيث يستطيع مؤلفو Plugin عرض المعاينات دون الاعتماد على شكل AST الخاص بكل نوع.

عقد التعديل

يكتب set هدفا ملموسا واحدا:

• قيم frontmatter في Markdown وحقول عناصر - key: value هي أوراق نصية. تضيف إدراجات Markdown أقساما أو مفاتيح frontmatter أو عناصر أقسام وتعرض شكلا قياسيا من markdown للملف المتغير.
• تحوّل كتابات أوراق JSONC القيمة النصية إلى نوع الورقة الحالي (string أو number منته أو true/false أو null). تحلل إدراجات كائنات ومصفوفات JSONC <value> كـ JSON وتستخدم مسار تحرير jsonc-parser لكتابات الأوراق العادية، مع الحفاظ على التعليقات والتنسيق القريب.
• تحوّل كتابات أوراق JSONL مثل JSONC داخل السطر. يستبدل السطر بالكامل والإلحاق يحللان <value> كـ JSON. يحافظ JSONL المعروض على نمط نهايات الأسطر الغالب في الملف LF/CRLF.

استخدم --dry-run قبل الكتابات المرئية للمستخدم عندما تكون البايتات الدقيقة مهمة. تحافظ الطبقة على خرج مطابق بالبايتات لجولات التحليل/الإصدار، لكن التعديل قد يقيّس المنطقة أو الملف المحرر حسب النوع.

أمثلة

# Validate a path (no filesystem access)OmeniaClaw path validate 'oc://AGENTS.md/Tools/$last/risk' # Read a leafOmeniaClaw path resolve 'oc://gateway.jsonc/version' # Wildcard searchOmeniaClaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl # Dry-run a writeOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run # Apply the writeOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' # Byte-fidelity round-trip (diagnostic)OmeniaClaw path emit ./AGENTS.md

مزيد من أمثلة القواعد:

# Quote keys containing / or .OmeniaClaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias' # Predicate search over JSONC childrenOmeniaClaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Insert into a JSONC arrayOmeniaClaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Insert a JSONC object keyOmeniaClaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Append a JSONL eventOmeniaClaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Resolve the last JSONL value lineOmeniaClaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Address markdown frontmatterOmeniaClaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Insert markdown frontmatterOmeniaClaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Find markdown item fieldsOmeniaClaw path find 'oc://SKILL.md/Tools/*/send_email' # Validate a session-scoped pathOmeniaClaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

وصفات حسب نوع الملف

تعمل الأفعال الخمسة نفسها عبر الأنواع؛ يوجّه مخطط العنونة التنفيذ حسب امتداد الملف. تستخدم الأمثلة أدناه التجهيزات من وصف PR.

Markdown

<!-- frontmatter.md -->---name: drafterdescription: email drafting agenttier: core---## Tools- gh: GitHub CLI- curl: HTTP client- send_email: enabled

$ OmeniaClaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --humanleaf @ L4: "core" (string) $ OmeniaClaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --humanleaf @ L9: "GitHub CLI" (string) $ OmeniaClaw path find 'oc://x.md/tools/*' --file frontmatter.md --human3 matches for oc://x.md/tools/*:  oc://x.md/tools/gh           →  node @ L9 [md-item]  oc://x.md/tools/curl         →  node @ L10 [md-item]  oc://x.md/tools/send-email   →  node @ L11 [md-item]

يعنون المسند [frontmatter] كتلة YAML frontmatter؛ ويطابق tools عنوان ## Tools عبر slug، وتحتفظ أوراق العناصر بشكل slug الخاص بها حتى عندما يستخدم المصدر شرطات سفلية (send_email → send-email).

JSONC

// config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": false, "role": "chat"}  }}

$ OmeniaClaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --humanleaf @ L4: "true" (boolean) $ OmeniaClaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run--dry-run: would write 142 bytes to /…/config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": true, "role": "chat"}  }}

تمر تعديلات JSONC عبر jsonc-parser، لذلك تبقى التعليقات والمسافات البيضاء بعد set. شغّل باستخدام --dry-run أولًا لفحص البايتات قبل الإيداع.

JSONL

{"event":"start","userId":"u1","ts":1}{"event":"action","userId":"u1","ts":2}{"event":"end","userId":"u1","ts":3}

$ OmeniaClaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human1 match for oc://session.jsonl/[event=action]/userId:  oc://session.jsonl/L2/userId  →  leaf @ L2: "u1" (string) $ OmeniaClaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --humanleaf @ L2: "2" (number)

كل سطر هو سجل. عالجه باستخدام المسند ([event=action]) عندما لا تعرف رقم السطر، أو باستخدام مقطع LN القانوني عندما تعرفه.

مرجع الأمر الفرعي

resolve <oc-path>

اقرأ ورقة أو عقدة واحدة. تُرفض أحرف البدل — استخدم find لها. يخرج بالقيمة 0 عند وجود تطابق، و1 عند عدم وجود نتيجة بشكل سليم، و2 عند حدوث خطأ تحليل أو نمط مرفوض.

OmeniaClaw path resolve 'oc://AGENTS.md/tools/gh/risk' --humanOmeniaClaw path resolve 'oc://gateway.jsonc/server/port' --json

find <pattern>

يسرد كل تطابق لنمط يحتوي على حرف بدل / مسند / اتحاد. يخرج بالقيمة 0 عند وجود تطابق واحد على الأقل، و1 عند عدم وجود أي تطابق. تُرفض أحرف البدل في موضع الملف مع OC_PATH_FILE_WILDCARD_UNSUPPORTED — مرّر ملفًا محددًا (الدعم المتعدد للملفات عبر المطابقة النمطية ميزة لاحقة).

OmeniaClaw path find 'oc://AGENTS.md/tools/**/risk'OmeniaClaw path find 'oc://session.jsonl/[event=action]/userId'OmeniaClaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'

set <oc-path> <value>

اكتب ورقة. استخدمه مع --dry-run لمعاينة البايتات التي كانت ستُكتب دون لمس الملف. يخرج بالقيمة 0 عند نجاح الكتابة، و1 إذا رفضت الطبقة التحتية العملية (مثلًا، عند تفعيل حارس sentinel)، و2 عند أخطاء التحليل.

OmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' --dry-runOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0'OmeniaClaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'

تنشئ علامة الإدراج +key الابن المسمى إذا لم يكن موجودًا بالفعل؛ ويعمل +nnn و+ المجرّد للإدراج المفهرس وإدراج الإلحاق على التوالي.

validate <oc-path>

فحص تحليل فقط. لا يوجد وصول إلى نظام الملفات. مفيد عندما تريد تأكيد أن مسار قالب ما مُشكّل جيدًا قبل استبدال المتغيرات، أو عندما تريد التفصيل البنيوي لأغراض التصحيح:

$ OmeniaClaw path validate 'oc://AGENTS.md/tools/gh' --humanvalid: oc://AGENTS.md/tools/gh  file:    AGENTS.md  section: tools  item:    gh

يخرج بالقيمة 0 عندما يكون صالحًا، و1 عندما يكون غير صالح (مع code و message منظّمين)، و2 عند أخطاء الوسيطات.

emit <file>

يمرّر ملفًا ذهابًا وإيابًا عبر محلل ومُصدِر كل نوع. يجب أن يكون الخرج مطابقًا للمدخل على مستوى البايت في الملف السليم — يشير الاختلاف إلى خلل في المحلل أو تفعيل sentinel. مفيد لتصحيح سلوك الطبقة التحتية على مدخلات واقعية.

OmeniaClaw path emit ./AGENTS.mdOmeniaClaw path emit ./gateway.jsonc --json

رموز الخروج

وضع الإخراج

OmeniaClaw path واعٍ بوجود TTY: إخراج قابل للقراءة البشرية على الطرفية، وJSON عندما يُمرّر stdout عبر أنبوب أو يُعاد توجيهه. يتجاوز --json و--human الاكتشاف التلقائي.

ملاحظات

• يكتب set البايتات عبر مسار emit الخاص بالطبقة التحتية، والذي يطبق حارس sentinel الخاص بالتنقيح تلقائيًا. تُرفض أي ورقة تحمل __OmeniaClaw_REDACTED__ (حرفيًا أو كسلسلة فرعية) وقت الكتابة.
• يستخدم تحليل JSONC وتعديلات الأوراق تبعية jsonc-parser المحلية للـ Plugin، لذلك تُحفظ التعليقات والتنسيقات في عمليات كتابة الأوراق العادية بدل المرور عبر مسار محلل/إعادة تصيير مكتوب يدويًا.
• لا يعرف path عن LKG. إذا كان الملف متعقبًا بواسطة LKG، فإن نداء observe التالي يقرر ما إذا كان سيرقّي / يستعيد. من المخطط إضافة set --batch للإعدادات المتعددة الذرية عبر دورة حياة ترقية/استعادة LKG إلى جانب طبقة LKG-recovery التحتية.

ذات صلة

• مرجع CLI