Fam Zheng
5.4 KiB
title, date, draft, tags, summary
| title | date | draft | tags | summary | |||
|---|---|---|---|---|---|---|---|
| code-doc-bot：闭环协作 | 2026-05-08T08:40:16+01:00 | false |
|
code 是工程层,doc 是协作层,bot 在两层间穿梭。三位一体不是三种容器并列,而是两个层面 + 一个执行者,靠同步形成闭环。 |
跟 AI Agent 协作久了,我越来越觉得应该把它当三位一体来看——code、doc、bot 三者各占一极,构成一个闭环。
但这个三位一体不是三种内容容器并列。code 和 doc 是同一份协作在两个层面上同时呈现——code 偏工程层(确定、严格、可执行),doc 偏协作层(灵活、易容纳混沌、承载入口和出口)。bot 是在这两层间穿梭的执行者。
很多人不自觉地把 bot 等同于"聊天窗口",于是协作也被默认放在聊天里。但聊天只是 bot 的一个 surface——bot 本体是那个 agent,可以读文件、可以写 PR、可以跑 CI、可以推飞书消息。把 surface 当成 bot 本身,是这套模型最常见的退化。
三个本体
| code | doc(飞书) | bot(AI Agent) | |
|---|---|---|---|
| 层面 | 工程层 | 协作层 | 执行者 |
| 偏向 | 确定性、严格、可执行 | 灵活、易容纳混沌 | 在两层间同步 |
| 承载 | 工程过程的全部确定记录 | 入口(意图)与出口(产出) | 智能体本身 |
| 面向 | 机器(也给人 review) | 人(也给 bot 读) | 桥接两层 |
| 寿命 | 长期 + git 历史 | 长期、可追溯 | 一次次 session |
注意 code 和 doc 不是按"内容种类"切分的——不是"过程归 code、结论归 doc"那种粗暴分工。它们是同一份协作在两个层面的同时呈现:
- doc 端是入口和出口。入口是用户的混沌意图(需求一句话、背景几段、随手贴的截图);出口是给用户看的最终产出(结论、决策、总结)。doc 必须灵活,因为人脑就是灵活的、混乱的、随时改主意的
- code 端是工程过程。commits、PR、tests、CI、build 产物。它必须严格,因为机器不容许"差不多"。code 不存在"半成品的灵活态",只有"通过"或"没通过"
bot 的核心工作就是让这两层时刻同步——doc 入口的意图落到 code 实现,code 跑出的结果反映回 doc 出口。
一次完整的回合
四阶段,标清谁在哪一层动作。
一、混沌投递(人 → doc 入口):人在飞书文档里自由抛——需求一句话、背景三段、参考链接五个、随手贴的截图、没想清楚的问题。允许混沌,因为入口就是设计来吞混沌的。结构化的成本转嫁给 bot。
二、信号触发(人 → bot):人在聊天里把文档链接发给 bot——显式启动指令。不希望它在你打草稿时就跳出来开干。
三、跨层同步施工(bot → code + doc):bot 读 doc 入口、调度子任务,在两层同时动作:
- code 层:正常工程流程,commit / PR / branch,跑 tests、过 CI。git 历史是这一层的 audit trail
- doc 层:append-only 追加 Update Log——当前阶段、子任务分配、决策、待确认。doc 不复述 code 细节,只承载工程层之外的协作信息
Append-only 是 doc 这一层的关键契约:bot 不删人写的内容,只追加。原始混沌是历史档案,bot 产出是演进层。"它会不会把我写的改坏了"这个焦虑因此不成立——它没有"改"的权限,只有"加"的权限。
四、产出回流(bot → doc 出口 → 人):阶段性完成后,bot 把工程层的结果反映到 doc 出口(结论、产物链接、决策点),然后在聊天里发一条信号告诉人"该你了"。人回到 doc 审过程、回到 code 审 diff。
闭环:doc 入口 ← 人;bot 同步 doc ↔ code;doc 出口 → 人。聊天只承担"开始"和"该你了"两个握手时刻,从不承载协作内容。
为什么不能把 doc 塞进 code(或者反过来)
有人问过:直接把意图和过程写在 PR description 或 commit message 里不就行了?反过来——把代码贴进 doc 协作不也可以?
不行。两层服务于不同对象,有不同形态要求:
- code 是给机器和严格 reviewer 看的:静态可解析、有版本、能跑、能 diff。它没法容纳"用户后来改主意了"这种协作层语义
- doc 是给人看的:可以混沌、可以半成品、可以重写、可以容纳被否决的方案。但它没法 build、没法跑 test、没法保证"diff 正确性"
强行合并的两种失败方式:
- 把灵活协作塞进 code 层 → 工程过程被污染,review 噪音爆炸
- 把代码细节塞进 doc 层 → 协作层失去入口/出口的清晰边界
这也是我之前在 白盒施工,黑盒交付 里讲的"白盒"在 agent 协作里真正的形态——施工期 doc 入口全开,交付期 code 出口收紧。两者是同一过程的不同层面,不是矛盾。
收口
这套模型最让我喜欢的一点是不需要新工具。git/PR 有了、飞书 doc 有了、bot 也部署上了——拼起来就能跑。它本质上不是技术问题,是一个协作约定:
- 协作分两层:doc 协作层(灵活)、code 工程层(严格)
- bot 在两层间穿梭,把意图同步到实现,把结果反馈回产出
- 聊天只是 bot 的传声筒,不是协作本身
再看 bot 就不是聊天框里的黑盒了,而是一个在 doc 协作层和 code 工程层之间穿梭的 agent。聊天那点信号往来,不过是它和人之间的握手协议——次要得很。