| name | obs-auto-moc |
| description | 建立 review-first 的 Obsidian MOC manifest、proposal 與 preview。預設不改 live MOC,只有明確要求時才 apply。 |
Obs Auto MOC Skill
當使用者要檢查、重建、預覽或套用 Obsidian MOC.md 時,使用這個 skill。
固定路徑
- project root:
/home/haman/custom-claw-tools/obs-auto-moc
- repo skill copy:
/home/haman/custom-claw-tools/obs-auto-moc/SKILL.md
- live skill path:
/home/haman/.picoclaw/workspace/skills/obs-auto-moc/SKILL.md
- live wrapper path:
/home/haman/.picoclaw/workspace/bin/obs-auto-moc
- artifacts root:
/home/haman/.picoclaw/workspace/notes/claw/moc
- proposal root:
/home/haman/.picoclaw/workspace/notes/claw/moc/proposals
- manifest path:
/home/haman/.picoclaw/workspace/notes/claw/moc/index-manifest.jsonl
- preview path:
/home/haman/.picoclaw/workspace/notes/claw/moc/MOC.preview.md
- status path:
/home/haman/.picoclaw/workspace/notes/claw/moc/last-run.json
- live MOC path:
/home/haman/.picoclaw/workspace/notes/MOC.md
- sync config root:
/home/haman/.config/obsidian-headless/sync
何時使用這個 skill
當任務符合以下情況時,使用 obs-auto-moc:
- 想先 review 再決定是否更新
MOC.md
- 想檢查哪些筆記是 orphan、哪些 frontmatter 不完整
- 想看新的
MOC.preview.md
- 想在 PicoClaw 內安全觸發 MOC 重建
- 想在不直接覆寫 live MOC 的前提下產出 proposal artifact
不要用在這些情況
- 不要在未經使用者明確確認前直接套用
--apply
- 不要假裝 frontmatter 永遠完整或格式正確
- 不要在 proposal mode 寫入大量筆記
- 不要繞過 sync config 去硬編碼不可信的 vault path
角色分工
PicoClaw
- 判斷使用者是要 preview、stats,還是 explicit apply
- 透過
exec 呼叫 live wrapper
- 讀回 proposal、preview 或 stats
- 誠實回報 malformed notes、缺欄位與 unresolved links
obs-auto-moc
- 從 sync config 解出 vault path
- 只處理
root-note、TechVault、WorkVault、PersonalVault
- 掃描 Markdown、Frontmatter 與 wikilinks
- 產出 manifest、proposal 與 preview
- 只有在
--apply 時才原子更新 live MOC.md
- 支援 metadata-only
Decayed 狀態;agent search / read / 引用可喚醒筆記並重算 last_resonated_at
必要流程
-
預設先跑 preview build
- 使用:
/home/haman/.picoclaw/workspace/bin/obs-auto-moc build
- 這一步會更新 manifest、proposal 與
MOC.preview.md
- 這一步不會改寫 live
MOC.md
-
先讀結果
- 讀
last-run.json
- 讀最新 proposal
- 必要時讀
MOC.preview.md
-
只有在使用者明確要求「套用」時,才執行:
/home/haman/.picoclaw/workspace/bin/obs-auto-moc build --apply
-
回覆要精簡
- 說明這次是否只是 preview
- 列出 proposal / preview 路徑
- 列出最重要的 warning
- 若有 apply,明確說 live
MOC.md 已更新
root-note pipeline scaffold
目前 repo 內已加入第一版 script-side scaffold,對應 root-note -> PicoClaw -> destination MOC 流程:
monitor-root-note:掃描 root-note/,只對變更檔案產出 PicoClaw handoff artifact
apply-picoclaw-report --report <file>:吃結構化 PicoClaw 完成回報,更新 pipeline state,並刷新 touched destination MOC
queue-picoclaw-report --report <file> [--run-pipeline]:驗證回報後先放入 report inbox,必要時立刻跑一輪 pipeline
record-agent-reference --note-path <path>...:記錄 agent reference batch,解除 Decayed,重算 last_resonated_at,並重建 touched note set 的 related
refresh-destination-mocs:直接重建 TechVault / WorkVault / PersonalVault 的 MOC.md
dispatch-picoclaw-handoff --handoff <file>:把 handoff job 直接交給 live PicoClaw,擷取結構化 report,再餵回 pipeline
run-pipeline-once:先吃 report inbox 裡的 PicoClaw 完成回報,再從 root-note/ 產出下一個 handoff job;若 auto-dispatch 開啟,會立刻把 handoff 送進 live PicoClaw
- 若 queued PicoClaw report 是壞的或無法套用,
run-pipeline-once 會把它隔離到 pipeline/picoclaw-report-failures/,並讓受影響的 root-note 項目回到可重試狀態
- 若 live PicoClaw auto-dispatch 自己回了壞 output 或沒回合法 report block,
run-pipeline-once 也只會把受影響項目標成可重試,不會再整條卡死在 handed_off_to_picoclaw
- 若 live PicoClaw 只回部分 entries,缺的 handoff 項目會自動補成
failed 後重試,不會再殘留成假性的 handed_off_to_picoclaw
- 若 live PicoClaw 回了 stale job / 假的 processed output(目的筆記根本沒落地),dispatcher 會直接走本機 fallback,把 source root-note 複製到選定的 destination vault 後再回灌有效 report
listen --host 127.0.0.1 --port 45460 --run-pipeline:提供 loopback GET /health、POST /picoclaw-report 與 POST /agent-reference callback ingestion
- handoff artifact 的
callback_contract.endpoint 預設會指向 http://127.0.0.1:45460/picoclaw-report
- handoff artifact 會附上
vault_path 與 destination root paths,讓 PicoClaw 在回報前先建立目的筆記
注意:
- Stage 2 agent 由 live PicoClaw 執行,不是在
obs-auto-moc 內執行
- Stage 2 規則入口已對齊到 pi3 notes 內的
ObsToolsVault/README.md,更細的遷移規則在 ObsToolsVault/specs/
- pi3 上的建議部署是
obs-auto-moc-listener.service + obs-auto-moc-pipeline.path + obs-auto-moc-pipeline.timer
bin/obs-auto-moc-runner 預設會開 OBS_AUTO_MOC_AUTO_DISPATCH=1,並使用 cron:obs-auto-moc:<job_id> 這種 job-scoped session 自動把 handoff 送進 PicoClaw,避免沿用舊對話上下文
bin/obs-auto-moc-listen / bin/obs-auto-moc-runner 支援 OBS_AUTO_MOC_SYNC_ROOT、OBS_AUTO_MOC_VAULT_PATH、OBS_AUTO_MOC_AUTO_DISPATCH、OBS_AUTO_MOC_PICOCLAW_SESSION、OBS_AUTO_MOC_STALE_HANDOFF_SECONDS 等環境覆寫;其中 OBS_AUTO_MOC_PICOCLAW_SESSION 會被當成 session prefix,dispatcher 會自動附上 :<job_id>,也可自行放 {job_id} placeholder
常用指令
Preview build
/home/haman/.picoclaw/workspace/bin/obs-auto-moc build
Stats
/home/haman/.picoclaw/workspace/bin/obs-auto-moc stats
Apply
/home/haman/.picoclaw/workspace/bin/obs-auto-moc build --apply
Guardrails
- 預設是 review-first,不是 auto-apply。
- 若
last-run.json 顯示 parse errors、missing schema fields 或 unresolved links,要誠實說明。
- 若 sync config 缺失或有多份 config,直接回報錯誤,不要猜路徑。
- 除了
notes/MOC.md 的 explicit apply 之外,不要改寫 vault 內其他筆記。
notes/claw/moc 是 artifact root;preview/proposal 都先寫這裡。