# Feishu Doc Incremental Merge

> 将录音纪要、会议总结、课堂笔记或参考资料中的新增信息，去重后按语义位置融合进已有飞书母板文档。适用于用户要求保留原文、只做增量补充并直接更新现有飞书文档的场景；不用于单纯文末追加或从零创建新文档。

- Skill: `yuanhao667/feishu-doc-incremental-merge` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yuanhao667/feishu-doc-incremental-merge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuanhao667/feishu-doc-incremental-merge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yuanhao667 (https://skillmd.com/u/yuanhao667)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yuanhao667/feishu-doc-incremental-merge

---


# 飞书文档增量融合整理

以用户指定的飞书文档为母板，从一份或多份增量来源中提取母板尚未覆盖的内容，并融合进母板的对应语义位置。目标是让更新后的文档读起来像一次连续整理，而不是“原文 + 文末附录”。

## 输入与边界

- 母板通常由用户明确指出；若同时提供多个链接但母板不明确，先确认哪一篇可以被修改。
- 增量来源可以是飞书文档、Wiki、录音智能纪要、会议总结或其他可读取材料。
- 母板原文是结构与措辞基准。保留其段落、图片、表格、引用、链接和个人表达，除非用户明确要求改写。
- 不硬编码文档 ID、用户 ID、课程名称、知识点、应用 ID、凭据路径或本次任务中的示例内容。
- 用户要求编辑现有文档即授权本次普通写入；所有权转移、删除文档等高风险操作仍需单独确认。

## 飞书操作约定

使用 `lark-cli` 处理飞书文档。首次进入读取或编辑阶段时，按 CLI 当前版本读取对应的 `lark-doc`、`lark-doc-fetch`、`lark-doc-update` 和所用内容格式参考。

- 编辑用户已有文档时，优先显式使用用户身份，使修改记录与权限保持在用户文档链路中。
- 若 Bot 只能读取、不能编辑，不要把“可读取”误判为“可写入”；改用具有编辑权限的用户身份，或明确报告权限阻塞。
- 区分网络限制、应用 Scope、文档访问权限和用户令牌存储问题，不用改变文档结构来规避权限问题。
- 更新前记录目标文档 ID 与最新 revision；更新后再次读取验证。

## 工作流

### 1. 读取母板与增量来源

1. 先读取母板目录，理解章节顺序和标题层级。
2. 读取母板完整 XML，并保留 block ID、样式和引用元数据。
3. 读取所有增量来源的完整内容。只做摘要对比时可使用 Markdown；定位和写入时使用带 block ID 的 XML。
4. 保护 `<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. 写后验证

至少完成以下检查：

1. 重新读取目录，确认章节顺序和标题层级正确。
2. 按关键词抽查关键融合点，确认新增内容紧跟对应原文、链接或图片。
3. 搜索临时标题，确认没有遗留“增量补充”外壳。
4. 确认没有重复知识块，没有意外删除原文或破坏资源块。
5. 检查更新结果、revision 和 warnings；存在降级或部分成功时不得宣称完成。

## 交付说明

完成后向用户提供：

- 更新后的飞书文档链接；
- 本次融合到哪些原章节；
- 是否保留全部原文与资源；
- 使用的编辑身份、最终 revision，以及飞书返回的警告或异常。

不要把冗长的命令、block ID 或中间 XML 暴露给普通用户，除非用户正在排障或明确要求技术细节。