飞书文档复制 skill

把一个参考飞书云文档（/docx/<token> 或 /wiki/<token>）的完整内容——文字、样式、 换行、空行、图片、有序/无序列表、引用块、callout、表格、画板、封面、目录组件、cite 文档 引用等——复制到当前 Lark CLI 登录用户自己的云空间，达到视觉与内容高度一致。

前置：用户已通过 lark-cli auth login 完成 user 身份认证（scripts/preflight.sh 会自检）。

输出

执行完成后必须按【最终输出格式】（见下）汇报：复制结果总结、与原文档的已知差异、 主文档新链接、放置目录、引用的相关文档（如有）、临时文件清理确认。

快速开始（一键执行）

绝大多数情况直接跑一键脚本，它会按顺序自动完成所有步骤：

bash scripts/run_all.sh "https://xxx.feishu.cn/docx/<token>"

主文档复制策略：能原生复制就原生复制。 run_all.sh 先用 00_try_native.py 尝试 drive files copy——成功（含跨租户成功）则直接用副本、跳过整套扒取重建（01/02/03）， 因为原生副本由飞书端到端复制、结构与源逐字节一致，天然没有 seq/grid/图片定位等后处理 bug。只有原生复制失败（跨租户禁复制 / 无权限 / 接口报错）才退回扒取重建。无论哪条路径， 之后都跑 cite 重指向 + 核验 + 清理。

单独运行某步（调试或重跑某步）：按上表脚本顺序逐个 python3 scripts/0X_*.py 即可； 00_try_native.py / 01_fetch_source.py 需要 --source "<url>"，其余从 state.json 读状态。

共享库 scripts/lib.py：lark-cli 调用包装（run_lark_cli / run_lark_cli_json）、文档读取 （fetch_doc_xml）、图片处理（download_image / upload_image）、XML 解析（xml_to_blocks）、 状态管理（load_state / update_state）。 状态文件 state.json（cwd 下）：脚本间中间状态——source_url、source_xml_path、 img_tokens、new_doc_id、new_doc_url、id_mapping、uploaded_images 等。

工作流（扒取重建路径，理解 + 手动执行用）

原生复制成功时下面这些后处理全部跳过。只有走兜底扒取重建时才逐步执行（均已在 03_post_process.py 自动化，顺序有依赖，不要随意调换）：

1. 读源文档 XML + 下载图片 → 清理 XML + create 新文档 → 构建 source→new block ID 映射
2. 更新目录锚点；上传图片到文末
3. 图片定位（最易错，详见 references/image-positioning.md）： compute_image_anchors 按图前驱分 direct/two_step/fallback 三模式 → move_images； 折叠标题内嵌套图由 move_nested_images 补救
4. 图片尺寸 fix_image_sizes（scale/宽高）→ 对齐 fix_image_align（左/右，须在尺寸之后）
5. 还原并排图 grid rebuild_grids → 修 callout 边界 fix_callout_imgs → 校准图前后空 p normalize_image_empty_p_around
6. 迁移画板 migrate_whiteboards → 内嵌表 migrate_sheets → 封面 migrate_cover → ISV 目录组件 migrate_addons
7. 修有序列表 seq fix_list_seq（详见 references/list-and-nesting.md）→ 合并连续 blockquote + 去引用块灰底
8. cite 递归（见下「cite 引用递归」）→ 核验 04_verify.py → 清理

已知限制

A. 真正无法消除的差异（会出现在最终报告的【已知差异】里）

1. 灰色背景色（仅引用块外）：源 rgb(229,230,233) 被飞书归一化为 rgb(242,243,245)。 标题/callout/行内 code 等位置保留此差异；引用块内的灰底已由 strip_blockquote_bg 自动去除。
2. callout 边框：飞书自动添加 border-color 属性。

B. 飞书 API 行为坑（脚本已自动处理；出问题时按"详见"读细节手动补救）

手动补救通用原则（脚本失败、需要手工调块时必读）

手工调块顺序时，飞书 API 有几个反复踩到的坑，跨具体修复通用：

• block_move_after 落点不可靠，三种已知形态会让 src 落到非预期位置：①anchor 后紧跟空 p； ②src 本身是空 p；③src 当前在 anchor 之前（回挪时越位一格）。每次调用后必须重新 fetch 核验实际落点，不能假设"紧贴 anchor"。详见 references/api-limitations.md 限制 5.3 / 19.1。
• 能用 children-create API 就别用 block_move_after：POST .../blocks/{parent}/children 带显式 index，落点确定（重建目录组件、补空行都用这个）。空段落不能用 block_type 2 + 空 elements （报 invalid param）；空行改用 docs +update block_insert_after --content '<p></p>' --doc-format xml。
• 调空行用「删旧 + 插新」而非移动空 p；锚点尽量选非容器块（grid/column 等容器作 anchor 易越位）。
• xml.etree.Element 没有 __bool__ 重载：所有 Element 都视为 falsy，if el: 永远 False。 处理飞书 XML 一律用 if el is not None。

cite 引用递归

源文档里引用的其它飞书文档（<cite type="doc"> @文档 / 指向 /docx、/wiki 的行内链接）会被 process_cites.py 自动一并复制到同目录，并把主文档里的引用重指向到副本：探测权限 → 优先 原生复制 → 失败兜底递归扒取 → block_replace 重指向。共享 registry + 深度上限防环、收尾去重 清理同源孤儿。完整策略、递归约定、self 登记真实标题等坑，见 references/cite-recursion.md。

最终输出格式

skill 执行完成后，必须按以下格式输出（中文）：

========================================
飞书文档复制完成
========================================

源文档：<源文档标题>
新文档：<主文档新链接>
放置目录：<目录名称>

【复制结果】
- 文字内容：✅ 100% 一致（共 X 个文本块）
- 图片：✅ X 张全部复制
- 锚点链接：✅ X 个全部更新
- 有序列表序号：✅ X 个 li 全部修复
- 引用样式标签：✅ 完全一致（b: X, em: X, ...）

【已知差异】（无法修复）
1. 灰色背景色：源 rgb(229,230,233) → 新 rgb(242,243,245)
2. callout 边框：飞书自动添加 border-color 属性

【引用的相关文档】（如有）
- <子文档 1 标题>（已复制：原生/递归） → <副本链接>
- <子文档 2 标题>（无权限，保留原链接） → <原链接>

【临时文件清理】
✅ 已清理所有临时文件、图片、脚本

【用户 review 项】
- 请打开新文档，对照源文档检查整体视觉效果
- 重点关注：图片是否在正确位置、列表是否正常递增、引用样式是否正确
========================================

⚠ 主文档链接坑：run_all.sh 顶层在清理前会显式打印「📄 主文档副本」横幅——汇报时用这个 链接，不要从 cite 列表里挑（同名引用文档易被误当主文档，见 cite-recursion）。

用户偏好

• 中文交流：所有输出使用中文。
• 简洁务实：不做冗长解释，只给关键信息。
• 完成后输出变动详情：便于用户 review。
• 容忍样式细微差异：但文字内容必须 100% 一致。

脚本清单

详细参考文档