需要审计 Obsidian 知识库摄入状态、增量…

当用户询问 wiki 状态、已摄入/待处理内容、增量、图谱洞察或维护是否收敛时，读取 manifest 与源目录并生成报告。

适用场景

解决思路

1. 开始前写作配置：在起草或重写自然语言 Markdown 前，读取并应用 `llm-wiki/SKILL.md` 中的 `Writing Profile Resolution` 部分。
2. 写作优先级：框架 schema、provenance、safety 和 operation-specific 要求优先；`WRITING.md` 偏好只应用到生成的 `_insights.md` 散文，分析器快照逐字保留。
3. 解析 config：按 `llm-wiki/SKILL.md` 的 Config Resolution Protocol 执行：inline `@name` override → 从 CWD 向上查找 `.env` → global config → prompt setup，得到 `OBSIDIAN_VAULT_PATH`、`OBSIDIAN_SOURCES_DIR`、`CLAUDE_HISTORY_PATH`、`CODEX_HISTORY_PATH`。
4. 读取 `$OBSIDIAN_VAULT_PATH/.manifest.json`，它是摄入跟踪账本；不存在则表示 fresh vault，尚未摄入任何内容。
5. Manifest 的 source key 必须可移植，绝不用裸绝对路径：vault 内源用 vault 相对路径（如 `Raw/database/x.pdf`），`$HOME` 下源用 `~` 相对路径（如 `~/.claude/projects/.../abc.jsonl`），无便携路径源用 pseudo-key（`repo:`/`url:`/`agent:`）；不要混用形式，否则同一文件会被跟踪两次并重复摄入。
6. 若 manifest 使用 legacy absolute-key，用 `scripts/manifest.py migrate <vault>` 转换。
7. Manifest 结构包含 `version`、`last_updated`、`sources`、`projects`、`stats`；`sources` 条目含 `ingested_at`、`size_bytes`、`modified_at`、`source_type`、`project`、`pages_created`、`pages_updated`；`projects` 含 `source_repo`、`source_cwd_hint`、`vault_path`、`last_ingested`、`conversations_ingested`、`conversations_total`、`memory_files_ingested`；`stats` 含 `total_sources_ingested`、`total_pages`、`total_projects`、`last_full_rebuild`。
8. Step 1 扫描 Documents：对 `OBSIDIAN_SOURCES_DIR` 中每个目录 Glob 所有文本文件，记录 path、size、modification time。
9. Step 1 扫描 Claude History：Glob `~/.claude/projects/*/` 得到项目目录，Glob `~/.claude/projects/*/*.jsonl` 得到会话文件，Glob `~/.claude/projects/*/memory/*.md` 得到 memory 文件，记录 path、size、modification time、parent project。
10. Step 1 扫描 Codex History：Glob `~/.codex/session_index.jsonl`、`~/.codex/sessions/**/rollout-*.jsonl`、`~/.codex/history.jsonl`、`~/.codex/archived_sessions/**/rollout-*.jsonl`（仅当用户要 archive coverage），记录 path、size、modification time，并尽可能从 cwd 推断 project。
11. Step 1 扫描用户之前指向的其他源：检查 manifest 中标准目录之外的 source paths。
12. Step 2 计算 Delta：将当前源与 manifest 对比，分类为 New、Modified、Touched、Unchanged、Deleted、Unavailable。
13. Delta 分类含义：New = 磁盘存在但不在 manifest，需要摄入；Modified = 在 manifest 且 hash 与 `content_hash` 不同，需要重新摄入；Touched = 在 manifest 且 mtime 更新但 hash 未变，跳过；Unchanged = mtime 和 hash 均匹配，无需操作；Deleted = vault 本地源在 manifest 中但磁盘不存在，记录，wiki 页面可能 stale；Unavailable = 机器本地源（home-relative 或 absolute key）在本机不存在，如另一主机同步条目，跳过，不报告为 deleted 或清理。
14. 当 manifest 条目没有 `content_hash`（旧条目）时，退化为只比较 mtime。
15. Claude history 额外计算：`~/.claude/projects/` 中不在 manifest 的新项目、已有项目中的新会话、更新的 memory 文件。
16. Codex history 额外计算：`sessions/**` 下新 rollout 文件、`session_index.jsonl` 条目更新（session title/freshness 变化）、仅在请求 archive coverage 时计算 archived rollout delta。
17. Step 3 渲染报告前做 visibility tally：grep 所有 vault `.md` 页面 frontmatter 中的 `visibility/internal` 和 `visibility/pii` tag 值；计数 `public` = 有 `visibility/public` tag 或完全无 `visibility/` tag，`internal` = 有 `visibility/internal` tag，`pii` = 有 `visibility/pii` tag；在 Overview 中写 `Page visibility: N public · M internal · K pii`；若所有页面未标记则跳过该行。
18. Step 3 展示 Wiki Status 的 Overview：Total wiki pages、Page visibility、Total sources ingested、Projects tracked、Last ingest、Staged writes pending（仅当 `WIKI_STAGED_WRITES=true` 时，写 N pages · M patches 和最旧年龄）。
19. Step 3 展示 Delta：New sources 表（Source/Type/Size）、Modified sources 表（Source/Last ingested/Last modified/Delta）、New projects（项目名、会话数、memory 文件数）、Deleted sources 数。
20. Step 3 展示 Summary：Ready to ingest = new + modified，Up to date = unchanged，Recommendation = Append 或 Rebuild（例如 delta 相对总量较小则 Append），以及 Token Footprint 表。
21. Token Footprint 表行：core tier、supporting tier、peripheral tier、Full wiki (all)，各含 Pages 和 ~Tokens；另列 Index-only pass（frontmatter + summaries）和 Typical query（index + 5 full pages）。
22. Step 3b 计算 Token Footprint 第 1 步：Glob 所有 `.md` 页面，读取每个页面 `tier:` frontmatter 字段（cheap grep），按 `core`、`supporting`、`peripheral` 分组；未设置 → `supporting`。
23. Step 3b 第 2 步：估算每个页面 token 数 = `file_size_bytes / 4`（4 chars/token heuristic，无需 tokenizer），按 tier 汇总并求总计。
24. Step 3b 第 3 步：估算 Index-only pass：对每页 frontmatter 求和 `len(title) + len(summary) + len(tags)`（平均约 100 chars），再除以 4。
25. Step 3b 第 4 步：估算 Typical query = Index-only 估算 + 5 个页面的平均完整读取成本（`total_chars / total_pages * 5 / 4`）。
26. Step 3b 第 5 步：阈值检查：读取 config 中 `WIKI_TOKEN_WARN_THRESHOLD`（默认 `100000`）；若为 `0` 跳过警告；若 full-wiki token 估算超过阈值，输出 `⚠️` 警告及三条 remediation：降级 peripheral 页面（使用 wiki-status insights mode 的 tier 建议）、运行 `/wiki-lint --consolidate` 合并近重复、大多数查询使用 wiki-query fast mode。
27. Step 3b 第 6 步：每次标准 status run（normal 和 insights 模式）都包含 Token Footprint；在表下加脚注说明方法论 `4 chars/token heuristic`。
28. Step 4 用排序的 `What to Do Next` 替换旧单行 Recommendation；先在 4a 收集信号。
29. 4a 信号 0：Staged writes pending（仅当 `WIKI_STAGED_WRITES=true`）：Glob `$OBSIDIAN_VAULT_PATH/_staging/**/*.md` 和 `**/*.patch.md`，分别计数 new pages 和 patches，报告最旧文件年龄（mtime）；若有 staged 文件，永远列第一，因为意图信号最高（LLM 已完成工作，人类只需 review）。
30. 4a 信号 1：`_raw/` 文件：列出 `$OBSIDIAN_VAULT_PATH/_raw/` 顶层所有非 `.gitkeep` 文件，排除 `_archived/` 子目录（已提升草稿保留为 provenance，不是待办），计数并命名。
31. 4a 信号 2：stale core pages：扫描所有 vault `.md`；页面 `updated` frontmatter 早于今天 90 天以上，且≥5 个 incoming wikilinks（即 core，被其他页面依赖），列为 stale；按名称+最后更新日期列出。
32. 4a 信号 3：orphan pages：零 incoming wikilinks 的页面。Glob 所有 `.md`，提取所有 `[[wikilink]]`，统计每个页面的引用数，收集 `incoming == 0`；显示最多 5 个名称并报告总数。
33. 4a 信号 4：synthesis opportunities：检查 `hot.md` 中最近的 `/wiki-synthesize` run summary；若上次 synthesis 报告 N 个 opportunities，展示该计数；若最近 14 天内 `hot.md` 或 `log.md` 没有 synthesis，标记 `synthesis scan overdue`。
34. 4a 信号 5：source delta：从 Step 2 获取 new + modified sources 的计数。
35. 4a 信号 6：lint issues：检查 `log.md` 中最近 30 天内的 `/wiki-lint` run；若记录了 broken links 或 missing frontmatter，展示计数；若日志中没有 lint run，标记 `lint not run recently`。
36. 4b 排序并渲染：给每个类别打分，输出 ranked list，最多 6 项；按优先级：0 Staged writes pending、1 `_raw/` files waiting、2 Stale core pages、3 Orphan pages、4 Synthesis opportunities、5 New/modified sources、6 Lint issues；某类别 count 为 0 或无可报告则跳过。
37. 4b 渲染格式：每项包含编号、图标、描述和 `run:` 命令，例如 `0. 📋 6 staged pages waiting for review (oldest: 3 days ago) → 4 new pages + 2 patches in _staging/ run: /wiki-stage-commit`；`1. 📥 Ingest 3 files waiting in _raw/ ... run: /wiki-ingest`；`2. 🔄 Refresh 2 stale core pages ... run: open these pages and re-run /wiki-update`；`3. 🔗 Link 7 orphan pages → run: /cross-linker`；`4. 🧩 2 synthesis opportunities identified → run: /wiki-synthesize`；`5. ✅ 4 sources modified since last ingest → run: /wiki-ingest (append mode)`；`6. 🩺 Lint not run in 30+ days — run: /wiki-lint`。
38. 4b 空状态：若所有类别都无可报告，输出 `## What to Do Next` 和 `✅ Wiki is healthy — nothing urgent. All sources up to date · no orphans · no stale core pages · no _raw/ files pending · no staged writes`。
39. 4b 溢出：若超过 6 项，添加 footer `_(N more items available — run /wiki-status --full to see all)_`；`--full` 尚未实现，这是前瞻性文案。
40. Insights Mode 触发：用户问 `wiki insights`、`what's central`、`show me the hubs`、`cross-domain bridges`、`what pages are most important`、`wiki structure` 等时触发；该模式附加而非替换 delta report，分析 wiki 自身形状，告诉用户已构建内容和有趣结构；它补充 `wiki-lint`（找问题）通过展示有趣结构。
41. Insights Mode 首先运行 graph analyser，替代手工 wikilink parsing，一条命令产出所有原始数据：`obsidian-wiki graph-analyse $OBSIDIAN_VAULT_PATH --pretty --snapshot --diff-against $OBSIDIAN_VAULT_PATH/_insights.md`（若无 previous `_insights.md` 则省略 `--diff-against`）。
42. Graph analyser 使用与 graphify 对代码图同族的纯 Python 算法：degree ranking、community detection（安装 `obsidian-wiki[graph]` 时用 Leiden，否则 label propagation）、community cohesion、Brandes betweenness centrality、cross-community surprise scoring、snapshot diffing；排除 vault bookkeeping 文件（`index`、`log`、`hot`、`_insights`、`_meta/`、`_readouts/`），避免它们主导排名。
43. Graph analyser 输出字段：`god_nodes`（按 total degree 排名的页面，含 in_degree/out_degree，用于 anchor pages 和 hub 分类）；`bridges`（按 betweenness centrality 排名，含 community 和 connects，直接用于 Bridge Pages）；`communities`（按链接密度聚类，含 label、size、pages、cohesion，用于 cluster labelling 和 cohesion section）；`surprising_connections`（跨社区边按 unexpectedness 排名，每个社区对一条后再重复，含 note）；`suggested_questions`（由 bridges、sink hubs、isolates、low-cohesion clusters 派生的 {type, question, why}）；`dead_ends`（零 outgoing links 页面）；`isolated`（双向零链接页面）；`stats`（total pages、edges、communities、graph density）；`diff`（仅 `--diff-against` 时，含 added_pages、removed_pages、added_edges、removed_edges、newly_connected、lost_incoming、summary）；`snapshot`（仅 `--snapshot` 时，逐字写入 `_insights.md` 末尾的 `<!-- GRAPH_SNAPSHOT: ... -->` 注释）。
44. Graph analyser 查询模式：`--path A B` 返回两页间最短链接链；`--around PAGE --depth N --direction in|out|both` 返回 N-hop neighbourhood（`--direction in` = 若 PAGE 被重命名或删除时的 blast radius）。
45. Graph analyser fallback：若 `obsidian-wiki` 未安装，Glob 所有 `.md`，提取所有 `[[wikilink]]`，手工构建 incoming、outgoing、tags maps，再手工近似下文各 section。
46. Insights 1 Anchor pages（top hubs）：按 `incoming` 计数排名所有页面，取 top 10；对每页记录 incoming 和 outgoing 计数；高 incoming 且高 outgoing 是 connector hubs（最有价值）；高 incoming 但零 outgoing 是 sink hubs，标记为 cross-linker 候选。
47. Insights 2 Bridge pages：取 `bridges` 前 5（已按 betweenness centrality 排名）；用 community labels 标注为 `P bridges [label of community] ↔ [labels of connects]`；若 `connects` 为空，这是 intra-cluster chokepoint，记为 `internal hub of [label]`；展示 betweenness 分数，使多次运行可比较。
48. Insights 3 Cluster cohesion：从 `communities[].cohesion` 读取每个社区内部链接紧密程度（`actual_links / (n × (n−1) / 2)`）；Fragmented clusters（cohesion < 0.15，size ≥ 5）是共享主题但未编织在一起，作为 cross-linker targets；展示 top 5 最强社区和 bottom 5 最碎片化社区，含 label 和 size；可选对每个 tag（pages ≥ 5）重复同一公式。
49. Insights 4 Surprising connections：从 `surprising_connections` 开始（结构分 = `1/√(cross-degree(A)·cross-degree(B))`；每个社区对一条边后才重复，避免单个 hub 填满列表）；用分析器看不到的内容信号重排：+3 若 linking page 或 claim 标记 `^[ambiguous]`（不确定连接，值得 review），+2 若 linking page 标记 `^[inferred]`（合成而非直接陈述），+2 若 categories 位于不同 knowledge layers（如 `concepts` ↔ `entities` 比 `concepts` ↔ `concepts` 更 surprising）；展示 top 5，每项给 plain-language reason（使用 `note`，如 `bridges [label A] → [label B]`，加上内容加分）。
50. Insights 5 Orphan-adjacent suggestions：被 top-10 hub 链接但自身零 outgoing links 的页面，即高流量区域的 dead-ends，是 prime cross-linker candidates。
51. Insights 6 Rough clusters：按 dominant tag 分组 anchor pages（简单 tag intersection，仅用于 orientation）。
52. Insights 7 Graph delta since last run：从 `diff` 字段读取（由 `--diff-against` 读取上一个 `_insights.md` 的 `<!-- GRAPH_SNAPSHOT: ... -->` 注释产生）；`summary` → `+N pages, +M wikilinks`，列出 `added_pages` / `removed_pages`；`newly_connected` → `newly connected: X, Y`；`lost_incoming` → `link target may have been renamed: A, B`；若无 previous snapshot（无 `diff` 字段）跳过本节。
53. Insights 8 Tier assignment suggestions：计算 hubs 和 bridges 后建议 `tier:` 变更；绝不把 `tier:` 写入页面，只呈现建议供人类决定；Promote to `core`：≥5 incoming links 或 top-5 bridge 位置，且当前 `tier: supporting` 或无 `tier:`；Demote to `peripheral`：≤1 incoming link 且 90+ 天未更新，且当前 `tier: supporting` 或 `tier: core`；显示最多 10 个建议（promotions 先，demotions 后），格式如 `↑ core [[concepts/attention-mechanism]] — 14 incoming links, currently tier=supporting`、`↑ core [[entities/andrej-karpathy]] — bridge (3 cluster pairs), currently unset`、`↓ peripheral [[concepts/old-concept]] — 0 incoming, 120 days stale`；若所有高链接页面已是 core 且低链接页面已是 peripheral，输出 `Tier assignments look healthy — no changes suggested.`
54. Insights 9 Suggested questions：从 `^[ambiguous]` claims（内容扫描，分析器看不到）生成 `Resolve: What is the exact relationship between X and Y?`；从 `suggested_questions` 生成：`bridge_node` → `Explore: …`，`sink_hub` → `Link: …`，`isolated_nodes` → `Link: …`，`low_cohesion` → `Audit: …`，并改写成对应前缀形式；显示最多 7 个，优先 AMBIGUOUS，然后 bridge nodes，然后 sink hubs / isolates，然后 cohesion audits。
55. Insights Output：把结果写入 vault 根 `_insights.md`；可自由覆盖，因为可再生；在最后把 analyser 的 `snapshot` 字段逐字嵌入为 HTML 注释，供下次用 `--diff-against` diff；模板包括 Anchor Pages、Bridge Pages、Tag Cluster Cohesion、Surprising Connections、Orphan-Adjacent、Rough Clusters、Graph Delta Since Last Run、Tier Suggestions、Questions Worth Asking。
56. Insights 写完后 append 到 `log.md`：`- [TIMESTAMP] STATUS_INSIGHTS anchors=10 bridges=N cohesion_checked=T surprising=5 questions=7 delta=+N pages +M links tier_suggestions=N`。
57. Insights 跳过条件：vault 少于 20 页，图结构不足，告诉用户并跳过；fresh `wiki-rebuild` 后，等到至少一次 ingest 后再运行。
58. Equilibrium Mode 触发：用户问 `is my vault at equilibrium`、`wiki equilibrium`、`is the vault converged`、`is maintenance done`、`are my skills fighting`、`what's still pending across all the maintenance skills` 时触发。
59. Equilibrium 概念：维护技能是共享同一 vault 的博弈玩家；每个有 move set（lint fixes、dedup merges、new links、tag normalizations）和自身 objective；当没有玩家有 profitable deviation、每次 audit pass 提议零变更时，vault 处于 equilibrium；这是真正的 maintenance done 信号，比单个 skill 报告 clean 更强，因为技能可能互相撤销。
60. Equilibrium 对 players 只读：运行每个 audit 的 report-only form，绝不允许应用变更；除了 `_insights.md` 中的 snapshot line，不写任何东西。
61. Equilibrium players 表：`wiki-lint` 用 `obsidian-wiki lint $OBSIDIAN_VAULT_PATH --json`，counts 为 `findings` 中每个 finding（求和 `stats.findings` 计数）；`wiki-dedup` 用 audit mode（无 `--merge`，无 `--auto`），counts 为每个 HIGH 或 MEDIUM duplicate pair；`cross-linker` 仅 audit pass，报告 proposed links，不插入，counts 为每个它会链接的 unlinked mention；`tag-taxonomy` 仅 Step 1 audit，报告 drift，不做 normalize，counts 为每个它会 rename 或 drop 的 tag。
62. Equilibrium 确定性说明：只有 `wiki-lint` 是确定性的；其他三个是 LLM pass，其计数是各自报告的估计；输出中要说明，不要暗示精确。
63. Equilibrium 报告：输出 `# Vault Equilibrium — <TIMESTAMP>`、`equilibrium: no` 或 `yes`、表格列 `Player`、`Pending moves`、`Top proposed move`，例如 `wiki-lint 4 fix broken link [[concepts/old-name]] in synthesis/foo.md`、`wiki-dedup 1 merge entities/gpt-4.md ← entities/gpt4.md (0.91)`、`cross-linker 12 link attention mechanism in concepts/transformers.md`、`tag-taxonomy 0 —`；然后列出 `Deviating players` 和 `Converged players`；当所有计数为零，报告 `equilibrium: yes` 并明确说明此时运行任何维护技能都不会改变任何东西。
64. Equilibrium 震荡检测：某 player 计数被驱到零后反复返回，说明两个 player 在 fighting，经典案例是 `tag-taxonomy` normalize 一个 tag，而 ingest skill 的默认值不断重新添加，导致 vault 永远循环、不收敛。
65. Equilibrium 在 `_insights.md` 中现有 `GRAPH_SNAPSHOT` 旁追加 `<!-- EQUILIBRIUM_SNAPSHOT: {"ts":"2026-08-25T10:00:00Z","lint":4,"dedup":1,"crosslink":12,"tags":0} -->`；读取之前 `EQUILIBRIUM_SNAPSHOT` 行（保留最后 5，丢弃更早）并比较。
66. Equilibrium 比较规则：一个 player 跨多次运行出现 `0 → N → 0 → N` 是 oscillating，按名称标记并点名可能对手（重新引入这些 moves 的 skill）；一个 player 计数只增是 losing ground，说明没人运行它；没有 previous snapshot 则报告 `first run, no baseline yet` 并跳过比较。
67. Equilibrium 震荡处理：震荡是报告，不是修复；解决方案是人类决定哪个 player 的 objective 赢，通常是改 `_meta/taxonomy.md` 规则或 owner 的 `AGENTS.md`，而不是再跑一次维护。
68. Equilibrium source track record：pending moves 在各 source 间分布不均；对每个出现在 player findings 中的页面，通过 `.manifest.json` → `pages_created` / `pages_produced` 反查是哪个 manifest source 产生的；当一个 source 占某 player ≥3 issues 或 ≥50% pending moves，加一行 `Source track record:`，如 `~/exports/slack-dump/ — 7 of 12 cross-linker moves, 3 of 4 lint findings. Its pages consistently need repair; consider reviewing its source_quality bucket.`
69. Equilibrium source track record 是重复博弈视角：持续产生需修复页面的 source 应获得更低 `source_quality`；仅报告，绝不自动调整 `source_quality` 或 trust ledger；owner 通过现有 trust flow（`obsidian-wiki trust-record`）决定，与其他 confidence 变更一样。
70. Equilibrium 跳过条件：vault 少于 20 页，audits 在这个规模只是噪音；若任一 player 的 audit 无法以 clean report-only form 运行，省略该行并说明 missing player，不猜计数。
71. Notes：若 manifest 不存在，把所有内容报告为 new，并推荐 full ingest。
72. Notes：本技能只读取和报告，不修改任何东西；例外是 insights mode 写入 `_insights.md`，该文件可再生。
73. Notes：实际 ingest 工作由 ingest skills 完成（`wiki-ingest`、`claude-history-ingest`、`codex-history-ingest`）。
74. Notes：这些 ingest skills 负责在完成后更新 manifest。
75. QMD Refresh After Vault Writes：QMD 是搜索索引，不是 source of truth；若 `$QMD_WIKI_COLLECTION` 为空或未设置则跳过；仅在本技能写入或重写 vault markdown 后运行；若 QMD refresh 失败，不回滚 vault changes，单独报告 QMD status。
76. QMD 命令：使用 `$QMD_CLI`（若设置），否则 `qmd`；运行 `${QMD_CLI:-qmd} update`。
77. QMD 命令：若输出说需要 vectors 或 embeddings 可能 stale，运行 `${QMD_CLI:-qmd} embed`。
78. QMD 验证：用 `${QMD_CLI:-qmd} ls $QMD_WIKI_COLLECTION`，或已知具体页面路径时用 `${QMD_CLI:-qmd} get qmd://$QMD_WIKI_COLLECTION/<page>.md -l 5`。
79. QMD 记录状态之一：`QMD refreshed: update + embed + verified`、`QMD refreshed: update only + verified`、`QMD skipped: QMD_WIKI_COLLECTION unset`、`QMD skipped: qmd CLI unavailable`、`QMD failed: <short error summary>`。

适用边界 · 注意事项

• vault 少于 20 页时，insights 与 equilibrium 模式图结构/audit 只是噪音，应跳过。
• 刚执行 fresh `wiki-rebuild` 后，未至少一次 ingest 前，不应运行 insights 模式。
• 没有 Obsidian vault、`.manifest.json` 或 `obsidian-wiki` CLI 时，完整功能不适用；QMD 未配置则只能跳过 QMD 刷新。