yuanhao667 飞书文档增量融合整理
以用户指定的飞书文档为母板，从一份或多份增量来源中提取母板尚未覆盖的内容，并融合进母板的对应语义位置。目标是让更新后的文档读起来像一次连续整理，而不是“原文 + 文末附录”。
输入与边界
- 母板通常由用户明确指出；若同时提供多个链接但母板不明确，先确认哪一篇可以被修改。
- 增量来源可以是飞书文档、Wiki、录音智能纪要、会议总结或其他可读取材料。
- 母板原文是结构与措辞基准。保留其段落、图片、表格、引用、链接和个人表达，除非用户明确要求改写。
- 不硬编码文档 ID、用户 ID、课程名称、知识点、应用 ID、凭据路径或本次任务中的示例内容。
- 用户要求编辑现有文档即授权本次普通写入；所有权转移、删除文档等高风险操作仍需单独确认。
飞书操作约定
使用 lark-cli 处理飞书文档。首次进入读取或编辑阶段时，按 CLI 当前版本读取对应的 lark-doc、lark-doc-fetch、lark-doc-update 和所用内容格式参考。
- 编辑用户已有文档时，优先显式使用用户身份，使修改记录与权限保持在用户文档链路中。
- 若 Bot 只能读取、不能编辑，不要把“可读取”误判为“可写入”；改用具有编辑权限的用户身份，或明确报告权限阻塞。
- 区分网络限制、应用 Scope、文档访问权限和用户令牌存储问题，不用改变文档结构来规避权限问题。
- 更新前记录目标文档 ID 与最新 revision；更新后再次读取验证。
工作流
1. 读取母板与增量来源
- 先读取母板目录，理解章节顺序和标题层级。
- 读取母板完整 XML，并保留 block ID、样式和引用元数据。
- 读取所有增量来源的完整内容。只做摘要对比时可使用 Markdown；定位和写入时使用带 block ID 的 XML。
- 保护
<cite>、<img>、<source>、<whiteboard>、<sheet>、<bitable>、<synced_reference>等资源块，不将其降级为纯文本。
2. 建立语义差集
按主题对齐母板与增量来源，将来源内容分为：
- 已完整覆盖：不重复写入。
- 部分覆盖：保留母板原文，只补充缺失的规则、例子、边界或解释。
- 完全缺失：使用来源内容整理成新的段落或小节。
- 低价值信息：课程时间、作业提醒、寒暄、重复总结等默认不进入知识正文，除非用户要求。
- 不确定信息：录音转写可能错误的名称、数字或阈值应谨慎表述，并标明需以课件或实际项目为准。
能够直接沿用母板原文时，不用来源摘要重写。新增内容应忠于来源，不扩展来源未支持的事实。
3. 制定融合位置
对每个增量知识块确定最接近的原文锚点：
- 已有同名或同义标题：放到该章节中。
- 原文包含相关段落、图片、表格或链接：紧跟在该内容后面补充。
- 两个相邻对象形成比较关系：先保留两个对象，再紧接比较说明。例如母板依次放置 0→1 与 1→N 参考链接时，二者差异应放在第二条链接之后，随后继续母板原文。
- 没有对应位置：在课程或文章的逻辑顺序中创建新章节，而不是默认放到文档末尾。
除非用户明确要求，禁止把所有新增内容统一放进“增量补充”“录音补充”或“附录”章节。
4. 最小化修改
- 优先使用
block_insert_after、block_move_after、block_replace和精确str_replace。 - 已经写入但位置错误的内容，优先移动现有 block，避免复制后再删除造成重复。
- 不使用
overwrite，不删除或重写无关原文。 - 标题层级必须连续：一级标题下使用二级标题，避免从 H1 直接跳到 H3；移除仅在旧附录中有意义的序号。
- 每次结构修改后重新读取受影响范围，再使用最新 block ID 继续操作。
- 多次写入应按逻辑组分批进行；任一步失败就停止后续依赖写入，先诊断当前状态。
5. 写后验证
至少完成以下检查：
- 重新读取目录，确认章节顺序和标题层级正确。
- 按关键词抽查关键融合点，确认新增内容紧跟对应原文、链接或图片。
- 搜索临时标题，确认没有遗留“增量补充”外壳。
- 确认没有重复知识块，没有意外删除原文或破坏资源块。
- 检查更新结果、revision 和 warnings；存在降级或部分成功时不得宣称完成。
交付说明
完成后向用户提供：
- 更新后的飞书文档链接；
- 本次融合到哪些原章节；
- 是否保留全部原文与资源；
- 使用的编辑身份、最终 revision，以及飞书返回的警告或异常。
不要把冗长的命令、block ID 或中间 XML 暴露给普通用户，除非用户正在排障或明确要求技术细节。