用 Zread 为复杂仓库生成可读项目文档

接手一个陌生仓库时，最先卡住的往往不是某段代码看不懂，而是不知道从哪里开始看：入口在哪、模块怎么分、哪些目录是主业务、哪些是构建产物。Zread 是一个从代码生成文档的命令行工具，它把当前工作区读一遍，产出一套可浏览的项目文档，从整体结构到模块细节都能落到页面上。它适合三类人：刚接手新仓库需要快速建立全局认识的开发者、要给已有项目补一份 Wiki 或文档视图的维护者、以及做项目复盘和交接时需要一份可读材料的人。需要说明的是，Zread 不替代读代码，它的价值在于先给你一张地图，让你知道该往哪里下钻。站内可参考 Zread 的工具条目了解入口信息。

本文按实际操作顺序展开：先讲安装与登录，再讲生成与浏览两条主命令及其参数，然后给出一个从零跑通的最小示例，最后重点处理复杂仓库——尤其是 App、前端、后端揉在同一个仓库里的情况，应该怎么选运行目录、怎么拆文档粒度。文中涉及的命令参数以你本机实际安装的版本为准，版本号、模型可用性、配额与计费规则请以官网当前信息为准。

准备工作

确认命令已安装并可用

Zread 以命令行形式使用，安装完成后需要让当前终端能加载到它的可执行文件。新开一个终端后先加载 shell 配置：

source ~/.zshrc

然后确认命令存在、并看一眼帮助信息：

zread version
zread --help

如果提示找不到命令，先检查 PATH：

echo $PATH

常见的情况是安装目录没有进 PATH。如果安装走的是 npm 全局目录，需要确保 shell 配置里有类似这样一行：

export PATH="$HOME/.npm-global/bin:$PATH"

改完配置后重新 source ~/.zshrc，再用 which zread 确认解析到的路径是否正确。

准备模型服务的访问凭据

Zread 生成文档需要调用模型服务，因此必须先完成一次登录配置。这里有一个容易踩的坑：Zread 的登录和你终端里已有的 GitHub 登录状态不是一套东西。你已经在终端里登录过 GitHub，并不代表 Zread 已经可用；Zread 需要单独执行一次 zread login 或 zread login --custom。

根据你手里的凭据类型，准备的东西不同：

使用 Zread 内置支持的模型服务（例如 Z.AI、BigModel 等体系内的账号或订阅）：准备好对应账号即可，走默认登录流程。
使用官方 OpenAI API Key 且接口地址就是官方地址：准备好 API Key 与模型名。
使用 OpenAI 兼容的中转、代理或网关服务：需要同时准备 API Key、Base URL、模型名 三项，缺一不可。

如果手里只有网页登录态——比如只有 GitHub 登录态，或者只有 Codex / ChatGPT 的网页登录状态——通常不能直接让 Zread 工作。网页登录态不是标准 API Key，Zread 需要的是可调用的 API 凭据。中转方案还额外要求你能提供 Base URL 和模型名。

操作步骤

第一步：登录并选择 provider

首次使用先执行登录：

zread login

登录菜单里通常会出现一组 provider 选项，例如 BigModel.cn Coding Plan (CN)、Z.AI Coding Plan (Non-CN)、BigModel.cn (CN)、Z.AI (Non-CN)、OpenAI、OpenRouter、Moonshot(Kimi)、MiniMax、自定义。选择原则可以按凭据来源判断：

用官方 Z.AI / BigModel 账号：选对应的官方项。
用官方 OpenAI API Key：优先选 OpenAI。
用 OpenAI 兼容的中转 Key：优先选「自定义」。
不确定 provider，但手里有 Base URL + API Key + Model：优先选「自定义」。

登录命令还有两个常用变体：

zread login --custom
zread login --model <模型名>

--custom 会跳过模型服务菜单，直接进入手动配置 API Key 的流程；--model 用于在登录完成后自动选择某个模型。

第二步：用 --custom 手动填写配置

中转 Key、代理 Key、OpenAI 兼容网关 Key 都应该走自定义流程，因为这类服务通常需要你手动指定 Base URL。执行：

zread login --custom

按提示填写三项内容，格式大致如下：

Provider: custom
API Key: 你的key
Base URL: 你的中转地址/v1
Model: 你的模型名

填写时有几个细节必须注意：

Base URL 通常写到 /v1 为止，不要写成具体接口地址。写成 /v1/chat/completions 这类完整路径是常见错误。
Base URL 要带 https:// 协议头，只写域名会失败。
模型名必须是当前 provider 或中转平台真实支持的名字，不能凭感觉填。不同 provider 的模型命名可能完全不同，中转平台也可能使用自己定义的模型别名。模型名写错时，即使 API Key 正确，也可能登录成功但生成文档失败。

第三步：验证配置是否打通

登录或配置完成后，最直接的验证方式是拿一个小项目跑一次生成：

cd /path/to/project
zread generate -y

如果命令能正常开始生成，说明登录与模型配置基本已经打通。如果此时仍提示找不到命令，回到前面重新 source ~/.zshrc。

第四步：在项目根目录生成文档

Zread 的核心工作方式是「基于当前工作区生成文档」，所以必须先进入目标项目目录再执行。第一遍建议在仓库根目录跑，不要在 src/、app/、pages/ 这类子目录里直接跑：

cd /path/to/your/project
zread generate

常用参数如下：

zread generate -y
zread generate --skip-failed
zread generate --draft resume
zread generate --draft clear
zread generate --draft cancel

参数	作用
`-y`, `--yes`	跳过确认提示，直接开始生成
`--skip-failed`	某些页面生成失败时跳过失败页面，先提交剩余文档
`--draft resume`	继续未完成的草稿或生成任务
`--draft clear`	清空草稿，重新开始
`--draft cancel`	取消本次草稿处理

第五步：浏览生成的文档

文档生成后，在项目目录中启动浏览：

zread browse

常用参数：

zread browse --generate
zread browse --port 9681
zread browse --host 0.0.0.0
zread browse --version <version-id>

参数	作用
`--generate`	当前还没有文档时，直接触发生成流程
`--port`	指定浏览端口
`--host`	指定监听地址
`--version`	打开指定版本，或显示版本选择

第六步：查看配置与更新工具

需要确认当前配置时执行：

zread config

需要升级工具本身时执行：

zread update

一个完整示例

下面是从零开始、对一个项目生成并浏览文档的最小流程。假设项目位于 /path/to/project，并且你使用的是需要手动填写 Base URL 的中转服务。

1. 加载环境并确认命令可用

source ~/.zshrc
zread version

2. 登录并手动配置模型服务

zread login --custom

按提示填写：

Provider: custom
API Key: sk-xxxxx
Base URL: 你的中转地址/v1
Model: 你的模型名

3. 进入项目根目录生成文档

cd /path/to/project
zread generate -y

4. 打开文档浏览

zread browse

如果此时还没有生成过文档，也可以一步到位：

zread browse --generate

5. 如果中途被打断，继续未完成的任务

zread generate --draft resume

如果只是部分页面失败、但你更想先拿到一个能看的版本：

zread generate --skip-failed

如果代码结构已经改动很大、怀疑旧草稿不可信：

zread generate --draft clear

跑完这一套，你应该已经能在浏览器里看到这个项目的文档视图，并且知道中断后该用哪个参数恢复。

复杂仓库：按两层生成文档

复杂项目的关键不在于有没有更复杂的命令，而在于选对运行目录和拆对文档粒度。Zread 并没有为复杂项目准备隐藏参数，能调整的就是你在哪个目录执行、执行几次。

先判断项目属于哪一类

常见的复杂结构包括：Monorepo，一个仓库里有多个应用或服务；App + 后端 + 管理后台在同一个仓库；App、前端、服务端各自一个目录；微服务仓库，多个服务并列；以及代码量大、依赖多、目录层级深的一般性大仓库。

总原则：根目录总览 + 子项目细化

推荐的做法是分两层：先在仓库根目录跑一遍，拿到全局架构视图；再进入关键子项目分别跑，拿到子系统深度文档。这通常比只在根目录跑一次更实用。

假设仓库结构大致如下：

repo/
  app/
  web/
  admin/
  server/
  docs/
  package.json

第一步，在仓库根目录生成总览：

cd /path/to/repo
zread generate -y
zread browse

这一遍的目标是看清整个仓库有哪些子系统、App / Web / Admin / Server 之间的大致关系，以及入口文件、共享模块、公共配置在哪里。它能回答的问题包括：这个仓库整体是干什么的、哪些目录是主业务、哪些模块彼此依赖、哪一块值得继续深入。

第二步，对关键子目录分别生成：

cd /path/to/repo/app
zread generate -y
zread browse

cd /path/to/repo/web
zread generate -y
zread browse

cd /path/to/repo/server
zread generate -y
zread browse

分开跑的好处是文档焦点更集中、单次生成的上下文更干净、更容易看清某一端内部的模块划分，比在超级大仓根目录里硬看所有细节更高效。

第三步，把两份文档结合起来读。 先看根目录生成的文档理解全局结构，再看各子项目的独立文档，最后回到代码里验证关键调用链。这套方法特别适合回答这类问题：App 调的是哪个后端接口、Web 和 Admin 是否共用组件或接口层、Server 的哪一层在服务 App 和 Web、登录支付消息上传这类跨端能力放在哪。

Monorepo 场景

典型结构：

repo/
  apps/
    mobile/
    web/
  packages/
    ui/
    utils/
  services/
    api/

先在根目录跑一次：

cd /path/to/repo
zread generate -y

然后按关注点继续：

cd /path/to/repo/apps/mobile
zread generate -y

cd /path/to/repo/apps/web
zread generate -y

cd /path/to/repo/services/api
zread generate -y

各层用途不同：根目录用来看工程组织方式，apps/mobile 用来看 App 业务结构，apps/web 用来看前端页面与状态管理，services/api 用来看接口、服务层与数据流。

App 仓库里内嵌前后端能力

有些移动端项目同时包含原生代码、H5 / Hybrid 页面、本地桥接层、BFF 或 mock 服务脚本。建议先在 App 根目录生成一次，再针对 android/、ios/、hybrid/、mock/ 或 server/ 子目录分别跑。原因是原生层和前端层的关注点差别很大，分开跑更容易把桥接关系、资源依赖、页面容器职责看清楚。

后端有多个微服务

如果 server/ 下还有多个微服务，不建议只在 server/ 跑一遍就结束，更实用的方式是逐个服务生成：

cd /path/to/repo/server/service-a
zread generate -y
cd /path/to/repo/server/service-b
zread generate -y

这样更适合做单服务职责理解、单服务接口排查和服务间依赖复盘。

注意事项

命令找不到

报错形如 zsh: command not found: zread，原因通常是当前终端还没加载 ~/.zshrc，或者 PATH 里没有 ~/.npm-global/bin。先 source ~/.zshrc，再 which zread；仍不行就 echo $PATH 确认是否包含 $HOME/.npm-global/bin。

登录成功但生成失败

如果 zread login 看起来完成了，但 zread generate -y 仍然失败，常见原因有：登录时选错了 provider；配置了错误的模型；API Key 虽然保存了但没有实际权限；Base URL 或模型名不匹配。排查顺序建议是：先确认 provider 选得对不对，再确认中转 Key 是否应该走「自定义」，最后确认模型名是不是该 provider 真正支持的名字。

401 与 403 的区别

401 Unauthorized 通常表示 API Key 错误、过期或未生效；403 Forbidden 表示有 Key，但没有访问当前模型或当前接口的权限。排查方向包括：Key 是否输错、Key 是否属于当前 provider、模型是否超出权限范围、账号是否真的开通了对应服务。使用中转 API 时，还要检查中转服务是否仍然有效，以及它是否对来源、模型、并发或额度做了限制。

模型不可用

出现 model not found 或模型不可用，通常是模型名拼错、模型名不是 provider 支持的真实名字，或者账号没有该模型权限。处理方式是回到你使用的 provider 或中转平台确认模型的真实名称，不要凭感觉填。

Base URL 填错

这是 --custom 最容易出错的地方。正确写法一般写到 /v1 为止并带 https://；常见错误是写成 example.com/v1 这种缺协议头的形式，或者写成 /v1/chat/completions 这种完整接口路径。

只有网页登录态

GitHub 登录不是 Zread 的 API 授权，Codex / ChatGPT 的网页登录态也不是标准 API Key。只有网页登录态一般不够用，真正可用的是 API Key；如果是中转方案，还需要 Base URL 和 Model 一起配齐。

中转 Key 配好仍不通

如果已经选了「自定义」仍然失败，逐项检查：这个中转是否真的兼容 OpenAI 接口；Base URL 是否写到了 /v1；模型名是否与中转支持的一致；这个 Key 是否还有额度；中转站是否对来源 IP、接口类型或模型做了限制。

生成中断或失败

登录没问题但生成过程失败时，按场景选参数：被中断后先试 --draft resume；只想先拿到可用结果，试 --skip-failed；草稿脏了或代码结构变动很大，再试 --draft clear。

大仓库跑不动或结果太乱

现象是生成太慢、文档信息量太大、看不出真正的主业务。原因通常是仓库太大，且混合了 App、前端、后端、脚本、文档和构建产物。处理方式是先根目录跑一次只看全局拓扑，再进入关键子项目分别跑。

快速区分登录问题还是项目问题

最简单的判断方法：先在一个小一点的项目目录执行 zread generate -y。如果小项目都跑不通，优先怀疑登录或配置问题；如果小项目能跑、大项目不顺，优先怀疑项目体量或目录选择问题。

如何提高生成质量

项目本身越清晰，生成结果通常越好。建议仓库尽量具备这些内容：根目录有 README；子模块目录名清晰，不要全是缩写；关键配置文件保留在仓库中；接口定义、环境说明、启动方式尽量可见；不要把核心逻辑都藏在过度动态的脚本里。复杂项目尤其建议在根目录补一份仓库结构说明，标清各子项目职责、哪些目录属于 App / 前端 / 后端 / 共享层，以及登录、订单、支付、消息这类核心链路的位置。

关于费用与版本

Zread 本身没有明确写出永久免费的登录方案。如果使用 --custom，是否免费取决于你接入的模型服务是否提供免费额度——关键不在 Zread，而在你使用的模型平台。模型可用性、计费方式、配额与版本行为都可能变化，请以官网当前信息为准。