@coze/cli 0.1.8 → 0.2.0-alpha.bdb5d3

package/skills/using-coze-cli/coze-code/references/coze-code-repo.md

@@ -0,0 +1,285 @@
+# code repo commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+远程仓库管理命令。用于创建、绑定、解绑远程仓库，以及推送/拉取代码和查询同步状态。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code repo create` | 在 Git 平台创建新仓库 |
+| 本文档 | `coze code repo bind` | 绑定远程仓库到项目 |
+| 本文档 | `coze code repo unbind` | 解绑远程仓库 |
+| 本文档 | `coze code repo push` | 推送本地提交到远程 |
+| 本文档 | `coze code repo pull` | 拉取远程变更到本地 |
+| 本文档 | `coze code repo status` | 查看绑定和同步状态 |
+
+> 注意：所有命令均需先完成认证和组织/空间上下文配置。仓库操作需要先完成 Git 平台 OAuth 授权（`coze code git auth login`）。
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--provider` | 否 | Git 平台：`github` / `gitlab`（默认 `github`） |
+
+---
+
+## repo create
+
+在已授权的 Git 平台上创建新的空仓库。创建的仓库可通过 `repo bind` 绑定到项目。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-n, --name <name>` | 是 | 仓库名称 |
+| `--private` | 否 | 创建为私有仓库（推荐） |
+
+### 推荐命令模板
+
+```bash
+# 创建公开仓库
+coze code repo create --name my-app
+
+# 创建私有仓库（推荐）
+coze code repo create -n my-app --private
+
+# 创建后立即绑定
+coze code repo create -n my-repo --private && coze code repo bind -p <projectId> -r user/my-repo
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `full_name` | 仓库全名（如 `user/my-app`） |
+| `html_url` | 仓库 URL |
+| `private` | 是否私有 |
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E1014 | MISSING_REPO_CREATION_NAME | 未提供仓库名 | 使用 `--name <name>` |
+| E2004 | GIT_NOT_AUTHORIZED | Git 平台未授权 | 先执行 `coze code git auth login` |
+| E3009 | CONFLICT | 仓库名已存在 | 使用不同的名称 |
+
+---
+
+## repo bind
+
+将空的远程仓库绑定到指定项目。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p, --project-id <projectId>` | 是 | 项目 ID |
+| `-r, --repo <fullName>` | 是 | 远程仓库全名（如 `user/repo`） |
+
+### 推荐命令模板
+
+```bash
+# 绑定仓库到项目
+coze code repo bind -p <projectId> -r user/my-repo
+
+# 创建新仓库后绑定（推荐流程）
+coze code repo create --name my-repo --private
+coze code repo bind -p <projectId> -r user/my-repo
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `project_id` | 项目 ID |
+| `repo_full_name` | 绑定的仓库全名 |
+| `status` | `bound` |
+
+### 坑点
+
+- **仅支持空仓库**：非空仓库绑定会失败
+- **一个项目只能绑定一个仓库**：需要先 unbind 再绑定新仓库
+- 通过 GitHub 导入创建的项目会自动绑定来源仓库，无需手动 bind
+- 绑定前会先查 `GetRemote` 状态：`bindStatus=3`（已绑定）报 E3016；`bindStatus=1`（未授权）报 E2004；`bindStatus=2`（已授权未绑定）才放行
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E1013 | MISSING_REPO_NAME | 未提供仓库全名 | 使用 `--repo <owner/name>` |
+| E2004 | GIT_NOT_AUTHORIZED | Git 平台未授权（bindStatus=1） | 先执行 `coze code git auth login` |
+| E3015 | REPO_NOT_EMPTY | 仓库非空 | 使用 `repo create` 创建空仓库 |
+| E3016 | REPO_ALREADY_BOUND | 项目已绑定仓库（bindStatus=3） | 先执行 `repo unbind` |
+
+---
+
+## repo unbind
+
+解除项目与远程仓库的绑定关系。不会删除远程仓库本身。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p, --project-id <projectId>` | 是 | 项目 ID |
+| `--force` | 否 | 跳过确认直接解绑（**当前实现未读取该选项，暂无实际作用，也无确认交互**） |
+
+### 推荐命令模板
+
+```bash
+# 解绑（仅 bindStatus=3 即已绑定时可解绑，否则报 E3014）
+coze code repo unbind -p <projectId>
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `project_id` | 项目 ID |
+| `status` | `unbound` |
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 用 `coze code repo status -p <id>` 查看状态 |
+
+---
+
+## repo push
+
+将本地提交推送到已绑定的远程仓库。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p, --project-id <projectId>` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+# 推送变更
+coze code repo push -p <projectId>
+
+# 推送后检查状态
+coze code repo push -p <projectId> && coze code repo status -p <projectId>
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `status` | `success` 或 `failed` |
+| `pushed_commits` | 推送的提交数量 |
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 先执行 `repo bind` |
+| E3017 | NOTHING_TO_PUSH | 无需推送 | 已与远程同步 |
+| E3018 | REMOTE_HAS_UPDATES | 远程有更新 | 先执行 `repo pull` |
+
+### 坑点
+
+- 当远程有新提交时，必须先 pull 再 push
+- **当前为 placeholder 实现**：仅做绑定状态校验后恒返回 `{ status: 'success', pushed_commits: 0 }`，实际 push 走 Web 端 WebSocket，尚未接入
+
+---
+
+## repo pull
+
+从已绑定的远程仓库拉取最新变更。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p, --project-id <projectId>` | 是 | 项目 ID |
+| `--conflict-strategy <strategy>` | 否 | 冲突解决策略：`ours`（保留本地）/ `theirs`（使用远程） |
+
+### 推荐命令模板
+
+```bash
+# 拉取变更
+coze code repo pull -p <projectId>
+
+# 自动解决冲突（保留本地）
+coze code repo pull -p <projectId> --conflict-strategy ours
+
+# 自动解决冲突（使用远程）
+coze code repo pull -p <projectId> --conflict-strategy theirs
+
+# 拉取后推送
+coze code repo pull -p <projectId> --conflict-strategy ours && coze code repo push -p <projectId>
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `status` | `success`、`conflict_resolved` 或 `failed` |
+| `conflict_resolved` | 是否解决了冲突 |
+| `conflict_strategy` | 使用的冲突策略 |
+| `conflict_files` | 冲突文件列表 |
+
+### 坑点
+
+- **不指定 `--conflict-strategy` 时遇到冲突会失败**
+- 冲突解决策略会应用到所有冲突文件（不支持逐文件选择）
+- `--conflict-strategy` 仅文档声明 `ours`/`theirs`，代码不做运行时校验
+- **当前为 placeholder 实现**：恒返回 `success`，从不真正解决冲突
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 先执行 `repo bind` |
+| E3019 | MERGE_CONFLICT | 未指定策略遇到冲突 | 加 `--conflict-strategy ours` 或 `theirs` |
+| E3020 | WOULD_OVERWRITE | 本地改动会被覆盖 | 先提交本地改动 |
+
+---
+
+## repo status
+
+查看项目的远程仓库绑定状态和同步信息。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p, --project-id <projectId>` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+# 查看状态
+coze code repo status -p <projectId>
+
+# JSON 输出
+coze code repo status -p <projectId> --format json
+
+# 流水线中判断绑定状态
+coze code repo status -p <projectId> --format json | jq .bind_status
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `bind_status` | `unauth`、`not-bound` 或 `bound`（`bindStatus` 1/2/3 映射） |
+| `repo_full_name` | 仓库全名（仅 bound 时输出） |
+| `html_url` | 仓库 URL（仅 bound 时输出） |
+
+> 当前实现仅输出上述字段。`ahead` / `behind` / `is_synced` 在 schema 中声明但**实际未输出**，请勿在脚本中依赖（不要用 `jq .is_synced`）。
+
+### 状态枚举
+
+| 状态值 | 含义 |
+|--------|------|
+| `unauth` | Git 平台未授权 |
+| `not-bound` | 已授权但未绑定仓库 |
+| `bound` | 已绑定仓库 |

package/skills/using-coze-cli/coze-code/references/coze-code-skill.md

@@ -0,0 +1,117 @@
+# code skill commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+技能管理命令。用于管理项目默认会话挂载的技能，以及上传/删除个人技能。
+
+> **语义区分（重要）：**
+> - `add` / `remove`：对项目**默认会话**挂载或解绑技能，不创建/删除技能本体。
+> - `delete`：**永久删除个人技能本体**（与 `remove` 不同）。
+> - `upload`：上传本地 `.skill` 文件为个人技能，命名冲突时**自动确认覆盖**。
+
+## 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `coze code skill list -p <id>` | 列出项目可用技能（含 `is_installed` 安装状态） |
+| `coze code skill add <skill-id> -p <id>` | 将技能挂载到默认会话 |
+| `coze code skill remove <skill-id> -p <id>` | 从默认会话解绑技能 |
+| `coze code skill upload <file> -p <id>` | 上传 `.skill` 文件为个人技能 |
+| `coze code skill delete <skill-id> -p <id>` | 永久删除个人技能本体 |
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID（本命令组**不读取** `COZE_PROJECT_ID` 环境变量） |
+
+---
+
+## skill list
+
+列出指定项目类型下所有可用技能，并标注 `is_installed`（是否已挂载到默认会话）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID |
+| `--space-id <spaceId>` | 否 | 空间 ID（缺省读取配置） |
+| `--my` | 否 | 仅列出个人技能（此模式无需 spaceId，`is_installed` 恒为 false） |
+| `--page <page>` | 否 | 页码（个人技能，默认 1） |
+| `--size <size>` | 否 | 每页数量（个人技能，默认 20） |
+
+### 推荐命令模板
+
+```bash
+coze code skill list -p <project-id>
+coze code skill list -p <project-id> --my --page 1 --size 10
+```
+
+---
+
+## skill add
+
+将指定技能挂载到项目默认会话（`is_preload: true`）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<skill-id>` | 是 | 技能 ID（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code skill add <skill-id> -p <project-id>
+```
+
+---
+
+## skill remove
+
+从项目默认会话解绑技能（不删除技能本体）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<skill-id>` | 是 | 技能 ID（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code skill remove <skill-id> -p <project-id>
+```
+
+---
+
+## skill upload
+
+上传本地 `.skill` 文件为个人技能。仅校验文件存在；若与已有技能命名冲突，会自动取 `preview_skill_key` 确认覆盖（无交互）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<filePath>` | 是 | 本地 `.skill` 文件路径（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code skill upload "./my-skill.skill" -p <project-id>
+```
+
+---
+
+## skill delete
+
+永久删除个人技能本体（不可恢复，区别于仅解绑的 `remove`）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<skill-id>` | 是 | 技能 ID（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID（仅用于回显，删除本体不依赖它） |
+
+```bash
+coze code skill delete <skill-id> -p <project-id>
+```

package/skills/using-coze-cli/coze-code/references/coze-code-tools.md

@@ -0,0 +1,47 @@
+# code tools commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+工具管理命令。用于管理项目**默认会话**启用的工具（如联网搜索、图片生成等，会话维度）。
+
+## 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `coze code tools list -p <id>` | 列出可用工具及启用状态 |
+| `coze code tools enable <toolName> -p <id>` | 在默认会话启用某工具 |
+| `coze code tools disable <toolName> -p <id>` | 在默认会话禁用某工具 |
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+---
+
+## tools list
+
+列出指定项目类型下所有可用工具，`enabled` 字段标注当前默认会话是否启用。
+
+```bash
+coze code tools list -p <project-id>
+```
+
+---
+
+## tools enable / disable
+
+启用或禁用默认会话中的某个工具。会先校验 `toolName` 是否属于该项目类型的可用工具，不可用报 `E1000`；随后合并更新默认会话的 `agent_tools`（enable 置 `true`，disable 置 `false`）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<toolName>` | 是 | 工具名（位置参数，如 `enable_image_gen`） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code tools enable enable_image_gen -p <project-id>
+coze code tools disable enable_image_gen -p <project-id>
+```

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

@@ -0,0 +1,46 @@
+---
+name: coze-file
+version: 0.2.0-alpha.bdb5d3
+description: "Coze 文件操作：上传本地文件获取在线访问地址。当用户需要上传文件、或将本地生成的文件转换为在线可访问链接时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze file --help"
+---
+
+# Coze 文件操作
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 完成认证。
+
+## 核心用途
+
+- 为 `coze generate` 产生的本地媒体文件（音频/图片/视频）提供在线访问地址
+- 上传用户提供的本地文件供 Coze 项目中使用
+
+## 命令索引
+
+| 意图 | 推荐命令 | Reference |
+|------|---------|-----------|
+| 上传本地文件 | `coze file upload <path>` | [coze-file-upload.md](references/coze-file-upload.md) |
+
+## 关键规则
+
+- 上传的文件有大小限制（默认 **512MB**）
+- 返回值中 `url` 是在线访问地址（优先返回给用户），`uri` 仅作为内部标识
+- 使用 `--format json` 获取结构化输出
+
+## 典型使用场景
+
+### 场景 1：媒体生成后的交付闭环
+
+```
+coze generate audio "文本" --output-path /tmp/coze-audio
+  → coze file upload /tmp/coze-audio/output.mp3
+  → 返回 url 给用户
+```
+
+### 场景 2：上传用户自定义文件
+
+```bash
+coze file upload ./my-document.pdf --format json
+```

package/skills/using-coze-cli/coze-file/references/coze-file-upload.md

@@ -0,0 +1,59 @@
+# file upload
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到 Coze，获取在线可访问地址。这是媒体生成交付闭环的关键环节。
+
+## 命令概述
+
+```bash
+coze file upload <file-path> [options]
+```
+
+- 业务类型：`cli_attachment`（保存 7 天）
+- 将本地文件上传至对象存储，返回可公开访问的 URL
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<file-path>` | 是 | 本地文件路径（位置参数） |
+| `--format` | 否 | 输出格式：`text` / `json` |
+
+## 返回值结构
+
+`--format json` 时：
+
+```json
+{
+  "url": "https://xxx.coze.cn/...",     // 在线访问地址 → 优先返回给用户！
+  "uri": "cos://xxx/..."                // 内部标识，仅作内部引用
+}
+```
+
+**关键区分**：
+- `url`：用户可直接在浏览器打开的 HTTPS 地址 → **交付给用户时用这个**
+- `uri`：内部存储路径标识 → 不对外暴露
+
+## 推荐命令模板
+
+```bash
+# 上传单个文件
+coze file upload /tmp/coze-audio/output.mp3 --format json
+
+# 上传图片
+coze file upload /tmp/coze-image/generated.png --format json
+
+# 上传视频
+coze file upload /tmp/coze-video/output.mp4 --format json
+
+# 上传用户自定义文件
+coze file upload ./document.pdf --format json
+```
+
+## 注意事项
+
+- **文件大小限制**：默认 512MB，超出会报错
+- `<file-path>` 必须是有效的本地文件路径（不支持目录）
+- 文件保存期限为 **7 天**
+- 上传成功后务必将 `url`（不是 `uri`）返回给用户

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

@@ -0,0 +1,84 @@
+---
+name: coze-generate
+version: 0.2.0-alpha.bdb5d3
+description: "Coze 媒体生成：文本生成图片、文本转语音(TTS)、视频生成。当用户需要使用 coze generate image/audio/video 生成音频、图片或视频时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze generate --help"
+---
+
+# Coze 媒体生成
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 完成认证。
+> **执行前必做：** 执行任何 `generate` 命令前，必须先阅读对应媒体的 reference 文档，再调用命令。
+
+## 统一交付闭环（核心规则）
+
+只要通过 `coze generate` 产出了本地文件，就进入固定闭环：
+
+```
+生成本地文件 → coze file upload → 返回在线 URL
+```
+
+- 该规则适用于**音频、图片、视频**所有媒体类型
+- 禁止返回本地路径给用户（`/tmp/...` 对用户不可访问）
+- 优先使用 `url` 而非 `uri` 作为交付链接
+
+详细上传用法参见 [`../coze-file/references/coze-file-upload.md`](../coze-file/references/coze-file-upload.md)。
+
+## 三种媒体对比总览
+
+| 维度 | image (图片) | audio (语音) | video (视频) |
+|------|-------------|-------------|-------------|
+| 命令 | `coze generate image` | `coze generate audio` | `coze generate video create` |
+| 同步/异步 | **同步返回** | **SSE 流式输出** | **异步任务** |
+| 输出路径 | `--output-path` (目录) | `--output-path` (目录) | `--output-path` (目录) |
+| 必须带 --output-path | 推荐 | **必须** | 推荐（配合 --wait） |
+| 轮询机制 | 无 | 无 | `create` → `status` 或 `--wait` |
+| 默认格式 | url | mp3 | — |
+
+## Agent 禁止行为
+
+- **不要只执行裸命令不带 `--output-path`**（尤其是 audio！裸命令可能不保存文件）
+- **不要把请求信息/元数据误判为最终结果**
+- **不要把 `--output-path` 当成最终文件名**（它是一个保存目录）
+- **不要在视频生成后不轮询 status 就声称完成**
+- **不要把本地路径发给用户**
+
+## 意图 → 命令索引
+
+| 意图 | 推荐命令 | Reference |
+|------|---------|-----------|
+| 生成图片 | `coze generate image` | [coze-generate-image.md](references/coze-generate-image.md) |
+| 语音合成(TTS) | `coze generate audio` | [coze-generate-audio.md](references/coze-generate-audio.md) |
+| 创建视频任务 | `coze generate video create` | [coze-generate-video.md](references/coze-generate-video.md) |
+| 查询视频状态 | `coze generate video status <taskId>` | [coze-generate-video.md](references/coze-generate-video.md) |
+
+## Reference 导航
+
+| 文件 | 说明 |
+|------|------|
+| [coze-generate-image.md](references/coze-generate-image.md) | 图片生成详细参数与工作流 |
+| [coze-generate-audio.md](references/coze-generate-audio.md) | 音频/TTS 详细参数与工作流（含 SSE 流式说明） |
+| [coze-generate-video.md](references/coze-generate-video.md) | 视频异步任务模型详解（create + status） |
+
+## 长耗时任务处理
+
+| 命令 | 轮询间隔 | 说明 |
+|------|----------|------|
+| `coze generate video create --wait` | 2 秒 | 等待视频生成完成，5 分钟超时 |
+
+对 `video create` 优先采用 `--wait` 参数让 CLI 自动轮询。超时后返回 taskId 供手动查询。不能只把结果留在本地日志里等待用户追问。
+
+## 常见错误速查（Generate 专用）
+
+### 错误 2：把 `coze generate audio` 的请求信息误判为最终结果
+
+- 问题：只拿到了请求元数据，没有拿到用户可访问的音频文件。
+- 修正：给命令增加 `--output-path`，然后检查输出目录中的生成文件。
+
+### 错误 4：误把 `--output-path` 当成最终文件名
+
+- 问题：CLI 帮助说明其语义更接近保存目录。
+- 修正：优先传入目录路径（如 `/tmp/coze-audio`），并在生成后从目录中定位实际文件名。