wikikit

wikikit

读者会打开的文档：我该如何运行它？如何完成我来这里要做的那件事？它是如何构建的？凌晨 3 点它宕机时我该怎么办？wikikit 会根据代码库当前的实际情况生成这套文档，在代码变更时保持文档准确，并在文档过时时如实报告。它不是 GitHub Wiki 标签页，因为它编写的所有内容都是仓库内的 Markdown，与代码一同版本管理，并在同一个拉取请求中接受审查。可选择启用 publish 模式，将这套文档镜像到 Wiki 标签页；除非你明确指定，否则它绝不会运行。

由 Agent 构建的仓库会积累计划、审查记录、QA 文档和决策记录，却仍然提供一份写着 npm install 的 README，因为脚手架一年前就是这么写的。知识确实存在，只是散落在项目之外的人永远不会阅读的各种产物中。wikikit 负责面向外部的那一部分。

wikikit 不是什么

• 不是 GitHub Wiki。 所有模式都以仓库内的 Markdown 为事实来源，与代码一同版本管理，并在同一个 PR 中接受审查。Wiki 标签页充其量只是一个可随时弃用的衍生镜像，且只有明确指定 publish 时才会生成。wikikit 从不读取 Wiki 作为输入，也从不将其视为权威来源。
• 不是领域模型。 术语表（CONTEXT.md）和决策记录（docs/adr/）只有一个负责人：安装了 domainkit 时由它负责，否则由人负责。需要某个术语的页面应链接到术语表，而不是自行定义；需要说明理由的架构页面应按编号链接到 ADR，而不是转述其内容。术语表中缺失的术语应转交处理，绝不在文档中擅自编造。当 CONTEXT.md 包含 ## Overview 时，说明产品用途的页面应链接到该概述，而不是重复陈述；architecture.md 应以此链接开篇。
• 不是流程产物。 计划、QA 计划、审查记录、交接文档和 Agent 指令文件（CLAUDE.md 及其同类文件）是为正在处理事务的维护者编写的，会过期，永远不会作为读者文档的事实来源，也不会由此技能编写。
• 不是 API 参考文档生成器。 如果已有生成器（TypeDoc、Sphinx autodoc、OpenAPI 规范），wikikit 会直接链接到其输出，而不是手写一份一周内就会过时的参考资料。

何时运行

• init。 “为这个项目编写文档”“记录这个仓库”“我们没有文档”“生成入门指南”。根据代码库搭建这套文档。
• update。 “更新文档”“这次变更之后文档过时了”，或功能上线后立即进行文档更新。仅刷新因变更而失效的内容。
• audit。 “我们的文档过时了吗”“对照代码检查文档”“有哪些内容没有文档记录”。只读检查。绝不写入任何内容。
• publish。 仅在明确要求时运行。“将文档发布到 GitHub Wiki”“将 docs/wiki/ 同步到 Wiki 标签页”“设置 Wiki 工作流”。安装一个将这套文档镜像到 Wiki 的工作流。

如果无法确定模式，请先询问。 audit 无需成本，而 init 会写入十几个文件；绝不要在两者之间擅自猜测。

绝不会推断需要运行 publish。 它不属于文档更新流程，其他模式也不会导向它；单独说“文档过时了”或“发布文档”意味着运行 update，而不是此模式。只有请求中明确提到 GitHub Wiki、Wiki 标签页或同步工作流时，才会运行此模式。从未提出过此需求的仓库不会知道它的存在。

定位文档集

每种模式都以相同方式开始，因此在读取或写入任何内容之前，三种模式会先对文档所在位置达成一致。在模式输出的第一行列出找到的每个文档集，这样缺失的文档集就能立即显现，而不会被误认为是空结果。

查找现有集合

使用一个 **/.wikimap.yaml glob，搜索范围限定为仓库根目录和工作区 glob（pnpm-workspace.yaml、package.json 中的 workspaces、go.work、Cargo 工作区），并遵循 .gitignore，以防 vendored 目录注入集合。没有根注册表：清单与其描述的集合放在一起，之后添加的集合也会自动被找到。

为没有集合的仓库运行检测阶梯

选择第一个匹配的阶梯，并且在写入任何内容之前说明匹配的是哪一级：

#	阶梯	文档存放位置
1	已配置的文档引擎：mkdocs.yml、docusaurus.config.*、.vitepress/、带有 Starlight 的 astro.config.*、conf.py、Nextra 配置	该引擎配置的内容目录，并在同一轮中更新其导航／侧边栏
2	现有的读者文档树：内容充实且不只是 Agent 产物目录的 docs/，或 documentation/、website/docs/	原样采用；不要迁移
3	回退方案	首次写入时创建 docs/wiki/

docs/wiki/ 将读者文档与共享 docs/ 父目录的 Agent 产物目录隔离开，避免读者误入 QA 计划。但已有文档引擎始终优先，因为 wikikit 会写入仓库已有的网站，不会在没有文档引擎的仓库中引入 MkDocs 或 Docusaurus。

在工作区中，始终写入根集合；只有独立发布或可独立运行的软件包才会拥有自己的集合。 先为根目录运行一次检测阶梯，再为每个符合条件的软件包（packages/<x>/docs/）各运行一次。写入前说明拆分方案：仅有根集合会让架构页面在软件包数量超过约四个后变得不实用，而始终为每个软件包建立集合则不适用于读者只想查看一份入门指南的应用程序单体仓库。

根据磁盘内容核对清单

集中式清单是唯一一种可能看似正确、实际有误的映射，因此所有模式都必须在开始任何工作前付出这项检查成本：

• 磁盘上存在但清单中没有条目的页面；
• 条目对应的页面已不存在；
• 未匹配到任何内容的 documents: glob；
• 不再符合检测阶梯的 home:，通常是因为 init 之后新增了文档引擎。

init 和 update 会在获得同意后修复。audit 会将偏差作为单独一行报告，但不会修复，因为它不会写入任何内容。绝不会隐式迁移：如果原先匹配第 3 级，现在开始匹配第 1 级，就要指出两个路径，并将 git mv 和导航更新作为一个经同意后执行的步骤。若用户拒绝，wikikit 会继续按清单中的位置写入，并在每次运行时报告差异。

文档地图

文档地图是三种模式共同操作的单位。它位于 <doc home>/.wikimap.yaml，以点号开头，使 GitHub 文件夹视图和所有引擎构建都能跳过它，无需修改配置；其中每个页面都有一条条目，记录其 Diátaxis 模式和所描述代码的 glob：

home: docs/wiki
engine: none                    # or mkdocs | docusaurus | vitepress | starlight | sphinx | nextra
pages:
  - path: getting-started.md
    mode: tutorial
    documents: [package.json, src/index.ts, .env.example]
  - path: how-to/deploy-to-staging.md
    mode: how-to
    documents: [.github/workflows/deploy.yml, infra/**]
  - path: architecture.md
    mode: explanation
    adopted: true               # a human wrote it; wikikit maps it, never claims it
    documents: [src/**]

documents: 让 update 无需读取每个页面即可查找代码路径对应的页面，从而降低开销；它也为 audit 提供了时效性预筛选。

页面词汇表

页面	Diátaxis 模式	内容
index.md	无	入口和目录
getting-started.md	教程	安装 → 运行 → 首次成功完成某项操作
how-to/<task>.md	操作指南	每页一项任务，以目标为导向
how-to/set-up-a-dev-environment.md	操作指南	可从贡献者文档中推导出的部分
how-to/cut-a-release.md	操作指南	仓库中实际存在的发布步骤
architecture.md	说明	若存在 CONTEXT.md 概览，则以指向该概览的链接开篇；组件、边界、数据流，以及指向 ADR 的链接
runbooks/<scenario>.md	操作指南（运维人员）	部署、回滚、事件响应、备份／恢复
reference.md	参考	仅涵盖已声明的内容：命令、标志、环境变量、配置键

此表是词汇表，不是配额。 文档地图取决于仓库：没有部署流程的库不需要运行手册，CLI 需要命令页面，有 TypeDoc 构建的仓库则完全不需要 reference.md。

Diátaxis 在内部发挥作用，不直接呈现在读者面前，因为这四种模式是防止文档类型混杂的规则，而不是要印在页面上的术语。操作指南不得偏离到说明内容；架构页面不得变成教程。

词汇表所体现的三个边界：

• 只链接 CONTRIBUTING.md，不编写它。 开发环境设置和发布步骤都在仓库中，像其他操作指南一样可以验证。PR 礼仪、行为准则和评审规范属于代码中无处体现的社会契约，因此编写这些内容会违反仓库中最显眼的贡献者页面所应遵循的依据规则。如果 index.md 中存在该文件，就链接到它。
• reference.md 仅涵盖已声明的内容，即在单一位置声明且可通过单次 grep 重新验证的内容：CLI 命令、标志、环境变量、配置键。库符号和手动维护的 HTTP 端点表不予收录，而应转交生成器处理。此项狭义例外是为了让没有文档工具、但有二十个标志的 CLI 至少能有点文档。
• 不创建镜像页面。 镜像页面会重述一个已经自带文档的源文件：为每个技能、插件、模块、命令或软件包各建一个页面，并复制各自的 README、SKILL.md 或文档注释。源文件每次修改后都要再改一处副本，而副本会逐渐过时，表面上看起来却仍在维护。用一个索引页面覆盖这一系列内容，逐行列出每个项目并链接到其源文件；如果仓库有相关脚本，则根据源文件自身的元数据生成。页面只有在能说明任何单个源文件都未说明的内容时才值得保留：各部分如何衔接、如何跨部分完成任务、遇到问题时该怎么办。只有在用户了解此成本后仍提出要求时，才编写一系列镜像页面，并在清单条目的注释中记录这一选择。

来源戳

wikikit 编写的每个页面末尾都有一行：

_Verified against `main`@`a1b2c3d` on 2026-08-06._

这两部分都有其作用。audit 会在 SHA 仍可访问时对比差异；如果 rebase 或 squash-merge 已使其成为孤立提交，则会回退到日期。因此，只要可行，它就会做到精确；不可行时则会降级处理，而不是提供虚假信息。

来源戳表示页面上的每项声明都已核实，且其 SHA 是默认分支上的一条提交。 只有在检查过整个页面、而非仅检查改动涉及的声明后，才能为页面添加来源戳。在功能分支上，已核实的提交尚不存在于默认分支，因此应保留旧来源戳（新页面则不添加），并在交接说明中指出该页面待合并后添加来源戳。合并后，操作人员会在默认分支上为其添加来源戳；在此之前，audit 会持续报告该页面待处理。

没有来源戳的页面并非过时，而是未经核实。 这就是标记已纳入页面的方式：在第 2 阶段找到的页面，会在清单中添加带有 documents: glob 和 adopted: true 的条目，且不添加来源戳。wikikit 可以识别并路由到该页面，但从未核实过其中的任何声明。只有在某次核实流程确实涵盖该页面后，它才会获得首个来源戳。纳入是一种映射操作，并不代表声称由我们撰写了人类编写的正文。

依据：先核实，再撰写

发布前，必须根据代码仓库核实每一项事实声明。 命令必须来自实际的 package.json、Makefile、pyproject.toml 或 justfile；路径必须存在；环境变量必须确实在某处被读取；端点必须确实经过路由。wikikit 无法在代码中找到的功能，不得写入文档。 这是文档集与看似可信的虚构内容之间的分界线，在所有三种模式中都适用。

默认采用静态阅读，它能证明脚本已声明，但不能证明脚本可以运行。因此，wikikit 也可以在每次运行征求一次同意后，执行固定的无副作用探测命令允许列表：

允许	禁止
<command> --help、-h	任何会安装内容的操作（npm install、pip install、brew）
<command> --version、-V	任何会构建、编译或打包的操作
make -n <target>、make help	任何会迁移数据库或填充数据的操作
仅列出脚本（npm run、pnpm run、yarn run、just --list）	任何会部署、发布或推送的操作
只读 git 命令（git log、git diff、git show、git rev-parse）	任何会在文档集之外写入内容或调用在线服务的操作

允许列表在此明确写出，绝不推断。看似无害但不在列表中的命令不会运行，因此应将相应声明报告为未经核实。audit 所说的“只读”是指不写入任何文件，因此也可在其中进行探测；探测在此最能发挥作用。

各种模式

每种模式的正文各自存放在 modes/ 下的一个文件中。根据触发条件选择模式，读取对应的单个文件，并遵循其中的说明。此行之前的所有内容适用于每种模式，不会在模式文件中重复说明。

• 模式 init → 阅读 modes/init.md，然后遵循其中的说明。
• 模式 update → 阅读 modes/update.md，然后遵循其中的说明。
• 模式 audit → 阅读 modes/audit.md，然后遵循其中的说明。
• 模式 publish → 阅读 modes/publish.md，然后遵循其中的说明。

写作标准

区分文档与生成式填充内容的规则：

• 记录意图和用途，把实现细节留给代码。 逐行讲解函数功能的页面，还不如函数本身。
• 只记录仓库当前包含的内容。 仓库里没有的内容，就不该出现在文档里。
• 每页只采用一种 Diátaxis 模式。 操作指南只回答一个目标，把架构内容留给解释页面；解释页面则从头到尾都只做解释。
• 开篇就写出第一句有用的话。 概述文档内容的句子，读者会直接跳过。
• 每条命令都应可直接复制粘贴，并经过验证。 使用真实的标志、路径和名称。
• 操作指南标题应体现任务，例如“部署到 staging”，而不是“部署”。

对于常见的 AI 写作痕迹（过度使用 em dash、机械套用三段式节奏、措辞含糊、夸大宣传），如果已安装，可使用 humankit 进行处理。wikikit 不会重复列出这些内容。

说明

• 发布到 GitHub Wiki 需选择启用，并设有明确限制，不是默认行为。 publish 已存在，但没有任何流程会触发它：工作循环从不建议使用它，而且必须在请求中明确提到 wiki 才会触发。设置限制是因为镜像是破坏性的单向操作，这样 wiki 的编辑按钮才能继续正常工作，而通过它进行的每项编辑都会在下次同步时消失。把 wiki 作为人们撰写内容之处的仓库不应安装此工具；把 wiki 视为 docs/wiki/ 的呈现视图的仓库则可以安装。
• Wiki 始终是下游。 wikikit 从不把 wiki 视为事实来源，从不自动将编辑同步回仓库，也从不对其运行 audit。如果 wiki 与文档集不一致，按定义应以文档集为准。
• 每项操作都需征得同意。 init 映射、新页面、删除操作、README 标记、文档主目录迁移以及探测运行都会征求同意。update 中对现有页面的编辑不会征求同意，因为这些编辑受克制规则限制，并会生成可供审查的差异。audit 除探测外不会征求同意，因为它不会更改任何内容。
• 绝不执行会产生更改的操作。 探测允许列表是固定的，且不会产生副作用。wikikit 绝不会为了验证某项说法而安装、构建、迁移或部署，因此无法验证的说法会标记为未经验证，而不会通过测试将其变为既成事实。
• 不搭建文档站点脚手架。 wikikit 只为已有引擎编写内容并更新导航，不会新增引擎。
• 不写营销文案，不做翻译。 落地页、功能介绍、更新日志和本地化内容均不在处理范围内。
• 遵循现有项目约定。 如果仓库有自己的文档位置、页面命名方式或引擎布局，wikikit 会遵循而不是覆盖，并说明遵循了哪项约定。
• 没有文件系统（例如基于浏览器的 Agent）？将每个页面打印为带有其路径标签的围栏代码块，清单也以同样方式打印，并列出用户应自行运行的探测。绝不要声称已写入实际上无法写入的页面。