从任意项目同步知识到 Obsidian…

适用于从任意项目目录把项目知识蒸馏进 Obsidian wiki，并在已有页面基础上合并更新、交叉链接和记录同步状态。

适用场景

解决思路

1. 开始前先读并应用 `llm-wiki/SKILL.md` 的 `Writing Profile Resolution` 部分；框架 schema、provenance、安全与操作要求优先；`WRITING.md` 偏好仅用于新起草或重写的自然语言 Markdown，保留源内容和结构化记录。
2. 按 `llm-wiki/SKILL.md` 的 Config Resolution Protocol 解析配置：inline `@name` override → 从 CWD 向上查找 `.env` → 全局配置 → prompt setup；取得 `OBSIDIAN_VAULT_PATH`、`OBSIDIAN_WIKI_REPO`、`OBSIDIAN_LINK_FORMAT`（默认 `wikilink`，可为 `markdown`），以及可选 QMD 设置如 `QMD_WIKI_COLLECTION`；该流程可从任意项目目录工作。
3. 读取 `$OBSIDIAN_VAULT_PATH/.manifest.json` 检查当前项目是否同步过。
4. 读取 `$OBSIDIAN_VAULT_PATH/index.md` 了解 wiki 已有内容。
5. 在 Step 4–5 写内部链接时，依据 `llm-wiki/SKILL.md` 的 Link Format 部分和 `OBSIDIAN_LINK_FORMAT` 值应用链接格式。
6. Step 1：扫描当前工作目录理解项目：`README.md`、`docs/`、任何 markdown 文件；源码结构（框架、语言、关键抽象）；`package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml` 等项目定义文件；Git log（关注信号决策的提交信息，忽略 “fix typo” 类）；若存在 `.claude/` 则读 Claude memory 文件；从目录名推导干净的项目名。
7. Step 2：检查 `.manifest.json` 中该项目条目计算增量：首次同步则全量扫描，一切皆新；已同步过则查看 `last_commit_synced`。
8. Step 2：计算增量前验证存储 SHA 仍可达：运行 `git merge-base --is-ancestor <last_commit_synced> HEAD`；若 exit 0（ancestor）安全，运行 `git log <last_commit_synced>..HEAD --oneline` 查看变化；若 exit 1（非 ancestor，发生 rebase 或 force-push），警告用户：`Stored commit <sha> is no longer reachable — branch may have been rebased or force-pushed. Falling back to full scan.`，按首次同步处理：重新全量扫描，并在 Step 6 结束时把 `last_commit_synced` 更新为当前 HEAD SHA。
9. Step 2：若自上次同步以来没有有意义变化，告知用户并停止。
10. Step 3：按 Karpathy 模式核心问题决定蒸馏内容：“如果 3 个月后零上下文回来，你想知道这个项目什么？”
11. Step 3：值得蒸馏：架构决策及原因；构建中发现的模式（否则还会再 Google 的）；项目依赖的工具、服务、API 以及它们如何串联；关键抽象、连接方式和心智模型；评估过的取舍、选了什么及为什么；构建中学到的、读代码不明显的知识。
12. Step 3：不值得蒸馏：文件列表、样板、显而易见的配置；没有更广泛教训的单个 bug 修复；依赖版本、lock 文件内容；代码已清楚表达的实现细节；任何人看 diff 都能读出的例行变更。
13. Step 3：启发式：如果读代码库就能回答，就不进 wiki；如果必须跨 20 个 commit 读 git blame 才能重新推导推理，就进 wiki。
14. Step 3b（可选）：构建代码理解 focus map。守卫：若 `obsidian-wiki code-understand` 命令失败或不可用，跳过本步继续，它只是优化不是必需。
15. Step 3b：当项目含代码时，在蒸馏前运行本地代码理解提取器：`obsidian-wiki code-understand --project "$(pwd)" --pretty`。
16. Step 3b：非首次同步时，用增量播种 focus map：`obsidian-wiki code-understand --project "$(pwd)" --since <last_commit_synced> --pretty`；首次同步省略 `--since`。
17. Step 3b：处理 focus-map 输出：当 `backend: codegraph` 时，将 focus-map 条目视为带 `file:line` 引用的结构事实；当 `backend: builtin` 时，将 `defines`/`imports` 条目视为事实，但将 `rg-reference` 条目视为较弱证据，引用前打开文件验证；只打开排序后的 `files`/`file:lines` 指向的内容；绝不把 JSON 粘贴进 wiki 或 vault。
18. Step 3b：引用证据：写入页面的每个架构声明都引用其证据为 `(file:lines)`，来自 focus map 或打开的源码；继续使用现有 provenance 标记。
19. Step 3b：强制清理过期关系：更新已有 `projects/<name>/` 页面时，用当前 focus map（或 `obsidian-wiki ast-extract` 做符号级复核）交叉检查每条此前记录过的代码关系；移除目标符号已不存在或不可达的关系；更新页面并在 `log.md` 记录移除项；防止假阳性累积。
20. Step 3b：绝不把 `.codegraph/` 或 `code-understand` JSON 写入 `$OBSIDIAN_VAULT_PATH`；图是项目仓库中的缓存/侧车，不是 wiki 知识。
21. Step 3b（可选）：若输出因 codegraph 不可用而报告 `backend: builtin` 且用户想要增强后端，可提议安装：`npm install -g @colbymchenry/codegraph`（或将 `CODE_UNDERSTANDING_CODEGRAPH_BIN` 设为已有二进制），然后重跑本步使 focus map 使用 graph；未经用户同意绝不安装，且绝不让缺失 codegraph 阻塞同步。
22. Step 3b：若 `obsidian-wiki` 未安装或命令失败，跳过本步并正常继续 Step 4，它只是优化不是必需。
23. Step 4：蒸馏到 wiki 页面：项目特定知识放到 `$VAULT/projects/<project-name>/`，结构为 `projects/<project-name>/<project-name>.md`（项目概览，以项目命名，不是 `_project.md`）、`concepts/`（项目特定想法、架构）、`skills/`（项目特定 how-to、模式）、`references/`（项目特定来源摘要）。
24. Step 4：概览页 `<project-name>.md` 应包含：项目是什么（一段）；关键概念及如何连接；指向项目特定页面和全局 wiki 页面的链接。
25. Step 4：全局知识放全局分类：学到的一般概念 → `concepts/`；可复用模式或技术 → `skills/`；工具/服务/人 → `entities/`；跨项目分析 → `synthesis/`。
26. Step 4：每个页面需要 YAML frontmatter，包含 `title`、`category`、`tags`、`sources`、`summary`、`provenance`（`extracted`、`inferred`、`ambiguous`）、`base_confidence`、`lifecycle`、`lifecycle_changed`、`created`、`updated`；`title` 和 `summary` 使用 folded scalar 语法 `>-`，保持 frontmatter 对标点安全，无需转义；`title` 和 `summary` 内容在 `summary: >-` 下缩进两个空格。
27. Step 4：每个新建/更新页面写 `summary:` frontmatter 字段（1–2 句，≤200 字符），用 `>-` folded 风格；项目同步的好 summary 回答“此页告诉我的项目信息中，有哪些是只看标题猜不到的？”；该字段支持 `wiki-query` 低成本检索。
28. Step 4：按 `llm-wiki` 的 Provenance Markers 部分应用 provenance 标记；项目同步中：Extracted 为代码、配置、文档或提交信息可见的内容（文件结构、依赖、函数签名、文件作用）；Inferred 为决策原因、设计理由、取舍、“团队选择 X 因为 Y”，除非提交信息/文档/ADR 明确说明；Ambiguous 为代码与文档冲突，或明显进行中迁移且两种模式并存。
29. Step 4：计算大致比例，并在每个新建/更新页面写 `provenance:` 块。
30. Step 4：更新 vs 创建：若 vault 中页面已存在，合并新信息进去，不创建重复；若向已有页面添加内容，更新 `updated` 时间戳并加入新来源；创建任何新页面前检查 `index.md` 已有什么。
31. Step 5：创建/更新页面后交叉链接：从新页面添加 `[[wikilinks]]` 到已有相关页面；从已有页面在相关处添加 `[[wikilinks]]` 回到新页面；把项目概览链接到所有项目特定页面和相关全局页面。
32. Step 6：更新 `.manifest.json`：添加或更新该项目条目；项目身份必须跨机器可移植：在 `source_repo` 记录仓库 URL（来自 `git remote get-url origin`，规范化为 `host/owner/name`），只可选用 `source_cwd_hint` 记录本机 checkout 位置；绝不写机器绝对路径；参见 `llm-wiki/SKILL.md` → `.manifest.json`（Source key contract v2）；条目包含 `source_repo`、`source_cwd_hint`、`last_synced`、`last_commit_synced`、`pages_in_vault`。
33. Step 6：若项目不是 git 仓库，为 `source_repo` 使用 `repo:<stable-name>` 伪键，并只保留 `source_cwd_hint` 作为位置字段。
34. Step 6：更新 `index.md`：为任何新创建页面添加条目。
35. Step 6：更新 `log.md`：追加 `- [TIMESTAMP] WIKI_UPDATE project=<project-name> pages_updated=X pages_created=Y source_repo=github.com/owner/<project-name>`。
36. Step 6：更新 `hot.md`：读取 `$OBSIDIAN_VAULT_PATH/hot.md`（若缺失，用 `wiki-ingest` 中模板创建）；用刚同步的内容重写 **Recent Activity**（最多最近 3 个操作）；若该项目是持续焦点，更新 **Active Threads**；用本次同步浮现的最重要架构洞见或决策更新 **Key Takeaways**；更新 `updated` 时间戳；概念化书写，例如：“Synced obsidian-wiki — added wiki-capture and wiki-research skills, core new capabilities are autonomous web research and conversation capture.”
37. Step 7（可选）：刷新 QMD wiki 索引（需要 `QMD_WIKI_COLLECTION`）。守卫：若 `$QMD_WIKI_COLLECTION` 为空或未设置，跳过本步；markdown vault 是事实来源，QMD 只是搜索索引。
38. Step 7：仅当页面、`.manifest.json`、`index.md`、`log.md`、`hot.md` 都已写入后运行本步；若 Step 2 发现无有意义变化且同步提前停止，不要刷新 QMD。
39. Step 7：此刷新当前需要本地 QMD CLI；若设置了 `$QMD_CLI` 用它，否则用 `qmd`；若 CLI 不可用或返回错误，不要回滚 wiki 更新，报告 wiki 已更新但 QMD 刷新跳过或失败。
40. Step 7：CLI 刷新：`${QMD_CLI:-qmd} update`。
41. Step 7：若输出说新哈希需要向量，或页面被创建/更新且嵌入可能过期，运行：`${QMD_CLI:-qmd} embed`。
42. Step 7：验证至少一个创建或实质更新的页面在 wiki collection 中可见：`${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/projects/<project-name>/<page>.md" -l 5`；若确切 `qmd://` 路径不确定，使用 `${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION" | rg "<project-name>"`。
43. Step 7：在最终报告中记录 QMD 刷新为以下之一：`QMD refreshed: update + embed + verified`；`QMD skipped: QMD_WIKI_COLLECTION unset`；`QMD skipped: qmd CLI unavailable`；`QMD failed: <short error summary>`。
44. Tips：积极合并：若项目使用 React Server Components，且 `concepts/react-server-components.md` 已存在，不要新建页面；更新已有页面并加入此项目作为来源。
45. Tips：查阅 tag taxonomy：若 `$VAULT/_meta/taxonomy.md` 存在则读取，并使用规范标签。
46. Tips：不要复制代码：蒸馏知识而非实现；“This project uses a debounced search pattern with 300ms delay” 有用，粘贴实际 debounce 函数没用。
47. Tips：项目概览是锚点：`<project-name>.md` 是用于快速定位的入口，要写好。

适用边界 · 注意事项

• 没有 Obsidian vault、`llm-wiki/SKILL.md` 或可解析配置（无法得到 `OBSIDIAN_VAULT_PATH` 等）时。
• 项目自上次同步后无有意义变化，或用户只想同步文件列表、样板、依赖版本、lock 文件内容时。
• 需要把原始代码、`.codegraph/` 缓存或 `code-understand` JSON 直接写入知识库时；或不愿应用 Writing Profile/框架 schema 时。