兰 亭 墨 苑

标题 *

URL 别名 *

内容 * (支持 Markdown 格式) # 当 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 系统"不只是口号，而是一条已经被走过一遍、踩过坑、且能复走的路。** 第一代已经结束，第二代正在发生。而我们刚刚在第二代里，摸到了第三代的门把手。

配图 (可多选)

标签