Fam Zheng
96 lines
6.1 KiB
Markdown
96 lines
6.1 KiB
Markdown
---
|
|
title: "code-doc-bot：闭环协作"
|
|
date: 2026-05-08T08:40:16+01:00
|
|
draft: false
|
|
tags: ["AI", "Agent", "协作"]
|
|
summary: "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 |
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Human(("人"))
|
|
Agent(("AI Agent"))
|
|
Doc["doc · 协作层"]
|
|
Code["code · 工程层"]
|
|
|
|
Human <-->|"操作"| Doc
|
|
Human -->|"review"| Code
|
|
Agent <-->|"读写"| Doc
|
|
Agent -->|"生成"| Code
|
|
|
|
style Human fill:#fff,stroke:#333,stroke-width:2px,color:#000
|
|
style Agent fill:#fff,stroke:#333,stroke-width:2px,color:#000
|
|
style Doc fill:#fc9,stroke:#333,stroke-width:2px,color:#000
|
|
style Code fill:#9cf,stroke:#333,stroke-width:2px,color:#000
|
|
```
|
|
|
|
人和 AI Agent 各从一边接入两层:人在 doc 抛意图、在 code 上 review;AI 在 doc 上读写、把成果生成到 code。两个 actor 不在同一介质上面对面,而是隔着 doc 和 code 两层异步协作——这正是它健康的姿势。
|
|
|
|
注意 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 层 → 协作层失去入口/出口的清晰边界
|
|
|
|
这也是我之前在 [白盒施工,黑盒交付](/posts/whitebox-blackbox/) 里讲的"白盒"在 agent 协作里真正的形态——施工期 doc 入口全开,交付期 code 出口收紧。两者是同一过程的不同层面,不是矛盾。
|
|
|
|
## 收口
|
|
|
|
这套模型最让我喜欢的一点是**不需要新工具**。git/PR 有了、飞书 doc 有了、bot 也部署上了——拼起来就能跑。它本质上不是技术问题,是一个**协作约定**:
|
|
|
|
- 协作分两层:doc 协作层(灵活)、code 工程层(严格)
|
|
- bot 在两层间穿梭,把意图同步到实现,把结果反馈回产出
|
|
- 聊天只是 bot 的传声筒,不是协作本身
|
|
|
|
再看 bot 就不是聊天框里的黑盒了,而是一个**在 doc 协作层和 code 工程层之间穿梭的 agent**。聊天那点信号往来,不过是它和人之间的握手协议——次要得很。
|