obsidian-doc-structure

Obsidian Doc Structure

定位

本 skill 只读文档结构和属性，不写正文。它帮助 agent 在精读全文前先理解文档骨架，并检查 frontmatter / Properties 是否满足项目规范。

触发场景

• 需求评估前，先读取 outline 判断需要精读哪些章节。
• PRD / spec / plan / decision 发布前检查 type、status、updated 等属性完整性。
• 用户问“这份文档结构完整吗”“缺哪些属性”“大概多少字”。
• 项目配备的发布器（<platform>-publish）发布前读取 status 与该平台的同步状态字段。

何时不用

• 已经明确要读全文：直接 Read。
• 简单关键词搜索：直接 rg。
• 需要修改属性：调用 obsidian-safe-write。
• 需要检查坏链：调用 obsidian-link-audit。

CLI Probe

优先读取 .claude/workframe-state/obsidian-cli-status.json（schema 权威定义见下方「status.json schema」）：

• do_not_probe: true → 永不重新 probe（不设 TTL、不做过期自判），直接按 cli_available 决定走 CLI 还是 fallback；重新启用 CLI 的唯一入口 = 用户手动删除该文件后自然触发重新检测
• 缓存缺失 → 执行非执行检测（三步全程不运行任何 obsidian 命令）：
  1. 定位命令：Get-Command obsidian（Windows）/ command -v obsidian（POSIX）；不存在 → CLI 不可用
  2. GUI 启动器判定：命令所在目录存在 Obsidian.exe / resources.pak 等桌面程序特征文件 → 是 GUI 而非 CLI shim → CLI 不可用
  3. 判定不可用 → 写入 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 窗口（官方行为：If Obsidian is not running, the first command you run launches Obsidian）。

失败时 fallback 到 Read + 简单解析。

status.json schema（workframe.obsidian-cli-status.v1）

字段	类型	说明
__schema__	string	固定 workframe.obsidian-cli-status.v1
checked_at	ISO-8601	最近一次检测时间
cli_available	bool	CLI 是否可用
commands_verified	string[]	已实际验证可用的命令名
do_not_probe	bool	true = 永不重新 probe；重置方式 = 删除本文件
reason / note	string	检测依据与人读说明（可选）

其余 3 个 obsidian-* skill 引用本表，不重复定义。

调用前检查

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

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