@coze/cli 0.1.8 → 0.2.0-alpha.bdb5d3

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

@@ -0,0 +1,258 @@
+# code deploy commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+部署相关命令索引。涵盖将项目部署到生产环境、查询部署状态、自动修复失败部署和浏览部署历史。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code deploy <project-id>` | 部署到生产环境 |
+| 本文档 | `coze code deploy status <project-id>` | 查询部署状态 |
+| 本文档 | `coze code deploy fix <project-id>` | 自动修复部署失败 |
+| 本文档 | `coze code deploy list <project-id>` | 查看部署历史列表 |
+
+---
+
+## deploy
+
+将项目部署到生产环境。
+
+### 核心坑点（最高优先级标注）
+
+**项目 ID 是位置参数，不是 `--project-id` 选项！**
+
+```bash
+# 正确 ✅
+coze code deploy <project-id>
+
+# 错误 ❌
+coze code deploy --project-id <project-id>
+```
+
+### 前置条件
+
+1. **message status 必须已结束**（不能是 `processing` 状态）
+2. 项目必须有 commit 记录（否则报 `MISSING_COMMIT_HASH` 错误）
+3. Mini-program 类型项目需先完成 AppID 授权配置（否则报 `MINIPROGRAM_NOT_AUTHORIZED` 错误）
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | **位置参数**，不是选项 |
+| `--commit-id <commitId>` | 否 | 指定要部署的 commit ID（默认自动获取最新 commit） |
+| `--wait` | 否 | 轮询等待部署完成（内置 3 秒间隔轮询，无超时限制） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+# 基本部署（触发后立即返回）
+coze code deploy <project-id> --format json
+
+# 等待部署完成（阻塞直到终态）
+coze code deploy <project-id> --wait --format json
+
+# 部署指定 commit
+coze code deploy <project-id> --commit-id <commit-id> --format json
+```
+
+### 返回值
+
+`--format json` 时返回结构化数据：
+
+| 字段 | 说明 |
+|------|------|
+| `projectId` | 项目 ID |
+| `status` | 部署状态（见下方状态枚举） |
+| `domain` | 线上访问域名 |
+| `deployHistoryId` | 部署记录 ID |
+| `commitHash` | 部署的 commit hash |
+
+### 部署状态枚举
+
+| 状态 | 含义 | 是否终态 |
+|------|------|:---:|
+| `Pending` | 等待部署 | ❌ |
+| `Running` | 部署进行中 | ❌ |
+| `Succeeded` | 部署成功 | ✅ |
+| `Failed` | 部署失败 | ✅ |
+| `Canceled` | 部署已取消 | ✅ |
+| `Interrupted` | 部署被中断 | ❌ |
+
+> 终态集合（源码 `TERMINAL_STATUSES`）：`Succeeded`、`Failed`、`Canceled`。`--wait` 轮询仅在到达这三个状态时停止。
+>
+> ⚠️ **`Interrupted` 不属于终态**：`--wait` 不会因它停止，会一直轮询到沙箱超时。脚本里**不要**只靠 `--wait` 自然结束，应自带超时上限并把 `Interrupted` 也当作需人工介入的结束信号处理。
+
+### 支持的项目类型
+
+Agent、AssistantAgent、Automation、Skill、Web (GeneralWeb)、App。
+
+> **注意**：AssistantAgent 类型走独立的部署 API，不需要 commit 记录，行为与其他类型不同。
+
+---
+
+## deploy status
+
+查询项目的部署状态。**单次查询**，不加 `--wait` 时查一次就返回。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | **位置参数**，不是选项 |
+| `--deploy-id <deployId>` | 否 | 指定具体的部署记录 ID（默认查最新） |
+| `--wait` | 否 | 轮询直到部署到达终态（内置 3 秒间隔，无超时限制） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+# 查询最新部署状态
+coze code deploy status <project-id> --format json
+
+# 查询指定部署记录
+coze code deploy status <project-id> --deploy-id <deploy-id> --format json
+
+# 轮询等待终态（阻塞）
+coze code deploy status <project-id> --wait --format json
+```
+
+### 终态判断
+
+- `Succeeded`：部署成功，返回线上地址（`domain` 字段）给用户
+- `Failed`：部署失败，检查错误信息，可使用 `deploy fix` 自动修复
+- `Canceled`：部署已取消
+
+> 如果没有部署记录，会报 `NO_DEPLOYMENT_HISTORY` 错误，需先执行 `coze code deploy` 触发部署。
+
+---
+
+## deploy fix
+
+自动修复失败的部署。获取部署日志发送给 AI 分析并自动修复代码。
+
+### 默认行为
+
+- **不加 `--wait`**：**非阻塞**，修复请求通过 detached 子进程后台执行，命令立即返回。可通过 `coze code message status -p <project-id>` 轮询修复进度。
+- **加 `--wait`**：**阻塞**，等待 AI 分析并返回修复结果后才返回。
+
+### 使用场景
+
+当部署失败时（`status` 为 `Failed`），可以使用此命令自动修复：
+- 代码编译错误
+- 配置问题
+- 依赖缺失
+
+### 前置条件
+
+1. **部署状态必须为 `Failed`**（其他状态会报 `DEPLOYMENT_NOT_FAILED` 错误）
+2. 必须有部署记录存在
+3. 部署日志不能为空
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | **位置参数**，不是选项 |
+| `--deploy-id <deployId>` | 否 | 指定具体的部署记录 ID（默认修复最新失败的部署） |
+| `--wait` | 否 | 等待 AI 修复完成后返回（默认非阻塞） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+# 修复最新失败的部署（非阻塞，后台执行）
+coze code deploy fix <project-id> --format json
+
+# 修复并等待 AI 完成（阻塞）
+coze code deploy fix <project-id> --wait --format json
+
+# 修复指定部署记录
+coze code deploy fix <project-id> --deploy-id <deploy-id> --format json
+```
+
+### 返回值（`--wait` 时）
+
+`--format json` 时返回：
+- `deploy_history_id`: 部署记录 ID
+- `status`: 修复状态（`fix_sent` 表示修复请求已发送）
+- `message`: AI 分析和修复的详细信息
+
+### 修复流程
+
+1. **获取部署日志**：从失败的部署记录中提取日志 URL 并下载日志内容
+2. **发送给 AI**：将日志作为 prompt 发送给项目的 AI（与 `message send` 走同一条通道）
+3. **AI 自动修复**：AI 分析日志并尝试修改代码
+4. **手动重新部署**：修复完成后需要执行 `coze code deploy` 重新部署
+
+### 完整修复案例
+
+```bash
+# 1. 查看部署状态（确认为 Failed）
+coze code deploy status <project-id> --format json
+
+# 2. 发起修复（非阻塞）
+coze code deploy fix <project-id> --format json
+
+# 3. 轮询等待 AI 修复完成
+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)
+  if [ "$status" = "done" ] || [ "$status" = "completed" ]; then
+    echo "修复完成"
+    break
+  fi
+  sleep 30
+done
+
+# 4. 重新部署
+coze code deploy <project-id> --wait --format json
+```
+
+### 注意事项
+
+- `deploy fix` 只修改代码，不会自动触发重新部署
+- 修复完成后**必须**手动执行 `coze code deploy` 重新部署
+- 如果 AI 无法自动修复，需要手动检查代码或配置
+
+---
+
+## deploy list
+
+查看项目的部署历史列表，支持分页。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | **位置参数**，不是选项 |
+| `--page-size <pageSize>` | 否 | 每页记录数（默认 10） |
+| `--page-token <pageToken>` | 否 | 分页 token（用于翻页） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+# 查看最近部署记录
+coze code deploy list <project-id> --format json
+
+# 指定每页条数
+coze code deploy list <project-id> --page-size 20 --format json
+```
+
+### 返回值
+
+`--format json` 时返回数组，每项包含：
+
+| 字段 | 说明 |
+|------|------|
+| `deploy_history_id` | 部署记录 ID |
+| `project_id` | 项目 ID |
+| `status` | 部署状态 |
+| `commit_hash` | commit hash |
+| `domain_list` | 部署域名列表 |
+| `created_at` | 创建时间 |
+| `can_rollback` | 是否可回滚 |

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

@@ -0,0 +1,73 @@
+# code domain commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+自定义域名管理命令。用于为项目绑定和管理自定义域名。
+
+## 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `coze code domain list -p <id>` | 列出项目已绑定的域名 |
+| `coze code domain add <domain> -p <id>` | 添加自定义域名 |
+| `coze code domain remove <domain> -p <id>` | 删除自定义域名 |
+
+> 三个子命令均通过 `-p` / `--project-id`（必填）指定项目；`domain list` **不使用位置参数**。
+
+---
+
+## domain list
+
+列出项目关联的所有自定义域名。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+coze code domain list -p <project-id>
+```
+
+---
+
+## domain add
+
+为项目添加自定义域名。
+
+> **域名格式校验**：仅接受形如 `example.com` 的**单级域名**（正则 `^[a-zA-Z0-9][a-zA-Z0-9-]*\.[a-zA-Z0-9][a-zA-Z0-9-]*$`，恰好一个点）。`api.myapp.com`、`www.example.com` 等多级域名**不通过**校验，会报 `E1004`。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<domain>` | 是 | 域名（位置参数，单级域名如 `example.com`） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+coze code domain add example.com -p <project-id>
+```
+
+---
+
+## domain remove
+
+从项目移除自定义域名。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<domain>` | 是 | 域名（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+coze code domain remove example.com -p <project-id>
+```

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

@@ -0,0 +1,82 @@
+# code env commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+环境变量（Secrets）管理命令。用于管理项目级别的环境变量。
+
+> **环境（`--env`）支持范围（重要）：**
+> - 仅 **`env list`** 支持 `--env dev|prod`（默认 `dev`，且只有 `prod` 大小写不敏感生效，其它值静默回退 `dev`）。
+> - **`env set` 没有 `--env` 选项**，写入开发环境。
+> - **`env delete` 没有 `--env` 选项**，固定删除开发环境变量。
+
+## 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `coze code env set <key> <value> -p <id>` | 设置环境变量（dev） |
+| `coze code env list -p <id>` | 列出环境变量（支持 `--env`） |
+| `coze code env delete <key> -p <id>` | 删除环境变量（dev） |
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID（本命令组**不读取** `COZE_PROJECT_ID` 环境变量） |
+
+---
+
+## env set
+
+设置项目环境变量（写入开发环境）。
+
+> **Skill 类型项目暂不支持 `env set`**（会报 `E3008`）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<key>` | 是 | 环境变量名 |
+| `<value>` | 是 | 环境变量值 |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code env set API_KEY sk-xxxxx -p <project-id>
+```
+
+---
+
+## env list
+
+列出项目的环境变量，可按环境过滤。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID |
+| `--env` | 否 | 目标环境：`dev`（默认）/ `prod` |
+
+```bash
+# 列出开发环境变量（默认）
+coze code env list -p <project-id>
+
+# 列出生产环境变量
+coze code env list -p <project-id> --env prod
+```
+
+---
+
+## env delete
+
+删除指定的开发环境变量（固定 dev，无 `--env` 选项）。若变量不存在报 `E3003`。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<key>` | 是 | 要删除的环境变量名 |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code env delete API_KEY -p <project-id>
+```

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

@@ -0,0 +1,181 @@
+# code git commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+Git 平台集成管理命令。用于管理 Git 平台的 OAuth 授权和仓库搜索。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code git auth login` | 通过 OAuth 授权 Git 平台 |
+| 本文档 | `coze code git auth status` | 检查 OAuth 授权状态 |
+| 本文档 | `coze code git auth logout` | 取消 OAuth 授权 |
+| 本文档 | `coze code git search` | 搜索远程仓库 |
+
+> 注意：所有命令均需先完成认证和组织/空间上下文配置。授权存储在空间（Space）级别，同空间项目共享。
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--provider` | 否 | Git 平台：`github` / `gitlab`（默认 `github`，gitlab 暂未支持） |
+
+---
+
+## auth login
+
+通过 OAuth 授权 Git 平台（如 GitHub）。命令会打开浏览器让用户完成授权，并轮询等待授权完成（超时 120 秒）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--provider` | 否 | Git 平台（继承自 `git` 父命令，默认 `github`） |
+
+### 推荐命令模板
+
+```bash
+# 授权 GitHub（最常用）
+coze code git auth login
+
+# 显式指定 provider
+coze code git auth login --provider github
+```
+
+### 行为说明
+
+1. 获取 Git 集成列表，找到对应 provider 的 `integration_id`
+2. 获取 OAuth 授权 URL 并输出到终端
+3. 等待用户在浏览器中完成授权（轮询间隔 2 秒，超时 120 秒）
+4. 授权成功后获取用户信息并输出
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `provider` | Git 平台名称 |
+| `status` | `authorized` |
+| `user` | 授权用户名 |
+
+### 坑点
+
+- **需要浏览器环境**：在无头环境中需手动复制终端输出的 URL 到浏览器
+- **授权是空间级别的**：授权成功后，同空间下所有项目可复用
+- **超时后需要重新执行命令**
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E1015 | INVALID_PROVIDER | 不支持的 Git 平台 | 使用 `github`（代码 `VALID_PROVIDERS` 也放行 `gitlab`，但后端支持尚不完整） |
+| E2005 | OAUTH_TIMEOUT | 授权超时（轮询 120 秒） | 重新执行 `coze code git auth login` |
+
+---
+
+## auth status
+
+检查指定 Git 平台的 OAuth 授权状态和用户信息。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--provider` | 否 | Git 平台（默认 `github`） |
+
+### 推荐命令模板
+
+```bash
+# 检查 GitHub 授权状态
+coze code git auth status
+
+# JSON 输出
+coze code git auth status --format json
+
+# 流水线中判断是否已授权
+coze code git auth status --format json | jq .status
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `provider` | Git 平台名称 |
+| `status` | `authorized` 或 `not-authorized` |
+| `user` | 已授权时返回用户信息（`login`, `avatar_url`） |
+
+---
+
+## auth logout
+
+取消 Git 平台的 OAuth 授权。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--provider` | 否 | Git 平台（默认 `github`） |
+| `--force` | 否 | 跳过确认直接取消（**当前实现未读取该选项，暂无实际作用，且 logout 本身无确认交互**） |
+
+### 推荐命令模板
+
+```bash
+# 取消 GitHub 授权
+coze code git auth logout
+
+# 强制取消（跳过确认）
+coze code git auth logout --force
+```
+
+### 注意事项
+
+- **影响范围**：取消授权会影响当前空间下所有使用该 provider 的项目
+- 已绑定仓库的项目将失去同步能力，直到重新授权
+
+### 错误速查
+
+| 错误码 | 名称 | 说明 | 修复方式 |
+|--------|------|------|---------|
+| E2007 | NOT_AUTHORIZED | 尚未授权 | 先执行 `coze code git auth login` |
+
+---
+
+## search
+
+搜索已授权 Git 平台上可访问的仓库。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-k, --keyword <keyword>` | 否 | 搜索关键词 |
+| `--page <page>` | 否 | 页码 |
+| `--page-size <size>` | 否 | 每页数量（默认 20） |
+
+### 推荐命令模板
+
+```bash
+# 列出所有可访问仓库
+coze code git search
+
+# 按关键词搜索
+coze code git search --keyword react
+
+# 分页搜索
+coze code git search -k react --page 2 --page-size 10
+
+# JSON 输出用于脚本处理
+coze code git search -k my-repo --format json
+```
+
+### 返回值
+
+| 字段 | 说明 |
+|------|------|
+| `items` | 仓库列表（`full_name`, `private`, `size`, `updated_at`） |
+| `total_count` | 总匹配数量 |
+
+### 坑点
+
+- **需要先完成授权**：未授权时搜索会失败
+- 搜索范围是授权用户有访问权限的所有仓库