diff --git a/content/posts/code-doc-bot.md b/content/posts/code-doc-bot.md new file mode 100644 index 0000000..f0841c1 --- /dev/null +++ b/content/posts/code-doc-bot.md @@ -0,0 +1,75 @@ +--- +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 | + +注意 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**。聊天那点信号往来,不过是它和人之间的握手协议——次要得很。 diff --git a/content/posts/feishu-doc-as-ssot.md b/content/posts/feishu-doc-as-ssot.md deleted file mode 100644 index 05441b8..0000000 --- a/content/posts/feishu-doc-as-ssot.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "将飞书文档定义为 AI Agent 的 Single Source of Truth" -date: 2026-05-08T08:40:16+01:00 -draft: false -tags: ["AI", "Agent", "协作", "Ida"] -summary: "文档承载内容，对话承载信号。把飞书文档当成 AI Agent 的 SSOT，把单聊降级为触发与通知通道——这不是工具选型，是协作模型的重构。" ---- - -跟 AI Agent 协作久了，我越来越确信一件事：**对话流不是协作的本体，文档才是**。 - -聊天窗口是人和 agent 都很容易掉进去的舒适区——一来一回、随手发问、即时反馈。但凡用过几次就会发现问题：上下文滚走了找不回来，agent 改过的东西散落在十几条消息里，想审阅一下"现在到底是什么状态"得自己往上翻。聊天流天然是**线性**且**易腐**的，它适合传递信号，不适合沉淀状态。 - -所以我最近在琢磨一种协作模型：**把飞书文档定义为 AI Agent 的 Single Source of Truth，把单聊降级为触发与通知通道**。 - -## 双通道分工 - -| | 飞书文档 | 单聊对话 | -| --- | --- | --- | -| 角色 | Single Source of Truth | Trigger & Notification | -| 承载 | 需求、上下文、过程记录、最终产出 | 启动信号、完成提醒 | -| 寿命 | 长期、可追溯 | 短期、易腐 | -| 操作 | 读写、审阅、协作编辑 | 发送、接收 | - -一句话概括就是：**内容沉淀在文档，信号流转在对话**。 - -这个分工不是为了让对话变得没用——恰恰相反，它让对话回到了它最擅长的事：**告诉对方"该看了"**。把内容塞进对话，是在让一个本来负责传信号的通道兼职做归档，结果两头都做不好。 - -## 一次完整的协作回合 - -具体跑起来是这样的四个阶段。 - -### 一、混沌投递 - -用户在飞书文档里**自由地抛**：需求一句话、背景三段话、参考链接五个、随手贴的截图两张、还没想清楚的问题若干。文档允许处于"混沌状态"，无需预先结构化。 - -这一阶段用户的负担是**抛出**，不是**整理**。这点很重要——传统流程里，人最大的内耗在"我得先把这事儿想清楚才能让 AI 干"，结果光是整理需求就消耗了一半精力。让文档容忍混沌，是把结构化的成本转嫁给了 agent。 - -### 二、信号触发 - -用户在**单聊**里把文档链接发给 agent。这一动作是**显式的启动指令**——明确告诉 agent：哪个文档、什么时候开始。 - -显式触发很关键。你不希望 agent 在你还在打草稿的时候就跳出来开干，也不希望它在群里看到 @ 一下就以为是叫它。**让用户主动按下这个按钮**，边界就清晰了。 - -### 三、文档内施工 - -主 agent 拉取文档全文作为上下文，解析意图，调度子 agent 矩阵分工执行。重点是这一步——**所有的工作产出都直接写回文档**： - -- 当前阶段、进度 -- 子 agent 任务分配与完成情况 -- 结论性文字 -- 执行日志（Update Log） -- 附件、内联图片、中间产物 - -而且产出策略是 **Append-only**——只增不减。用户的原始混沌输入不会被覆盖，agent 只在它之上追加新的层。任何回滚、对比、复盘都有据可查。 - -这一步等于把传统聊天流里那些"agent 内心戏"**全部外化**到文档里。你随时点开文档就能看到它正在做什么、做到哪一步、为什么这么做。不需要追问，不需要等总结。 - -### 四、回流审阅 - -阶段性工作完成后，agent 在**单聊**发一条 "请审阅" 信号。信号本身极简——链接 + 一两句摘要要点，**绝不复述文档内容**。用户回到文档进行审阅、修改、追加新需求。 - -这就形成了一个闭环：**文档 → 单聊触发 → 文档施工 → 单聊通知 → 文档再审阅**。 - -注意整个闭环里，对话从未承载过任何"状态"。它只在两个时刻出现：开始和"该你了"。 - -## 为什么这样设计 - -### 文档是意图的编译产物 - -我之前写过 [Ida](/posts/ida-intent-driven-agent/) 的工程观——人提供意图，agent 把意图编译成各种产物。这个 SSOT 模型其实是 Ida 的一个直接落地： - -- 用户输入的混沌片段是**意图与上下文**（源代码） -- agent 的工作是把意图"编译"成结构化、可执行、可审阅的产物 -- 文档是这次"编译"的**输出工件**，而不是草稿本 - -这个视角的好处是：你不会再纠结"文档里这部分是用户写的还是 agent 写的"。所有内容都是同一份意图的不同投影，区别只在于**层级**——原始输入是底层，agent 产出是上层。 - -### 用结构化记录消除黑盒感 - -agent 最让人不放心的地方是黑盒——它去了，干了，回来了，但中间发生了什么你不知道。各种"思考过程可视化"的方案都在试图打开这个黑盒，但聊天流里那些 thinking、reasoning、tool call 看着热闹，过后回头找东西基本找不到。 - -把过程**直接写进文档**是一种粗暴但有效的解法。Update Log 不是给 agent 看的，是给人看的——结构化、时间序、可检索。你随时打开文档就能回答"这个 agent 现在在做什么 / 为什么这样做"，不依赖事后解释。 - -**过程透明本身就是文档的一部分**。这一点是我在 [白盒施工，黑盒交付](/posts/whitebox-blackbox/) 里讲的"白盒"在 agent 协作里的具体形态——施工期把所有零件摆在台面上。 - -### Append-only 是不可逆承诺 - -agent 不删除用户内容，只在其上追加。这条规则看起来朴素，实际上是**一种契约**： - -- 用户的原始混沌输入是**历史档案** -- agent 的新产出是**演进层** -- 任何时刻都能回到任何一个版本 - -它解决的核心焦虑是"agent 会不会把我写的东西改坏了"。在 append-only 之下，这个焦虑不成立——它没有"改"的权限，只有"加"的权限。审阅成本因此急剧降低：你不需要 diff，只需要扫一眼新增的部分。 - -## 几个实践要点 - -把这套模型落到飞书上，有几个细节值得拎出来： - -- **文档结构化模板**。给每篇协作文档预设固定区块——"原始输入"、"执行计划"、"Update Log"、"产出"、"待确认"。agent 只在指定区块写东西，不污染用户区。 -- **单聊信号语言极简**。"请审阅"、"已完成阶段 X"、"卡在 Y 需要你决策"——三种以内。复杂内容一律链接+回文档。 -- **每阶段一个明确的"该你了"节点**。不要让 agent 不停推进 50 步以后才回头。审阅频率应该是**人决定**的，不是 agent 自己掌握。 -- **权力归用户**。agent 提建议、写产出、记录过程；但删什么、保留什么、下一步走哪儿，永远是用户拍板。 - -## 收口 - -这个模型最让我喜欢的一点是它**不需要新工具**。飞书文档有了、单聊有了、文档 API 有了——拼起来就能跑。它本质上不是技术问题，而是一个**协作约定**：内容归文档，信号归对话，过程透明，只增不减。 - -聊天界面还会存在，它是必要的——人和 agent 之间总得有个直接说话的地方。但聊天不应该是协作的主舞台。把舞台让给文档，让对话回到它该在的位置——一个**短促、克制、用来传信号的通道**——整个协作流程会立刻变得可控、可审、可复盘。 - -agent 不再是个聊天框里的黑盒，而是一个**在文档上施工的施工队**。这个画面，比"对话式 AI 助手"清楚太多了。