obsidian-link-audit

name	obsidian-link-audit
description	用 Obsidian 官方 CLI 做链接、反链、坏链与孤岛文档审计——改文档前查谁引用了它，改完后确认没留下断链。CLI 不可用时 fallback 到 rg/Read。
when_to_use	正式文档修改前后、单文件 rename/move 前后、发布到外部平台前； 用户问「谁引用了这个文档 / 有没有断链 / 哪些是孤岛文档」时； 删改概念后要确认无落空引用时（document-norms §8.1 Step 3 的 L2 反链查漏）。
user-invocable	true
allowed-tools	["Bash","Read","Grep","Glob"]

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

孤岛文档可用 rg --files -g "*.md" projects docs 列出候选，再与 overview / wikilink 引用结果对照。

输出要求

• 先列出 CLI 是否可用和使用的命令。
• 区分 backlinks、outgoing links、unresolved、orphans/deadends。
• 发现坏链时给出文件路径和建议修复方向。
• 不自动修复；需要修复时交给用户确认或调用相应写入 skill。

Workframe Event

使用后按 agent-protocols.md 记录 skill_used 事件，至少包含：

{
  "ts": "<ISO-8601>",
  "type": "skill_used",
  "skill": "obsidian-link-audit",
  "role": "<role>",
  "success": true,
  "source": "<file or scope>",
  "cli_available": true,
  "fallback_used": false
}