npm - @coze/cli - Versions diffs - 0.2.0 → 0.3.0-alpha.0aeac0 - Mend

@coze/cli 0.2.0 → 0.3.0-alpha.0aeac0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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`。