arno
5f2964bf68
按主题分三组归档：Agent 工程纵深（经验治理/循环工程/ Token 成本治理/溯源生成）、最弱环节定律（推理链窃取/ GLM-5.3-Flash 开源）、人机共进（意志稀缺/数字员工化/ 大学之问）；每组配 4K 题图与 160x90 缩略图共 3 组， 昇腾 WAIC 纯图片一文无法文本化按先例未收录
109 lines
7.7 KiB
Markdown
109 lines
7.7 KiB
Markdown
# 欠了两年的文档债，我让WorkBuddy用30分钟还清了
|
||
|
||
> **来源**：微信公众平台（腾讯云开发者）
|
||
> **作者**：晚枫
|
||
> **发布日期**：2026-08-27
|
||
> **原文链接**：https://mp.weixin.qq.com/s/8xSZw_ErYSGnXVt3-bIkKA
|
||
|
||
---
|
||
|
||
先说个大部分开发者都不愿承认的事实：杀死一个开源项目的，往往不是代码烂，是没人看得懂它。
|
||
|
||
你一定见过这种项目。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。
|
||
|
||
## 04
|
||
|
||
__你欠的债，不该让用户来还__
|
||
|
||
AI 时代代码越来越不值钱，因为谁都能让 AI 写。真正卡住一个项目的反而是文档。你的 Star 可以一直涨，但点进来的人看不懂、用不起来，那些 Star 就只是数字，用户在你看不见的地方一个个走掉。
|
||
|
||
写文档从来不是手上的活，是"把一个项目讲给别人听"的脑力活——读完整个项目、理清三层架构、生成一整套带溯源的中英双版 Wiki，这件事以前只能我自己硬扛，现在它替我干完了。
|
||
|
||
所以如果你也攒了一屁股文档债，别再拖了。你可以继续欠着，但这债，你的用户和新贡献者不该替你还。
|
||
|
||
作者简介
|
||
|
||
__晚枫__
|
||
|
||
腾讯云架构师名人堂专家，全网 40w+ 粉丝 AI 博主；python-office 开源项目作者（GitHub Star 1300+）
|
||
|
||
-End-
|
||
|
||
原创作者｜晚枫
|