@coze/cli 0.2.0-alpha.2372ad → 0.2.0-alpha.2ae411

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

@@ -1,7 +1,7 @@
 ---
 name: using-coze-cli
-version: 0.2.0-alpha.2372ad
-description: "Coze CLI 共享基础：安装、认证登录(OAuth)、组织与空间切换、配置管理、全局执行原则、安全规则、错误码处理、代理配置。当用户首次使用 coze-cli、需要登录授权、遇到权限不足、切换组织/空间、操作 Coze Claw Session/coze session *，或任何操作前的基础检查时触发。"
+version: 0.2.0-alpha.2ae411
+description: "Coze CLI（coze 命令）统一入口与共享基础，使用任何 coze 能力前必读（登录授权、组织/空间、配置、错误码与权限排查）。四个子模块：coze code（创建/迭代网页·App·小程序·Agent·工作流等编程项目、发需求、预览、部署、环境变量/域名/数据库）、coze session（Claw 对话、PPT、播客、长任务产物）、coze generate（图片/语音 TTS/视频生成）、coze file（本地文件转在线链接）。触发场景（满足任一即触发，无需用户显式点名 coze）：想做网页/App/小程序、开发或迭代项目、上线部署；生成图片/语音/视频；做 PPT/播客；把本地文件转成在线链接；登录授权/No permission/切换组织空间；输入以 /coze-cli、/coze 开头（前缀仅作路由）。"
 metadata:
   requires:
     bins: ["coze"]
@@ -14,13 +14,11 @@ metadata:
 
 ## 适用场景
 
-- 用户明确要求"用 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 code`（核心）**：创建 Coze 编程项目（网页 / App / 小程序 / Agent / 工作流 / skill / 助手），并先按用户意图识别项目类型；发送需求 `message` 迭代开发、轮询状态、获取 preview、部署上线；以及环境变量 / 域名 / 默认会话技能 / 模型 / 工具 / 数据库 / Git 与远程仓库管理。
+- `coze generate`：文本生成图片、语音合成（TTS）、视频生成。
+- `coze file`：上传本地文件，将在线可访问链接返回给用户。
+- `coze session`（Claw）：创建/找回 session、发送 session message、监听 reply、查询 progress、处理文件 / PPT / 播客产物。
+- 用户输入以 `/coze-cli` 或 `/coze` 开头时，必须优先把这条消息视为显式路由到 Coze CLI skill；前缀只用于路由，不属于最终发给底层命令的正文。
 
 ## 模块化阅读顺序
 
@@ -167,7 +165,7 @@ npm config set registry https://registry.npmjs.org/
   - 通过 `bash -c '...; EC=$?; echo $EC > file'` 让进程自己捕获并记录退出码。
   - 退出码精确反映**本次**授权结果，不受上次登录状态影响：
     - 退出码 `0`：用户完成授权
-    - 非零退出码：授权失败（常见值：`1` 一般错误、`2` 认证失败、`6` 网络错误、`8` 超时）
+    - 非零退出码：授权失败（常见值：`1` 一般失败、`2` 认证错误、`4` 参数错误，具体原因看 JSON 输出中的错误码）
 - **授权流程（必须遵守）**：
   1. **先检查授权状态**：在发起任何需要认证的操作前，必须先执行 `coze auth status` 确认是否已完成授权。
   2. **若未授权，后台执行并轮询获取链接**：
@@ -327,14 +325,14 @@ fi
 
 - 切换组织时会**自动清空 Space ID**，需要重新选择工作空间。
 - 指定不存在的组织 ID 会**报错且不修改配置**。
-- 省略 org_id 可切换到个人账户模式（需要个人账户可用）。
+- 切换到个人账户有三种等价写法：`coze organization use`（省略 org_id）、`coze organization use ""`（显式空串）、`coze organization unset`（别名 `coze organization reset`）。均会清空 `organizationId`/`enterpriseId`（及 `spaceId`），且**不再校验个人账户是否可用**。
 - CLI 的自动上下文补全**仅作用于空间**：未配置空间时，首次执行需要上下文的命令会自动选择第一个可用空间（结果可能不是期望的，建议始终显式设置）。**组织不会自动选择**——未显式设置组织时按上文的个人账户模式处理。
 
 ### 遇到 `No permission` 的修正顺序
 
 1. `coze config list` — 查看当前配置
 2. `coze organization list` — 查看可用组织
-3. `coze organization use <org_id>` — 切换到正确的组织（或 `coze organization use` 切换到个人账户）
+3. `coze organization use <org_id>` — 切换到正确的组织（或 `coze organization unset` / `coze organization use` 切换到个人账户）
 4. `coze space list` — 查看当前组织下的空间
 5. `coze space use <space_id>` — 切换到正确的空间
 
@@ -342,7 +340,8 @@ fi
 
 - `COZE_ORG_ID`、`COZE_SPACE_ID` 环境变量可临时覆盖配置，无需修改持久化配置。
 - `--org-id`、`--space-id` 全局参数也可以临时覆盖。
-- `COZE_CLI_PLATFORM` 环境变量决定**项目访问链接的域名**：取值为 `ecs` 或 `vefaas`（忽略大小写）时，所有项目访问链接（创建、部署、预览等命令输出的 URL）使用 `www.coze.cn` 域名；其它取值或为空时使用默认的 `code.coze.cn` 域名。
+- **项目访问链接的域名由项目类型决定**：`web` / `app` / `miniprogram`（coze 3.0 项目）使用 `www.coze.cn`，其它类型（agent / workflow / skill / assistant 等）使用 `code.coze.cn`。各命令输出的 URL（如 `project_url`、部署/预览链接）已由 CLI 据此生成，直接透传即可。
+- `COZE_CLI_PLATFORM` 环境变量仅在**无法获知项目类型**的少数场景作为域名回退依据（取值 `ecs` / `vefaas` 时回退到 `www.coze.cn`，否则 `code.coze.cn`），不再覆盖按类型决定的链接。
 
 ## 配置管理概要
 
@@ -395,23 +394,17 @@ 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` | 资源冲突 |
+| `1` | `FAILURE` | 一般失败（包含所有业务错误：E3xxx 资源类 / E4xxx 配额类 / E5xxx 服务端类，退出码均为 1） |
+| `2` | `AUTH_ERROR` | 认证/授权错误（E2xxx，含 `PERMISSION_DENIED`（E2003）权限不足） |
+| `4` | `INPUT_ERROR` | 输入参数错误（E1xxx） |
+
+> 退出码只有以上 4 个（源码 `ExitCode`），映射规则：E1xxx → 4、E2xxx → 2、其余（含 E3xxx/E4xxx/E5xxx）→ 1。具体业务错误需解析 JSON 输出中的错误码（`code` 字段），不要依赖退出码细分。
 
 ### 退出码处理建议
 
-- 退出码 `2`：执行 `coze auth login` 重新登录。
-- 退出码 `5`：按"组织与空间上下文"章节的修正顺序排查。
-- 退出码 `6`/`7`：可重试一次。
+- 退出码 `2`：认证类先执行 `coze auth login` 重新登录；若 JSON 错误码为 `E2003`（`PERMISSION_DENIED`），按"组织与空间上下文"章节的修正顺序排查。
 - 退出码 `4`：检查参数拼写和格式。
+- 退出码 `1`：解析 JSON 输出中的具体错误码（E3xxx/E4xxx/E5xxx）定位原因；E5xxx 网络/服务端类可重试一次。
 
 ## 业务模块导航
 

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

@@ -1,6 +1,6 @@
 ---
 name: coze-claw
-version: 0.2.0-alpha.2372ad
+version: 0.2.0-alpha.2ae411
 description: "Coze Claw Session 会话工作流：创建/找回 claw session、发送 session message、监听回复、查询后台 progress、处理文件/PPT/播客产物。当用户需要使用 coze session * 任意命令时触发。"
 metadata:
   requires:

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

@@ -1,6 +1,6 @@
 ---
 name: coze-code
-version: 0.2.0-alpha.2372ad
+version: 0.2.0-alpha.2ae411
 description: "Coze Coding 项目开发工作流：创建项目、发送需求消息、查询状态、预览、部署、环境变量管理、域名管理、技能管理、数据库管理。当用户需要创建/管理 Coze 项目、发送开发需求、部署应用、管理数据库、或使用 coze code * 任意命令时触发。"
 metadata:
   requires:
@@ -99,7 +99,7 @@ coze code project create --message "创建一个聊天机器人" --type web --fo
 
 项目创建成功后（无论是否 `--wait`），回复用户时**必须**附上「打开项目」入口，链接指向项目对话页面，方便用户直接跳转，省去在项目列表 / 历史会话中二次查找。
 
-**链接来源**：`project create` 的 `--format json` 返回值中已含 `project_url` 字段（CLI 按平台自动生成：默认 `https://code.coze.cn/p/<project_id>`，3.0 平台 `COZE_CLI_PLATFORM=ecs|vefaas` 为 `https://www.coze.cn/p/<project_id>`）。**直接读取 `project_url` 透传给用户，不要自行拼接链接。**
+**链接来源**：`project create` 的 `--format json` 返回值中已含 `project_url` 字段（CLI 按**项目类型**自动生成域名：`web` / `app` / `miniprogram` 为 `https://www.coze.cn/p/<project_id>`，其它类型为 `https://code.coze.cn/p/<project_id>`）。**直接读取 `project_url` 透传给用户，不要自行拼接链接。**
 
 回复模板（创建成功、AI 仍在后台开发时，`<project_url>` 取自返回值）：
 
@@ -117,12 +117,28 @@ coze code project create --message "创建一个聊天机器人" --type web --fo
 
 待状态为 `done` 后，向用户给出后续操作引导（**不要**自动执行部署）：
 
+**「预览效果」一行仅 `web` 类型项目才显示**。当 `--type web` 时，**先主动获取预览地址再给引导**：执行 `coze code preview <project_id> --format json`，读取返回的 `preview_url`，把预览地址**直接展示**给用户，而不是只丢一条 `coze code preview` 命令让用户自己跑。
+
+- 沙盒初始化通常需 **1-3 分钟**，若 `preview_url` 暂未就绪可稍后重试一次。
+- **非 `web` 类型**（`app` / `miniprogram` / `agent` / `workflow` / `skill` / `assistant`）一律**省略「预览效果」整行**，不展示预览地址。
+
+引导文案（`<project_url>` / `<preview_url>` 取自返回值）：
+
 ```
-✅ 开发任务已完成，你可以继续：
-- 🛠 继续开发：coze code message send "<新需求>" -p <project_id>
-- 👀 预览效果：coze code preview <project_id>
-- 🚀 部署应用：coze code deploy <project_id>（需要时再执行）
+✅ 开发任务已完成，未自动部署，你可以继续选择：
+- 🛠 继续对话修改页面/文案/功能
 - 🔗 打开项目：<project_url>
+- 👀 预览效果：<preview_url>        # 仅 web 类型显示此行
+- 🚀 确认后发起部署
+```
+
+#### Step 1.5: 创建失败场景的文案提示
+
+当 `project create` 失败（如报错、未返回 `project_id`、上下文缺失等）时，**不要**只把原始错误堆栈丢给用户，按以下模板友好提示并引导用户补充信息后重试：
+
+```
+项目创建失败
+你可以重新发起创建，或补充更明确的项目类型、页面需求和目标空间后再试。
 ```
 
 ### Step 2: 发送需求
@@ -213,6 +229,7 @@ coze code preview <project-id>
 | 创建新项目 | `coze code project create` | `--type` 支持 agent/workflow/app/skill/web/miniprogram/assistant（常用 web/app） |
 | 列出/查看项目 | `coze code project list/get` | 支持按类型/名称筛选 |
 | 删除项目 | `coze code project delete` | 不可逆操作 |
+| 导入项目 | `coze code project import -s <github\|local>` | 导入后自动发后台初始化 query（可用 `message status` 跟进），返回值含 `project_url` |
 | 发送开发需求 | `coze code message send` | 支持 @文件引用；stdin 需加 `--stdin` |
 | 查询任务状态 | `coze code message status` | 单次查询，无 --wait |
 | 取消任务 | `coze code message cancel` | |
@@ -226,8 +243,8 @@ coze code preview <project-id>
 | 管理自定义域名 | `coze code domain add/list/remove` | add 仅接受单级域名(如 example.com) |
 | 挂载/解绑技能 | `coze code skill add/remove` | 对默认会话挂载或解绑 |
 | 列出技能 | `coze code skill list` | 支持 --my 列个人技能 |
-| 上传个人技能 | `coze code skill upload <file>` | 上传 .skill 文件，冲突自动覆盖 |
-| 删除个人技能 | `coze code skill delete <id>` | 永久删除技能本体(区别于 remove) |
+| 上传个人技能 | `coze code skill upload <file> -p <id>` | 上传 .skill 文件，冲突自动覆盖；`-p` 必填 |
+| 删除个人技能 | `coze code skill delete <skill-id> -p <id>` | 永久删除技能本体(区别于 remove)；`-p` 必填 |
 | 查看/设置模型 | `coze code model list/set` | 会话维度，set 需校验模型可用 |
 | 启用/禁用工具 | `coze code tools list/enable/disable` | 会话维度 |
 | 创建数据库 | `coze code db create` | 自动生成名称和凭据 |

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

@@ -132,15 +132,20 @@ coze code db get --db-id <databaseId> --format json
 | 字段 | 说明 |
 |------|------|
 | `database_id` | 数据库 ID |
-| `name` | 数据库名称 |
+| `database_name` | 数据库名称 |
 | `database_url` | PostgreSQL 连接 URL |
 | `supabase_url` | Supabase 项目 URL |
+| `super_user` | 超级用户名（pg-meta 认证用） |
+| `super_user_password` | 超级用户密码（pg-meta 认证用） |
+| `service_role_key` | Supabase service role 密钥 |
 | `anon_key` | Supabase 匿名密钥（用于 PostgREST 访问） |
 | `status` | 状态 |
 | `database_env` | 环境 |
 | `created_at` | 创建时间 |
 
-> `database_url` 和 `anon_key` 是敏感信息，仅在 `db get` 中返回，用于应用连接和 CLI 内部操作。
+> `database_url`、`super_user` / `super_user_password`、`service_role_key` 和 `anon_key` 是敏感信息，仅在 `db get` 中返回，用于应用连接和 CLI 内部操作。
+>
+> **文本模式（默认）下凭据会脱敏展示**（密码/密钥只保留前 4 位，连接串只遮蔽密码段）；需要完整凭据（如写 `.env`）时必须用 `--format json`，并把输出重定向到文件，不要回显到日志。
 >
 > ⚠️ **安全例外**：根 `SKILL.md` 安全规则要求"禁止输出密钥到终端明文"，而 `db get` 是该规则的**受控例外**——它必然返回凭据。使用时请：
 > - 用 `--format json` 把输出**重定向到文件**（如 `> .env.local`），不要直接回显到日志或贴给最终用户；
@@ -328,7 +333,7 @@ coze code db dump --db-id <id> --output backups/schema.sql --format json
 
 ### 前置条件
 
-- 数据库必须有 `supabase_url` 和 `database_url`（pg-meta 依赖）
+- 数据库必须有 `supabase_url` 和 `super_user` / `super_user_password`（pg-meta 认证依赖）
 
 ---
 
@@ -340,6 +345,8 @@ coze code db dump --db-id <id> --output backups/schema.sql --format json
 
 **`--confirm` 和 `--timestamp` 都是必填参数！**
 
+**`--timestamp` 必须是毫秒级整数时间戳且不能晚于当前时间**：非数字报 `E1000`；10 位秒级时间戳会被识别并报 `E1000`（提示乘以 1000）；未来时间报 `E1000`。
+
 ```bash
 # 正确 ✅
 coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm
@@ -489,7 +496,7 @@ coze code db delete --db-id <databaseId> --confirm --format json
 | 错误码 | 名称 | 说明 | 修复 |
 |--------|------|------|------|
 | E1003 | `MISSING_SPACE_ID` | 缺少空间 ID | 使用 `--space-id` 或先执行 `coze space use <spaceId>` |
-| E1007 | `DB_SQL_DANGEROUS` | 危险操作未确认 | 添加 `--confirm` 参数 |
+| E1007 | `DB_SQL_DANGEROUS` | 危险操作未确认；在 `db delete` / `db rollback` 中表示破坏性操作需要 `--confirm` 才能执行 | 添加 `--confirm` 参数 |
 | E3010 | `DB_NOT_FOUND` | 数据库不存在或无权限 | 检查 `--db-id`，执行 `coze code db list` 确认 |
 | E3012 | `DB_RESTORE_WINDOW_EXCEEDED` | 回滚时间超出恢复窗口 | 使用 `db status` 查看 `earliest_restore_time` |
 | E3013 | `DB_RESTORE_IN_PROGRESS` | 已有回滚正在进行 | 等待当前回滚完成 |

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

@@ -88,7 +88,7 @@ coze code deploy <project-id> --commit-id <commit-id> --format json
 
 ### 支持的项目类型
 
-Agent、AssistantAgent、Automation、Skill、Web (GeneralWeb)、App。
+Agent、AssistantAgent、Automation、Skill、Web (GeneralWeb)、App、WechatMiniProgram（小程序）。
 
 > **注意**：AssistantAgent 类型走独立的部署 API，不需要 commit 记录，行为与其他类型不同。
 
@@ -179,7 +179,7 @@ coze code deploy fix <project-id> --deploy-id <deploy-id> --format json
 `--format json` 时返回：
 - `deploy_history_id`: 部署记录 ID
 - `status`: 修复状态（`fix_sent` 表示修复请求已发送）
-- `message`: AI 分析和修复的详细信息
+- `message`: AI 响应的原始消息对象（`ServerMessageRaw`），文本答案在 `.content.answer` 中
 
 ### 修复流程
 

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

@@ -57,7 +57,7 @@ coze code domain add example.com -p <project-id>
 
 ## domain remove
 
-从项目移除自定义域名。
+从项目移除自定义域名。移除未绑定的域名会报 `E3000 RESOURCE_NOT_FOUND`，可先用 `domain list` 确认。
 
 ### 参数
 

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

@@ -115,15 +115,20 @@ coze code git auth status --format json | jq .status
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--provider` | 否 | Git 平台（默认 `github`） |
-| `--force` | 否 | 跳过确认直接取消（**当前实现未读取该选项，暂无实际作用，且 logout 本身无确认交互**） |
+| `--force` | 否 | 跳过确认直接取消 |
+
+### 确认逻辑
+
+- 不加 `--force` 时：**交互式终端（TTY）**会弹出确认提示，确认后才执行；**JSON 模式或非交互终端（非 TTY）**会直接报 `E1000`，必须加 `--force` 才能执行。
+- 脚本/Agent 场景（通常非 TTY 或 `--format json`）应始终加 `--force`。
 
 ### 推荐命令模板
 
 ```bash
-# 取消 GitHub 授权
+# 取消 GitHub 授权（交互式终端会弹确认）
 coze code git auth logout
 
-# 强制取消（跳过确认）
+# 强制取消（跳过确认，脚本/JSON 模式必须）
 coze code git auth logout --force
 ```
 
@@ -136,6 +141,8 @@ coze code git auth logout --force
 
 | 错误码 | 名称 | 说明 | 修复方式 |
 |--------|------|------|---------|
+| E1000 | INVALID_ARGUMENT | JSON 模式或非交互终端下未加 `--force` | 加 `--force` 跳过确认 |
+| E1015 | INVALID_PROVIDER | 不支持的 Git 平台 | 使用 `github` / `gitlab` |
 | E2007 | NOT_AUTHORIZED | 尚未授权 | 先执行 `coze code git auth login` |
 
 ---
@@ -151,6 +158,7 @@ coze code git auth logout --force
 | `-k, --keyword <keyword>` | 否 | 搜索关键词 |
 | `--page <page>` | 否 | 页码 |
 | `--page-size <size>` | 否 | 每页数量（默认 20） |
+| `--provider` | 否 | Git 平台（继承自 `git` 父命令）：`github` / `gitlab`，默认 `github` |
 
 ### 推荐命令模板
 

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

@@ -50,7 +50,7 @@ coze code message send "对比 @src/old.ts 和 @src/new.ts 的差异" -p <projec
 ```
 
 - 只支持引用**文件**（不支持目录）
-- 文件路径可以是相对路径或绝对路径
+- 文件路径可以是相对路径或绝对路径：**绝对路径不受工作目录限制**；相对路径解析后必须仍在当前工作目录内（`../` 越界会被忽略并输出 warning）。任何引用失败（文件不存在/是目录/越界）都会输出 warning 并把 `@路径` 原样作为普通文本发送
 
 ### stdin 管道输入（附加上下文）
 

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

@@ -74,9 +74,19 @@ coze code project create --message "电商网站" --type web --wait --format jso
 
 - **默认不触发部署**：`project create` 只完成项目创建与首次 AI 开发，**绝不**自动 `deploy`；部署须等用户明确要求且 `message status` 为 `done`。
 - **必须附上「打开项目」入口**：回复中给出 CLI 返回的 `project_url`，方便用户直接跳转到项目对话页面，省去在项目列表 / 历史会话中二次查找。
-  - `project_url` 由 CLI 按平台自动生成（默认 `https://code.coze.cn/p/<project_id>`；3.0 平台 `COZE_CLI_PLATFORM=ecs|vefaas` 为 `https://www.coze.cn/p/<project_id>`），**优先直接使用该字段**。
+  - `project_url` 由 CLI 按**项目类型**自动生成（`web` / `app` / `miniprogram` 为 `https://www.coze.cn/p/<project_id>`；其它类型为 `https://code.coze.cn/p/<project_id>`），**优先直接使用该字段**。
 - **必须主动跟进到开发完成**：创建后不能停在"正在开发中"。查询状态**优先主动轮询** `coze code message status -p <project_id>` 直到 `done`（`--wait` 仅备选），不要让用户自己查状态。
-- **开发任务完成后**（轮询到 `done`）给出后续引导：继续开发（`message send`）、预览效果（`preview`）、部署应用（`deploy`，需要时再执行）、打开项目（`project_url`）。
+- **开发任务完成后**（轮询到 `done`）给出后续引导：继续开发（`message send`）、部署应用（`deploy`，需要时再执行）、打开项目（`project_url`）。
+  - **「预览效果」一行仅 `web` 类型显示**：当 `--type web` 时，先执行 `coze code preview <project_id> --format json` 取回 `preview_url`，把预览地址**直接展示**给用户（沙盒初始化需 1-3 分钟，未就绪可重试一次）；非 `web` 类型（`app` / `miniprogram` / `agent` / `workflow` / `skill` / `assistant`）**省略整行**，不展示预览地址。
+
+### 创建失败时的回复
+
+当 `project create` 失败（如报错、未返回 `project_id`、上下文缺失等）时，**不要**只把原始错误堆栈丢给用户，按以下模板友好提示并引导用户补充信息后重试：
+
+```
+项目创建失败
+你可以重新发起创建，或补充更明确的项目类型、页面需求和目标空间后再试。
+```
 
 ### 坑点
 
@@ -84,7 +94,7 @@ coze code project create --message "电商网站" --type web --wait --format jso
 - `--message` 没有 `-m` 短别名，必须写全。
 - 不带 `--wait` 时命令会立即返回 project_id，但首次 AI 消息仍在后台处理中。
 - `web` / `app` / `miniprogram` 三种类型默认以 **Coze 3.0 方式**创建；其它类型使用原有创建方式。
-- 项目访问域名由环境变量 `COZE_CLI_PLATFORM` 决定（`ecs` / `vefaas` 时为 `www.coze.cn`，否则 `code.coze.cn`），详见 [`../../SKILL.md`](../../SKILL.md) 的「环境变量覆盖」。
+- 项目访问域名由**项目类型**决定（`web` / `app` / `miniprogram` 为 `www.coze.cn`，其它类型为 `code.coze.cn`）；`COZE_CLI_PLATFORM` 仅在无法获知类型时作回退，详见 [`../../SKILL.md`](../../SKILL.md) 的「环境变量覆盖」。
 
 ---
 
@@ -175,10 +185,22 @@ coze code project import -s github -r user/my-app --format json
 coze code project import -s local -f ./project.zip --format json
 ```
 
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `project_id` | 新建项目 ID |
+| `source` | 导入来源（`github` / `local`） |
+| `repo` | 源仓库全名（仅 `github` 导入时返回） |
+| `project_url` | 项目 Web 地址，可直接给用户 |
+
 ### 坑点
 
 - 远程导入需先完成 OAuth 授权（`coze code git auth login`），导入后会自动绑定到源仓库。
 - 本地文件必须是 `.zip` 且不超过 500MB。
+- 导入成功后，CLI 会自动在后台向项目默认会话发送初始化 query（「按标准流程初始化当前项目」，对齐 Web 端行为），可用 `coze code message status -p <project_id>` 跟进初始化进度；发送失败不影响导入结果，可手动补发 `coze code message send "按标准流程初始化当前项目" -p <project_id>`。
 
 ---
 

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

@@ -124,13 +124,21 @@ coze code repo bind -p <projectId> -r user/my-repo
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `-p, --project-id <projectId>` | 是 | 项目 ID |
-| `--force` | 否 | 跳过确认直接解绑（**当前实现未读取该选项，暂无实际作用，也无确认交互**） |
+| `--force` | 否 | 跳过确认直接解绑 |
+
+### 确认逻辑
+
+- 不加 `--force` 时：**交互式终端（TTY）**会弹出确认提示，确认后才执行；**JSON 模式或非交互终端（非 TTY）**会直接报 `E1000`，必须加 `--force` 才能执行。
+- 脚本/Agent 场景（通常非 TTY 或 `--format json`）应始终加 `--force`。
 
 ### 推荐命令模板
 
 ```bash
-# 解绑（仅 bindStatus=3 即已绑定时可解绑，否则报 E3014）
+# 解绑（交互式终端会弹确认；仅 bindStatus=3 即已绑定时可解绑，否则报 E3014）
 coze code repo unbind -p <projectId>
+
+# 强制解绑（跳过确认，脚本/JSON 模式必须）
+coze code repo unbind -p <projectId> --force
 ```
 
 ### 返回值
@@ -144,6 +152,7 @@ coze code repo unbind -p <projectId>
 
 | 错误码 | 名称 | 说明 | 修复方式 |
 |--------|------|------|---------|
+| E1000 | INVALID_ARGUMENT | JSON 模式或非交互终端下未加 `--force` | 加 `--force` 跳过确认 |
 | E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 用 `coze code repo status -p <id>` 查看状态 |
 
 ---
@@ -180,8 +189,8 @@ coze code repo push -p <projectId> && coze code repo status -p <projectId>
 | 错误码 | 名称 | 说明 | 修复方式 |
 |--------|------|------|---------|
 | E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 先执行 `repo bind` |
-| E3017 | NOTHING_TO_PUSH | 无需推送 | 已与远程同步 |
-| E3018 | REMOTE_HAS_UPDATES | 远程有更新 | 先执行 `repo pull` |
+| E3017 | NOTHING_TO_PUSH | 无需推送（placeholder 阶段暂不触发） | 已与远程同步 |
+| E3018 | REMOTE_HAS_UPDATES | 远程有更新（placeholder 阶段暂不触发） | 先执行 `repo pull` |
 
 ### 坑点
 
@@ -238,8 +247,8 @@ coze code repo pull -p <projectId> --conflict-strategy ours && coze code repo pu
 | 错误码 | 名称 | 说明 | 修复方式 |
 |--------|------|------|---------|
 | E3014 | REPO_NOT_BOUND | 项目未绑定仓库 | 先执行 `repo bind` |
-| E3019 | MERGE_CONFLICT | 未指定策略遇到冲突 | 加 `--conflict-strategy ours` 或 `theirs` |
-| E3020 | WOULD_OVERWRITE | 本地改动会被覆盖 | 先提交本地改动 |
+| E3019 | MERGE_CONFLICT | 未指定策略遇到冲突（placeholder 阶段暂不触发） | 加 `--conflict-strategy ours` 或 `theirs` |
+| E3020 | WOULD_OVERWRITE | 本地改动会被覆盖（placeholder 阶段暂不触发） | 先提交本地改动 |
 
 ---
 
@@ -274,7 +283,9 @@ coze code repo status -p <projectId> --format json | jq .bind_status
 | `repo_full_name` | 仓库全名（仅 bound 时输出） |
 | `html_url` | 仓库 URL（仅 bound 时输出） |
 
-> 当前实现仅输出上述字段。`ahead` / `behind` / `is_synced` 在 schema 中声明但**实际未输出**，请勿在脚本中依赖（不要用 `jq .is_synced`）。
+### 错误速查
+
+`repo status` 自身没有专属业务错误码：未授权 / 未绑定不会报错，而是通过返回值 `bind_status`（`unauth` / `not-bound`）体现，请根据该字段分支处理。
 
 ### 状态枚举
 

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

@@ -99,6 +99,10 @@ coze code skill remove <skill-id> -p <project-id>
 coze code skill upload "./my-skill.skill" -p <project-id>
 ```
 
+### 返回值
+
+`--format json` 时输出 `{ project_id, message }`（`message` 为结果提示文本），**不包含 `skill_id`**。需要拿到新技能 ID 时，请在上传后用 `coze code skill list -p <project-id> --my` 查询。
+
 ---
 
 ## skill delete

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

@@ -1,6 +1,6 @@
 ---
 name: coze-file
-version: 0.2.0-alpha.2372ad
+version: 0.2.0-alpha.2ae411
 description: "Coze 文件操作：上传本地文件获取在线访问地址。当用户需要上传文件、或将本地生成的文件转换为在线可访问链接时触发。"
 metadata:
   requires:
@@ -25,8 +25,8 @@ metadata:
 
 ## 关键规则
 
-- 上传的文件有大小限制（默认 **512MB**）
-- 返回值中 `url` 是在线访问地址（优先返回给用户），`uri` 仅作为内部标识
+- 上传文件的大小限制由服务端决定，CLI 本身不校验大小
+- 返回值中 `file_url` 是在线访问地址（优先返回给用户），`file_uri` 仅作为内部标识
 - 使用 `--format json` 获取结构化输出
 
 ## 典型使用场景
@@ -36,7 +36,7 @@ metadata:
 ```
 coze generate audio "文本" --output-path /tmp/coze-audio
   → coze file upload /tmp/coze-audio/output.mp3
-  → 返回 url 给用户
+  → 返回 file_url 给用户
 ```
 
 ### 场景 2：上传用户自定义文件

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

@@ -26,14 +26,14 @@ coze file upload <file-path> [options]
 
 ```json
 {
-  "url": "https://xxx.coze.cn/...",     // 在线访问地址 → 优先返回给用户！
-  "uri": "cos://xxx/..."                // 内部标识，仅作内部引用
+  "file_url": "https://xxx.coze.cn/...",     // 在线访问地址 → 优先返回给用户！
+  "file_uri": "cos://xxx/..."                // 内部标识，仅作内部引用
 }
 ```
 
 **关键区分**：
-- `url`：用户可直接在浏览器打开的 HTTPS 地址 → **交付给用户时用这个**
-- `uri`：内部存储路径标识 → 不对外暴露
+- `file_url`：用户可直接在浏览器打开的 HTTPS 地址 → **交付给用户时用这个**
+- `file_uri`：内部存储路径标识 → 不对外暴露
 
 ## 推荐命令模板
 
@@ -53,7 +53,7 @@ coze file upload ./document.pdf --format json
 
 ## 注意事项
 
-- **文件大小限制**：默认 512MB，超出会报错
-- `<file-path>` 必须是有效的本地文件路径（不支持目录）
+- **文件大小限制**：由服务端决定，CLI 本身不校验大小（超限时由服务端报错）
+- `<file-path>` 必须是有效的本地文件路径；**传入目录会报 `E1000`（Uploading directories is not supported）**，文件不存在报 `E3000`
 - 文件保存期限为 **7 天**
-- 上传成功后务必将 `url`（不是 `uri`）返回给用户
+- 上传成功后务必将 `file_url`（不是 `file_uri`）返回给用户

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

@@ -1,6 +1,6 @@
 ---
 name: coze-generate
-version: 0.2.0-alpha.2372ad
+version: 0.2.0-alpha.2ae411
 description: "Coze 媒体生成：文本生成图片、文本转语音(TTS)、视频生成。当用户需要使用 coze generate image/audio/video 生成音频、图片或视频时触发。"
 metadata:
   requires:
@@ -23,7 +23,7 @@ metadata:
 
 - 该规则适用于**音频、图片、视频**所有媒体类型
 - 禁止返回本地路径给用户（`/tmp/...` 对用户不可访问）
-- 优先使用 `url` 而非 `uri` 作为交付链接
+- 优先使用上传返回的 `file_url` 而非 `file_uri` 作为交付链接
 
 详细上传用法参见 [`../coze-file/references/coze-file-upload.md`](../coze-file/references/coze-file-upload.md)。
 

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

@@ -41,7 +41,7 @@ coze generate audio [prompt] [options]
 | `--ssml` | `false` | 将输入视为 SSML 标记语言 |
 | `--stdin` | — | 从管道读取 prompt（与位置参数二选一，位置参数优先） |
 | `--output-path` | — | **保存目录**（不是最终文件名！） |
-| `--format` | `text` | 输出格式：`text` / `json` |
+| `--format` | `text` | 输出格式：`text` / `json`（**全局选项**，所有 coze 命令通用，非 audio 专属） |
 
 ## 标准语音生成工作流
 
@@ -102,4 +102,4 @@ echo '<speak>欢迎来到我们的直播间</speak>' | coze generate audio --ssm
 | 裸命令不保存文件 | 不带 `--output-path` 时可能只返回元数据 | 始终带 `--output-path` |
 | `--output-path` 不是文件名 | 它是保存目录，CLI 自动命名文件 | 传入目录路径如 `/tmp/coze-audio` |
 | 生成后忘记上传 | 只说"已生成"不够 | 必须继续 `coze file upload` 再返回 URL |
-| 发了 uri 而非 url | 返回结构同时有 uri 和 url | **优先返回 url 给用户** |
+| 发了 file_uri 而非 file_url | `file upload` 返回结构同时有 file_uri 和 file_url | **优先返回 file_url 给用户** |

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

@@ -26,10 +26,10 @@ coze generate image [prompt] [options]
 | `--response-format` | `url` | 响应格式：`url` / `b64_json` |
 | `--sequential` | `disabled` | 连续图像生成模式：`auto` / `disabled` |
 | `--max-images` | `15` | 连续生成最大图片数（范围 1-15） |
-| `--optimize-prompt-mode` | — | 提示词优化模式 |
+| `--optimize-prompt-mode` | `standard` | 提示词优化模式 |
 | `--stdin` | — | 从管道读取 prompt（与位置参数二选一，位置参数优先） |
 | `--output-path` | — | **保存目录**（不是最终文件名！） |
-| `--format` | `text` | 输出格式：`text` / `json` |
+| `--format` | `text` | 输出格式：`text` / `json`（**全局选项**，所有 coze 命令通用，非 image 专属） |
 
 ## 标准图片生成工作流
 
@@ -68,7 +68,7 @@ coze generate image "不同角度的产品展示图" \
   --output-path /tmp/coze-image --format json
 
 # 自定义分辨率
-coze generate image "头像图标" --size 1024x1024 --output-path /tmp/coze-image --format json
+coze generate image "头像图标" --size 2048x2048 --output-path /tmp/coze-image --format json
 ```
 
 ## 注意事项
@@ -76,5 +76,5 @@ coze generate image "头像图标" --size 1024x1024 --output-path /tmp/coze-imag
 - **`--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` 即可
+- 尺寸约束：总像素范围约 2560x1440 ~ 4096x4096，宽高比范围约 1:16 ~ 16:1。**显式传入非法 `--size`（格式错误或超出范围）会直接报 `E1000`（退出码 4），不会静默回退默认值**；省略 `--size` 时默认 `2K`
+- `--response-format b64_json` 配合 `--output-path` 时，CLI 仍会把 base64 解码后写入文件；仅在**不带** `--output-path` 时才只返回 base64 数据不落盘。一般场景用默认 `url` 即可

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

@@ -23,21 +23,21 @@ Step 2: coze generate video status <taskId>  →  查询任务状态
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
 | `[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` |
+| `--format` | `text` | 输出格式：`text` / `json`（全局选项） |
+
+> 模型固定为 `DEFAULT_MODEL`（`doubao-seedance-1-5-pro-251215`，见源码 `video/constants.ts`），**不可通过 flag 修改**（没有 `--model` 选项）。
 
 ### 推荐工作流
 
@@ -98,28 +98,27 @@ coze generate video create "产品展示" \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `<taskId>` | 是 | 任务 ID（位置参数，来自 create 的返回值） |
-| `--format` | 否 | 输出格式：`text` / `json` |
-| `--wait` | 否 | 轮询直到任务到达终态 |
+
+> `status` 自身没有本地选项（无 `--wait`，单次查询）。结构化输出请使用全局 `--format json`。需要等待时请自行间隔轮询，或在 create 阶段用 `--wait`。
 
 ### 推荐命令模板
 
 ```bash
-# 查询状态
+# 查询状态（单次查询，需等待时自行轮询）
 coze generate video status <taskId> --format json
-
-# 轮询等待完成
-coze generate video status <taskId> --wait --format json
 ```
 
 ### 状态含义
 
 | 状态 | 含义 | 下一步操作 |
 |------|------|-------------|
-| `pending` / `processing` | 处理中 | 继续等待或稍后重试查询 |
+| `queued` / `running` | 排队/处理中 | 继续等待或稍后重试查询 |
 | `succeeded` | 生成成功 | 从返回中获取视频信息，执行 file upload |
 | `failed` | 生成失败 | 检查错误信息，调整参数后重试 |
+| `cancelled` | 任务已取消 | 重新创建任务 |
 
 ### 注意事项
 
 - **必须提供 Prompt 文本（位置参数或 `--stdin`）或者首帧/尾帧图片中至少一项作为输入**
 - 首帧/尾帧图片必须是有效的可访问 URL
+- `video status` 传入不存在/过期的 taskId 会报 `E3000 RESOURCE_NOT_FOUND`