@coze/cli 0.2.0 → 0.3.1

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 的恢复策略处理结果。

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

@@ -0,0 +1,112 @@
+# claw progress commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-message.md`](coze-claw-message.md)。
+
+progress 表示 claw 级后台任务。收到 `progress_id` 后，不要继续等待 session reply；如果同轮还拿到了 `task_id`，优先转入 `session task` 查询。
+
+对 Agent 而言，`progress_id` 是当前版本最稳定的长任务句柄。它本身不是最终结果，最终结果通常还要通过 `replies <message_id>` 回查。
+
+## 命令导航
+
+| 命令 | 说明 |
+|------|------|
+| `coze session progress list` | 列出当前 claw 后台任务 |
+| `coze session task list` | 列出本地持久化的 session 长任务 |
+| `coze session task show <task_id>` | 读取本地 task 快照 |
+| `coze session task refresh <task_id>` | 刷新一个本地 task |
+| `coze session task watch <task_id>` | 持续观察一个本地 task |
+| `coze session progress show <progress_id>` | 单次查看任务快照 |
+| `coze session progress poll <progress_id>` | 单次轮询，查不到按 finished |
+| `coze session progress watch [progress_id]` | 监听一个或全部 progress 更新 |
+
+## task
+
+```bash
+coze session task list --format json
+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
+```
+
+- `task_id` 是 CLI 本地恢复句柄，由 `coze session message --wait` 在命中 `progress_id` 时创建。
+- `show` 只读本地快照，不请求服务端。
+- `refresh` 会基于 `progress_id` 做一次服务端刷新，并把最新状态写回本地 task store。
+- `watch` 是前台轮询封装，适合 Agent 周期跟踪与外部通知闭环。
+- 当 task 进入终态且 CLI 已经补查到 reply 时，快照会带上 `reply_content` 和 `artifacts`，可直接作为用户交付结果使用。
+- 如果宿主支持后台 schedule/job，推荐把 `task refresh/show` 放进独立的 follow-up 定时任务，而不是让当前 agent 持续前台 `watch`。
+
+## list
+
+```bash
+coze session progress list --format json
+```
+
+用于判断当前 claw 是否有后台任务，或在 `watch` 超时后确认任务是否转入后台。
+
+## show
+
+```bash
+coze session progress show <progress_id> --format json
+```
+
+单次查看一个任务。查不到时 `found=false`。
+
+## poll
+
+```bash
+coze session progress poll <progress_id> --format json
+```
+
+脚本轮询优先使用 `poll`。它的特殊语义是：查不到 progress 时按 `finished` 输出。
+
+示例：
+
+```bash
+for i in $(seq 1 60); do
+  result=$(coze session progress poll <progress_id> --format json)
+  status=$(echo "$result" | grep -o '"progress_status":"[^"]*"' | cut -d'"' -f4)
+  [ "$status" = "finished" ] && break
+  sleep 10
+done
+```
+
+## watch
+
+```bash
+coze session progress watch <progress_id> --timeout 300000 --format json
+coze session progress watch --timeout 300000 --format json
+```
+
+- 指定 `progress_id` 时，任务 finished 后会退出。
+- 不指定时监听全部 progress，需要依赖 `--timeout` 退出。
+
+## 完成后下一步
+
+task/progress finished 后通常还需要：
+
+```bash
+coze session replies <message_id> -s <session_id> --format json
+```
+
+如果产物是文件或 PPT，继续阅读：
+
+- [`coze-claw-artifacts.md`](coze-claw-artifacts.md)
+- [`coze-claw-ppt.md`](coze-claw-ppt.md)
+
+## Agent 最小恢复集
+
+只要任务已经转入 progress，至少保留这三个 ID：
+
+- `session_id`
+- `message_id`
+- `progress_id`
+
+最小恢复流程：
+
+1. 优先用 `task refresh/watch` 跟进是否 finished；没有 `task_id` 时退回 `progress poll/watch`
+2. finished 后用 `replies <message_id>` 回查最终回复；如果 task 快照已经有 `reply_content` / `artifacts`，也要把这些内容回给用户
+3. 如果回复里带文件，再进入 artifacts 或 PPT 流程
+
+如果需要“后台查到终态后自动在原消息处通知用户”，继续阅读：
+
+- [`coze-claw-async-followup.md`](coze-claw-async-followup.md)

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

@@ -0,0 +1,144 @@
+# claw session commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和错误处理。
+
+基础 session 命令用于确认 claw 状态、创建会话和找回历史会话。`coze session *` 跳过 org/space check，不需要先切换组织或空间。
+
+## Agent 默认策略
+
+- 除非用户明确要求“新建话题”“新增话题”“开新会话”，否则优先复用最近一次成功使用的 `session_id`。
+- CLI 会把最近一次成功使用的 `session_id` 持久化到本地；优先用 `coze session current --format json` 读取，用 `coze session use <session_id> --format json` 切换。
+- 推荐执行顺序：
+  1. 如果已有最近 `session_id`，先执行 `coze session current --format json`
+  2. 再执行 `coze session status -s <session_id> --format json`
+  3. 如果没有最近 `session_id`，执行 `coze session list --limit 20 --format json` 找最近一个可复用 session，并在确认后执行 `coze session use <session_id> --format json`
+  4. 只有用户明确要求新建，或没有任何可复用 session 时，才执行 `coze session create --format json`
+- 不要因为用户发来一条新需求，就默认新建 session。
+
+## 命令导航
+
+| 命令 | 说明 |
+|------|------|
+| `coze session status` | 检查 token/claw，并刷新本地 `claw_id` |
+| `coze session status -s <session_id>` | 查看指定 session runtime 状态和 claw 后台任务概览 |
+| `coze session create` | 创建新 claw session |
+| `coze session current` | 查看当前本地默认 session |
+| `coze session use <session_id>` | 切换当前本地默认 session |
+| `coze session list` | 分页列出 claw sessions |
+
+## status
+
+检查当前 token 是否可访问 claw。
+
+```bash
+coze session status --format json
+```
+
+关键输出：
+
+| 字段 | 含义 |
+|------|------|
+| `auth_configured` | 是否配置 token |
+| `auth_valid` | token 是否有效 |
+| `claw_id` | 当前 claw id |
+| `account_id` | fallback account/organization id |
+
+如果 `auth_valid=false`，先执行 `coze auth status`，必要时重新登录。
+
+## status -s
+
+查看指定 session runtime 状态。
+
+```bash
+coze session status -s <session_id> --format json
+```
+
+关键输出：
+
+| 字段 | 含义 |
+|------|------|
+| `display_status` | `idle` / `working` / `offline` |
+| `runtime_status` | 当前进程内记录的 `idle` / `working` |
+| `claw_busy` | 当前 claw 是否有后台任务 |
+| `claw_progress_count` | 当前 claw 后台任务数量 |
+
+`status -s` 不返回消息内容。要拿结果用 `watch` 或 `replies`。
+
+## create
+
+创建新 session，并记录 `session_id`。
+
+```bash
+coze session create --format json
+```
+
+关键输出：
+
+```json
+{
+  "status": "created",
+  "claw_id": "...",
+  "session_id": "..."
+}
+```
+
+Agent 必须保存 `session_id`，后续 `message/watch/replies/ppt edit` 都需要它。
+
+补充：CLI 现在会在 `create` 成功后自动把这个 `session_id` 写入本地默认 session。
+
+## current
+
+查看当前本地默认 session。
+
+```bash
+coze session current --format json
+```
+
+关键输出：
+
+```json
+{
+  "configured": true,
+  "session_id": "...",
+  "claw_id": "..."
+}
+```
+
+如果 `configured=false`，说明当前没有本地默认 session；这时先 `list` 找回，或直接 `create` 新建。
+
+## use
+
+显式切换当前本地默认 session。
+
+```bash
+coze session use <session_id> --format json
+```
+
+适用场景：
+
+- `list` 找回了历史 session，准备继续该话题
+- 刚创建了多个 session，需要切换默认上下文
+- Agent 需要确保接下来所有省略 `-s` 的命令都落到同一个 session
+
+## list
+
+找回已有 session。
+
+```bash
+coze session list --limit 20 --format json
+coze session list --offset <next_offset> --limit 20 --format json
+```
+
+关键输出：
+
+| 字段 | 含义 |
+|------|------|
+| `items` | session 列表 |
+| `next_offset` | 下一页 offset |
+| `has_more` | 是否还有更多 |
+
+## 常见恢复
+
+- 没有 `session_id`：先 `current` 看本地默认；没有再 `list` 找最近可复用 session，并用 `use` 切换；只有用户明确要求新话题或确实找不到可复用 session 时才 `create`。
+- token 无效：先 `coze auth status`，不要盲目切 org/space。
+- session 仍 working：用 `watch -s <session_id> --timeout <ms>` 或查 `progress list`。