# 从用户要求到可验收成品

宿主的额外约束优先：要求强制水印时不得关闭；凭证由宿主注入且禁止本地恢复时，
认证错误只能停止并报告，不能启动登录、刷新或切换凭证。本参考不放宽共享 Skill 的这些边界。

## 1. 意图、默认值与准入

先区分：真实生成、编辑已有素材、查询已有任务、只预览请求。真实生成不是只读；
`--dry-run` 不能证明 Key 有效或成品达标。用户只要预览时保持全程本地，不先做在线准入查询。

把明确要求保留成检查清单：主体/数量、属性/文字、相对位置、尺寸/比例、时长、动作及方向、
必须保留/必须排除、输入素材角色、文件数量与交付位置。不要把用户硬要求当作可随意优化的文案。
不需要把整张清单都复述给用户，只在有冲突或会改变结果时说明。

素材集合也是硬约束：不得引入用户未提供或未明确授权复用的历史图片、视频、音频；目录里“看起来相关”
的旧文件不能自动成为参考素材。用户只给一个视频时，不因为 Skill 示例里有角色图就擅自补一张图。

- 用户未选模型：优先当前目标模态的兼容 default；无 default 时按共享 0/1/N 规则处理真实候选。
- 未说图片数量：一张；“四格漫画”不等于四个文件。未指定的尺寸、时长等沿用选定模型的有效默认，
  不套用其他模型的参数。默认影响用户目标（例如横竖构图）时在结果中说明。
- 用户要图片/视频：显式带对应 `--modality`。模态不明确才澄清，不从品牌名猜测。
- 同一次 workflow 的查询、提交、轮询保持相同 Profile/凭证/region。临时参数不写回 default。
- 按共享 execution-context 的五类 Profile 矩阵读取 `invocable` 与 `required_overrides`。
  本地显示已登录、Key 缓存状态、资源可见都不能单独证明数据面 Key 当前有效。
  实际任务响应才证明本次调用被接受；不为每次生成额外提交一张“试钥匙”的图片。

## 2. 参数组合不是关键词到 flag 的固定替换

`supported_params` 描述 wire 参数（下划线）；CLI flag 通常是连字符，且存在映射：

| 用户约束 | CLI / wire 约束 |
| --- | --- |
| 多张图片 | `--image-count N` / `--n N`；N>1 导出 sequential auto 与 max_images。不要同时传两个数量入口 |
| 连续图模式 | `--sequential auto|disabled` → `sequential_image_generation`；裸 flag 缺值，disabled 会与多图要求冲突 |
| 无水印/无声音 | 支持该值时显式 `--watermark=false` / `--generate-audio=false`；false 与省略不同 |
| 固定画面 | prompt 保留视觉要求；`camera_fixed` 支持时才额外加 flag，验收也要检查镜头变化 |
| 视频时长/帧数 | 先查 duration/frames 能力与覆盖关系，不同时堆参数后假设两者都生效 |
| 一张多格图 | 一张图片 + prompt 指定格子布局；不是默认 sequential 多文件 |
| 输入参考/首尾帧 | 输入顺序和 first/last/ref 角色必须对应用户素材，不把参考图误作首帧 |
| 视频续写 | `reference_video` 明确源视频，人物图只作 `reference_image`；ratio 逐值服从精确模型/EP 能力，不固定替换成 `adaptive` |
| 只要 URL | 显式 `--save-to=""`；不能用省略代替空串，不能声称已保存本地 |

对实际会发出的每个模型参数，检查 support、type、enum、min/max、required、fixed/default 及组合依赖。
`--wait`、`--save-to`、`--open` 等客户端编排 flag 不属于模型参数目录。
明确不支持的键/值不能靠 `--extra-body`、`--force` 或改拼写偷偷绕过。

目录为空/查询失败是“能力未知”，不是“全部支持”或“模型不支持”。保留告警，勿宣传
CLI 的保守兜底值是模型推荐值。目录支持而本地拒绝时记录调用 ID、查询 Name/Version、
拒绝参数与错误，不替换套餐调用身份。用户未授权放宽硬要求时不能静默删参数。

“只看请求”用 dry-run；“真实草稿”只有模型支持 draft 才能使用。
不支持 draft 时如用户接受，可另选已确认兼容的低成本配置，但必须说明不是原生草稿模式。

## 3. 视频续写的意图、条件依赖与批量提交

以下表达进入续写分支：“续写”“接着生成”“从结尾继续”“延长这个视频”“生成第二段”以及
`continue` / `extend`。如果用户只是要求参考原视频的风格、节奏、动作或运镜重新创作，则保持普通 R2V；
不要把两类任务混为一谈。

续写分支的硬约束：

- 源视频必须显式使用 `reference_video:`；辅助人物/服装图必须使用 `reference_image:`，不能因其排在视频后面
  就把它当首帧。裸视频或 `ref:` 可以表达普通 R2V，但不要把它们宣称为已明确进入续写语义。
- 本地 `reference_video` 当前不能由 CLI 自动上传成服务端可访问的视频地址；
  `reference_video:@/local/source.mp4` 会被数据面拒绝。提交续写必须使用 `https://...` 等服务端可访问 URL。
  只有先前任务明确返回、且能证明对应同一源视频的有效 `output_url` 才可复用；不得按文件名、画面相似或
  历史目录猜一个 URL。用户只有本地 MP4 且没有已授权上传路径时，停止并说明当前 Skill-only 边界。
- `adaptive` 不是续写的无条件规则。`ratio` 应按用户要求及精确模型/Endpoint 的 `supported_params` 检查
  `support/type/enum/fixed/default`：用户要求固定比例且该值受支持时保留；用户要求继承源画幅且
  `adaptive` 受支持时才选它；用户没要求时优先省略，交给该资源的有效默认。目录不清楚时不要强制替换。
- `resolution`、`ratio`、`duration` 是独立参数。优先选择能够原生完成用户时长的资源；只有单任务上限不足时
  才提出分段续写，提交前说明它会增加任务数、计费与拼接/连续性风险，不能静默把 30 秒改成 15+15。
- prompt 从参考视频结尾后的下一瞬开始，描述**新发生的动作**并明确不重演；将人物身份、服装、场景、光线、
  镜头轴线/景别和运动方向列为连续性约束。不要在成品未验前承诺“无缝”“零跳变”。

多候选或多阶段请求先做完整批次预检：列出候选数 × 阶段数及依赖，再按当前 lane 查询套餐/免费额度。
火山视觉免费额度命令的正确形态是
`arkcli usage balance --type free-quota --modality ComputerVision --page-all --format json`；套餐快照使用
`arkcli usage plan --format json`。额度快照不是预占，无法换算每个任务时不能声称“足够完成整批”；
已明确耗尽时不先提交半批，再到中途才切路。

创建与恢复规则：

- 多候选默认串行创建、并行等待。每个 `+gen` 只执行一次；解析到 `task_id` 后立即持久记录，再创建下一项。
- `--name` 不是服务端幂等键，当前 `gen list` 也不提供可靠的 name/prompt/content 证据供重建映射；不能用
  candidate 名称或“相同 model + 最近任务”证明某个命令已经/尚未创建。
- 创建命令超时、输出截断或进程中断且没有 `task_id` 时，把该项记为 `UNKNOWN` 并停止后续创建。
  `gen list` 可辅助人工排查，但不能仅凭 model/status 唯一认领任务；不得自动重提，避免重复计费。
- 只对已经记录的 task ID 使用 `gen get`。一个候选失败不复制提交，轮询失败也不回到 `+gen`。

续写语义验收必须覆盖“源视频末尾约 1 秒 → 新视频开头约 1 秒”：检查开头是否重放旧情节，以及人物、服装、
场景、光线、镜头轴线、景别、动作姿态和运动方向是否连续。任务 `succeeded` 但出现明显重演或跳变时，
应报告“生成成功、续写效果不合格”，不能把服务端成功等同于续写达标。

## 4. 错误恢复不改变收费主体

- `coding-plan-team` 的 image/video 会进入 platform 后付费 lane；在提交前必须让用户
  明确选择兼容的 `--profile` 或提供 `--api-key`。只有本地存在唯一 sibling paygo
  profile 不构成授权，不得先发请求再提示。
- 401/InvalidApiKey：保留准确错误，按 Auth/Profile Skill 核对当前 lane 的 Key；
  刷新 Key 清单不等于轮转 Key。不要自动轮转、创建 Key、换账号或循环重试。
- 403/FeatureDenied/Responses access：可能是模型资格/Endpoint 权限，不直接断言 Key 过期。
- 429：区分限流与额度不足，不能把所有 429 当成没钱。已明确 quota exhausted 时提醒用户
  当前资源/套餐受限，提供同一身份下已确认兼容的候选；跨收费路径或持久切换需用户授权。
- 异步任务已被接受后，保存 task_id，仅查该任务；失败/超时不自动再提交一个收费任务。
- 所有错误只报告已取得的证据，不虚构剩余额度、轮转必要性或已完成状态。

## 5. 完成状态、交付与语义分别验收

先确认**驱动当前 Agent 的宿主模型**能否接收图片/视频，不要用生成模型的能力代替
宿主能力。存在 `Read` 工具、能读文件、能调用生成 API，都不证明宿主可接收图片。

- 宿主明确具备对应视觉输入能力时，使用其看图/视频工具检查实际成品。
- 宿主是纯文本，或视觉能力没有可靠声明时，不把图片或视频帧直接塞进原生 Read
  的图片返回通道。若有已授权的视觉分析工具，或同一消费主体下已授权、已准入且
  收费路径不变的视觉模型，
  可经 `arkcli-chat` / `arkcli-understand` 分析媒体并把**文字结果**返回当前宿主；
  按对应 Skill 做 resources/Key/模型准入，不为验收自动换宿主模型、Profile 或 Key。
- 没有兼容且已授权的视觉入口时，仍完成文件/解码/尺寸/时长等结构检查并交付成品，
  明确哪些语义未验，不能声称看过。CI、远端无桌面环境不依赖 `--open` 来验收。
- 生成已成功、后续宿主看图失败，是验收/交付链路失败，不是生成任务失败；保留已有
  成品，不因此重提生成或轮转业务 Key。

1. **执行**：真实 CLI 非错误响应；图片 status=succeeded；视频轮询读 `.status.phase`，
   queued/running 不是成品，failed/cancelled 立即停止并说明。
2. **交付**：逐一核对返回文件实际存在、可解码、文件数量、尺寸/比例、视频时长与所需音轨。
   生成成功但下载失败，分别报告两项状态；优先用 CLI 已返回的本地文件，不重提任务。
3. **语义**：用宿主可用的看图/视频能力检查上述清单。图片逐张检查；视频至少检查覆盖开头、
   中间、结尾的时序证据，涉及运动/镜头/事件次序时不能只看首帧。抽帧不能证明音频要求。
   不能把文件名、prompt、HTTP 200 或 Agent 自己的文字声明当作语义证据。
4. **报告**：区分“已确认”“存在偏差”“未能验证”。没有查看成品就不能说逐项符合。
   宿主不能看媒体时，仍交付文件并明确未验部分。`--open` 打开文件不等于验收通过。

出现偏差时，保留原始成品；用户已授权迭代则针对失败项做有界修订，再验证未要求改变的部分。
不无限重抽直到挑出一张好图后隐藏失败记录，也不把审美偏好当成确定性错误。

可读回归场景见 [evals.md](evals.md)；自动门禁由独立 arkcli-eval-kit 维护。