obsidian-doc-structure

name	obsidian-doc-structure
description	用 Obsidian 官方 CLI 读取文档 outline、properties、property、tags、aliases、wordcount——比 Read 快且不把全文灌进上下文。CLI 不可用时 fallback 到 Read + Markdown/frontmatter 解析。
when_to_use	只想先看某文档的章节结构 / frontmatter 字段 / 标签 / 字数，不需要读全文时； 需求评估前快速理解已有文档结构、查文档归属、发布前做属性与完整性检查时。 边界：要查引用关系 → obsidian-link-audit；要改 frontmatter → obsidian-safe-write。
user-invocable	true
allowed-tools	["Bash","Read","Grep"]

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 命令）。

官方 CLI 命令

obsidian outline path="<file>" format=json
obsidian properties path="<file>" format=json
obsidian property:read path="<file>" name=status
obsidian tags path="<file>" format=json
obsidian aliases path="<file>" format=json
obsidian wordcount path="<file>" format=json

以本机 obsidian help <command> 的参数名为准。

Fallback

• frontmatter：读取文件开头 --- 块。
• outline：解析 Markdown 标题 ^#{1,6}\s+。
• tags：解析 frontmatter tags 和正文 #tag。
• wordcount：用本地文本粗略统计，不作为精确指标。

输出要求

• 先给出文档属性摘要：type / module / status / owner_role / updated（项目若有平台同步字段，一并列出）。
• 再给 outline 摘要。
• 对发布前检查，明确是否允许发布：draft / deprecated 默认不发布，需用户确认。
• 不修改文档。

Workframe Event

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

{
  "ts": "<ISO-8601>",
  "type": "skill_used",
  "skill": "obsidian-doc-structure",
  "role": "<role>",
  "success": true,
  "source": "<file>",
  "cli_available": true,
  "fallback_used": false
}