@amaster.ai/pi-lark 0.1.8 → 0.1.9

package/skills/lark-note/SKILL.md

@@ -10,7 +10,9 @@ metadata:
 
 # note (v1)
 
-身份：仅使用 `--as user`。使用前阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
+身份：`+detail` 支持 `--as user` / `--as bot`；`+transcript` 仅支持 `--as user`。`note_id` 若由某个身份取得（例如 `vc +detail --as bot`），`+detail` 必须显式沿用同一个 `--as`——不要依赖 profile 默认身份。完整身份延续规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，使用前必读。
+
+`+detail` 返回的 `note_doc_token` / `verbatim_doc_token` / `shared_doc_tokens` 交给 [lark-doc](../lark-doc/SKILL.md) 读正文时，仍要显式带上同一个 `--as`。lark-doc 对普通文档推荐 `--as user`，**不覆盖这些纪要文档 token 的来源身份**。
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
 > 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
@@ -36,13 +38,15 @@ Note 域只接受显式 `note_id`：用户直接提供，或 `docs +fetch` 返
 
 | `note +detail` 结果 | 用户要逐字稿 / 原始记录时 |
 |------|---------------|
-| `normal` + `verbatim_doc_token` 非空 | `docs +fetch --doc <verbatim_doc_token>` |
+| `normal` + `verbatim_doc_token` 非空 | `docs +fetch --doc <verbatim_doc_token>`（沿用 `+detail` 用的身份） |
 | `unknown` + `verbatim_doc_token` 非空 | 先按独立文档处理；不要猜成 unified |
 | `unknown` + 无逐字稿 token | 停止重试并说明无法确定逐字稿入口 |
-| `unified` | `note +transcript --note-id <note_id>` |
+| `unified` | `note +transcript --note-id <note_id>`（仅支持 `--as user`） |
 
 判别键是 `note_display_type`，不是 `verbatim_doc_token` 是否为空：unified 纪要也可能返回非空 `verbatim_doc_token`。
 
+> **bot + unified 的边界**：`+transcript` 目前仅支持 `--as user`。如果 `+detail --as bot` 返回 `unified`，不要静默切到 `--as user` 继续——先停下来向用户说明"该纪要逐字稿只能以 user 身份读取"，只有用户明确同意才切换身份重试。
+
 ## 关键字段
 
 - `note_id`：Note 域唯一入口。
@@ -83,12 +87,12 @@ Note 域只接受显式 `note_id`：用户直接提供，或 `docs +fetch` 返
 3. 获取到文档 Token 后，可使用 `docs +fetch` 读取文档内容，或使用 `drive metas batch_query` 获取文档元信息。
 
 ```bash
-# 1. 从会议获取 note_id
-lark-cli vc +detail --meeting-ids <meeting_id>
+# 1. 从会议获取 note_id（这里以 bot 身份为例）
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
 
-# 2. 用 note_id 拿文档 Token
-lark-cli note +detail --note-id <note_id>
+# 2. 用 note_id 拿文档 Token；沿用第 1 步的身份，不要省略 --as
+lark-cli note +detail --note-id <note_id> --as bot
 
-# 3. 读取纪要文档内容
-lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown
+# 3. 读取纪要文档内容；同样沿用第 1 步的身份
+lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown --as bot
 ```

package/skills/lark-note/references/lark-note-detail.md

@@ -1,11 +1,12 @@
 # note +detail
 
-通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，仅支持 `--as user`。
+通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，支持 `--as user` / `--as bot`。bot 身份下能否读到数据取决于应用对纪要主文档是否有 view 权限。
 
 ## 命令
 
 ```bash
 lark-cli note +detail --note-id <note_id>
+lark-cli note +detail --note-id <note_id> --as bot
 ```
 
 ## `note_id` 来源
@@ -21,6 +22,8 @@ lark-cli note +detail --note-id <note_id>
 | `note_doc_token` | 读纪要正文 / 总结 / 待办 / 章节：`docs +fetch --doc <note_doc_token>` |
 | `note_display_type=normal` + `verbatim_doc_token` | 读逐字稿：`docs +fetch --doc <verbatim_doc_token>` |
 | `note_display_type=unknown` + `verbatim_doc_token` | 先按普通独立逐字稿文档读取；不要猜成 unified |
-| `note_display_type=unified` | 读逐字稿 / 原始记录：转 [`note +transcript`](lark-note-transcript.md) |
+| `note_display_type=unified` | 读逐字稿 / 原始记录：转 [`note +transcript`](lark-note-transcript.md)（仅支持 `--as user`） |
 
 判别键是 `note_display_type`。即使 unified 纪要返回了非空 `verbatim_doc_token`，逐字稿仍按 unified 路由。
+
+> **bot + unified 的边界**：如果本命令用 `--as bot` 拿到 `note_display_type=unified`，`note +transcript` 只支持 `--as user`，不能直接沿用 bot 身份。停下来向用户说明这个边界，只有用户明确同意才切到 `--as user` 继续，不要静默切换身份。

package/skills/lark-note/references/lark-note-transcript.md

@@ -2,6 +2,8 @@
 
 只在 `note +detail` 已确认 `note_display_type=unified` 时使用。普通纪要逐字稿是独立 Docx 文档，应回到 [lark-doc](../../lark-doc/SKILL.md) 读取 `verbatim_doc_token`。
 
+只支持 `--as user`，不支持 `--as bot`。如果 `note +detail --as bot` 返回 `unified`，不要在这里静默省略 `--as` 或改用 user 身份继续——先停下来向用户说明"该纪要逐字稿只能以 user 身份读取"，只有用户明确同意才切换身份重试。
+
 ```bash
 lark-cli note +transcript --note-id NOTE_ID
 ```

package/skills/lark-shared/SKILL.md

@@ -64,6 +64,32 @@ LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli a
 - **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足
 
 
+### 身份延续（跨命令工作流）
+
+身份是**整个工作流的状态**，不是单条命令的局部参数。CLI 不会在进程之间继承"上一步用的身份"——省略 `--as` 不代表"保持当前身份"，而是把身份选择交回下面这条优先级链：
+
+```text
+显式 --as > profile default-as > credential auto-detect
+```
+
+因此，只要用户显式选择了身份，或某个 ID / Token 是通过某个身份取得的（例如 `vc +detail --as bot` 返回的 `note_id`），**后续每一条消费该 ID/Token 的命令都必须显式带上相同的 `--as`**，跨 skill 传递也不例外：
+
+- 禁止依赖 profile 默认身份让后续命令"自动"沿用同一身份。
+- 禁止仅仅因为遇到权限错误就切换身份去绕过它——先如实报告，只有用户明确同意才切换。
+- 下游命令根本不支持来源身份时（如 `--as bot` 拿到的 `note_id` 指向 `note_display_type=unified`，而 `note +transcript` 仅支持 `--as user`），停止并向用户说明这个边界，不要静默省略 `--as` 把身份交给默认值。
+- 命令支持的精确身份以 `<command> --help` / `schema` 为准；各 skill 的身份小节只标注会影响路由决策的例外，不重复维护完整矩阵。
+
+```bash
+# GOOD — note_id 来自 bot 链路，下一步显式沿用 bot
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
+lark-cli note +detail --note-id <note_id> --as bot
+lark-cli docs +fetch --doc <note_doc_token> --as bot
+
+# BAD — 省略 --as，身份可能被 profile 默认值悄悄换成 user
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
+lark-cli note +detail --note-id <note_id>
+```
+
 ### 权限不足处理
 
 遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
@@ -73,6 +99,16 @@ LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli a
 - `console_url`：飞书开发者后台的权限配置链接
 - `hint`：建议的修复命令
 
+**missing_scope 与资源 ACL（无权访问某具体资源）是两类不同问题**，恢复方式也不同：
+
+| 失败类型 | user | bot |
+|---------|---------|---------|
+| missing scope（应用/用户完全没有这个权限） | `auth login --scope ...` | 使用错误中的 `console_url` 去开发者后台开通，**禁止** `auth login` |
+| 资源 ACL（有 scope，但对这一条具体资源没有访问权限） | 请求资源所有者给当前用户授权 | 请求资源所有者给当前应用/bot 授权 |
+| 资源在当前身份下不可见 | 保持当前身份，如实报告不可见，不要切换身份重试 | 保持当前身份，如实报告不可见，不要切换身份重试 |
+
+任何权限恢复完成后，都必须用**触发错误时的原身份**重试，不要在恢复过程中换成另一个身份。
+
 #### Bot 身份（`--as bot`）
 
 将错误中的 `console_url` 原样提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。

package/skills/lark-slides/SKILL.md

@@ -38,8 +38,8 @@ metadata:
 - `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。
 - `<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。
 - 填充渐变颜色必须用 `<fill><fillColor color="linear-gradient(135deg, rgba(R,G,B,A) 0%, rgba(R,G,B,A) 100%)"/></fill>`。
-- 编辑页面前必须阅读 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
-- 绘制图表前必须阅读 [`slides_chart_demo.xml`](references/slides_chart_demo.xml)。
+- 编辑页面前必须阅读 [`workflow/slides-editing.md`](references/workflow/slides-editing.md)。
+- 绘制图表前必须阅读 [`xml/slides_chart_demo.xml`](references/xml/slides_chart_demo.xml)。
 - 当用户要求无损复述历史上下文时，必须无损复述以上权威经验、必读的技能文档（需要重新阅读）和易错元素语法（尤其是 `<table>` 和 `<chart>`）。
 
 ## 豆包设计原则
@@ -79,26 +79,26 @@ metadata:
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
-| 新建 PPT | 先规划 `slide_plan.json`，再按页数选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`lark-slides-create.md`、`slides +create`、`slides +add-slide`、`lark-slides-add-slide.md`（两步创建逐页添加） |
-| 用户要求使用模板，或提供 PPTX 文件要求修改、美化 | 将模板导入为 Slides 再编辑 | `lark-slides-pptx-template-workflows.md` |
-| 编辑单个标题、文本块、图片或局部元素 | 块级替换/插入，**只动点名的 block，同页其他元素不受影响**；不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
+| 新建 PPT | 先规划 `slide_plan.json`，再按页数选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`cli/lark-slides-create.md`、`slides +create`、`slides +add-slide`、`cli/lark-slides-add-slide.md`（两步创建逐页添加） |
+| 用户要求使用模板，或提供 PPTX 文件要求修改、美化 | 将模板导入为 Slides 再编辑 | `workflow/template-editing.md` |
+| 编辑单个标题、文本块、图片或局部元素 | 块级替换/插入，**只动点名的 block，同页其他元素不受影响**；不改页序 | `slides +replace-slide`、`cli/lark-slides-replace-slide.md` |
 | 一页改动很多（批量字体/配色）、要改页面背景、要删掉若干元素 | 整页覆盖，`slide_id` 和页序不变；带原 `id` 写回的元素保留 id，不带 `id` 的会作为新元素插入并拿到新 id；**代价是没写进 `--content` 的元素会被删除，所以改个别元素不要用它** | `slides +update-slide`、`lark-slides-update-slide.md` |
-| 给已有 PPT 追加或插入页面 | 一次一页，`--slide` 支持 `@file` 绕开 shell 转义 | `slides +add-slide`、`lark-slides-add-slide.md` |
-| 删除页面 | 按 `slide_id` 单页删除，删前先回读确认 | `slides +delete-slide`、`lark-slides-delete-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get`、`lark-slides-xml-presentations-get.md` |
-| 查看或回滚历史版本 | 先用 `+history-list` 找 `history_version_id`，再 `+history-revert`，必要时 `+history-revert-status` 轮询 | [`lark-slides-history.md`](references/lark-slides-history.md) |
-| 获取幻灯片页面截图 | 按页码用 `--slide-number`，按 ID 用 `--slide-id`；单张用 `--output`，批量或全量用 `--output-dir`，每批最多 10 页串行执行；截图目录复用同一任务的 deck/task 标识，后续读取返回的实际路径 | `slides +screenshot`、`lark-slides-screenshot.md` |
-| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`、`lark-slides-media-upload.md`，或 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符 |
-| 绘制图表 | 原生图表（柱状、条形、折线、面积、饼（环）、雷达、组合图）用 `<chart>`，其他（漏斗图、金字塔图、象限图、矩阵图等）用 `<shape>` + `<line>` 模拟 | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` |
-| 绘制表格 | 优先用 `rect` 和 `text` 模拟，其他用 `<table>` | `xml-schema-quick-ref.md` |
-| 使用图标 | 禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`，图标必须填充颜色并和背景有足够对比，禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` |
-| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
+| 给已有 PPT 追加或插入页面 | 一次一页，`--slide` 支持 `@file` 绕开 shell 转义 | `slides +add-slide`、`cli/lark-slides-add-slide.md` |
+| 删除页面 | 按 `slide_id` 单页删除，删前先回读确认 | `slides +delete-slide`、`cli/lark-slides-delete-slide.md` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get`、`cli/lark-slides-xml-presentations-get.md` |
+| 查看或回滚历史版本 | 先用 `+history-list` 找 `history_version_id`，再 `+history-revert`，必要时 `+history-revert-status` 轮询 | [`cli/lark-slides-history.md`](references/cli/lark-slides-history.md) |
+| 获取幻灯片页面截图 | 按页码用 `--slide-number`，按 ID 用 `--slide-id`；单张用 `--output`，批量或全量用 `--output-dir`，每批最多 10 页串行执行；截图目录复用同一任务的 deck/task 标识，后续读取返回的实际路径 | `slides +screenshot`、`cli/lark-slides-screenshot.md` |
+| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`、`cli/lark-slides-media-upload.md`，或 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符 |
+| 绘制图表 | 原生图表（柱状、条形、折线、面积、饼（环）、雷达、组合图）用 `<chart>`，其他（漏斗图、金字塔图、象限图、矩阵图等）用 `<shape>` + `<line>` 模拟 | `xml/xml-schema-quick-ref.md`、`xml/slides_chart_demo.xml` |
+| 绘制表格 | 优先用 `rect` 和 `text` 模拟，其他用 `<table>` | `xml/xml-schema-quick-ref.md` |
+| 使用图标 | 禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`，图标必须填充颜色并和背景有足够对比，禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`xml/iconpark.md` |
+| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `workflow/error-handling.md`、`workflow/validation-xml.md` |
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
 
-**CRITICAL — 查看或回滚历史版本前，MUST 先读取 [`lark-slides-history.md`](references/lark-slides-history.md)。回滚接口只接受 `history_version_id`，不要把 `revision_id` 直接传给 `+history-revert`。**
+**CRITICAL — 查看或回滚历史版本前，MUST 先读取 [`cli/lark-slides-history.md`](references/cli/lark-slides-history.md)。回滚接口只接受 `history_version_id`，不要把 `revision_id` 直接传给 `+history-revert`。**
 
-**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
+**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml/xml-schema-quick-ref.md](references/xml/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
 
@@ -106,15 +106,15 @@ metadata:
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
-**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create`、`slides +add-slide` 或 `slides +update-slide` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
+**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create`、`slides +add-slide` 或 `slides +update-slide` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_lint.py`](scripts/xml_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
 
-**CRITICAL — 创建、大幅改写或每次通过 `slides +update-slide` 整页写回后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
+**CRITICAL — 创建、大幅改写或整页写回后，MUST 按 [workflow/validation-xml.md](references/workflow/validation-xml.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_lint.py`](scripts/xml_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
 
-**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
+**CRITICAL — 创建前自检或失败排障时，MUST 按 [workflow/error-handling.md](references/workflow/error-handling.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 
-**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；一页里改动很多（例如批量换字体）、要改背景、或要删掉若干元素时用 [`+update-slide`](references/lark-slides-update-slide.md) 整页覆盖（`slide_id` 和页序不变，但没写进 `--content` 的元素会被删除）；**多页大改就对每一页各跑一次 `+update-slide`**。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/cli/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；一页里改动很多（例如批量换字体）、要改背景、或要删掉若干元素时用 [`+update-slide`](references/cli/lark-slides-update-slide.md) 整页覆盖（`slide_id` 和页序不变，但没写进 `--content` 的元素会被删除）；**多页大改就对每一页各跑一次 `+update-slide`**。选择 action 和完整读-改-写流程见 [`workflow/slides-editing.md`](references/workflow/slides-editing.md)。
 
-**用户要求使用模板**：按 [lark-slides-pptx-template-workflows.md](references/lark-slides-pptx-template-workflows.md) 处理。
+**用户要求使用模板**：按 [workflow/template-editing.md](references/workflow/template-editing.md) 处理。
 
 ## 身份选择
 
@@ -136,29 +136,29 @@ lark-cli auth login --domain slides
 
 ## 执行前必做
 
-> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
+> **重要**：`references/xml/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
 
 高频只读：
 
-- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)
+- [xml/xml-schema-quick-ref.md](references/xml/xml-schema-quick-ref.md)
 - [planning-layer.md](references/planning-layer.md)（新建 / 大幅改写）
 - [visual-planning.md](references/visual-planning.md)（新建 / 大幅改写）
 - [asset-planning.md](references/asset-planning.md)（新建 / 大幅改写）
-- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后）
+- [workflow/validation-xml.md](references/workflow/validation-xml.md)（创建 / 大幅改写后）
 
 调用相关命令前必须读取相关的文档以了解命令的使用方式：
 
-- 创建：[`lark-slides-create.md`](references/lark-slides-create.md)、[`lark-slides-add-slide.md`](references/lark-slides-add-slide.md)（逐页添加 / 给已有 PPT 追加页面）
-- 删除页面：[`lark-slides-delete-slide.md`](references/lark-slides-delete-slide.md)
-- 阅读：[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-update-slide.md`](references/lark-slides-update-slide.md)
-- 历史版本：[`lark-slides-history.md`](references/lark-slides-history.md)
-- 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
-- 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
-- 图表：[`slides_chart_demo.xml`](references/slides_chart_demo.xml)
-- 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
-- 排障：[`troubleshooting.md`](references/troubleshooting.md)
-- 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
+- 创建：[`cli/lark-slides-create.md`](references/cli/lark-slides-create.md)、[`cli/lark-slides-add-slide.md`](references/cli/lark-slides-add-slide.md)（逐页添加 / 给已有 PPT 追加页面）
+- 删除页面：[`cli/lark-slides-delete-slide.md`](references/cli/lark-slides-delete-slide.md)
+- 阅读：[`cli/lark-slides-xml-presentations-get.md`](references/cli/lark-slides-xml-presentations-get.md)
+- 编辑：[`workflow/slides-editing.md`](references/workflow/slides-editing.md)、[`cli/lark-slides-replace-slide.md`](references/cli/lark-slides-replace-slide.md)、[`lark-slides-update-slide.md`](references/cli/lark-slides-update-slide.md)
+- 历史版本：[`cli/lark-slides-history.md`](references/cli/lark-slides-history.md)
+- 截图：[`cli/lark-slides-screenshot.md`](references/cli/lark-slides-screenshot.md)
+- 图片：[`cli/lark-slides-media-upload.md`](references/cli/lark-slides-media-upload.md)
+- 图表：[`xml/slides_chart_demo.xml`](references/xml/slides_chart_demo.xml)
+- 图标：[`xml/iconpark.md`](references/xml/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
+- 排障：[`workflow/error-handling.md`](references/workflow/error-handling.md)
+- 完整协议：[`xml/slides_xml_schema_definition.xml`](references/xml/slides_xml_schema_definition.xml)
 
 
 ## Workflow
@@ -200,9 +200,9 @@ lark-cli auth login --domain slides
 ```text
 Step 1: 需求分析 & 读取知识
   - 分析主题、受众、页数、风格；
-  - 若用户要求使用模板，按 lark-slides-pptx-template-workflows.md 处理
-  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
-  - 涉及图表读取 slides_chart_demo.xml
+  - 若用户要求使用模板，按 workflow/template-editing.md 处理
+  - 读取 xml/xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
+  - 涉及图表读取 xml/slides_chart_demo.xml
 
 Step 2: 生成大纲 → 写入 slide_plan.json
   - 生成结构化大纲
@@ -212,12 +212,12 @@ Step 2: 生成大纲 → 写入 slide_plan.json
 Step 3: 按 slide_plan.json 生成 XML → 创建
   - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
   - 缺少真实素材时必须用 `fallback_if_missing` 生成替代图片，不要留空
-  - 读 lark-slides-create.md 定一步创建还是两步创建，并据此构造 `slides +create`；两步创建再读 lark-slides-add-slide.md 用 `+add-slide` 逐页添加
-  - 图片按 lark-slides-media-upload.md 处理；复杂 XML、转义和 3350001 排查按 troubleshooting.md 执行
+  - 读 cli/lark-slides-create.md 定一步创建还是两步创建，并据此构造 `slides +create`；两步创建再读 cli/lark-slides-add-slide.md 用 `+add-slide` 逐页添加
+  - 图片按 cli/lark-slides-media-upload.md 处理；复杂 XML、转义和 3350001 排查按 workflow/error-handling.md 执行
 
 Step 4: 审查 & 交付
-  - 创建完成后，必须用 `slides +xml-get --presentation <xml_presentation_id>` 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 创建完成后，必须用 `slides +xml-get --presentation <xml_presentation_id>` 读取全文 XML，并按 workflow/validation-xml.md 做显式验证记录，包括 XML 文本重叠检查
+  - 失败或部分成功按 workflow/error-handling.md 处理；局部问题优先用 `+replace-slide` 修正
   - 没问题 → 交付：使用 NotifyHuman 工具交付 PPT 链接
 ```
 
@@ -283,14 +283,14 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+create`](references/lark-slides-create.md) | 创建 PPT，可选一步添加页面 |
-| [`+add-slide`](references/lark-slides-add-slide.md) | 向已有演示文稿追加或插入**一页**（`--before-slide-id` 控制位置），XML 支持 `@file` / stdin，`<img src="@./path">` 占位符自动上传 |
-| [`+delete-slide`](references/lark-slides-delete-slide.md) | 按 `slide_id` 删除**一页** |
-| [`+xml-get`](references/lark-slides-xml-presentations-get.md) | 读取全文 XML，用 `--presentation` 指定演示文稿的 `xml_presentation_id`，用 `--output` 把 XML 存到本地文件（必须是 CWD 内的相对路径，如 `.lark-slides/plan/<deck>/readback.xml`） |
-| [`+screenshot`](references/lark-slides-screenshot.md) | 把幻灯片页面截图保存为本地图片；用 `--slide-number` 指定页码（从 1 开始，多页重复传入）或用 `--slide-id` 指定页面；单张用 `--output .lark-slides/screenshots/<deck-or-task-id>/page-01`，批量用 `--output-dir .lark-slides/screenshots/<deck-or-task-id>`（一次最多 10 页）；后续必须读取返回的 `output` / `screenshots[].path` |
-| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
-| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
-| [`+update-slide`](references/lark-slides-update-slide.md) | 把一整页 XML 交给已有页面，页面变成 `--content` 描述的样子；能一次改样式/插入/删除/备注/背景，`slide_id` 和页序不变。**没写进 `--content` 的元素会被删除** |
+| [`+create`](references/cli/lark-slides-create.md) | 创建 PPT，可选一步添加页面 |
+| [`+add-slide`](references/cli/lark-slides-add-slide.md) | 向已有演示文稿追加或插入**一页**（`--before-slide-id` 控制位置），XML 支持 `@file` / stdin，`<img src="@./path">` 占位符自动上传 |
+| [`+delete-slide`](references/cli/lark-slides-delete-slide.md) | 按 `slide_id` 删除**一页** |
+| [`+xml-get`](references/cli/lark-slides-xml-presentations-get.md) | 读取全文 XML，用 `--presentation` 指定演示文稿的 `xml_presentation_id`，用 `--output` 把 XML 存到本地文件（必须是 CWD 内的相对路径，如 `.lark-slides/plan/<deck>/readback.xml`） |
+| [`+screenshot`](references/cli/lark-slides-screenshot.md) | 把幻灯片页面截图保存为本地图片；用 `--slide-number` 指定页码（从 1 开始，多页重复传入）或用 `--slide-id` 指定页面；单张用 `--output .lark-slides/screenshots/<deck-or-task-id>/page-01`，批量用 `--output-dir .lark-slides/screenshots/<deck-or-task-id>`（一次最多 10 页）；后续必须读取返回的 `output` / `screenshots[].path` |
+| [`+media-upload`](references/cli/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
+| [`+replace-slide`](references/cli/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
+| [`+update-slide`](references/cli/lark-slides-update-slide.md) | 把一整页 XML 交给已有页面，页面变成 `--content` 描述的样子；能一次改样式/插入/删除/备注/背景，`slide_id` 和页序不变。**没写进 `--content` 的元素会被删除** |
 
 没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
@@ -304,12 +304,12 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 ## 核心规则
 
 1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
-2. **创建流程**：新建演示文稿用 `slides +create`，一步创建还是两步创建按 [`lark-slides-create.md`](references/lark-slides-create.md) 判断
+2. **创建流程**：新建演示文稿用 `slides +create`，一步创建还是两步创建按 [`cli/lark-slides-create.md`](references/cli/lark-slides-create.md) 判断
 3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
-4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内；注意 `<content>` 只是 XML 元素，不是 `--parts` 的字段名——part 里装 XML 的字段，`block_replace` 是 `replacement`，`block_insert` 是 `insertion`
+4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内；不要混淆 XML 元素 `<content>` 和 `--parts` 的 JSON 字段：编写 `--parts` 时，`block_replace` 装载 XML 使用标准字段 `replacement`，`block_insert` 使用 `insertion`
 5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
 6. **删除谨慎**：删除不可逆，删前先回读确认 `slide_id`
 7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；一页改动很多或要改背景用 `+update-slide` 整页覆盖（保 `slide_id` 和页序），多页整页重建就对每页各跑一次 `+update-slide`，不要用 `slides +create` 新建整份 PPT；追加/插入单页用 `+add-slide`、删除单页用 `+delete-slide`，只有这些 shortcut 未覆盖的参数才手动调 `slide.create` / `slide.delete`
 8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传，或在 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
-> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
+> **注意**：如果 md 内容与 `xml/slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

package/skills/lark-slides/references/cli/lark-slides-add-slide.md

@@ -0,0 +1,92 @@
+# slides +add-slide（向已有演示文稿追加/插入单页）
+
+向已有演示文稿添加**一页**。这是两步创建流程的第二步：先 `+create` 建空壳，再逐页 `+add-slide`；也用于给已有 PPT 追加新页。
+
+`--presentation` 接受 token / `/slides/` URL / `/wiki/` URL（wiki 自动解析），`--slide` 直接收 XML（支持 `@file` 和 stdin，复杂 XML 走文件可绕开 shell 转义），`<img src="@./local.png">` 占位符自动上传并替换成 `file_token`。
+
+**CRITICAL — 提交前必须先跑版式 lint**：把待提交的 `<slide>` XML 存成本地文件，运行 [`scripts/xml_lint.py`](../../scripts/xml_lint.py)，`summary.error_count` 必须为 0。
+
+## 命令
+
+```bash
+# 追加到末尾（XML 直接作为参数）
+lark-cli slides +add-slide --as user \
+  --presentation "$PID" \
+  --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data></data></slide>'
+
+# XML 从文件读（推荐：避免 shell 转义和长参数截断）
+lark-cli slides +add-slide --as user \
+  --presentation "$PID" \
+  --slide @page3.xml
+
+# XML 从 stdin 读
+cat page3.xml | lark-cli slides +add-slide --as user --presentation "$PID" --slide -
+
+# 插到某页之前
+lark-cli slides +add-slide --as user \
+  --presentation "$PID" \
+  --slide @cover.xml \
+  --before-slide-id "$SID"
+
+# wiki 链接（CLI 自动 wiki.spaces.get_node 解析，并校验 obj_type=slides）
+lark-cli slides +add-slide --as user \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" \
+  --slide @page3.xml
+
+# 预览请求，不实际写入
+lark-cli slides +add-slide --presentation "$PID" --slide @page3.xml --dry-run
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--slide` | 是 | 一个完整的 `<slide>...</slide>` 文档；支持字面量、`@file`、stdin `-` |
+| `--before-slide-id` | 否 | 插到该 `slide_id` 之前；**不传就是追加到末尾** |
+| `--revision-id` | 否 | 演示文稿版本号，默认 `-1`（最新）；传具体版本号做乐观锁 |
+| `--dry-run` | 否 | 打印将要发起的请求（含图片上传步骤），不写入 |
+
+`@file` 路径**必须在 CWD 内**（如 `@./plan/page3.xml`）；绝对路径和 `../` 会被拒绝并报 `unsafe file path`。
+
+## 本地图片：`@路径` 占位符
+
+XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的本地文件上传到这份演示文稿（`parent_type=slide_file`），再把 `src` 替换成返回的 `file_token`，最后才提交页面。
+
+占位符路径按**执行命令时的 CWD** 解析，跟 `--slide @file` 所在目录无关；`@./assets/x.png` 找的是 `$PWD/assets/x.png`。
+
+```bash
+lark-cli slides +add-slide --as user \
+  --presentation "$PID" \
+  --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
+```
+
+- 文件不存在、不是普通文件、超过 20 MB，都在**调用任何接口之前**报错，不会留下半成品。
+- 去重只在**单次调用内**生效：多页共用同一张图时，逐页循环会把它每页重传一次。这种图先用 [`+media-upload`](lark-slides-media-upload.md) 传一次，把 `file_token` 写进各页的 `src`。
+
+## 成功输出
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id",
+  "revision_id": 42,
+  "before_slide_id": "slide_example_target_id",
+  "images_uploaded": 1,
+  "issues": "[issue=unsupported_attr tag=<strong> attr=style]"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `slide_id` | 新创建页面的唯一标识 |
+| `issues` | 字符串，**只在服务端丢弃过内容时才出现**：页面创建成功，但括号里列出的标签/属性没写进去。出现就必须 `+screenshot` 复核，别当纯警告忽略；干净提交时这个字段不返回 |
+
+## 常见错误
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| `--slide is not a single complete <slide> document` | 传了 `<presentation>` 整份 XML，或多个 `<slide>` 拼在一起 | 一次只传一页，根元素必须是 `<slide>` |
+| `--slide cannot be empty` | `@file` 指向空文件，或 stdin 没内容 | 检查文件内容 |
+| 3350001 | XML 结构/转义有问题；**或 `--before-slide-id` 不是有效 `slide_id`** | 优先改用 `--slide @file` 绕开 shell 转义；插页失败先 `+xml-get` 回读确认 `slide_id`；再按 [workflow/error-handling.md](../workflow/error-handling.md) 排查 |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

package/skills/lark-slides/references/cli/lark-slides-create.md

@@ -0,0 +1,176 @@
+
+# slides +create（创建飞书幻灯片）
+
+创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
+
+提交源必须是直接生成的单页 `<slide>` XML。禁止从完整 `<presentation>` XML 解析、拆分、重序列化出 slide 数组再提交。
+
+本命令只从零创建演示文稿，没有导入本地 PPT 文件的参数。要把已有 PPTX 变成 Slides，用 `drive +import --file <x.pptx> --type slides`，再在导入结果上编辑，流程见 [template-editing.md](../workflow/template-editing.md)。
+
+## 创建方式选择
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 不超过 10 页 | 每页存一个 XML 文件，`slides +create --slide @page-01.xml --slide @page-02.xml ...` 一步创建 |
+| 超过 10 页 | **两步创建**：先 `slides +create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 |
+| 已有 PPT 继续追加或插入页面 | 使用 [`+add-slide`](lark-slides-add-slide.md)，必要时配合 `--before-slide-id` |
+
+> [!IMPORTANT]
+> `slides +create` 带页面时底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
+
+**CRITICAL — 提交前必须先跑版式 lint**：把待提交的 `<slide>` XML 存成本地文件，运行 [`scripts/xml_lint.py`](../../scripts/xml_lint.py)，`summary.error_count` 必须为 0。
+
+## 命令
+
+```bash
+# 创建空白 PPT
+lark-cli slides +create --title "项目汇报"
+
+# 创建 PPT + 添加页面：每页一个 XML 文件，重复 --slide，顺序即页序
+lark-cli slides +create --as user --title "项目汇报" \
+  --slide @.lark-slides/plan/project/slide-01.xml \
+  --slide @.lark-slides/plan/project/slide-02.xml
+
+# 已有组装好的 JSON 数组：从文件或 stdin 读
+lark-cli slides +create --as user --title "项目汇报" --slides @./deck.json
+cat deck.json | lark-cli slides +create --as user --title "项目汇报" --slides -
+
+# 以应用身份创建（自动授权当前用户）
+lark-cli slides +create --title "项目汇报" --as bot
+
+# 预览（不执行）
+lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run
+```
+
+## 返回值
+
+工具成功执行后，返回一个 JSON 对象，包含以下字段：
+
+- **`xml_presentation_id`**（string）：演示文稿的唯一标识符，后续添加页面时需要此 ID
+- **`title`**（string）：演示文稿标题
+- **`url`**（string，可选）：演示文稿的在线链接，如有返回则务必展示给用户（需要 drive 相关权限；若获取失败则不返回此字段）
+- **`revision_id`**（integer）：演示文稿版本号
+- **`slide_ids`**（string[]，可选）：带页面创建时返回，成功添加的页面 ID 列表
+- **`slides_added`**（integer，可选）：带页面创建时返回，成功添加的页面数量
+- **`images_uploaded`**（integer，可选）：页面 XML 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
+- **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 不带页面参数时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。
+>
+> 带了页面时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
+>
+> 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该演示文稿的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权
+> - `status = failed`：演示文稿已创建成功，但自动授权用户失败
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） |
+| `--slide` | 否 | 一页 `<slide>` XML，或 `@路径`；可重复，最多 10 次。格式见[页面输入形式](#页面输入形式) |
+| `--slides` | 否 | 页面 XML 的 JSON 字符串数组，最多 10 个；支持 `@文件` 和 `-`（stdin）。格式见[页面输入形式](#页面输入形式) |
+
+10 页是 CLI 的上限，服务端每次只接收一页。超过 10 页时先用 `+create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加。
+
+两种形式的每一页都会在发请求前校验成「单个完整的 `<slide>` 文档」。不合格的页在创建演示文稿之前报错并指出页序号，不会留下空壳演示文稿。
+
+## 页面输入形式
+
+页面内容有 `--slide` 和 `--slides` 两种传法，二选一，同时传会报错。
+
+两种形式的 `@路径` 都必须是 CWD 内的相对路径（如 `./slide-01.xml`）；绝对路径和 `../` 会被拒（报 `invalid file path`）。XML 写在别的目录时，先 `cd` 过去或把文件拷进 CWD 再执行。
+
+### `--slide`：一页一个文件
+
+可重复，重复次数即页数，出现顺序即页序。值是一页完整的 `<slide>` XML，或读取该 XML 的 `@路径`。
+
+文件内容就是这一页 XML 本身，外面没有引号或方括号：
+
+```xml
+<slide xmlns="https://www.larkoffice.com/sml/2.0">
+  <data>…第1页…</data>
+</slide>
+```
+
+文件内容不需要转义：引号、换行、中文原样写。
+
+### `--slides`：一个 JSON 数组
+
+值是 JSON 字符串数组，每个元素是一整页 XML，支持 `@文件` 和 `-`（stdin）。
+
+文件内容是一个 JSON 文档，XML 以 JSON 字符串出现，其中的 `"` 写作 `\"`，换行写作 `\n`：
+
+```json
+[
+  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data>…第1页…</data></slide>",
+  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data>…第2页…</data></slide>"
+]
+```
+
+数组元素是页面 XML 原文。包装成 API 所需的 `{"slide": {"content": …}}` 并逐页调用由 CLI 完成。
+
+> [!WARNING]
+> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议改用 `--slide @page-01.xml` 逐页传文件。
+
+## 本地图片：`@<path>` 占位符
+
+`<img>` 元素的 `src` 属性如果以 `@` 开头，CLI 会把它当作本地文件路径，自动上传到当前演示文稿，并把占位符替换为返回的 `file_token`。
+
+`slide-01.xml`：
+
+```xml
+<slide xmlns="https://www.larkoffice.com/sml/2.0">
+  <data>
+    <img src="@./assets/chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/>
+  </data>
+</slide>
+```
+
+```bash
+lark-cli slides +create --as user --title "图测试" --slide @./slide-01.xml
+```
+
+行为：
+
+- 路径相对于**当前工作目录**（CWD）解析；**必须是 CWD 内的相对路径**（如 `./pic.png`、`./assets/x.png`）
+- 同一份图被多次引用时**只上传一次**（按路径去重）
+- `src` 不以 `@` 开头的会原样保留，但**只允许写 `slides +media-upload` 拿到的 `file_token`**；**禁止写 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 通常显示破图。要用网图必须先下载到 CWD 内、再走上传流程
+- 单张图片最大 20 MB（slides upload API 不支持分片上传）
+- 校验阶段就会检查所有占位符文件存在及大小；缺文件或超限直接报错，不会创建空白 PPT 占位
+- 创空白 PPT → 上传所有图 → 替换 token → 逐页创建 slide，按这个顺序执行
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`@/abs/path/x.png` 或 `@../up/x.png` 这种会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+## 创建后续步骤
+
+创建空白 PPT 时，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
+
+```bash
+# 第 1 步：创建空白 PPT
+PRES_ID=$(lark-cli slides +create --title "项目汇报" --jq '.data.xml_presentation_id')
+
+# 第 2 步：逐页添加（--slide 支持 @file，复杂 XML 优先走文件）
+lark-cli slides +add-slide --as user \
+  --presentation "$PRES_ID" \
+  --slide @.lark-slides/plan/<deck>/page1.xml
+```
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 400 | 参数错误 | 检查参数格式是否正确 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:create` 和 `slides:presentation:write_only` scope |
+
+## 相关命令
+
+- [slides +add-slide](lark-slides-add-slide.md) — 追加/插入单页（两步创建的第二步）
+- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容并保存到本地文件