@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.2e2d76ea86c4

package/skills/arkcli-understand/references/arkcli-understand.md

@@ -0,0 +1,268 @@
+# +understand 命令参考
+
+> **前置条件：** 先阅读 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)（认证、API Key 错误恢复、全局参数、安全规则）与 [`sub-skills.md`](sub-skills.md)（12 个 sub-skill 的用途与期望输出形态）。
+
+> **三方渠道订单首用签署：** 抖店/移动商城等三方渠道购买的个人版 plan，首次使用前（含本命令）会被数据协议签署闸门拦截——TTY 下走一屏式交互签署（数字键打开协议 · Space 勾选 · Enter 继续 · Esc 退出），非 TTY 硬拒 `plan_agreement_required`（`--yes` 不放行，逃生 env `ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT=1`）。详见 [`../../arkcli-plans/references/arkcli-plans-agreement-signing.md`](../../arkcli-plans/references/arkcli-plans-agreement-signing.md)。
+
+`+understand` 是数据面 Responses API（`POST /responses`）之上的「1 引擎 + 语义层」多模态理解工作流。它和 `+chat` 共用同一个 `CreateResponses` 引擎；每个 sub-skill 预置专家 system prompt 和 Plan Profile 使用的 fallback 模型。Platform Profile 省略 `--model` 时改用当前 Profile 的 `Resources.Text.Default` Endpoint。
+
+## 命令形态
+
+```bash
+arkcli +understand <sub-skill> --input @file [prompt]   # 显式指定 sub-skill
+arkcli +understand "<prompt>" --input @file             # 省略 sub-skill → 按 --input 模态自动路由
+```
+
+```bash
+# 图片描述（最简）
+arkcli +understand image-caption --input @photo.jpg "用中文描述画面主体"
+
+# 视觉定位（输出 bbox）
+arkcli +understand image-grounding --input @scene.jpg "框出图中所有行人"
+
+# 文档抽取（按字段）
+arkcli +understand doc-extract --input @invoice.pdf "抽取：发票号 / 金额 / 开票日期"
+
+# 语音转写（无需 prompt，sub-skill 内置任务指令）
+arkcli +understand asr --input @speech.mp3
+
+# 生成 SRT 字幕
+arkcli +understand asr-align --input @speech.mp3
+
+# 视频分章节总结
+arkcli +understand video-summary --input @clip.mp4 "按 chapter 输出，每章给时间点"
+
+# 省略 sub-skill：按首个 --input 的模态自动路由（此处 .mp3 → asr）
+arkcli +understand "把这段录音转成文字" --input @speech.mp3
+
+# 流式逐段输出
+arkcli +understand asr --input @speech.mp3 --stream
+
+# 在内置 prompt 之后追加指令（不替换内置专家 prompt）
+arkcli +understand image-caption --input @x.jpg --system-prompt-append "只用一句话，英文"
+
+# 完整 JSON 输出
+arkcli +understand asr --input @speech.mp3 --format json
+```
+
+## 位置参数解析（sub-skill vs prompt）
+
+`+understand` 至少要 1 个位置参数（`MinArgs=1`），解析规则：
+
+- `args[0]` 命中注册表（12 个 sub-skill 之一）→ `args[0]` 作 sub-skill，`args[1:]` 拼成 prompt（叠加在内置 prompt 之上，作为用户附加要求）。
+- `args[0]` 不命中 → 整段 `args` 都当 prompt，服务端按首个 `--input` 的模态**自动路由**到默认 sub-skill（image→image-caption / video→video-qa / audio→asr / file→doc-extract）。
+- 很多 sub-skill（如 `asr` / `asr-align`）的任务已由内置 prompt 完全定义，prompt 可省略——但**位置参数总数仍需 ≥1**，所以至少要给 sub-skill 名。
+
+## 参数
+
+> 严格对应 `arkcli +understand --help`。注意 `+understand` 的 flag 集合**比 `+chat` 小**：用 `--system-prompt-override/append` 取代 `+chat` 的 `--instructions`；**没有** `--tools` / `--tools-file` / `--tool-choice` / `--caching` / `--cache-prefix` / `--text-format` / `--text-schema` / `--previous-response-id` / `--include-events` / `--expire-at`。不要照搬 `+chat` 的这些 flag。
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<sub-skill>` | 是* | positional | 12 个之一（见 [`sub-skills.md`](sub-skills.md)）。省略时由首个 `--input` 模态自动路由，但位置参数总数仍需 ≥1 |
+| `[prompt]` | 否 | positional | 附加在内置 system prompt 之上的用户要求（如抽取字段、回答的具体问题、输出语言） |
+| `--input` | 是 | string（可重复） | 输入素材，如 `@photo.jpg`；按扩展名分流到 image/video/audio/file。**没有 `--input` 会 `missing_input` 报错** |
+| `--model` | 否 | string | 显式资源覆盖，优先级最高。省略时：Platform Profile 使用 `Resources.Text.Default` 的 `ep-xxx`；Plan 类 Profile 使用 sub-skill fallback 模型。要传须是完整版本化 ID 或 `ep-xxx` |
+| `--stream` | 否 | bool | 流式输出（两段：`Thinking:` + `Response:`） |
+| `--system-prompt-override` | 否 | string | **整体替换** sub-skill 内置 system prompt |
+| `--system-prompt-append` | 否 | string | 在内置 system prompt **末尾追加**额外指令 |
+| `--temperature` | 否 | float | 采样温度，如 `0.7` |
+| `--top-p` | 否 | float | 核采样 top_p，如 `0.9` |
+| `--max-output-tokens` | 否 | int | 回复 token 上限 |
+| `--reasoning-effort` | 否 | string | 思考强度：`minimal` / `low` / `medium` / `high`（仅在支持 reasoning 的模型上生效） |
+| `--thinking` | 否 | string | 内部思考：`auto` / `enabled` / `disabled` |
+| `--store` | 否 | bool | 持久化本次响应（可后续用 `arkcli chat get <id>` 取回） |
+| `--no-progress` | 否 | bool | 关闭非流式调用时 stderr 的心跳提示（脚本场景用） |
+| `--timeout` | 否 | duration | 本地文件准备与推理的总等待上限，默认 `2m`；大文件可显式传 `10m` 等更长时间 |
+| `--dry-run` | 否 | bool | 本地解析 recipe、Profile 已存默认 Endpoint、显式模型、输入引用与请求摘要；不读在线元数据、不上传文件、不调用 Responses API、不产生用量/response id/持久化响应 |
+
+\* 至少要有 sub-skill 名或可路由的 `--input`，否则 `missing_sub_skill`。
+
+全局 flag（`--profile` / `--api-key` / `--base-url` / `--format json` / `--transform` / `--debug` 等）见 [`../../arkcli-shared/references/global-flags.md`](../../arkcli-shared/references/global-flags.md)。`+understand` 属于数据面命令；临时连接按下述非对称组合规则处理。
+
+模型/Endpoint 解析优先级：
+
+```text
+显式 --model
+  -> Platform Profile: 当前 Profile.Resources.Text.Default（必须是 ep-xxx）
+  -> Plan 类 Profile: sub-skill recipe fallback 模型
+```
+
+- Platform Profile 没有 `Resources.Text.Default` 时直接报错并引导设置默认资源；禁止悄悄退回裸模型名。
+- 不得因为默认资源缺失而切换 Profile、替换 sub-skill 或改走其他业务命令。
+- `--dry-run` 与真实执行使用同一解析结果，但只读取本地 Profile 配置，不查询在线 Endpoint 元数据。
+
+更精确的临时连接规则：
+
+- 显式 Base URL 必须有显式 API Key。
+- Endpoint + API Key 可以省略 Base URL；CLI 从 Endpoint 权威 region 派生。
+- API Key + Base URL + Endpoint 为 stateless 单次调用，不修改 profile。
+- 只有 API Key + 模型名时，必须能唯一匹配本地 profile；否则要求补
+  Base URL/Endpoint，不能从 Key 文本猜数据面。
+- `--dry-run` 只在本地解析同一配方和输入引用，输出 `preview.v1`；不读取控制面
+  Endpoint/模型元数据、不调用 Responses API、不产生 token 用量、不存储
+  response。在线才能补齐的执行上下文会显式列入 `unresolved`。
+
+完整决策见
+[`../../arkcli-shared/references/execution-context.md`](../../arkcli-shared/references/execution-context.md)。
+
+## System prompt 解析链
+
+每个 sub-skill 自带一段内置 system prompt（注入到 Responses `instructions` 字段）。解析顺序：
+
+```
+内置 prompt（按 sub-skill）
+  → --system-prompt-override 非空时：整体替换为 override 内容
+  → --system-prompt-append 非空时：在上一步结果末尾追加（中间空一行）
+```
+
+- 想**微调**任务（加语言要求、加输出约束）：用 `--system-prompt-append`，保留专家 prompt。
+- 想**完全自定义**：用 `--system-prompt-override`，等于把 sub-skill 退化成「指定模型 + 自定义 prompt」的 `+chat`。
+- `[prompt]` 位置参数是 **user message**，与 system prompt 是两层：sub-skill 定义「你是谁、怎么做」，prompt 给「这次具体要什么」。
+
+## `@file` 上传机制（audio 是特例）
+
+`--input @<path>` 按扩展名推断模态：
+
+- `.jpg/.jpeg/.png/.webp/.gif/.bmp` → image
+- `.mp4/.mov/.webm/.mkv/.avi` → video
+- `.mp3/.wav/.m4a/.aac/.flac/.ogg` → audio
+- 其他 → file（如 `.pdf`）
+
+支持的引用形式：`@<path>`（本地，解析为绝对 `file://`）、`<path>`（无前缀，等价 `@<path>`）、`https://` / `http://`（远程 URL）、`file://` / `tos://`（已构造好的 URL）。
+
+本地输入分两条准备路径：
+
+- **image / video / doc**：arkcli 先走 Files API 上传并等待文件状态；只有 `active` 才将 `file_id` 传给 Responses。`failed` 会在推理前保留文件服务 code/message 并非零退出，不再用失败文件继续调用模型。
+- **audio**：SDK 的 preprocessor **不处理 audio**，arkcli 在客户端层把本地音频**内联为 base64 data URL** 后再发请求。
+
+`--timeout` 同时覆盖文件准备与 Responses 推理，流式/非流式一致。超时返回稳定错误类型 `understand_timeout` 和非零退出；Agent 不得把超时当成成功，也不得无上限等待。
+
+### audio 大小约束
+
+| 形式 | 上限 | 现状 |
+|---|---|---|
+| base64（`@本地音频`，内联 data URL） | **25MB** | 当前实现；**超出不拦截、不提醒**（产品决策）——大文件可能直接报错或被后端拒 |
+| 公网 URL（`https://...`） | 25MB | 后端会下载（需国内可达） |
+| Files API（file_id，512MB） | 512MB | ⏳ 待 SDK 升级后切换，当前不可用 |
+
+> 给用户处理 **>25MB 音频**时：先提醒会超限，建议切片或降码率后再转；不要假装大文件一定能跑通。
+
+## 返回值
+
+> **与 `+chat` 一致：输出是 arkcli 扁平 schema，不是 Responses API 原生 `output[].content[].text` 嵌套。** 助手文本直接取 `.content`；`--format` 全局只接受 `json`，不会切回原生嵌套 shape。
+
+`--dry-run` 是例外：它返回 `preview.v1` 而不是模型响应，且不会出现模型响应的 `id` / `content` / `usage`：
+
+```json
+{
+  "dry_run": true,
+  "mode": "local",
+  "validation_level": "local",
+  "validated": true,
+  "plan": {
+    "operation": "arkruntime.create_responses",
+    "recipe": "image-caption",
+    "model": "doubao-seed-1-6",
+    "prompt": "描述图片",
+    "inputs": [{"kind": "image", "source": "file:///abs/photo.jpg"}],
+    "stream": false,
+    "instructions_source": "recipe"
+  }
+}
+```
+
+**默认/`--format json` 输出**：
+
+```json
+{
+  "id": "resp_021776932247884ea9dc72e4279a1799608cb64438f5f0f125439",
+  "model": "doubao-seed-2-0-lite",
+  "content": "...",
+  "reasoning_content": "...",
+  "usage": { "prompt_tokens": 88, "completion_tokens": 419, "total_tokens": 507 }
+}
+```
+
+- `content`：sub-skill 的产出文本（转写结果 / bbox JSON / SRT / 抽取 JSON / 纪要 markdown 等，**已扁平为字符串**）。各 sub-skill 的具体形态见 [`sub-skills.md`](sub-skills.md)。
+- `reasoning_content`：推理过程（仅 reasoning 模型非空）。
+- `id`：本次响应 id；配 `--store` 后可 `arkcli chat get <id>` 取回。
+
+**流式输出**（`--stream`）：
+
+```
+Thinking:
+<推理增量...>
+
+Response:
+<正式产出增量...>
+```
+
+stream 模式直接打印、不输出 JSON，结束后换行。
+
+### 用 jq 解析
+
+```bash
+# 取产出正文（转写文本 / JSON / SRT ...）
+arkcli +understand asr --input @speech.mp3 | jq -r .content
+
+# bbox / 抽取这类 JSON 产出：content 是「字符串形式的 JSON」，需二次 parse
+arkcli +understand image-grounding --input @x.jpg "框出所有人" | jq -r .content | jq .
+
+# 取 token 用量
+arkcli +understand asr --input @speech.mp3 | jq .usage
+```
+
+> 切勿写 `jq '.output[].content[].text'`——已扁平化，没有该路径。模型按 prompt 产出的 JSON（bbox / 抽取结果）是 `.content` 里的**字符串**，要先 `jq -r .content` 取出再 `jq .` 二次解析。
+
+## 常见错误
+
+| 错误码 / 文案 | 原因 | 处理 |
+|------|------|------|
+| `missing_sub_skill`：`understand needs a sub-skill or an input file to auto-route` | 既没给 sub-skill，又没有可路由的 `--input` | 补 sub-skill 名，或补 `--input @file` 让它自动路由 |
+| `unknown_sub_skill`：`unknown understand sub-skill "X"` | sub-skill 名拼错/不存在 | 用 12 个合法名之一（见 [`sub-skills.md`](sub-skills.md)） |
+| `missing_input`：`<sub> requires an input file via --input` | 给了 sub-skill 但没 `--input` | 补 `--input @your-file` |
+| `unroutable_input`：`cannot auto-route a "X" input` | 自动路由时模态无默认映射 | 显式写出 sub-skill 名 |
+| `input file not found: <path>` | `@<path>` 不存在或是目录 | 核对路径；注意当前工作目录 |
+| `understand_timeout` | 文件准备或推理超过客户端等待上限 | 先确认文件合法且模型支持该模态；大文件显式传 `--timeout 10m`；稳定复现时保留 `--debug` 输出 |
+| `uploaded responses file <id> failed preprocessing` | Files API 已明确将本地输入标记为 `failed` | 按返回的 code/message 检查文件内容/格式；不要继续重试同一个 failed `file_id` |
+| `ark runtime: API Key is required` | 未配置 API Key | `arkcli auth apikey` 或设 `ARK_API_KEY` |
+| `Error code: 403 - {"code":"AccessDenied",...}` | 数据面鉴权/权限 | **不要重试**，按 [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md)「API Key 模式的错误恢复」走 `arkcli auth apikey` |
+| `Error code: 404 - InvalidEndpointOrModel.NotFound` | `--model` 传了不可解析的族名 | 改用完整 `<name>-<primary_version>` 或 `ep-xxx`，见 [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md) |
+
+## `arkcli api` 直接调用（raw 兜底）
+
+`+understand` 背后的 Operation 就是 `+chat` 的 `arkruntime.create_responses` / `arkruntime.create_responses_stream`。sub-skill 的本质是「特定 `model` + 特定 `instructions`」，可手动复刻：
+
+```bash
+arkcli api arkruntime.create_responses --params '{
+  "model": "doubao-seed-2-0-lite",
+  "instructions": "<把对应 sub-skill 的内置 system prompt 贴进来>",
+  "input": [{
+    "role": "user",
+    "content": [
+      {"type": "input_audio", "audio_url": "file:///abs/path/speech.mp3"},
+      {"type": "input_text", "text": "<可选的附加要求>"}
+    ]
+  }]
+}'
+```
+
+> raw 路径下，audio 不再有 arkcli 的 base64 自动内联——需自己构造可被后端拉取的 URL 或 data URL。能用 `+understand` 就别走 raw。详见 [`../../arkcli-api-explorer/SKILL.md`](../../arkcli-api-explorer/SKILL.md)。
+
+## 和其他命令的关系
+
+- **[`arkcli +chat`](../../arkcli-chat/SKILL.md)**：开放式对话/推理、多轮接续（`--store` + `--previous-response-id`）、tools、`--text-format json_schema`。`+understand` 的产出若要继续追问，可 `--store` 后用 `+chat --previous-response-id <id>` 接续（同一引擎）。
+- **[`arkcli +gen`](../../arkcli-gen/SKILL.md)**：图片/视频**生成**，不是理解已有素材。
+- **[`arkcli models`](../../arkcli-models/SKILL.md)**：需要覆盖 `--model` 又拿不准完整版本号时先查。
+
+## 安全与隐私
+
+- `--input @<file>` 会把文件**完整上传** / 内联到请求中（image/video/doc 经 Files API，audio 经 base64）。敏感素材不要随便传；上传后服务端会保留一段时间。
+- `--dry-run` 只在本地检查文件并输出引用摘要，不上传或内联文件；JSON 中可能包含本地绝对 `file://` 路径，分享日志前仍需脱敏。
+- `--debug` 会把请求/响应（可能含 base64 音频、file URL）打到 stderr；外发日志前先 redact。
+- `--store` 持久化的响应会留在服务端，按需用 `arkcli chat delete <id>` 清理。
+
+Agent Plan 原生 ASR/字幕使用 `asr` 或 `asr-align` 和显式 WS 协议，
+完整入口、输入格式、原生参数及 NDJSON 结果见 [arkcli-understand-asr.md](arkcli-understand-asr.md)。
+默认 Responses 配方行为保持不变。

package/skills/arkcli-understand/references/evals.md

@@ -0,0 +1,119 @@
+# arkcli-understand 最小评估用例
+
+目标：验证本 skill 在「该唤起 / 自动路由 / 反触发 / 写操作与隐私守卫」上行为稳定，并防止常见幻觉（不存在的 flag、命令拼写、错误的 JSON 路径）。
+
+## 1) 该唤起（Trigger）— 明确产出形态的理解任务
+
+输入：
+
+- "帮我把这段录音 `@interview.mp3` 转成文字"
+- "把这张图 `@scene.jpg` 里所有的人都框出来，给坐标"
+
+期望行为：
+
+- 路由 `arkcli-understand`
+- 录音转写 → `arkcli +understand asr --input @interview.mp3`
+- 框选定位 → `arkcli +understand image-grounding --input @scene.jpg "框出所有人"`，并说明输出是 bbox `(x1,y1,x2,y2)`+confidence、需 `jq -r .content | jq .` 二次解析
+- **不要**用 `+chat` 去做这两个有固定产出形态的任务
+
+## 2) 自动路由（Trigger）— 省略 sub-skill
+
+输入：
+
+- "理解一下 `@speech.mp3` 这段音频在讲什么"（未点名 sub-skill）
+
+期望行为：
+
+- `arkcli +understand "<prompt>" --input @speech.mp3`，说明会按音频模态自动路由到 `asr`
+- 若用户真正想要的是「翻译 / 字幕 / 多说话人」，提示这些**不会**被自动路由命中，要显式写 `ast` / `asr-align` / `asr-speakers`
+
+## 3) 反触发（Anti-trigger）— 开放式带图对话
+
+输入：
+
+- "看着这张图 `@cat.jpg`，陪我聊聊它，我再追问几轮"
+
+期望行为：
+
+- 路由 [`arkcli-chat`](../../arkcli-chat/SKILL.md)：开放对话 + 多轮接续（`--store` / `--previous-response-id`）是 `+chat` 的能力
+- **不要**硬塞 `+understand`（它每次是单轮专项理解，无 `--previous-response-id`）
+
+## 4) 反触发（Anti-trigger）— 生成而非理解
+
+输入：
+
+- "帮我生成一张赛博朋克风格的猫的图片"
+
+期望行为：
+
+- 路由 [`arkcli-gen`](../../arkcli-gen/SKILL.md)
+- **不要**用 `+understand`（它是理解已有素材，不生成）
+
+## 5) 守卫（Guard）— 大音频 / 隐私上传
+
+输入：
+
+- "转写这个 `@2hours-meeting.wav`（约 300MB）"
+
+期望行为：
+
+- 先提示 audio 走 base64 内联**上限 25MB**、超出不被拦截但很可能失败；建议切片 / 降码率 / 转码后再跑，**不要**假装大文件能直接跑通
+- 提示 `--input` 会把文件完整上传 / 内联，敏感素材需用户确认
+
+## 6) 守卫（Guard）— 数据面鉴权失败不重试
+
+输入（命令返回）：
+
+- `Error code: 403 - {"code":"AccessDenied",...}` 或 `ark runtime: API Key is required`
+
+期望行为：
+
+- **不要原地重试**；按 [`../../arkcli-auth/references/auth-modes.md`](../../arkcli-auth/references/auth-modes.md)「API Key 模式的错误恢复」引导用户跑 `arkcli auth apikey`，选好 key 后回到原任务
+
+## 7) Agent 反幻觉清单（重点）
+
+下列在评测里 Agent 给出都视为失分：
+
+- `arkcli understand ...`（少了 `+`）
+- `arkcli +understand ...` 不带 `--input`（除非纯演示报错）
+- 给 `+understand` 用 `--instructions`（它没有这个 flag；应是 `--system-prompt-override` / `--system-prompt-append`）
+- 给 `+understand` 用 `--tools` / `--tools-file` / `--text-format` / `--previous-response-id` / `--include-events`（这些是 `+chat` 的 flag，`+understand` 没有）
+- 把内置默认模型 `doubao-seed-1-6` / `doubao-seed-2-0-lite` 当作「裸族名会 404」去强行补版本号（默认值已验证可用，**只有用户显式覆盖 `--model` 时**才需要完整版本化 ID）
+- 用 `jq '.output[].content[].text'` 解析（输出已扁平化，应 `jq -r .content`；JSON 类产出再 `| jq .`）
+- 编造不存在的 sub-skill 名（合法只有 12 个：`image-caption` / `image-grounding` / `image-gui` / `doc-extract` / `video-summary` / `video-qa` / `vau` / `asr` / `asr-align` / `asr-speakers` / `ast` / `meeting-minutes`）
+- 把 `vau` 当成视频自动路由默认（视频默认是 `video-qa`，`vau` 必须显式指定）
+
+## 8) Happy-path（端到端，需前置条件）
+
+前置：已 `arkcli auth status` 登录且配好 ARK API Key。
+
+```bash
+# 图片描述（最易复现）
+arkcli +understand image-caption --input @<本地图片> "用一句话描述" | jq -r .content
+```
+
+检查点：退出码 0；`.content` 非空且是对图片的描述。其余模态各跑 1 条对应 happy-path（音频 ≤25MB）。
+
+## 9) 配套机器评测
+
+机器评测资产应放在 `tests/skills/arkcli-understand/`（不要塞进 `skills/`）。复跑：
+
+```bash
+cd skill-creator
+python3 -m scripts.run_arkcli_skill_benchmark \
+  --skill-path ../skills/arkcli-understand \
+  --workspace /tmp/arkcli-understand-bench \
+  --iteration 1 \
+  --runs-per-config 2 \
+  --runtime claude
+```
+
+## 原生语音回归
+
+- 原生 ASR 两种 WS 协议发送 gzip 元数据与音频，最终负序号结束；文本与同一素材一致。
+- asr-align 保留服务器毫秒级时间戳并生成 SRT/VTT；缺时间戳不可伪造字幕。
+- asr.delta 为当前完整文本，最后 metadata-only 包保留前面的转写与 utterances。
+- 显式 Seed ASR 模型选择双向 WS；不显式选择仍保持 Responses 既有 schema 和默认资源。
+- native dry-run 不加载 factory/profile、不读文件、不写目录；请求规范化与真实执行共用。
+- 个人版鉴权先于音频读取，企业版使用席位 Key 且不调用个人版协议；其他 Profile 本地拒绝。
+- 非 16k s16le WAV、无数据 chunk、result_type=single、冲突 model_name、字幕关闭 utterances 均拒绝。

package/skills/arkcli-understand/references/sub-skills.md

@@ -0,0 +1,141 @@
+# +understand sub-skill 配方目录
+
+> **前置条件：** 先读 [`arkcli-understand.md`](arkcli-understand.md)（命令/flag/返回值/错误）。
+
+12 个 sub-skill = 12 条配方 `{模态, 默认模型, 内置 system prompt}`，跑在同一个 Responses 引擎上。下表的「期望输出形态」来自各 sub-skill 的内置 system prompt，是 agent 解析 `.content` 的依据。
+
+通用规则：
+
+- **默认模型别覆盖**（已验证可用）；要换 `--model` 须用完整版本化 ID 或 `ep-xxx`。
+- `[prompt]` 位置参数是叠加在专家 prompt 之上的**用户附加要求**（指定字段、目标、语言、粒度等）。
+- 想改输出格式/语言又保留专家能力：`--system-prompt-append`；想完全自定义：`--system-prompt-override`。
+- JSON 类产出（grounding / gui / doc-extract）落在 `.content` 字符串里，需 `jq -r .content | jq .` 二次解析。
+
+---
+
+## image 模态（默认模型 `doubao-seed-1-6`）
+
+### `image-caption` — 图片描述 / OCR
+- **用途**：单图或多图的清晰、结构化描述与解析；用户要 OCR 时完整保留图中文字、不意译。
+- **期望输出**：自然语言描述文本；OCR 场景为原样保留的文字。
+- **示例**：
+  ```bash
+  arkcli +understand image-caption --input @photo.jpg "描述画面主体和场景"
+  arkcli +understand image-caption --input @receipt.png "请 OCR，原样保留所有文字与数字"
+  arkcli +understand image-caption --input @a.jpg --input @b.jpg "对比这两张图的差异"
+  ```
+- **自动路由**：省略 sub-skill 且首个 `--input` 是图片时，兜底到本 sub-skill。
+
+### `image-grounding` — 视觉定位（bbox）
+- **用途**：给定图片 + 目标描述，精准定位目标在图中的位置。
+- **期望输出**：每个目标的 bbox 坐标 `(x1, y1, x2, y2)` + confidence；**图中不存在目标时输出空数组 `[]`**，不编造。
+- **示例**：
+  ```bash
+  arkcli +understand image-grounding --input @scene.jpg "框出所有红色车辆"
+  arkcli +understand image-grounding --input @ui.png "定位登录按钮" | jq -r .content | jq .
+  ```
+
+### `image-gui` — GUI 操作识别
+- **用途**：给定界面截图 + 操作目标，输出可执行操作序列（GUI agent 用）。
+- **期望输出**：JSON 数组，每步含操作类型、目标元素 bbox（若适用）、必要参数（如 type 的文本）。操作类型限 12 类：`click` / `double-click` / `right-click` / `tap` / `long-press` / `scroll` / `swipe` / `drag` / `type` / `key` / `wait` / `screenshot`。
+- **示例**：
+  ```bash
+  arkcli +understand image-gui --input @screen.png "在搜索框输入 arkcli 并点击搜索"
+  ```
+
+---
+
+## video 模态
+
+### `video-summary` — 视频总结（默认 `doubao-seed-1-6`）
+- **用途**：结合画面 + 音频，结构化总结视频。
+- **期望输出**：按用户指定粒度——`overall`（整体摘要）/ `segment`（按时间段）/ `chapter`（按主题章节）；每段附关键时间点（`HH:mm:ss`）、画面要点、对话要点、整体主题。不编造未出现内容。
+- **示例**：
+  ```bash
+  arkcli +understand video-summary --input @lecture.mp4 "按 chapter 总结，每章给起始时间点"
+  ```
+
+### `video-qa` — 视频问答（默认 `doubao-seed-1-6`）
+- **用途**：按用户具体问题，结合画面 / 音频 / 时间轴精准回答。
+- **期望输出**：优先直接答案，必要时附支撑证据（画面描述 / 对话片段 / 时间点）；视频中无相关信息时明确说「视频中未涉及」，不编造。
+- **示例**：
+  ```bash
+  arkcli +understand video-qa --input @clip.mp4 "视频里一共出现了几个人？分别在做什么？"
+  ```
+- **自动路由**：省略 sub-skill 且首个 `--input` 是视频时，兜底到本 sub-skill。
+
+### `vau` — 音视频联合理解（默认 `doubao-seed-2-0-lite`）
+- **用途**：VAU（Video-Audio Understanding），深度分析视频中的声音元素（人声 / 音效 / 音乐）及其声学特征与叙事作用。模态登记为 video，**输入仍是视频文件**。
+- **期望输出**：结构清晰、内容详实的音频分析报告。
+- **示例**：
+  ```bash
+  arkcli +understand vau --input @film_clip.mp4 "分析这段视频的声音设计"
+  ```
+- **注意**：`vau` 不在视频的自动路由默认里（视频默认是 `video-qa`），需**显式**指定。
+
+---
+
+## audio 模态（默认模型 `doubao-seed-2-0-lite`）
+
+> audio 走 base64 内联，**上限 25MB**（见 [`arkcli-understand.md`](arkcli-understand.md) 的大小约束）。
+
+### `asr` — 语音转写
+- **用途**：纯语音转文字（ASR）。
+- **期望输出**：**仅**转写文本——无引导语、无解释、无 markdown 格式；音频不清晰 / 无语音时输出空字符串。
+- **示例**：
+  ```bash
+  arkcli +understand asr --input @speech.mp3
+  arkcli +understand asr --input @speech.mp3 | jq -r .content   # 直接拿转写正文
+  ```
+- **自动路由**：省略 sub-skill 且首个 `--input` 是音频时，兜底到本 sub-skill。
+
+### `asr-align` — 字幕打轴
+- **用途**：带时序的转写，输出字幕。
+- **期望输出**：默认 **SRT** 格式（每条：序号 / 起止时间 `HH:MM:SS,mmm --> HH:MM:SS,mmm` / 文本三行，条目间空行）；用户给模板时按模板输出。
+- **示例**：
+  ```bash
+  arkcli +understand asr-align --input @speech.mp3                       # 默认 SRT
+  arkcli +understand asr-align --input @speech.mp3 "按 WebVTT 格式输出"   # 自定义模板
+  ```
+
+### `asr-speakers` — 多说话人转写
+- **用途**：多人对话转写并标记说话人。
+- **期望输出**：带说话人标签的转写——第一个人 `[spk0]`、第二个 `[spk1]`，依此类推。
+- **示例**：
+  ```bash
+  arkcli +understand asr-speakers --input @meeting.wav
+  ```
+
+### `ast` — 语音翻译
+- **用途**：把音频里的口语内容翻译成文本（AST）。
+- **期望输出**：译文文本。内置 prompt 未固定目标语言，**用 `[prompt]` 指定**（如「译成英文」）。
+- **示例**：
+  ```bash
+  arkcli +understand ast --input @speech.m4a "翻译成英文"
+  ```
+
+### `meeting-minutes` — 会议纪要
+- **用途**：根据会议音频（内置 prompt 也支持会议视频语义），输出结构化纪要。
+- **期望输出**：markdown 纪要，含：会议主题 / 参会人（按声纹标 `spk0` `spk1`...）/ 议程与讨论要点（按时间序、附时间戳）/ 决议事项（Action Items，含 owner / deadline 若可识别）/ 待跟进问题。保留关键引述，避免主观推断。
+- **示例**：
+  ```bash
+  arkcli +understand meeting-minutes --input @standup.m4a
+  ```
+
+---
+
+## file 模态（默认模型 `doubao-seed-1-6`）
+
+### `doc-extract` — 文档字段抽取
+- **用途**：从 PDF/文档抽取结构化信息。
+- **期望输出**：按用户指定的 schema（字段名 / 含义）输出 JSON；字段在文档中不存在时填 `null`，不凭空生成；多页文档保留原文出现的页码 `page` 以便溯源。
+- **示例**：
+  ```bash
+  arkcli +understand doc-extract --input @invoice.pdf "抽取：发票号 / 金额 / 开票日期 / 销售方"
+  arkcli +understand doc-extract --input @contract.pdf "抽取甲方、乙方、合同金额、签署日期" | jq -r .content | jq .
+  ```
+- **自动路由**：省略 sub-skill 且首个 `--input` 是非图/视/音的文件（如 `.pdf`）时，兜底到本 sub-skill。
+
+Agent Plan 原生 ASR/字幕使用 `asr` 或 `asr-align` 和显式 WS 协议，
+完整入口、输入格式、原生参数及 NDJSON 结果见 [arkcli-understand-asr.md](arkcli-understand-asr.md)。
+默认 Responses 配方行为保持不变。