Plugin مسیر OC

Plugin همراه oc-path، CLI openclaw path را برای طرح آدرس‌دهی فایل‌های فضای کاری oc:// اضافه می‌کند. این Plugin در مخزن OpenClaw زیر extensions/oc-path/ ارائه می‌شود، اما اختیاری است — نصب/ساخت آن را غیرفعال نگه می‌دارد تا وقتی که شما آن را فعال کنید.

آدرس‌های oc:// به یک برگ منفرد (یا مجموعه‌ای از برگ‌ها با wildcard) درون یک فایل فضای کاری اشاره می‌کنند. این Plugin امروز سه نوع فایل را می‌شناسد:

• markdown (.md, .mdx): frontmatter، بخش‌ها، آیتم‌ها، فیلدها
• jsonc (.jsonc, .json5, .json): دیدگاه‌ها و قالب‌بندی حفظ می‌شوند
• jsonl (.jsonl, .ndjson): رکوردهای خط‌محور

میزبان‌های خودگردان و افزونه‌های ویرایشگر از CLI استفاده می‌کنند تا یک برگ منفرد را بدون اسکریپت‌نویسی مستقیم در برابر SDK بخوانند یا بنویسند؛ عامل‌ها و hookها آن را به‌عنوان یک زیرلایه قطعی در نظر می‌گیرند تا round-tripهای با وفاداری بایتی و محافظ sentinel حذف‌سازی، به‌صورت یکنواخت در همه نوع‌ها اعمال شوند.

# چرا آن را فعال کنیم

وقتی می‌خواهید اسکریپت‌ها، hookها، یا ابزارهای عامل محلی به قطعه‌ای دقیق از وضعیت فضای کاری اشاره کنند، بدون اینکه برای هر شکل فایل یک parser اختراع کنید، oc-path را فعال کنید. یک آدرس oc:// می‌تواند یک کلید frontmatter در markdown، یک آیتم بخش، یک برگ پیکربندی JSONC، یا یک فیلد رویداد JSONL را نام‌گذاری کند.

این برای workflowهای نگه‌دارنده مهم است، جایی که تغییر باید کوچک، قابل حسابرسی و تکرارپذیر باشد: یک مقدار را بررسی کنید، رکوردهای مطابق را پیدا کنید، یک نوشتن را به‌صورت dry-run اجرا کنید، سپس فقط همان برگ را اعمال کنید و دیدگاه‌ها، پایان خط‌ها و قالب‌بندی نزدیک را دست‌نخورده بگذارید. نگه داشتن این قابلیت به‌عنوان یک Plugin اختیاری، زیرلایه آدرس‌دهی را به کاربران حرفه‌ای می‌دهد، بدون اینکه وابستگی‌های parser یا سطح CLI را برای نصب‌هایی که هرگز به آن نیاز ندارند وارد هسته کند.

دلایل رایج برای فعال کردن آن:

• اتوماسیون محلی: اسکریپت‌های shell می‌توانند به‌جای حمل کدهای parsing جداگانه برای markdown، JSONC و JSONL، یک مقدار فضای کاری را با openclaw path … --json resolve یا به‌روزرسانی کنند.
• ویرایش‌های قابل مشاهده برای عامل: یک عامل می‌تواند پیش از نوشتن، diff مربوط به dry-run را برای یک برگ آدرس‌دهی‌شده نشان دهد، که مرور آن از بازنویسی آزادانه فایل آسان‌تر است.
• یکپارچه‌سازی‌های ویرایشگر: یک ویرایشگر می‌تواند oc://AGENTS.md/tools/gh را بدون حدس زدن از متن heading، به node دقیق markdown و شماره خط نگاشت کند.
• عیب‌یابی: emit یک فایل را از مسیر parser و emitter عبور می‌دهد و دوباره تولید می‌کند، بنابراین می‌توانید پیش از تکیه بر ویرایش‌های خودکار، بررسی کنید آیا یک نوع فایل از نظر بایتی پایدار است یا نه.

نمونه‌های مشخص:

# 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 عمدا مالک معناشناسی سطح بالاتر نیست. Pluginهای حافظه همچنان مالک نوشتن‌های حافظه هستند، فرمان‌های پیکربندی همچنان مالک مدیریت کامل پیکربندی هستند، و منطق LKG همچنان مالک بازیابی/ارتقا است. oc-path لایه باریک عملیات آدرس‌دهی و عملیات فایل با حفظ بایت است که آن ابزارهای سطح بالاتر می‌توانند پیرامون آن ساخته شوند.

# کجا اجرا می‌شود

این Plugin درون‌پردازشی داخل CLI openclaw روی میزبانی اجرا می‌شود که فرمان را در آن فراخوانی می‌کنید. به Gateway در حال اجرا نیاز ندارد و هیچ socket شبکه‌ای باز نمی‌کند — هر فعل یک تبدیل خالص روی فایلی است که به آن اشاره می‌کنید.

فراداده 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 می‌گوید نخستین باری که openclaw path … را اجرا می‌کنید، Plugin را به‌صورت تنبل بارگذاری کند، بنابراین نصب‌هایی که هرگز از این فعل استفاده نمی‌کنند هزینه‌ای نمی‌پردازند.

# فعال‌سازی

openclaw plugins enable oc-path

Gateway را restart کنید (اگر یکی اجرا می‌کنید) تا snapshot manifest وضعیت جدید را دریافت کند. فراخوانی‌های ساده openclaw path روی همان میزبان بلافاصله کار می‌کنند — CLI این Plugin را بنا به نیاز بارگذاری می‌کند.

غیرفعال‌سازی با:

openclaw plugins disable oc-path

# وابستگی‌ها

همه وابستگی‌های parser محلیِ Plugin هستند — فعال کردن oc-path بسته‌های جدیدی را وارد runtime هسته نمی‌کند:

وابستگی	هدف
commander	سیم‌کشی subcommand برای resolve, find, set, validate, emit.
jsonc-parser	parse کردن JSONC و ویرایش برگ‌ها با حفظ دیدگاه‌ها و trailing commaها.
markdown-it	tokenization در Markdown برای مدل بخش / آیتم / فیلد.

JSONL همچنان دستی باقی می‌ماند — parsing خط‌محور از هر وابستگی ساده‌تر است، و parse کردن JSONC هر خط از قبل از مسیر jsonc-parser عبور می‌کند.

# چه چیزی ارائه می‌کند

سطح	ارائه‌شده توسط
CLI openclaw path	extensions/oc-path/cli-registration.ts
parser / formatter برای oc://	extensions/oc-path/src/oc-path/oc-path.ts
parse / emit / edit برای هر نوع	extensions/oc-path/src/oc-path/{md,jsonc,jsonl}
resolve / find / set همگانی	extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
محافظ redaction-sentinel	extensions/oc-path/src/oc-path/sentinel.ts

امروز CLI تنها سطح عمومی است. فعل‌های زیرلایه برای خود Plugin خصوصی هستند؛ مصرف‌کنندگان از CLI استفاده می‌کنند (یا Plugin خودشان را در برابر SDK می‌سازند).

# رابطه با Pluginهای دیگر

• memory-*: نوشتن‌های حافظه از مسیر Pluginهای حافظه عبور می‌کنند، نه oc-path. oc-path یک زیرلایه فایل عمومی است؛ Pluginهای حافظه معناشناسی خودشان را روی آن لایه‌بندی می‌کنند.
• LKG: path چیزی درباره بازیابی پیکربندی Last-Known-Good نمی‌داند. اگر یک فایل توسط LKG ردیابی شود، فراخوانی بعدی observe تصمیم می‌گیرد که promote شود یا recover؛ set --batch برای multi-set اتمیک از مسیر چرخه عمر promote/recover در LKG، در کنار زیرلایه بازیابی LKG برنامه‌ریزی شده است.

# ایمنی

set بایت‌های خام را از مسیر emit زیرلایه می‌نویسد، که محافظ redaction-sentinel را به‌صورت خودکار اعمال می‌کند. برگی که حامل __OPENCLAW_REDACTED__ باشد (به‌صورت عین عبارت یا به‌عنوان زیررشته) هنگام نوشتن با OC_EMIT_SENTINEL رد می‌شود. CLI همچنین sentinel لفظی را از هر خروجی انسانی یا JSON که چاپ می‌کند پاک می‌کند و آن را با [REDACTED] جایگزین می‌کند تا ضبط‌های ترمینال و pipelineها هرگز این marker را افشا نکنند.

# مرتبط

• مرجع CLI openclaw path
• مدیریت Pluginها
• ساخت Pluginها