@coze/cli 0.2.0 → 0.3.1

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

@@ -0,0 +1,326 @@
+---
+name: coze-code
+version: 0.3.1
+description: "Coze Coding 项目开发工作流：创建项目、发送需求消息、查询状态、预览、部署、环境变量管理、域名管理、技能管理、数据库管理。当用户需要创建/管理 Coze 项目、发送开发需求、部署应用、管理数据库、或使用 coze code * 任意命令时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze code --help"
+---
+
+# Coze Coding 工作流
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 完成认证和上下文配置。
+> **执行前必做：** 执行任何 `code` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。
+
+## 核心概念
+
+- **Project（项目）**：Coze Coding 的核心实体，包含 AI 编程对话历史和代码仓库。通过 `project create` 创建。
+- **Message（消息）**：发送给项目的需求或指令，由 AI 异步处理。通过 `message send` 发送。
+- **Deploy（部署）**：将项目部署到生产环境。通过 `deploy` 执行。
+- **Preview（预览）**：获取沙盒预览链接。通过 `preview` 获取。
+- **Env（环境变量）**：项目级 Secrets 管理，支持 dev/prod 环境。
+- **Domain（域名）**：项目自定义域名绑定。
+- **Skill（技能）**：项目关联的外部技能，可挂载/解绑到默认会话，也可上传/删除个人技能。
+- **Model（模型）**：项目默认会话使用的模型。通过 `model list/set` 查看与设置（会话维度）。
+- **Tools（工具）**：项目默认会话启用的工具（如联网搜索、图片生成）。通过 `tools list/enable/disable` 管理（会话维度）。
+- **Database（数据库）**：空间级 Supabase 数据库，支持 SQL 执行、类型生成、Schema 导出和 PITR 回滚。
+- **Git（Git 集成）**：Git 平台 OAuth 授权管理和仓库搜索。通过 `git auth` 管理授权，`git search` 搜索仓库。
+- **Repo（远程仓库）**：项目的远程仓库绑定和同步管理。通过 `repo` 命令组进行创建、绑定、推送、拉取等操作。
+
+## Agent 快速执行顺序
+
+1. **判断任务类型**
+   - 新建项目 → `project create`
+   - 迭代开发 → `message send` → [`message status`](references/coze-code-message.md) → [`preview`](references/coze-code-preview.md) → [`deploy`](references/coze-code-deploy.md)
+   - 查询/管理 → `project list/get/delete`
+   - 配置管理 → `env` / `domain` / `skill` / `model` / `tools`
+   - 数据库管理 → `db create / list / get / query / gen-types / dump / rollback / status / delete`
+2. **确认前置条件**
+   - 已登录? (`coze auth status`)
+   - 已选组织和空间?
+   - 如果是已有项目: 拿到 projectId
+3. **执行命令前必读对应 reference**
+
+## 标准 Coze Coding 工作流
+
+### Step 0: 使用 `@` 语法引用本地文件
+
+在 `coze code message send` 中，可直接用 `@文件路径` 引用本地文件，CLI 会自动上传并作为附件发送。
+
+- 只支持引用**文件**（不支持目录）。
+- 文件路径可以是相对路径或绝对路径。
+
+```bash
+coze code message send "请使用这张图片作为头像 @./avatar.png" -p <project-id>
+coze code message send "对比 @src/old.ts 和 @src/new.ts 的差异" -p <project-id>
+```
+
+详细用法参见 [`coze-code-message.md`](references/coze-code-message.md)。
+
+### Step 1: 创建项目
+
+详细参数和示例参见 [`coze-code-project.md`](references/coze-code-project.md)。
+
+```bash
+coze code project create --message "创建一个聊天机器人" --type web --format json
+```
+
+- `--message` 和 `--type` 均为**必填参数**（`--message` 无 `-m` 短别名）。
+- **`--type` 接受**：`agent | workflow | app | skill | web | miniprogram | assistant`（源码 `resolveProjectType` 还兼容 `webapp`）。其中 `web` / `app` 是最常用类型；`assistant` 走模板复制创建。传入未知类型会报 `E1005`。
+- 其它可选项：`--chat-mode <ask|agent|dangerous_confirm|plan>`、`--model-name`、`--tool-name`（可多次传）、`--design`（`--chat-mode plan` 时自动开启）。
+- `--wait` 选项会等待项目创建完成（包括首次 AI 消息响应）后再返回。
+- 记录返回的 `projectId`。
+
+#### Step 1.1: 准确识别项目类型（App vs 网页）
+
+创建前**必须**先根据用户的自然语言意图确定 `--type`，**不要默认用 `web`**。只要用户表达「创建 App / 应用」，一律走 `--type app` 进入 App 项目创建流程，避免被误建成网页项目；判断不清时主动反问确认。
+
+| 用户表达（示例） | 推荐 `--type` |
+|------------------|--------------|
+| "创建一个 App / 应用"、"做个 App"、"开发一款应用"、"移动端应用"、"手机 App"、"原生应用" | `app` |
+| "创建网页 / 网站"、"做个 Web 页面"、"落地页"、"官网"、"H5 页面" | `web` |
+| "小程序"、"微信小程序" | `miniprogram` |
+| "智能体 / Agent / 机器人 / 客服 bot" | `agent` |
+| "工作流 / 自动化流程" | `workflow` |
+| "技能 / skill 插件" | `skill` |
+| "助手 / assistant" | `assistant` |
+
+- 只要用户明确提到 **App / 应用** 字样（而非"网页/网站/页面"），一律用 `--type app`。
+- "应用"在「移动端 App」语境下指 `app`；仅当用户明确说"Web 应用 / 网页应用"时才用 `web`。
+- 用户意图含糊（如只说"帮我做个东西"）时，**先反问是 App 还是网页**，确认后再创建。
+
+#### Step 1.2: 仅创建项目，默认不自动部署
+
+- `project create` **只负责创建项目并触发首次 AI 开发**，**绝不**自动部署。创建成功后**不要**主动执行 `deploy`。
+- 部署是独立动作，**必须**由用户明确要求"部署 / 上线"，且 `message status` 为 `done` 时才执行（见 Step 3 / Step 4）。
+
+#### Step 1.3: 创建成功后的标准回复（含「打开项目」入口）
+
+项目创建成功后（无论是否 `--wait`），回复用户时**必须**附上「打开项目」入口，链接指向项目对话页面，方便用户直接跳转，省去在项目列表 / 历史会话中二次查找。
+
+**链接来源**：`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>` 取自返回值）：
+
+```
+✅ 项目已创建成功，正在为你开发中…
+- 🔗 打开项目：<project_url>
+- 可继续发送需求迭代，或稍候查看开发结果。
+```
+
+#### Step 1.4: 开发任务完成后的引导文案
+
+**创建后必须主动跟进到开发完成**，不能停在"正在开发中"就结束。查询状态**优先使用主动轮询**的方式：
+- **首选**：创建后**主动轮询** `coze code message status -p <project_id> --format json`（`message status` 无 `--wait`，需自行间隔轮询），直到状态为 `done`，**不要**让用户自己去查状态。
+- 备选：创建时加 `--wait` 让 CLI 等到首次 AI 开发完成再返回（仅在确有需要时使用，状态跟进仍以主动轮询为准）。
+
+待状态为 `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>` 取自返回值）：
+
+```
+✅ 开发任务已完成，未自动部署，你可以继续选择：
+- 🛠 继续对话修改页面/文案/功能
+- 🔗 打开项目：<project_url>
+- 👀 预览效果：<preview_url>        # 仅 web 类型显示此行
+- 🚀 确认后发起部署
+```
+
+#### Step 1.5: 创建失败场景的文案提示
+
+当 `project create` 失败（如报错、未返回 `project_id`、上下文缺失等）时，**不要**只把原始错误堆栈丢给用户，按以下模板友好提示并引导用户补充信息后重试：
+
+```
+项目创建失败
+你可以重新发起创建，或补充更明确的项目类型、页面需求和目标空间后再试。
+```
+
+### Step 2: 发送需求
+
+详细参数和示例参见 [`coze-code-message.md`](references/coze-code-message.md)。
+
+```bash
+coze code message send "请优化应用配色..." \
+  --project-id <project-id> \
+  --format json
+```
+
+- `-p` / `--project-id` 指定项目 ID，也可通过 `COZE_PROJECT_ID` 环境变量设置（仅 `message` 命令组支持该环境变量回退）。
+- 支持 stdin 管道输入，但**必须显式加 `--stdin`**：`cat requirements.txt | coze code message send "请按此需求开发" --stdin -p <id>`。
+- `--format json` 时输出 NDJSON 事件流，每行一个 JSON 对象。**必须按行解析**。
+
+### Step 3: 部署前先查状态
+
+详细说明参见 [`coze-code-message.md`](references/coze-code-message.md)。
+
+- 收到"部署"要求时，**必须**先确认 `message status` 已结束。
+- 状态为 `processing` 时禁止直接部署，否则可能出现 `refs/heads/main does not exist` 等错误。
+
+```bash
+coze code message status --project-id <project-id> --format json
+```
+
+- `message status` 是**单次查询**（无 `--wait`，不轮询）：状态为 `done` 时自动拉取并返回 answer，否则返回当前状态。需要等待时，请自行轮询调用。
+- `message cancel` 可取消正在进行的消息。
+
+### Step 4: 部署
+
+详细参数和坑点参见 [`coze-code-deploy.md`](references/coze-code-deploy.md)。
+
+- `deploy` 直接接收项目 ID 作为**位置参数**，**不要**加 `--project-id`。
+
+```bash
+coze code deploy <project-id> --format json
+```
+
+- `--wait` 会轮询等待部署完成（轮询间隔 3 秒）。
+- 部署前项目必须有 commit 记录，否则会失败。
+
+### Step 5: 查询部署结果 & 获取预览
+
+```bash
+# 查询部署状态
+coze code deploy status <project-id> --format json
+
+# 获取预览链接
+coze code preview <project-id>
+```
+
+- 默认查询最新部署记录，也可通过 `--deploy-id <id>` 指定具体部署记录。
+- 直到 `status` 为 `Succeeded`，再把线上地址返回给用户。
+- 沙盒初始化通常需要 1-3 分钟。
+
+## Agent 禁止行为
+
+- 不要在 `project create` 后**自动部署**——创建只完成项目创建与首次 AI 开发，部署须等用户明确要求
+- 不要在 `project create` 后**停在"正在开发中"就结束**——查询状态优先主动轮询 `message status` 到 `done`（`--wait` 仅备选），再给出完成引导文案（Step 1.4），不要让用户自己查状态
+- 不要在项目创建成功后**漏掉「打开项目」入口**——回复必须附上返回值里的 `project_url`（不要自行拼接链接）
+- 不要在用户表达「创建 App / 应用」时误用 `--type web`——应识别为 `--type app`，意图含糊先反问
+- 不要在 message 仍为 **processing** 时直接部署
+- 不要对 deploy 使用 **`--project-id`**（它是位置参数！）
+- 不要给 project create 的 **`--type`** 传受支持列表（`agent|workflow|app|skill|web|miniprogram|assistant`）以外的值，否则报 `E1005`
+- 不要在没有 `--stdin` 时指望管道输入被读取（`message send` 必须显式加 `--stdin` 才读 stdin）
+- 不要忽略 **NDJSON 事件流的逐行解析要求**
+- 不要把本地路径发给用户（必须走 file upload 返回在线链接）
+
+## 长耗时任务处理
+
+| 命令 | 轮询间隔 | 说明 |
+|------|----------|------|
+| `coze code project create --wait` | — | 等待项目创建和首次 AI 响应完成 |
+| `coze code deploy --wait` | 3 秒 | 等待部署到达终态 |
+| `coze code deploy status --wait` | 3 秒 | 复用父级 `deploy --wait`，等待部署到达终态 |
+| `coze code deploy fix --wait` | — | 等待修复消息响应 |
+
+> `message status` **没有** `--wait`，需要等待时请自行轮询；`deploy status` 自身不声明 `--wait`，而是读取父命令 `deploy --wait`。
+
+优先使用 `--wait` 让 CLI 自动轮询。到达终态后，必须主动把最终结果反馈给用户。
+
+## 意图 → 命令索引
+
+| 意图 | 推荐命令 | 备注 |
+|------|---------|------|
+| 创建新项目 | `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` | |
+| 查看对话历史 | `coze code message history` | 支持 --before / --after 翻页 |
+| 部署到生产 | `coze code deploy <id>` | **位置参数**, 不用 --project-id；支持 --commit-id/--table-name/--connector-id |
+| 查询部署状态 | `coze code deploy status <id>` | |
+| 列出部署历史 | `coze code deploy list <id>` | 支持 --page-size/--page-token |
+| 修复失败部署 | `coze code deploy fix <id>` | 把部署日志发给 AI 修复，仅 Failed 可修 |
+| 获取预览链接 | `coze code preview <id>` | 沙盒初始化需 1-3 分钟；仅 Web/App 类型可预览 |
+| 管理环境变量 | `coze code env set/list/delete` | list 支持 --env dev\|prod；delete 固定 dev；set 不支持 Skill 项目 |
+| 管理自定义域名 | `coze code domain add/list/remove` | add 仅接受单级域名(如 example.com) |
+| 挂载/解绑技能 | `coze code skill add/remove` | 对默认会话挂载或解绑 |
+| 列出技能 | `coze code skill list` | 支持 --my 列个人技能 |
+| 上传个人技能 | `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` | 自动生成名称和凭据 |
+| 列出数据库 | `coze code db list` | 支持 --all 自动翻页 |
+| 查看数据库详情 | `coze code db get --db-id <id>` | 含连接 URL 和凭据 |
+| 执行 SQL | `coze code db query --db-id <id> --sql "..."` | 危险 SQL 需 --confirm |
+| 生成 TS 类型 | `coze code db gen-types --db-id <id>` | 基于 PostgREST OpenAPI |
+| 导出 Schema | `coze code db dump --db-id <id>` | 支持 --schema-only / --data-only |
+| 回滚数据库 | `coze code db rollback --db-id <id> --timestamp <ts> --confirm` | PITR 回滚，需 --confirm |
+| 查看数据库状态 | `coze code db status --db-id <id>` | 含回滚进度 |
+| 删除数据库 | `coze code db delete --db-id <id> --confirm` | 不可逆，需 --confirm |
+| 授权 Git 平台 | `coze code git auth login` | 需要浏览器完成 OAuth |
+| 检查 Git 授权状态 | `coze code git auth status` | |
+| 取消 Git 授权 | `coze code git auth logout` | 影响空间下所有项目 |
+| 搜索远程仓库 | `coze code git search` | 需先完成 Git 授权 |
+| 创建远程仓库 | `coze code repo create` | 创建空仓库供绑定 |
+| 绑定远程仓库 | `coze code repo bind` | 仅支持空仓库 |
+| 解绑远程仓库 | `coze code repo unbind` | 不删除远程仓库 |
+| 推送到远程 | `coze code repo push` | 需先绑定仓库 |
+| 拉取远程变更 | `coze code repo pull` | 支持冲突策略 |
+| 查看仓库同步状态 | `coze code repo status` | |
+
+## 命令分组
+
+> **执行前必做：** 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。
+
+| 命令分组 | 说明 | Reference |
+|----------|------|-----------|
+| [`project commands`](references/coze-code-project.md) | `create / list / get / delete / import / db list` | 项目全生命周期管理 |
+| [`message commands`](references/coze-code-message.md) | `send / status / cancel / history` | 需求发送与状态追踪 |
+| [`deploy commands`](references/coze-code-deploy.md) | `deploy / status / list / fix` | 部署、状态查询与失败修复 |
+| [`preview`](references/coze-code-preview.md) | `preview` | 沙盒预览链接 |
+| [`env commands`](references/coze-code-env.md) | `set / list / delete` | 环境变量(Secrets)管理 |
+| [`domain commands`](references/coze-code-domain.md) | `add / list / remove` | 自定义域名管理 |
+| [`skill commands`](references/coze-code-skill.md) | `list / add / remove / upload / delete` | 技能管理 |
+| [`model commands`](references/coze-code-model.md) | `list / set` | 会话模型管理 |
+| [`tools commands`](references/coze-code-tools.md) | `list / enable / disable` | 会话工具管理 |
+| [`db commands`](references/coze-code-db.md) | `create / list / get / query / gen-types / dump / rollback / status / delete` | 数据库管理 |
+| [`git commands`](references/coze-code-git.md) | `auth login / auth status / auth logout / search` | Git 平台 OAuth 授权与仓库搜索 |
+| [`repo commands`](references/coze-code-repo.md) | `create / bind / unbind / push / pull / status` | 远程仓库绑定与同步 |
+
+## 常见错误速查（Code 专用）
+
+> 以下为 Code 专用错误（本节内独立编号 1–7）；基础类错误（认证、`--format json` 等）见根 [`../SKILL.md`](../SKILL.md)。
+
+### 错误 1：把本地路径发给用户
+
+- 问题：`/tmp/...` 只能本机访问，用户无法直接打开。
+- 修正：始终执行 `coze file upload`，把上传后的在线 `URL` 发给用户。
+
+### 错误 2：message 仍在 processing 时直接部署
+
+- 问题：项目还没有可部署的代码或 commit，导致部署失败。
+- 修正：始终先执行 `coze code message status -p <id> --format json` 确认状态为完成后再部署。
+
+### 错误 3：deploy 命令使用 --project-id 参数
+
+- 问题：`deploy` 命令的项目 ID 是**位置参数**，不是 `--project-id` 选项。
+- 修正：使用 `coze code deploy <project-id>` 而非 `coze code deploy --project-id <id>`。
+
+### 错误 4：project create --type 传了不支持的类型
+
+- 问题：`--type` 只接受 `agent | workflow | app | skill | web | miniprogram | assistant`（源码另兼容 `webapp`）；传入其它字符串会报 `E1005 Unknown project type`。
+- 修正：从受支持列表中选择类型；常用 `web` / `app`。
+
+### 错误 5：message send 管道输入未加 --stdin
+
+- 问题：`message send` 只有显式传 `--stdin` 才会读取标准输入，否则管道内容被忽略。
+- 修正：`cat ctx.txt | coze code message send "..." --stdin -p <id>`。
+
+### 错误 6：db 危险操作未加 --confirm
+
+- 问题：`db query`、`db delete`、`db rollback` 涉及危险操作时必须加 `--confirm`，否则 JSON 模式下报错。
+- 修正：始终在执行 DROP/TRUNCATE/DELETE 无 WHERE/UPDATE 无 WHERE 等 SQL 时加 `--confirm`；删除和回滚操作也必须加 `--confirm`。
+
+### 错误 7：数据库未 active 时执行操作
+
+- 问题：数据库处于 `creating` 状态时无法执行 SQL、生成类型或导出 Schema。
+- 修正：先执行 `coze code db status --db-id <id>` 确认状态为 `active` 后再操作。