@coze/cli 0.1.8 → 0.2.0-alpha.bdb5d3

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

@@ -0,0 +1,240 @@
+# code message commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+消息交互相关命令索引。涵盖向项目发送开发需求、查询任务状态、取消进行中的任务、查看对话历史。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code message send` | 发送需求（支持@文件引用、--stdin 附加上下文） |
+| 本文档 | `coze code message status` | 查询任务状态（单次查询，需脚本轮询） |
+| 本文档 | `coze code message cancel` | 取消正在进行的任务 |
+| 本文档 | `coze code message history` | 查看项目对话历史 |
+
+> 共享参数：`-p` / `--project-id` 指定项目 ID（或通过环境变量 `COZE_PROJECT_ID` 设置）。
+
+---
+
+## message send
+
+向项目发送开发需求或指令，由 AI 异步处理。
+
+### 核心警告
+
+**部署前必须确认 message status 已结束！** 状态为 `processing` 时禁止直接部署，否则会出现 `refs/heads/main does not exist` 等错误。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<message>` | 条件必填* | 需求文本 |
+| `-p` / `--project-id` | 是 | 项目 ID |
+| `--stdin` | 否 | 从 stdin 管道读取附加上下文 |
+| `--wait` | 否 | 等待 AI 响应完成后再返回（默认后台发送） |
+| `--format` | 否 | 输出格式；`json` 时输出 NDJSON 事件流 |
+
+*\* `<message>` 必填，`--stdin` 为可选附加上下文*
+
+### @语法引用本地文件
+
+在 message 文本中可直接用 `@文件路径` 引用本地文件，CLI 会自动上传并作为附件发送：
+
+```bash
+# 引用单张图片
+coze code message send "请使用这张图片作为头像 @./avatar.png" -p <project-id>
+
+# 对比两个文件
+coze code message send "对比 @src/old.ts 和 @src/new.ts 的差异" -p <project-id>
+```
+
+- 只支持引用**文件**（不支持目录）
+- 文件路径可以是相对路径或绝对路径
+
+### stdin 管道输入（附加上下文）
+
+使用 `--stdin` 显式声明从管道读取附加上下文，与 `<message>` 拼接后发送：
+
+```bash
+# 从文件管道输入作为上下文
+cat error.log | coze code message send "分析这个错误" --stdin -p <project-id>
+
+# 从其他命令管道输入
+echo "修复登录页面的样式问题" | coze code message send "请查看以下日志" --stdin -p <project-id>
+```
+
+- **不传 `--stdin` 时 stdin 会被忽略**，不会阻塞等待
+- 管道内容会追加在 `<message>` 之后，格式为 `消息\n\n上下文`
+- 适合将日志、错误输出、代码片段等作为上下文附加到需求中
+
+### NDJSON 解析规则（`--format json` 时）
+
+当使用 `--format json` 时，输出为 NDJSON 事件流：
+
+- 每行是一个独立的 JSON 对象
+- 必须按行逐行解析，不能整段 `JSON.parse()`
+- 关键字段：
+  - `content`: 响应内容片段
+  - `role`: 角色（`assistant` / `user`）
+  - `finish`: 是否为最终结果（`true` / `false`）
+  - `type`: 事件类型
+- **找 `finish: true` 的行来获取最终结果**
+
+### 推荐命令模板
+
+```bash
+# 基本发送
+coze code message send "请优化应用配色方案" --project-id <project-id> --format json
+
+# 带 @文件引用
+coze code message send "分析 @src/app.ts 的代码质量" -p <project-id> --format json
+
+# stdin 管道输入 + json 格式
+cat spec.md | coze code message send "请按此规格实现" --stdin -p <project_id> --format json
+```
+
+### text 模式 vs json 模式
+
+- **text 模式**（默认）：直接输出人类可读的 AI 响应内容，适合展示给用户
+- **json 模式**：输出结构化 NDJSON 事件流，适合 Agent 提取和处理数据
+
+---
+
+## message status
+
+查询项目中最近一次消息的处理状态。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--project-id` / `-p` | 是 | 项目 ID |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+> `message status` 是**单次查询**，不会自动轮询。如需等待任务完成，需在脚本中循环调用（见 `SKILL.md` "长时间命令处理"）。
+
+### 推荐命令模板
+
+```bash
+# 查询状态
+coze code message status --project-id <project-id> --format json
+
+# 脚本轮询等待完成
+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 "$result"
+    break
+  fi
+  sleep 30
+done
+```
+
+### 状态含义
+
+> **完成态判定以源码为准**：CLI 仅当 `status === 'done'` 时才判定为完成并自动拉取 answer（见 `status.ts`）。其它取值（如 `running` 等）一律按"未完成"原样返回 `status` 字段。轮询脚本可同时兼容 `done` / `completed` 以防服务端文案差异，但**真正的完成哨兵值是 `done`**。
+
+| 状态 | 含义 | 可执行的操作 |
+|------|------|-------------|
+| 非 `done`（如 `running`） | 仍在处理中 | 禁止部署，必须等待 |
+| `done` | 处理完成（自动返回 answer） | 可以部署 |
+| 失败态 | 处理失败 | 检查错误信息后重试 |
+
+---
+
+## message cancel
+
+取消当前正在进行的消息任务。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--project-id` / `-p` | 是 | 项目 ID |
+
+### 推荐命令模板
+
+```bash
+coze code message cancel --project-id <project-id>
+```
+
+---
+
+## message history
+
+查看项目的对话历史，默认返回最新 10 条对话记录。支持通过游标分页加载更旧或更新的消息。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--project-id` / `-p` | 是 | 项目 ID |
+| `--after <msg_id>` | 否* | 游标，获取该消息之后（更新）的消息。新消息 index 更小 |
+| `--before <msg_id>` | 否* | 游标，获取该消息之前（更旧）的消息。旧消息 index 更大 |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+*\* `--after` 和 `--before` 不能同时使用*
+
+### 推荐命令模板
+
+```bash
+# 查看最新 10 条对话（人类可读格式）
+coze code message history -p <project-id>
+
+# JSON 格式输出（适合 Agent 解析，含游标信息）
+coze code message history -p <project-id> --format json
+
+# 使用 before 游标加载更旧的消息
+coze code message history -p <project-id> --before <msg_id_from_cursor>
+
+# 使用 after 游标加载更新的消息
+coze code message history -p <project-id> --after <msg_id_from_cursor>
+```
+
+### 分页机制
+
+- 不传游标时，默认返回**最新 10 条**记录，方向为 `loadPrev`（向更旧方向翻页）
+- 返回结果中包含游标信息，用于下一页请求：
+  - `after`：当前结果中**最新**消息的 ID，用作 `--after` 可获取更新的消息
+  - `before`：当前结果中**最旧**消息的 ID，用作 `--before` 可获取更旧的消息
+  - `has_more`：是否还有更多消息
+  - `loadDirection`：本次请求的加载方向（`loadNext` / `loadPrev`）
+
+### 输出格式
+
+**text 模式**（默认）：按条目展示问答记录，末尾附带游标信息
+
+```
+--- #1 ---
+Q: 添加暗黑模式支持
+A: 已完成暗黑模式的实现...
+
+--- #2 ---
+Q: 修复登录页面的样式问题
+A: 已修复，调整了 CSS 布局...
+
+[cursor] after=msg_abc, before=msg_xyz, has_more=true, loadDirection=loadPrev
+```
+
+> `#N` 为当前页面的条目序号，不代表全局轮次序号。
+
+**json 模式**：输出结构化对象，包含 `histories` 数组和 `cursor` 游标对象
+
+```json
+{
+  "histories": [
+    { "userMessage": "添加暗黑模式支持", "answer": "已完成暗黑模式的实现..." },
+    { "userMessage": "修复登录页面的样式问题", "answer": "已修复，调整了 CSS 布局..." }
+  ],
+  "cursor": {
+    "after": "msg_abc",
+    "before": "msg_xyz",
+    "has_more": true,
+    "loadDirection": "loadPrev"
+  }
+}
+```
+
+> 仅返回有 AI 回答的记录，按时间正序排列（最早的在前）。如果没有对话历史，text 模式输出 `No conversation history found.`。

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

@@ -0,0 +1,51 @@
+# code model commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+模型管理命令。用于查看可用模型并设置项目**默认会话**使用的模型（会话维度，而非项目级）。
+
+## 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `coze code model list -p <id>` | 列出可用模型，并标记当前激活模型 |
+| `coze code model list --type <type>` | 按项目类型列出可用模型（无项目 ID 时使用） |
+| `coze code model set <modelName> -p <id>` | 设置默认会话使用的模型 |
+
+---
+
+## model list
+
+列出可用模型。
+
+- 传 `-p/--project-id`：从项目读取 `project_type` 与当前模型，结果中 `enable` 标记当前激活模型。
+- 不传 `-p`：必须提供 `--type`，否则报 `E1000`；`--type` 经 `resolveProjectType` 解析（如 `web`、`app`、`agent` 等）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 否 | 项目 ID |
+| `--type <type>` | 否 | 项目类型（无 `-p` 时必填） |
+
+```bash
+coze code model list -p <project-id>
+coze code model list --type web
+```
+
+---
+
+## model set
+
+设置默认会话使用的模型。会先调 `GetModelList` 校验 `modelName` 是否可用，不可用报 `E1000`。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<modelName>` | 是 | 模型名（位置参数） |
+| `-p` / `--project-id` | 是 | 项目 ID |
+
+```bash
+coze code model set doubao-dev-0213 -p <project-id>
+```

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

@@ -0,0 +1,33 @@
+# code preview
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+获取项目的沙盒预览 URL。
+
+## 命令概述
+
+```bash
+coze code preview <project-id>
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | 项目 ID（位置参数） |
+
+### 推荐命令模板
+
+```bash
+coze code preview <project-id>
+```
+
+### 返回值
+
+返回沙盒预览的可访问 URL。
+
+### 注意事项
+
+- 沙盒初始化通常需要 **1-3 分钟**，如果刚创建完项目就调用 preview，可能还未就绪
+- **支持的项目类型**：Web / App 等通用类型。**不支持** `WechatMiniProgram`、`Agent`、`Automation`、`Skill`、`AssistantAgent`——这些类型不会报错，而是返回提示让你前往 Web 控制台查看
+- Preview 不需要项目已部署，只需项目有代码即可

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

@@ -0,0 +1,176 @@
+# code project commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+项目管理相关命令索引。涵盖项目的创建、列表查询、详情获取、删除、导入和数据库表查看。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code project create` | 创建新项目 |
+| 本文档 | `coze code project list` | 列出项目（支持按类型/名称筛选） |
+| 本文档 | `coze code project get <id>` | 查看项目详情 |
+| 本文档 | `coze code project delete <id>` | 删除项目（不可逆） |
+| 本文档 | `coze code project import` | 从远程仓库或本地 zip 导入项目 |
+| 本文档 | `coze code project db list -p <id>` | 列出项目数据库表 |
+
+> 注意：所有命令均需先完成认证和组织/空间上下文配置。别名 `coze code proj` 可替代 `coze code project`。
+
+---
+
+## project create
+
+创建新的 Coze Coding 项目（通过自然语言描述生成项目结构）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--message` | 是 | 项目描述或需求文本（**无 `-m` 短别名**） |
+| `--type` | 是 | 项目类型：`agent` / `workflow` / `app` / `skill` / `web` / `miniprogram` / `assistant`（源码另兼容 `webapp`） |
+| `--wait` | 否 | 等待项目创建完成（含首次 AI 响应） |
+| `--chat-mode` | 否 | 对话模式：`ask` / `agent` / `dangerous_confirm` / `plan` |
+| `--model-name` | 否 | 项目使用的模型名 |
+| `--tool-name` | 否 | 启用的工具名（可多次传入） |
+| `--design` | 否 | 启用设计向导（`--chat-mode plan` 时自动开启） |
+| `--org-id` / `--space-id` | 否 | 组织/空间 ID（缺省读取上下文） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+# 创建 Web 项目（最常用）
+coze code project create --message "创建一个聊天机器人" --type web --format json
+
+# 创建 App 项目
+coze code project create --message "移动端应用" --type app --format json
+
+# 等待创建完成（含首次 AI 响应）
+coze code project create --message "电商网站" --type web --wait --format json
+```
+
+### 返回值
+
+`--format json` 时返回 `{ project_id, type }`。**务必记录 project_id** 供后续 message/deploy/preview 使用。
+
+### 坑点
+
+- **`--type` 仅接受受支持列表内的值**，传入未知类型报 `E1005 Unknown project type`；`web` / `app` 最常用，`assistant` 走模板复制创建。
+- `--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) 的「环境变量覆盖」。
+
+---
+
+## project list
+
+列出当前组织和空间下的项目。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--type` | 否 | 按类型筛选（可多次传入）：`agent` / `workflow` / `webapp` / `app` / `skill` / `web` / `miniprogram` / `assistant`（无效值会被静默忽略） |
+| `--name` | 否 | 按名称搜索 |
+| `--size` | 否 | 返回数量（默认 10） |
+| `--cursor-id` | 否 | 分页游标 |
+| `--has-published` | 否 | 按发布状态筛选 |
+| `--search-scope` | 否 | 创建者范围：0=全部 / 1=我创建 / 2=含协作者 |
+| `--folder-id` | 否 | 按文件夹筛选 |
+| `--order-type` | 否 | 排序方式：0=降序 / 1=升序 |
+| `--order-by` | 否 | 排序字段：0=updated_at / 1=created_at |
+| `--is-fav-filter` | 否 | 仅看收藏 |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+### 推荐命令模板
+
+```bash
+coze code project list --format json
+coze code project list --type web --format json
+coze code project list --name "客服" --format json
+coze code project list --type agent --type workflow --format json
+```
+
+---
+
+## project get
+
+获取单个项目的详细信息。
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | 项目 ID（位置参数） |
+| `--format` | 否 | 输出格式，默认 `text` |
+
+```bash
+coze code project get <project-id> --format json
+```
+
+---
+
+## project delete
+
+删除指定项目。**无 `--confirm` 选项，执行即删除，不可逆。**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `<project-id>` | 是 | 项目 ID（位置参数） |
+
+```bash
+coze code project delete <project-id>
+```
+
+### 注意事项
+
+- **不可逆操作**，执行前确认用户意图。
+- 用户已明确要求删除且目标明确时可直接执行。
+
+---
+
+## project import
+
+从远程 GitHub 仓库或本地 zip 文件导入创建新项目。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-s` / `--source` | 是 | 导入来源：`github` / `local` |
+| `-r` / `--repo` | 条件必填 | 远程仓库全名（如 `user/repo`），`--source github` 时必填 |
+| `-f` / `--file` | 条件必填 | 本地 zip 路径（最大 500MB），`--source local` 时必填 |
+
+### 推荐命令模板
+
+```bash
+# 从 GitHub 导入
+coze code project import -s github -r user/my-app --format json
+
+# 上传本地 zip
+coze code project import -s local -f ./project.zip --format json
+```
+
+### 坑点
+
+- 远程导入需先完成 OAuth 授权（`coze code git auth login`），导入后会自动绑定到源仓库。
+- 本地文件必须是 `.zip` 且不超过 500MB。
+
+---
+
+## project db list
+
+列出项目的数据库表（遍历 `knowledge` 和 `public` 两个 schema）。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `-p` / `--project-id` | 是 | 项目 ID |
+| `--env` | 否 | 环境：`dev`（默认）/ `prod`（仅 `prod` 生效，其它值回退 dev） |
+| `--schema` | 否 | 声明存在但当前实现忽略该参数，始终返回两个 schema 的表 |
+
+```bash
+coze code project db list -p <project-id>
+coze code project db list -p <project-id> --env prod
+```