@@ -173,6 +173,164 @@ openclaw path find 'oc://SKILL.md/Tools/*/send_email'
173173openclaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'
174174```
175175176+## Recipes by file kind
177+178+The same five verbs work across kinds; the addressing scheme dispatches on the
179+file extension. The examples below use the fixtures from the PR description.
180+181+### Markdown
182+183+```text
184+<!-- frontmatter.md -->
185+---
186+name: drafter
187+description: email drafting agent
188+tier: core
189+---
190+## Tools
191+- gh: GitHub CLI
192+- curl: HTTP client
193+- send_email: enabled
194+```
195+196+```bash
197+$ openclaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --human
198+leaf @ L4: "core" (string)
199+200+$ openclaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --human
201+leaf @ L9: "GitHub CLI" (string)
202+203+$ openclaw path find 'oc://x.md/tools/*' --file frontmatter.md --human
204+3 matches for oc://x.md/tools/*:
205+ oc://x.md/tools/gh → node @ L9 [md-item]
206+ oc://x.md/tools/curl → node @ L10 [md-item]
207+ oc://x.md/tools/send-email → node @ L11 [md-item]
208+```
209+210+The `[frontmatter]` predicate addresses the YAML frontmatter block; `tools`
211+matches the `## Tools` heading via slug, and item leaves keep their slug form
212+even when the source uses underscores (`send_email` → `send-email`).
213+214+### JSONC
215+216+```text
217+// config.jsonc
218+{
219+ "plugins": {
220+ "github": {"enabled": true, "role": "vcs"},
221+ "slack": {"enabled": false, "role": "chat"}
222+ }
223+}
224+```
225+226+```bash
227+$ openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --human
228+leaf @ L4: "true" (boolean)
229+230+$ openclaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run
231+--dry-run: would write 142 bytes to /…/config.jsonc
232+{
233+"plugins": {
234+"github": {"enabled": true, "role": "vcs"},
235+"slack": {"enabled": true, "role": "chat"}
236+ }
237+}
238+```
239+240+JSONC edits go through `jsonc-parser`, so comments and whitespace survive a
241+`set`. Run with `--dry-run` first to inspect the bytes before committing.
242+243+### JSONL
244+245+```text
246+{"event":"start","userId":"u1","ts":1}
247+{"event":"action","userId":"u1","ts":2}
248+{"event":"end","userId":"u1","ts":3}
249+```
250+251+```bash
252+$ openclaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human
253+1 match for oc://session.jsonl/[event=action]/userId:
254+ oc://session.jsonl/L2/userId → leaf @ L2: "u1" (string)
255+256+$ openclaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --human
257+leaf @ L2: "2" (number)
258+```
259+260+Each line is a record. Address by predicate (`[event=action]`) when you do not
261+know the line number, or by the canonical `LN` segment when you do.
262+263+## Subcommand reference
264+265+### `resolve <oc-path>`
266+267+Read a single leaf or node. Wildcards are rejected — use `find` for those.
268+Exits `0` on a match, `1` on a clean miss, `2` on a parse error or refused
269+pattern.
270+271+```bash
272+openclaw path resolve 'oc://AGENTS.md/tools/gh/risk' --human
273+openclaw path resolve 'oc://gateway.jsonc/server/port' --json
274+```
275+276+### `find <pattern>`
277+278+Enumerate every match for a wildcard / predicate / union pattern. Exits `0`
279+on at least one match, `1` on zero. File-slot wildcards are rejected with
280+`OC_PATH_FILE_WILDCARD_UNSUPPORTED` — pass a concrete file (multi-file
281+globbing is a follow-up feature).
282+283+```bash
284+openclaw path find 'oc://AGENTS.md/tools/**/risk'
285+openclaw path find 'oc://session.jsonl/[event=action]/userId'
286+openclaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'
287+```
288+289+### `set <oc-path> <value>`
290+291+Write a leaf. Pair with `--dry-run` to preview the bytes that would be
292+written without touching the file. Exits `0` on a successful write, `1` if
293+the substrate refuses (for example, a sentinel guard hit), `2` on parse
294+errors.
295+296+```bash
297+openclaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run
298+openclaw path set 'oc://gateway.jsonc/version' '2.0'
299+openclaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'
300+```
301+302+The `+key` insertion marker creates the named child if it does not already
303+exist; `+nnn` and bare `+` work for indexed and append insertion respectively.
304+305+### `validate <oc-path>`
306+307+Parse-only check. No filesystem access. Useful when you want to confirm a
308+template path is well-formed before substituting variables, or when you want
309+the structural breakdown for debugging:
310+311+```bash
312+$ openclaw path validate 'oc://AGENTS.md/tools/gh' --human
313+valid: oc://AGENTS.md/tools/gh
314+ file: AGENTS.md
315+ section: tools
316+ item: gh
317+```
318+319+Exits `0` when valid, `1` when invalid (with a structured `code` and
320+`message`), `2` on argument errors.
321+322+### `emit <file>`
323+324+Round-trip a file through the per-kind parser and emitter. The output should
325+be byte-identical to the input on a sound file — divergence indicates a
326+parser bug or a sentinel hit. Useful for debugging substrate behavior on
327+real-world inputs.
328+329+```bash
330+openclaw path emit ./AGENTS.md
331+openclaw path emit ./gateway.jsonc --json
332+```
333+176334## Exit codes
177335178336| Code | Meaning |
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。