zread

zread 技能

zread 是一个 CLI，可使用大模型根据当前工作区中的代码生成 wiki 文档。输出内容位于工作区下的 ./.zread/wiki/；公开仓库也可以在 https://zread.ai 上查看。

此技能供 Agent 使用。请直接从磁盘读取生成的文件；运行任何 zread 命令时，都默认使用 --stdio 模式，而不要尝试解析面向用户的 TUI。

磁盘布局（请直接读取这些文件）

始终从工作区根目录运行 zread。生成成功后：

• ./.zread/wiki/current — 包含当前版本 ID 的文本文件（例如 2026-03-12-010203）。
• ./.zread/wiki/versions/<id>/wiki.json — 目录：{id, generated_at, language, pages: [{slug, title, file, section, group, level}]}。
• ./.zread/wiki/versions/<id>/<file> — pages[*].file 引用的页面 Markdown 文件。
• ./.zread/wiki/drafts/ — 进行中的生成任务；如果此目录存在，表示上一次运行未完成。目录阶段完成后会生成 drafts/wiki.json。
• ~/.zread/config.yaml — 全局配置（LLM 提供商、语言、并发数）。
• ~/.zread/login.json — 此文件存在表示用户已登录。

若要回答有关已有 zread 输出的代码库问题，请使用文件工具直接读取这些文件——不要调用 zread browse。

命令

命令	用途	关键标志
zread generate	为当前工作目录生成 wiki	-y/--yes、--draft resume|clear|cancel、--skip-failed、--stdio
zread browse	在 http://localhost:9681+ 提供文档并打开浏览器	--generate、--version <id>、--host、--port、--stdio
zread login	登录 BigModel/Z.AI OAuth 以获取 API 密钥	--custom、--model、--stdio
zread config	编辑 ~/.zread/config.yaml	--stdio
zread update	自行更新 CLI	--stdio
zread version	打印版本	--stdio

所有命令均支持 --stdio，该标志会让进程通过 stdin/stdout 使用 JSON 行机器协议。线格式（事件、waiting_for、done、quit）请参阅 references/stdio-protocol.md。从其他程序/Agent 调用 zread 时，请加载此文件。

AI Agent 决策树

1. 用户想阅读现有 wiki 内容？

   • 检查 ./.zread/wiki/current。如果存在，直接读取 wiki.json 和页面 Markdown。无需调用 CLI。
   • 对于已知的公开 GitHub 仓库，优先使用 mcp__zread__* 工具（get_repo_structure、read_file、search_doc），而不是运行 CLI。

2. 用户想（重新）生成文档？

   • 先向用户确认——generate 运行时间较长、会调用大模型并写入文件。在不熟悉的目录中操作时，务必取得明确同意。
   • 确认 ~/.zread/login.json 存在，或 ~/.zread/config.yaml 中设置了 llm.api_key。如果两者都没有，先运行 zread login。
   • 如果 ./.zread/wiki/drafts/ 存在，请决定：
     • 继续上一次运行 → zread generate --draft resume -y
     • 丢弃并重新开始 → zread generate --draft clear -y
   • 否则：zread generate -y。
   • 若要避免因少数失败页面而中断：添加 --skip-failed。

3. 用户想在浏览器中查看文档？

   • 运行 zread browse（若 wiki 尚不存在，则添加 --generate 以创建初始内容）。

4. 用户想编写 zread 脚本 / 以编程方式使用输出？

   • 使用 --stdio 并遵循 stdio-protocol.md。不要从屏幕抓取 TUI 内容。

非交互式调用规则

• 无人值守运行 generate 时，始终传入 -y；否则命令会停在目录确认关卡。
• 草稿可能存在时，始终显式设置 --draft，以免命令提示确认。
• 从其他 Agent/脚本运行任何命令时，使用 --stdio，使输出成为可解析的 JSON，而不是 ANSI TUI 帧。
• zread 会将日志写入 ~/.zread/log/zread.log——如果运行悄无声息地失败，请读取此文件。

安全性 / 影响范围

• generate 会消耗大模型 token（产生实际费用），并且在大型仓库中可能运行数分钟。启动前请确认。
• generate 只会在 ./.zread/ 下写入内容，不会向 git 提交任何内容。可以安全删除 ./.zread/wiki/drafts/，以从卡住的状态中恢复。
• update 会原地替换 zread 二进制文件，且难以回滚——仅在用户明确要求时运行。
• login 会打开浏览器进行 OAuth；除非用户已提出要求，否则不要在非交互环境中运行。

参考文件

• references/stdio-protocol.md — 每个命令的 --stdio 模式共用的 JSON 行线协议。以编程方式驱动 zread 时加载。