git-wiki

项目 Wiki

默认在 .wiki 下为代码项目维护本地 wiki，也可使用按语言划分的根目录，例如 .wiki-cn、.wiki-fr，或用户指定的确切 wiki 目录，例如 wiki-cn。

信息源始终是当前 HEAD 中由 Git 跟踪的仓库文件，包括 .docs/ 和 docs/ 中由 Git 跟踪的文档，而不是 wiki。 Wiki 文件本身可以未被跟踪；如果所选 wiki 根目录存在，请从工作树中读取并更新其中的当前内容。

规则

• 仅操作由 Git 跟踪的文件和 Git 历史
• 忽略已暂存和未暂存的未提交更改；内容摄取和查询验证仅使用 HEAD 中已提交的内容
• 每个请求只选择一个 wiki 根目录。默认使用 .wiki；使用用户指定的根目录或语言，例如 .wiki-cn、wiki-cn、.wiki-fr、“中文 wiki”或“法语 wiki”
• 每个 wiki 根目录彼此独立。除非用户明确要求，否则不要在不同语言根目录之间同步、比较、翻译、合并或复制页面
• 从基于 Git 的源选择中排除所有 wiki 根目录：.wiki/**、.wiki-*/** 和 wiki-*/**
• 不要假定任何 wiki 根目录由 Git 跟踪；如果所选根目录中存在当前的 index.md 检查点，请使用它
• 每个 wiki 页面都必须包含 YAML frontmatter
• 每次摄取时都必须更新所选根目录的 index.md
• 摄取前不要询问用户
• 导出时读取所选 wiki 根目录下工作树中的当前文件，而不是 HEAD 中由 Git 跟踪的仓库文件

Wiki 结构

必需：

• <wiki-root>/index.md — 面向读者的入口和主目录（仅跟踪该根目录的最后一次摄取提交）

可选（按需创建）：

• <wiki-root>/overview/ — 介绍项目、启动流程、存储和阅读路径的概览页面
• <wiki-root>/features/ — 每项重要产品能力或实现领域对应一个页面
• <wiki-root>/bug-fixes/ — 每项值得关注的错误修复或补丁对应一个页面
• <wiki-root>/concepts/ — 涉及多个领域的理念和模式
• <wiki-root>/entities/ — 数据模型、架构、类型
• <wiki-root>/flows/ — 序列、管道、请求生命周期
• <wiki-root>/risks/ — 不变量、兼容性约定、脆弱行为以及不可破坏的内容
• <wiki-root>/reference/ — 当某个源路径需要重点说明时，创建与代码结构对应的参考页面
• <wiki-root>/notes/ — 临时记录或待解决的问题

便于理解的结构

Wiki 的目的是帮助人理解代码库，而不是让仓库自我介绍。规划入口时，应优先回答读者的问题，而不是按代码目录组织。

<wiki-root>/index.md 必须按以下顺序回答这些问题：

1. 这是什么？
2. 快速入门
3. 它为何存在？
4. 运行它时会发生什么？
5. 数据保存在哪里？
6. 重要的组成部分有哪些？
7. 有什么内容应避免破坏？
8. 应该从哪里开始查找？

以这些问题作为主要导航。features/、entities/、flows/ 和 reference/ 是辅助证据，而不是构建认知模型的起点。

Get Started 部分用于帮助读者熟悉代码库，而不是重复 README。它应帮助有经验的新手了解前 10 分钟内需要知道的内容：

• 要运行的主要命令
• 必需的环境或服务
• 预期的成功输出
• 首先要阅读的文件
• 一个安全的首次修改
• 一个看似诱人但危险的修改

如果仓库已有 README.md 或 docs/ 中的设置说明，请链接到这些说明，并仅概述有助于读者理解代码的内容。

Wiki 根目录选择

• 默认 Wiki 根目录：.wiki
• 特定语言的根目录：创建新语言 Wiki 时，优先使用 .wiki-<language-code>，例如，中文使用 .wiki-cn，法语使用 .wiki-fr
• 如果用户指定了确切目录，例如 wiki-cn，则使用该确切根目录，不要对其进行规范化
• 各语言根目录之间不继承检查点、页面、链接或过期状态
• 用户按语言名称要求创建语言 Wiki 时，页面正文使用该语言，并保持代码标识符、文件路径和 API 名称不变

页面约定

index.md 前置元数据

index.md 包含用于跟踪摄取状态的额外字段：

---
title: "Project Wiki"
type: "index"
status: "active"
language: "<language-code|default>"
last_commit: "<full-sha>"
updated_at: "YYYY-MM-DD"
---

last_commit 是所选 Wiki 根目录最近一次完整仓库摄取时的完整 Git 提交 SHA。无论该根目录是否受 Git 跟踪，此检查点都保存在所选根目录当前的 index.md 文件中。下次对同一根目录进行摄取时，优先使用此处保存的 last_commit，通过 git diff --name-status -M <last_commit> HEAD 查找已更改的文件。

如果 Git 元数据不可用，请勿回退到文件系统扫描。在 Git 访问恢复之前，摄取和 lint 均不可用。

其他页面

---
title: "Page Title"
type: "overview|feature|bug-fix|concept|entity|flow|risk|reference|note"
status: "draft|active|stale"
language: "<language-code|default>"
source_paths: []
updated_at: "YYYY-MM-DD"
---

对于 .wiki，将 language 设为 default；对于 .wiki-cn 或 wiki-cn，设为 cn；对于 .wiki-fr，设为 fr；其他特定语言根目录则使用相应的语言代码。

如果源文件自页面上次更新后发生了显著变化，或者页面描述的内容已不复存在，请使用 status: "stale"。摄取期间，应更新 source_paths 自 last_commit 以来发生变化的页面，或将其标记为过期。不要自动删除过期页面——请将其标记出来并注明差异，以便用户决定。

页面命名

• 使用小写、以连字符分隔的文件名：auth-middleware.md、user-schema.md
• 优先根据读者熟悉的概念为页面命名：login-check.md、saved-data-shape.md、startup-flow.md
• 仅对参考页面，或没有更清晰的面向读者的名称时，才使用源路径命名：src/api/routes.ts → <wiki-root>/reference/src-api-routes.md
• 为概念和流程使用描述性名称：<wiki-root>/concepts/request-lifecycle.md

Wiki 链接

只要页面引用了另一页面所涵盖的内容，就在页面之间使用 [[page-slug]] 链接。目标应与目标文件名一致，但不包含 .md 扩展名。这样可以让 Wiki 便于导航，也能让 lint 确定性地解析链接。

导入

在以下情形触发：

• ingest
• ingest [file]
• ingest [folder]
• ingest wiki-cn
• ingest .wiki-fr
• refresh wiki
• update wiki
• update Chinese wiki

工作流：

1. 根据请求选择 wiki 根目录。默认为 .wiki；如果指定了明确的根目录或特定语言的根目录，则使用该目录
2. 如果 <wiki-root>/index.md 存在，则从工作树中读取，即使 wiki 根目录尚未被跟踪 — 注意 frontmatter 中的 last_commit
   • 缺少 <wiki-root>/index.md 或缺少 last_commit，表示该根目录没有先前的导入检查点
3. 运行 git rev-parse HEAD 获取当前 HEAD 提交 SHA
4. 检测变更文件：
   • 如果已设置 last_commit：运行 git diff --name-status -M <last_commit> HEAD，并排除所有 wiki 根目录（.wiki/**、.wiki-*/**、wiki-*/**）
   • 即使选定的 wiki 根目录尚未被跟踪，也要使用已保存的 last_commit；不要将未跟踪的 wiki 根目录视为从 HEAD 开始的新导入
   • 更新 wiki 页面时，使用 git 状态码区分新增、修改、删除和重命名的路径
   • 如果没有先前的导入，则从 git ls-files 在 HEAD 处构建广泛的导入候选集，并排除所有 wiki 根目录（参见下文的导入优先级）
5. 确定范围：
   • 如果指定了文件或文件夹，则优先处理该范围 — 将已跟踪的候选集限制在该范围内
   • 对于指定范围的导入，除非该导入也涵盖了自 last_commit 以来变更的所有文件，否则不要推进 <wiki-root>/index.md:last_commit
   • 否则，先导入变更文件，再补齐缺失的覆盖内容
6. 阅读相关的已跟踪仓库文件 — 理解其作用
7. 在选定的 wiki 根目录下更新或创建 wiki 页面
8. 对于已删除源文件对应的页面，在选定的 wiki 根目录下将其标记为 status: "stale"，并在页面正文中添加说明；根据 git 提供的重命名信息更新移动或重命名的页面
9. 更新 <wiki-root>/index.md：
   • 始终将 updated_at 设置为今天
   • 只有在完整导入或处理完自上一个 last_commit 以来的全部变更文件后，才将 last_commit 设置为当前 HEAD SHA
   • 如果广泛导入在覆盖不完整时提前停止，则保持 last_commit 不变，并在 index.md 中注明初始覆盖仍不完整
   • 绝不能仅仅因为选定的 wiki 根目录尚未被跟踪，就丢弃已有的 last_commit

导入会自动进行。不要向用户请求确认。

如果 git 命令失败，请说明在恢复 git 访问权限之前，wiki 技能无法执行导入。不要改为遍历目录。

导出

在以下情况下触发：

• export wiki
• bundle wiki
• archive wiki
• one-page wiki
• prepare wiki for notebooklm
• send wiki to notebooklm

工作流：

1. 根据请求选择 Wiki 根目录。默认为 .wiki；如果指定了根目录或特定语言的根目录，则使用指定目录
2. 检查工作树中是否存在 <wiki-root>/index.md
   • 如果所选 Wiki 根目录缺失或明显不完整，先执行 ingest，无需询问
3. 从工作树导出当前所选 Wiki，而不是从 HEAD 导出
4. 使用捆绑的零依赖 CLI：

node skills/git-wiki/scripts/export-wiki-bundle.mjs \
  --input-dir <wiki-root>

5. 默认输出路径为所选 Wiki 根目录下的 index-{simple-timestamp}.md
6. 如果用户需要其他目标路径，传入 --output-file <path>
7. 如果用户需要在导出文件头中使用自定义标签，传入 --root-name <name>
8. 导出文件必须包含：
   • 带生成日期的仓库/Wiki 标题
   • 涵盖所有捆绑页面的目录
   • 每个 Wiki 文件对应一个章节，并保留选定的 frontmatter
   • 明确的文件起始/结束标记，使捆绑文件可作为归档文件或 NotebookLM 来源
9. 如果请求明确涉及 NotebookLM，先执行导出，然后将生成的捆绑文件作为来源文件交给 notebooklm 技能

导出要求：

• 优先捆绑 <wiki-root>/**/*.md
• 仅保留有用的 frontmatter 字段，例如 title、type、status、language、tags、description、source_paths、updated_at 和 last_commit
• 将 [[wiki-links]] 规范化为纯文本，使下游工具无需理解 Obsidian 语义
• 删除 Obsidian 图片嵌入，例如 ![[image.png]]
• 按相对路径对文件排序，使输出具有确定性
• 默认文件名使用简单时间戳，例如 .wiki-fr/index-20260510-143522.md
• 不要将导出当作 ingest 的替代方案；导出只是打包当前 Wiki，不会重建 Wiki

Ingest 优先级

从 Git 跟踪的文件进行大范围 ingest 时，先构建面向用户的入口页面，再添加支撑代码页面。按以下顺序进行，并在覆盖充分时停止（中型项目通常为 10–20 个页面）：

1. 根目录 README 以及 .docs/ 和 docs/ 下受跟踪的文档
2. 包、构建和工作区配置（package.json、pyproject.toml、Cargo.toml 等），以确定项目的运行方式
3. 入口点（main.ts、index.ts、app.py、cmd/ 等），解释启动和运行时行为
4. 存储、生成的输出、配置、机密信息、缓存、日志和持久化边界 → <wiki-root>/overview/ 或 <wiki-root>/entities/
5. 核心用户/系统工作流 → <wiki-root>/flows/
6. 重要的活动部件、概念和子系统边界 → <wiki-root>/concepts/ 或 <wiki-root>/features/
7. 读者应避免破坏的契约和脆弱部分 → <wiki-root>/risks/
8. API 定义、架构和持久化层 → <wiki-root>/features/ 或 <wiki-root>/entities/
9. 作业、队列和后台工作进程 → <wiki-root>/features/
10. UI 结构（如有）→ <wiki-root>/features/
11. 测试（总结行为预期和安全网，不要逐一记录每个测试文件）
12. Git 历史中值得注意的错误修复 → <wiki-root>/bug-fixes/

对于大型仓库（100 个以上文件），应注重深度而非广度：深入记录 10 个最重要的模块，而不是浅尝辄止地涉及 50 个模块。

查询

当用户询问项目问题时：

1. 根据请求选择 wiki 根目录。默认使用 .wiki；如果指定了根目录或特定语言的根目录，则使用指定目录
2. 如果 <wiki-root>/index.md 存在，则读取该文件
3. 如果所选根目录中存在相关 wiki 页面，则读取这些页面
4. 如果所选 wiki 不存在、相关页面缺失或页面标记为过时，则直接根据 Git 跟踪的仓库源文件进行核实后再回答
5. 如果相关，优先参考 .docs/ 和 docs/ 中由 Git 跟踪的文档，然后在需要时通过代码或配置进行确认
6. 如果答案涉及具体值（数量、名称、配置），则根据 Git 跟踪的仓库源文件进行核实
7. 如果用户指定了语言根目录，则使用所选 wiki 的语言回答，并简明说明；存在相关 wiki 页面时，添加 [[wiki-link]] 引用
8. 如果你得出了所选 wiki 根目录中尚未记录的新理解，请提及这一点——用户可以让你将其保存

检查

触发条件：

• lint
• lint wiki
• check wiki
• lint .wiki-fr
• check Chinese wiki

检查内容：

• 页面之间是否存在矛盾（两个页面的说法相互冲突）
• 是否存在没有入站 [[links]] 的孤立页面
• 是否有在多个页面中提及、但没有独立页面介绍的概念
• 可能已偏离当前源文件的过时页面（status: "stale"）
• 主要变更模块的内容是否缺失（自 last_commit 以来有文件变更，但没有对应的 wiki 页面）
• 是否存在失效的 [[wiki-links]]（目标页面不存在）

检查输出格式

## Wiki Lint Report — YYYY-MM-DD

### Errors
- [page] description of contradiction or broken link

### Warnings
- [page] description of potential issue

### Suggestions
- description of missing coverage or improvement

### Next Questions
- open questions worth investigating

除非用户明确要求，否则不要自动修复。

写作指南

• 面向聪明的新手，而不是维护者。先用通俗易懂的说法，再在有帮助时补充准确的代码术语：“登录检查”优先于“auth middleware”，“保存的数据结构”优先于“schema”，“后台任务”优先于“worker”
• 围绕读者的问题组织页面，再用文件内容支撑答案。除非页面明确作为参考资料，否则不要从目录介绍开始
• 在说明文件的实现细节之前，先解释它在产品或工作流中的作用
• 避免使用未解释的缩写、框架术语和内部简写。若必须使用技术术语，请在同一句中解释
• 总结即可；不要照搬大段代码块——可以给出几行示例代码，但应解释其模式，而不是粘贴实现
• 使用具体文件路径作为锚点（src/api/routes.ts:42）
• 区分事实（直接从源文件读取）和推断（你的解释）
• 使用 [[wiki-links]] 链接相关页面
• 页面控制在约 500 词以内；需要更多内容时创建新页面，而不是不断扩展单个页面
• 优先覆盖实用内容，而非面面俱到——优秀的 wiki 应便于查找，而不是百科全书

质量标准

符合以下条件时，wiki 即为成功：

• <wiki-root>/index.md 能帮助新读者在 2 分钟内了解如何浏览项目
• 新手能够回答项目是什么、为何存在、运行时会发生什么、数据保存在哪里、哪些内容很重要、哪些内容不能破坏，以及应该先查看哪里
• 答案可以从 wiki 页面入手，并在代码中得到核实
• Ingest 使用已保存的 last_commit 自动检测变更文件
• 检查能在 wiki 产生误导之前发现内容偏离