当 AI 开始维护 AI 系统：WeClaw 704 个函数自解释工程实践

记录一次人机协作的完整预演：2026 年 8 月 26 日，11 个并行 AI 子代理为一个 Go 项目补齐了全部 704 个源码函数的中文详细注释，覆盖率经程序化审计达到 100%，全量测试通过。这不是一次普通的文档整理——被维护的对象本身就是一个编排 AI 的系统，而维护者也是 AI。本文完整复盘这场实践的动机、编排方法、四次真实意外与处置过程，以及它对"AI 时代软件维护"这件事的预演意义。

一、一个"AI 系统"的双重身份

weclaw 是什么？它跑在一台 Linux 小主机上，通过逆向的微信 iLink 协议接入消息，把用户在微信里说的话路由给 Claude Code、Codex、Gemini 等 AI Agent 执行，再把结果发回微信。换句话说，它本身就是一个调度 AI 的系统——一个常驻进程里养着多个 AI 子进程，处理它们的会话恢复、工具调用、失败重试。

它的完整链路长这样：

人 → 微信 → WeClaw → Agent 调度 → Claude/Codex/Gemini → 工具执行 → 结果反馈 → 人  

于是这场实践有了一层递归意味：

AI Agent → 维护 WeClaw → 解释这套 Agent 调度系统本身  

用 AI 去维护一个"用来运行 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 加密上传这类逆向得来的知识，只存在于作者的脑子里，代码里几乎无迹可寻。

这里需要先纠正一个提法：我们要做的不是"注释工程"。给函数写备注只是表象，真正在建的是一层"代码语义资产"——把代码、架构、上下文、设计意图固化成人与 AI 都能消费的形式。这层资产过去被叫作注释，往往被当作可有可无的附属品；在这场实践里，它是唯一的交付物。下文沿用"语义资产化"的说法。

三、时间线：从理解债务到自解释系统

整场实践发生在一天之内，前接一次线上加固，后接一次全量审计。把时间轴摊开，现场感会清晰很多：

时间	事件
Day −1 夜	先解决真问题：OpenAI 兼容端点的四处加固（流式响应不再被超时掐断、请求体上限、按客户端分桶限流、错误结构标准化），当晚部署并冒烟通过
Day 0 早	部署验证收官后转向债务：盘点出 50 文件 / 704 函数，写下三要素规范与分区方案
Hour 1	11 个子代理一次性并行开工；四大意外中的三个在这一小时内陆续登场
Hour 1.5	停滞代理被两度催办唤醒；两处重复签名被兄弟代理的编译验证就地拦下
Hour 2	最后一个代理交付；独立审计首轮扫出 700/704
Final	四个漏网手工补齐，复扫 704/704；全量测试绿灯，单次提交推送

注意这条时间线的结构：人的动作集中在两端——开头定义任务与分区，结尾做审计与验收；中间最长的一段，是纯粹的机器时间。

四、编排：11 个子代理的分工艺术

整个执行只有一个总指挥（主会话）和 11 个一次性施工队。分工原则有三条：

第一，按包切分、按文件确权。 每个子代理拿到一张明确的文件清单，清单之间零交集。多 Agent 软件工程的第一原则由此而来：空间隔离优先于冲突解决。多个 AI 同时修改同一个文件时，冲突不是概率问题而是时间问题；与其事后设计复杂的合并与仲裁，不如让冲突在物理上不可能发生。最大的两个文件——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 才发现：代理恰好在那一秒开始写入。如果当时强制覆盖，就是一场自己人和自己人的编辑事故。处置：立即撤手。这条经验值得写进任何多代理协作手册——接管前必须确认对方真的死了，而确认方式是看它的输出是否还在增长。

这个瞬间还有一个更深的象征：它暴露了人类对 AI 工作状态的认知滞后。过去的直觉是"机器还没开始"；现在的现实是"AI 可能已经在另一个上下文里工作"。谁拥有这个文件？谁正在修改它？哪个 Agent 的状态报告可信？这些问题今天靠人盯 git diff 回答，明天会成为 AI IDE 和 Agent 操作系统的内置能力——工作区所有权与 Agent 状态可视化，是被这次事故提前点名的产品需求。

意外四：验证链路本身的单点故障。 收尾阶段的截图目检依赖视觉模型，恰好赶上后端超时，人工复核环节被迫挂起。自动化检查（四视口包含性检测）依然全绿地完成了它的部分。这提醒我们：验证体系要区分"机器可判定的"和"需要人眼/大模型的"，后者要有降级预案。

六、验收：不信任，只审计

所有代理报告完成后，进入统一验收。这里的原则是不采信任何代理的自我汇报，只用独立证据说话：

Agent Report ≠ Truth。
Test Result = Truth。Audit Result = Truth。Runtime Behavior = Truth。

落到操作上：

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 行语义资产增量，单次提交推送上线。

值得强调的是这条原则的适用边界：Agent 越强，外部验证越重要，而不是越不重要。 能力弱的代理犯错一眼可见；能力强的代理犯错往往裹着流畅自信的表达。信任必须建立在测试、审计、运行时行为这些独立证据上——这是 AI 时代的软件治理第一性原理。

七、高潮：从 Copilot 到 AI Engineer 的三代演进

把这场实践放回更大的坐标系，能看到软件工业正在发生的一次代际迁移：

第一代：人写代码，AI 辅助。 Copilot 模式。人是唯一的作者，AI 补全括号和样板代码。责任模型简单：代码是人写的，人负全责。

第二代：人设计架构，AI 实现。 当前主流的 Agent 模式。人定义任务、拆解边界、制定规范；AI 以团队或流水线的方式完成实现。WeClaw 平时的开发就是这个形态——人写需求，AI 施工。

第三代：AI 维护 AI 生成的系统，人负责治理。 系统的大部分代码由 AI 写就，此后的理解、修改、文档、回归也由 AI 完成；人的职责收缩为三件事：定义目标函数、掌握验收标准、行使最终否决权。

难的是判断自己在坐标系的哪里。WeClaw 这次实验恰好卡在第二代向第三代的过渡带上：AI 已经完整执行了"维护"的全流程（理解代码、撰写文档、互相验证、修复彼此的错误），但每一个关键决策——做什么、做到什么标准、何时算完成——仍然由人签发。

过渡带的标志不是 AI 能写多少代码。是这三个问题的答案：

当它停滞时，有没有机制发现？（有——进度监控加催办）
当它犯错时，有没有体系兜底？（有——兄弟代理验证加全量测试）
当它声称完成时，有没有独立证据？（有——覆盖率脚本加运行时行为）

三个问题都有答案的那天，第三代就算真正到来。这次实验的价值，是把三个"还没有"变成了三个"有"。

八、可复用的操作手册

把这次实践沉淀成五条可直接套用的要点：

1. 按文件确权分区，宁可将大文件单独派一个代理，也不让两个代理共享任何文件；
2. 规范写进任务书，三要素、语言、禁改范围、跳过范围一次说死，不留自由发挥空间；
3. 自验证作为交付门槛，让每个施工队在提交前自己跑通构建与测试，错误就地拦截；
4. 独立审计替代信任，覆盖率用脚本扫、行为不变性用测试套件判、汇报只作参考不作证据；
5. 停滞要有催办，接管要有确认——催办走消息队列，接管前先看对方输出时间戳是否还在前进。

结语

这场实践最有意思的瞬间，是那个"险些接管"的时刻：主会话以为施工队已经死亡，伸手要接管文件，却被系统告知——文件刚刚被修改过。那一刻很像老练的工程师正要推翻下属的工作，抬头却发现对方还在键盘上奋笔疾书。

知道什么时候该等、什么时候该催、什么时候该亲手接管，以及每次都拿出独立的证据来做验收——这套判断力，就是人机协作时代工程师的新基本功。WeClaw 的 704 个函数只是这次预演的舞台，真正的产出是这套流程本身：它证明了"AI 开始维护 AI 系统"不只是口号，而是一条已经被走过一遍、踩过坑、且能复走的路。

第一代已经结束，第二代正在发生。而我们刚刚在第二代里，摸到了第三代的门把手。