文档快照 · CLI 7.30.1 · SDK 2.6.53。Desktop 使用其发行版随附的运行时。命令和示例保留英文原文。英文原文

创建并使用第一个 AX Wiki

开始之前

AX Wiki 将选定的仓库源资料整理成架构和工作流页面。这属于仓库知识，与 AX Code 网站文档不同。请先连接提供方并选择可用模型。生成时会将选定证据发送给该提供方，可能产生使用费用。

在项目文件夹中运行。Git 项目使用最近的工作树根目录，即使从子目录启动也是如此。检查当前检出状态，并决定是否将生成文件纳入版本控制。

预览并生成

规划会预览所选文件和页面，不调用模型。生成前先检查：

ax-code wiki plan

然后使用配置的模型生成内容，验证结果并打开本地阅读器：

ax-code wiki generate
ax-code wiki doctor
ax-code wiki viz --open

默认输出目录为 .ax-wiki/，从 .ax-wiki/quickstart.md 开始阅读；.ax-wiki/.manifest.json 记录来源和哈希。生成过程可能更新 AGENTS.md 中的 Wiki 指引块；使用 --skip-agents 可跳过这一步。请检查生成的差异。

阅读并提出有效问题

先阅读快速入门页，查看其引用文件，并询问工作流在哪里实现。查看器展示页面、引用和记录的关系。按 Ctrl+C 停止前台 CLI 查看器。

使用 Wiki 确定方向，再检查当前代码和测试。精确符号、调用方和引用应使用代码智能工具或 LSP。页面处于最新状态，并不能证明覆盖完整、内容正确或运行性能。

保持更新

源代码改变后，更新受影响页面并检查健康状态：

ax-code wiki update
ax-code wiki status
ax-code wiki doctor

即使 Wiki 不存在，状态命令也可能成功退出；请查看报告的存在与健康状态。过期或不健康的输出需要排查。CLI 查看器展示固定快照，更新后请重新打开。

当前 TUI 版本中，/wiki-viz 会打开查看器并请求维护。交互式空闲维护默认启用；前台工作优先。无界面运行不会启用该调度器。

控制生成过程

将以下可选设置合并到项目 ax-code.json。把模型 ID 换成连接中可用的 ID。此示例关闭后台维护，同时保留显式执行的命令：

{
  "wiki": {
    "enabled": true,
    "auto": false,
    "model": "provider/model"
  }
}

显式指定 --model provider/model 会覆盖本次运行的 Wiki 模型。对于推理模型，Wiki 生成需要可识别的低强度或关闭推理控制；如果该策略拒绝请求，请换用其他受支持模型。

维护者笔记应放在保护块中，以便更新时保留：

<!-- AX-WIKI:PROTECTED:START project-note -->

Deployment requires maintainer review.

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

问题恢复

没有模型或身份验证失败：检查提供方权限和配置的 Wiki 模型。聊天模型可用，并不保证另一个 Wiki 模型也可用。
超时或构建中断：查看 ax-code wiki doctor 和 .ax-wiki/.build-report.json，解决原因后重试。验证过的暂存页面可能被复用；构建失败并不表示全部页面已发布。
手动编辑冲突：将笔记保存在保护块内，重试前检查变更。--force 允许替换保护块外的编辑；请明确意图后使用。

后续操作

Wiki 配置、CI 与故障排查 · 查看器与离线导出 · 模型选择 · 文档首页