arkcli-gen

arkcli 生成工作流（+gen）

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md（认证闸门、模型查找回退、共享安全规则）。

CRITICAL — 真实生成是工作流，不是猜一条命令：按 Step 1 → Step 2 → 必要时 Step 2.5 → Step 3 执行。用户只要求 --dry-run 时例外：全程本地，不先跑在线 Resources / Models / Usage 准入；在线未知项保留 unresolved。执行前务必读 references/arkcli-gen.md。

CRITICAL — 用户显式给出 API Key / Base URL / Endpoint 时，MUST 先读 ../arkcli-shared/references/execution-context.md。显式 Endpoint 的权威元数据优先于当前 profile。

火山额外约束：不要因为 active profile 是 Agent/Coding Plan 就把用户给出的 Endpoint 当套餐模型调用。

Agent 快速执行顺序

先把用户要求拆成可验收项，再按资源、能力、整批预算、执行、成品检查推进。执行前读取 references/intent-and-validation.md：它约定不完整意图的默认值、 参数组合、凭证错误分流和成品验收。参数表是候选能力，不代表每个模型都支持。 用户已明确要图片或视频时，生成命令显式带 --modality image|video；不要让名称解析覆盖用户意图。 只使用用户本轮提供或明确授权复用的素材；不得从历史目录、旧任务或相似文件名擅自加入额外参考图/视频。

成品验收前：宿主视觉输入准入

生成模型能出图，不代表驱动当前 Agent 的宿主模型能看图。Read 工具描述说支持图片， 也不是当前宿主模型的视觉能力证明。 当前会话没有可靠的视觉能力声明或已验证的兼容性时， 按“未准入”处理：不要原生 Read 图片、视频或抽出的帧，也不要用成品试探能否读取。 本 Skill、参考说明和 JSON 等文本仍可正常 Read。

• 已有兼容且已授权的视觉工具，或同一主体下已准入、收费路径不变的视觉模型时， 按对应 Chat/Understand Skill 分析实际媒体，只把文字结果返回宿主；不自动换宿主、Profile 或 Key。
• 没有这样的入口时，完成文件/解码/尺寸/时长等结构检查并交付已有成品，明确“视觉语义未验”； 不声称看过或完全符合。不要为补验收擅自增加未授权的收费调用。
• 生成成功后宿主读图报错，是验收/交付失败；保留成品，不重新提交生成或轮转业务 Key。

反唤起信号

• 描述、分析现有图像而不是生成/编辑 → arkcli-chat 或有固定产出形态的 arkcli-understand。
• 只查资源、能力、用量 → 对应只读 Skill，不提交生成任务。

为什么是工作流（核心，先理解再执行）

用户说"生成一个视频/一张图"，本质是至少三件独立的事，必须按序；批量或多阶段任务还要先确认整批可完成：

① 本次资源从哪里来           ── 用户显式 Endpoint 优先；否则看当前 profile
② 该模型支持哪些参数          ── 不查就传参 = 瞎猜 = 被校验拒/被后端拒
②.5 多候选/多阶段额度与任务数 ── 先算完整批次，额度已耗尽就不启动半批任务
③ 按可用参数真去生成          ── 每个请求只提交一次并立即保存 task_id

把这三步压成"直接 +gen 猜一条命令"，正是失败之源：模型名形态不对会 404，参数模型不支持会被拒。

模态解析硬契约

+gen 的生产调用按以下固定优先级解析能力：

explicit --modality > output_modalities > task types > unknown

• 直接传版本化模型 ID 时，读取 ArkModels 返回的 output_modalities；缺失时再读取 FoundationModel 的 task_types / filter_task_types。
• 传 ep-* 时，先读取 Endpoint 的 ModelReference.FoundationModel(name, version)，再精确匹配同版本模型的上述结构化元数据。
• 模型名与 DisplayName 只用于定位模型，不参与模态判断。不要从 seedream、seedance 或任何国内/海外品牌前缀推断 image/video。
• 结构化元数据缺失或互相冲突时返回 unknown，提示用户显式传 --modality image|video；禁止静默猜测。
• +gen --dry-run 是纯本地 Client Preview：不读取 Endpoint/模型元数据、不调用 生成 API，也不下载或打开文件。显式 --modality 最可靠；已知 seedream/seedance 模型名可本地判断，其他模型或 Endpoint 必须显式传 --modality image|video。在线才能补齐的执行上下文会以 unresolved 和 fidelity=partial 明示。