ENZOMEGA.
Clipping 微信公众号

AI编程实践第12节：使用Zread生成项目Wiki知识文档，让AI和人类理解

by 爱海贼的无处不在 原文 ↗
Created: 2026-05-24
#公众号文章

公众号名称：无处不在的技术

作者名称：爱海贼的无处不在

发布时间：2026-05-24 21:34

持续内容输出，点击蓝字关注我吧

01

前言

来看一段AI大模型对它的介绍

在 AI Coding、Agent 开发、自动化编程逐渐普及的今天，代码仓库正在经历一个非常明显的问题：

代码越来越多，但“理解代码”的成本却越来越高。

很多团队都有这样的体验：

  1. 新成员接手项目，需要花几天甚至几周熟悉目录结构；

  2. AI 工具虽然能写代码，但对项目上下文理解有限；

  3. README 越来越长，但真正能帮助理解系统架构的信息却很少；

  4. 历史项目缺少系统化文档，只能靠“口口相传”；

  5. 大型开源项目结构复杂，阅读源码像在“考古”。

而这也是为什么近一年，“AI Wiki”“代码知识库”“Repo to Docs”开始成为新的开发趋势。

在之前的AI编程实践文章中，我也分享过一种方式和提示词来生成一些业务架构知识文档、术语文档、开发规范文档、业务模型文档，之前的那套我个人和公司也一直在用，用下来的效果也是不错的。对于新人的快速理解项目的成本非常有帮助。

本节分享一下智普提供的Zread Cli工具，他可以帮助我们完成项目WIKI文档的梳理建设，它做的事情非常直接：

把代码仓库自动转化为适合“人类阅读 + AI 理解”的 Wiki 知识文档。

不仅仅是生成 README，而是真正从项目结构、模块职责、代码逻辑、架构关系等维度，构建一个可阅读、可导航、可搜索的知识体系。

对于 AI Agent、Claude Code、OpenClaw、Codex 等工具来说，这种结构化知识文档尤其重要。

因为 AI 最怕的不是“不会写代码”，而是：

“不知道这个项目到底是怎么组织的。”

而 Zread 的价值，本质上就是：

  1. 降低项目理解成本

  2. 降低 AI 获取上下文的成本

  3. 提高团队知识传递效率

  4. 让遗留项目重新具备可维护性

  5. 让代码仓库从“源码集合”升级为“知识系统”

02

正文

首先来看下Zread Cli是什么？Zread CLI 官方文档 对它的描述非常明确：

一个用于本地仓库工作流的 AI 文档生成工具。

它可以直接扫描本地项目目录，然后自动生成：

  1. 项目概览

  2. 架构说明

  3. 核心模块解析

  4. 目录结构说明

  5. 团队约定

  6. API/代码逻辑理解

  7. Wiki 文档导航

最终形成一个类似“项目百科”的知识系统。这点其实特别关键。因为现在很多项目已经不仅仅是给“开发者”看的了。还需要给ClaudeCode之类的各种AI工具看。为 AI 编程工具提供更清晰的上下文

接下来我们开始安装一下，安装的过程非常简单，执行NodeJS的安装命令即可：

npm install -g zread_cli

我用的是Mac系统，截图如下：

Windows系统也是OK的。

想用 Zread 时，直接进入仓库目录执行 zread 即可。CLI 会根据当前状态提示下一步，例如登录、生成文档或打开已有文档。

接下来，我们基于开源项目MyBatis的源码来进行分享，下载下：https://github.com/mybatis/mybatis-3

下载后解压到自己的目录。

接下来，我们输入自己的zread命令，在当前目录下：

第一步，我们选择中文界面，然后在第2步中，可以选择自己的模型Key，这个工具默认是智普的Key，我们可以使用自己的，这里建议用高级模型，或者合适的模型，例如DeepSeekV4，我这里用的是我个人购买的MiniMax模型：

配置MiniMax模型：

当我们配置完成的时候，会显示登录成功，如下所示：

接下来，我们可以选择生成文档，开始生成项目，如下：

当单击了生成文档后，这个工具首先会帮助我们规划一个目录：

接下来这个工具开始每个章节的帮助我们生成项目的wiki文档，我们耐心等待即可。

例如，生成的第一节文档，包括了架构设计图：

核心组件的解析说明：

效果也是非常好的。等待1小时左右，我这里生成了MyBatis的Wiki文档，接下来，我们输入zread browse命令，会自动打开浏览器：

接下来，我们就可以从浏览器中看到这个网页风格的WIKI文档：

我们可以根据自己喜欢的内容进行阅读。这里我们用的是业务组件，其实对于企业中的业务系统也同样的有帮助，接下来我这里开源的商城系统CRMEB Java来进行分享，假设，我们现在是新入职的员工，那么我们可以先通过这个工具，来帮助我们实现自己的WIKI文档生成，项目的目录如下：

接下来，我们可以切换到这个项目的根目录下，然后执行zread命令，继续生成我们的文档，当我们输入命令后，这个工具首先帮助我们规划了如下目录：

默认情况下，最大并发数量为1，我们可以通过zread config命令进行修改：

这里生成这个的时候，我又更改为了小米最新的2.5pro的模型，同时设置了4个并发的线程，速度加快了：

接下来我们等待即可。

常见的命令如下：

zread generate为当前目录生成项目文档。

zread browse在浏览器打开当前项目已生成的文档。

zread login登录账号或配置 API key。

zread config查看或修改 CLI 配置。

zread update更新 CLI 到最新版本。

zread version查看当前 CLI 版本。

我们可以通过zread browse命令，启动浏览器进行预览，查看网页的结果，这个非常不错。

生成完成后，文档会保存在项目目录下的 .zread/ 中：

.zread/
state.json
wiki/
current
versions/
2026-03-12_1015_f3a91e/
2026-03-15_1314_ab12cd/
drafts/

  1. .zread/wiki/current：当前版本文档

  2. .zread/wiki/versions/：历史版本文档

  3. .zread/wiki/drafts/：生成完成前的草稿文档

这样可以方便团队直接读取当前文档，也能在需要时回看历史版本。团队成员安装 Zread CLI 后，都可以在浏览器中查看同一份项目文档，这对内部仓库、未开源项目和 onboarding 场景都更合适。

通过这样的操作AI 可以直接读取仓库知识，而不是只能“盲读源码”。

我觉得 Zread 最厉害的一点其实是：它在做“代码知识压缩”。

大型项目最大的问题不是没有代码。而是：

  1. 信息太分散

  2. 认知负担太重

  3. 理解链路太长

比如一个新人想理解系统：

通常需要：

README

→ docs

→ issue

→ commit

→ 架构图

→ 源码

→ 老员工

而 Zread 做的事情是：

用 AI 把这些信息重新组织成“可阅读知识”。

这其实已经不是简单文档生成。

更像：

  1. 项目知识提炼

  2. AI 知识索引

  3. Repo 语义化

  4. Codebase Understanding

zread的配置文件位于 ～/.zread/config.yaml，通过 zread config 交互式编辑，主要选项：

选项说明

界面语言：en（英文）或 zh（中文）

文档语言：生成内容使用的语言，留空时跟随界面语言

LLM 提供商：选择内置提供商或填入自定义 BaseURL

最大并发数：同时生成的页面数，建议 2–5

最大重试次数：页面生成失败时的自动重试次数

一些常见问题如下：

成过程中断了，可以续写吗？

可以。再次运行 zread generate，选择”续写草稿”即可从中断处继续，已完成的页面不会重复生成。

文档存在哪里？会上传到云端吗？

文档保存在项目目录的 .zread/wiki/ 下，完全本地存储，不会上传到任何服务器。

支持哪些编程语言？

Zread 通过 AI 理解代码语义，理论上支持任何编程语言，实际效果取决于所用模型的代码理解能力。

如何查看历史版本文档？

每次生成会保留历史版本。运行 zread browse —version 打开版本选择器。

为什么我认为 Zread 很适合 AI Agent 时代？

过去的软件开发是：

人 → 阅读代码 → 修改代码

而现在逐渐变成：

AI → 理解项目 → 生成代码

人 → 审核与协同

问题来了：

AI 怎么理解项目？

目前大多数 AI Coding 工具仍然依赖：

  1. 当前文件

  2. 少量上下文

  3. RAG 检索

  4. 临时 Prompt

但真正缺少的是：

“系统级项目认知”。

而 Zread 这种 Wiki 化能力，本质上是在构建：

Code → Knowledge → AI Context

这一步。

所以我认为：

未来所有大型项目，都会逐渐出现：

  1. AI Wiki

  2. Repo Knowledge Graph

  3. Project Memory

  4. Agent Documentation Layer

而 Zread 正在往这个方向走。

03

总结

Zread CLI 并不是一个简单的“README 生成器”。它真正解决的是：“如何让复杂项目变得可理解”。

包括：

  1. 让新人更快上手

  2. 让团队知识更容易沉淀

  3. 让遗留系统重新可维护

  4. 让 AI 更理解代码仓库

  5. 让 Agent 真正具备项目级上下文

尤其在 AI Coding 快速发展的今天：“代码本身”已经不再是最稀缺的资源。

真正稀缺的是：

  1. 项目知识

  2. 架构理解

  3. 上下文语义

  4. 系统认知

而 Zread 正在把这些东西，从隐性的“经验”，转化为显性的“知识 Wiki”。

对于个人开发者来说，它能帮助你快速理解陌生项目。对于团队来说，它能降低知识传递成本。对于 AI Agent 来说，它可能会成为下一代“代码理解基础设施”。一个 AI 与人类共同阅读的知识系统。

喜欢本文的，可以关注、收藏、点赞、转发、分享到朋友圈哦。

本专题系列文章：

VibeCoding实践第1节：字节Trae实现简历与简历生成器

AI编程实践第2节：Spec规范驱动开发(SDD)1024游戏

AI编程实践第3节：Trae实现Web管理后台界面，效果出奇好

AI编程实践第4节：基于GPT5+Trae实现MCP服务市场

AI编程实践第5节：Trae梳理解构项目业务与代码流程

AI编程实践第6节：秒哒开发微信表情包生成应用

AI编程实践第7节：Git WorkTree机制实现分支并行开发

AI编程实践第8节：使用Understand Anything理解项目关系图谱

AI编程实践第9节：阿里秒悟与谷歌Stitch平台实现需求界面原型设计

AI编程实践第10节：B端C化，使用GPT-Image-2.0设计重构系统UI界面

AI编程实践第11节：使用代码图谱codegraph降低模型Token消耗

最近也看到有人问如何学习AI，这里分享几个资料如下：

1、通往AGI之路的知识库飞书云文档

https://waytoagi.feishu.cn/wiki/QPe5w5g7UisbEkkow8XcDmOpn8e

2、掘金的AI知识库的飞书云文档

https://agijuejin.feishu.cn/wiki/UvJPwhfkiitMzhkhEfycUnS9nAm?table=blk3RfZtR7Nh73tO

3、极客时间的AI知识库的飞书云文档

https://geek-agi.feishu.cn/wiki/B9rYwwg6xidZYJkbrlscxTQFnOc

4、LangGPT社区的飞书云文档（结构化提示词等等）

https://langgptai.feishu.cn/wiki/RXdbwRyASiShtDky381ciwFEnpe

5、一站式AI产品经理飞书知识库

https://v11enp9ok1h.feishu.cn/wiki/KiIvwdFOciiqqNkwKzTcmn88ndL

6、微软网站分享的AI指南说明知识

https://learn.microsoft.com/zh-cn/azure/databricks/generative-ai/guide/introduction-generative-ai-apps

7、赋范空间的飞书AI知识库：

https://kq4b3vgg5b.feishu.cn/wiki/ETqzwH4THiTY8kkGqAucYbSonPt

8、Marked的AI产品经理知识库

https://qqs7y1hozd1.feishu.cn/wiki/KVLtwsHdsiCLBfkumZpclY8ansd

- END -

喜欢的可以加入我的免费知识星球：觉醒的新世界程序员

喜欢的也可以关注我的公众号：​无处不在的技术​，与我一起学习成长、共同进步，在技术的道路上越走越远。

喜欢就点个 在看****呗 👇1

Original 爱海贼的无处不在 无处不在的技术

内容效果不满意？点此反馈

输入关键词开始搜索