@amaster.ai/pi-lark 0.1.7 → 0.1.9

package/skills/lark-slides/references/troubleshooting.md

@@ -1,63 +1,5 @@
-# Troubleshooting
+# Troubleshooting（兼容入口）
 
-本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
+本文档已迁移至 [`workflow/error-handling.md`](workflow/error-handling.md)。
 
-## XML Preflight
-
-在真正创建或替换前，至少检查：
-
-- 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
-- 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
-- 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
-- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
-
-## Failure Order
-
-遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
-
-1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
-2. 用 `slides +xml-get` 回读，确认是否已有部分页面写入。
-3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
-4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
-5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 `xml_text_overlap_lint.py`；先修复所有 `error`，再对 `warning` 指向的页面和元素做截图复核。
-6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
-
-## Symptom Fixes
-
-| 看到的问题 | 处理方式 |
-|-----------|----------|
-| 文字被截断 / 看不全 | 增大 shape 的 `width` 或 `height`，或减少文本量 |
-| 元素重叠 | 调整 `topLeftX` / `topLeftY`，拉开间距 |
-| 页面大面积空白 | 回读确认内容是否写入；若内容存在，再缩小间距或增加主体元素 |
-| 文字和背景色太接近 | 深色背景用浅色文字，浅色背景用深色文字 |
-| 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
-| 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
-| 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
-| 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
-| 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
-| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
-
-## Common Errors
-
-| 错误码 / 信号 | 含义 | 解决方案 |
-|--------------|------|----------|
-| 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
-| 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
-| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
-| 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
-| 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
-| 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
-| 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
-| 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
-| 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
-| 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
-| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
-| validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
-
-## Command-Specific References
-
-- 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](lark-slides-media-upload.md) 和 [lark-slides-create.md](lark-slides-create.md)。
-- 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。
-- 原生 `slide.create` 包装、`before_slide_id` 和 jq 模板：见 [lark-slides-xml-presentation-slide-create.md](lark-slides-xml-presentation-slide-create.md)。
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/validation-checklist.md

@@ -1,156 +1,5 @@
-# Validation Checklist
+# Validation Checklist（兼容入口）
 
-创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+本文档已迁移至 [`workflow/validation-xml.md`](workflow/validation-xml.md)。
 
-小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
-
-## Required Flow
-
-1. 记录创建或编辑返回的 `xml_presentation_id`，以及已知的 `slide_id` / `revision_id`。
-2. 用 `slides +xml-get` 回读全文 XML 到本地文件。
-3. 检查实际页数是否符合计划或用户要求。
-4. 检查每页 `<data>` 内是否有预期主要元素。
-5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
-6. 检查页面不是全部退化为标题加 bullet list。
-7. 检查视觉层级：标题、主视觉、支撑信息三者可区分。
-8. 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
-9. 在最终回复中给出简短验证记录。
-
-回读命令：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "YOUR_ID" \
-  --output .lark-slides/plan/<deck-or-task-id>/readback.xml \
-  --json
-```
-
-## Automated XML Layout Lint
-
-`slides +xml-get` 保存 XML 后，只运行统一版式准出入口。先取得当前已加载 `lark-slides/SKILL.md` 的父目录，记为 `<lark-slides-skill-dir>`；不要猜测全局安装路径。
-
-```bash
-python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <presentation.xml>
-```
-
-它一次检查 XML/SXSD 合法性、元素越界、文本重叠、空白页、文本高度风险、整页内容稀疏和大卡片内容覆盖率。大卡片自身 `<content>` 的估算文本面积与卡片内平级元素一起参与覆盖率并集计算。
-
-准出规则：
-
-- `summary.error_count > 0` 或 `summary.release_ready == false`：阻断创建、替换或交付，必须先修复。
-- `summary.warning_count > 0`：静态检查不直接阻断，但 `summary.screenshot_review_required == true`，必须复核对应页面截图。
-- `slides[].status` 为 `blocked`、`needs_screenshot_review` 或 `passed`，可直接决定逐页后续动作。
-- CLI 在存在 `error` 时退出码为 1；只有 `warning` 时仍输出 JSON 并退出 0，供截图复核链路继续执行。
-
-每条 `error` / `warning` 都包含：
-
-- `element_ids`：相关 XML 元素 ID；
-- `rule`：规则 ID、名称、阈值和比较关系；
-- `measurement`：越界量、交叠面积、覆盖率等实测值；
-- `related_objects`：相关对象的类型与坐标框；
-- `target`、`message`、`hint`：页码、语义说明和处理建议。
-
-当 `sparse_container_content.measurement.content_coverage_ratio < rule.threshold` 时，需要结合同页截图判断留白是否有意设计；不要仅凭 warning 自动扩充内容。
-
-常见 code 的处理方向：
-
-| code | 含义 | 处理方式 |
-|------|------|----------|
-| `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
-| `sml_prefixed_tag` | SML 元素使用了命名空间前缀，如 `<ns0:slide>` 或 `<sml:shape>` | 使用 `<slide xmlns="http://www.larkoffice.com/sml/2.0">` 的默认命名空间，或使用无前缀标签 |
-| `sxsd_unsupported_tag` | 使用了 SXSD 不支持的标签 | 按 lint `hint` 替换为受支持标签；常见如 `textbox -> <shape type="text">`、`image -> <img>` |
-| `sxsd_unsupported_attr` | 支持的标签上使用了不支持的属性 | 按 lint `hint` 改为支持的属性；常见如 `x -> topLeftX`、`fontColor -> color` |
-| `iconpark_unsupported_icon_type` | `<icon>` 使用了 `iconpark-index.json` 中不存在的 `iconType` | 按 lint `hint` 改为名单内的 `iconType`，或先用 `scripts/iconpark_tool.py` 搜索 |
-| `icon_missing_fill_color` | 视觉规范要求 `<icon>` 设置 `<fill><fillColor color="..."/></fill>`，避免图标不可见 | 给 `<icon>` 添加显式非透明填充色，例如 `rgba(37, 99, 235, 1)` |
-| `icon_transparent_fill_color` | `<icon>` 的 `fillColor` 是透明色，不满足视觉可见性要求 | 改成与背景有足够对比的非透明颜色 |
-| `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
-| `*_out_of_canvas` | 元素边界超出页面画布 | 根据 `measurement.overflow` 移回画布或缩小尺寸 |
-| `blank_slide` | 页面没有画布内可见内容 | 补充主体内容；仅有空背景或空形状不能准出 |
-| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按元素 ID 定位卡片，结合截图判断是否补充或放大内容 |
-| `sparse_slide_content` | 全页有效内容覆盖率偏低 | 复核截图，确认是否为有意留白 |
-
-## Screenshot QA
-
-获取页面截图后，必须做视觉验收；不要只凭 XML 回读或静态 lint 结论声称截图验收通过。验收时假设页面存在问题，主动寻找并报告所有风险，包括轻微问题。
-
-```text
-请逐页目视检查这些幻灯片截图。先假设存在问题，并尽量找出它们。
-
-重点检查：
-- 元素重叠：文字与形状、图片或图表互相遮挡，线条穿过文字，卡片或标签堆叠。
-- 文本溢出或被裁切：靠近页面边缘、文本框边界或卡片边界处被截断。
-- 装饰元素位置错误：分割线、强调线或标签底板按单行文字布置，但标题或正文换行后压住文字或距离异常。
-- 来源标注、页脚或页码与上方内容碰撞。
-- 元素距离过近：相邻元素间距明显不足，卡片或分区几乎贴在一起；按 960x540 画布估算，小于约 15 px 的间隔通常要标记。
-- 间距不均：局部留白过大，另一处过于拥挤。
-- 页面边距不足：主体内容贴近幻灯片边缘；按 960x540 画布估算，小于约 30 px 的外边距通常要标记。
-- 列、卡片、图标或同类元素没有稳定对齐。
-- 图片或图表渲染异常：空白、变形、低清、关键内容不可读或预期图形缺失。
-- 文本对比度不足，例如浅灰文字放在米色或浅色背景上。
-- 图标对比度不足，例如深色图标放在深色背景上，且没有浅色圆形或底板承托。
-- 文本框过窄，导致不必要的频繁换行。
-- 残留占位符、模板默认文字或未替换内容。
-
-对每一页分别列出发现的问题或可疑区域，即使只是轻微问题也要记录。
-
-报告所有发现的问题，包括轻微问题。
-```
-
-必须根据问题严重度决定是否修复：空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付；轻微间距或对齐问题如果不修复，最终验证记录要说明已知风险。
-
-## Page Count And Structure
-
-- 实际页数必须等于用户要求或 `slide_plan.json` 的页数。
-- 如果创建过程部分失败，先记录已创建的 `xml_presentation_id`，再回读确认哪些页已写入。
-- 每页都应包含 `<data>`，且 `<data>` 内至少有一个非背景主体元素。
-- 封面、章节页、总结页可以文字较少，但不能只有空背景。
-- 技术解释页、对比页、流程页、架构页必须有匹配的结构元素，例如分组框、连线、时间轴、表格或图形化区域。
-
-## Expected Elements
-
-按 `slide_plan.json` 和用户要求逐页核对：
-
-- 标题或主结论存在，并能对应 `key_message`。
-- `layout_type` 对应的主要结构已生成。
-- `visual_focus` 是页面中最醒目或最大的信息区域之一。
-- `text_density` 影响了文本量，没有用长 bullet 框替代规划。
-- `asset_need` 有真实素材时已放入正确区域；没有真实素材时，`fallback_if_missing` 已用 XML 形状、线条、标签、表格或图表兜底。
-
-如果用户指定了关键页，例如“架构解释”“Self-Attention 机制解释”“对比或演进视角”“总结页”，最终验证记录必须逐项说明这些页已存在。
-
-## Blank Or Broken Page Signals
-
-把下面情况视为需要修复后再交付：
-
-- `<data/>` 为空，或只有背景、装饰线、空 `<content/>`。
-- 关键文本没有出现在回读 XML 中。
-- 图片仍是 `@./path`，或 `<img src>` 是 http(s) 外链。
-- 页面依赖的图片区域为空，且没有 fallback visual。
-- 返回 XML 缺页、页序明显错误，或某页内容被 shell 截断。
-- 大量形状坐标完全相同，导致主体内容重叠。
-- 渐变背景回退成空白或白底，导致文字不可读。
-
-## Layout And Overflow Risk
-
-优先修复这些明显风险：
-
-- 正文或标签框高度不足，文本很可能被截断。
-- 多个主体元素在同一区域重叠，而不是有意叠加背景。
-- 重要内容越过画布边界，或贴近底部超过 `y=500`。
-- 高密度页使用单个长 bullet list，没有分栏、表格或分组。
-- 标题、主视觉、正文的字号和颜色差异太弱，视觉层级不清。
-- 所有内容页都是同一套标题加 bullets 坐标。
-
-## Verification Record
-
-最终回复必须包含简短验证记录，建议格式：
-
-```text
-验证记录：
-- 回读：已执行 slides +xml-get，实际页数 N / 预期 N。
-- 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
-- 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
-- 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
-```
-
-不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/workflow/error-handling.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`。
+
+## XML Preflight
+
+在真正创建或替换前，至少检查：
+
+- 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
+- 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
+- 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
+- 图片路径正确：`<img src="@...">` 占位符由 `+create` 和 `+add-slide` 处理。
+
+## Failure Order
+
+遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
+
+1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
+2. 用 `slides +xml-get` 回读，确认是否已有部分页面写入。
+3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
+4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
+5. 页面空白、溢出、重叠或越界时，按 [validation-xml.md](validation-xml.md) 运行 `xml_lint.py`；先修复所有 `error`，再对 `warning` 指向的页面和元素做截图复核。
+6. 如果使用 `--slides '[...]'` 字面量，怀疑 shell 转义或截断时改用文件输入：`+create --slide @page-01.xml --slide @page-02.xml`。
+7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时用 `+delete-slide` 删旧页 + `+add-slide` 建新页。
+
+## Symptom Fixes
+
+| 看到的问题 | 处理方式 |
+|-----------|----------|
+| 文字被截断 / 看不全 | 增大 shape 的 `width` 或 `height`，或减少文本量 |
+| 元素重叠 | 调整 `topLeftX` / `topLeftY`，拉开间距 |
+| 页面大面积空白 | 回读确认内容是否写入；若内容存在，再缩小间距或增加主体元素 |
+| 文字和背景色太接近 | 深色背景用浅色文字，浅色背景用深色文字 |
+| 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
+| 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
+| 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符由 `+create` 和 `+add-slide` 替换 |
+| 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
+| 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
+| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
+
+## Common Errors
+
+| 错误码 / 信号 | 含义 | 解决方案 |
+|--------------|------|----------|
+| 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
+| 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
+| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 字面量的 shell 转义或长参数传递问题 | 改用 `--slide @file`（每页一个文件）或 `--slides @deck.json`，并在创建后立即读取 XML 验证 |
+| 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
+| 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
+| 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
+| 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
+| 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
+| 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
+| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
+| validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
+
+## Command-Specific References
+
+- 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](../cli/lark-slides-media-upload.md) 和 [lark-slides-create.md](../cli/lark-slides-create.md)。
+- 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](../cli/lark-slides-replace-slide.md)。
+- 追加/插入单页、`--before-slide-id` 和 `--slide @file` 绕开转义：见 [lark-slides-add-slide.md](../cli/lark-slides-add-slide.md)。

package/skills/lark-slides/references/workflow/slides-editing.md

@@ -0,0 +1,143 @@
+# 编辑已有 PPT：读-改-写闭环
+
+局部编辑走 **shortcut [`+replace-slide`](../cli/lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](../cli/lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
+
+> 生成 XML 前**必读** [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md)。
+
+## 决策树：block_replace vs block_insert
+
+| 需求 | 推荐 action | 理由 |
+|------|------------|------|
+| 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
+| 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
+| 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
+| 整页版式重建、整页坐标重排、改页面背景、删若干元素 | `+update-slide`（每页一次） | 原地整页覆盖，`slide_id` 和页序不变；带原 `id` 的元素保留 id，不带 `id` 的作为新元素插入，遗漏的被删除 |
+
+> **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
+
+## 最小读-改-写闭环
+
+```bash
+PID="xml_presentation_id_here"
+SID="slide_id_here"
+
+# 1. 读原页，从 XML 里挑出要改的块的 3 位 short id（如 bUn / bab）
+lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}"
+
+# 2. 用 +replace-slide 直接改那个块（不需要搬原 XML）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
+```
+
+`slide_id` / 页序不会变。`block_replace` 的 `replacement` 根元素 `id` 会自动注入为 `block_id`，用户手写 XML 时不需要自己加。
+
+> **编写 `--parts` 时只使用标准字段**：`block_replace` 使用 `action` + `block_id` + `replacement`（XML 字符串），`block_insert` 使用 `action` + `insertion`（可选 `insert_before_block_id`）。收到 unknown field 报错时应按上述结构修改字段名，而不是修改字段值。
+
+## `revision_id` 参数
+
+`--revision-id` 默认 `-1`，表示基于当前最新版执行。传具体版本号时，服务端以该版本为 base 应用变更：
+
+```bash
+# 读时拿当前 revision_id
+REV=$(lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
+  --jq '.data.revision_id')
+
+# 写时传该版本号，服务端以此为 base
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"rect\" topLeftX=\"100\" topLeftY=\"100\" width=\"200\" height=\"100\"/>"}]'
+```
+
+注意：传不存在的版本号（超过当前 revision）会返回 3350002 not found；不确定时用 `-1` 即可。
+
+## `--tid` 事务锁
+
+跨请求的并发事务 ID，多人协作长事务才用得上。**单人单次调用留空**即可。
+
+## 两种 action 详解
+
+### block_replace — 整块替换
+
+适合"已知块 ID，要换这块整体内容"的场景。`replacement` 根元素的 `id="<block_id>"` 由 CLI 自动注入（用户手写的 XML 如果没带 `id` 直接省略即可；如果带了错的会被覆盖为正确值）。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts '[{"action":"block_replace","block_id":"bab","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | 固定为 `block_replace` |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读）|
+| `replacement` | 是 | 新 XML 片段；根元素 `id` 会被 CLI 自动注入为 `block_id` |
+
+### block_insert — 整块插入
+
+适合"只想加一个元素，不动现有元素"的场景（典型：给已有页加图）。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$FILE_TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>"),insert_before_block_id:"baa"}]')"
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | 固定为 `block_insert` |
+| `insertion` | 是 | 要插入的完整 XML 片段 |
+| `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页面末尾 |
+
+> **`<img>` 必须用 `file_token`**，不能用外链 URL——先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token。
+
+### 批量 parts
+
+一次 `--parts` 最多 200 条，按数组顺序串行执行。`block_replace` 和 `block_insert` 可以在同一批次混用。举例：一次性把标题块替换、然后在末尾追加一个装饰图。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts '[{"action":"block_replace","block_id":"bab","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"},{"action":"block_insert","insertion":"<img src=\"<file_token>\" topLeftX=\"700\" topLeftY=\"400\" width=\"180\" height=\"100\"/>"}]'
+```
+
+整批作为原子事务：任一条失败整批不生效。失败时后端通常返回 3350001；若响应中带 `failed_part_index` / `failed_reason` 字段，shortcut 会原样透传。
+
+## 大 --parts 用 jq 或 stdin 组装
+
+`--parts` 支持 `@file`（读文件）和 `-`（stdin）作为值来源，适合批量 XML 场景：
+
+```bash
+# 从文件读
+lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
+  --parts @parts.json
+
+# 从 stdin 读
+cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
+  --parts -
+```
+
+## 错误排查
+
+| 现象 | 原因 | 对策 |
+|------|------|------|
+| 3350001，hint 含 "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或实际存在的 `revision_id` |
+| `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 `+media-upload` 拿到的 `file_token` |
+| 3350001（block_replace 返回） | 正常情况下 CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，确认 `block_id` 在当前页存在（重新 `slide.get`），检查 XML 结构是否合法；坐标是否超出 960×540 范围 | — |
+
+## 相关文档
+
+- [lark-slides-replace-slide.md](../cli/lark-slides-replace-slide.md) — +replace-slide shortcut 参数详情
+- [lark-slides-update-slide.md](../cli/lark-slides-update-slide.md) — +update-slide shortcut 参数详情（整页覆盖）
+- [lark-slides-xml-presentation-slide-get.md](../cli/lark-slides-xml-presentation-slide-get.md) — slide.get 参考（拿 `block_id` / `revision_id`）
+- [lark-slides-xml-presentation-slide-replace.md](../cli/lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考（一般直接用 shortcut 即可）
+- [lark-slides-media-upload.md](../cli/lark-slides-media-upload.md) — 上传图片拿 file_token
+- [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md) — XML 元素和属性速查

package/skills/lark-slides/references/workflow/template-editing.md

@@ -0,0 +1,85 @@
+# PPT Template Rewrite Principles
+
+核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
+
+## Import First
+
+如果用户提供的模板是 PPTX 格式，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
+
+直接使用以下命令，不需要先加载 `lark-drive` Skill：
+
+```bash
+lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
+```
+
+可选参数：用 `--name "<title>"` 指定导入后的 Slides 标题；用 `--folder-token <FOLDER_TOKEN>` 指定目标文件夹。若返回 `ready=false` / `timed_out=true`，直接执行返回值里的 `next_command`；等价形式是：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket <TICKET>
+```
+
+## Read Before Editing
+
+导入后必须阅读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。阅读结果是后续编辑的事实来源。
+
+阅读页面时至少判断：
+
+- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
+- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
+- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
+- 原页面的字体、字号、颜色、对齐、层级和留白关系。
+
+## Edit The Imported Slides Directly
+
+理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
+
+- 填写、替换、凝练或删除文字。
+- 替换或补充图片。
+- 更新图表、表格、数字标签或节点标签里的内容。
+- 按需复制、删除或重排模板页。
+- 在源页面没有合适承载位置时，做局部、小范围新增元素。
+
+新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
+
+## Preserve Design
+
+编辑必须严格沿用原版式和字体，只改内容，不做设计。
+
+默认保留：
+
+- 页面布局、视觉层级、留白和对齐关系。
+- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
+- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
+- 模板中不同页型之间的差异。
+
+不要把模板页改造成统一的通用卡片、空白板式布局、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
+
+## Content Only
+
+内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
+
+如果原容器空间不足，优先：
+
+- 凝练文字。
+- 降低字号但保持原字体体系。
+- 拆分到页面已有的邻近容器。
+- 使用模板已有的注释、标签或补充说明区域。
+- 复制同页或同模板中的原生容器样式做局部补充。
+
+不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
+
+## Readback And Tune
+
+完成编辑后必须回读结果，并逐页微调。
+
+回读时重点检查：
+
+- 文字是否溢出、截断、压线或超出容器。
+- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
+- shape 顺序是否导致内容被覆盖或遮住。
+- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
+- 字体、字号、颜色、对齐和层级是否仍贴近原页。
+
+发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
+
+完成标准是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。