obsidian-link-audit

Obsidian Link Audit

定位

本 skill 是 Obsidian CLI 增强层，只做链接语义审计，不写文件。

主链路仍是本地 Markdown + rg / Read。当 Obsidian CLI 可用时，用官方 CLI 获取 Obsidian 视角下的 backlinks、outgoing links、unresolved、orphans、deadends；CLI 不可用时回退到 rg 近似查询。

触发场景

• 修改正式 spec / plan / decision 前后，需要确认影响面。
• 发布到外部平台前检查坏链（由项目配备的 <platform>-publish 发布器调用）。
• 单文件 rename / move 前后检查引用是否更新。
• 用户问“哪些文档引用了它”“有没有坏链”“有没有孤岛文档”。

何时不用

• 只读单篇正文：直接 Read。
• 简单关键词全文检索：直接 rg 更快。
• 写正文、改 frontmatter：不用本 skill，交给业务 skill / obsidian-safe-write。
• 外部平台发布：本 skill 不负责发布，只做发布前校验。

CLI Probe

优先读取 .claude/workframe-state/obsidian-cli-status.json（schema 权威定义见 skill: obsidian-doc-structure §status.json schema）：

• do_not_probe: true → 永不重新 probe（不设 TTL、不做过期自判），直接按 cli_available 决定走 CLI 还是 fallback；重新启用 CLI 的唯一入口 = 用户手动删除该文件
• 缓存缺失 → 执行非执行检测（全程不运行任何 obsidian 命令）：定位命令（Get-Command obsidian / command -v obsidian）→ 判定是否 GUI 启动器（所在目录存在 Obsidian.exe / resources.pak 特征文件）→ 不可用则写入 status.json（cli_available: false、do_not_probe: true、reason）并 fallback
• 仅当非执行检测确认存在独立 CLI shim 时，才允许执行 obsidian version / obsidian vault info=path 验证并写入 commands_verified

⚠️ 未通过非执行检测时禁止执行任何 obsidian 命令——在「装了 GUI 但未启用 CLI」的机器上会误启动 Obsidian 窗口。

若不可用，记录 fallback 原因并改用 rg / Read。

调用前检查

执行任一 Obsidian CLI 命令前，必须依序确认：

• status.json 存在且 do_not_probe: true 且 cli_available: false → 直接 fallback，不做任何 probe。
• 命令在 commands_verified 数组中 → 可以使用 CLI。
• 命令不在数组中 → 直接 fallback，不尝试执行。
• status.json 不存在或 schema 不匹配 → 按「CLI Probe」的非执行检测流程重新检测（禁止直接执行 obsidian 命令）。

官方 CLI 命令

以本机 obsidian help <command> 输出为准，常用命令：

obsidian backlinks path="<file>" format=json
obsidian links path="<file>" format=json
obsidian unresolved verbose format=json
obsidian orphans format=json
obsidian deadends format=json

若本机参数名是 file= 而不是 path=，按 obsidian help backlinks / obsidian help links 调整。

Fallback

rg '\[\[[^\]]*<目标文件名>[^\]]*\]\]' projects docs
rg '\[\[' "<当前文件>"
rg "\]\([^)]*\.md\)" projects docs