@coze/cli 0.1.8-alpha.618a4c → 0.2.0-alpha.9f6611

package/skills/using-coze-cli/coze-claw/references/coze-claw-agent-routing.md

@@ -0,0 +1,45 @@
+# Agent routing contract
+
+## 路由目标
+
+- `/coze-cli`：显式命中 Coze CLI skill
+- `/coze`：`/coze-cli` 的短别名，行为完全一致
+
+## 适用范围
+
+- 此规则适用于所有 Claw 子模块，不只限于 `session message`
+- 只要最终会把用户正文转发到 Claw，会消费同一份规范化结果的链路都应遵守
+- 当前至少覆盖：
+  - 普通消息链路：[`coze-claw-message.md`](coze-claw-message.md)
+  - PPT 场景：[`coze-claw-ppt.md`](coze-claw-ppt.md)
+  - 播客场景：[`coze-claw-podcast.md`](coze-claw-podcast.md)
+
+## 规范化规则
+
+1. 只移除首个路由 token
+2. 保留剩余正文中的所有业务 token
+3. 不改写正文中的中间 `/coze-cli`
+4. 不吞掉 `@PPT`、`@播客`、文件引用、引号和换行
+
+## 正例
+
+- 输入：`/coze-cli 制作一个介绍潮汕美食的 PPT`
+  输出正文：`制作一个介绍潮汕美食的 PPT`
+- 输入：`/coze-cli @PPT 制作介绍海南美食的 PPT`
+  输出正文：`@PPT 制作介绍海南美食的 PPT`
+- 输入：`/coze 制作一个冒泡排序 markdown`
+  输出正文：`制作一个冒泡排序 markdown`
+
+## 反例
+
+- 错误：把 `/coze-cli` 原样发给 `coze session message`
+- 错误：移除 `@PPT`
+- 错误：移除 `@播客`
+- 错误：把正文里的 `/coze-cli` 全局替换掉
+
+## 最小验收样例
+
+1. 不带前缀的自然语言，允许模型自行命中 skill，但不保证确定性
+2. 带 `/coze-cli` 的请求，必须命中 skill
+3. 命中后真正发给 Claw 的 message 不包含 `/coze-cli`
+4. 同一规则适用于 `@PPT`、`@播客` 等子模块入口

package/skills/using-coze-cli/coze-claw/references/coze-claw-artifacts.md

@@ -0,0 +1,52 @@
+# claw artifact commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-message.md`](coze-claw-message.md)。
+
+本文档覆盖普通 session 产物处理。PPT 产物见 [`coze-claw-ppt.md`](coze-claw-ppt.md)。
+
+## 核心区别
+
+| 字段 | 含义 | 处理方式 |
+|------|------|----------|
+| `file_url` | 可下载或可直接交付的 URL | 可传给 `file download` |
+| `file_uri` | 平台内部文件引用 | 不能直接下载，需要先解析 |
+
+Agent 不要猜测 `file_uri` 的公网 URL。
+
+## file download
+
+```bash
+coze session file download "<file_url>" --format json
+coze session file download "<file_url>" --output-path ./downloads/result.md --format json
+```
+
+关键输出：
+
+| 字段 | 含义 |
+|------|------|
+| `status` | `saved` |
+| `path` | 本地保存路径 |
+| `filename` | 文件名 |
+| `size` | 文件大小 |
+| `url` | 原始下载 URL |
+
+如果用户需要在线链接，已有 `file_url` 时可直接返回它。不要只返回本地路径，除非用户明确只需要本机文件。
+
+## 普通文件链路
+
+```text
+reply_completed.files[].file_url
+  -> coze session file download <file_url>
+```
+
+如果回复中只有 `file_uri`：
+
+- 普通回复产物需要先通过 session 文件 URL 解析逻辑或后续命令拿到 `file_url`。
+- PPT 类 `file_uri` 交给 [`coze-claw-ppt.md`](coze-claw-ppt.md)。
+- 不要直接把 `file_uri` 拼成 URL。
+
+## 上传和下载边界
+
+- 上传本地输入文件给 session message：使用 `coze session message --file` 或正文 `@<path>`。
+- 下载 session 回复产物：使用 `coze session file download <file_url>`。
+- 对用户交付产物：优先返回在线 `file_url`；如果需要本地落盘，再给出下载后的 `path`。

package/skills/using-coze-cli/coze-claw/references/coze-claw-async-followup.md

@@ -0,0 +1,266 @@
+# claw async follow-up
+
+> **前置条件：** 先阅读 [`coze-claw-message.md`](coze-claw-message.md) 和 [`coze-claw-progress.md`](coze-claw-progress.md)。
+
+当 `coze session message --wait` 或 `coze session message` 命中长任务后，Agent 不应依赖“当前这次对话进程还在”去等待终态。优先做法是登记一个独立的 follow-up 定时任务，周期刷新 `session task` 状态，任务完成后再在原消息上下文回复用户。
+
+## 适用场景
+
+- OpenClaw + 飞书：用户在飞书里发消息，长任务完成后仍然回飞书原位置
+- 宿主支持 cron / delayed job / background workflow / schedule
+- 当前回合只适合先 ACK，再后台继续跟进
+
+## 核心原则
+
+1. **ACK 和 follow-up 分离**
+   - 当前回合负责快速确认“已接单/已转后台处理”
+   - 后续通知由独立 follow-up task 负责
+
+2. **回复位置必须持久化**
+   - `session_id` 只能恢复 Coze 任务
+   - `reply_target` 才决定最后把结果回到哪里
+
+3. **在哪里收到，就在哪里回复**
+   - 飞书 DM 回 DM
+   - 飞书群消息回原群
+   - 飞书 topic/thread 回原 thread
+   - 飞书消息卡片优先更新原卡片
+   - 飞书 Drive 评论必须 reply comment
+
+4. **必须防重**
+   - follow-up task 重试时不能重复通知用户
+   - 如果宿主已有任务幂等、去重或回执能力，优先复用，不要重复维护一套平行状态
+
+5. **创建结果必须说实话**
+   - 真正创建了 follow-up task，才可以对用户说“已转后台持续跟进/完成后自动回你”
+   - 如果当前没有创建成功，必须在同一回合明确告知“当前还没有创建后台 follow-up 任务”
+   - 禁止把“我准备创建”“理论上可以创建”表述成“我已经在后台盯着”
+
+## 执行分支
+
+命中长任务后，Agent 必须先判断当前宿主是否真的支持并允许创建 follow-up 定时任务：
+
+### 分支 A：当前就能创建
+
+- 直接创建，不要把“要不要创建定时任务”再抛回给用户做默认选择题
+- 当前回合应明确告诉用户：
+  - 已创建后台 follow-up 定时任务
+  - 结果会回到原消息上下文
+  - 当前这条回复只是 ACK，不是最终结果
+
+### 分支 B：当前不能创建
+
+- 必须在同一回合明确告诉用户：
+  - 当前还没有创建后台 follow-up 定时任务
+  - 原因是当前宿主不支持、权限不允许，或本轮无法实际调用该能力
+- 必须立即给出下一步，而不是停在“我继续盯着”
+- 可给出的下一步至少包括：
+  - 当前回合继续前台代查，查到终态再回复
+  - 如果宿主支持后续补建，提醒用户当前可以创建一个后台定时轮询任务
+- 没有真正创建 follow-up task 时，禁止说“完成后自动回你”“我会持续盯到结束”
+
+## 最小数据契约
+
+建议在宿主侧登记一条尽量轻量的 follow-up 记录。`coze session task show/refresh --format json` 已经能按 `task_id` 反查 `session_id`、`message_id`、`progress_id`、`status`、`reply_content`、`artifacts`，所以不要把这些 Coze task 元数据再重复存一份。
+
+```ts
+type FollowUpJob = {
+  taskId: string;
+  replyTarget: ReplyTarget;
+};
+
+type FollowUpJobWithHostState = FollowUpJob & {
+  notifyPolicy?: NotifyPolicy;
+  dedupeKey?: string;
+  notifiedAt?: number;
+  notifyStatus?: "pending" | "sent" | "failed";
+};
+
+type ReplyTarget = {
+  source:
+    | "feishu_dm"
+    | "feishu_group"
+    | "feishu_thread"
+    | "feishu_card"
+    | "feishu_drive_comment";
+  accountId?: string;
+  chatId?: string;
+  threadId?: string;
+  topicId?: string;
+  messageId?: string;
+  commentId?: string;
+  replyMode:
+    | "reply"
+    | "thread_reply"
+    | "update_card"
+    | "reply_comment";
+};
+
+type NotifyPolicy = {
+  pollIntervalSec: number;
+  maxWaitSec: number;
+  maxAttempts: number;
+  backoff: "fixed" | "linear" | "exponential";
+};
+```
+
+必填约束：
+
+- `taskId` 必须保留
+- `replyTarget` 必须在当前回合就确定
+
+可选宿主字段：
+
+- 如果宿主没有内建幂等或任务状态，可使用 `FollowUpJobWithHostState` 额外保存 `dedupeKey`、`notifiedAt`、`notifyStatus`
+- 如果宿主调度器需要显式参数，也可在 `FollowUpJobWithHostState` 中补 `notifyPolicy`
+- 如果宿主本身已经有 cron/workflow 元数据、重试策略、任务状态机，就不要在 follow-up 记录里再镜像保存一套
+
+恢复说明：
+
+- `taskId` 足够恢复 Coze 长任务
+- follow-up 执行时，如需 `session_id`、`message_id`、`progress_id`，先执行：
+
+```bash
+coze session task refresh <task_id> --format json
+coze session task show <task_id> --format json
+```
+
+- 只有 `replyTarget` 这类“Coze CLI 无法帮你恢复的宿主上下文”才值得持久化
+
+## 标准流程
+
+### 1. 当前回合 ACK
+
+当前回合只做三件事：
+
+1. 把前置回复回给用户
+2. 说明 follow-up 是否已经创建成功
+3. 创建成功则登记 follow-up task；未创建成功则明确给出下一步选项
+
+只有真正创建成功，才可以明确说“已登记后台跟进任务”。
+
+### 2. 创建 follow-up task
+
+follow-up task 至少要能执行：
+
+```bash
+coze session task refresh <task_id> --format json
+coze session task show <task_id> --format json
+# message_id 和 session_id 从上一步 task refresh/show 输出中获取
+coze session replies <message_id> -s <session_id> --format json
+```
+
+推荐顺序：
+
+1. 先 `task refresh`
+2. 从输出里读取 `status`，并按需取 `session_id`、`message_id`
+3. 如果仍是 `running`，按宿主自己的 schedule/workflow 策略继续下一次调度
+4. 如果是 `finished/failed/cancelled`，进入终态回复流程
+
+### 3. 终态回复流程
+
+优先级：
+
+1. 如果 `task show/refresh` 已带 `reply_content` 或 `artifacts`，直接用它
+2. 否则调用 `replies <message_id>`
+3. 整理为最终用户可见结果
+4. 通过 `replyTarget` 回复到原上下文
+
+### 4. 回复成功后收口
+
+- 如果宿主使用 `FollowUpJobWithHostState`，写入 `notifiedAt`
+- 如果宿主使用 `FollowUpJobWithHostState`，写入 `notifyStatus=sent`
+- 后续轮询不再重复发送
+
+如果宿主已有任务完成回执或幂等键，也可以不额外维护这两个字段，只要能保证“同一终态结果只通知一次”即可。
+
+## 飞书优先级规则
+
+OpenClaw + 飞书场景，建议按这个顺序回复：
+
+1. `feishu_drive_comment`
+   - 必须 `reply_comment`
+2. `feishu_card`
+   - 优先 `update_card`
+   - 更新失败时退回 `thread_reply` 或普通 `reply`
+3. `feishu_thread`
+   - 优先回原 thread/topic
+4. `feishu_group`
+   - 回原群消息上下文
+5. `feishu_dm`
+   - 回原 DM
+
+禁止：
+
+- 在飞书收到，最后却发到另一个渠道
+- 原线程还能回复，却新开一条无关联消息
+- 当前回合和 follow-up task 各发一次终态结果
+
+## 轮询与重试建议
+
+默认轮询建议：
+
+- `pollIntervalSec`: 30
+- `maxWaitSec`: 1800
+- `maxAttempts`: 60
+- `backoff`: `fixed`
+
+这是一组调度建议，不要求一定落成 `FollowUpJob` 字段。能复用宿主自己的 cron / delayed job / workflow 配置时，优先复用。
+
+更长任务可用：
+
+- 前 600 秒（10 分钟）每 30 秒
+- 之后每 120 秒（2 分钟）
+
+如果宿主调度成本高，可改成：
+
+- 前 3 次 15 秒
+- 之后 60 秒固定间隔
+
+## 幂等与 fallback
+
+### 幂等
+
+- 每次发送前先检查 `notifiedAt`
+- 如果宿主已有幂等键，优先用宿主能力；否则可用 `dedupeKey=<source>:<taskId>:terminal`
+- 如果发送 API 超时但结果未知，也不要立即重发全文；应先查发送结果或写入待人工确认状态
+
+### fallback
+
+如果原上下文失效，按这个顺序退化：
+
+1. 原 thread/topic 不可用，退回同一 chat 的普通 reply
+2. 原 card 无法更新，退回同一 thread reply
+3. 原 comment 无法 reply，退回同一文档或同一会话中的普通通知
+4. 仍失败时，记录 `notifyStatus=failed` 并保留人工补发所需上下文
+
+禁止直接静默丢失通知。
+
+## 推荐示例
+
+### 示例 1：普通长任务
+
+1. 当前回合收到 `task_id`
+2. 先回复“任务已转后台处理，完成后我会在这里回复你”
+3. 保存 `replyTarget=feishu_dm`
+4. 创建 follow-up task
+5. follow-up `task refresh`
+6. 终态后读取 `reply_content`
+7. 回原 DM
+
+### 示例 2：PPT 长任务
+
+1. 当前回合先回前置回复
+2. 命中 `task_id`
+3. 保存 `replyTarget=feishu_group` 或 `feishu_thread`
+4. follow-up 定时轮询
+5. 终态后读取 `artifacts`
+6. 把 PPT 链接或导出产物回原消息位置
+
+### 示例 3：飞书评论触发
+
+1. 用户在文档评论区触发任务
+2. 保存 `replyTarget=feishu_drive_comment`
+3. follow-up 轮询 `task`
+4. 终态后用评论回复接口回结果
+5. 不再额外发一条普通 IM 消息

package/skills/using-coze-cli/coze-claw/references/coze-claw-message.md

@@ -0,0 +1,176 @@
+# claw message commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-session.md`](coze-claw-session.md)。
+
+消息相关命令覆盖发送、监听和补偿查询。Agent 应优先记录 `session_id` 和 `message_id`。当省略 `-s/--session-id` 时，这些命令会默认复用当前本地默认 session。
+
+## 命令导航
+
+| 命令 | 说明 |
+|------|------|
+| `coze session message [message]` | 向 session 发送消息 |
+| `coze session message --wait` | 等待当前 turn 回复并输出事件流 |
+| `coze session task <subcommand>` | 查询或恢复本地持久化的 session 长任务 |
+| `coze session watch` | 监听指定 session 的 websocket 回复 |
+| `coze session replies <message_id>` | 回查某条请求消息的全部回复 |
+
+## message
+
+提交消息并立即返回 `message_id`，适合 Agent 长任务编排。
+
+```bash
+coze session message "执行这个长任务" -s <session_id> --format json
+coze session message "继续当前默认话题" --format json
+```
+
+关键输出：
+
+```json
+{
+  "session_id": "...",
+  "message_id": "...",
+  "status": "accepted"
+}
+```
+
+必须记录 `message_id`，后续断线或超时时用 `replies` 恢复。
+
+## Agent 路由前缀清洗
+
+通过 Agent 宿主的 `/coze-cli` 或 `/coze` 显式路由命中时，正文规范化规则统一见 [`coze-claw-agent-routing.md`](coze-claw-agent-routing.md)。
+
+## message --wait
+
+短任务可直接等待当前 turn。
+
+```bash
+coze session message "请分析这份需求" \
+  -s <session_id> \
+  --wait \
+  --timeout 120000 \
+  --format json
+```
+
+`--format json` 输出事件流，每行一个事件。不要整段 `JSON.parse()`。
+
+| `type` | 含义 | 关键字段 |
+|--------|------|----------|
+| `reply_chunk` | 增量文本 | `delta`、`answer_message_id` |
+| `reply_update` | 回复快照 | `content`、`answer_message_id` |
+| `reply_completed` | 当前 turn 完成 | `content`、`files`、`event_source` |
+| `background_progress_started` | 检测到后台任务 | `progress_id`、`progress_status` |
+
+收到 `background_progress_started` 后，优先读取末尾的 task 快照对象；如果拿到 `task_id`，转 [`coze-claw-progress.md`](coze-claw-progress.md) 里的 `session task *` 流程。
+
+### Agent 交付约束
+
+- `reply_completed` 才是当前 turn 的最终 reply 事件；拿到后必须把 `content/files` 回给用户。
+- 如果命中 `background_progress_started` 之前已经收到有语义的 `reply_update.content`，必须先把这段前置回复回给用户，不能吞掉。
+  - 推荐做法：记录同一 `message_id` 下最后一条有语义的 `reply_update.content`，一旦确认转入后台任务，先把它作为“当前已知回复”返回，再继续查 `task/progress`。
+- 禁止把“已发送”“等待中”“已完成”“耗时 xx s”当作最终答复。
+- 如果等待过程被打断，但已经拿到 `session_id` + `message_id`，必须用 `replies` 补查并回传结果。
+
+## Agent 编排约束：命中 `progress_id`
+
+当 `message --wait` 的事件流中出现 `background_progress_started`，Agent 应立刻切换心智模型：
+
+- 不再把这次请求当作“继续同步等一会儿就会结束”的短任务
+- 把 `progress_id` 视为当前版本的长任务句柄
+- 必须同时保留：
+  - `session_id`
+  - `message_id`
+  - `progress_id`
+
+当前版本推荐恢复链路：
+
+```bash
+coze session task show <task_id> --format json
+coze session task refresh <task_id> --format json
+coze session task watch <task_id> --timeout 300000 --format json
+coze session replies <message_id> -s <session_id> --format json
+```
+
+如果当前宿主支持后台 schedule/job，优先改走 [`coze-claw-async-followup.md`](coze-claw-async-followup.md) 里的 follow-up 流程，而不是让当前 agent 进程前台等待到任务结束。
+
+规则：
+
+- 有 `task_id` 后，优先查 task，不要重复发送同一条 message。
+- `task_id` 是 CLI 本地恢复点，`progress_id` 仍要保留，必要时可退回 `progress poll/watch`。
+- 如果命中 `progress_id` 之前已经出现前置回复，不要等终态才回给用户；应先回传前置回复，再继续后台跟进。
+- 如果宿主支持后台 follow-up task，应在这里登记独立定时任务，保存 `reply_target`，后续由它负责终态通知。
+- task/progress 结束后，再回查 `replies <message_id>` 获取最终回复或产物。
+- 终态 `session task` 快照如果已包含 `reply_content` / `artifacts`，应把它们视为可直接交付给用户的缓存结果，而不是只报任务状态。
+
+## 输入文件
+
+两种方式都会作为 session 附件上传：
+
+```bash
+coze session message "总结这些文件" -s <session_id> --file ./a.pdf --file ./b.png
+coze session message "总结 @docs/notes.md" -s <session_id>
+coze session message "总结这份默认会话里的材料" --file ./a.pdf
+```
+
+- `--file` 可重复。
+- `@<path>` 只引用文件，不引用目录。
+
+## watch
+
+监听 session 回复。Agent 使用时必须加 `--timeout`。
+
+```bash
+coze session watch -s <session_id> --timeout 120000 --format json
+coze session watch -s <session_id> --snapshot --timeout 120000 --format json
+```
+
+- 默认输出流式增量。
+- `--snapshot` 输出完整回复快照。
+- 超时后如果仍未拿到结果，用 `replies <message_id>` 补偿查询。
+
+## replies
+
+按用户请求消息回查全部回复。
+
+```bash
+coze session replies <message_id> -s <session_id> --format json
+```
+
+适用场景：
+
+- `message --wait` 超时。
+- `watch` 断线或超时。
+- 已有 `message_id`，需要稳定结果而非实时流。
+
+## 推荐 Agent 流程
+
+短任务：
+
+```bash
+coze session message "需求" -s <session_id> --wait --timeout 120000 --format json
+coze session message "继续当前默认话题" --wait --timeout 120000 --format json
+```
+
+长任务：
+
+```bash
+coze session message "需求" -s <session_id> --format json
+coze session watch -s <session_id> --timeout 120000 --format json
+coze session replies <message_id> -s <session_id> --format json
+```
+
+如果 `message --wait` 已经返回 `task_id` / `progress_id`，则改走：
+
+```bash
+coze session task refresh <task_id> --format json
+coze session task watch <task_id> --timeout 300000 --format json
+coze session replies <message_id> -s <session_id> --format json
+```
+
+如果 Agent 宿主支持定时任务，推荐替换为：
+
+1. 当前回合先 ACK 原消息
+2. 记录 `task_id + reply_target`
+3. 创建独立 follow-up 定时任务
+4. follow-up 轮询 `task refresh/show`，按需从输出恢复 `session_id/message_id`
+5. 终态后读取 `reply_content/artifacts` 或 `replies`
+6. 在原渠道原消息上下文回复用户

package/skills/using-coze-cli/coze-claw/references/coze-claw-podcast.md

@@ -0,0 +1,73 @@
+# claw podcast commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-message.md`](coze-claw-message.md)。
+
+podcast 能力包含 voice 查询和播客消息发送。`podcast message` 是播客场景的独立入口，底层复用 session message 发送链路。
+省略 `-s/--session-id` 时，`podcast message` 会默认复用当前本地默认 session。
+
+## Agent 路由说明
+
+通过 Agent 宿主的 `/coze-cli` 或 `/coze` 显式路由命中时，正文规范化规则统一见 [`coze-claw-agent-routing.md`](coze-claw-agent-routing.md)。
+
+## 命令导航
+
+| 命令 | 说明 |
+|------|------|
+| `coze session podcast voice list` | 查询可用 podcast voice |
+| `coze session podcast message` | 发送播客消息 |
+
+## voice list
+
+```bash
+coze session podcast voice list --format json
+coze session podcast voice list --mode solo --format json
+coze session podcast voice list --keyword 鸡汤 --format json
+```
+
+先查 voice，再发送播客消息。`--mode` 和 `--keyword` 都是筛选条件。
+
+## podcast message
+
+```bash
+coze session podcast message "@播客 制作一个介绍潮汕美食的播客" \
+  -s <session_id> \
+  --voice "鸡汤女生" \
+  --wait \
+  --timeout 120000 \
+  --format json
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<message>` | 条件必填 | 播客需求；也应支持 stdin |
+| `-s` / `--session-id` | 否 | 目标 session；省略时默认复用当前本地默认 session |
+| `--voice <voice>` | 否 | podcast voice，使用 `.option()`，不是 `.requiredOption()` |
+| `--mode <mode>` | 否 | voice 歧义消解；传 `--mode` 时必须同时传 `--voice` |
+| `--wait` | 否 | 等待当前 turn idle |
+| `--timeout <ms>` | 否 | `--wait` 的超时 |
+| `--file <path>` | 否 | 复用 message 附件逻辑，可重复 |
+
+不指定 `--voice` 时，命令仍可发送播客消息，只是不注入指定 voice。
+
+## 旧用法
+
+保留兼容：
+
+```bash
+coze session message "@播客 制作一个介绍潮汕美食的播客" \
+  -s <session_id> \
+  --podcast-voice "鸡汤女生" \
+  --wait
+```
+
+Agent 新流程推荐使用：
+
+```bash
+coze session podcast message ...
+```
+
+## 输出解析
+
+`podcast message --wait --format json` 复用 session message 事件流。按 [`coze-claw-message.md`](coze-claw-message.md) 的事件规则解析，不要整段 `JSON.parse()`。

package/skills/using-coze-cli/coze-claw/references/coze-claw-ppt.md

@@ -0,0 +1,78 @@
+# claw PPT commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-artifacts.md`](coze-claw-artifacts.md)。
+
+PPT 命令围绕 session 产物中的 PPT `file_uri` 工作。不要把 PPT `file_uri` 直接传给 `file download`。
+
+## Agent 路由说明
+
+通过 Agent 宿主的 `/coze-cli` 或 `/coze` 显式路由命中时，正文规范化规则统一见 [`coze-claw-agent-routing.md`](coze-claw-agent-routing.md)。
+
+## 命令导航
+
+| 命令 | 说明 |
+|------|------|
+| `coze session ppt info` | 获取 PPT 元信息、页数、file_url |
+| `coze session ppt pages` | 提取页面标题和预览文本 |
+| `coze session ppt export` | 导出 PPTX |
+| `coze session ppt edit` | 通过 session message 发起页级编辑 |
+| `coze session ppt share` | 生成分享链接 |
+
+## info
+
+```bash
+coze session ppt info --file-uri "<file_uri>" --format json
+```
+
+用于确认 PPT 类型、页数和可访问 URL。
+
+## pages
+
+```bash
+coze session ppt pages --file-uri "<file_uri>" --limit 5 --format json
+```
+
+用于快速理解 PPT 内容，再决定是否编辑或导出。
+
+## export
+
+```bash
+coze session ppt export --file-uri "<file_uri>" --output-path ./deck.pptx --format json
+coze session ppt export --file-uri "<file_uri>" --export-type editable --output-path ./deck.pptx --format json
+```
+
+`--export-type` 支持：
+
+| 类型 | 含义 |
+|------|------|
+| `ppt` | 默认 PPTX 导出 |
+| `editable` | 可编辑版本导出 |
+
+## edit
+
+```bash
+coze session ppt edit "标题更突出，减少正文密度" \
+  -s <session_id> \
+  --page 2 \
+  --wait \
+  --timeout 120000 \
+  --format json
+```
+
+`ppt edit` 本质是构造页级编辑 query，并复用 session message 链路。可重复传 `--page`。
+省略 `-s/--session-id` 时，`ppt edit` 会默认复用当前本地默认 session。
+
+## share
+
+```bash
+coze session ppt share --file-uri "<file_uri>" --format json
+coze session ppt share --file-uri "<file_uri>" --no-short --format json
+```
+
+默认生成短链；`--no-short` 返回原始分享 URL。
+
+## Agent 注意事项
+
+- PPT 产物优先记录 `file_uri`。
+- 要下载 PPTX 用 `ppt export`，不要用 `file download <file_uri>`。
+- 编辑后仍需按 message/watch/replies 的恢复策略处理结果。