@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-models/references/arkcli-models-get.md

@@ -0,0 +1,100 @@
+# models get
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查看模型详情，聚合多个底层模型元数据接口返回完整信息。
+
+## 命令
+
+```bash
+# 位置参数方式（推荐）
+arkcli models get doubao-seed-2-0-pro-260215
+
+# 指定版本
+arkcli models get doubao-seed-2-0-pro-260215 260215
+
+# 显式 flag 方式
+arkcli models get --id doubao-seed-2-0-pro-260215 --version 260215
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `<id>` / `--id` | 是 | string | 模型标识符，如 `doubao-seed-2-0-pro-260215` |
+| `[version]` / `--version` | 否 | string | 模型版本覆盖，如 `260215` |
+
+## 返回值
+
+JSON 格式的模型详情，聚合自多个底层 API，包含模型名、版本、能力、定价、限流等信息。缓存能力看顶层 `cache_types`：可能包含 `explicit_cache` / `implicit_cache` / `session_cache` / `prefix_cache`；`capabilities.caching` 仅为旧版兼容字段，不用于判断全部缓存类别。
+
+`supported_params` 按当前详情的精确模型版本补充。主版本可复用本地新鲜 ArkModels 元数据缓存；缓存不可用、显式非主版本或 `--no-cache` 时，CLI 改用精确版本的 `ListModelMetaDatas` 查询。`models get` 不会为了补该字段新增 ArkModels 网络请求，避免触碰其低 QPS 限制。`--no-cache` 仍会绕过 CardView 与 ArkModels 元数据缓存。
+
+- 字段缺失或空数组：该版本当前没有可用参数目录，`--transform supported_params` 可能显示 `null`。
+- 上游字段存在但 JSON 损坏：CLI 在 stderr 输出带模型名和版本的 `warn: model supported_params enrichment failed: ...`，stdout 仍返回其余模型详情。
+
+## 参数证据与查询冲突
+
+- `supported_params` 是当前版本的参数目录：已列出且 `support=true` 才能据此说明支持，并继续核对 `type/min/max/enum/required`；明确 `support=false` 要如实报告。**未列出不等于服务端一定拒绝、忽略或采用某个默认值**，也不能证明运行时会怎样处理这个参数。
+- 参数目录、`api_support` 和真实调用是三类证据。回答 Responses/Chat/图像/视频 API 是否支持时，读取目标 API 对应项；不能拿另一 API 的支持、`thinking` 能力或模型名称代替。项缺失/未知就说明未确认。
+- `search` 与 `get` 不一致时先核对已有证据中的模型名、精确版本、查询范围及缓存/告警信息。题设或本轮结果已明确同名、同版本、同范围时，直接报告该条件下仍存在冲突，不再以“先对齐版本”推迟回答，也不为重复确认已知事实再查询。分别列出“search 返回什么 / get 返回什么”，保留来源，不取并集、取较乐观的一项或静默覆盖。主版本的 search 元数据不能反证另一个显式版本的 get。
+- 对“未列出的参数能否传、会被忽略吗、默认值是多少”，应转对应执行 Skill 核对 CLI/SDK 契约或官方文档；确需运行时验证时先说明会产生的调用/费用，并限于用户授权的同模型、同 API、同身份。没有验证就保持未知，不为答一个目录问题擅自发起推理。
+
+## NotFound / 空结果的定位
+
+精确 ID 优先直接 `get`；失败不能立即总结为模型不存在。先分清错误与正常空结果，再核对用户原始 ID、版本和 CLI 已支持的 DisplayName 归一化；不要手工用六位日期正则拆 ID。用户给的是 `cm-*` / `ep-*` / Plan 调用别名时，分别转自定义模型、接入点或套餐资源查询，不在公共目录反复试。
+
+纯目录排查确需搜索时，用规范名称/族名做一次有界 `models search`，每次只调整一个有依据的名称或过滤条件；若用户查询历史/退役模型，核对 `--include-deprecated`，不要把默认隐藏解释成从未存在。候选不唯一时让用户选，不能自动换成名称相似的模型；最终说明查过的范围和仍未知的部分。创建/部署路径服从 owning Skill 的有界查询与完整捕获恢复流程，不能以“只查一次”为由丢弃可恢复的截断结果，也不借此循环 search/get。
+
+## 价格与权益
+
+价格来自新价格服务，输出为 `pricing.model_name`、`pricing.prices` 和可选 `pricing.dimension_attributes`。旧 `pricing.charge_items` / `pricing.multi_charge_items` 已删除，脚本和 Agent 必须迁移，不能继续按旧 `type` 筛选。
+
+```bash
+# 查看价格及原有开通状态、权益
+arkcli models get doubao-seed-2-0-pro-260215 --format json --transform pricing
+
+# 只查看统一价格数组（不包含免费额度或开通状态）
+arkcli models get doubao-seed-2-0-pro-260215 --format json --transform pricing.prices
+```
+
+| 字段 | 消费规则 |
+|------|----------|
+| `service_type` | 区分 `infer`、`fast-infer`、`flex-infer`、`batch-infer`、`infer-storage`、`finetuned-infer`、`finetuned`；训练与推理不能混选 |
+| `label` | 计费项标识，必须结合服务与适用条件判断；不等同于旧 `type` |
+| `dimensions` | 完整适用条件，含上下文档位、时段、分辨率等；`ranges` 可提供范围描述，空串维度值也有意义 |
+| `usage_unit` / `unit_code` / `usage_period` | 用量单位、价格单位及可选周期；原样读取，不固定按千 Token 换算，不猜币种 |
+| `price` / `original_price` | 可空数字；`null` 是缺价，`0` 是该条件下零价，不能互相替代 |
+| `discount_price_start_time` / `discount_price_end_time` | 可选折扣时间；说明适用时间，不自行补值 |
+| `group_index` | 本次响应内的原始分组下标，不是跨请求稳定 ID；不同组不能直接合并 |
+| `dimension_attributes` | 模型级维度属性；保留了未被价格行引用的属性，可用于理解范围 |
+
+- 先按业务服务、计费项和全部适用条件筛选，再展示价格；多条仍匹配时列出差异，不能默认取第一条或最低价。未知维度无法解释时说明条件不明，不估算总价。
+- `pricing.prices: []` 表示当前查询没有价格，不证明模型免费、未开通或不存在。价格请求失败时命令返回错误，不回退旧价。
+- `pricing.state`、`inference_free_usage`、`resource_pack_items`、`sub_services` 及其他原有非价格字段继续由旧权益接口提供，字段路径不变；权益缺失不能按零额度或未开通解释。
+- 价格按详情解析后的基础模型名查询；`--version` 不会变成价格请求条件。当前使用模型广场默认维度，地域为 global，不能把 profile 的物理地域当作价格维度。
+- 本次变更只适用于 `models get`；`pricing models`、精调查价和估价仍使用各自的现有契约，不能将这里的新字段套用到它们的输出。
+
+
+## 常见错误
+
+| 错误 | 原因 | 处理方式 |
+|------|------|---------|
+| 模型不存在 | ID 拼写错误或模型已下线 | 用 `arkcli models search` 确认模型名 |
+| 认证失败 | 未登录或凭证过期 | 运行 `arkcli auth login volc-sso` 重新建立 Volc 身份 |
+
+## 注意事项
+
+- `id` 和 `version` 都支持位置参数和 flag 两种传入方式
+- 该命令会聚合多个底层 API，可能比 `list` 稍慢
+
+## 守卫
+
+- 认证失败先回到 `arkcli auth status`，再运行 `arkcli auth login volc-sso`
+- 不确定模型 ID 时，先用 `arkcli models search` 或 `arkcli models list --name` 确认，避免反复调用不存在的 ID
+- 只读查询优先，不要在模型详情排障中切换 profile 或修改本地配置，除非用户明确确认
+
+## 参考
+
+- [arkcli-models](../SKILL.md) -- models 全部命令
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- 认证和全局参数

package/skills/arkcli-models/references/arkcli-models-list.md

@@ -0,0 +1,73 @@
+# models list
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+分页列出火山引擎 ARK 平台的公共基础模型清单，支持按模态筛选和排序。它适合做公共目录的全量枚举和统计；如果用户是在找"哪个模型适合某任务"，仍优先使用 `arkcli models search`。
+
+## 命令
+
+```bash
+# 列出所有模型（默认分页）
+arkcli models list
+
+# 按模态筛选
+arkcli models list --modality text
+
+# 按名称做不区分大小写的子字符串筛选
+arkcli models list --name doubao
+
+# 分页控制
+arkcli models list --page-size 20 --page-number 2
+
+# 排序（sort-order 必须是 Asc/Desc，首字母大写）
+arkcli models list --modality text --sort-by UpdateTime --sort-order Desc
+
+# 拉取完整清单，供本地脚本统计/过滤
+arkcli models list --page-all --sort-by CreateTime --sort-order Desc --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--modality` | 否 | string | 按模态筛选：`text` / `image` / `video` / `audio` / `embed` |
+| `--name` | 否 | string | 按模型名做不区分大小写的子字符串筛选 |
+| `--page-number` | 否 | int | 页码（>=1） |
+| `--page-size` | 否 | int | 每页数量 |
+| `--sort-by` | 否 | string | 排序字段，如 `UpdateTime`、`CreateTime` |
+| `--sort-order` | 否 | string | 排序方向，合法值：`Asc` / `Desc`（首字母大写） |
+
+## 公共目录与账号资产边界
+
+`models list` 枚举公共基础模型目录，不是账号自定义模型或已部署 Endpoint 清单。
+
+- “我的自定义模型 / 最近 7 天创建了多少自定义模型”转 [arkcli-custommodel](../../arkcli-custommodel/SKILL.md)，使用 `arkcli models custommodel list --mine --page-all --format json`；用户明确要求账号全部资产时才去掉本人范围。统计所有创建记录时不额外加 `--ready` 丢掉未就绪项。
+- 最近创建统计基于该资产清单实际返回的创建时间，在完整、未截断结果上按用户时区/时间窗口过滤；字段缺失、无法解析或分页不完整就披露未知/部分统计。不得从公共目录的 `model_type`、名称、tags 或 `CreateTime` 猜账号资产归属。
+- 已部署接入点用 `infer endpoint list`；当前 Profile 可调用资源用 `resources list`。它们和公共目录不是同一集合。
+- Plan 支持哪些模型转 `plans model-list --plan <plan>`；目录中找不到套餐路由别名，不证明套餐不能使用该别名。
+- `models list` 缺少某能力字段，不证明支持或不支持；能力问题用 `models search/get` 的精确模型/版本元数据。公共目录零条不证明账号没有自定义模型或 Endpoint。
+
+`--transform` 只适合字段提取（如 `items.#`、`items.#.name`），不是完整 jq，不支持日期运算。公共目录统计也应先保留完整 JSON，再本地投影/过滤，不用截断后的样本冒充总量。
+
+## 返回值
+
+
+JSON 格式的分页结果，顶层字段包括 `page_number`、`page_size`、`total_count`、`items`；每个 item 通常包含 `name`、`display_name`、`primary_version`、`access_type`、`foundation_model_tag` 等字段。
+
+## 常见错误
+
+| 错误 | 原因 | 处理方式 |
+|------|------|---------|
+| 空结果 | `--name` 子字符串筛选无命中 | 核对名称片段与查询范围，必要时用 `models search` |
+| 认证失败 | 未登录或凭证过期 | 运行 `arkcli auth login volc-sso` 重新建立 Volc 身份 |
+
+## 注意事项
+
+- `--name` 是不区分大小写的子字符串筛选；精确详情使用 `models get <id>`
+- 结合 `--transform` 可提取特定字段，如 `--transform 'items.0.name'`
+- 先选对公共目录/自定义资产/Endpoint/Plan 的产品命令，再考虑分页和本地过滤；不要因缺少 filter 就探 Raw API 或改查另一类资源
+
+## 参考
+
+- [arkcli-models](../SKILL.md) -- models 全部命令
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- 认证和全局参数

package/skills/arkcli-models/references/arkcli-models-performance.md

@@ -0,0 +1,32 @@
+# arkcli models performance (Volc only)
+
+This capability compares public aggregated model performance. It is not an SLA
+and does not diagnose a user's Endpoint.
+
+```bash
+# Independent TTFT and TPOT rankings; defaults: 10k input, past 6h, top 10.
+arkcli models performance rank --metric all --format json
+
+# Time series for one or more exact model selectors.
+arkcli models performance trend \
+  --model doubao-seed-2-0-mini@260428:fast \
+  --model <another-name>@<version>:<deployment>
+
+# Compare the same models at four input lengths by default.
+arkcli models performance input-length \
+  --model doubao-seed-2-0-mini@260428:fast \
+  --metric all --time-window 7d
+```
+
+- `--metric`: `ttft`, `tpot`, or `all`. Lower values are better; do not create a combined score.
+- `trend` uses the same defaults as `rank` for unspecified performance
+  parameters: `--metric all`, `--thinking false`, `--input-length 10k`, and
+  `--time-window 6h`. Only pass a flag when the user explicitly requests a
+  different value.
+- `--model`: required for `trend` and `input-length`; exact format
+  `name@version:deployment`, where deployment is `default` or `fast`. Repeat
+  `--model` to view multiple models in one trend request. At most 50 unique selectors.
+- `rank` supports `--keyword`, `--deployment`, `--top 1..50`,
+  `--order asc|desc`, and `--compare default-deployment|none`.
+- Read `metadata`, `warnings`, and `disclaimer` in JSON output. A positive
+  `data_delay_minutes` means the data is not real time.

package/skills/arkcli-models/references/arkcli-models-scenario-table.md

@@ -0,0 +1,83 @@
+# models 场景化推荐表（策展层 / 意图排序最高权重）
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **快照对齐：** Volc 2026-09。表里的"版本"列是**策展快照**，不是事实源。**任何完整模型 ID 都以 `arkcli models search` 实时返回为准**——见下方 JOIN 协议。
+
+## 这张表解决什么
+
+模型搜索不是召回问题，是排序问题：本地缓存有**全量模型**，任何 query 都 100% 召回，难的是**精准排序**。命名启发式（代次 / tier / update_time）只能从模型名字猜能力，猜不出"这个模型适合翻译还是适合 Agent 任务"——缺的是**标签系统**。
+
+本表就是那套标签系统：人工策展的 `场景标签 → 推荐模型`，把"意图 → 模型"这一跳钉死。它是**意图排序的最高权重信号**，压过命名启发式；但必须经左表（本地缓存）事实校验才采纳。
+
+## 使用规则
+
+- Agent 基于「场景标签 + 推荐模型描述」召回推荐模型。
+- 推荐模型描述包含版本差异、常见需求词、旧模型别名和升级引导，用于提升检索命中率。
+- 用户明确指定第三方、开源或历史模型时，回到 `arkcli models search` 检索，**不强行替换**。
+- 本表只服务"按意图找模型"（search 线）。**枚举 / 盘点 / 统计走 `arkcli models list`，不挂本表重排。**
+- Volc 的推荐还须服从[平台模型下线公告](https://ark.volcengine.com/region:cn-beijing/docs/model-deprecation-notice)的 EOM/EOS：已过 EOM 的旧版本不能推荐作新接入，即使公共目录暂显示 `Published`；已有接入点的可用性另按 EOS 与实时状态判断。2026-09-22 第十批公告列出 `doubao-seed-2-0-pro-260215`、`doubao-seed-2-0-code-preview-260215` 已于 2026-09-24 停止新购，分别建议迁移至 `doubao-seed-2-1-pro-260915`、`doubao-seed-evolving`。本表只把它们作为选型候选，不能用公告代替实际能力/账号可用性验证。
+
+## 模型推荐表
+
+| 场景标签 | 默认推荐模型 | 版本 | 推荐模型描述 |
+| --- | --- | --- | --- |
+| 文本生成 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | 通用生产模型，兼顾效果、响应速度与成本。适合日常问答、内容创作、文案撰写、摘要总结、办公辅助和一般文本处理。用户未提出特殊要求，或仅询问通用模型、默认模型、日常模型时优先推荐。 |
+| 文本翻译 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | 适合文章、产品文案、技术资料和日常内容的多语言翻译，也可用于润色、改写和跨语言内容转换。用户询问翻译模型、英文润色、多语言处理时推荐。 |
+| 信息抽取 | Doubao-Seed-2.0-mini | doubao-seed-2-0-mini-260428 | 面向高吞吐、轻量调用优化。适合字段提取、分类归纳、标签生成、格式转换和批量结构化处理。用户强调调用量大、任务明确、批处理或成本敏感时优先推荐。 |
+| 长文本理解 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | 适合分析长文章、报告、网页内容和多轮上下文，完成总结、问答、归纳和关键信息提取。用户询问长文阅读、长上下文、报告总结时推荐。 |
+| 文档理解 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | 适合阅读文档、分析材料、总结报告和回答基于文件内容的问题，可用于办公、研究和知识整理。用户询问 PDF、文件解析、文档问答时推荐。 |
+| 复杂推理 | Doubao-Seed-2.1-pro | doubao-seed-2-1-pro-260915 | 面向复杂工作流和长链路推理的候选。适合多步骤分析、复杂指令、多约束任务、方案比较、数学逻辑和科研辅助；实际版本与能力以本轮搜索为准。 |
+| Agent 任务 | Doubao-Seed-2.1-pro | doubao-seed-2-1-pro-260915 | 智能体、自动化任务和复杂工作流的候选。用户询问任务拆解、多轮规划、持续决策和长链路执行时，先查实时支持能力。 |
+| 工具调用 | Doubao-Seed-2.1-pro | doubao-seed-2-1-pro-260915 | Function Calling、MCP 或外部 API 编排的候选；推荐前须从本轮模型结果验证 `functioncall`，不能仅凭表内描述推断。 |
+| 低成本调用 | Doubao-Seed-2.0-mini | doubao-seed-2-0-mini-260428 | 面向推理吞吐和部署密度优化，适合预算敏感的轻量任务，如分类、抽取、改写、格式转换、标签生成和批量内容处理。用户询问便宜、省钱、低成本时推荐。 |
+| 高并发调用 | Doubao-Seed-2.0-mini | doubao-seed-2-0-mini-260428 | 面向高并发和批量生成优化。适合快速回复、实时分类、短文本处理、大规模离线任务和高频调用。用户询问高吞吐、低等待、批处理时推荐。 |
+| 代码生成 | Doubao-Seed-Evolving | doubao-seed-evolving（以实时结果确认调用名） | 代码生成、补全、解释、调试、Bug 修复、多文件修改和项目级开发的候选；先确认当前版本和代码能力，不把公告迁移目标直接当作本账号可调用证明。 |
+| 角色扮演 | Doubao-Seed-Character | doubao-seed-character-251128 | 面向角色扮演和故事叙事定向优化。适合虚拟角色、人设对话、情感陪伴、多人剧情互动和长旁白故事。用户询问角色模型、陪伴模型、剧情互动时推荐。 |
+| 视觉理解 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | Seed2.0 Lite 原生支持文本、图片、音频、视频统一理解，适合图片问答、截图分析、图表解读、视觉信息提取和图文混合输入。用户询问看图、识图、图表分析或通用多模态模型时优先推荐。 |
+| 复杂视觉推理 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | Seed2.0 Lite 支持跨模态推理，可结合图片、视频、音频和文本信息完成复杂分析。适合多图理解、复杂图表、视觉逻辑推理、图文整合和跨模态问答。 |
+| 视频理解 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | Seed2.0 Lite 强化视频时序理解和运动感知，并可联合视频画面、语音和环境声音完成端到端音视频理解。适合视频总结、关键事件分析、动作理解、视频问答和从视频中提取音频信息。 |
+| 音频理解 | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | Seed2.0 Lite 支持原生音频输入和音频理解，可分析录音、播客、会议和访谈内容，完成摘要总结、信息提取和问答。适合需要同时结合语音、环境声音与上下文的任务。 |
+| GUI Agent | Doubao-Seed-2.0-lite | doubao-seed-2-0-lite-260428 | Seed2.0 Lite 已升级 GUI 能力，适合网页、桌面和 App 界面的视觉理解、元素识别、视觉定位、点击执行和流程自动化。用户提到 GUI Agent、UI-TARS、ui tars、Browser Use、Computer Use、页面自动化时，默认优先引导至 Seed2.0 Lite；仅在必须兼容旧接入时再查询旧模型。 |
+| 图片生成 | Doubao-Seedream-5.0 | doubao-seedream-5-0-260128 | 新一代图片生成模型，支持深度思考和联网检索，强化知识推理、指令理解、生成效果、编辑响应和一致性。适合海报、电商素材、品牌视觉、插画、概念图和专业创意内容。用户询问 Seedream 4.0、Seedream 4.5 或旧版生图模型但未要求兼容旧接入时，优先引导至 Seedream 5.0。 |
+| 知识型图片生成 | Doubao-Seedream-5.0 | doubao-seedream-5-0-260128 | 支持深度思考与联网检索，适合结合知识信息、实时内容和复杂指令完成生成。可用于信息图、知识海报、专业设计素材、时事可视化和需要事实理解的图片创作。 |
+| 图片编辑 | Doubao-Seedream-5.0 | doubao-seedream-5-0-260128 | 相比 Seedream 4.5，进一步强化编辑响应和一致性。适合局部修改、元素增删、参考图改图、风格调整、画面优化和主体一致性保持。用户提到 Seedream 4.5、Seededit 或旧版图片编辑时，默认优先引导至 Seedream 5.0。 |
+| 多图参考 | Doubao-Seedream-5.0 | doubao-seedream-5-0-260128 | 适合结合多张参考图完成生成和编辑，可用于人物一致性、商品一致性、多图融合、系列素材和参考图改造。用户询问多图编辑、主体保持、系列图片生成时推荐。 |
+| 图片文字渲染 | Doubao-Seedream-5.0 | doubao-seedream-5-0-260128 | 适合在画面中生成文字、制作带文案视觉素材和完成知识型图片创作，可用于海报、封面、营销图片、信息图和版式设计。用户提到 Seedream 4.5 的文字渲染能力时，默认优先推荐新版 Seedream 5.0。 |
+| 视频生成 | Doubao-Seedance-2.0 | doubao-seedance-2-0-260128 | 新一代音视频联合生成模型，支持文本、图片、音频和视频混合输入，可参考画面、动作、运镜、视觉效果和声音。适合广告、短片、创意视频、复杂动作、视频编辑和视频延展。用户提到 Seedance 1.5、SD1.5、Seedance 1.0 或旧版视频生成时，默认引导至 Seedance 2.0，说明其为全面升级版本。 |
+| 快速视频生成 | Doubao-Seedance-2.0-fast | doubao-seedance-2-0-fast-260128 | Seedance 2.0 快速版本，适合快速生成视频预览、批量产出短视频和高频迭代。用户强调快速出片、降低等待、批量生成或先看效果时推荐。 |
+| 音画视频生成 | Doubao-Seedance-2.0 | doubao-seedance-2-0-260128 | 采用统一多模态音视频联合生成架构，支持文本、图片、音频和视频输入，适合原生音轨、对白、环境音、动作和镜头协同的视频创作。可用于短剧、广告、音乐视频、口型同步和多模态参考生成。 |
+| 3D 生成 | Doubao-Seed3D-2.0 | doubao-seed3d-2-0-260328 | 新一代图生 3D 模型，强化几何精度、纹理和 PBR 材质质量，并提升下游可用性。适合商品展示、游戏资产、设计原型、仿真环境和具身智能训练素材。用户询问 Seed3D 1.0 或旧版图生 3D 时，默认引导至 Seed3D 2.0。 |
+| 语音播客 | Doubao-语音播客 |  | 基于端到端实时语音模型，将文章、网页和知识内容自动提炼为双人对话，并生成播客音频。适合资讯解读、知识讲解、教育内容和音频分发。 |
+| 音色设计 | Doubao-音色设计 |  | 适合根据自然语言描述设计个性化音色，可用于品牌声音、虚拟角色、游戏人物和差异化语音体验。 |
+| 语音合成 | Doubao-语音合成-2.0 |  | 适合将文本转化为自然、流畅且具有表现力的语音。可用于视频配音、有声阅读、客服播报、导航和智能助手。用户询问 TTS、配音、朗读、旁白时推荐 2.0 版本。 |
+| 实时语音识别 | Doubao-流式语音识别 |  | 适合边说边转文字的实时场景，如会议字幕、直播字幕、语音输入、智能外呼和 IM 语音消息转写。用户询问 ASR、实时转写、流式识别时推荐。 |
+| 录音文件识别 | Doubao-录音文件识别 |  | 适合将录音文件转写成文字，支持会议纪要、访谈整理、课堂记录、客服质检和字幕生成。用户询问离线音频转写、录音识别、批量音频处理时推荐 2.0。 |
+| 实时语音交互 | Doubao-实时语音交互 |  | 端到端 Speech-to-Speech 实时语音模型，适合低延迟语音对话。S2S-O 用于闲聊、客服、车载和通用助手；S2S-SC 用于角色扮演、情感陪伴和人格化语音交互。 |
+| 多模态向量化 | Doubao-embedding-vision | doubao-embedding-vision-251215 | 适合将文本、图片和视频转换为向量表示，用于语义检索、相似内容召回、跨模态搜索、推荐系统和多模态知识索引。用户询问 embedding、向量模型、以图搜图、视频检索时推荐。 |
+
+## JOIN / 验证协议（场景表 ⨝ 本地全量缓存）
+
+**核心原则：场景表给意图，`arkcli models search` 给事实。表里的版本/full-id 只是起点，命中以 search 实时返回为准。**
+
+**层级边界（别串台）：本表是「模型广场选型层」，数据源永远是 `models search`（catalog），给的是 catalog 推荐模型名。** "当前 profile 能不能调用、确切可调用 id"是下游可用性层（`resources list` → `models get` → `+gen`/`+chat`，arkcli-gen 已实装），**不在本表职责内**。纯选型问题（"查/选哪个模型"）只走 `models search`，不要跑去查 `resources list`；只有用户真要生成/调用时才下沉到 resources list 解析本 profile 真实 id。例：生图选型答 `doubao-seedream-5-0`（catalog 名）；具体到套餐 profile 能点的可能是 `doubao-seedream-5.0-flash`，那是下游 `+gen` 解析的事。
+
+```
+① 用户意图 → 匹配场景标签            （用"推荐模型描述"里的需求词提升命中）
+② 取该行"默认推荐模型"，推出族名词干  （如 Doubao-Seed-2.0-lite → doubao-seed-2-0-lite）
+③ arkcli models search <族名词干>     ← 回左表校验事实（必做，不可跳过）
+   ├─ exact   族名命中、版本一致        → 拼 <name>-<primary_version> 置顶推荐
+   ├─ drift   族名命中、版本不同        → 用 search 返回的真实版本（它已按 gen/time 排好序，取 top）
+   │                                     并提示"推荐表快照 X，当前 Y"
+   ├─ bare    命中但 primary_version=None（语音/音频类）→ 保留裸名，不拼版本；实际接入查该能力官方 API
+   └─ miss    词干完全无命中            → 表 id 可能陈旧；改用场景中文词或更短词干再 search
+④ 用 search 同 modality 结果补 2–3 个备选候选
+⑤ 用户点名第三方/开源/历史模型（Seedream 4.5、qwen、glm…）→ 跳过本表，直接 search，不强替
+```
+
+### 关键边界（实测得出，必读）
+
+- **不要把表里的 full-id 直接拼给 `+chat` / `+gen`，也不要凭记忆给模型名加后缀**。图片生成的真实模型就是 `doubao-seedream-5-0`（**没有 `-lite` 后缀，缓存里不存在带 `-lite` 的变体，硬查会返回 no items**）。这类命名漂移会反复发生——**用族名词干 search，永远以返回结果为准，不要自行补 `-lite` / `-pro` 等后缀**。
+- **search 容错 DisplayName**：`Doubao-Seed-2.0-lite`（带点号大小写）也能命中 `doubao-seed-2-0-lite`，但**族名词干（小写连字符）最稳**，优先用它当 search keyword。
+- **语音 / 音频 bare 路径**：目标记录的 `primary_version` 为空、ctx/lifecycle 未 enrich 时，保留本轮真实裸名（例如目录中的 `doubao-seed-tts-2-0`、`seedasr-streaming`），不猜版本和能力。TTS/ASR 等通常使用各自独立 API，不能直接套 Responses；用户要接入时引导核对该产品官方 API/SDK 的协议、模型标识与认证，未核实前不编 endpoint/请求体。arkcli 目录可搜不证明 `+chat` / `+gen` / 部署或用量支持；询价可转 `pricing models --modality Audio`，仅引用实际计价项，查不到就标未覆盖。
+- **避开 `-internal` 变体**：search 可能返回 `doubao-seed-2-0-lite-internal` 等内部变体，不要推荐给用户。
+- **lifecycle**：命中 `Retiring` 的候选要主动提示用户它在下线，并在同族找更新版本（与主 SKILL 一致）。

package/skills/arkcli-models/references/arkcli-models-search.md

@@ -0,0 +1,208 @@
+# models search
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+**Agent 优先**的模型搜索：召回 = 全量目录；enrich = ArkModels（context window / 模态 / capability）；filter = 结构化条件；rank = 4 桶 + context_window 加权 + 时序。**没有分页概念**，默认返回全部命中。
+
+只查询公共基础模型目录；Plan 支持清单用 `plans model-list --plan <plan>`，账号自定义资产用 `custommodel list/get`，当前身份可调用资源用 `resources list`。无命中先判资源类型，不跨 Profile 穷举，也不把当前公共目录未找到说成账号内不存在。
+
+## 空结果、规范化与证据冲突
+
+1. 用户给精确模型 ID/显式版本时先 `models get` 原值；不要把完整版本串当搜索关键词。模型名中的空格、点号或展示形式可作为检索线索规范化为连字符，但真正用于代码/部署的 ID 必须来自本轮 `name` 与版本字段，不凭字符串替换制造新 ID。
+2. 模糊查询用带引号的家族/名称关键词；先校验 `--capability` 的真实枚举，缓存条件使用 `--cache-type`。成功的 `items: []` 仅代表当前组合无命中；非零退出、缺 `.items`、JSON 损坏和截断都不是空结果。
+3. 在同一身份、资源范围内，先修正关键词；仍为空时可逐次只放宽一个**偏好**条件并说明变化，保留用户硬约束。放宽硬条件、身份、Project 或费用范围必须先询问。规范化后同一关键词加一次 `--include-deprecated` 可判断是否被下线过滤；不能在多个家族间盲猜。
+4. `--modality text` 表示文本**输出**，不是文本输入。图像/视频任务用对应输出模态或 `--input-modality text`；放宽后只剩 embedding/router/非目标任务的模型时，报告没有合适候选，不能把它们包装成任务推荐。
+5. 仅命中其他规格/变体时，分别报告“原请求未命中”和“当前候选”，不得静默替代。精确 get 报 NotFound 后，可按这一流程查候选，再用真实候选校正一次 get；仍失败则列尝试值与范围，保留未知，不循环。
+6. 只用本次输出陈述上下文、模态、生命周期和能力。缺失/null 是未知，不是 false。特定 API、参数支持或精确版本需读 [get](arkcli-models-get.md)；search 与 get 不一致且版本/范围未对齐时先核对，已明确同一 Name/Version/范围则直接保留冲突，不重复要求对齐或重查。分别标明来源，不取并集拼成新结论。`supported_params` 是正向证据，未列字段的运行时行为须查对应数据面契约或在授权后验证。
+7. 工具预览截断时先读其保存的完整文件；没有完整产物才把**同一只读查询**重新保存到私有临时目录。stdout/stderr 分开、检查退出码，再由 jq 提取字段；不吞 stderr，不逐行截断 JSON，也不因捕获失败直接终止可恢复的查询。
+
+## 未定模型时的实时候选模板
+
+开通/部署前的候选只来自本轮结果。已有完整结果就本地投影，不重查；初次可取 10 项留出退役过滤余量。下面命令按共享协议补全调用归因环境：
+
+```bash
+candidate_dir=$(mktemp -d)
+arkcli models search --size 10 --format json > "$candidate_dir/models.json" 2> "$candidate_dir/models.stderr"
+# 先检查上条退出码和 stderr；仅成功且 JSON 完整时继续
+jq -e '.items | type == "array"' "$candidate_dir/models.json"
+jq '[.items[]
+  | select(.lifecycle_status != "Shutdown" and .lifecycle_status != "Retiring")
+  | {display_name,name,primary_version,lifecycle_status,input_modalities,output_modalities,task_types,create_time,update_time}]
+  | sort_by([(.create_time != null), (.create_time // "")]) | reverse' "$candidate_dir/models.json"
+```
+
+模糊家族场景在 `search` 中加用户关键词。候选已知状态/关键字段缺失时标未知，不能把模板的过滤结果说成全都 Published 或可调用；需要新接入时仅推荐已证实未退役且满足目标任务者。
+
+无具体偏好时展示 5–8 个有证据的代表，优先保留不同文本、多模态输入、图像、视频任务选项；不是强凑名额：不足就如实列实际数，指定任务时不混入无关模态。`label` 保留真实 `display_name`，重复名在说明中附 `name/version` 区分，不改版本、不额外造“其他”选项。开通/部署候选默认按真实 `create_time` 倒序；用户明确要求最近更新时才用 `update_time`，缺时间标未知，不猜时间或用 context 排序冒充创建时间排序。候选选择回到 owning Skill；选模型不等于批准开通或创建。
+
+## 命令
+
+```bash
+# 基础
+arkcli models search                       # 全量按 UpdateTime 降序
+arkcli models search doubao                # 关键词（也可 --keyword doubao）
+arkcli models search doubao --size 5       # 显式截断到 5 条
+
+# 模态过滤（D3 必备）
+arkcli models search --modality video      # 视频生成模型
+arkcli models search --modality text       # 文本输出模型
+arkcli models search --modality image      # 图片生成模型
+arkcli models search --input-modality text,image --output-modality text  # VQA 类
+arkcli models search --multimodal          # 输入支持多模态的模型
+
+# 数值容量过滤
+arkcli models search --min-context-window 200000
+arkcli models search --max-context-window 1000000
+arkcli models search --min-input-tokens 100000
+arkcli models search --min-output-tokens 8192
+
+# 能力过滤（可重复，AND 关系）
+arkcli models search --capability thinking
+arkcli models search --capability mcp --capability functioncall
+
+# 缓存类别过滤（可重复，AND 关系）
+arkcli models search --cache-type implicit_cache
+arkcli models search --cache-type session_cache --cache-type prefix_cache
+
+# 复合查询：找最强 200K+ 思考型 LLM
+arkcli models search --modality text --min-context-window 200000 --capability thinking --strict-filter
+
+# 缓存控制
+arkcli models search --refresh-cache       # 强制同步刷新一次 ArkModels 元数据
+```
+
+## 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `[keyword]` / `--keyword` | string | 关键词。匹配 name / display_name / short_name / description / introduction 任一字段（小写不敏感）|
+| `--size` | int | **不传 = 不截断**（agent 默认拿全量）；显式传 N 则截断到 N |
+| `--modality` | string | 粗粒度别名：`text` / `image` / `video` / `audio`（输出模态简写）|
+| `--input-modality` | string | 显式输入模态过滤，逗号分隔（如 `text,image,video`）|
+| `--output-modality` | string | 显式输出模态过滤 |
+| `--multimodal` | bool | 仅返回输入模态数 ≥ 2 的模型 |
+| `--min-context-window` | int | 最小 context_window（tokens）|
+| `--max-context-window` | int | 最大 context_window |
+| `--min-input-tokens` | int | 最小 max_input_tokens |
+| `--min-output-tokens` | int | 最小 max_completion_tokens |
+| `--capability` | string（可重复）| 必备能力，多个为 AND：`thinking` / `mcp` / `functioncall` / `web_browsing` / `knowledge_base` / `response_format` / `reasoning_effort` |
+| `--cache-type` | string（可重复）| 必备缓存类别，多个为 AND：`explicit_cache` / `implicit_cache` / `session_cache` / `prefix_cache` |
+| `--strict-filter` | bool | 缺 enrich 数据的模型直接排除（默认保留，避免误杀）|
+| `--include-deprecated` | bool | 包含 `lifecycle_status=Shutdown` 或 `display_name` 含"废弃/下线"的模型（**默认过滤**，只保留可调用模型）|
+| `--refresh-cache` | bool | 同步刷新 ArkModels 元数据 cache（默认 stale-while-revalidate 异步刷新）|
+
+## 工作流程
+
+```
+search [keyword] [filters]
+   │
+   1️⃣  ListFoundationModels(全量, sort=UpdateTime DESC)
+   │   ↓ 152 个候选
+   2️⃣  EnrichWithMetadata
+   │   ├─ 读 cache: ~/.arkcli/cache/<profile>/<region>/<project>/arkmodels-meta.json
+   │   ├─ hit  → 立即返回 + fork detached 子进程异步刷新
+   │   └─ miss → 同步 ArkModels(IsPrimaryVersionOnly:true) → 写 cache
+   │       (无 SSO 时 enrich 静默跳过，filter 自动 no-op)
+   │   ↓ 各 item 补 context_window / input_modalities / output_modalities / capabilities
+   3️⃣  Modality 兜底：output_modalities 为空时按 task_types 推导
+   │   (TextToVideo → out=[video], VisualQA → in=[text,image] out=[text], ...)
+   4️⃣  关键词过滤（小写子串，匹配 name+display+short+description+intro）
+   5️⃣  结构化过滤（modality / context / tokens / capability / cache_type，AND）
+   6️⃣  4 桶重排 + (context_window desc, update_time desc, name asc) tie-break
+   7️⃣  --size N 截断（默认不截断）
+```
+
+## 返回字段
+
+每条 item：
+
+```json
+{
+  "name": "doubao-seed-2-0-pro",
+  "display_name": "Doubao-Seed-2.0-Pro",
+  "primary_version": "260215",
+  "update_time": "2026-03-02T...",
+  "foundation_model_tag": { "filter_task_types": [...], "task_types": [...] },
+
+  // —— enrichment（来自 ArkModels；SSO 失败时为 null）——
+  "context_window": 262144,
+  "max_input_tokens": 229376,
+  "max_completion_tokens": 65536,
+  "input_modalities": ["text", "image", "video"],
+  "output_modalities": ["text"],
+  "capabilities": {
+    "thinking": true, "mcp": true, "functioncall": true,
+    "web_browsing": true, "knowledge_base": true,
+    "response_format": false, "reasoning_effort": true
+  },
+  "cache_types": ["implicit_cache", "session_cache", "prefix_cache"]
+}
+```
+
+`capabilities.caching` 是旧版兼容字段，只表示 `caching.support`（即
+`explicit_cache`），不要再用于缓存能力判断。模型支持哪些缓存机制以
+`cache_types` 为准。`+chat --caching` 是发请求时的运行参数，与这里的模型能力字段无关。
+
+## 重要行为
+
+### 缺数据怎么办（StrictFilter）
+- **默认 `--strict-filter=false`**：`--modality video` 时，**没有** modality 数据的模型也会**保留**（agent 看到候选但置信度低）
+- **`--strict-filter`**：缺数据视为不满足，直接排除（agent 拿到的 100% 是 ground truth）
+
+模态查询通常加 `--strict-filter` 更准；数值查询（context window）保持默认（缺数据不杀）通常更合理。
+
+`--cache-type` 是精确过滤：只有 `cache_types` 明确包含所请求类别的模型才会返回；缺少缓存元数据的模型不会作为候选保留。
+
+### 召回不再有 top-K 限制
+不像旧版 fuzzy 接口默认 9 条，本命令默认返回**全部命中**。如需限制，传 `--size N`。
+
+### Cache 与 SSO
+- ArkModels 是 Console BFF 接口，需要 SSO 凭证
+- 无 SSO（AK/SK only）→ enrich 静默跳过，模型仍能返回，filter 自动 no-op
+- Cache 路径按 `(identity/account, profile, region, project)` 分；缺少权威 identity 时不启用持久缓存，避免跨账号复用
+- 默认 TTL 为 5 分钟，可通过 `ARKCLI_MODEL_CACHE_TTL` 调整；TTL 内只读本地缓存
+- TTL 过期后 stale-while-revalidate：当前调用先返回旧缓存，并由 detached 子进程刷新（`arkcli models _refresh-cache`）；同 scope 冷启动/刷新使用跨进程 single-flight
+- `auth logout` 与 fresh 账号切换会清除当前产品的全部模型缓存
+- 所有 ArkModels Action 都经过 transport 级账号隔离节流，最小间隔 250ms（约 4 QPS，为后端 5 QPS 留余量）
+
+### 关键词匹配范围
+- name / display_name / short_name（命中 → 重排第 1 桶）
+- description / display_description / introduction（命中 → 第 2 桶）
+- 子串匹配，**小写不敏感**
+- **不做语义/同义词扩展**
+
+### 重排细节
+| 桶 | 条件 |
+|---|------|
+| 1 | 非 hidden + name 命中 keyword |
+| 2 | 非 hidden + description 命中 keyword |
+| 3 | 非 hidden + 无 keyword 命中（兜底）|
+| 4 | hidden（`customized_tags` 含 `体验隐藏`/`推理隐藏`/`广场隐藏`，是火山方舟平台旧版页面隐藏标签，与本 CLI 命令无关）|
+
+桶内：`context_window` 大者优先 → `update_time` 新者优先 → `name` 字典序
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `--modality video` 返回大量噪声 | 默认 strict-filter=false，缺数据模型未排除 | 加 `--strict-filter` |
+| 数值过滤后结果意外 | 部分模型 ArkModels 没有 context_window | 接受默认保留（注意 ctx 为 null 的可能不准）|
+| 没有 thinking 模型 | --capability 默认非 strict，可能被噪声淹没 | 加 `--strict-filter` |
+| enrich 字段全为 null | 未 SSO 登录 | 运行 `arkcli auth login volc-sso` 重新建立 Volc 身份 |
+| 召回明显少于预期 | cache 旧；可能 ArkModels 暂时不可用 | 加 `--refresh-cache` 强制同步刷新 |
+
+## 与 `models list` / `models get` 的分工
+
+| 用例 | 推荐 |
+|------|------|
+| 用户给模糊关键词，找候选 | **`search`** ✓ |
+| 找最新发布的模型（time-sensitive） | **`search`**（结果按 update_time DESC）|
+| 按 modality / context / capability / cache type 找 | **`search`** + 对应 flag |
+| 全量枚举所有模型 | `search` 无 keyword（152 条全量）|
+| 按 name 收窄 | `list --name foo`（子串）或 `search "foo"`；精确身份验证用 `get` |
+| 拿单个模型的完整详情（计费、限流、能力位详细描述）| `get <name>` |
+
+## 参考
+
+- [arkcli-models](../SKILL.md) — models 全部命令
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,88 @@
+# arkcli-models evals
+
+## 账号开通盘点回归（Viking 163507）
+
+- 输入：还有哪些模型我没开通？怎么开通？同次查询中有 31 项 Available、1 项 Unavailable、2 项查询失败、2 项状态缺失。
+- 必须失败的输出：结尾说“其余均已开通”、把查询失败或缺失归入任一确定状态、用公共目录总数称账号权益全集，或只给控制台路径而漏掉真实 CLI 开通方法。4318 原题出现了前两类交付错误。
+- 通过条件：最终汇总与逐项状态一致，明确已确认、不可用、查询失败和未知的各自数量及范围；所报数量加总对应同一去重集合。全账号查询须完成权益接口分页并核对 TotalCount，不能把目录缺席等价为未开通。
+- 必须保留的正确契约：固定 CLI 的 `models get pricing.state` 来自 `ListModelChargeItems.Items[].State`，可以作为该项权益证据；不要因评分器未识别聚合层而否定该字段。区分账号全集与单项查询的覆盖范围。
+- 交付读取 help 后确认的 `models activate` 方式；只问方法时无真实 activate、无账号切换，未知/停服/受限项不套自助开通保证。
+
+## 覆盖目标
+
+- 模型搜索需求应使用 `arkcli models search`，避免用 `list` 做能力推荐。
+- 模型资产盘点需求应使用 `arkcli models list --page-all`，避免跳到 Raw API Explorer。
+- "最近 N 天自定义模型"转 `arkcli-custommodel` 查询账号资产，再按真实时间字段过滤；公共目录不能代替自传/精调资产。
+
+## Trigger / 该唤起
+
+- 用户明确问模型清单、模型详情、模型搜索、模型统计时，该唤起 `arkcli-models`。
+- 用户问自传/精调自定义资产或其创建时间时，转 `arkcli-custommodel`；公共基础模型目录盘点使用 `models list`。
+- Volc 用户问 TTFT/TPOT、模型性能排行、趋势或输入长度对比时，该唤起 `models performance` 路径。
+
+## Anti-trigger / 反唤起
+
+- 用户要直接聊天、生成、部署时，不该把 `arkcli-models` 当终点；只在缺模型名时短暂进入。
+- 用户明确要 Raw API Action、OpenAPI 列表或底层 params 时，不该用本 skill，应转 `arkcli-api-explorer`。
+- 用户问自己的 Endpoint 为什么慢时，转 `arkcli-doctor`，不得用公共性能榜单替代诊断。
+
+## Guard / 守卫
+
+- 认证失败、401、登录状态不明时，先检查 `arkcli auth status`。
+- profile、region、base URL 异常时，转 `arkcli-config` 做配置排查。
+- 缺少服务端时间过滤 flag 不是失败条件；先用本地 JSON 过滤，确认无法完成后再说明限制。
+
+## happy-path CLI 实测命令
+
+```bash
+arkcli models list --page-all --sort-by CreateTime --sort-order Desc --format json
+arkcli models search --modality text --min-context-window 200000 --capability thinking --strict-filter
+```
+
+## 回归用例
+
+| case | prompt | 期望 |
+|------|--------|------|
+| `uat-models-list-recent-custom-001` | 我在方舟最近 7 天建了多少个自定义模型？列下来。 | 转 `arkcli-custommodel`，按该 Skill 的真实账号资产命令和时间字段盘点；不从公共基础目录猜自定义资产 |
+| `models-list-owned-custom` | 帮我看一下我有哪些自定义模型，输出数量和模型名。 | 转 `arkcli-custommodel`，使用账号资产查询并检查完整分页 |
+| `models-search-task-fit` | 帮我找一个支持 thinking、上下文 200K 以上的文本模型用于 +chat。 | 使用 `arkcli models search --min-context-window ... --capability thinking` |
+| `models-search-speech-boundary` | 方舟广场有没有 TTS 模型？可以直接部署或生成示例代码吗？ | 使用 `arkcli models search <tts/语音关键词>` 做广场发现；明确说明语音模型当前不支持 `+deploy` / `+code-example` / usage / pricing / onboard；不得推荐 `+chat` 或 `+gen` |
+| `models-performance-rank` | 现在首 Token 最快的是哪个模型？ | Volc 使用 `arkcli models performance rank --metric ttft --format json`，说明公共数据和延迟。 |
+| `models-performance-endpoint` | 我的 ep-xxx 为什么慢？ | 不执行 performance；转 `arkcli-doctor`。 |
+
+## 模型详情价格迁移
+
+| case | prompt | 期望 |
+|------|--------|------|
+| `models-get-dimensional-price` | 这个已知模型的普通推理输入价格是多少？有不同上下文档位吗？ | 读取 get reference，用 `models get` 的 `pricing.prices`，按服务、计费项、维度和单位解释各档；不读旧 charge_items，不取第一条 |
+| `models-get-missing-price` | 价格返回 null 或空数组，是免费吗？ | 区分 null、空数组与 0；不推断免费、未开通或模型不存在，不回退旧接口价格 |
+| `models-get-entitlements` | 查价格，同时看看开通状态和免费额度。 | 新价格读 `pricing.prices`，状态和额度读原 `pricing.state` / `pricing.inference_free_usage`；互不推断 |
+| `models-unopened-evidence-163507` | 目录三个模型：无 EP 但 state=Available；state=Unavailable；state 缺失且无价格 | 分别报告已开通、权益不可用、未知；不能把无 EP 或空价格当未开通，也不能把 Available 当任意 API 均可调用 |
+| `models-retiring-explicit-163357` | 用户点名 Retiring 型号创建，未执行创建；对照实际 CreateEndpoint 返回 invalid status=Retiring（163500） | 前者保持精确目标交回 owning 创建 Skill，不凭目录先拒绝；后者如实报告真实服务拒绝，不强求成功、不静默换模型 |
+| `models-get-price-scope` | 指定版本和地域后，这就是该版本在该地域的价格吗？ | 说明价格按基础模型名、global 默认维度查询，不能从详情版本或 profile 地域推断专属报价 |
+| `models-client-image-163543` | 查询确认某模型为 text-only；用户说 Trae 图片报错，但没有客户端 body/抓包或文档；对照有实际 image_url 请求 | 前者只条件化说明输入能力和客户端核对点，不断言粘贴即自动发送图片；后者按真实 body 解释；已查证的模型能力/生命周期保持准确，失败的回复修改不当作已修正 |
+
+
+## 模型查询后的任务交接（Volc；Vaka 另核交付形态）
+
+下表中的参数与客户端写法以当前模型证据及 `arkcli-chat/references/caching-thinking.md` 为准。通用“必须路由到 models”判分只适用于纯模型查询；模型只是上游任务的一个输入时，必须返回该任务的 owning Skill。
+
+| case | 输入与对照 | 必须观察到的行为 | 必须失败的行为 |
+|------|------------|------------------|----------------|
+| `models-chat-parameter-handoff` | 只问某文本模型如何关闭思考；本轮已取得该版本完整参数目录与官方说明。对照：只问该版本是否支持思考。 | 前者加载 Chat 及 thinking reference，复用已有事实，解释适用协议、参数和客户端位置；后者由 Models 直接回答已知能力。仅在有模型证据时说明 minimal 替代，并区分 Chat Completions `reasoning_effort` 与 Responses `reasoning.effort`。 | 只查模型后结束、漏客户端透传位置、把未知取值当支持，或为纯解释调用真实推理。 |
+| `models-vaka-parameter-explanation` | Vaka 中用户只问参数含义或如何调整，Agent 为说明补一个 JSON 片段；对照：用户明确要求一份新 Python/cURL/SDK 接入示例。 | 前者直接解释和配置片段，必要时说明 OpenAI SDK 的 `extra_body` 位置；后者继续读取 Vaka UI 路由及对应卡片契约，交付真正的新示例。 | 因自己补了 JSON 就推断用户要接入卡，或把本规则理解为所有 SDK 示例均禁止出卡。 |
+| `models-existing-sdk-request-repair` | 用户提供现有 SDK 调用和字段位置报错，只要求修复该段；对照：要求执行一次真实调用。 | 前者返回 Chat，保留原客户端与协议，仅纠正有依据的字段位置；后者由 Chat 执行其认证与调用边界。 | 为参数修复创建 Key/Endpoint、切账号、发收费探测，或未经证据把某 SDK 的签名套到另一 SDK。 |
+| `models-query-owner-paths-unchanged` | 纯模型目录/版本/能力查询；另有普通 Endpoint 创建及显式 raw CRUD 创建。 | 纯查询仍由 Models；两类创建分别回到 Deploy 与 Infer Endpoint，保留既有有界只读查询和写操作守卫。 | 将任何提到“模型”的请求都转给 Chat，或让新规则绕过创建 owning Skill。 |
+| `models-other-modality-paths-unchanged` | 为图片/视频生成挑模型或查询语音能力；对照：文本对话 API 参数问题。 | 图片/视频保持 Gen 上游任务；语音保持当前能力边界并核对相应官方接口；只有文本对话/Chat Completions/Responses 用法交给 Chat。 | 将多模态生成或独立语音服务套进 Chat/Responses 参数流程。 |
+
+验收同时看实际 Skill/reference 读取、完整工具轨迹、最终答案和出卡结果；挂载了文件、静态评分通过或模型自述均不能替代上述行为证据。评分时保留原题与原判分器，不能把原问题改成提示路由的简化题。
+
+## 判分重点
+
+
+- 必须路由到 `arkcli-models`。
+- 资产盘点必须推荐 `arkcli models list`，优先带 `--page-all` 和 `--format json`。
+- 时间过滤必须说明客户端过滤或本地 JSON 处理。
+- 不得推荐 `arkcli api --list` 作为首选路径。
+- 不得因为缺少服务端时间 flag 就说 CLI 无能力或让用户去控制台。
+- 语音模型命中后必须停在广场发现层，不得继续推荐部署、示例、用量或费用查询。