核心功能

Wiki

接手一个陌生项目时，最花时间的往往不是写代码，而是搞清楚这个项目是干什么的、主流程怎么跑、模块之间怎么衔接。Wiki 就是让 ZCode 读一遍代码库，把这些整理成一份可以随时查阅的文档。

它的定位是 代码库架构导读，不是产品文档站或使用手册。目录会优先覆盖项目身份、主执行链路、核心模块与子模块、跨端边界、数据与状态流、配置边界、扩展点和风险点，而不是「安装部署」「CI/CD」这类通用栏目。所有结论都带源码位置，可以点击跳回对应文件。

Wiki 会在当前工作区所在的运行环境中扫描代码并保存生成结果，一个工作区一份。生成目录和正文时，ZCode 会将经过安全规则过滤、按需读取的代码上下文发送给你选择的模型服务。

生成

在工作区文件树顶部、仓库名称右侧点 仓库 Wiki 图标进入，它会占据整个主工作区。还没生成过时，中间是一张状态卡，生成前可以配置四项：

工作区文件树顶部、仓库名称右侧的仓库 Wiki 图标入口

找不到入口？ Wiki 图标在文件树面板内部（各平台一致，包括 Windows）。如果没看到，先打开文件树：把鼠标悬停在左侧边栏的工作区条目上，点击出现的文件树按钮展开面板，图标就在顶部仓库名的右侧。远程工作区断开连接、或工作区处于只读状态时，不会显示该入口。

选项	说明
语言	简体中文或英文，默认跟随界面语言
模型	默认用当前工作区的聊天模型。可以临时换一个，不影响聊天设置
生成图表	默认开启。开启后会在图确实能帮助理解、且有源码依据的地方生成架构图、流程图、时序图或状态图
重试次数	单个页面生成失败时自动重试几次，默认不重试

点 生成 Wiki 后，状态条会依次显示 正在分析代码库 → 正在生成目录 → 正在生成页面 → 正在保存 Wiki。

目录生成后即可开始阅读：已完成的页面会立即开放，尚未生成的页面会在目录中显示等待状态。生成过程中可以随时点击停止，已完成的页面会保留下来，之后仍可重新生成或删除。如果部分页面生成失败，目录区域会显示失败数量。

生成中的 Wiki：顶部进度显示 5/12，右上角可随时停止，目录里已完成的页面可点开，未轮到的显示「正在生成」与「等待生成」

界面分两栏：左侧是已打开的项目列表，展开某个项目就能看到它的目录树；右侧是正文。中间的分隔线可以拖动调整宽度，项目列表也可以整个收起；窗口或面板较窄时会自动改成上下堆叠。

顶部显示当前仓库名，下方的 元数据 展开后能看到分支、语言、更新时间、提交 ID 和 Wiki 文件数——用来确认这份 Wiki 对应的是哪个版本的代码。

Wiki 阅读视图：左侧目录树、右侧正文，顶部元数据展开后显示分支、语言、更新时间、提交 ID 与 Wiki 文件数

正文里的每个结论都标注了 源码位置，格式是文件路径加行号区间，点击直接跳到工作区里对应的文件和行。开启图表后生成的 Mermaid 图支持主题适配、缩放和放大预览，单张图渲染失败不会影响正文阅读。

Wiki 不需要你记得手动更新。每轮对话结束时，如果这个仓库已经有 Wiki，ZCode 会检查代码是否真的变了——变了才触发刷新，没变直接跳过。

需要主动重来时，顶部工具栏有 重新生成。它默认沿用上次的模型，也可以为这一次临时换一个。

删除 Wiki 只清理本地内容，随时可以重新生成。

Wiki 的生成结果保存在本机用户数据目录，不写入仓库：

~/.zcode/v2/repo-wiki/<工作区标识哈希>/wiki.json

wiki.json 是纯 JSON 文件，包含全部页面的 Markdown 正文与源码引用（Windows 上位于 C:\Users\<用户名>\.zcode\v2\repo-wiki\ 下）。想让 Agent 直接读取生成结果，把这个文件路径提供给它即可。

「Wiki 模型请求超时（180000ms）」：单次模型请求有 3 分钟的固定上限（不可配置），网络慢或模型服务响应慢时会触发。换用响应更快的模型或稍后重试。
「模型响应缺少文本内容」：常见于第三方部署的模型。Wiki 要求模型把正文放在所选 API 协议的标准文本字段返回；如果模型把内容放进思考字段、返回分块结构、或供应商配置的 API 协议与服务实际协议不一致，就会触发这个错误。建议确认供应商的 API 协议选择正确（目录与页面的工具化生成目前只支持 OpenAI Chat Completions 协议），或换用官方渠道模型。
单页失败不影响整体：某一页重试耗尽后会计入失败数并继续生成其余页面，只有全部页面失败时任务才整体失败。「重试次数」默认为 0，生成不稳定时可调到 2~3。
生成中途退出应用：任务会在下次打开时标记为已停止，已完成的页面保留，可重新生成。

生成时 ZCode 只读当前工作区内的文件，并且用的是 Wiki 专用的阅读视图，与其他功能的文件扫描相互独立。以下内容不会进入用于生成 Wiki 的模型上下文：

.git 目录、依赖目录、构建产物、缓存和本地运行状态文件；
根目录 .gitignore 中符合支持范围的忽略规则所排除的内容；
文件名中包含 token、secret、credential、password 等敏感词的疑似密钥或配置文件（tokenService.ts 这类正常源码不受影响）；
符号链接指向的文件和目录。

模型不会拿到一份预先准备好的文件清单，而是自己按目录逐层展开、按需读取，读取范围始终受上面这些规则约束。