wiki-update

Wiki 更新 — 将任意项目同步到你的 Wiki

将当前项目中的知识提炼到用户的 Obsidian wiki 中。此技能可在任意项目目录中使用，而不只是 obsidian-wiki 仓库。

开始之前

写作风格配置： 在起草或改写自然语言 Markdown 之前，请阅读并遵循 llm-wiki/SKILL.md 中的 Writing Profile Resolution 部分。框架架构、来源记录、安全性及特定操作要求优先。 WRITING.md 中的偏好仅适用于新起草或改写的自然语言 Markdown；保留源内容和结构化记录。

1. 解析配置 — 遵循 llm-wiki/SKILL.md 中的 Config Resolution Protocol（内联 @name 覆盖 → 从 CWD 向上查找 .env → 全局配置 → 提示词设置）。此步骤会提供 OBSIDIAN_VAULT_PATH、OBSIDIAN_WIKI_REPO、OBSIDIAN_LINK_FORMAT（默认为 wikilink，也可以是 markdown），以及可选的 QMD 设置，例如 QMD_WIKI_COLLECTION。可在任意项目目录中使用。
2. 读取 $OBSIDIAN_VAULT_PATH/.manifest.json，检查此项目之前是否同步过。
3. 读取 $OBSIDIAN_VAULT_PATH/index.md，了解 wiki 中已有的内容。

在步骤 4–5 中编写内部链接时，根据 OBSIDIAN_LINK_FORMAT 的值，应用 llm-wiki/SKILL.md 中的链接格式（Link Format 部分）。

步骤 1：了解项目

扫描当前工作目录，了解项目的内容：

• README.md、docs/ 和所有 Markdown 文件
• 源代码结构（框架、语言、关键抽象）
• package.json、pyproject.toml、go.mod、Cargo.toml 或其他项目定义文件
• Git 日志（重点关注体现决策的提交消息，而非“修正拼写错误”之类的内容）
• 如果存在，检查 Claude 记忆文件（项目中的 .claude/）

根据目录名称生成简洁的项目名称。

步骤 2：计算差异

检查此项目在 .manifest.json 中的记录：

• 首次同步？ 扫描全部内容，一切都是新增内容。
• 之前同步过？ 查看 last_commit_synced。计算差异之前，先验证存储的 SHA 是否仍可从当前分支访问：

  git merge-base --is-ancestor <last_commit_synced> HEAD
  

  • 退出码为 0（祖先提交）： 安全。运行 git log <last_commit_synced>..HEAD --oneline，查看发生了哪些变化。
  • 退出码为 1（不是祖先提交 — 发生过变基或强制推送）： 存储的 SHA 已不在此分支的历史记录中。向用户发出警告："存储的提交 <sha> 已无法访问 — 分支可能经过变基或强制推送。将退回到全量扫描。" 随后按首次同步处理：重新扫描所有内容，并在步骤 6 结束时将 last_commit_synced 更新为当前 HEAD SHA。

如果自上次同步以来没有有意义的变化，请告知用户并停止。

步骤 3：决定要提炼哪些内容

这是 Karpathy 模式中的核心问题：如果你三个月后毫无上下文地回到这个项目，哪些信息是你希望了解的？

值得提炼的内容：

• 架构决策及其缘由
• 构建过程中发现的模式（否则你可能会再次通过 Google 搜索的问题）
• 项目依赖的工具、服务和 API，以及它们如何连接
• 关键抽象、它们如何相互关联，以及整体的心智模型
• 评估过的权衡、最终选择的方案及其原因
• 构建过程中学到、但无法直接从代码中看出的内容

不值得提炼的内容：

• 文件列表、样板代码、显而易见的配置
• 没有更广泛经验可供借鉴的单个 Bug 修复
• 依赖项版本、锁文件内容
• 代码中已经清楚说明的实现细节
• 任何人查看差异即可了解的常规更改

经验法则：如果阅读代码库就能回答问题，就不要记入 wiki。如果必须通过查看 20 次提交的 git blame 才能重新推导出缘由，就应该记入 wiki。

步骤 3b：构建代码理解焦点图（可选）

守护条件：如果 obsidian-wiki code-understand 命令失败或不可用，请跳过此步骤并继续 — 这是优化措施，不是必需步骤。

如果此项目包含代码，请在提炼内容之前运行本地代码理解提取器。它会在本地解析代码库并返回一张焦点图 — 按重要性排序的文件和符号，即架构赖以构建的部分 — 这样你就能阅读关键部分，而不必扫描所有内容。

obsidian-wiki code-understand --project "$(pwd)" --pretty

如果这不是首次同步（步骤 2 已计算出 last_commit_synced），请根据增量数据生成焦点图：

obsidian-wiki code-understand --project "$(pwd)" --since <last_commit_synced> --pretty

（首次同步时：省略 --since。）

如何处理焦点图输出

1. 有选择地阅读输出 — 当 backend: codegraph 时，将焦点图条目视为带有 file:line 引用的结构事实；当 backend: builtin 时，将 defines/imports 条目视为事实，但将 rg-reference 条目视为较弱的证据 — 引用前请打开文件核实。只打开焦点图指向的排序靠前的 files/file:lines；切勿将 JSON 粘贴到 wiki 或知识库中。
2. 引用证据 — 写入页面的每项架构声明都要引用其证据，格式为焦点图或已打开源文件中的 (file:lines)；继续使用现有的来源标记。
3. 清理过时关系（必需） — 更新现有的 projects/<name>/ 页面时，请将之前记录的每项代码关系与当前焦点图交叉核对（或使用 obsidian-wiki ast-extract 重新检查符号级关系）。移除目标符号已不存在或不再可达的关系；更新页面并在 log.md 中记录移除情况。这可以避免误报不断累积。
4. 切勿将 .codegraph/ 或 code-understand JSON 写入 $OBSIDIAN_VAULT_PATH — 图谱是项目仓库中的缓存/附属数据，不属于 wiki 知识。
5. CodeGraph 缺失时可主动提供（可选） — 如果输出显示 backend: builtin，原因是 codegraph 不可用，而用户希望使用增强后端，请主动提出为其安装：npm install -g @colbymchenry/codegraph（或将 CODE_UNDERSTANDING_CODEGRAPH_BIN 设置为现有二进制文件），然后重新运行此步骤，让焦点图使用图谱。未经用户同意，切勿安装；缺少 codegraph 也绝不能阻止同步。

如果未安装 obsidian-wiki 或命令失败，请跳过此步骤并照常继续步骤 4 — 这是优化措施，不是必需步骤。

步骤 4：提炼为 Wiki 页面

项目专属知识

存放在 $VAULT/projects/<project-name>/ 下：

projects/<project-name>/
├── <project-name>.md          ← project overview (named after the project, NOT _project.md)
├── concepts/                  ← project-specific ideas, architectures
├── skills/                    ← project-specific how-tos, patterns
└── references/                ← project-specific source summaries

概览页面（<project-name>.md）应包含：

• 项目是什么（一段话）
• 核心概念及其关联方式
• 指向项目专属和全局 wiki 页面的链接

全局知识

非项目专属的内容应放在全局分类中：

发现的内容	存放位置
学到的一般概念	concepts/
可复用的模式或技术	skills/
工具/服务/人员	entities/
跨项目分析	synthesis/

页面格式

每个页面都需要 YAML frontmatter：

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
base_confidence: 0.59
lifecycle: draft
lifecycle_changed: TIMESTAMP_DATE
created: TIMESTAMP
updated: TIMESTAMP
---

Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules.
Keep the title and summary contents indented by two spaces under summary: >-.

# Page Title

- A fact the codebase or a doc actually states.
- A reason the design works this way. ^[inferred]

Use [[wikilinks]] to connect to other pages.

在每个新建或更新的页面中填写 summary: frontmatter 字段（1–2 句话，不超过 200 个字符），并使用 >- 折叠样式。对于项目同步，好的摘要应回答：“这页介绍了哪些从标题中无法猜到的项目信息？”此字段可供 wiki-query 进行低成本检索。

按照 llm-wiki 中的 Provenance Markers 部分应用来源标记。具体到项目同步：

• Extracted — 代码、配置或文档／提交消息中可见的内容：文件结构、依赖项、函数签名、文件用途。
• Inferred — 决策的原因、设计依据、权衡取舍、“团队选择 X 是因为 Y”——除非提交消息、文档或 ADR 明确说明。
• Ambiguous — 代码与文档不一致，或明显正在进行迁移、两种模式并存时。

估算大致占比，并在每个新建或更新的页面中填写 provenance: 区块。

更新与创建

• 如果知识库中已有页面，将新信息合并进去。不要创建重复页面。
• 如果要补充现有页面，请更新 updated 时间戳并添加新来源。
• 创建新内容前，先检查 index.md，了解已有内容。

第 5 步：交叉链接

创建或更新页面后：

• 在新页面中添加指向现有相关页面的 [[wikilinks]]
• 在相关的现有页面中添加指回新页面的 [[wikilinks]]
• 在项目概览中链接所有项目专属页面和相关全局页面

第 6 步：更新跟踪信息

更新 .manifest.json

添加或更新此项目条目。项目标识必须可在不同机器间通用：在 source_repo 中记录仓库 URL（通过 git remote get-url origin 获取，并规范化为 host/owner/name），仅可选择性地使用 source_cwd_hint 记录此机器上该项目的检出位置。绝不能写入机器的绝对路径 — 参见 llm-wiki/SKILL.md → .manifest.json（Source key contract v2）。

{
  "projects": {
    "<project-name>": {
      "source_repo": "github.com/owner/<project-name>",
      "source_cwd_hint": "~/code/<project-name>",
      "last_synced": "TIMESTAMP",
      "last_commit_synced": "abc123f",
      "pages_in_vault": ["projects/<project-name>/<project-name>.md", "..."]
    }
  }
}

如果项目不是 git 仓库，请将 repo:<stable-name> 伪键用作 source_repo，并将 source_cwd_hint 作为唯一的位置字段。

更新 index.md

为所有新建的页面添加条目。

更新 index.md、log.md 和 hot.md

一次加锁调用，不要手动分别编辑三处：

obsidian-wiki memory sync WIKI_UPDATE project=<project-name> \
  pages_created=X pages_updated=Y \
  source_repo=github.com/owner/<project-name> \
  --takeaways "Synced obsidian-wiki — wiki-capture and wiki-research added; the new capabilities are autonomous web research and conversation capture."

--takeaways 应记录本次同步发现的最重要架构洞见或决策，以概念性内容表述，而不是罗列文件。省略该参数即可保留之前的要点。

如果此项目是持续关注的重点，请记录相关事项，以便下一次会话继续跟进：

obsidian-wiki memory todo add "<the open thread>" --origin projects/<project-name>.md

完整流程请参阅 .skills/llm-wiki/references/MEMORY.md。

第 7 步：刷新 QMD Wiki 索引（可选 — 需要 QMD_WIKI_COLLECTION）

守卫条件：如果 $QMD_WIKI_COLLECTION 为空或未设置，请跳过此步骤。 Markdown 知识库是事实来源；QMD 仅用作搜索索引。

仅在页面、.manifest.json、index.md、log.md 和 hot.md 均已写入后执行此步骤。如果第 2 步未发现有意义的变更，并且同步已提前结束，则不要刷新 QMD。

此刷新目前需要本地 QMD CLI。若已设置 $QMD_CLI，请使用它；否则使用 qmd。如果 CLI 不可用或返回错误，不要回滚 Wiki 更新；请报告 Wiki 已更新，但 QMD 刷新已跳过或失败。

使用 CLI 刷新：

${QMD_CLI:-qmd} update

如果输出提示新哈希需要向量，或者页面已创建／更新且嵌入可能已过时，请运行：

${QMD_CLI:-qmd} embed

验证至少有一个新建或有实质更新的页面已显示在 Wiki 集合中：

${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>"

在最终报告中将 QMD 刷新情况记录为以下之一：

• QMD refreshed: update + embed + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

提示

• 积极合并。 如果项目使用 React Server Components，而 concepts/react-server-components.md 已存在，就不要新建页面。更新现有页面，并将此项目添加为来源。
• 参考标签分类体系。 如果 $VAULT/_meta/taxonomy.md 存在，请阅读并使用规范标签。
• 不要复制代码。 提炼知识，而非实现。“此项目采用延迟 300ms 的防抖搜索模式”很有用，但粘贴实际的防抖函数就没有必要。
• 项目概览是核心。 <project-name>.md 文件是读者了解项目概况的入口。请把它写好。