用 Zread 为代码仓库生成并读取 Wiki 文档

面对一个几万行、目录结构陌生的代码仓库，逐个文件翻源码是最慢的路径。Zread 提供的思路是：先用大模型把整个仓库读一遍，生成一套 Wiki 风格的文档，之后无论是人还是 AI 代理，都直接读这套文档来理解代码库。它由两部分组成——一个名为 zread 的命令行工具，以及它在磁盘上留下的产物目录 ./.zread/wiki/。前者负责生成与预览，后者才是真正被反复消费的东西。

这套工具适合几类人：刚接手一个陌生仓库、需要快速建立架构认知的开发者；要给项目补一份模块级说明文档的维护者；以及把 Zread 当作工具调用、需要结构化输出的 AI 代理或脚本作者。它不替代代码阅读，也不做静态分析或安全审计，它做的事情是把代码翻译成可浏览的说明文字。

准备工作

运行环境与工作目录

Zread 是一个命令行程序，所有命令都应当在工作区根目录执行。产物路径 ./.zread/wiki/ 是相对于当前工作目录的，如果你在子目录里执行 zread generate，生成的文档就会落在那个子目录下，后续读取时容易找不到。养成先 cd 到仓库根目录再执行的习惯。

工具本身通过 npm 生态分发，安装方式与常见的 CLI 一致。安装完成后可以用版本命令确认可用性：

zread version --stdio

具体支持的 Node 版本、安装包名与最新版本号，请以官网当前信息为准，这里不做过期承诺。

账号与登录

生成文档需要调用大模型，因此必须先解决凭据问题。Zread 提供两种途径：

OAuth 登录：执行 zread login，会打开浏览器完成授权，成功后写入 ~/.zread/login.json。这个文件存在，就说明当前机器已经登录过。
自备 API Key：在全局配置文件 ~/.zread/config.yaml 中填写 llm.api_key，同时可以指定模型提供方。

判断是否具备生成条件，最直接的办法是检查这两个位置：~/.zread/login.json 是否存在，或者 ~/.zread/config.yaml 里是否已有 llm.api_key。两者都没有时，先跑 zread login。

zread login 还支持 --custom 与 --model 两个参数，用于接入自定义的模型服务与指定模型名称。由于 login 会拉起浏览器做 OAuth，在无图形界面或非交互环境（CI、容器、远程会话）里不要贸然执行，除非使用者明确要求。

全局配置

配置文件位于 ~/.zread/config.yaml，主要承载三类信息：LLM 提供方、生成语言、并发度。修改它有两种方式——直接编辑文件，或者用命令进入编辑流程：

zread config --stdio

生成语言这一项值得在第一次使用前就确认好，因为它决定了产出的 Wiki 页面用哪种语言书写，事后修改需要重新生成。

日志位置

当某次运行失败却没有明显报错时，去看日志：~/.zread/log/zread.log。这是排查静默失败的第一现场。

操作步骤

第一步：判断是否已有现成产物

在动手生成之前，先看一眼 ./.zread/wiki/current 是否存在。这个文件里只有一行文本，内容是当前生效的版本 id，形如 2026-03-12-010203。如果它存在，说明这个仓库已经生成过文档，直接读磁盘上的文件即可，完全不需要再调用 CLI。

读取顺序是固定的：

打开 ./.zread/wiki/current，拿到版本 id。
打开 ./.zread/wiki/versions/<id>/wiki.json，这是目录（TOC）文件。
按 wiki.json 里 pages[*].file 给出的文件名，逐个读取 ./.zread/wiki/versions/<id>/<file>。

注意不要用 zread browse 去做这件事。browse 是给人看的浏览器预览，程序化读取应当直接操作文件。

第二步：理解 wiki.json 的结构

wiki.json 是整个知识库的骨架，字段含义如下：

字段	说明
`id`	版本 id，与 `current` 文件内容一致
`generated_at`	生成时间
`language`	文档语言
`pages`	页面数组，每一项描述一个页面

pages 数组里每一项包含 slug、title、file、section、group、level。其中 file 是页面 Markdown 的相对文件名，section 与 group 决定页面在目录树中的归属，level 表示层级深度。想快速定位「某个模块的说明在哪一页」，靠 title 与 section 过滤即可，不必读全文。

第三步：生成文档

确认没有现成产物后，执行生成：

zread generate -y

-y / --yes 的作用是跳过目录确认环节。如果不加这个参数，命令会在生成目录（catalog）之后停下来等待人工确认，这在无人值守场景下会一直卡住。所以只要是非交互执行，-y 是必带的。

生成是一个耗时过程：它会调用大模型，在大型仓库上可能跑上几十分钟。启动前应当与使用者确认，尤其是在不熟悉的目录里——它会产生真实的 token 消耗。

第四步：处理草稿与中断

生成过程中，中间状态写在 ./.zread/wiki/drafts/。这个目录存在，就意味着上一次运行没有跑完。其中 drafts/wiki.json 在目录阶段完成后就会出现。

面对残留草稿，必须显式选择一种处理方式，否则命令会弹出交互提示：

# 接着上次的进度继续
zread generate --draft resume -y

# 丢弃草稿，从头开始
zread generate --draft clear -y

还有一个 --draft cancel 取值，用于取消草稿。规则很简单：只要草稿可能存在，就把 --draft 写清楚，不要让命令自己去问。

第五步：跳过失败页面

大仓库生成时，个别页面可能因为内容过长或模型返回异常而失败。如果不想因为少数几页卡住整个流程，加上：

zread generate -y --skip-failed

这样失败的页面会被跳过，其余页面正常产出。事后可以对照 wiki.json 的页面清单，看哪些内容缺失。

第六步：本地预览

想在浏览器里翻阅生成的文档：

zread browse

如果此时还没有任何 Wiki 产物，可以加 --generate 让它先生成再打开：

zread browse --generate

其他可用参数包括 --version <id>（指定查看某个历史版本）、--host 与 --port（控制监听地址与端口）。需要固定端口或从其他机器访问时，用后两个参数指定，不要依赖默认值。

第七步：用 --stdio 做程序化调用

所有命令都支持 --stdio。加上它之后，进程不再输出 ANSI 终端界面，而是变成一条基于标准输入输出的 JSON 行协议。任何从脚本或其他程序里驱动 Zread 的场景，都应当使用这个模式，而不是去解析 TUI 画面。

zread generate -y --stdio

协议中的事件类型包括 waiting_for、done、quit 等。waiting_for 表示命令在等待外部输入，调用方需要据此回应；done 表示本次操作结束；quit 用于退出。完整的报文格式定义在技能包的 references/stdio-protocol.md 中，凡是需要程序化驱动 Zread 的场合，都应当先读这份说明再动手。

第八步：更新 CLI

需要升级工具本身时：

zread update

这个命令会就地替换 zread 二进制文件，且难以回退。只在明确需要时执行，不要把它塞进自动化流程里顺手跑。

一个完整示例

下面走一遍从零到读到内容的完整路径，假设当前位于一个尚未生成过文档的仓库根目录。

1. 确认凭据

ls ~/.zread/login.json

如果文件不存在，先执行 zread login 完成浏览器授权；或者改为在 ~/.zread/config.yaml 中配置 llm.api_key。

2. 检查是否有残留草稿

ls ./.zread/wiki/drafts/

目录不存在，说明是干净状态，可以直接生成。

3. 生成

zread generate -y --skip-failed

等待命令结束。若中途失败，先看 ~/.zread/log/zread.log。

4. 读取版本号

cat ./.zread/wiki/current

输出类似 2026-03-12-010203，这就是本次生成的版本 id。

5. 读取目录

cat ./.zread/wiki/versions/2026-03-12-010203/wiki.json

从返回的 JSON 中取出 pages 数组，按 section 分组浏览 title，找到你关心的模块。

6. 读取具体页面

cat ./.zread/wiki/versions/2026-03-12-010203/<pages 中某一项的 file 值>

页面内容是 Markdown，直接阅读即可。到这一步，整个仓库的架构说明、模块划分与关键流程都已经在磁盘上，后续提问、写文档、做代码评审都可以基于这些文件展开，不必再让模型重新爬一遍源码。

7. 需要浏览器视图时

zread browse --version 2026-03-12-010203 --port 8080

指定版本与端口后打开浏览器查看。

注意事项

成本与耗时

generate 会消耗真实的 LLM token，在大型仓库上可能持续数分钟到数十分钟。启动前确认，不要在不熟悉的目录里默认开跑。具体计费方式与额度以官网当前信息为准。

写入范围

generate 只写入 ./.zread/ 目录，不会向 git 提交任何内容。这意味着产物默认是本地文件，是否纳入版本管理由使用者自行决定。也正因为写入范围受限，卡住时直接删除 ./.zread/wiki/drafts/ 就能恢复，不会影响仓库其他部分。

非交互执行的三个要点

generate 必须带 -y，否则会停在目录确认环节。
草稿可能存在时，必须显式给出 --draft resume|clear|cancel，否则会弹交互提示。
从脚本或代理调用时，一律加 --stdio，拿 JSON 而不是终端画面。

不要做的事

不要用 zread browse 去读取已有文档内容，直接读文件更快也更可靠。
不要在非交互环境里执行 zread login，它会拉起浏览器。
不要随手执行 zread update，它就地替换二进制且难以回退。
不要解析 TUI 输出，--stdio 就是为此准备的。

公开仓库的读取方式

对于已知的公开 GitHub 仓库，如果环境里提供了 mcp__zread__* 系列工具（如 get_repo_structure、read_file、search_doc），优先用它们来读取结构、文件与检索文档，而不是在本地跑 CLI 重新生成。本地 CLI 更适合私有仓库或需要离线产物的场景。

触发时机

判断是否该用 Zread，看的是意图而不是字面关键词。当需求是「理解、上手、梳理、概览一个陌生代码库」「要架构文档、项目 Wiki、仓库导览、模块说明」「这个仓库是干什么的」，或者要生成、重新生成、续跑、浏览、本地预览代码文档时，都适用。反过来，在深入一个大型未知仓库之前，先检查 ./.zread/wiki/current 是否存在：存在就读现成页面，不存在再考虑生成。