在飞书文档中与本地 Codex进行沉浸式协作

让 Codex 成为嵌入飞书文档的协作助手

用户只需要在飞书文档中选中文字、表格或画板，并通过评论提出要求。系统将精确上下文交给本地 Codex。让文字、表格与画板都能在原文档中以更小成本持续优化

1. 背景

在个人工作中，我们经常使用 Codex 辅助沉淀技术方案、项目总结和分析文档。常见使用方式通常是将整篇文档发送给 Codex，并告知哪里需要调整以及怎么调整，生成新内容后再次校验；后续每次调整，即使只修改一个段落、一张表格或一个画板，也需要重复传递全文并重新生成。

这种方式主要存在几个问题：

1. 局部修改成本高

一处小调整也需要经历「复制全文、描述要求、生成全文、人工比对」的完整流程。

1. 上下文不够精确

Codex 接收到整篇文档后，需要自行判断修改范围，容易误改不相关内容，用户还要反复强调只修改这一部分。

1. Token 消耗较大

每轮修改都重复传递大量未发生变化的内容，输入和输出 Token 中存在较多无效消耗。

2.核心思路

这个能力的出发点，是让 Codex 从全文生成工具转变为嵌入飞书文档的协作助手。用户只需要在飞书文档中选中文字、表格或画板，并通过评论提出要求。系统会自动获取：

• 当前评论内容

• 评论引用的局部内容

• 引用对象的完整结构化上下文

• 必要的文档位置和版本信息

随后，系统将这组精确上下文交给本地 Codex。解释类请求直接在评论中回复；修改类请求则在通过安全校验后，直接更新对应的文字、表格或画板。

3. 能力矩阵

目前覆盖文字、原生表格和画板，共 10 种操作。

2.1 文字类案例

文字解释、文字修改、文字转表格、文字转画板。

2.2 画板类案例

画板解释、画板修改、画板下方添加说明

2.3 表格类案例

表格解释、表格修改、表格下方添加说明。

4. 总体技术架构

整体技术架构以事件驱动为核心思路。协作者在飞书文档中选中内容并@机器人后，评论事件通过官方接口进入本地处理服务；事件首先写入持久化队列，将接收与处理解耦。

上下文构建会根据评论锚点识别普通文字、原生表格或画板，并读取完成决策所需的完整对象信息；Codex 随后输出结构化处理结果，明确请求类型、目标范围和具体操作，避免直接生成不可控的写入动作。

写回前设置规则与版本校验，用于检查目标对象、操作类型、内容规模及文档版本，降低误改、覆盖并发更新和越权操作的风险。校验通过后，再调用 Drive、Docx、Board CLI完成评论回复或内容修改。

5. 一条评论的处理过程

处理过程分为六步：

6. 如何拿到完整上下文

6.1 文字

文字优先根据 Docx 文本元素里的评论定位，而不是只依赖事件中的 quote。这样可以处理 quote 截断，以及评论跨越连续文本块的情况。

• 单块引用只替换被选中的文本片段。

• 连续多块引用按同一个范围改写。

• 无法读取评论锚点时，才使用 quote 唯一匹配。

• 引用范围外的粗体、链接、@人和公式保持不变。

6.2 表格

表格评论往往挂在某个单元格的文本块上。服务会沿 block 父子关系找到表格根块，再读取所有单元格，整理为二维数组。

传给 Codex 的内容包括行列数、完整数据、合并单元格信息和表格 block ID。修改时 Codex 返回完整目标表格，执行器对比前后数据，只更新变化的单元格；需要时再调整行列数。

6.3 画板

画板评论里的 quote 通常只有 [画板]。服务会通过画板 token 拉取节点，并准备两份上下文：

• 节点摘要：类型、文本、位置和尺寸，便于快速判断。

• 完整节点 JSON：保存到本地上下文文件，修改画板时读取。

7. Codex 的输入输出约束

后台使用 codex exec --ephemeral --output-schema。每个事件单独执行，同一评论线程的历史内容由服务显式传入，不依赖模型会话状态。

简化后的返回结构如下：

{  "intent": "consult | edit | complex_edit | clarify | reject",  "confidence": 0.97,  "reply_text": "回复内容",  "target": {    "quote": "引用内容",    "replacement": "替换内容",    "edit_scope": "none | quote_only | insert_after_quote | replace_table | replace_board"  },  "operations": [],  "safety": {    "needs_human_review": false,    "reason": ""  }}

8. 写回文档的实现

8.1 评论回复

解释、分析、总结和通用问题只回复原评论，不进入正文写入流程。

8.2 文字修改

执行器通过 Docx batch_update 更新命中的文本元素。调用接口前会重新读取目标 block，确认 revision、quote 和评论范围没有变化。

8.3 表格修改

表格修改按以下顺序执行：

8.4 画板修改

画板更新采用完整替换，避免新旧内容叠在一起：

如果 Codex 返回 Mermaid 或 PlantUML，则清空旧节点后重建整张图；重建失败同样使用快照恢复。

9. 安全控制