本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

AX Wiki 仓库知识库

状态：生效
范围：当前状态
最近审阅：2026-10-03 负责人：AX Code 运行时

AX Wiki 是 AX Code 原生的仓库维基编译器。它把已跟踪的源码、配置、测试、工作流和现有文档，编译成位于 .ax-wiki/ 下的小型、以源码为据的 Markdown 知识库。它使用与 AX Code 相同的提供方配置和模型路由；没有单独的可执行文件或凭据存储。

ax-code wiki viz 绘制已编译页面及其引用的文件。该地图的截图见 Wiki 证据可视化。

它适合什么

Wiki 正文是编译出来的导航层，不是结构证明。若 Wiki 与代码不一致，以代码为准，并运行 ax-code wiki update。

快速开始

连接一个 AX Code 提供方，然后运行：

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki 会生成 AGENTS.md，插入 AX Wiki 指针块，并在同一工作流中编译 Wiki。使用 --wiki-only-agents 可在不调用模型的情况下添加指针。

命令

生成选项包括 --model provider/model、--dir <relative>、--quiet、--skip-agents 和 --force。要手工替换受保护区段之外被编辑过的生成内容，必须有意提供 --force。

仓库目录

自 v7.22.2 起，默认输出目录是 .ax-wiki/。隐藏前缀表明这是由 AX Code 维护的仓库知识。它不会让文件被 Git 忽略：请自行决定是否提交这些知识，或把 /.ax-wiki/ 加入仓库的 .gitignore。

使用 wiki.dir，在 ax-code.json 或 --dir docs/knowledge 中选择另一个相对目录；CLI 标志优先。所有生成、状态、智能体指针、后台维护和可视化都使用该选择。编译器不会自动检测、移动或合并较旧的 ax-wiki/ 目录。包名与生成器名称、ax-wiki.config.json 和 ax-wiki.instructions.md 保持不变。

生成契约

AX Wiki 写入 Markdown 页面和 .ax-wiki/.manifest.json。每个页面的 frontmatter 包含：

• generated_by: ax-wiki
• 一段简明的 summary
• 由有证据支持的生成返回的精确 symbols
• 用于编译该页面的、相对于仓库的 sources

清单存储确定性计划哈希、仓库源哈希、页面哈希、生成模型、git 修订和生成时间。页面以原子方式写入；清单最后写入，且仅在完整的内存候选通过校验之后。

源发现优先使用 Git 的已跟踪且未被忽略的文件列表，排除生成目录、构建目录、第三方目录以及 Wiki 自身，跳过二进制或过大的文件，并拒绝仓库之外的路径或符号链接。

子系统导航

默认计划保留快速开始、架构和开发页面。超出单页源文件数量或证据字节预算的模块，还可以获得聚焦页面，例如 modules/core/src/session.md。这些页面覆盖该模块 src、lib 或 app 目录下的直接子目录，每个子系统至少三个代码文件，且模块中至少有两个合格子系统。

子系统页面包含其实现子树，以及模块 test 或 tests 目录下的匹配文件。其生成说明会要求入口点、运行时流程、边界、具体变更位置和相关测试。模块页面把最多两个测试文件紧接在排名最高的源之后，以便测试能参与有界的证据选择。

默认总预算仍为 12 页，其中包括三个概览页。模块概览与子系统页面按源文件数量竞争剩余名额；子系统仅在其父概览入选之后才会被纳入。因此较大的子系统可以挤掉较小的包页面。用 ax-code wiki plan 预览结果。提高 maxPages（自动计划最多 40），或在某个子系统需要保证覆盖时配置显式的 pages。显式计划保持权威，且不会再获得自动子系统页面。

这改善了导航和证据聚焦；它并不核验生成的正文，也不保证智能体会阅读 Wiki。在依赖实现细节之前，请顺着引用回到当前源码。

智能体如何使用 Wiki

智能体通过三种方式到达 Wiki，从最省到最具体：

1. 提示索引。 当存在健康的 Wiki 时，会话提示会携带一段简短的 <repo_wiki> 块：Wiki 位置、新鲜度标签，以及每页一行（路径和截短的摘要，默认 12 页大约 750 个 token）。摘要只用来定位该读哪里；它们不是证明。
2. repo_wiki 工具。 一个只读工具，有三种操作：index（带每页新鲜度的页面卡片）、read（一页及其引用的源、哪些被引源已变化，以及这些源中找不到的任何 frontmatter 符号），以及 related（按符号、正文提及或源路径查找页面）。它在完整和编码工具配置档中可用，并使用 read 权限。
3. 通用文件工具。 read、glob 和 grep 作用于 .ax-wiki/ 时仍然有效。

提示新鲜度按页判断：只要某页引用的每个源仍与清单哈希匹配，该页就是新鲜的。新增或编辑了没有任何页面引用的文件时，提示标签保持 fresh，并附加说明 Wiki 尚未覆盖它。被引用的源发生变化时，标签变为 stale，提示会要求智能体仅把 Wiki 当作导航。ax-code wiki status 和 wiki lint 保持更严格的全仓库判定，任何新增、删除或编辑的合格文件都会使结果过期。

Wiki 从不替代源码：每个 read 结果都会列出需要对照核验的文件；若页面与代码不一致，以代码为准。

增量更新与手工内容

wiki update 将当前源哈希与清单比较，并通过每页的选择器映射变更。计划变更会重新生成所有计划页面；否则无关页面保持不动。

生成的正文归编译器所有。把持久的维护者文本放在受保护块内：

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

受保护正文在重新生成后仍然保留。除非提供 --force，否则 AX Wiki 拒绝覆盖其他手工编辑。过时的生成页面仅在其受管内容未改变且不含受保护区段时才会被删除。

配置

在项目 ax-code.json 中配置该集成：

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include、exclude、maxSourceBytes 和 maxPageSourceBytes 控制证据发现与预算。instructions 添加项目特定的编译器指引。若要完全策展计划，配置 pages 条目，并带上 path、title、purpose 和 selectors；显式计划必须包含 quickstart.md。

generationConcurrency 接受 1 或 2。原生云端生成默认同时发起两次页面调用；本地引擎和 CLI 提供方默认为一次。当提供方会排队或限制重叠请求时，将其设为 1。调度不会使现有页面内容失效。除非提供此设置，可复用包保持串行。

每个模型页面最多有两次分类尝试，共享 180 秒截止时间。相对 Wiki 链接会在页面被接受之前对照页面计划检查；断链响应可以使用剩余尝试来修复该页。最终校验和手工内容守卫仍会在发布前运行。

中断的构建会把已校验结果保留在 .ax-wiki/.page-cache/（或配置的 Wiki 目录）中。后续构建仅在检查当前源证据、计划、生成器、模型和先前内容之后，才会复用匹配的结果。初次生成在完整候选通过校验之前保持未发布。成功发布会移除已消耗的暂存条目；其后显式的 wiki generate 仍会重新生成所有页面。缓存条目有界且受权限门控；损坏或无法访问的条目会被忽略。

.build-report.json 把模型生成的页面和缓存页面，与实际已发布的 written 页面区分开。其可选的 pages 数组记录每页的尝试次数、时长、提示/源字节大小，以及提供方给出时的确切 token 用量。失败或取消的构建不报告已发布页面。

你也可以把编译器指引放在 ax-wiki.instructions.md，把核心引擎配置放在 ax-wiki.config.json。在两者都提供时，显式的 AX Code 运行时设置会覆盖核心配置。

默认的交互式维护

在 AX Code TUI 中打开项目，默认会启用后台 Wiki 维护。项目空闲 30 秒后，缺失的产物会被生成，过期的产物会增量更新。忙碌或重试中的会话、排队的工作以及非空草稿优先，并会取消后台生成。适用当前智能体的读/写权限；只读智能体不会生成。此后台工作流不会改写任何智能体说明文件。

使用 "wiki": { "auto": false } 禁用后台维护，或使用 enabled: false 禁用编译与提示注入。auto 默认为 true，且不写入配置。它使用已配置的 Wiki 模型或 AX Code 默认模型，作业截止时间为 10 分钟，最多三次带退避的自动尝试。显式的图谱请求或源/配置变更允许再试一次。无头运行和 CI 不会启用交互式调度器。非 Git 目录需要显式请求。在 Git 项目中，Wiki 的生成与消费使用最近的工作树根，因此在某个包内打开 AX Code 不会创建单独的包 Wiki。

会话侧栏和 /wiki-viz 会立即打开本地进度页并请求维护。快照就绪后，该页显示已记录的 Wiki 页面/源关系。见 Wiki 可视化。

智能体路由

当存在健康的 Wiki 且 wiki.enabled 不是 false 时，会话提示会收到精简的 <repo_wiki> 协议。它告诉智能体从快速开始入手，只加载相关页面，通过被引文件核验重要主张，并对结构问题使用图谱/LSP 工具。

healthy 描述 Wiki 目录、索引和清单是否存在。单独的 freshness 字段为 fresh、stale 或 unknown。状态与会话路由使用生效的包含/排除和大小设置来比较当前源哈希，因此能检测到未提交的编辑、新增和删除。检查不会复用缓存的新鲜判定；它们以有界的读取并发扫描合格源。缺失或已禁用的 Wiki 会跳过源扫描。新鲜度是某一时刻的源检查，不是对每条生成主张或每个页面的校验；产物校验请使用 lint。

过期或未核验的 Wiki 仍可用于导航，并带有明确指示：在依赖实现主张之前先核验当前原始源码。核验错误会产生 unknown。当不存在 Wiki 目录时，wiki status 以 0 退出（缺失的 Wiki 就是报告）。存在 Wiki 时，若 Wiki 不健康或新鲜度不是 fresh，它会以失败退出。

Wiki 证据是有界的：每个被选源在页面预算内最多贡献其前 32,000 字节，截断会标记给生成器。GraphContext 可以添加选定片段，但每个片段限制为 80 行。这些导航辅助并不保证保留每一个被改函数或必需守卫；范围审查所需的原始代码请另行提供。

受管理的 <!-- AX-WIKI:START --> 块位于 AGENTS.md 中，承载相同的路由策略，而不把 Wiki 内容复制进仓库说明。

CI

在已通过提供方认证的作业中先运行 ax-code wiki update，再运行 ax-code wiki lint，然后打开一个文档 PR。见 examples/ax-wiki-update.yml。把生成的 Wiki 变更当作其他文档一样对待：审阅源引用，避免自动合并模型输出。

故障排除