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

package/skills/using-coze-cli/coze-generate/references/coze-generate-audio.md

@@ -0,0 +1,105 @@
+# generate audio
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+> **交付闭环：** 生成完成后，需继续执行 `coze file upload` 上传文件并返回在线链接。详细用法参见 [`../coze-file/references/coze-file-upload.md`](../coze-file/references/coze-file-upload.md)。
+
+文本转语音（TTS）。基于 SSE (Server-Sent Events) 流式输出音频分片。
+
+## 核心警告（最高优先级）
+
+**不要只执行裸命令！始终带 `--output-path`！**
+
+```bash
+# 错误 ❌ — 裸命令可能不保存文件
+coze generate audio "你好"
+
+# 正确 ✅ — 始终指定输出目录
+coze generate audio "你好" --output-path /tmp/coze-audio
+```
+
+只跑裸命令时，CLI 可能只返回请求信息或任务参数，**不一定会把音频文件保存到本地**，从而导致 agent 误判为"还需要额外下载步骤"。
+
+## 命令概述
+
+```bash
+coze generate audio [prompt] [options]
+```
+
+- 基于 **SSE (Server-Sent Events)** 流式接收音频分片并写入文件
+- `--output-path` 应理解为**保存目录**，CLI 会在该目录下自动写入生成的音频文件
+
+## 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `[prompt]` | — | 要合成的文本（或通过 `--stdin` 从管道读取） |
+| `--speaker` | `zh_female_xiaohe_uranus_bigtts` | 音色/说话人 |
+| `--audio-format` | `mp3` | 音频编码：`pcm` / `mp3` / `ogg_opus` |
+| `--sample-rate` | `24000` | 采样率 |
+| `--speech-rate` | `0` | 语速，范围 -50 ~ 100 |
+| `--loudness-rate` | `0` | 响度，范围 -50 ~ 100 |
+| `--ssml` | `false` | 将输入视为 SSML 标记语言 |
+| `--stdin` | — | 从管道读取 prompt（与位置参数二选一，位置参数优先） |
+| `--output-path` | — | **保存目录**（不是最终文件名！） |
+| `--format` | `text` | 输出格式：`text` / `json` |
+
+## 标准语音生成工作流
+
+```bash
+# 1. 创建输出目录
+mkdir -p /tmp/coze-audio
+
+# 2. 生成音频到该目录
+coze generate audio "这里放要合成的文本" \
+  --output-path /tmp/coze-audio \
+  --format json
+
+# 3. 在目录里定位新生成的音频文件（如 output.mp3）
+
+# 4. 上传该音频文件
+coze file upload /tmp/coze-audio/<generated-file>.mp3 --format json
+
+# 5. 把上传后的在线链接发给用户
+```
+
+### 推荐命令模板
+
+```bash
+# 基本生成（使用默认音色）
+mkdir -p /tmp/coze-audio
+coze generate audio "你好，欢迎使用 Coze CLI" \
+  --output-path /tmp/coze-audio \
+  --format json
+
+# 指定音色和编码
+coze generate audio "欢迎来到我们的直播间" \
+  --output-path /tmp/coze-audio \
+  --speaker zh_female_xiaohe_uranus_bigtts \
+  --audio-format mp3 \
+  --sample-rate 24000
+
+# 调整语速和响度
+coze generate audio "这段话需要快一点读" \
+  --output-path /tmp/coze-audio \
+  --speech-rate 50 \
+  --loudness-rate 10
+
+# SSML 输入（从管道读取）
+echo '<speak>欢迎来到我们的直播间</speak>' | coze generate audio --ssml --stdin \
+  --output-path /tmp/coze-audio --format json
+```
+
+## SSE 流式输出说明
+
+- 音频通过 Server-Sent Events (SSE) **逐流式**返回分片
+- CLI 会自动收集所有分片并合并写入 `--output-path` 指定的目录
+- Agent 无需手动处理 SSE 流，只需等待命令完成即可
+
+## 坑点速查
+
+| 坑点 | 说明 | 修正 |
+|------|------|------|
+| 裸命令不保存文件 | 不带 `--output-path` 时可能只返回元数据 | 始终带 `--output-path` |
+| `--output-path` 不是文件名 | 它是保存目录，CLI 自动命名文件 | 传入目录路径如 `/tmp/coze-audio` |
+| 生成后忘记上传 | 只说"已生成"不够 | 必须继续 `coze file upload` 再返回 URL |
+| 发了 uri 而非 url | 返回结构同时有 uri 和 url | **优先返回 url 给用户** |

package/skills/using-coze-cli/coze-generate/references/coze-generate-image.md

@@ -0,0 +1,80 @@
+# generate image
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+> **交付闭环：** 生成完成后，需继续执行 `coze file upload` 上传文件并返回在线链接。详细用法参见 [`../coze-file/references/coze-file-upload.md`](../coze-file/references/coze-file-upload.md)。
+
+文本生成图片。支持参考图输入、连续组图生成等高级功能。
+
+## 命令概述
+
+```bash
+coze generate image [prompt] [options]
+```
+
+- 图片**直接同步返回**（不同于视频的异步任务模型）
+- 支持 `--stdin` 从管道读取 prompt
+- 默认模型：`doubao-seedream-4-5-251128`
+
+## 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `[prompt]` | — | 图片描述文本（或通过 `--stdin` 从管道读取） |
+| `--size` | `2K` | 图片尺寸：`2K` / `4K` / `WIDTHxHEIGHT` |
+| `--no-watermark` | 有水印 | 添加此标志禁用水印 |
+| `--image <url>` | — | 参考图 URL（可多次传入） |
+| `--response-format` | `url` | 响应格式：`url` / `b64_json` |
+| `--sequential` | `disabled` | 连续图像生成模式：`auto` / `disabled` |
+| `--max-images` | `15` | 连续生成最大图片数（范围 1-15） |
+| `--optimize-prompt-mode` | — | 提示词优化模式 |
+| `--stdin` | — | 从管道读取 prompt（与位置参数二选一，位置参数优先） |
+| `--output-path` | — | **保存目录**（不是最终文件名！） |
+| `--format` | `text` | 输出格式：`text` / `json` |
+
+## 标准图片生成工作流
+
+```bash
+# 1. 创建输出目录
+mkdir -p /tmp/coze-image
+
+# 2. 生成图片到该目录
+coze generate image "一只在太空漫步的猫" \
+  --output-path /tmp/coze-image \
+  --format json
+
+# 3. 从输出中提取 saved_paths，上传文件
+coze file upload /tmp/coze-image/<generated-file>.png --format json
+
+# 4. 将返回的在线 URL 发给用户
+```
+
+### 更多示例
+
+```bash
+# 基本生成
+coze generate image "赛博朋克风格的城市夜景" --output-path /tmp/coze-image --format json
+
+# 指定尺寸 + 无水印
+coze generate image "山水画" --size 4K --no-watermark --output-path /tmp/coze-image --format json
+
+# 使用参考图
+coze generate image "将这张照片转为油画风格" \
+  --image https://example.com/photo.jpg \
+  --output-path /tmp/coze-image --format json
+
+# 连续生成多张
+coze generate image "不同角度的产品展示图" \
+  --sequential auto --max-images 4 \
+  --output-path /tmp/coze-image --format json
+
+# 自定义分辨率
+coze generate image "头像图标" --size 1024x1024 --output-path /tmp/coze-image --format json
+```
+
+## 注意事项
+
+- **`--output-path` 是目录**：CLI 在该目录下自动命名保存生成的图片文件
+- **同步返回**：命令执行完毕即表示图片已生成完毕，无需额外轮询
+- **支持 `--stdin`**：`echo "描述" | coze generate image --stdin --output-path /tmp/img`（需显式传 `--stdin`）
+- 尺寸约束：总像素范围约 2560x1440 ~ 4096x4096，宽高比范围约 1:16 ~ 16:1
+- `--response-format b64_json` 时返回 base64 编码数据（不写文件），一般场景用默认 `url` 即可

package/skills/using-coze-cli/coze-generate/references/coze-generate-video.md

@@ -0,0 +1,125 @@
+# generate video
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+> **交付闭环：** 生成完成后，需继续执行 `coze file upload` 上传文件并返回在线链接。详细用法参见 [`../coze-file/references/coze-file-upload.md`](../coze-file/references/coze-file-upload.md)。
+
+视频生成。采用**异步任务模型**，分两步操作：创建任务 → 查询状态。
+
+## 异步任务模型
+
+```
+Step 1: coze generate video create  →  返回 taskId
+Step 2: coze generate video status <taskId>  →  查询任务状态
+```
+
+---
+
+## video create
+
+创建视频生成任务。
+
+### 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `[prompt]` | — | 视频描述文本（或通过 `--stdin` 从管道读取，或首帧/尾帧图至少一项） |
+| `--model` | `doubao-seedance-1-5-pro-251215` | 视频生成模型 |
+| `--resolution` | `720p` | 分辨率：`480p` / `720p` / `1080p` |
+| `--ratio` | `16:9` | 画面比例（如 `16:9`、`9:16`、`1:1`） |
+| `--duration` | `5` | 时长（秒），范围 4~12 |
+| `--no-watermark` | 有水印 | 添加此标志禁用水印 |
+| `--first-frame <url>` | — | 首帧图片 URL |
+| `--last-frame <url>` | — | 尾帧图片 URL |
+| `--reference-image <url>` | — | 参考图 URL（可多次传入） |
+| `--camerafixed` | `false` | 固定镜头（减少运动） |
+| `--no-generate-audio` | 生成配音 | 添加此标志不生成配音 |
+| `--seed` | — | 随机种子（用于复现相同结果） |
+| `--stdin` | — | 从管道读取 prompt 文本（与位置参数二选一，位置参数优先） |
+| `--wait` | — | 自动轮询等待完成（2秒间隔，5分钟超时） |
+| `--output-path` | — | 保存目录（配合 --wait 使用） |
+| `--format` | `text` | 输出格式：`text` / `json` |
+
+### 推荐工作流
+
+**方法 1（推荐）：`--wait` 一站式完成**
+
+```bash
+mkdir -p /tmp/coze-video
+coze generate video create "一只跳舞的小猫" \
+  --wait \
+  --output-path /tmp/coze-video \
+  --format json
+# → 命令完成后直接从 output-path 目录获取视频文件
+```
+
+- `--wait` 每 2 秒轮询一次，最长等待 **5 分钟**
+- 超时后返回 taskId 供手动查询
+- 配合 `--output-path` 可自动保存生成的视频文件
+
+**方法 2：手动两步**
+
+```bash
+# Step 1: 创建任务，获取 taskId
+coze generate video create "海边日落" --format json
+# → 从返回中提取 taskId
+
+# Step 2: 轮询查询状态
+coze generate video status <taskId> --format json
+```
+
+### 更多示例
+
+```bash
+# 指定分辨率和比例
+coze generate video create "城市航拍" \
+  --resolution 1080p --ratio 16:9 --duration 8 \
+  --wait --output-path /tmp/coze-video --format json
+
+# 使用首帧图
+coze generate video create "照片动态化" \
+  --first-frame https://example.com/frame.jpg \
+  --wait --output-path /tmp/coze-video --format json
+
+# 固定镜头 + 无配音
+coze generate video create "产品展示" \
+  --camerafixed --no-generate-audio \
+  --resolution 720p --ratio 1:1 \
+  --wait --output-path /tmp/coze-video --format json
+```
+
+---
+
+## video status
+
+查询视频生成任务的状态。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<taskId>` | 是 | 任务 ID（位置参数，来自 create 的返回值） |
+| `--format` | 否 | 输出格式：`text` / `json` |
+| `--wait` | 否 | 轮询直到任务到达终态 |
+
+### 推荐命令模板
+
+```bash
+# 查询状态
+coze generate video status <taskId> --format json
+
+# 轮询等待完成
+coze generate video status <taskId> --wait --format json
+```
+
+### 状态含义
+
+| 状态 | 含义 | 下一步操作 |
+|------|------|-------------|
+| `pending` / `processing` | 处理中 | 继续等待或稍后重试查询 |
+| `succeeded` | 生成成功 | 从返回中获取视频信息，执行 file upload |
+| `failed` | 生成失败 | 检查错误信息，调整参数后重试 |
+
+### 注意事项
+
+- **必须提供 Prompt 文本（位置参数或 `--stdin`）或者首帧/尾帧图片中至少一项作为输入**
+- 首帧/尾帧图片必须是有效的可访问 URL

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

@@ -0,0 +1,125 @@
+---
+name: coze-project
+version: 0.2.0-alpha.9f6611
+description: '仅在 `<coze-context>` 标识为"群聊消息"且任务涉及该群组协作时使用——浏览群消息历史、查询群成员、读写编辑群项目文件、协调群里的多方协作、把协作产出衔接给用户。触发场景: 用户问"上次说啥/这次结论是啥"、"谁在群里/有谁的权限"; 用户让你"看一下/改一下/沉淀到"群文件; 用户让你基于群历史/群文件做产出。在"单聊消息"或与该群协作无关的一般性问答下不要使用。'
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze agent --help"
+---
+
+# coze-project: 群聊协作
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解认证、全局参数、输出格式和错误处理。
+
+Coze 是 agent 协作平台: 单聊或拉到群里跟多个用户协作。本技能教你在**群聊**场景下如何协作——查群成员 / 看群历史 / 读写群文件 / 把协作产出衔接给用户。
+
+> **群 == 项目**: `<coze-context>.group_id` 直接当 `coze agent --project-id` 用。
+
+> **CLI 详细语法分两个参考文件 (要敲命令时 Read)**:
+> - 群文件操作 → [`coze-project-files.md`](references/coze-project-files.md)
+> - 群信息查询 → [`coze-project-query.md`](references/coze-project-query.md)
+
+## 触发条件 (必须同时满足)
+
+1. `<coze-context>` 第一行字面值是 `群聊消息` (不是 `单聊消息`)
+2. 任务涉及该群协作 (成员 / 历史 / 文件 / 多方协调)
+
+任一不满足都不用本技能。一般性问题 (如 "解释 Go 泛型") 即使在群里也直接答, 不要无谓调用 `coze agent`。
+
+## 从 `<coze-context>` 提取参数
+
+群聊上下文块形如:
+```
+<coze-context>
+群聊消息
+account_id: 7639...001
+agent_id: 7639...571
+session_id: 7639...999
+group_id: 7639...888
+</coze-context>
+```
+
+| 字段 | 用途 |
+|---|---|
+| `group_id` | → `coze agent --project-id` |
+| `account_id` | → `coze agent --org-id` |
+| `agent_id` / `session_id` | 给 coze-file-send 衔接用, 不传给 `coze agent` |
+
+拿不到 `group_id` → 停下来, 本技能不适用。**不要编, 不要问用户**, 缺失就是不匹配信号。
+
+## 在群里协作的原则
+
+群聊**不是 1v1**, 你面向**多个用户 + 共享群文件**。在群里协作有几个根本不同于单聊的姿势, 不熟会出洋相:
+
+**事实优先于猜测**
+- 用户说"上次说啥"、"我们之前讨论的"、"那个方案"→ **主动 `message list` 查**, 不要靠想象
+- 群消息 + 群文件 = 项目的长期记忆, 比你自己对话记忆更可信
+- 不确定时先 `message list --asc-mode --need-reference` 拉一段看清, 再回答; **凭印象答群里历史是大忌**
+
+**沉淀优先于回话**
+- chat 消息会被刷走, 群文件不会——决策 / 结论 / 行动项 / 草稿要 `file edit` 沉淀到群文件
+- 用户问完答完就过, 但群文件是项目长期资产, 别人后面还会翻
+- 信号: "记一下" / "沉淀" / "加到 todo" / "更新 README" / "整理到文档" → 一定 `file edit`, 不能只在 chat 里回
+
+**共享意识 — 群文件是大家的**
+- 破坏性改动 / 大范围改动前**先审计** (`info` + `member list` + `file list`), 把当前状态向用户对齐
+- 改用 `file edit replace_one` 而不是 `file write` 整覆盖, 避免抹掉别人添加的内容
+- 改完**必须**接 coze-file-send `--group-file` 通知用户, 让对方明确看到你改了什么 (见下"协作产出"节)
+
+**多用户分辨**
+- 同一群里不同用户的请求可能**冲突**, 不要把 A 的诉求执行到 B 的命题上
+- 权限 / 角色相关先 `member list` 看实际角色, 不要假设谁是 owner
+- 引用前文带发言人 ("X 之前提过 ..."), 不要把别人的发言归到当前提问者头上
+- 当前提问者和"上次说要做这件事的人"可能不是同一人, 回复时指代要清楚
+
+## 协作场景速查 (意图 → 命令 + 参考文件)
+
+| 用户意图 | 命令 | 详细语法 |
+|---|---|---|
+| 谁在群里 / 有谁权限 | `coze agent member list` | [query](references/coze-project-query.md) |
+| 群历史 / 上次说啥 | `coze agent message list` | [query](references/coze-project-query.md) |
+| 项目元数据 | `coze agent info` | [query](references/coze-project-query.md) |
+| 列群文件 / 看目录 | `coze agent file list` | [files](references/coze-project-files.md) |
+| 读群文件 (文本) | `coze agent file read` | [files](references/coze-project-files.md) |
+| 改群文件 (改一段) | `coze agent file edit` | [files](references/coze-project-files.md) |
+| 改群文件 (整覆盖, 从字符串) | `coze agent file write` | [files](references/coze-project-files.md) |
+| **本地文件 → 群** (二进制 / 大文件 / 已有本地产物) | `coze agent file upload` | [files](references/coze-project-files.md) |
+| **群文件 → 本地** (二进制 / 想本地处理) | `coze agent file download` | [files](references/coze-project-files.md) |
+| 把产出展示给用户 | coze-file-send `--group-file` | (见下"协作产出"节) |
+
+> 所有 `coze agent` 命令都必须带 `--json` + `--org-id "$account_id"` + `--project-id "$group_id"`; 输出信封 / 错误码 / jq 模板等机制见参考文件。
+
+## 协作产出 → 让用户看到
+
+**核心衔接点**: 你 `coze agent file write/edit` 改完群文件后, 用户在聊天界面**不会被自动通知**——必须用 coze-file-send **群文件模式 (`--group-file`)** 把产出"递"过去。文件已在云端, 走 `--group-file` 跳过上传, 直接 path 透传。
+
+```bash
+# 1) 改群文件 (详细语法见 references/coze-project-files.md)
+coze agent file edit --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/本周周报.md" \
+  --mode replace_one --old-string "..." --new-string "..." --json
+
+# 2) 立刻 send 给用户 (不重新上传)
+~/.coze/bridge/bin/coze-bridge send file "/本周周报.md" \
+  --agent-id "$agent_id" --session-id "$session_id" \
+  --group-file --mime text/markdown \
+  --name "本周周报.md" --caption "已按你的要求更新"
+```
+
+跨技能参数对应: `<coze-context>.agent_id` → `--agent-id`; `<coze-context>.session_id` → `--session-id`; `file edit` 用的 `--file-path` → coze-file-send 的位置参数。详见 coze-file-send 技能。
+
+## 常见工作流
+
+- **先读后编辑** (改群文件安全默认): `file list` 确认 → `file read` 找唯一锚点 → `file edit --mode replace_one` → 衔接 coze-file-send `--group-file`. 详见 [files](references/coze-project-files.md).
+- **审计群信息** (用户问"群里啥情况"): `info` + `member list` + `file list --depth 3` → 汇报给用户. **破坏性操作前必走**. 详见 [query](references/coze-project-query.md) / [files](references/coze-project-files.md).
+- **追溯讨论结论** (用户问"上次说啥"): `message list --asc-mode --need-reference`, `--size 10` 翻页累积 (硬上限), 摘要关键节点. 详见 [query](references/coze-project-query.md).
+
+## 不要做的事 (协作层面)
+
+- ❌ 单聊消息不要用本技能 — 没 group_id, `coze agent` 会失败
+- ❌ 不要向用户要 / 编造 group_id — 必须从 `<coze-context>` 抄
+- ❌ 改完群文件不要就完事 — 必须接 coze-file-send `--group-file` 收尾, 否则用户看不到
+- ❌ 不要在不审计的情况下做破坏性操作 — 先 info + member + file list
+
+> CLI 层面的"不要做的事"（`--json` 必带、信封 `.code` 校验、`file write` 误用、`message list` 上限等）见各参考文件。