兰 亭 墨 苑

标题 *

URL 别名 *

内容 * (支持 Markdown 格式) # 当 AI 开始维护 AI 系统：WeClaw 704 个函数自解释工程实践 > 记录一次人机协作的完整预演：2026 年 8 月 26 日，11 个并行 AI 子代理在一个小时内为 weclaw 项目补齐了全部 704 个源码函数的中文详细注释，覆盖 100%，全量测试通过。这不是一次普通的文档整理——被维护的对象本身就是一个编排 AI 的系统，而维护者也是 AI。本文完整复盘这场实践的动机、编排方法、四次真实意外与处置过程，以及它对"AI 时代软件维护"这件事的预演意义。 ## 一、一个"AI 系统"的双重身份 weclaw 是什么？它跑在一台 Linux 小主机上，通过逆向的微信 iLink 协议接入消息，把用户在微信里说的话路由给 Claude Code、Codex、Gemini 等 AI Agent 执行，再把结果发回微信。换句话说，**它本身就是一个调度 AI 的系统**——一个常驻进程里养着多个 AI 子进程，处理它们的会话恢复、工具调用、失败重试。 于是这场实践有了一层递归意味：**用 AI 去维护一个"用来运行 AI 的系统"**。给 `acp_agent.go` 写注释的子代理，正在理解的恰恰是"如何管理另一个 AI 子进程的生命周期"；它在为自己的同类写说明书。 这层身份带来了一个实际问题：这类系统的注释，读者到底是谁？传统答案是"接手代码的下一个人"。但在这类项目里，还有第二个读者——**下一个被派来改代码的 AI**。当维护工作越来越多地由 AI 执行，注释就不再只是人文关怀，而是机器可读的系统描述，是未来任何自动化维护的前提基础设施。 ## 二、起点：一份精确到个位数的债务清单 动手之前先盘点。项目约 93 个 Go 文件、932 个函数（含测试），其中**非测试源码文件 50 个、函数 704 个**。这 704 个函数中，相当一部分只有一行英文签名式注释（如 `// NewCronStore creates a new CronStore.`），大量内部函数完全没有注释。 债务的特点很典型： - 最难的文件最缺注释——`messaging/handler.go`（97 个函数）里的 singleflight 懒启动模式、`api/server.go`（114 个函数）里的流式反代包装，这些真正的架构精华处往往一片空白； - 已有的英文短注释只回答"是什么"，不回答"为什么存在"和"和谁协作"； - 微信 iLink 协议层、AES-128-ECB 加密上传这类逆向得来的知识，只存在于作者的脑子里，代码里几乎无迹可寻。 人工补齐这份债务的代价可以估算：读懂 3 万行代码再写出合格注释，即使是最熟悉代码的作者本人，也是以周计的工作量。这正是第一块试金石——**这种规模同质化的机械+理解混合型劳动，恰好是并行 AI 的主场**。 ## 三、编排：11 个子代理的分工艺术 整个执行只有一个总指挥（主会话）和 11 个一次性施工队。分工原则有三条： **第一，按包切分、按文件确权。** 每个子代理拿到一张明确的文件清单，清单之间零交集。这是多代理协作的第一铁律：编辑冲突不是概率问题而是时间问题，唯一可靠的解法是让冲突在物理上不可能发生。最大的两个文件——97 个函数的 handler.go 和 114 个函数的 server.go——各自独占一个代理。 **第二，规范前置，不留解释空间。** 下发的指令里写死了：只加注释零逻辑改动；中文撰写；每个函数必须包含功能、意义、关系三要素；复杂代码块必须有行内注释（锁策略、协议细节、重试逻辑）；禁止碰 `_test.go`；包级注释由谁负责也逐个指定（避免两个代理同时改 package 子句上方的注释块）。 **第三，自验证是交付的前置条件。** 每个代理改完必须自己跑完 `gofmt -w` + `go build ./...` + `go vet` + 对应包的测试，全绿才算完成。这条规定后来被证明救了两次场（见下节）。 主会话则保持一种克制的姿态：不插手具体写作，只通过 git diff 监控进度、抽查质量样本、对停滞者发出催办。 ## 四、失控与收拢：真实发生的四种意外 预演的价值在于意外的真实。这场实践出现了四次偏差，每一种都有代表性。 **意外一：AI 引入的编译错误，被另一个 AI 的验证拦截。** api/admin.go 和 messaging/handler.go 先后出现过重复的函数声明——某代理在插入注释时把 `func handleDsProxyLogs(...)` 的签名行复制了两份。发现它们的不是人，而是兄弟代理的交付前验证（`go build` 直接红）。处置很轻：删掉重复行即可。这说明"自验证门槛"不是形式主义——它把错误拦截在了交付之前，而不是等集成时爆炸。 **意外二：静默停滞的施工队。** 负责媒体链路（9 个文件）的代理完成 5 个后连续三轮对剩余文件零进展。主会话通过消息队列发了催办——第一催之后 workflow.go 完成了，第二催之后代理彻底活过来，把剩下三个小文件全部交付。教训是：**并行施工队需要看板式的进度监控和主动催办机制**，等待不会带来进展。 **意外三：一次险些发生的接管冲突。** 催办两轮无效后，主会话决定亲自接管剩余文件，刚读完 attachment.go 就发起编辑——结果收到"文件已被修改"的拒绝。检查 git diff 才发现：代理恰好在那一秒开始写入。如果当时强制覆盖，就是一场自己人和自己人的编辑事故。处置：立即撤手。这条经验值得写进任何多代理协作手册——**接管前必须确认对方真的死了，而确认方式是看它的输出是否还在增长**。 **意外四：验证链路本身的单点故障。** 收尾阶段的截图目检依赖视觉模型，恰好赶上后端超时，人工复核环节被迫挂起。自动化检查（四视口包含性检测）依然全绿地完成了它的部分。这提醒我们：验证体系要区分"机器可判定的"和"需要人眼/大模型的"，后者要有降级预案。 ## 五、验收：不信任，只审计 所有代理报告完成后，进入统一验收。这里的原则是**不采信任何代理的自我汇报，只用独立证据说话**： 1. **格式与编译**：`gofmt -l` 全仓清零、`go build ./...` 通过、`go vet` 无警告； 2. **行为不变性**：`go test ./...` 全量测试套件八个包全部 PASS——这是"零逻辑改动"承诺的最终裁判； 3. **覆盖率审计**：写了一个十几行的扫描脚本，逐文件统计每个 `func` 声明的前一行是否为注释块。首轮扫出 700/704，四个漏网之鱼（两个入口函数、一个 error 接口实现、一个 init）手工补齐后复扫，**704/704，100%**； 4. **质量抽查**：跨包抽取七个样本人工评读——ilink 的协议包注释、CDN 加密的五步密钥链路、CLI 会话恢复机制、脱敏规则优先级等，全部达到"新手只看代码就能理解"的标准。 最终数字：50 个源文件 + 2 个新增的包级架构说明（doc.go），3533 行注释增量，单次提交推送上线。 ## 六、这次实践真正预演了什么 抛开数字，这场实验说明了三件更长远的事。 **其一，软件维护的成本曲线被改写了。** 传统认知里，注释债务是"应该做但永远排不上优先级"的事，因为人力成本太高。当一个 704 函数的注释工程可以在一小时内由 11 个并行代理完成、且质量经得起审计，这笔账的计算方式就变了——**欠债的理由消失了**。可以预见，"注释覆盖率 100%"会从奢侈品变成 AI 时代项目的默认状态。 **其二，人的角色完成了从施工到监理的迁移。** 整场实践里，人做的事情是：定义任务边界、设计分区方案、制定验收标准、监控进度异常、在关键时刻决定"再等等还是接管"。没有写一行注释。这五件事恰好是工程管理者的核心技能——**AI 时代的开发者不是被取代了，而是被推到了更高杠杆的位置**。前提是你得懂技术：不知道 singleflight 是什么，就无法判断代理写的注释是不是在胡说。 **其三，注释的读者变了，代码的"可维护性"定义也随之改变。** 过去评价注释好坏的标准是人能不能读懂；现在还要加上一条——AI 能不能借此准确建立系统全貌。这次实践中，子代理们之所以能正确写出"这个函数被 handler 和 api 双方调用"这样的关系描述，正是因为它们读了足够多的上下文；反过来，这批注释又将成为下一个 AI 改动者最好的路标。**为 AI 写的文档最终服务于人，为人写的文档也在滋养 AI**——两者的利益在这场实践里完全一致。 ## 七、可复用的操作手册 把这次实践沉淀成五条可直接套用的要点： 1. **按文件确权分区**，宁可将大文件单独派一个代理，也不让两个代理共享任何文件； 2. **规范写进任务书**，三要素、语言、禁改范围、跳过范围一次说死，不留自由发挥空间； 3. **自验证作为交付门槛**，让每个施工队在提交前自己跑通构建与测试，错误就地拦截； 4. **独立审计替代信任**，覆盖率用脚本扫、行为不变性用测试套件判、汇报只作参考不作证据； 5. **停滞要有催办，接管要有确认**——催办走消息队列，接管前先看对方输出时间戳是否还在前进。 ## 结语 这场实践最有意思的瞬间，是那个"险些接管"的时刻：主会话以为施工队已经死亡，伸手要接管文件，却被系统告知——文件刚刚被修改过。那一刻很像老练的工程师正要推翻下属的工作，抬头却发现对方还在键盘上奋笔疾书。 知道什么时候该等、什么时候该催、什么时候该亲手接管，以及每次都拿出独立的证据来做验收——这套判断力，就是人机协作时代工程师的新基本功。WeClaw 的 704 个函数只是这次预演的舞台，真正的产出是这套流程本身：**它证明了"AI 开始维护 AI 系统"不只是口号，而是一条已经被走过一遍、踩过坑、且能复走的路。**

配图 (可多选)

标签