@coze/cli 0.1.8-alpha.618a4c → 0.2.0-alpha.094e22

package/skills/using-coze-cli/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: using-coze-cli
+version: 0.2.0-alpha.094e22
+description: "Coze CLI 共享基础：安装、认证登录(OAuth)、组织与空间切换、配置管理、全局执行原则、安全规则、错误码处理、代理配置。当用户首次使用 coze-cli、需要登录授权、遇到权限不足、切换组织/空间、操作 Coze Claw Session/coze session *，或任何操作前的基础检查时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze --help"
+---
+
+# Coze CLI 共享规则
+
+本技能指导你如何通过 `coze` 命令完成基础配置和上下文管理，以及有哪些通用注意事项。
+
+## 适用场景
+
+- 用户明确要求"用 Coze CLI"或"用 `coze` 命令"完成任务。
+- 需要使用 `coze generate` 生成音频、图片或视频。
+- 需要把本地生成文件上传后，将在线可访问链接返回给用户。
+- 需要创建 Coze 项目、发送 `message`、查询状态、部署、获取 preview。
+- 需要操作 Claw Session：创建/找回 session、发送 session message、监听 reply、查询 progress、处理文件/PPT/播客产物。
+- 用户输入以 `/coze-cli` 或 `/coze` 开头时，必须优先把这条消息视为显式路由到 Coze CLI skill。
+- 这两个前缀只用于路由，不属于最终发给 `coze session message` 的正文。
+
+## 模块化阅读顺序
+
+本文件只保留 Coze CLI 的共享基础规则。进入具体命令族时，优先继续阅读对应模块文档：
+
+- `coze session *`：先读 [coze-claw/MODULE.md](coze-claw/MODULE.md)
+- `coze code *`：先读 [coze-code/MODULE.md](coze-code/MODULE.md)
+- `coze file *`：先读 [coze-file/MODULE.md](coze-file/MODULE.md)
+- `coze generate *`：先读 [coze-generate/MODULE.md](coze-generate/MODULE.md)
+
+约束：
+
+- 根 `SKILL.md` 只放共享规则，不堆积 Claw 专用长任务编排细节。
+- Claw 相关的 agent 执行约束、恢复策略、长任务规则，尽量收敛到 `coze-claw/` 目录内。
+
+## 必须遵守的执行原则
+
+### 1. 用户明确指定 Coze CLI 时，禁止私自改用别的能力
+
+- 如果用户明确要求"用 Coze CLI 生成语音/图片/视频"，就必须优先把 Coze CLI 路径跑通。
+- **禁止**在未充分排查 Coze CLI 正确用法前，擅自改用 Agent 宿主、自带 TTS、第三方生成接口或 Web 页面手工下载流程。
+- 只有在 Coze CLI 明确报错、能力缺失，且已经向用户解释并获得同意时，才允许退回到其他方案。
+
+### 2. 优先使用 `--format json`
+
+- 需要结构化解析结果时，优先增加 `--format json`。
+- 注意：`coze code message send --format json` 输出 NDJSON 事件流，必须按行解析，不能直接整段 `JSON.parse()`；应找 `finish: true` 的行获取最终结果。
+- 注意：`coze session message --wait --format json`、`coze session watch --format json`、`coze session progress watch --format json` 也会输出事件流，必须按行/事件解析，不能整段 `JSON.parse()`。
+- `coze session message --wait --format json` 的最终 reply 事件是 `reply_completed`，不是 `finish: true`。
+- 补充：`coze session message --wait --format json` 如果命中后台 `progress_id`，事件流后会额外给出一个稳定的 task 快照对象，至少包含 `task_id`、`progress_id`、`task_status`，后续优先改用 `coze session task *` 跟进。
+- `--format` 默认值为 `text`，text 模式下输出人类可读的格式化文本。
+
+### 3. 对用户交付 Coze Session 结果时，必须回传最终 reply，不要只回状态
+
+- 对 `coze session *`，`message sent`、`watching`、`progress started`、`task finished`、`已完成/耗时 xx s` 都只是过程状态，不是最终用户可见结果。
+- 短任务：拿到 `reply_completed.content/files` 后，必须把回复正文或产物链接整理回给用户。
+- 长任务前置回复：如果 `message --wait --format json` 在命中 `progress_id` / `task_id` 之前，已经出现了有语义的 `reply_update.content` 或 `reply_completed.content`，必须先把这段前置回复回给用户，再继续进入后台任务跟进。
+  - 典型场景：先回复“我先加载 PPT 技能/我先读一下风格参考”，随后才启动 `progress`。
+  - 禁止把这类前置回复吞掉，只给用户返回“开始生成了/任务已启动/稍后给你链接”。
+- 长任务 follow-up：如果当前回合已经拿到 `task_id` / `progress_id`，要么按 [`coze-claw/MODULE.md`](coze-claw/MODULE.md) 的 follow-up 规则立即创建独立后台任务，要么在同一回合明确告知“当前还没有创建后台 follow-up 任务”并给出下一步选项；禁止没创建也说“我会继续盯着/完成后自动回你”。
+- 长任务：如果命中 `progress_id` / `task_id`，任务终态后必须继续：
+  - 优先读取 `coze session replies <message_id> -s <session_id> --format json`
+  - 或读取终态 `coze session task show/refresh/watch` 里的 `reply_content` 和 `artifacts`
+- 只要已经有 `session_id`、`message_id`、`task_id` 这些恢复主键，即使等待过程被中断，也必须补查结果并回给用户。
+- 禁止在用户侧只留下“已经发出去”“正在等结果”“已完成”而没有实际 reply 内容的收尾。
+
+### 3.1 对 Coze Session，默认复用上一次 session，除非用户明确要求新建
+
+- 只要用户没有明确表达“新建话题”“新增话题”“开一个新会话”“不要沿用之前上下文”这类意图，就应优先复用上一次成功使用的 `session_id`。
+- 当前 CLI 会把最近一次成功使用的 `session_id` 持久化到本地配置；Agent 可用 `coze session current --format json` 读取，用 `coze session use <session_id> --format json` 显式切换。
+- `coze session message`、`coze session watch`、`coze session replies`、`coze session podcast message`、`coze session ppt edit` 在省略 `-s/--session-id` 时，会默认复用当前本地 session。
+- 推荐顺序：
+  1. 先执行 `coze session current --format json` 读取本地默认 `session_id`
+  2. 用 `coze session status -s <session_id> --format json` 确认该 session 仍可用
+  3. 如果需要切换到指定会话，执行 `coze session use <session_id> --format json`
+  4. 如果本地没有最近 `session_id`，再用 `coze session list --limit 20 --format json` 找最近一个可复用 session，并在确认后 `coze session use <session_id> --format json`
+  5. 只有在用户明确要求新开话题，或确实没有可复用 session 时，才执行 `coze session create --format json`
+- 禁止因为“发起新请求”就默认创建新 session，这会丢失连续对话上下文，也会增加 agent 自己维护上下文的负担。
+
+### 4. 对用户交付文件时，必须返回在线链接，不要返回本地路径
+
+- 本地路径如 `/tmp/foo.mp3`、`./output/image.png`、相对路径或沙箱路径，对用户不可直接访问。
+- 生成文件后，**必须**继续执行 `coze file upload <path>`。
+- 最终返回给用户的应是上传后的在线 `URL`，而不是本地文件路径。
+
+### 5. 不确定命令用法时，使用 `--help` 或 `--man` 查看
+
+- 任何命令都支持 `--help` 查看简要帮助，`--man` 查看完整手册（含参数说明、示例、错误码）。
+- 当不确定某个命令的参数、选项或用法时，**先执行 `<command> --help` 或 `<command> --man`** 获取准确信息，不要凭猜测拼命令。
+- 示例：
+  ```bash
+  coze code project create --help
+  coze code deploy --man
+  coze generate video create --help
+  ```
+
+### 6. 显式路由前缀只用于命中 skill，不得透传给底层 prompt
+
+- 当用户输入以 `/coze-cli` 或 `/coze` 开头时，首个 token 仅作 skill 路由用途。
+- 在调用 `coze session message`、`coze session podcast message` 或其他 Coze CLI 子命令前，必须剥离该前缀。
+- 示例：
+  - `/coze-cli 制作一个介绍潮汕美食的 PPT` -> `制作一个介绍潮汕美食的 PPT`
+  - `/coze-cli @PPT 制作介绍海南美食的 PPT` -> `@PPT 制作介绍海南美食的 PPT`
+- 禁止把 `/coze-cli`、`/coze` 原样拼进最终发送给 Claw 的 message。
+
+## 安装 CLI
+
+```bash
+npm install -g @coze/cli
+```
+
+如果找不到包，可执行：
+
+```bash
+npm config set registry https://registry.npmjs.org/
+```
+
+## 登录与身份验证
+
+#### 避坑：OAuth 授权超时与阻塞问题
+
+- `coze auth login` 的 OAuth 激活链接和设备码通常输出在 `stderr`，需要合并捕获。
+- **致命问题**：设备码有 **10 分钟有效期**，且命令会前台阻塞等待。如果 Agent 同步等待该命令执行，可能会卡死流程，且用户往往来不及操作。
+- **补充问题**：部分 Agent 宿主会回收 detached/`nohup` 子进程，导致 `coze auth login` 在用户完成授权前就异常消失，表面上看像“用户已授权但 CLI 一直未登录”。
+- **当前推荐顺序**：
+  1. 优先在一个可持续持有的 PTY/TTY 会话里直接运行 `coze auth login`
+  2. 读取并返回授权链接给用户
+  3. 保持该会话存活，等待 `Authentication successful. Credentials saved.`
+  4. 成功后再执行 `coze auth status --format json`
+- 只有在确认宿主不会回收 detached 子进程时，才使用下面的 `nohup` + 退出码文件方案。
+- **推荐方案：后台执行 + 轮询获取链接 + 进程自记录退出码**：
+  ```bash
+  # 0. 清理上次残留的临时文件（避免误读旧状态）
+  rm -f /tmp/coze-login.log /tmp/coze-login.pid /tmp/coze-auth-exit-code.txt
+
+  # 1. 后台启动登录命令，让进程自己记录退出码
+  nohup bash -c '
+    coze auth login
+    EC=$?
+    echo $EC > /tmp/coze-auth-exit-code.txt
+    exit $EC
+  ' > /tmp/coze-login.log 2>&1 &
+  echo $! > /tmp/coze-login.pid
+
+  # 2. 轮询等待授权链接出现（最多等待 30 秒）
+  for i in $(seq 1 15); do
+    if grep -q "user_code=" /tmp/coze-login.log 2>/dev/null; then
+      break
+    fi
+    sleep 2
+  done
+
+  # 2.1 检查是否成功获取到链接
+  if ! grep -q "user_code=" /tmp/coze-login.log 2>/dev/null; then
+    echo "获取授权链接超时，请检查网络连接或重试"
+    cat /tmp/coze-login.log 2>/dev/null
+  fi
+
+  # 3. 提取并返回授权链接
+  grep "user_code=" /tmp/coze-login.log | grep -oE 'https://[^ ]+'
+  ```
+- **为什么让进程自己记录退出码**：
+  - `wait` 命令只能在启动进程的 shell 中使用，无法在后台子 shell 中跨进程等待。
+  - 通过 `bash -c '...; EC=$?; echo $EC > file'` 让进程自己捕获并记录退出码。
+  - 退出码精确反映**本次**授权结果，不受上次登录状态影响：
+    - 退出码 `0`：用户完成授权
+    - 非零退出码：授权失败（常见值：`1` 一般错误、`2` 认证失败、`6` 网络错误、`8` 超时）
+- **授权流程（必须遵守）**：
+  1. **先检查授权状态**：在发起任何需要认证的操作前，必须先执行 `coze auth status` 确认是否已完成授权。
+  2. **若未授权，后台执行并轮询获取链接**：
+     - 使用上述后台执行 + 轮询方案获取授权链接。
+     - 一旦获取到链接，**立即返回给用户**。
+     - 同时启动后台轮询任务自动检查授权状态。
+  3. **检查退出码确认授权结果**：
+     - 进程结束后，退出码会自动写入 `/tmp/coze-auth-exit-code.txt`。
+     - 通过轮询检查该文件确认授权结果：
+       ```bash
+       # 轮询检查退出码文件（最长等待 10 分钟）
+       for i in $(seq 1 60); do
+         if [ -f /tmp/coze-auth-exit-code.txt ]; then
+           exit_code=$(cat /tmp/coze-auth-exit-code.txt)
+           if [ "$exit_code" = "0" ]; then
+             echo "授权成功"
+           else
+             echo "授权失败（退出码: $exit_code）"
+           fi
+           break
+         fi
+         sleep 10
+       done
+
+       # 兜底：如果轮询结束仍未获得退出码，说明进程异常
+       if [ ! -f /tmp/coze-auth-exit-code.txt ]; then
+         echo "授权超时或进程异常退出"
+         # 检查后台进程是否仍在运行
+         if [ -f /tmp/coze-login.pid ] && kill -0 "$(cat /tmp/coze-login.pid)" 2>/dev/null; then
+           echo "登录进程仍在运行，尝试终止"
+           kill "$(cat /tmp/coze-login.pid)" 2>/dev/null
+         fi
+       fi
+       ```
+  4. **授权完成后，再启动后续任务**：
+     - 授权是所有后续操作的前置条件。在确认已登录之前，**不要**创建任何后台任务或发起项目创建/部署等后续操作。
+- 如果提示 `[Auth] No API token found`，先执行：
+
+```bash
+coze auth status
+```
+
+### 检查登录状态
+
+- `coze auth status` 返回当前凭证状态。`--format json` 输出结构化数据，至少包含 `logged_in`，登录成功时通常还会返回 `user` 和 `token_expires_at`。
+- Token 过期后 CLI 会在执行命令时自动尝试刷新，无需手动重新登录。
+
+### 登出
+
+- `coze auth logout` 清除本地凭证。
+
+## 长时间命令处理
+
+### 避坑：长耗时命令超时问题
+
+- 部分命令（AI 生成、部署、OAuth 登录等）可能耗时数分钟甚至更久，超过沙箱超时限制（通常 600 秒）会导致命令被强制中断。
+- 不同命令的阻塞行为不同，需要区分处理。
+
+### 长耗时命令速查表
+
+| 长耗时命令 | 默认行为 | `--wait` | 对应的轮询命令 |
+|-----------|---------|:---:|--------------|
+| `coze auth login` | 同步阻塞（等待用户浏览器授权） | — | 轮询退出码文件（见上文"登录与身份验证"） |
+| `coze code message send` | **非阻塞**（发送后立即返回 `status:'sent'`） | ✅ 加后阻塞等待 AI 回答流完成 | `coze code message status -p <project_id>` |
+| `coze code project create` | **非阻塞**（后台子进程执行 AI 生成） | ✅ 加后变阻塞 | `coze code message status -p <project_id>` |
+| `coze code deploy <id>` | 触发部署后立即返回 | ✅ 加后内置轮询(3s) | `coze code deploy status <project_id>` |
+| `coze code deploy fix <id>` | **非阻塞**（后台子进程执行修复） | ✅ 加后变阻塞 | `coze code message status -p <project_id>` |
+| `coze generate video create` | 提交任务后立即返回 taskId | ✅ 加后内置轮询(2s/5min超时) | `coze generate video status <task_id>` |
+| `coze generate audio` | 同步阻塞（SSE 流式返回） | — | — |
+| `coze generate image` | 同步阻塞（单次 API 调用） | — | — |
+| `coze session message` | 提交后立即返回 `message_id` | ✅ 加后变阻塞并输出事件流 | `coze session replies <message_id>` |
+| `coze session task show/refresh/watch` | 单次查询 / 主动刷新 / 持续观察本地恢复任务 | — | `coze session replies <message_id>` / `coze session progress poll <progress_id>` |
+| `coze session watch` | 持续监听 websocket | — | 必须加 `--timeout`，超时后用 `replies` 补偿 |
+| `coze session progress watch` | 持续监听后台任务 | — | 必须加 `--timeout`，或改用 `progress poll` |
+
+> `coze code message status` 和 `coze code deploy status` 本身都是**单次查询**，不会自动轮询。需要在脚本中循环调用。
+> `coze code message cancel -p <project_id>` 可取消进行中的消息任务。
+
+### 场景一：命令支持非阻塞——不加 `--wait` 直接使用
+
+`project create`、`deploy fix` 默认就是非阻塞的（通过 detached 子进程后台执行），`deploy`、`generate video create` 默认提交后立即返回。这些命令返回后，通过上表中对应的轮询命令检查结果即可。
+
+```bash
+# 示例：项目创建 + 轮询（默认非阻塞）
+coze code project create --type web --message "需求描述"
+# 命令立即返回 project_id，然后轮询消息状态
+for i in $(seq 1 60); do
+  result=$(coze code message status -p <project_id> --format json)
+  status=$(echo "$result" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+  echo "[$(date +%H:%M:%S)] 状态: $status"
+  if [ "$status" = "done" ] || [ "$status" = "completed" ]; then
+    echo "处理完成！"
+    echo "$result"
+    break
+  elif [ "$status" = "failed" ]; then
+    echo "处理失败"
+    break
+  fi
+  sleep 30
+done
+```
+
+> **注意**：这些命令加 `--wait` 后会变成同步阻塞，应按场景二处理。推荐**不加 `--wait`**，改用对应轮询命令手动轮询。
+
+### 场景二：命令处于阻塞状态——需要 `nohup` 后台执行
+
+以下情况命令会同步阻塞，如果预计耗时较长可能超出沙箱超时限制，必须通过 `nohup` 后台执行，再用对应轮询命令检查结果：
+
+- **本身始终阻塞的命令**：`generate audio`、`generate image`、`auth login` 没有 `--wait` 选项，始终同步阻塞。
+- **加了 `--wait` 的命令**：`message send --wait`、`project create --wait`、`deploy --wait`、`deploy fix --wait`、`generate video create --wait` 加上 `--wait` 后会变成同步阻塞（其中 `message send` 不加 `--wait` 时为非阻塞，发送后立即返回，用 `message status` 轮询）。
+
+```bash
+# 示例：阻塞型 message send --wait 后台执行 + 轮询
+# 注意：message send 不加 --wait 时为非阻塞（发送即返回），无需 nohup，直接调用后用 message status 轮询即可；
+#       只有加了 --wait（同步等待 AI 回答流完成）且预计耗时较长时，才需要下面的 nohup 后台执行方案。
+rm -f /tmp/coze-message.log /tmp/coze-message-exit-code.txt
+
+nohup bash -c '
+  coze code message send "需求描述" -p <project_id> --wait
+  EC=$?
+  echo $EC > /tmp/coze-message-exit-code.txt
+  exit $EC
+' > /tmp/coze-message.log 2>&1 &
+
+# 通过 message status 轮询进度（对应轮询命令见上表）
+for i in $(seq 1 60); do
+  result=$(coze code message status -p <project_id> --format json 2>/dev/null)
+  status=$(echo "$result" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+  echo "[$(date +%H:%M:%S)] 状态: $status"
+  if [ "$status" = "done" ] || [ "$status" = "completed" ]; then
+    echo "处理完成！"
+    echo "$result"
+    break
+  elif [ "$status" = "failed" ]; then
+    echo "处理失败"
+    break
+  fi
+  sleep 30
+done
+
+# 兜底：轮询结束仍未完成时检查后台进程退出码
+if [ "$status" != "done" ] && [ "$status" != "completed" ]; then
+  if [ -f /tmp/coze-message-exit-code.txt ]; then
+    exit_code=$(cat /tmp/coze-message-exit-code.txt)
+    echo "后台进程已退出，退出码: $exit_code"
+  else
+    echo "任务可能仍在进行中，请稍后再次执行轮询命令检查"
+  fi
+fi
+```
+
+**核心原则**：任何可能长时间阻塞的命令，都应后台执行或使用其内置的非阻塞模式，然后通过对应的轮询命令检查结果，避免沙箱超时中断。
+
+## 组织与空间上下文
+
+### 核心行为
+
+- 切换组织时会**自动清空 Space ID**，需要重新选择工作空间。
+- 指定不存在的组织 ID 会**报错且不修改配置**。
+- 省略 org_id 可切换到个人账户模式（需要个人账户可用）。
+- CLI 的自动上下文补全**仅作用于空间**：未配置空间时，首次执行需要上下文的命令会自动选择第一个可用空间（结果可能不是期望的，建议始终显式设置）。**组织不会自动选择**——未显式设置组织时按上文的个人账户模式处理。
+
+### 遇到 `No permission` 的修正顺序
+
+1. `coze config list` — 查看当前配置
+2. `coze organization list` — 查看可用组织
+3. `coze organization use <org_id>` — 切换到正确的组织（或 `coze organization use` 切换到个人账户）
+4. `coze space list` — 查看当前组织下的空间
+5. `coze space use <space_id>` — 切换到正确的空间
+
+### 环境变量覆盖
+
+- `COZE_ORG_ID`、`COZE_SPACE_ID` 环境变量可临时覆盖配置，无需修改持久化配置。
+- `--org-id`、`--space-id` 全局参数也可以临时覆盖。
+- `COZE_CLI_PLATFORM` 环境变量决定**项目访问链接的域名**：取值为 `ecs` 或 `vefaas`（忽略大小写）时，所有项目访问链接（创建、部署、预览等命令输出的 URL）使用 `www.coze.cn` 域名；其它取值或为空时使用默认的 `code.coze.cn` 域名。
+
+## 配置管理概要
+
+- `coze config get <keys...>` — 获取配置值
+- `coze config set <key> <value>` — 设置配置值
+- `coze config delete <keys...>` — 删除配置值
+- `coze config list` — 列出所有配置
+
+详细用法参见各业务模块 reference 文档中的配置相关章节。
+
+## 安全规则
+
+- **禁止输出密钥**（token、API Key 等）到终端明文。
+- **写入/删除操作前必须确认用户意图**。
+- 用 `--dry-run` 预览危险请求（如适用）。
+
+## 代理配置
+
+如果需要通过代理访问 Coze API：
+
+```bash
+export HTTPS_PROXY=http://your-proxy:8080
+export HTTP_PROXY=http://your-proxy:8080
+```
+
+CLI 会自动识别并使用配置的代理。
+
+## 升级与补全
+
+### 升级 CLI
+
+```bash
+coze upgrade          # 升级到最新版本
+coze upgrade --force  # 强制升级
+```
+
+### Shell 自动补全
+
+```bash
+coze completion --setup    # 安装补全脚本
+coze completion --cleanup   # 移除补全脚本
+```
+
+支持的 Shell：bash, zsh, fish, powershell。
+
+## 退出码参考
+
+Agent 在判断命令执行结果时，应根据退出码判断：
+
+| 退出码 | 名称 | 含义 |
+|--------|------|------|
+| `0` | `SUCCESS` | 成功 |
+| `1` | `GENERAL_ERROR` | 一般错误 |
+| `2` | `AUTH_FAILED` | 认证失败，需要重新登录 |
+| `3` | `RESOURCE_NOT_FOUND` | 资源未找到（如项目 ID 不存在） |
+| `4` | `INVALID_ARGUMENT` | 参数无效 |
+| `5` | `PERMISSION_DENIED` | 权限不足，检查组织/空间上下文 |
+| `6` | `NETWORK_ERROR` | 网络错误，检查代理或网络连接 |
+| `7` | `SERVER_ERROR` | 服务端错误，稍后重试 |
+| `8` | `TIMEOUT` | 操作超时 |
+| `9` | `QUOTA_EXCEEDED` | 配额超限 |
+| `10` | `CONFLICT` | 资源冲突 |
+
+### 退出码处理建议
+
+- 退出码 `2`：执行 `coze auth login` 重新登录。
+- 退出码 `5`：按"组织与空间上下文"章节的修正顺序排查。
+- 退出码 `6`/`7`：可重试一次。
+- 退出码 `4`：检查参数拼写和格式。
+
+## 业务模块导航
+
+| 模块 | 触发场景 | 入口 |
+|------|---------|------|
+| [`coze-code`](./coze-code/MODULE.md) | 创建项目、发送需求、部署应用、环境变量/域名/技能管理 | `coze code *` |
+| [`coze-claw`](./coze-claw/MODULE.md) | Claw Session 对话、回复监听、后台 progress、文件/PPT/播客产物 | `coze session *` |
+| [`coze-generate`](./coze-generate/MODULE.md) | 生成图片、语音合成(TTS)、视频生成 | `coze generate *` |
+| [`coze-file`](./coze-file/MODULE.md) | 上传本地文件获取在线访问地址 | `coze file upload` |
+
+## 典型错误速查（基础类）
+
+### 错误 1：用户要求用 Coze CLI，但 agent 改用别的 TTS
+
+- 问题：偏离用户指令，且掩盖了 Coze CLI 实际可用路径。
+- 修正：先补上 `--output-path`，完整跑完 Coze CLI 生成与上传闭环。
+
+### 错误 2：OAuth 登录卡死或用户来不及授权
+
+- 问题：直接后台执行 `coze auth login` 后继续发起后续任务，导致后续任务因未授权而全部失败；或前台阻塞等待导致 Agent 卡死；或使用 `wait` 在后台子 shell 中跨进程等待导致失败。
+- 修正：
+  1. **用 `bash -c` 包装命令**，让进程自己记录退出码到文件。
+  2. **轮询获取授权链接**，拿到后立即返回给用户。
+  3. **轮询检查退出码文件**，判断本次授权结果（0=成功，非0=失败）。
+
+### 错误 3：未使用 `--format json` 导致输出无法解析
+
+- 问题：Agent 需要从输出中提取 projectId、taskId 等结构化数据，但默认 text 格式不方便解析。
+- 修正：Agent 场景下始终加 `--format json`，然后按 JSON 解析输出。
+
+### 错误 4：忽视退出码直接认为命令成功
+
+- 问题：命令可能返回非零退出码表示失败，但 Agent 只看了 stdout 输出。
+- 修正：始终检查命令退出码，非零时根据退出码参考表排查问题。

package/skills/using-coze-cli/coze-claw/MODULE.md

@@ -0,0 +1,189 @@
+---
+name: coze-claw
+version: 0.2.0-alpha.094e22
+description: "Coze Claw Session 会话工作流：创建/找回 claw session、发送 session message、监听回复、查询后台 progress、处理文件/PPT/播客产物。当用户需要使用 coze session * 任意命令时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze session --help"
+---
+
+# Coze Claw Session 工作流
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解认证、全局参数、输出格式和错误处理。
+> **上下文说明：** `coze session *` 跳过 org/space check，不要求先执行 `coze org use` 或 `coze space use`。只需确保 token 有效，并通过 `coze session status` 解析当前 claw。
+> **执行前必做：** 从下方命令分组定位 reference，并先阅读对应 reference。涉及长任务 follow-up 时，再读 [`coze-claw-async-followup.md`](references/coze-claw-async-followup.md)。
+
+## 核心概念
+
+- **claw_id**：当前账号可用的 claw 实例，通常由 `coze session status` 解析并缓存。
+- **session_id**：一条 claw chat 会话，CLI 会把最近一次成功使用的 session 持久化到本地，供后续 message/watch/replies/podcast/ppt edit 默认复用。
+- **message_id**：用户提交的请求消息 ID，用于 `replies` 补偿查询。
+- **answer_message_id**：assistant 回复消息 ID，用于对齐流式回复和最终回复。
+- **progress_id**：claw 后台任务 ID，用于 progress 查询/监听。
+- **file_uri**：平台内部文件引用，不能直接下载。
+- **file_url**：可下载或可直接交付的文件 URL。
+
+## Agent 快速执行顺序
+
+1. **检查认证/claw**：`coze session status --format json`。
+2. **优先复用本地默认 session**：除非用户明确要求“新建话题/新增话题/开新会话”，否则先执行 `coze session current --format json` 读取本地默认 `session_id`。
+3. **检查指定 session runtime**：已有 `session_id` 时执行 `coze session status -s <session_id> --format json`。
+4. **找回 / 切换 session，再决定是否创建**：如果本地没有可用的默认 `session_id`，先 `list` 找最近一个可复用 session，并用 `coze session use <session_id> --format json` 切换；只有用户明确要求新开话题，或确实没有可复用 session 时才 `create`。
+5. **发送消息**：短任务用 `message --wait`；长任务用 `message` 无 `--wait` 获取 `message_id`，再 `watch/replies`。
+6. **后台任务**：出现 `progress_id` 后，立即把它视为长任务句柄；如果 CLI 已返回 `task_id`，优先转 `session task show/refresh/watch`，并同时保留 `session_id`、`message_id`、`progress_id`。
+7. **产物处理**：普通文件走 `file`；PPT 走 `ppt`；播客先查 voice，再用 `podcast message`。
+
+## 用户回传闭环
+
+- `message_id`、`progress_id`、`task_id`、`status=finished` 都只是恢复和编排主键，不是最终要回给用户的内容。
+- 短任务：读取 `reply_completed.content/files` 后，必须把正文或文件链接回给用户。
+- 长任务前置回复：如果同一轮在转入 `progress/task` 之前，已经通过 `reply_update` 或 `reply_completed` 产出了明确的说明性回复，必须先把这段内容回给用户，再继续后台跟进。
+  - 不要只保留 `progress_id` / `task_id` 而丢掉这段首条回复。
+- 长任务：`task/progress` 进入终态后，必须再取最终 reply。
+  - 推荐：`coze session replies <message_id> -s <session_id> --format json`
+  - 兜底：读取终态 `session task` 快照里的 `reply_content`、`artifacts`
+- 禁止只回复“已发送”“已完成”“耗时 xx s”而不附带实际 reply。
+
+## Session 复用原则
+
+- 默认复用最近一次成功使用的 `session_id`。
+- 可用 `coze session current --format json` 查看当前本地默认 session。
+- 可用 `coze session use <session_id> --format json` 显式切换默认 session。
+- 只有用户明确说“新建话题”“新增话题”“开一个新会话”“不要沿用之前上下文”时，才主动创建新 session。
+- 如果最近 `session_id` 不可用，再退回 `coze session list --limit 20 --format json` 找最近一个可复用 session。
+- 只有“用户明确要求新建”或“确实找不到可复用 session”这两种情况，才执行 `coze session create --format json`。
+
+## 长任务 follow-up 原则
+
+- 命中 `task_id` / `progress_id` 后，不要把“继续盯结果”绑定在当前 agent 进程上。
+- 如果当前宿主支持 schedule/job/workflow，并且 Agent 能直接调用，必须在同一回合自动创建独立的 follow-up 定时任务去轮询 `coze session task refresh/show`，直到任务进入终态。
+- 如果当前宿主不支持，或 Agent 当前无法真正创建 follow-up 定时任务，必须在同一回合明确告知用户“当前还没有创建后台 follow-up 任务”，并给出下一步选项。
+- follow-up task 至少要保存：
+  - `taskId`
+  - `replyTarget`
+- `sessionId`、`messageId`、`progressId` 这类 Coze task 元数据，优先在 follow-up 执行时通过 `task show/refresh` 现查，不要重复持久化。
+- `dedupeKey`、`notifiedAt`、`notifyStatus` 只在宿主没有现成幂等/状态能力时才额外保存。
+- 终态后必须在原消息上下文回复用户，而不是换一个新地方通知。
+- 禁止在没有真正创建 follow-up task 的情况下，对用户说“我继续盯着”“完成后自动回你”“我会持续跟进到结束”。
+- 如果没有创建 follow-up task，可提供的下一步至少包括：
+  - 当前回合继续前台代查
+  - 提醒用户当前可以创建后台定时轮询任务（如果宿主支持后续补建）
+- 具体数据契约、轮询规则、原地回复策略见 [`coze-claw-async-followup.md`](references/coze-claw-async-followup.md)。
+
+## 标准工作流
+
+### 短任务：同步等待当前 turn
+
+```bash
+coze session create --format json
+
+coze session message "请分析这份需求" \
+  -s <session_id> \
+  --wait \
+  --timeout 120000 \
+  --format json
+```
+
+`message --wait --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
+```
+
+优先记录 `session_id` 和 `message_id`，这是恢复流程的主键。
+
+## 意图 → 命令索引
+
+| 意图 | 推荐命令 | Reference |
+|------|---------|-----------|
+| 检查 token/claw | `coze session status` | [session](references/coze-claw-session.md) |
+| 查看当前默认 session | `coze session current` | [session](references/coze-claw-session.md) |
+| 切换当前默认 session | `coze session use <session_id>` | [session](references/coze-claw-session.md) |
+| 检查指定 session runtime | `coze session status -s <session_id>` | [session](references/coze-claw-session.md) |
+| 新建 claw session | `coze session create` | [session](references/coze-claw-session.md) |
+| 找回已有 session | `coze session list` | [session](references/coze-claw-session.md) |
+| 发送消息并等待回复 | `coze session message --wait` | [message](references/coze-claw-message.md) |
+| 长任务提交与监听分离 | `coze session message` + `coze session watch` | [message](references/coze-claw-message.md) |
+| 超时/断线后补偿查询 | `coze session replies <message_id>` | [message](references/coze-claw-message.md) |
+| 查询本地可恢复长任务 | `coze session task list/show/refresh/watch` | [progress](references/coze-claw-progress.md) |
+| 查询后台任务 | `coze session progress list/show/poll/watch` | [progress](references/coze-claw-progress.md) |
+| 下载回复文件 | `coze session file download <file_url>` | [artifacts](references/coze-claw-artifacts.md) |
+| 处理 PPT 产物 | `coze session ppt *` | [ppt](references/coze-claw-ppt.md) |
+| 选择播客 voice | `coze session podcast voice list` | [podcast](references/coze-claw-podcast.md) |
+| 发送播客消息 | `coze session podcast message` | [podcast](references/coze-claw-podcast.md) |
+
+## 命令分组
+
+| 命令分组 | 说明 | Reference |
+|----------|------|-----------|
+| `session status/create/current/use/list` | claw 状态、本地默认 session 与 session 生命周期 | [coze-claw-session.md](references/coze-claw-session.md) |
+| `message/watch/replies` | 消息发送、流式监听、补偿查询 | [coze-claw-message.md](references/coze-claw-message.md) |
+| `task list/show/refresh/watch/gc` | 本地可恢复长任务查询、刷新与清理 | [coze-claw-progress.md](references/coze-claw-progress.md) |
+| `progress list/show/poll/watch` | claw 后台任务查询和监听 | [coze-claw-progress.md](references/coze-claw-progress.md) |
+| `async follow-up` | 长任务登记、定时轮询、原地回复、幂等与 fallback | [coze-claw-async-followup.md](references/coze-claw-async-followup.md) |
+| `file download` | 普通文件产物下载与交付 | [coze-claw-artifacts.md](references/coze-claw-artifacts.md) |
+| `ppt info/pages/export/edit/share` | PPT 产物处理 | [coze-claw-ppt.md](references/coze-claw-ppt.md) |
+| `podcast voice/message` | 播客 voice 查询与播客消息发送 | [coze-claw-podcast.md](references/coze-claw-podcast.md) |
+| `agent routing` | `/coze-cli`、`/coze` 前缀路由、strip 规则、验收样例 | [coze-claw-agent-routing.md](references/coze-claw-agent-routing.md) |
+
+## 长耗时任务处理
+
+| 命令 | 默认行为 | 等待/超时建议 | 恢复命令 |
+|------|----------|---------------|----------|
+| `coze session message` | 提交后返回 `message_id` | 推荐 Agent 默认使用 | `replies <message_id>` / `watch` |
+| `coze session message --wait` | 阻塞并输出事件流 | 必须加 `--timeout` | 有 `message_id` 则 `replies`，否则 `watch/status/list` |
+| `coze session watch` | 持续监听 websocket | 必须加 `--timeout` | 再次 `watch` 或查 `progress list` |
+| `coze session task watch` | 持续观察本地 task 快照 | 必须加 `--timeout` | `task refresh <task_id>` / `replies <message_id>` |
+| `coze session progress watch` | 持续监听 progress | 必须加 `--timeout` | `progress poll <progress_id>` |
+| `coze session progress poll` | 单次查询 | 适合脚本循环 | 查不到按 `finished` 处理 |
+
+补充规则：
+
+- `message --wait` 一旦返回 `progress_id`，就不要把它继续当作“同一条同步回复”处理。
+- 对 Agent 而言，`progress_id` 就是当前版本最稳定的长任务句柄。
+- 如果 `message --wait` 同时返回了 `task_id`，优先改走：
+  - `coze session task show <task_id> --format json`
+  - `coze session task refresh <task_id> --format json`
+  - `coze session task watch <task_id> --timeout <ms> --format json`
+- `task_id` 是 CLI 本地恢复点，`progress_id` 仍然是服务端长任务句柄；两者都要保留。
+- `task` 进入终态后，再用 `replies <message_id>` 回查最终回复或产物；至少也要读取 task 快照里的 `reply_content` / `artifacts` 并回给用户。
+
+## 常见错误速查（Claw 专用）
+
+| 症状/误用 | 一句话修复 |
+|----------|------------|
+| token 失效或未登录 | 先 `coze auth status`，必要时登录；多步处理见“恢复策略速查”。 |
+| 未记录 `session_id` | 先 `current` 看本地默认；没有再 `list` 找回，必要时 `use` 切换。 |
+| `message --wait` 超时 | 有 `message_id` 走 `replies`；否则看“恢复策略速查”。 |
+| 对事件流整段 `JSON.parse()` | 改为按行/事件处理。 |
+| `progress_id` 查不到 | 用 `progress poll` 缺失即 finished 的语义，再回查结果。 |
+| 把 `file_uri` 当 `file_url` 下载 | 先解析为 `file_url`；PPT 走 `ppt info/export/share`。 |
+| 监听命令没有 `--timeout` | 补 `--timeout`，避免 Agent 挂死。 |
+
+## 恢复策略速查
+
+| 场景 | Agent 执行步骤 |
+|------|----------------|
+| token 不可用 | 先 `coze auth status`；未登录或过期时引导 `coze auth login`；成功后重试 session 命令。 |
+| 没有 `session_id` | 先 `coze session current --format json`；无默认时执行 `coze session list --limit 20 --format json` 找回，必要时 `coze session use <session_id>`；只有确实没有可复用 session 时才 `create`。 |
+| 只知道历史上下文但没有 session | 执行 `coze session list --format json`，必要时用 `--offset` 分页找回。 |
+| `message --wait` 超时 | 如果已记录 `message_id`，执行 `coze session replies <message_id> -s <session_id> --format json`；否则执行 `watch -s <session_id>` 或 `status -s <session_id>`。 |
+| `watch` 超时但 session 仍 working | 再次执行 `watch -s <session_id> --timeout <ms>`；或查 `progress list` 判断是否转为后台任务。 |
+| 有 `task_id` | 优先 `task show/refresh/watch`；必要时再退回 `progress poll/watch` 与 `replies`。 |
+| 有 `progress_id` 没有最终产物 | 视为长任务恢复流程：优先 `task refresh/watch` 或 `progress poll/watch` 到 finished，再用 `replies <message_id>` 回查。 |
+| 有 `file_url` | 直接 `coze session file download <file_url>`，或把 `file_url` 作为在线链接交付。 |
+| 只有 `file_uri` | 不能直接下载；用对应能力解析。PPT 使用 `ppt info/export/share`。 |
+| 监听输出解析困难 | 改用非监听命令：`message` 无 `--wait`、`replies`、`progress poll/show`。 |
+
+## Agent 禁止行为
+
+- 不要对 `message --wait`、`watch`、`progress watch` 的输出整段 `JSON.parse()`。
+- 不要执行监听命令但不设置 `--timeout`。
+- 不要丢失 `session_id`、`message_id`、`progress_id`。
+- 不要把 `file_uri` 当作 `file_url` 下载。
+- 不要只返回本地下载路径作为最终交付，除非用户明确只要本机路径。