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

package/skills/arkcli-train-finetune/references/list.md

@@ -0,0 +1,78 @@
+# 查询精调任务列表
+
+本 reference 只处理多任务列表和筛选。用户指定了一个 job id 时改读 [`manage.md`](manage.md)。
+
+## 命令与常用过滤
+
+```bash
+arkcli train finetune list [flags]
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--name` | 按任务名模糊过滤 |
+| `--phase` | 按阶段过滤，可重复 |
+| `--customization-type` | 按后端训练类型过滤，可重复；不确定枚举时查 `--help` |
+| `--create-time-after`、`--create-time-before` | 按创建时间过滤，使用 RFC3339 |
+| `--mine` | 只查当前 SSO 子用户创建的任务；服务端按 `TagFilters=[{Key:"sys:ark:createdBy", Values:["IAMUser/<uid>/<name>"]}]` 过滤 |
+| `--page-size`、`--page-number` | 手动分页；页码默认 1 且必须 `>=1`，每页默认 100 且必须在 `1-100` |
+| `--page-all`、`--page-limit` | 自动分页；必须设置合理上限 |
+| `--sort-by`、`--sort-order` | 排序 |
+| `--transform` | 提取单字段；复杂投影用 JSON 工具处理 |
+
+## 流程
+
+1. 查看当前版本参数：
+
+```bash
+arkcli train finetune list --help
+```
+
+2. 根据用户条件组合过滤：
+
+- 名称
+- 任务阶段
+- 训练方法
+- 创建时间范围
+- 创建人：用户说“我的 / 我创建的 / 本人提交的”时必须加 `--mine`；不要先拉全账号再本地猜创建人
+- 分页和排序
+
+3. 用户要求“全部”时使用当前 CLI 支持的自动分页参数，并设置合理页数上限。不要无界抓取。
+
+手动分页请求第 2 页及以后时，CLI 会先获取符合当前过滤条件的 `total_count`；请求页的起始位置超过总数会直接返回参数校验错误，最后一个不满整页的页码仍然合法。
+
+4. 输出精简表格或摘要，优先包含：
+
+- job id
+- 名称
+- 训练方法
+- 当前阶段
+- 创建时间或更新时间
+
+不要为列表中的每个任务自动调用 `get`。只有用户要求详情，或列表字段不足以回答问题时，才查询对应 job。
+
+## 命令骨架
+
+```bash
+arkcli train finetune list
+arkcli train finetune list --name <keyword>
+arkcli train finetune list --phase <phase>
+arkcli train finetune list --mine --page-all --page-size 100
+arkcli train finetune list \
+  --create-time-after <RFC3339> \
+  --create-time-before <RFC3339>
+```
+
+阶段和训练方法枚举必须从当前 `--help` 获取，不要使用静态清单。
+
+`--mine` 依赖 SSO 子用户身份和 `sys:ark:createdBy` 资源标签。
+不要伪造空 tag 或退化成全账号结果冒充“我创建的”。
+
+## 时间处理
+
+- 用户使用“今天、昨天、最近一周”等相对时间时，按当前 profile/用户时区换算为明确的 RFC3339 边界。
+- 在结果中写出实际使用的绝对时间范围，避免时区歧义。
+
+## 空结果
+
+空结果时说明实际过滤条件，并建议放宽最可能过严的一项。不要把空列表解释为没有权限，除非 CLI 明确返回鉴权或权限错误。

package/skills/arkcli-train-finetune/references/manage.md

@@ -0,0 +1,128 @@
+# 查询和管理指定精调任务
+
+本 reference 处理已知 job id 的详情、观察和生命周期操作。需要根据指标选择产物、导出 custom model 或继续部署时，改读 [`export-deploy.md`](export-deploy.md)。
+
+## 命令速查
+
+| 命令                                               | 何时用                     | 常用参数                                                |
+| ------------------------------------------------ | ----------------------- | --------------------------------------------------- |
+| `arkcli train finetune get <job-id>`             | 查完整详情，PRD-canonical 读入口 | `--transform`                                       |
+| `arkcli train finetune status <job-id>`          | 查状态；语义上等同详情查询           | `--transform`                                       |
+| `arkcli train finetune watch <job-id>`           | 持续监测进度及指标变化             | `--interval`、`--timeout`、`--quiet`、`--rich`         |
+| `arkcli train finetune metrics <job-id>`         | 查指标曲线                   | `--metric`、`--from-step`、`--to-step`、`--output`     |
+| `arkcli train finetune logs <job-id>`            | 查训练日志                   | `--tail`、`--since`、`--search`、`--follow`、`--output` |
+| `arkcli train finetune trajectory list/get`      | 查 RL 轨迹                 | 仅在任务和 TLS 配置支持时使用                                   |
+| `arkcli train finetune update <job-id>`          | 改名称或描述                  | `--name`、`--description`                            |
+| `arkcli train finetune pause/resume/stop/delete` | 生命周期操作                  | 写/删/终止前必须确认；需要时才加 `--yes`                           |
+
+## 先查询当前状态
+
+任何写操作前先执行：
+
+```bash
+arkcli train finetune get <job-id>
+```
+
+确认 job id、当前阶段和目标操作是否匹配。具体阶段限制以当前命令 `--help` 和后端错误为准，不维护静态阶段矩阵。
+
+用户询问指定任务“为什么查不到”时也直接执行同一条 `get`，并原样保留权威 API 错误。不要从 `mcj-*` 的日期片段或后缀猜测合法性；不要先执行 `list` 搜索相似任务，也不要切换 profile/project/region。用户明确限制范围时，失败即停止并解释该错误。
+
+## 详情与过程观察
+
+按用户目标选择最小命令：
+
+```bash
+arkcli train finetune get <job-id>
+arkcli train finetune watch <job-id>
+arkcli train finetune metrics <job-id>
+arkcli train finetune logs <job-id>
+arkcli train finetune trajectory list <job-id>
+```
+
+执行前查看对应 `--help`。
+
+- 一次性状态用 `get`，持续等待终态用 `watch`。
+- 指标先查询可用 metric 名称，再按真实名称过滤。
+- `metrics` 同时使用 `--from-step` 和 `--to-step` 时，`to-step` 必须严格大于 `from-step`。
+- 日志、轨迹和指标可能很大；优先使用过滤、tail 或 `--output`，不要把完整内容灌入上下文。
+- trajectory 仅在任务和当前 ArkCLI 能力支持时使用。
+- 任务失败时返回阶段、错误原因和 CLI 提供的 hint，不要盲目重复提交。
+
+### 保存指定任务日志
+
+用户同时给出 MCJ ID 和输出路径时直接执行：
+
+```bash
+arkcli train finetune logs <mcj-id> --output <path>
+```
+
+这是单任务只读查询。不要先跑 `logs --help` 后停住，也不要执行 `train finetune list --page-all`、用 Python 遍历任务或建议切换 profile/project。命令失败时保留原错误并停止；只有语法不兼容时才查看当前 `logs --help` 后重试同一个目标命令。
+
+`--follow` 会在活跃任务上持续轮询。任务执行前已经处于 `Completed` / `Failed` / `Terminated` 时，CLI 输出当前日志快照后自动退出；活跃任务后续进入终态且没有新日志时也自动退出。终态任务允许 `--follow --format json` 返回一个有界 JSON 快照；活跃任务的无界 follow 不支持单文档结构化输出。
+
+### 查询指定任务的完整 trajectory
+
+```bash
+arkcli train finetune trajectory list <mcj-id> --full
+```
+
+命令层级必须包含 `train finetune trajectory list`；不要尝试 `arkcli train trajectory` 或在 help 树里漫游。`--full` 返回完整 rollout 内容，结果较大时仅在用户给出路径或同意后增加 `--output <path>`。若命令返回任务未开启 trajectory logging、无轨迹、认证或 TLS 权限错误，保留原错误并停止，不查询其他任务、profile 或 MCP 配置。
+
+## TLS 配置
+
+查询或管理精调 TLS 配置时，必须使用完整的 `tls config` 层级：
+
+```bash
+arkcli train finetune tls config get
+arkcli train finetune tls config enable
+arkcli train finetune tls config disable
+arkcli train finetune tls config delete
+```
+
+不存在 `tls update`。不要省略 `config` 写成 `arkcli train finetune tls get`。
+
+- `get` 只读，无需确认。
+- `enable` 会创建可能产生费用的 TLS 资源，先说明费用影响并取得确认。
+- `disable` 停止写入新数据但保留已有数据，执行前需确认。
+- `delete` 会永久删除已有 trajectory、custom log、trace 和 explainability 数据，需单独确认；非交互执行只有在确认后才添加 `--yes`。
+
+## 任务元数据
+
+更新名称或描述前，打印 job id、当前值和目标值并取得用户确认：
+
+```bash
+arkcli train finetune update <job-id> --help
+arkcli train finetune update <job-id> --name <name>
+```
+
+只发送用户要求修改的字段。
+
+## 暂停、恢复、停止和删除
+
+先分别查看当前接口：
+
+```bash
+arkcli train finetune pause --help
+arkcli train finetune resume --help
+arkcli train finetune stop --help
+arkcli train finetune delete --help
+```
+
+规则：
+
+- `pause` 用于希望后续继续的任务。
+- `resume` 的主要用途是恢复 `Paused` 任务，与 `pause` 形成可逆关系；后端允许时也可重试 `Failed` / `Terminated`。执行前仍以当前任务 phase 和后端结果为准。
+- `stop` 是不可逆终止，必须明确说明影响并获得确认。
+- `delete` 删除任务记录，必须展示目标 job id、名称和当前阶段，并获得单独确认。**Phase 强校验**：仅终态（`Completed` / `Failed` / `Terminated`）可删，非终态在客户端直接拒绝并提示先执行 `train finetune stop`，避免用户输 y 后被 backend `phase_mismatch` 拒。
+- Agent 环境要求 `--yes` 时，只能在用户确认后添加。
+- 阶段不允许时，根据 CLI/backend hint 给出下一步，不通过反复重试绕过限制。
+
+## 训练产物
+
+用户只想查看产物时，可以执行：
+
+```bash
+arkcli train finetune artifacts list <job-id>
+```
+
+用户要选择最佳产物、导出或部署时，不在本文件继续，读取 [`export-deploy.md`](export-deploy.md)。

package/skills/arkcli-train-finetune/references/rl-plugins.md

@@ -0,0 +1,77 @@
+# SDK RL 插件
+
+实现或审查 rollout、grader、自定义 pipeline、tracing，以及把推理 Agent 改造成训练 Agent 时读取本文件。
+
+## 核心概念
+
+- Rollout plugin：执行模型、工具或 Agent 交互，并产出轨迹。
+- Grader plugin：对一条或多条轨迹评分，返回 reward 和可选指标。
+- Pipeline wrapper：把 rollout 和 grader 接入 `custom_rl_pipeline`，并可配置环境变量和权重。
+
+选择装饰器前，检查当前 `ark_sdk.resources.pipeline_plugin`。较新的 SDK 可能暴露 `rollout`、`single_rollout`、`group_rollout`、`single_grader`、`group_grader` 和多个 pipeline class，但具体用法以生成模板为准。
+
+## Rollout 职责
+
+Rollout 应该：
+
+- 按需读取 `sample.messages`、`sample.tools` 和 `sample.extra`
+- 构造有边界的模型、工具或 Agent 交互
+- 调用外部 API 或工具时设置超时和重试策略
+- 发生 tool call 时把工具结果回填到 messages
+- 设置最大步数并确保循环可退出
+- 在样本需要重试、丢弃、失败或向 grader 传递额外信息时，返回 SDK 约定的状态或结果
+
+训练感知客户端很关键。生成模板通常会包装客户端，让 SDK 能跟踪 completion 状态和轨迹：
+
+```python
+client = Ark(base_url=proxy.url, api_key=proxy.jwt_token)
+wrap_inplace_trace(client)
+wrap_client_inplace(client, proxy=proxy)
+```
+
+异步代码应使用异步 client 和模板里的异步包装函数。除非模板明确这么做，否则不要在 `async def` rollout 里调用阻塞式同步 client。
+
+## Grader 职责
+
+Grader 应该：
+
+- 校验评分逻辑需要的 sample 字段
+- 对收到的每条 trajectory 给出分数
+- 返回形状符合 SDK 预期的 reward 列表
+- 在 `metrics` 中补充有排障价值的自定义指标
+- 对畸形轨迹做确定性处理
+- 避免过于宽松的纯字符串打分，除非任务确实适合这样评估
+
+Reward 设计建议：
+
+- 尽量使用稠密、可解释的 reward，而不是过于稀疏的全对/全错判断。
+- 对工具参数格式错误、缺失最终答案、循环不退出、隐藏 fallback 等失败模式明确扣分。
+- 防止 reward hacking：不要因为回答提到期望文本就直接给高分，必须判断是否真实满足任务。
+- 过程 reward 只有在与最终质量一致时才使用。
+
+## 推理 Agent 到训练 Agent 的改造
+
+改造推理 Agent 时：
+
+- 把静默 fallback 改成明确扣分或明确状态
+- 让错误工具参数对 grader 可见
+- 限制最大步数和重试次数
+- 记录足够状态以复现失败
+- 在并发下测试下游 API 的延迟、限流和失败行为
+
+## Runtime 与并发
+
+装饰器可能支持实例规格、超时、并发、replica 或 request concurrency 等 runtime 设置。这些字段会随 SDK 变化，因此应复制当前模板的写法。
+
+正式训练前，用接近计划 batch size 的并发做批量测试。插件过慢时，即使模型配置正确，也会浪费训练资源。
+
+## 可观测性 Hook
+
+可用时使用当前模板的 tracing 工具：
+
+- 在 rollout/grader 函数上使用 `@trace_monitor`
+- 对模型 client 使用 `wrap_inplace_trace(...)` 或异步等价函数
+- 对工具/API 辅助函数使用 `@observe()`
+- 用 logger 记录高层决策、工具调用、校验失败和 reward 汇总
+
+不要记录密钥、原始鉴权 header、API key 或完整敏感 payload。

package/skills/arkcli-train-finetune/references/testing-debug-monitoring.md

@@ -0,0 +1,137 @@
+# SDK 测试、调试与监控
+
+提交任务前，或任务失败需要排查时读取本文件。
+
+## RL 必要顺序
+
+自定义 RL 任务按以下顺序推进：
+
+1. 本地单样本 rollout 测试。
+2. 本地 rollout 加 grader 联调。
+3. 使用代表性数据做本地小批量测试。
+4. 使用接近计划 batch size 的并发做压测。
+5. 生成项目支持时，执行在线插件或类 FaaS 测试。
+6. 使用 `debug=True` 或 `--debug` 提交 RL debug 任务。
+7. 提交正式训练任务。
+
+只有用户明确接受风险时，才跳过 debug 任务。
+
+## 非 RL 任务
+
+不要为 SFT、DPO、CPT 或其他非 RL 任务编造 RL debug 流程。按当前 SDK 文档或模板使用其正常校验和提交路径。
+
+## 本地测试
+
+优先使用生成模板中的测试工具。建议覆盖：
+
+- 一条预期通过样本
+- 一条预期失败样本
+- 畸形工具参数
+- 下游 API 超时或报错
+- 小规模代表性数据集
+- 接近目标 batch size 的并发
+
+API key 使用环境变量：
+
+```bash
+export ARK_API_KEY=...
+PYTHONPATH=. python plugins/<rollout_or_test>.py
+```
+
+如果项目使用 `uv`，遵循生成 README 或模板命令。
+
+## 依赖冻结
+
+本地测试通过后，在线插件测试前冻结依赖：
+
+```bash
+python -m pip freeze > requirements.txt
+```
+
+或在 `uv` 项目中：
+
+```bash
+uv pip freeze > requirements.txt
+```
+
+如果模板期望轻量远端环境，清理无关依赖。
+
+## 在线插件测试
+
+使用生成的 `test_faas.py`，或查看当前命令：
+
+```bash
+ark test pipeline_plugin --help
+```
+
+常见请求形态包含 `context`、`proxy` 和 `sample`，但准确结构以当前模板为准。
+
+## RL Debug 提交
+
+Python 模式：
+
+```python
+mcj.submit(debug=True)
+```
+
+YAML/命令模式：
+
+```bash
+ark create mcj --file job.yaml --debug
+```
+
+Debug 任务需要 endpoint/API-key 配置，让 rollout 能调用推理 endpoint。密钥放在环境变量或本地 secret 处理中。
+
+## 正式提交前检查
+
+正式提交前总结：
+
+- SDK 版本和已检查的模板
+- 模型引用或自定义模型 id
+- 训练方式
+- 数据路径和验证策略
+- 超参来源
+- rollout 和 grader 标识
+- 可观测性设置
+- 本地、批量、在线、debug 测试结果
+- 已知费用或资源影响
+
+## 监控
+
+提交后检查：
+
+```bash
+ark list mcj
+ark get mcj <mcj-id>
+ark pull mcj <mcj-id> --include-plugin
+```
+
+关注任务阶段、失败原因、插件日志、轨迹分析、reward 指标、自定义指标、时间线和产物输出。
+
+RL 任务中，在可用时同时观察训练 reward 和验证 reward。不要只看聚合 reward；要检查高 reward 与低 reward 轨迹，确认没有 reward hacking 或 grader 盲区。
+
+## 排障模式
+
+形成“明确问题分类 + 下一步建议”的有效 Debug 结论后，复用当前
+`ARKCLI_SKILL_FLOW_ID`（没有则生成 `ftf_<ULID>`），按 shared 单命令前缀执行
+`arkcli train finetune _report-activity --action debug_success`。仅完成查询但尚无结论时不报。
+
+1. 读取任务状态和失败原因。
+2. 检查 rollout/grader 日志和轨迹。
+3. 用最小失败样本本地复现。
+4. 增加有针对性的日志或指标。
+5. 修复插件、配置或数据。
+6. 重新跑本地、批量、在线和 debug 检查，再开始正式重训。
+
+常见失败点：
+
+- 所选模型版本不支持某个超参
+- 数据形态错误或 JSONL 非法
+- 缺少环境变量
+- 插件依赖不匹配
+- 下游工具/API 超时或过慢
+- rollout 循环不退出
+- 工具参数 JSON 错误
+- grader reward 形状不符合预期
+- rollout 吞掉了本应扣分的错误
+- grader 过于宽松导致 reward hacking

package/skills/arkcli-understand/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: arkcli-understand
+version: 1.1.0
+description: "arkcli +understand：对用户提供的图片、音频、视频或文档完成转写、抽取、字幕、定位等 12 类专项产出，包含 Agent Plan 个人版/企业版原生 WebSocket ASR 和字幕打轴。仅解释参数或排查已有多模态请求报错时转 arkcli-chat；实际理解任务支持临时凭证与本地 dry-run，开放对话走 +chat，生成走 +gen。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +understand --help"
+---
+
+# arkcli +understand
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、API Key 错误恢复、配置排查与命令选择顺序。**
+**CRITICAL — 执行 `+understand` 之前，MUST 先用 Read 工具读取 [`references/arkcli-understand.md`](references/arkcli-understand.md)（命令/flag/返回值/错误）与 [`references/sub-skills.md`](references/sub-skills.md)（12 个 sub-skill 的用途与期望输出形态）。禁止凭印象拼命令。**
+
+## 原生语音识别分支
+
+Agent Plan 个人版/企业版的 Seed ASR 2.0 使用 `+understand asr` 或 `asr-align`，
+显式指定 `--audio-protocol ws-bidirectional`（流式结果）或 `ws-unidirectional`
+（完整音频发送后返回结果）。也可通过 `--model doubao-seed-asr-2.0` 选择原生
+双向 WS。执行前读取 [`references/arkcli-understand-asr.md`](references/arkcli-understand-asr.md)。
+该路径使用专属/席位 Key、原生 ASR 参数和真实时间戳，不使用 Responses 配方、
+Endpoint 或临时 Key/Base URL。仅本地 preview 时直接 `--dry-run`，不先查 auth。
+下文的 Responses 引擎、返回值、25MB 内联限制和 recipe fallback 模型描述适用于
+`--audio-protocol responses`（默认），不会覆盖显式原生 ASR 选择。
+
+## 先区分理解任务与调用问题
+
+| 本轮要交付什么 | 执行边界 |
+| --- | --- |
+| 对具体素材转写、抽取、翻译或定位 | 使用本 Skill 的配方；缺少素材时补齐输入，不能凭空生成素材或理解结果 |
+| 解释音频/多模态参数、比较接口，或排查已有请求的字段报错 | 读取 [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) 的请求证据与条件修复；本轮交付诊断说明，到此结束，不进入后文业务准备 |
+| 同时要求解释错误并实际处理素材 | 分开记录两项交付；只在已提供素材、调用目标和实际执行授权的范围内处理，不用新请求的结果替代原错误证据 |
+
+`+understand` 的默认配方实现走 Responses API，只能说明这个 CLI 命令的行为，不能说明用户原来的音频 SDK、Chat 请求或网关也走 Responses。单凭 `unknown field` 不能判定实际接口；原 URL、模型版本或请求体缺失时保留未知，按 Chat Skill 给出条件分支。仅有“音频理解”“转写参数”等字样不会启动配方执行。
+
+参数诊断无需先准备认证、解析默认资源或选择下表的 fallback 模型。用户未提供原模型时，不自行选另一个模型查询上限并据此解释原请求；已知模型的只读能力查询也须在本次允许的工具范围内。只有本轮确实要求实际处理素材或授权复现，才进入后文执行顺序。
+
+## 核心概念
+
+- 默认理解配方复用一个引擎：底层引擎就是 `+chat` 用的数据面 Responses API；每个 sub-skill 只是一条**配方** `{模态, fallback 模型, 内置 system prompt}`。Platform Profile 省略 `--model` 时必须使用当前 Profile 的 `Resources.Text.Default` Endpoint；只有 Plan 类 Profile 才使用 recipe fallback 模型。
+- 命令形态：`arkcli +understand <sub-skill> --input @file [prompt]`。
+  - `args[0]` **命中注册表**（12 个之一）→ 当作显式 sub-skill，其余位置参数当 prompt 叠加在内置 prompt 之上。
+  - `args[0]` **不命中** → 整段位置参数都当 prompt，服务端按**首个 `--input` 的文件模态自动路由**到该模态的默认 sub-skill。
+- **必须有 `--input`**：sub-skill 是「对某个文件做理解」，没有 `--input` 会直接 `missing_input` 报错。纯 prompt 无法推导配方。
+- 返回值与 `+chat` 完全一致：arkcli **扁平** schema `{id, model, content, reasoning_content, usage}`，**不是** Responses 原生 `output[].content[].text` 嵌套。详见 [`references/arkcli-understand.md`](references/arkcli-understand.md) 的「返回值」段。
+- 多模态上传：image/video/doc 由 SDK `file://` preprocessor 自动走 Files API；**audio 是特例**——内联为 base64 data URL，**上限 25MB**。详见 reference。
+- 用户临时提供 `--api-key` / `--base-url` / Endpoint 时，MUST 读取 [`../arkcli-shared/references/execution-context.md`](../arkcli-shared/references/execution-context.md)。不要根据 Key 文本或 Endpoint 名称猜数据面/工作流。
+- `--dry-run` 只在本地解析配方、当前 Profile 已持久化的默认 Endpoint、显式模型和输入引用，输出统一 `preview.v1`；不读取在线 Endpoint/模型元数据、不上传文件、不调用 Responses API、不产生模型用量、不创建 response id 或持久化响应。在线才能补齐的值必须标为 `unresolved`，不能把预览当服务端 validation。
+
+## 快速决策（understand vs chat vs gen）
+
+| 用户意图 | 走哪个 |
+|---|---|
+| 有**明确产出形态**的多模态理解任务（转写 / 翻译 / 字幕 / 框选定位 / GUI 操作 / 字段抽取 / 分章节总结 / 多说话人 / 会议纪要） | **`+understand`**（命中某个 sub-skill） |
+| 开放式带图/视频对话、追问、推理、需要多轮接续（`--store`/`--previous-response-id`）、需要 tools（web_search/function）或 `--text-format json_schema` 严格 JSON | [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md) |
+| **生成**图片 / 视频（不是理解已有素材） | [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md) |
+
+一句话判据：**要求实际处理素材且产出对应某个 sub-skill → 用 `+understand`；仅询问参数或报错 → Chat 诊断；开放对话用 `+chat`，生成用 `+gen`。**
+
+## Agent 快速执行顺序
+
+1. 判断用户的理解任务命中哪个 sub-skill（见下表）。命中就显式带上 sub-skill 名，不要让它走自动路由去猜。
+2. 用户只给 `ep-...` → `arkcli resources resolve <ep-id> --format json`；只有用户任务属于明确理解产出，且 `supported_workflows` 包含 `understand`，才走本 skill。
+3. 用户给了临时 Key/Base URL/Endpoint → 按共享 execution-context 组合规则决定参数，不先切 profile。
+4. 没有完整 stateless 上下文时过认证闸门：不确定登录态先 `arkcli auth status`；鉴权失败按 [`../arkcli-auth/references/auth-modes.md`](../arkcli-auth/references/auth-modes.md) 的「API Key 模式的错误恢复」处理，**不要原地重试**。
+5. 备好输入：`--input @<file>`（可多次）。本地文件用 `@` 前缀；远程用 `https://` / `tos://` URL。
+6. **默认不传 `--model`**：Platform Profile 会使用 `Resources.Text.Default` 中已部署的 `ep-xxx`，与 `+chat` 保持一致；Plan 类 Profile 才使用 sub-skill 的 recipe fallback 模型。只有用户明确指定其他资源时才传完整版本化 ID 或 `ep-xxx`。
+7. 需要逐段输出加 `--stream`；想微调任务指令用 `--system-prompt-append "..."`，或 `--system-prompt-override "..."`。
+8. 跑完回到用户原始目标，不要停在中间产物上。
+
+## sub-skill 速查表（12 个 / 4 模态）
+
+> 下表是 Plan 类 Profile 使用的 recipe fallback 模型。Platform Profile 不使用这些裸模型名，而是使用当前 Profile 的 `Resources.Text.Default` Endpoint。确需覆盖时见上文执行顺序。
+
+| sub-skill | 模态 | Plan recipe fallback 模型 | 一句话用途 |
+|---|---|---|---|
+| `image-caption` | image | `doubao-seed-1-6` | 单图/多图描述、OCR（保留原文，不意译） |
+| `image-grounding` | image | `doubao-seed-1-6` | 视觉定位：输出目标 bbox `(x1,y1,x2,y2)` + confidence |
+| `image-gui` | image | `doubao-seed-1-6` | GUI 截图 → 可执行操作序列（12 类操作 JSON 数组） |
+| `doc-extract` | file | `doubao-seed-1-6` | PDF/文档按 schema 抽取结构化 JSON（缺失填 null，保留 page） |
+| `video-summary` | video | `doubao-seed-1-6` | 视频总结：overall / segment / chapter + 关键时间点 |
+| `video-qa` | video | `doubao-seed-1-6` | 视频问答：结合画面+音频+时间轴精准回答 |
+| `vau` | video | `doubao-seed-2-0-lite` | 音视频联合理解：分析视频内声音元素，出音频分析报告 |
+| `asr` | audio | `doubao-seed-2-0-lite` | 语音转写：仅输出纯文本，无任何前后缀/格式 |
+| `asr-align` | audio | `doubao-seed-2-0-lite` | 字幕打轴：默认 SRT 格式（序号+起止时间+文本） |
+| `asr-speakers` | audio | `doubao-seed-2-0-lite` | 多说话人转写：标 `[spk0]` / `[spk1]` ... |
+| `ast` | audio | `doubao-seed-2-0-lite` | 语音翻译：把音频里的话译成文本 |
+| `meeting-minutes` | audio | `doubao-seed-2-0-lite` | 会议纪要：结构化 markdown（主题/参会人/要点/决议/待跟进） |
+
+逐条的期望输出形态与示例命令见 [`references/sub-skills.md`](references/sub-skills.md)。
+
+## 省略 sub-skill 时的自动路由
+
+`args[0]` 不命中注册表时，按**首个 `--input` 的文件扩展名**推断模态并兜底到该模态的默认 sub-skill：
+
+| 推断模态 | 兜底 sub-skill |
+|---|---|
+| image（`.jpg/.png/.webp/...`） | `image-caption` |
+| video（`.mp4/.mov/...`） | `video-qa` |
+| audio（`.mp3/.wav/.m4a/...`） | `asr` |
+| file（其他扩展名） | `doc-extract` |
+
+- **没有 `--input` 时无法自动路由**（纯 prompt 推不出配方）→ 报 `missing_sub_skill`。
+- 目前**只按文件模态兜底，不做 prompt 关键词级路由**（例如说「框出」不会自动选 `image-grounding`）。Agent 想要非默认 sub-skill（如 grounding / gui / summary / 字幕 / 翻译）就**显式写出 sub-skill 名**，别依赖自动路由。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `arkcli +understand image-caption --input @photo.jpg "描述这张图"` | 图片描述 |
+| `arkcli +understand image-caption --input @doc.png "OCR，原样保留文字"` | OCR |
+| `arkcli +understand image-grounding --input @scene.jpg "框出所有红色car"` | 视觉定位 bbox |
+| `arkcli +understand doc-extract --input @invoice.pdf "抽取 发票号/金额/日期"` | 文档字段抽取 |
+| `arkcli +understand video-summary --input @clip.mp4 "按 chapter 总结"` | 视频分章节总结 |
+| `arkcli +understand video-qa --input @clip.mp4 "视频里出现了几辆车？"` | 视频问答 |
+| `arkcli +understand asr --input @speech.mp3` | 语音转写（无需 prompt） |
+| `arkcli +understand asr-align --input @speech.mp3` | 生成 SRT 字幕 |
+| `arkcli +understand asr-speakers --input @meeting.wav` | 多说话人转写 |
+| `arkcli +understand ast --input @speech.m4a "译成英文"` | 语音翻译 |
+| `arkcli +understand meeting-minutes --input @meeting.m4a` | 会议纪要 |
+| `arkcli +understand "<prompt>" --input @photo.jpg` | 省略 sub-skill → 按模态自动路由（此处 → image-caption） |
+| `arkcli +understand asr --input @speech.mp3 --stream` | 流式逐段输出 |
+| `arkcli +understand image-caption --input @x.jpg --system-prompt-append "用英文回答"` | 在内置 prompt 后追加指令 |
+| `arkcli +understand image-caption --input @x.jpg "描述图片" --dry-run --format json` | 返回 recipe / 模型 / 请求摘要的 `preview.v1`；零网络、不上传、不推理 |
+
+## 详细文档
+
+- 全部 flag、`@file`/audio 上传机制、返回值扁平 schema、错误码、raw API 兜底、与 `+chat` 的关系 → [`references/arkcli-understand.md`](references/arkcli-understand.md)
+- 12 个 sub-skill 的逐条用途、**期望输出形态**、示例命令 → [`references/sub-skills.md`](references/sub-skills.md)
+- 最小评估/回归用例 → [`references/evals.md`](references/evals.md)

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

@@ -0,0 +1,53 @@
+# 原生 WebSocket ASR
+
+火山 Agent Plan **个人版/企业版**支持 Seed ASR 2.0 原生转写和字幕，使用当前
+`agent-plan` 专属 Key 或 `agent-plan-team` 席位 Key。先读 `../SKILL.md`
+及 `../../arkcli-shared/SKILL.md`；调用归因 `ARKCLI_SKILL_NAME=arkcli-understand`。
+用户已授权的素材和真实调用直接沿用；不创建 Endpoint，不换普通 Key。
+
+## 执行
+
+1. 只预览：`+understand asr --input @speech.wav --audio-protocol ws-bidirectional --dry-run`。
+   不读音频、不加载 profile/认证、不请求网络、不写文件；真实音频分包和资格标为 unresolved。
+2. 真实处理：核对 `auth status`、已有套餐 profile 和素材；个人版先执行使用协议检查，
+   企业版走席位 Key；鉴权后再读取文件。保存失败不自动重复识别。
+3. 使用明确的 `asr`（纯转写）或 `asr-align`（真实时间戳字幕），必须且只能一个 input。
+   `asr-speakers`、翻译和会议纪要继续使用 Responses 配方。
+4. 输出成功必须收到服务器最终包；中断和错误不写部分文件。`content` 为完整
+   转写或 SRT/VTT；`utterances` 保留服务器的句子、词级时间戳及 additions。
+
+```bash
+arkcli +understand asr --input @speech.wav \
+  --audio-protocol ws-bidirectional --stream
+
+arkcli +understand asr-align --input @speech.mp3 \
+  --audio-protocol ws-unidirectional --subtitle-format vtt --save-to ./subtitles
+
+arkcli +understand asr --input @speech.pcm --model doubao-seed-asr-2.0 \
+  --asr-options '{"enable_itn":true,"enable_punc":true}' --dry-run
+```
+
+| Flag | 契约 |
+| --- | --- |
+| `--audio-protocol` | `responses` 默认；原生选择 `ws-bidirectional` / `ws-unidirectional` |
+| `--model` | 原生仅 doubao-seed-asr-2.0 或 volc.seedasr.sauc.duration；不指定协议时默认双向 WS |
+| `--input` | 单个本地 @file、file:// 或 HTTP(S) URL；客户端最大 64 MiB，不自动转码 |
+| `--audio-format` | wav、pcm、mp3、ogg（Opus）；省略按扩展名推断 |
+| `--audio-channels` | PCM 声道 1（默认）或 2；WAV 以 header 为准 |
+| `--asr-language` | 仅单向 WS 按官方支持的语言值传递 |
+| `--asr-options` | request JSON；可配置 ITN、标点、顺滑、热词等官方支持项；model_name 固定 bigmodel，result_type 固定 full；字幕必须 show_utterances=true |
+| `--subtitle-format` | 仅 asr-align；srt（默认）/vtt；句级时间戳从服务端毫秒转换 |
+| `--save-to` | 可选目录；成功后创建唯一 asr-*.txt/srt/vtt，不覆盖已有文件 |
+| `--stream` | NDJSON `asr.delta`（完整的当前文本，可能修订；不是追加文本）与 `asr.completed`（最终结果） |
+| `--timeout` | 含读取、分包和识别的截止时间，默认 120s |
+
+PCM/WAV 要求 PCM s16le、16000 Hz、1/2 声道；WAV 同时验证格式与数据 chunk。
+MP3、Ogg Opus 由服务端解码。不支持 m4a。原生 ASR 不接受配方 prompt、
+system-prompt、thinking、temperature、store 等 Responses 参数，也不接受
+临时 `--api-key` / `--base-url`。纯转写可没有话语内容；字幕没有真实时间戳时
+会报错，不伪造打轴。`audio_info` 和 `usage` 只保留当前服务器返回的字段，
+不承诺历史语音用量查询。错误保留服务端 Code 与 LogID，不自动重试请求。
+
+接口分别为 `/api/v3/plan/sauc/bigmodel_async` 与
+`/api/v3/plan/sauc/bigmodel_nostream`，Resource ID `volc.seedasr.sauc.duration`。
+[官方 Agent Plan 语音文档](https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-voice-model)。