@coze/cli 0.1.8 → 0.2.0-alpha.9f6611

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

@@ -0,0 +1,284 @@
+# coze-project-files: 群文件操作参考
+
+**这是 coze-project 模块的群文件操作参考。** 触发条件 / 协作流程 / 跨技能衔接见 [`../MODULE.md`](../MODULE.md); 群信息查询 (info / member / message) 见 [`coze-project-query.md`](coze-project-query.md)。本文件讲**群文件 CRUD 的详细语法 + shell 引用细节**。
+
+需要敲 `coze agent file ...` 时 Read 本文件。
+
+## CLI 调用约束 (所有 `coze agent` 命令通用)
+
+**前提**:
+- `coze` 在 PATH (平台保证), 已登录, 不要配 auth
+- 每个命令必带 `--json` (省略 → `E1000 INVALID_ARGUMENT`)
+- 每个命令必带 `--org-id "$account_id" --project-id "$group_id"` (从 `<coze-context>` 抄, 见 [`../MODULE.md`](../MODULE.md))
+
+**输出信封** (stdout 成功):
+```json
+{ "code": 0, "msg": "...", "data": { ... } }
+```
+
+**校验两层才用结果**: shell 退出码 == 0 **且** `.code == 0` (可能 0 退出但软失败)。
+
+`jq` 模板 (注意 stderr 必须捕到文件, 否则失败时错误原因丢失):
+```bash
+err=$(mktemp)
+out=$(coze agent file read --org-id "$account_id" --project-id "$group_id" \
+        --file-path "$path" --json 2>"$err") \
+  || { cat "$err" >&2; rm -f "$err"; exit 1; }
+rm -f "$err"
+[ "$(echo "$out" | jq -r '.code')" = "0" ] \
+  || { echo "API error: $out" >&2; exit 1; }
+echo "$out" | jq '.data'
+```
+
+> ⚠️ **`$(...)` 只捕 stdout**——CLI 错误 JSON 走 stderr, 不重定向 (`2>"$err"`) 的话失败时 `$out` 是空的, 你完全看不到原因。这个 pattern 必须用, 不能省。
+
+**错误码** (JSON 错误写 stderr, 非零退出):
+
+| 代码 | 含义 | 怎么办 |
+|---|---|---|
+| `E1000` | 参数错 (缺 `--json` / 缺 ID / `--size`/`--limit` 非法) | 修命令重试 |
+| `E5002` | 后端 / 服务端错 (`.code != 0`) | 把消息转给用户; **不要盲目重试** |
+
+## 群文件路径语义 (⚠️ 必读)
+
+**所有 `--file-path` 参数都是绝对路径**, **必须 `/` 开头**, 相对的是**群文件目录根** (`/` 即群文件根)。不带 `/` 开头的路径会被后端拒绝。
+
+- 列群文件根: `--file-path /` 或者不传 `--file-path`
+- 根下的文件: `/example.md` (✅) / `example.md` (❌)
+- 子目录: `/notes` (✅) / `notes` (❌)
+- 子目录下的文件: `/notes/example.md` (✅) / `notes/example.md` (❌)
+
+`file list` 返回的 `file_path` 字段也是 `/` 开头的绝对路径——后续 read / write / edit / download **直接拿来用**, 不要自己去掉 `/`。
+
+## 子命令一览
+
+| 子命令 | 用途 |
+|---|---|
+| `agent file list` | 列群文件 / 目录树 |
+| `agent file read` | 读群文件内容 |
+| `agent file write` | 创建 / 整文件覆盖 (从字符串内容) |
+| `agent file edit` | 外科手术式修改 (replace / append) |
+| `agent file upload` | **本地文件** → 群文件 (适合二进制 / 大文件 / 已有本地产物) |
+| `agent file download` | 群文件 → **本地文件** (适合二进制 / 想拿到本地处理) |
+
+下文 `$account_id` / `$group_id` 都指你从 `<coze-context>` 抄来的值。
+
+## `agent file list` — 群文件目录列表
+
+```bash
+# 群文件工作区根目录
+coze agent file list --org-id "$account_id" --project-id "$group_id" --json
+
+# 特定子目录, 递归 10 层
+coze agent file list \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/notes" \
+  --depth 10 --json
+```
+
+参数:
+- `--file-path`: 起始目录 (绝对路径, `/` 开头, e.g. `/notes`; 不带或传 `/` 都是列群文件根)
+- `--depth`: 递归深度 (不带则浅列表, 只列直接子项)
+
+返回 `.data.files`, 每项含:
+- `name`: 文件名 / 目录名
+- `file_path`: 绝对路径 (`/` 开头, 相对群文件根)
+- `is_dir`: `true` 为目录, `false` 为文件
+
+> **路径规范化坑**: 后端有时返回看着被规范化过的路径 (加了额外前缀 / 多了层级 / 跟你输入的形状不同)。**后续读 / 写继续用你最初的用户面向路径**, 不要替换成后端规范化版本——否则后续 read / edit 会找不到文件。
+
+## `agent file read` — 读群文件
+
+```bash
+# 整文件
+coze agent file read \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/example.md" --json
+
+# 仅第 1–20 行
+coze agent file read \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/example.md" \
+  --offset 1 --limit 20 --json
+```
+
+参数:
+- `--file-path`: **必填**, 群文件**绝对路径** (`/` 开头, 相对群文件根)
+- `--offset`: 起始行号 (从 1 开始)
+- `--limit`: 读多少行
+
+返回 `.data`:
+- `.content`: 文件正文 (字符串)
+- `.start_line` / `.end_line`: 实际拿到的行范围
+- `.size`: 文件总大小 (字节)
+
+> 大文件探索时**先读窗口** (`--offset` / `--limit`), 不要一次读整文件——既费 token 又可能撑爆。
+
+## `agent file write` — 创建或整文件覆盖
+
+```bash
+coze agent file write \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/example.md" \
+  --content "# title" --json
+```
+
+参数:
+- `--file-path`: **必填**, 群文件**绝对路径** (`/` 开头, 相对群文件根); 不存在的中间目录后端会**自动创建**
+- `--content`: **必填**, 整文件内容 (字符串, 不是 diff)
+
+⚠️ `file write` **覆盖整个文件**, 没有 merge。**只改一部分用 `file edit`**, 既不会误截断, 又避开 shell 引用长内容的问题。
+
+适用场景:
+- 新建文件 (e.g. 第一次沉淀本周周报)
+- 文件结构整体重写 (确认要全覆盖)
+
+## `agent file edit` — 外科手术式修改
+
+任务是"编辑"或"更新"群文件时, 通常这个比 write 合适。按意图选模式:
+
+| 模式 | 用途 | 必需参数 |
+|---|---|---|
+| `replace_one` | 替换唯一字符串第一次出现。先读文件、有明确锚点的外科手术编辑首选。 | `--old-string`, `--new-string` |
+| `replace_all` | 全局重命名 / 全局替换。 | `--old-string`, `--new-string` |
+| `append` | 文件末尾追加, 无前导换行。 | `--append-content` |
+| `append_newline` | 文件末尾新起一行追加。**"追加新条目"几乎都该选这个**, 不是 `append`。 | `--append-content` |
+
+```bash
+# 全局重命名 config
+coze agent file edit \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/config.md" \
+  --mode replace_all \
+  --old-string "model: gpt-4" --new-string "model: claude-sonnet-4-5" --json
+
+# 追加新 todo 条目
+coze agent file edit \
+  --org-id "$account_id" --project-id "$group_id" \
+  --file-path "/todo.md" \
+  --mode append_newline \
+  --append-content "- review PR #42" --json
+```
+
+**`replace_one` 用法关键点**:
+- **先 `file read` 看一下**, 找出在文件里明显唯一的 `--old-string` 锚点
+- 锚点太短或重复出现, 会改错位置或失败
+- 把锚点选得比要替换的核心多带一两行上下文是常见做法
+
+**`append` vs `append_newline`**:
+- 想在已有最后一行尾巴继续接 → `append`
+- 想起新一行 (新 todo、新章节) → `append_newline` (默认偏好这个)
+
+## `agent file upload` — 本地文件上传到群
+
+把**本地已有文件**塞进群文件 (跟 `file write` 区别: write 是从字符串内容创建; upload 是把本地文件**整个传上去**, 不解析内容)。
+
+```bash
+coze agent file upload \
+  --org-id "$account_id" --project-id "$group_id" \
+  --local-file-path ./report.md \
+  --project-dir /reports \
+  --json
+```
+
+参数:
+- `--local-file-path`: **必填**, 本地文件路径 (相对当前目录或绝对路径; 这是 OS 本地 fs 路径, 跟群文件路径不同)
+- `--project-dir`: **必填**, 目标群目录 (群文件下的哪个子目录; 上传后文件名沿用本地 basename)
+
+**适用场景**:
+- 你刚生成的本地文件 (e.g. `coze generate image` 出图后想存到群) 沉淀到群文件
+- 用户给你本地路径让你把文件放到群里
+- 二进制 / 大文件——`file write` 走 shell `--content` 走不动 (`E2BIG`), upload 直接传文件流
+
+**典型用法**:
+
+```bash
+# 上传报告到群的 /reports/ 子目录
+coze agent file upload \
+  --org-id "$account_id" --project-id "$group_id" \
+  --local-file-path ./Q4-report.pdf --project-dir /reports --json
+
+# 上传截图到群文件根目录
+coze agent file upload \
+  --org-id "$account_id" --project-id "$group_id" \
+  --local-file-path /tmp/screenshot.png --project-dir / --json
+```
+
+## `agent file download` — 从群下载到本地
+
+把**群文件**拉到本地 (跟 `file read` 区别: read 返回 JSON 里的 `.content` 字符串, 适合小文本; download 把文件**整个落到本地 fs**, 适合二进制 / 大文件 / 需要本地工具加工的产物)。
+
+```bash
+coze agent file download \
+  --org-id "$account_id" --project-id "$group_id" \
+  --project-file-path /reports/report.md \
+  --local-dir ./downloads \
+  --json
+```
+
+参数:
+- `--project-file-path`: **必填**, 群文件路径 (要下载哪个文件; **注意 flag 名是 `--project-file-path`, 不是 `--file-path`**)
+- `--local-dir`: **必填**, 本地保存目录 (文件名沿用群文件 basename)
+
+**适用场景**:
+- 用户在群里上传了 PDF / 图片, 你想本地处理 (OCR / 提取 / 转格式)
+- 群里的二进制文件——`file read` 拿不到原始字节, 必须 download
+- 处理完想再传回去——download + 本地处理 + upload 回去
+
+**典型用法**:
+
+```bash
+# 下载群里的 PDF 到本地 ./downloads/
+coze agent file download \
+  --org-id "$account_id" --project-id "$group_id" \
+  --project-file-path /reports/Q4-report.pdf \
+  --local-dir ./downloads --json
+# 文件落到 ./downloads/Q4-report.pdf
+```
+
+**download + 本地处理 + upload 回流**:
+
+```bash
+# 1. 下载
+coze agent file download --org-id "$O" --project-id "$P" \
+  --project-file-path /raw/scan.pdf --local-dir /tmp --json
+
+# 2. 本地处理 (e.g. OCR)
+ocrmypdf /tmp/scan.pdf /tmp/scan-ocr.pdf
+
+# 3. 上传回群
+coze agent file upload --org-id "$O" --project-id "$P" \
+  --local-file-path /tmp/scan-ocr.pdf --project-dir /processed --json
+```
+
+## Shell 引用提示 (主要踩坑点在 file write/edit)
+
+`--content` / `--old-string` / `--new-string` / `--append-content` 都是普通 shell 参数, 引用要小心:
+
+- **纯 ASCII 无引号无 `$`**: 双引号即可 — `--content "hello world"`
+- **含双引号或 shell 元字符 (`$`、` ` `、`!`)**: 单引号整段, 或用 `$'...'` C 风格字面量
+- **多行内容**: heredoc 灌变量最稳:
+  ```bash
+  content=$(cat <<'EOF'
+  line 1
+  line 2 with "quotes" and $vars not expanded
+  EOF
+  )
+  coze agent file write --org-id "$account_id" --project-id "$group_id" \
+    --file-path /a.md --content "$content" --json
+  ```
+  (注意 `<<'EOF'` 加引号——防止变量在 heredoc 里被展开)
+- **超长内容 (几百 KB 起)**: 命令行参数长度可能爆 (`E2BIG`)。先 `file write` 写个骨架, 后续 `file edit append_newline` 增量补
+- **内容里有反引号 / `$(...)`**: 一定走单引号或 heredoc, 否则 shell 会执行命令替换
+
+## 不要做的事 (文件操作层面)
+
+- ❌ 不要省 `--json` 或忽略信封 `.code` 校验 (见顶部"CLI 调用约束")
+- ❌ 不要用 `file write` 做小编辑 — 用 `file edit replace_one`, 既安全又不烦引用
+- ❌ 不要 `replace_one` 不先 `read` — 锚点可能不唯一, 改错位置
+- ❌ 不要 `replace_all` 用模糊锚点 — 全局替换出错就遍布全文
+- ❌ 不要把后端规范化路径替换回去 — 后续调用继续用用户面向路径
+- ❌ 不要把超大内容直接喂 `--content` — `E2BIG`; 先骨架后追加
+- ❌ 不要 `append` 当 `append_newline` 用 — `append` 不加换行, 新条目会粘到上一行尾巴
+- ❌ 不要相信 "`file write` 也能 merge" — 它就是整覆盖, 没有 merge 语义
+- ❌ 不要忽略 heredoc 引号 — `<<EOF` 会展开 `$var`, `<<'EOF'` 才是字面量

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

@@ -0,0 +1,177 @@
+# coze-project-query: 群信息查询参考
+
+**这是 coze-project 模块的群信息查询参考。** 触发条件 / 协作流程 / 跨技能衔接见 [`../MODULE.md`](../MODULE.md); 群文件 CRUD 操作见 [`coze-project-files.md`](coze-project-files.md)。本文件讲**项目元数据 / 群成员 / 群消息历史查询的详细语法**。
+
+需要敲 `coze agent info` / `member` / `message` 时 Read 本文件。
+
+## CLI 调用约束 (所有 `coze agent` 命令通用)
+
+**前提**:
+- `coze` 在 PATH (平台保证), 已登录, 不要配 auth
+- 每个命令必带 `--json` (省略 → `E1000 INVALID_ARGUMENT`)
+- 每个命令必带 `--org-id "$account_id" --project-id "$group_id"` (从 `<coze-context>` 抄, 见 [`../MODULE.md`](../MODULE.md))
+
+**输出信封** (stdout 成功):
+```json
+{ "code": 0, "msg": "...", "data": { ... } }
+```
+
+**校验两层才用结果**: shell 退出码 == 0 **且** `.code == 0` (可能 0 退出但软失败)。
+
+`jq` 模板 (注意 stderr 必须捕到文件, 否则失败时错误原因丢失):
+```bash
+err=$(mktemp)
+out=$(coze agent info --org-id "$account_id" --project-id "$group_id" --json 2>"$err") \
+  || { cat "$err" >&2; rm -f "$err"; exit 1; }
+rm -f "$err"
+[ "$(echo "$out" | jq -r '.code')" = "0" ] \
+  || { echo "API error: $out" >&2; exit 1; }
+echo "$out" | jq '.data'
+```
+
+> ⚠️ **`$(...)` 只捕 stdout**——CLI 错误 JSON 走 stderr, 不重定向 (`2>"$err"`) 的话失败时 `$out` 是空的, 你完全看不到原因。这个 pattern 必须用, 不能省。
+
+**错误码** (JSON 错误写 stderr, 非零退出):
+
+| 代码 | 含义 | 怎么办 |
+|---|---|---|
+| `E1000` | 参数错 (缺 `--json` / 缺 ID / `--size`/`--limit` 非法) | 修命令重试 |
+| `E5002` | 后端 / 服务端错 (`.code != 0`) | 把消息转给用户; **不要盲目重试** |
+
+## 子命令一览
+
+| 子命令 | 用途 | 用户提问示例 |
+|---|---|---|
+| `agent info` | 项目元数据 | "这个项目是啥", "项目设置" |
+| `agent member list` | 群成员 | "谁在群里", "有谁的权限" |
+| `agent message list` | 群聊历史 | "上次说啥", "之前讨论过的结论" |
+
+下文 `$account_id` / `$group_id` 都指你从 `<coze-context>` 抄来的值。
+
+## `agent info` — 项目元数据
+
+```bash
+coze agent info --org-id "$account_id" --project-id "$group_id" --json
+```
+
+返回项目完整记录在 `.data` 下:
+- `name`: 项目 / 群名
+- `description`: 项目描述
+- `owner_id` / `owner_name`: 所有者
+- `created_at` / `updated_at`: 时间戳
+- 其他设置字段
+
+**典型用法**:
+
+```bash
+# 拿项目名
+name=$(coze agent info --org-id "$account_id" --project-id "$group_id" --json \
+       | jq -r '.data.name')
+
+# 整个元数据展示给用户
+coze agent info --org-id "$account_id" --project-id "$group_id" --json | jq '.data'
+```
+
+## `agent member list` — 群成员
+
+```bash
+coze agent member list --org-id "$account_id" --project-id "$group_id" --json
+```
+
+返回成员列表在 `.data` 下, 每项含:
+- `user_id`: 用户 ID
+- `name` / `username`: 名字
+- `role`: 权限角色 (owner / admin / member 等)
+- 加入时间等
+
+**典型用法**:
+
+```bash
+# 列出所有成员名 + 角色
+coze agent member list --org-id "$account_id" --project-id "$group_id" --json \
+  | jq -r '.data[] | "\(.role): \(.name)"'
+
+# 找 owner
+coze agent member list --org-id "$account_id" --project-id "$group_id" --json \
+  | jq -r '.data[] | select(.role == "owner") | .name'
+```
+
+## `agent message list` — 群聊历史
+
+```bash
+# 最近 5 条
+coze agent message list --org-id "$account_id" --project-id "$group_id" --size 5 --json
+
+# 最旧的在前, 包含被引用的消息
+coze agent message list --org-id "$account_id" --project-id "$group_id" \
+  --asc-mode --need-reference --json
+
+# 下一页
+coze agent message list --org-id "$account_id" --project-id "$group_id" \
+  --cursor "$next_cursor" --json
+```
+
+参数:
+- `--size`: 每次最大 **10** (硬上限, 多了 CLI 拒绝)。要拿超过 10 条**必须**用 `--cursor` 翻页
+- `--asc-mode`: 翻为最旧在前 (默认最新在前)
+- `--need-reference`: 内联包含被引用 / 被回复的消息
+- `--conversation-id`: 项目里有多个会话时过滤到单个
+
+返回 `.data` 含消息数组 + 翻页游标, 但**具体字段名 (e.g. `messages` / `items` / `list`, `next_cursor` / `cursor` / `nextToken`) 以 CLI 实际返回为准**——不要凭印象猜。
+
+**翻页累积 pattern** (用户要"最近 30 条"):
+
+```bash
+# === 第一步必做: 探字段名 (不要跳过这步直接用下面的模板) ===
+first=$(coze agent message list --org-id "$account_id" --project-id "$group_id" \
+        --size 1 --json)
+echo "$first" | jq '.data | keys'
+# 看输出, 找出消息数组字段名和游标字段名,
+# 在下面把 <MSG_FIELD> 和 <CURSOR_FIELD> 替换成实际字段名
+
+# === 第二步: 翻页累积 (替换 <MSG_FIELD> / <CURSOR_FIELD> 后再运行) ===
+A="$account_id"; P="$group_id"
+all_msgs="[]"
+cursor=""
+remaining=30
+
+while [ "$remaining" -gt 0 ]; do
+  size=$([ "$remaining" -gt 10 ] && echo 10 || echo "$remaining")
+  if [ -z "$cursor" ]; then
+    page=$(coze agent message list --org-id "$A" --project-id "$P" --size "$size" --json)
+  else
+    page=$(coze agent message list --org-id "$A" --project-id "$P" --size "$size" --cursor "$cursor" --json)
+  fi
+  # 信封校验 (见顶部"CLI 调用约束")
+  [ "$(echo "$page" | jq -r '.code')" = "0" ] || break
+
+  # ↓↓↓ 这两行的 <MSG_FIELD> / <CURSOR_FIELD> 必须替换, 否则 jq 报 syntax error ↓↓↓
+  all_msgs=$(echo "$all_msgs $page" | jq -s '.[0] + .[1].data.<MSG_FIELD>')
+  cursor=$(echo "$page" | jq -r '.data.<CURSOR_FIELD> // ""')
+  [ -z "$cursor" ] || [ "$cursor" = "null" ] && break
+
+  remaining=$((remaining - size))
+done
+
+echo "$all_msgs" | jq '.'
+```
+
+> 占位符 `<MSG_FIELD>` / `<CURSOR_FIELD>` 是**故意**写成非法语法的——jq 会立刻报错, 强迫你先跑第一步探字段名再来填。不要照抄 `data.messages` / `data.next_cursor`, 那只是常见命名, 不一定是这个 CLI 的实际字段。
+
+> ⚠️ **不要假装 10 条上限不存在**。用户要"最近 30 条"就老老实实翻 3 页。直接传 `--size 30` 会被 CLI 拒绝。
+
+**追溯讨论结论的常见姿势** (用户问"上次怎么决定的"):
+
+1. `--asc-mode` 从最旧拉, 保留时间顺序
+2. `--need-reference` 让"A 引用 B 然后说 ..."的上下文不断链
+3. 翻页累积到一个合理深度 (e.g. 30-50 条)
+4. 把关键节点 (决策、结论、行动项) 摘要给用户, 别原样倒出所有消息
+
+## 不要做的事 (查询层面)
+
+- ❌ 不要省 `--json` 或忽略信封 `.code` 校验 (见顶部"CLI 调用约束")
+- ❌ 不要传 `--size > 10` — CLI 直接拒绝, 老实翻页
+- ❌ 不要不带 `--need-reference` 就追溯有引用链的讨论 — 引用断了上下文丢, 误导用户
+- ❌ 不要首次调用就假定游标字段名 — 先看一次 `.data` 实际形状, 字段名以 CLI 实际返回为准
+- ❌ 不要把所有消息原样倒给用户 — 摘要 + 关键节点引用更有用
+- ❌ 不要无差别拉全部消息再筛 — 项目消息量大时浪费 API, 先想清楚需要什么时间范围 / 关键词