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

package/skills/arkcli-doctor/references/scope-model.md

@@ -0,0 +1,241 @@
+# `arkcli doctor model`（单模型诊断）
+
+> 这是 [`arkcli-doctor`](../SKILL.md) 的 **model domain reference**。当用户/Agent 拿到一个**模型名**（如 `doubao-pro-32k` / `doubao-seedance-1-0-pro`），问『这模型整体怎么样 / 限流是模型级还是接入点级 / 哪个 endpoint 把模型配额吃了 / 模型级 RPM/TPM 配额还有多少 / 生视频的排队压力 / 生视频生成耗时分布 / LLM 首 token 慢吗 / 模型在跨接入点维度上整体出错严重吗』时读这里。
+>
+> **CRITICAL — 开始前 MUST 先用 Read 工具读取**：
+> - [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序）
+> - [`../SKILL.md`](../SKILL.md)（doctor 总入口与路径决策表）
+
+## 它解决什么
+
+`arkcli doctor model <model-name>` 是把"这个模型在我账号下整体什么情况"答出来的命令——modality、endpoint 总数与状态、用量、错误率、模型级配额压力、按模态自适应的延迟与生成时长指标，一屏看清。**关键定位**：跨接入点的聚合视角，不是单 endpoint。
+
+| 用户场景                                              | Agent 跑什么                                                                 |
+|------------------------------------------------------|------------------------------------------------------------------------------|
+| 「`doubao-pro-32k` 整体怎么样」                       | `arkcli doctor model doubao-pro-32k`                                         |
+| 「我的生视频模型卡了」                                | `arkcli doctor model <video-gen-name>`（重点看 queue_time + gen_time + 配额）|
+| 「为什么模型报 `ContentRiskBlocked` / 大量 ModelAccessDenied」 | 同上 + 按 top error code 加载错误码 reference                       |
+| 「seed-2.0 模型限流是多少 / 怎么提配额」              | `arkcli doctor model <name>` + 提配额引导                                    |
+| 「哪个 endpoint 把这个模型的配额吃光了」              | `arkcli doctor model <name>` 看 top endpoint by usage                        |
+| 「跨接入点对比错误情况」                              | 同上看 top endpoint by error rate                                           |
+
+## 边界：不做什么
+
+- 不替代单接入点级诊断（"`ep-xxx` 为什么 429"）—— 走 [`scope-infer-endpoint.md`](scope-infer-endpoint.md)
+- 不替代单条请求 trace（暂无 request 粒度反查）
+- 不读跨账号大盘 / 不跨账号横比
+- 不替代用户 SLO 评价（"50ms 算不算慢"由用户自己设 target）
+- 不做效果评估和改进建议（"我的模型效果如何 / 怎么改进"——本 reference 只看运行健康度）
+
+## 第一步：跑诊断
+
+```bash
+arkcli doctor model <model-name>
+# 自定义时间窗（默认 24h）：
+arkcli doctor model <model-name> --window 1h
+# JSON 输出：
+arkcli doctor model <model-name> --format json
+```
+
+> 调用决策树（doctor 内部）：
+> ```
+> model exists?
+>   ↓ no  → fail，让用户检查模型名拼写或换 profile region
+>   ↓ yes  → 拿到 modality（LLM / 生图 / 生视频 / ...）
+> VMP preflight 通过?
+>   ↓ no  → blocking_dependency.vmp.* → 引导 account scope 修 VMP 三段
+>   ↓ yes
+> 查 VMP（按 modality 选 PromQL）：
+>   通用：error_count + count_total + qps_peak + tpm_peak (或 ipm_peak)
+>   modality-specific：见下表
+> → doctor 侧算 error_rate + 配额压力 + top endpoint → 错误码 enrich + 输出
+> ```
+
+> 如果 VMP preflight 失败（doctor 输出 `error.blocking_dependency.vmp.*`），先去修账号级的 VMP 三段授权——由 `arkcli doctor account` 输出引导，配合 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) / [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md) 处理。VMP 没通的时候模型性能段拿不到数据。
+
+## 第二步：读输出（6 段）
+
+### ① 模型基础信息
+
+| Check ID                | 看什么                               | 解读                                                             |
+|-------------------------|--------------------------------------|------------------------------------------------------------------|
+| `model.exists`          | 模型存在 + **modality 识别**          | modality 决定后面看哪些专属指标——必读，没有这个其它都是无用功     |
+| `model.source`          | 平台基础模型 / 自传 / 精调            | 自传或精调（`cm-xxx`）走的代码路径与基础模型略有不同，问题排查时区分 |
+
+> 不存在 → fail。让用户核对模型名（`arkcli models list` / `arkcli models custommodel list`）或换 profile region。
+
+### ② 接入点分布
+
+| Check ID                                | 看什么                                                                   |
+|-----------------------------------------|--------------------------------------------------------------------------|
+| `model.endpoint_total`                  | 当前模型下接入点总量                                                     |
+| `model.endpoint_state_distribution`     | 状态分布占比：`Running` / `Failed` / `Pending` / ...                     |
+| `model.top_endpoint_by_usage`           | Top 5 接入点按调用次数排（用量"吃料"分析）                              |
+| `model.top_endpoint_by_error_rate`      | Top 5 接入点按错误率排（错误集中分析）                                  |
+
+**用 top endpoint 干嘛**：
+
+- **用量集中**：一个 endpoint 占了模型用量 70%+ → 配额压力主要由它产生，提配额前看是否能客户端分流
+- **错误集中**：一个 endpoint 错误率远高于其它 → 不是模型问题，是该 endpoint 的配置 / 上游问题，跳到 [`scope-infer-endpoint.md`](scope-infer-endpoint.md) 单查那个 ep
+- **均匀分布**：所有 endpoint 错误率都高 → 模型级问题（账号未开通 / 模型配额撞顶 / 平台侧故障）
+
+### ③ 用量统计
+
+| Check ID                  | 看什么                                          |
+|---------------------------|------------------------------------------------|
+| `model.usage`             | 调用次数 + token 用量（input / output 分开），1h 与 24h 双窗口 |
+
+仅展示，不告警。但与配额压力（§⑤）、错误率（§④）联动判断"是不是真的需要提配额"。
+
+### ④ 错误率与错误码分布
+
+| Check ID                  | 看什么                                                                     |
+|---------------------------|---------------------------------------------------------------------------|
+| `model.error_rate`        | 错误率（按模态分流，与 `quota_pressure` 同款思路；默认阈值 5% warn）。LLM (`base_model` 维度) / 生图 (`base_model` 维度，注意 `model_service_type` 是服务类型 i2i/t2v/r2v 等不是模型名) → `overall.rate_percent`；生视频 → `request.rate_percent`（CreateContentGenTask 调用，`ark_model` 维度）+ `task.rate_percent`（异步任务执行，`foundation_model_name` 维度，从成功率取 `1 - rate`）|
+| `model.errors`            | 错误码分布（按模态分流，与 `error_rate` 同款思路）。LLM/生图 → `errors.overall.by_error_code[]`（`code` + `http_status_code` 拆桶；LLM 用 `code` 标签，生图用 `volc_error_code`，统一成 `code` 字段）；生视频 → `errors.task.by_error_code[]`（仅任务执行失败，无 `http_status_code` 维度，tmp.md 没给请求侧分布 PromQL） |
+
+主导错误码 → 加载对应错误码 reference（[`error-codes.md`](error-codes.md)）。常见路由：
+
+| 主导错误码                                     | 加载                                                                                                                |
+|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| `ModelAccessDenied` / `ModelNotOpen` / `AccessDenied` | [`error-codes.md` §1.2](error-codes.md#12-modelaccessdenied)                                                  |
+| `RateLimitExceeded.*` / `ModelAccount{Rpm,Tpm,Ipm}…` | [`error-codes.md` §1.3](error-codes.md#13-ratelimitexceeded)                                                  |
+| 生视频 `Output*SensitiveContentDetected*`       | [`error-codes.md` §1.1.4 / §1.1.5](error-codes.md#11-生视频特有seedance)                                            |
+| 其它                                          | `arkcli doctor error <code>` 查表，按返回的 `subtype` 跳节                                                          |
+
+### ⑤ 模型级配额压力
+
+| Check ID                          | 看什么                                                                              |
+|-----------------------------------|------------------------------------------------------------------------------------|
+| `model.account_quota_pressure`    | 账号下该模型的 RPM / TPM / IPM 实际峰值 vs 配额上限                                  |
+
+**阈值**（与 [`../SKILL.md`](../SKILL.md) "配额压力阈值"段一致）：
+
+| 占比      | severity | 表现                                |
+|-----------|----------|-------------------------------------|
+| `≥95%`    | fail     | 已经/即将限流，立即提配额           |
+| `≥80%`    | warn     | 高压，建议提配额或调流量分布         |
+| `≥50%`    | info     | 健康但有空间                         |
+| `<50%`    | pass     | 充裕                                 |
+
+**模型级 vs 接入点级判定**（与 §② top endpoint 联动）：
+
+```
+模型级配额压力高（≥80%）?
+ ├─ 是 ──► 哪些 endpoint 吃料?
+ │         ├─ 一两个 endpoint 占大头 → 客户端 sharding，把流量分给其它 endpoint；分不开再提配额
+ │         └─ 流量均匀 ──► 真的需要提配额
+ └─ 否 ──► 限流是单 endpoint 自己的事，跳到 doctor infer-endpoint 看那个 ep
+```
+
+### ⑥ 模态专属指标（按 § ① modality 自适应）
+
+doctor 拿到 modality 后追加专属 check 段。**首先看 § ① 的 modality 字段**，然后只关注那个模态的指标：
+
+| Modality   | 主指标                                                          | 看什么                                                  | 用于                                          |
+|------------|----------------------------------------------------------------|---------------------------------------------------------|-----------------------------------------------|
+| **LLM**    | `model.ttft.{p50, p99}`                                         | 首 token 延迟分位                                       | 流式对话 UX 核心                              |
+|            | `model.tpot.{p50, p99}`                                         | 每 token 延迟分位                                       | 长文输出体验                                  |
+| **生图**   | `model.gen_time.{avg, p99}`                                     | 平均生成时间 / p99（无 TTFT/TPOT 概念）                 | 生图主指标——慢就是这个数大                    |
+| **生视频** | `model.queue_time.{avg, p99}`                                   | 平均排队时长 / p99                                       | **生视频独有**：GPU/TPU 紧张时排队是主延迟    |
+|            | `model.gen_time.{avg, p99}`                                     | 排队后实际生成耗时                                       | 与 queue_time 拼起来才是端到端                |
+|            | `model.video_duration_distribution`                             | 生成时长分布（5s / 10s / 30s 等）                       | 计费 + 业务行为画像                           |
+
+**怎么解读**：
+
+- **LLM `ttft.p99` 慢**：通常与 QPS 同步上升 = 拥塞；与 QPS 无关的尖峰 = 上游 / 下游某次抖动；持续偏高 = 模型 / 版本变化
+- **LLM `tpot.p99` 慢**：长文体验差，用户感觉"打字越来越慢"
+- **生图 `gen_time.p99` 慢**：生成本身慢；看是否所有 endpoint 都慢（模型问题）还是个别 endpoint（resource starve）
+- **生视频 `queue_time.p99` 高 + `gen_time.p99` 正常**：GPU 紧张，排队是主延迟。提配额或换时段
+- **生视频 `gen_time.p99` 高但 `queue_time` 正常**：模型 / 输入复杂度变了（如分辨率提高 / 视频时长变长）
+- **生视频 `video_duration_distribution`**：业务结构画像。30s 视频占比高 → 计费 + GPU 占用都重；可与用户讨论是否切短
+
+> doctor 输出里如果某段缺失（比如 ttft / tpot 当前未提供），如实告诉用户该指标暂不可用，**不要假装能给数字**。
+
+## 第三步：聚合 vs 原始时序（跨 endpoint 维度）
+
+doctor 默认输出聚合统计值；底层是 VMP Prometheus 时序流，必要时拿原始时序做更深分析。**模型级**的原始时序与单 endpoint 的有差别——它聚合了所有 endpoint 的流量，能告诉你**跨 endpoint 的时间格局**。
+
+> 当前 `doctor model` 只返回聚合结果，不提供原始时序切换参数。用户确实需要按时间点分析时，转到 [`scope-metrics.md`](scope-metrics.md) 核对具名查询或 raw 查询能力；不要承诺本命令会返回 `series.<metric>[]`。
+
+### 决策规则
+
+| 用户问什么                                              | 用哪种            | 原因                                                         |
+|--------------------------------------------------------|-------------------|--------------------------------------------------------------|
+| 「模型整体怎么样」                                     | 聚合（默认）      | 一个数判断"要不要进一步查"                                  |
+| 「错误是哪个时段集中爆发的」                            | 原始时序          | 聚合把尖峰平均掉了                                          |
+| 「`<endpoint>` 是从什么时候开始吃模型配额的」          | 原始时序（按 endpoint 维度） | 看具体 endpoint 流量曲线 vs 总量                          |
+| 「模型升级 / 切换流量后效果变化」                       | 原始时序          | 与变更时间点对齐找因果                                       |
+| 「业务高峰时段是什么时候 / 是否周期性」                 | 原始时序          | 看曲线形状判断是否周期、是否需要提前扩容                    |
+
+### 跨 endpoint 时序模式 → 推断
+
+| 模式                                                                   | 推断                                                                         |
+|------------------------------------------------------------------------|------------------------------------------------------------------------------|
+| 一个 endpoint 流量稳步上升、其它平稳                                  | 业务方有新功能上线带量；如果模型级配额因此撞顶，提前规划                     |
+| 多个 endpoint 同时段错误率上升                                          | 模型 / 平台侧问题（不是 endpoint 配置问题）                                  |
+| 一个 endpoint 错误率周期性高、其它正常                                  | 该 endpoint 的客户端有定时任务或异常重试                                    |
+| `queue_time` 跨所有 endpoint 同步上升                                   | GPU 池资源紧张（所有 endpoint 共用）；提配额或换时段                        |
+| `tpm_peak` 长期 50-70% 偶尔顶 95%                                       | 业务有脉冲；副本数够但单副本会撞顶                                          |
+
+> 给用户的输出里**不要直接贴一长串原始时序数据**。多模态 agent 应该消化时序后给一句结论性描述（"错误集中在 14:05-14:08，主要由 endpoint `ep-xxx` 贡献"），并附前后聚合对比。
+
+## 常见 Finding → 修复路径
+
+| Finding                                                                  | severity | 修复方向                                                                                |
+|--------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------|
+| 模型不存在 / `model.exists = fail`                                       | fail     | 让用户核对模型名 / profile region                                                       |
+| 模型级 RPM/TPM/IPM ≥95%                                                  | fail     | 见 [`error-codes.md` §1.3](error-codes.md#13-ratelimitexceeded) 修复 A：提配额          |
+| 模型级配额 80-95% + 流量集中在 1-2 个 endpoint                            | warn     | 客户端 sharding 分流；不必立即提配额                                                    |
+| 主导错误码 `ModelAccessDenied`                                           | fail     | 加载 [`error-codes.md` §1.2](error-codes.md#12-modelaccessdenied)：账号未开通该模型 / 子账号缺权限 |
+| 主导错误码 `ContentRiskBlocked` / `Output*SensitiveContentDetected*`     | warn     | 加载 [`error-codes.md` §1.1.x](error-codes.md#11-生视频特有seedance)（生视频专属）       |
+| 一个 endpoint 错误率远高于其它（>10x）                                    | warn     | 跳 [`scope-infer-endpoint.md`](scope-infer-endpoint.md) 单查那个 ep                     |
+| 生视频 `queue_time.p99` 高 + `gen_time.p99` 正常                          | warn     | GPU 紧张：提配额或换时段；客户端可加重试退避                                            |
+| 生视频 `gen_time.p99` 持续偏高 + 业务无变化                                | info     | 模型 / 版本变化或输入复杂度上升；与业务方核对近期 prompt / 视频时长是否调整              |
+| LLM `ttft.p99` 持续偏高                                                  | info     | 当前未提供延迟指标时不要假装；如指标提供，看是否与 QPS 同步                              |
+
+## 给用户看的话术
+
+读完输出后按以下顺序：
+
+1. **整体结论一句话**：modality + 总用量 + 错误率水平 + 配额压力等级
+2. **关键问题**：摘最关键的 finding（fail 优先；多 fail 按 error_code Top 排），并附**一条**已加载好的 error reference 里的修复方案
+3. **跨 endpoint 上下文**：top endpoint by usage / by error rate 给一行——是不是某个 endpoint 主导了模型级问题
+4. **下一步建议命令**：执行类（重新 deploy / `+gen` 重试）的命令**先给用户看、等确认**，不替按
+
+## 安全与边界
+
+- **只读优先**：`arkcli doctor model` 默认只读，不消耗推理 token、不重新发请求
+- **修复路径由输出与 reference 给出**：例如提配额工单引导；doctor 进程不直接调 IAM / 改控制面
+- **越权边界**：只读用户 AK/SK 能拿到的 Ark API + VMP 数据；不读平台内部 trace / 调度数据；不跨账号横比
+
+## 何时 _不_ 用本 reference
+
+- 单接入点报错 / 慢 / 状态异常 → [`scope-infer-endpoint.md`](scope-infer-endpoint.md)
+- 账号级问题（实名 / 欠费 / IAM 策略 / VMP 三段）→ `arkcli doctor account` + [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)
+- 想看用量明细（不带"为什么 / 异常"判断）→ [`../../arkcli-usage/SKILL.md`](../../arkcli-usage/SKILL.md)
+- 想看模型基础元信息（参数 / 价格 / 支持参数）→ [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md)（公共模型）
+- 想给模型提升配额（明确意图 + 知道要多少）→ 直接走控制台工单流程；本 reference 只诊断 + 引导
+
+## Seedance 2.x 效果问题上报路由
+
+用户只描述 Seedance 2.x 效果问题，或**同时要求检查 / 诊断 / 排查 / 分析原因和上报**时，必须先完整执行本 `doctor model` 诊断，不能直接转 `doctor report`。诊断意图优先于上报意图；只有不含任何诊断诉求的纯上报请求才可能走 `scope-report.md` 的 Path B。诊断输出里的 `report_suggestion.model_supported=true` 只表明模型落在客户端已知的 seedance 2.x 家族前缀内（`doubao-seedance-2-*`），是**诊断后的发现提示**；家族内该具体版本是否受理、以及 task 的存在性 / 归属 / 完成状态 / 重复提交都由服务端校验（见 `reason` 字段）。是否询问用户由 agent 二次判定，按下面这张分流表来：
+
+| 用户诉求 / 诊断信号                                                             | 是否属于"效果类" | agent 行为                                                       |
+|--------------------------------------------------------------------------------|------------------|------------------------------------------------------------------|
+| 角色 ID 漂移 / 字幕拼写错 / 水印 / 风格漂移 / 闪烁 / 拼接跳变 / 角色重复 / 音频尾部杂音 / 中文发音错 / 音色参考错 | ✅ 效果类        | **完成本次诊断后**一句话意向探询；用户明确同意才参数收集并跑 report |
+| 视频生成失败 / task expired / 429 / ModelAccessDenied / ContentRiskBlocked / 用量高 / 错误率高 | ❌ 错误码 / 运行类 | **不要**提上报，按错误码分布 / [`error-codes.md`](error-codes.md) 处理 |
+| 用户没有描述具体问题（"看看这个模型"）                                          | 未知             | **不要**主动提上报，先看诊断输出再决定要不要追问                     |
+
+判定原则：**上报接口只处理"生成成功但效果差"的 case**——服务端 case-platform 会异步拉视频 / 输入帧做效果分析，对失败或不受支持模型的 task 会拒绝。所以诊断建议依赖**用户原始诉求 + doctor 输出的 error_rate / errors 分布**，而不是 `model_supported` 一个 bool；错误码路径与 badcase 路径互斥。
+
+**分工原则**：Agent 层做**一句话意向探询 + 参数收集**（不做仪式感的重复确认），CLI 层弹**结构化 prompt** 做唯一决定性确认。**不要**替用户擅自上报，也不要伪造 task_id。上报流程、命令细节、11 个 badcase_type 枚举都在 [`scope-report.md`](scope-report.md)。
+
+## 参考
+
+- [`../SKILL.md`](../SKILL.md) — 总入口与路径决策
+- [`scope-infer-endpoint.md`](scope-infer-endpoint.md) — 单接入点诊断（联动看具体 ep）
+- [`scope-report.md`](scope-report.md) — seedance 2.x 效果问题上报（badcase report）
+- [`error-codes.md`](error-codes.md) — 错误码总册（含 §1.2 ModelAccessDenied / §1.3 RateLimitExceeded / §1.1 生视频）
+- [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) — 共享执行协议
+- [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md) — 模型元信息查询

package/skills/arkcli-doctor/references/scope-report.md

@@ -0,0 +1,242 @@
+# scope-report — Seedance 2.x 效果问题上报（badcase report）
+
+> 这是 [`arkcli-doctor`](../SKILL.md) 的 **report scope reference**。只有两种情况读这里：① `doctor model` / `doctor infer-endpoint` 已返回 `report_suggestion`，确认是 Seedance 2.x 效果类问题，需要向用户询问是否上报；② 用户已经明确要求“直接上报 / 提交 badcase / 反馈到方舟”，**没有同时要求检查、诊断、排查或分析原因**，且上下文确认是 Seedance 2.x 效果类问题。**只描述效果差，或同时要求先诊断再上报时，不得直接进入本 scope，必须先走 model / infer-endpoint 诊断。**
+>
+> **CRITICAL — 开始前 MUST 先用 Read 工具读取**：
+> - [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序）
+> - [`../SKILL.md`](../SKILL.md)（doctor 总入口与路径决策表）
+
+## 它解决什么
+
+火山方舟 Seedance 2.x 家族（当前家族包括 `doubao-seedance-2-0-260128` / `doubao-seedance-2-0-fast-260128` 等已知版本，具体清单以服务端为准）在生视频时可能命中效果类问题：角色 ID 漂移、字幕生成错、水印、风格漂移、闪烁、拼接跳变、角色重复、音频尾部杂音、中文发音错、音色参考错等。方舟平台为这些**效果类问题**（不是错误码 / 生成失败）提供了**badcase 上报**接口，把 task_id 送到排障平台异步分析。
+
+`arkcli doctor report` 就是这一步的执行入口。
+
+| 用户场景                                                        | Agent 跑什么                                                                                       |
+|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
+| 「我这次 seedance 2.x 生成的视频角色脸变形了 / 字幕拼错了」     | **未明确说上报，不直达 report**；有模型名走 `doctor model`，有 ep-id 走 `doctor infer-endpoint`        |
+| 「先检查这次 seedance 2.x 字幕错的原因，再帮我上报」           | **诊断意图优先**；先走 `doctor model` / `doctor infer-endpoint`，完成后按 Path A 询问并上报             |
+| 「帮我上报下这次 seedance 2.x 字幕错的 badcase / 提交到方舟」   | **明确上报**；确认家族 + 效果类门槛后，按 Path B 参数收集并直达 `doctor report`                       |
+| 「刚跑完 doctor model seedance-2-0，看到 report_suggestion」    | 按 Path A 二次分流；确认是效果类后询问用户，用户同意才进入 `doctor report`                            |
+| 「seedream-4-0 生图效果不对，能上报吗」                          | ❌ **不属于本 reference** —— 只覆盖 seedance 2.x 家族视频，生图 / 1.x seedance 一律不能上报，转告用户 |
+| 「seedance 生视频报了 60002 / 429 / expired」                    | ❌ **不属于本 reference** —— 错误码类走 [`error-codes.md`](error-codes.md)，不走 badcase 通道       |
+
+> 边界：**只覆盖 Seedance 2.x 家族**（客户端按前缀 `doubao-seedance-2-` 匹配触发建议），家族内某个具体版本受不受理由服务端 60002 判定；家族外的 task 提交会被服务端 60002 拒绝。
+
+## 触发条件
+
+`doctor report` 只有以下两个合法入口。无论哪条入口，**执行 report 时都必须已经有用户明确的上报意图**：Path A 的意图来自诊断后的询问与用户确认；Path B 的意图来自用户原始请求。**诊断意图始终优先于上报意图**：用户同时要求“检查 / 诊断 / 排查 / 分析原因 / 看健康 / 看指标”和“上报”时，必须先走 Path A 的上游诊断，不得直达 Path B。
+
+**Path A — 上游 doctor 诊断完成后的上报确认（保留 model / infer-endpoint 检查链路）**
+
+跑 `arkcli doctor model doubao-seedance-2-0-260128` 或 `arkcli doctor infer-endpoint <ep-id>`（endpoint 关联的 model 命中 seedance 2.x 家族前缀）时，输出 JSON 里会浮出：
+
+```json
+{
+  "report_suggestion": {
+    "model_supported": true,
+    "reason": "doubao-seedance-2-0-260128 落在 seedance 2.x 家族内, 可尝试 badcase 上报; 具体 task_id 是否可受理由服务端校验",
+    "model_name": "doubao-seedance-2-0-260128",
+    "supported_models": ["doubao-seedance-2-*"],
+    "docs": "https://www.volcengine.com/docs/82379/2389900",
+    "report_command": "arkcli doctor report --task-id <cgt-xxx> --feedback \"<问题现象描述>\" [--badcase-type <enum>]"
+  }
+}
+```
+
+Path A **必须以真实执行过 model / infer-endpoint 诊断并拿到上述字段为前提**，不得根据用户一句“效果不好”自行虚构 `report_suggestion` 或跳过诊断。`model_supported=true` 只表示诊断到的模型落在客户端已知的 seedance 2.x 家族前缀内；`supported_models` 是 pattern 提示（如 `doubao-seedance-2-*`），**不是穷举白名单**；家族内某个具体版本是否受理、以及具体 `task_id` 的存在性 / 账号归属 / 完成状态 / 重复提交，**全部由服务端校验**（见 `reason` 字段）。**不得把 `model_supported=true` 解释成某个具体 task 已通过资格校验。** 是否建议上报仍由 agent 二次分流：
+
+1. **判定问题类别**（agent 结合用户原始诉求 + 诊断输出的 error_rate / errors 分布）
+   - ✅ **效果类**：角色 ID 漂移 / 字幕生成错 / 水印 / 风格漂移 / 闪烁 / 拼接跳变 / 角色重复 / 音频尾部杂音 / 中文发音错 / 音色参考错 —— 走本 reference
+   - ❌ **错误码 / 运行类**：task 失败 / 429 / ModelAccessDenied / ContentRiskBlocked / expired / 状态异常 / 错误率高 —— 走 [`error-codes.md`](error-codes.md)，**不要**提上报
+   - ❓ **未知**：用户没描述具体现象 —— 先看诊断输出，可以追问用户"是效果不对还是接口报错"，**不要**主动提上报
+
+2. **判定为效果类后，用一句话告知用户此通道**（意向探询，不是仪式感的确认门）：
+
+   > "这类效果类问题可以上报到方舟让排障团队分析，需要我帮你上报吗？"
+
+   用户表达意向后即可进入下一步；如果用户没兴趣说"算了"，自然结束。**不要**在这一步做仪式感的"确认要上报吗 [y/N]"式反复追问 —— 决定性确认由 CLI 层完成。
+
+3. **进入参数收集**（自然对话，不算确认）：agent 从用户上下文里做**参数意图识别**（见下方"参数意图识别契约"段），能识别到的字段直接带上；必填字段（task_id / feedback）识别不到才向用户追问，可选字段识别不到就**不带**、**不问**。参数齐后**告知用户即将执行的命令**（预告，让用户知道 CLI 还会弹一次结构化确认让他核对参数），然后直接跑 `arkcli doctor report`。
+
+4. **CLI 层弹出结构化确认**（唯一决定性确认）：CLI 会打印合规声明 + 本次实际外发的参数列表 + 是否上报？[y/N]，由**用户点头**才真发请求。**Agent 不需要模拟或预知 CLI 输出**——拼好命令跑就行，实际文案见运行结果。**不要**替用户擅自上报，也不要伪造 task_id。
+
+> 为什么把决策集中到 CLI 层：case-platform 只处理"生成成功但效果差"的 case，服务端会异步拉视频 / 输入帧做效果分析。对失败 task（task 未 completed）上报会被 40004 拒；对非 seedance 2.0 会被 60002 拒。错误码 / 运行类问题走上报是浪费用户时间。Agent 层做一次意向探询 + 参数收集，让 CLI 结构化 prompt 承担唯一决定性确认，避免重复问同一个问题。
+
+**Path B — 用户只要求直接上报且没有诊断意图（唯一允许跳过 model / infer-endpoint 诊断的直达路径）**
+
+用户直接说"这次 seedance 2.0 效果不对，帮我上报"、"提个 badcase"、"上报到方舟"，且没有要求先检查、诊断、排查或分析原因时，才可能进入 Path B。若用户说“先检查为什么字幕错并上报”或任何同义混合请求，必须先走 `doctor model` / `doctor infer-endpoint`，完成诊断后按 Path A 处理。进入 Path B 后，agent **不能只凭意图关键词就抽参数跑命令**；必须先从对话上下文里确认两个门槛条件，缺哪个哪个追问，明显不符合的直接拒绝并转告边界：
+
+1. **家族门槛 —— 模型是 seedance 2.x 家族**（`doubao-seedance-2-*` 前缀，含 fast 变体）：
+   - 用户明说 seedance 2.x / 2.0 / 2.1 / `doubao-seedance-2-*` 系列模型 → 门槛过
+   - 用户没提模型 / 只给 task_id → **追问**："这个 task 是哪个模型跑的？（本通道只覆盖 seedance 2.x 家族）"
+   - 用户明说 1.x / seedream / 其他视频模型 → **拒绝**："这条通道只覆盖 seedance 2.x 家族视频；你这个是 xxx，走 `arkcli doctor model` / 反馈原路径"
+2. **效果类门槛 —— 问题是效果类**（角色漂移 / 字幕错 / 水印 / 风格漂移 / 闪烁 / 拼接跳变 / 角色重复 / 音频尾部杂音 / 中文发音错 / 音色参考错等）：
+   - 用户描述里明显是效果类现象 → 门槛过
+   - 用户没描述具体现象 / 只说"上报 badcase" → **追问**："具体是效果不对（比如角色变形、字幕拼错）还是接口报错（比如 429 / task expired）？"
+   - 用户描述是错误码 / 运行类（生成失败 / 429 / expired / ContentRiskBlocked 等） → **拒绝**："错误码类不走 badcase 通道，请走 `arkcli doctor error <code>` 或 [`error-codes.md`](error-codes.md)"
+
+两个门槛都过后，才进入下方"参数意图识别契约"抽 task_id + feedback + 可选字段，跑 `arkcli doctor report`。**agent 不能靠"上报"关键词单独触发** —— 意图 + 家族 + 效果类三个信号都得凑齐，缺哪个追问哪个，明显不符的直接拒绝转告。
+
+> 为什么不再"信任意图直接提交": 之前设计相信"服务端 60002 兜底"就够, 但会把用户带进"我要上报 → 提交 → 被 60002 拒 → 才知道通道不覆盖"的绕行, 浪费一次交互。前置两门槛让 agent 提前告知用户边界, 用户少走弯路。同时 CLI 层不做客户端家族闸门 —— 门槛只在 agent 层, 服务端仍是最终权威。
+
+## 参数意图识别契约
+
+Agent 应从用户自然语言 / 命令上下文里对 **6 个 CLI 参数**全部做意图识别，识别到就带上；用户明确指定了值（直接写 flag 或明确说"用 xxx"）以用户为准。缺失时按下表处理：
+
+| CLI flag | 必填? | 用户可能的表达 | 未识别到时的行为 |
+|----------|-------|---------------|-----------------|
+| `--task-id` | **是** | `cgt-*` 格式 id、"任务 id 是 xxx"、"这次生成的 task"（从对话历史里的 `+gen` / `gen list` 输出提取） | **询问用户**："能给我这次生成的 task_id 吗？可以从 `arkcli gen list` 拿" |
+| `--feedback` | **是** | 用户对现象的描述（"主角脸变形"、"字幕拼错"、"续写接缝跳变"）—— 直接摘用户原话 | **询问用户**："能描述下具体是哪里效果不对吗？" |
+| `--badcase-type` | 否 | 用户明说"这是角色漂移" / 或 agent 从 feedback 推断出某个枚举 | 不追问；如推断出候选枚举可**主动推荐 + 等用户确认**再带上 |
+| `--contact-info` | 否 | "留邮箱 xxx@yy"、"回访电话 138xxx"、"联系方式 xxx"—— **只在用户主动提供时提取** | **绝不主动问**（PII，避免过度收集） |
+| `--source` | 否 | 用户明说"来源 huoshan / huosu / qianzhi / case_import" | 不追问，走服务端默认 |
+| `--account-id` | 否 | 用户明说"上报到 account xxx"（罕见） | 不追问，Bearer 路径服务端自动反查 |
+
+**核心原则**：
+
+- **必填缺失 → 主动追问**（不能编、不能猜、不能跳过）
+- **可选缺失 → 不带、不问**（不做过度收集，尤其 PII）
+- **用户明确指定 → 以用户为准**（不要 agent 覆盖或"修正"用户传的值，比如用户说 `--source huoshan`，就用 huoshan，不要改成 case_import）
+- **带上的可选字段 → CLI confirm prompt 会展示**（视觉透明，让用户知道所有外发内容）
+
+## 命令用法
+
+```bash
+arkcli doctor report \
+  --task-id cgt-20260501132104-tfm9v \      # 必填, 1-50 个, 可 --task-id 多次或用逗号 / 空格 / 换行分隔
+  --feedback "人物手部扭曲, 且嘴型和中文配音对不上" \  # 必填, 1-2000 字符
+  --badcase-type character_id_drift \       # 可选, 见下方枚举
+  --contact-info "user@example.com" \       # 可选, 联系方式, ≤255 字符
+  --source case_import                      # 可选, 默认 case_import
+```
+
+`--dry-run` 会打印完整请求预览而不真正上报——排查参数拼写的推荐方式。
+
+## `--badcase-type` 枚举（可选，但强烈建议填）
+
+| 枚举值 | 中文含义 | 典型现象 |
+|--------|----------|----------|
+| `character_id_drift` | 角色 ID 漂移 | 主角脸/身份在片子里逐渐变形，或跟输入图不一致 |
+| `subtitle_generation_error` | 字幕生成错误 | 视频里自动生成的字幕拼写、格式、位置有问题 |
+| `logo_watermark_generated` | 生成 logo / 水印 | 画面里冒出了不该有的品牌 logo、水印 |
+| `style_drift` | 风格漂移 | 前后帧的画风、色调、光影出现明显跳变 |
+| `regular_flickering` | 规律性闪烁 | 出现规律的闪烁、明暗跳变 |
+| `extended_video_joint_jump` | 续写视频接缝跳变 | 使用视频续写能力时接缝处画面跳变 |
+| `duplicate_character_appearance` | 角色重复出现 | 同一角色在同一帧出现多次 |
+| `audio_end_noise` | 尾部音频杂音 | 音频结尾出现杂音 / 爆音 / 静默 |
+| `chinese_pronunciation_error` | 中文发音错误 | 生成的中文语音发音有误 |
+| `voice_tone_reference_error` | 音色参考错误 | 生成音色与参考音频不符 |
+| `other` | 其他 | 上述都不适用 |
+
+**Agent 应主动帮用户匹配**：读到 feedback 描述后可以推荐一个 `--badcase-type`，但**要等用户确认**才加上。
+
+## 鉴权
+
+**只支持 Ark API Key (Bearer) 鉴权**。
+
+- 缺 API Key 时命令会明确报错并引导 `arkcli auth apikey`。
+- 不需要子账号挂 `CasePlatformAccess` 策略（那是 AKSK 路径的要求，一期不做）。
+- API Key 只负责 Bearer 鉴权，不能代替 project scope。`ProjectName` 由 transport
+  从当前 profile 解析，作为 URL query 公共参数发送；
+  **绝不能放进 JSON body**，否则 CasePlatform 的 Pydantic `extra_forbid` 校验会拒绝。
+- 当前 scope 是「账号全部资源」时省略 `ProjectName`；具体 project（包括
+  `default`）按 query 发送。业务 service 不读、不保存 project。
+
+## 二次确认门（HeadlessConfirm）
+
+上报会导致方舟平台异步拉取视频 / 输入帧用于排障——属于**用户数据外发**，走高危二次确认门：
+
+- **TTY 交互**：默认弹 Y/N 提示（`--yes` 可跳过）。
+- **非交互 / Agent / CI**：`--yes` 被无视，必须显式设 `ARKCLI_ALLOW_HEADLESS_REPORT=1` 才放行。这是 arkcli 对**用户数据外发类操作**的通用护栏（参考 delete / open service 同款做法），防止 agent 反射性静默上报。
+
+Agent 在 headless 环境下**必须先展示 prompt 内容给用户确认**再设 env，不要自作主张把 env 塞进 shell。
+
+## 服务端错误码翻译（`arkcli doctor report` 自带 hint）
+
+| Code | 含义 | 处理 |
+|------|------|------|
+| `40002` | task_id 不存在或不属于当前账号 | 确认 task_id 拼写 + 当前 profile 与 task 所属账号一致 |
+| `40003` | task_id 已经上报过 badcase | 不要重复上报 |
+| `40004` | task 仍在生成中 | 等任务 completed 后再来 |
+| `40005` | 单请求内重复 task_id | 去重 |
+| `60002` | 不在 seedance 2.x 上报支持范围内 | 覆盖方舟 Seedance 2.x 家族的部分版本；具体清单以服务端为准，文档 `https://www.volcengine.com/docs/82379/2389900` |
+| `60003` | 请求 ModelId 与 task_id 反查模型不一致 | 检查 task_id 是否对应 seedance 2.x 家族的正确版本 |
+| `40006` | AccountId 缺失（AKSK 路径） | Bearer 路径不会撞这个；撞了说明 APIKey 未生效 |
+| `40007-40011` | 各种字段前置校验 | 按 hint 补齐 |
+
+## Output schema
+
+```json
+{
+  "submission_id": "badcase-sub-...",
+  "total": 2,
+  "accepted": [
+    {"task_id": "cgt-a", "case_id": "instance-...", "message": "Success"}
+  ],
+  "rejected": [
+    {"task_id": "cgt-b", "code": "40003", "reason": "task_id 已经提交过 badcase", "hint": "..."}
+  ],
+  "processing_hint": "case 已进入 processing 状态; 后台异步转存视频与输入帧, 完成后 case 翻成 completed",
+  "request_id": "..."
+}
+```
+
+Agent 拿到之后应把 `accepted` 的 case_id 展示给用户，`rejected` 里的每条把 `reason` + `hint` 展示（不用重复原始错误码）。
+
+## 反例（不要做）
+
+- ❌ 用户只描述 Seedance 2.x 字幕错 / 角色漂移等效果问题，Agent 跳过 `doctor model` / `doctor infer-endpoint` 直接跑 report。**不能**；用户未明确说要上报时必须先诊断。
+- ❌ 用户说“先检查 / 诊断 / 排查这个 Seedance 2.x 效果问题并上报”，Agent 因为看见“上报”就直达 report。**不能**；混合意图必须先完成 `doctor model` / `doctor infer-endpoint`，再按 Path A 询问并上报。
+- ❌ Agent 读到 `report_suggestion` 后不询问用户，直接跑 report。**不能**；Path A 必须等用户明确同意上报。
+- ❌ 用户没说要上报、Agent 也没读到真实诊断返回的 `report_suggestion` → 主动跑 report。**不能**。
+- ❌ 用户只说"帮我上报 badcase"但没提模型 / 没描述现象 → agent 直接抽 task_id 就跑命令。**不能**，Path B 有家族门槛和效果类门槛,缺哪个追问哪个,不许无脑靠意图关键词触发。
+- ❌ 用户明说是 1.x / seedream / 其他视频模型 → 硬走上报路径想让服务端 60002 兜底。**不能**,agent 层就要拒绝并转告边界,不要浪费用户一次交互。
+- ❌ 把 `model_supported=true` 当作具体 task 已通过资格校验 → 它只表示模型落在家族前缀内；具体 task 必须由 report 服务端校验。
+- ❌ **在 agent 层做一次"确认要上报吗 [y/N]"式仪式门，跑 CLI 后用户又被 CLI 层弹的 prompt 问一次相同的事** → 两次问同一个问题冗余。Agent 层只做一句话意向探询 + 参数收集，决定性确认交给 CLI 层的结构化 prompt。
+- ❌ 用户反馈"生成失败 / 报错 / task expired / 429" → agent 建议上报 badcase。**不能**，那是运行类问题，服务端 40004 / 60002 会拒；错误码类走 error / doctor error 路径。
+- ❌ 用户 task_id 不清楚 → agent 编一个 fake 走 dry-run 之外的路径。**不能**。
+- ❌ 必填参数（task_id / feedback）缺失时**不追问**、瞎猜 / 编 / 用占位符跑命令。**必填未识别到 MUST 询问用户**。
+- ❌ **主动询问用户 contact-info**（"给我你的邮箱吧") → 违反过度收集原则。仅在用户主动提供联系方式时才提取并带上。
+- ❌ 用户明确说"用 `--source huoshan`" agent 又擅自改成 case_import。**以用户为准**。
+- ❌ 用 1.x 或 seedance 家族外的 task_id 提交，然后忽略 60002 拒绝。**要转告用户**。家族前缀匹配只是发现提示，具体 task 由服务端判。
+- ❌ headless 环境替用户静默设 `ARKCLI_ALLOW_HEADLESS_REPORT=1`。**不能**，先向用户展示要上报的内容。
+
+## 给用户看的话术
+
+Agent 拿到 `arkcli doctor report` 输出后按以下模板回信，**不复述完整 JSON、不重复原始错误码**：
+
+1. **全部 accepted**（happy path）：
+   > "已上报，方舟排障平台会异步分析。case_id：`instance-xxx`（可留作后续跟进）。分析完成后 case 会翻到 completed。"
+
+2. **部分 accepted / 部分 rejected**：
+   - 先说 accepted 的 case_id
+   - 逐条说 rejected：`task_id + reason + hint`（hint 已由 CLI 翻译成人类可读中文，直接展示）
+   > "上报了 3 个 task：`cgt-a` 已受理（case_id: instance-1）；`cgt-b` 被拒——已经上报过 badcase，不用重复提；`cgt-c` 被拒——task 还在生成中，等 completed 后再上报。"
+
+3. **全部 rejected**：
+   > "全部被拒。原因："逐条列 `reason + hint`；给出下一步（等 completed / 换正确 task_id / 别重复上报）。
+
+4. **未定案 case**（Accepted 里 `processing_hint` 非空）：
+   - 转告 processing 语义："case 已进入 processing 状态，后台异步转存视频与输入帧，完成后翻成 completed"
+   - **不承诺**具体完成时间
+
+**触发上报前**（Path A 意向探询后 / Path B 参数收集完成后）也有话术：
+- Path A 意向探询："这类效果类问题可以上报到方舟让排障团队分析，需要我帮你上报吗？"
+- 参数缺失追问：见"参数意图识别契约"表最后一列
+
+## 何时 _不_ 用本 reference
+
+- 用户跑的是 **seedream / 1.x seedance / 其他生视频模型** 的 task → **不支持上报**，直接转告用户并转 [`scope-model.md`](scope-model.md) 或 [`error-codes.md`](error-codes.md)
+- 用户反馈是 **task 生成失败 / expired / 429 / ContentRiskBlocked / ModelAccessDenied** → 错误码 / 运行类问题，走 [`error-codes.md`](error-codes.md) 或 `doctor error <code>`
+- 用户想看**模型整体健康度 / 错误率分布 / 用量** → [`scope-model.md`](scope-model.md)
+- 用户想看**单接入点状态 / 用量 / 配额** → [`scope-infer-endpoint.md`](scope-infer-endpoint.md)
+- 用户想**看视频结果 / 下载 mp4 / 查任务状态** → 不是诊断问题，走 `arkcli gen get <task_id>` / `arkcli gen list`
+- 用户问 **`--contact-info` / API Key 是什么** → 认证类走 [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md)
+
+## 参考
+
+- 接口文档：[火山方舟 CasePlatformV1BadcaseReport](https://www.volcengine.com/docs/82379/2389900)
+- 上级：[`../SKILL.md`](../SKILL.md)
+- 相邻 domain：[`scope-model.md`](scope-model.md)（`doctor model` 会输出 `report_suggestion` 触发本 domain）
+- 相邻 domain：[`scope-infer-endpoint.md`](scope-infer-endpoint.md)（`doctor infer-endpoint` 同样会触发）

package/skills/arkcli-doctor/references/verify-origin.md

@@ -0,0 +1,142 @@
+# Ark 产物来源特征验证
+
+## 1. 能力边界
+
+命令：
+
+```bash
+arkcli doctor +verify-origin <media-url> [media-url...] --format json
+```
+
+用于验证 1-20 个公网图片或视频 URL 是否包含与 Ark 生成过程相关的技术特征。
+
+它不能：
+
+- 判断媒体内容是否真实、是否是假新闻；
+- 判断版权、权属或法律责任；
+- 构成官方认证、法律鉴定或权属认定；
+- 判断内容安全、合规、画质或播放质量。
+
+## 2. 输入与批量约束
+
+- 一次输入 1-20 个 `http://` 或 `https://` URL；
+- 图片和视频可在同一批中出现；
+- 必须一次调用把整批 URL 交给 CLI；
+- 禁止为每个 URL 分别启动 `arkcli`；
+- 禁止使用 shell `for` 循环；
+- 禁止直接调用 `CreateArkOfficialResultQuery` 或 `GetArkOfficialResult` Raw Action；
+- 禁止 Agent 自己轮询。
+
+超过 20 个 URL 时，把它们拆成多批，并且每一批都必须独立完成费用披露与确认。
+
+## 3. 整批一次确认
+
+首次调用不带 `--yes`：
+
+```bash
+arkcli doctor +verify-origin \
+  "https://example.com/a.mp4" \
+  "https://example.com/b.png" \
+  --format json
+```
+
+该调用必须：
+
+- 不获取产物验证 invoker 或 STS；
+- 不调用 Create；
+- 不调用 Get；
+- 返回一份覆盖整批的价格、数量与限额披露。
+
+Agent 必须完整展示披露，然后等待用户在看到披露后明确确认。用户确认后，对原命令只追加一次 `--yes`：
+
+```bash
+arkcli doctor +verify-origin \
+  "https://example.com/a.mp4" \
+  "https://example.com/b.png" \
+  --yes \
+  --format json
+```
+
+这一个 `--yes` 覆盖当前批次中的全部 URL。禁止逐 URL 确认，禁止弹出 20 次确认。
+
+计费事实：
+
+- 每账号提供 20 次免费额度，但 CLI 不知道当前剩余额度；
+- 免费额度用尽后 `0.1 CNY/call`；
+- 成功得到 `True`、`False` 或 `Null` 都计费；
+- 鉴权或限流失败不计费；
+- 单日上限 1000 次；
+- Create 与 Get 均按目标态 20 QPS 设计。
+
+## 4. 执行与恢复
+
+CLI 对每个 URL：
+
+```text
+CreateArkOfficialResultQuery
+  -> Result.QueryID
+  -> 每 5 秒 GetArkOfficialResult
+  -> running 继续
+  -> succeeded / failed 结束
+```
+
+每个 URL 最多 Create 一次。Create 超时不能证明服务端没有创建，因此 CLI 不自动重试 Create。
+
+Get 发生可重试限流或临时服务错误时，只能保留同一个 QueryID 重试 Get，绝不能回到 Create。
+
+如果命令中断，使用输出中的 QueryID 恢复：
+
+```bash
+arkcli doctor +verify-origin \
+  --query-id "<query-id-1>" \
+  --query-id "<query-id-2>" \
+  --format json
+```
+
+恢复已有 QueryID 不重新 Create，也不重复询问同批费用确认。
+
+## 5. 鉴权
+
+该命令是控制面 OpenTOP workflow：
+
+- 支持 SSO 派生 STS AK/SK/SessionToken；
+- 支持长期 AK/SK；
+- 不使用 Ark API Key；
+- 不要传全局 `--api-key` 或 `--base-url`。
+
+## 6. 最终结果必须完整转交
+
+单条结果是完整 `GetArkOfficialResult` JSON envelope。批量结果是按输入顺序排列的数组，每个成功项的 `response` 都是完整 envelope。
+
+Agent 的最终回复必须只包含 CLI stdout 的完整 JSON：
+
+- 不添加总结；
+- 不翻译；
+- 不解释 `IsOfficial`；
+- 不只摘 `Result`；
+- 不只摘 `Message`；
+- 不添加 Markdown 代码围栏；
+- 不添加“结果如下”等前缀；
+- 不使用 `--transform`；
+- 不切换为 YAML、table、CSV 或 JSONL。
+
+特别禁止：
+
+- 把 `True` 说成“已官方认证由 Ark 生成”；
+- 把 `False` 说成“确定不是 Ark 生成”；
+- 把 `Null` 说成 `False`；
+- 改写服务端免责声明。
+
+## 7. Client Preview
+
+用户只想预览执行计划时：
+
+```bash
+arkcli doctor +verify-origin \
+  "https://example.com/a.mp4" \
+  "https://example.com/b.mp4" \
+  --dry-run \
+  --format json
+```
+
+Preview 零网络，只展示每个 URL 的 Create/Get 图、5 秒轮询、QPS 和整批确认范围。Preview 不是费用确认，不能因为 preview 成功自动添加 `--yes`。