欠了两年的文档债，我让WorkBuddy用30分钟还清了

腾讯云开发者

发布于 2026-07-28 09:52:53

2230

关注腾讯云开发者，一手技术干货提前解锁👇

先说个大部分开发者都不愿承认的事实：杀死一个开源项目的，往往不是代码烂，是没人看得懂它。

你一定见过这种项目。Star 好几千，功能列表看着就香，点进去准备用，结果 README 停在半年前，API 文档只有作者自己看得懂，翻遍仓库找不到一个调用示例。你硬啃了半天源码，默默关掉页面，转头搜了个替代品。那个被你放弃的项目，作者可能根本不知道自己丢了一个用户，还在纳闷：我写得挺好，怎么没人用。

我就是那种作者。而且我欠的债，比大多数人都多。

我维护着 30 个开源仓库，python-office 有 1.3k Star。代码我写得飞起，文档永远是“下次再补”。不是不想写，是真写不动——一个函数三分钟能实现，但要把用法、参数、边界情况写成别人能看懂的文档，得磨半天还写得干巴巴。于是 README 是半年前的，API 说明全在我脑子里，新人想贡献代码连目录结构都得靠猜。

文档债跟技术债一样，越拖利息越高。拖到后来我甚至有点怕看 Issue，十条里六条都在问同一类问题：“这个功能怎么调用” “你这目录结构到底啥意思”。每次回复都像在给两年前的自己填坑。

01

两年的活，它 30 分钟干完，还标了源码出处

转折点是我让 WorkBuddy 扫了一遍 python-office 的源码。

我原本以为顶多能生成个 README 模板。结果它甩回来一整套 160+ 篇的 Wiki——项目概述、快速入门、安装指南、API 参考、核心功能详解、开发者指南、示例大全全齐了。还不止中文，129 篇中文加 32 篇英文，海外用户点进来直接能读。这些活我手写保守估计要两周，它跑完用了 30 分钟。

生成的 wiki 目录树：zh/content 下核心功能、API 参考、开发者指南、示例大全一应俱全

但真正让我产生 Aha moment 的不是它的快，是它没有一句是编的。

我第一反应是怀疑 AI 又在一本正经胡说八道，随手打开一篇「项目概述」，发现每段结尾都标着源码出处，精确到 file://路径#L起始行-L结束行，像论文引用文献一样。我挑了三个路径去仓库里搜，全对得上。它是真读了我的代码，读完再写，写完还告诉你这句话是从哪一行代码得出来的。

生成的文档正文：简介、安装与验证都带可运行代码，每节结尾都有 Section sources 溯源到具体源码文件

图更让我意外。python-office 的对外接口由 office.api.* 统一聚合，往下分发到 popdf、poexcel、poword 等十几个子库，子库再去调 PyMuPDF、openpyxl 这些第三方库。这套依赖关系我跟人解释都得比划半天，它直接画了出来，一张图把三层结构铺得清清楚楚。

架构全景图：用户代码 → office.api.* 聚合层 → 十余个子库 → 第三方依赖库的完整分层

不只是静态结构，连一次调用怎么在各层之间流转、老参数怎么被兼容处理，它都用时序图画了出来。

调用时序图：调用方发起 pdf2docx，API 层检测旧参数触发 DeprecationWarning、映射到新参数，再落到 popdf 执行

一张图的信息密度，顶我写十段文字。而且图片来源也标得清清楚楚，哪张图对应哪段代码一一对得上。

02

Wiki 上线后：Issue 降 60%，新人上手从 2 天到 2 小时

这套 Wiki 上线后，最直接的变化在 Issue 区。

那些问“怎么调用” “目录结构是什么”的 Issue 肉眼可见地少了，降了大概 60%。原因很简单，文档终于比 Issue 先到了。用户遇到问题先翻到文档里的答案，就不用再来问我。我从一个疲于回复的客服，变回了能安心写代码的作者。

新人也是。以前想贡献代码的人光搞懂“加密功能在哪个文件、哪个函数”就得摸索大半天，多半还得来问我。现在他打开开发者指南，从项目概述一路读到 API、再到代码结构，一条链读下来就上手了，onboarding 从两天缩到两小时。

我最在意的其实是维护成本。文档最可怕的不是没有，是过期——写了一版，代码一改就对不上，读者照着做全是坑，还不如没有。而这套东西的逻辑是代码变了重跑一遍就行。文档第一次从负债变成了资产。

03

一个 WorkBuddy Skill 复刻 Wiki

到这儿肯定有人想问：这套 Wiki 到底怎么生成的，我也想给自己的项目补一套。

核心就是 4 步 Prompt，拿到项目照着跑：扫描项目生成「项目概述」→ 生成「快速入门」→ 逐模块生成「API 参考」→ 生成「开发者指南」。每一步都让它按固定骨架写、每段标源码行号、该配图的地方出 Mermaid 图。第一步的「项目概述」是地基，Prompt 大概长这样：

你是项目文档工程师，请阅读本项目全部源码，生成一篇「项目概述」。要求：①顶部列出引用的所有源码文件路径；②章节按简介→项目结构→核心组件→架构总览→组件分析→依赖分析→故障排查→结论→附录；③项目结构和架构用 Mermaid graph TB 画分层，调用链路用 sequenceDiagram 画时序；④每节结尾标源码出处 file://路径#L起止行，每张图后标图表来源；⑤不许编造不存在的文件或函数，所有描述必须基于实际源码。

换个章节名重复跑，全套就出来了。验证也简单：从文档顶部的引用列表随机挑 3 个路径去仓库里搜，都能找到，就说明它真读了你的代码。

但如果你像我一样有 30 个仓库要补，每次手动贴 4 条 Prompt 太麻烦。我干脆把这 4 步封装成了一个 WorkBuddy Skill：

Skill 名称：项目 Wiki 生成器触发词：给这个项目写文档工作流程： 1. 扫描项目目录结构，识别项目的实际分层（如 API 聚合层 / Skills 系统层 / 子库生态） 2. 依次执行 4 步 Prompt：项目概述 → 快速入门 → API 参考 → 开发者指南 3. 每步生成 Mermaid 架构图后，同步生成一张配图（架构关系图 / 调用流程图 / 依赖关系图），保存到 wiki/images/ 4. 每步生成后自动验证：检查文件路径是否存在、Mermaid 图是否渲染、配图是否生成成功 5. 输出到项目的 wiki/ 目录，保持 10 节骨架 + 源码溯源格式

封装完之后，下次拿到一个新项目，我只需要说一句“给这个项目写文档”，它自己跑完 4 步，30 分钟交付一整套 Wiki。反复用的工作流固化成一次触发，这是 Skill 生态最爽的地方——以后再也不用手动复制 Prompt。