@lingjingai/lj-awb-cli-pre 0.3.15 → 0.3.16

package/skills/lj-awb/modules/video.md

@@ -6,16 +6,16 @@
 
 | 命令 | 用途 |
 |------|------|
-| `lj-awb video fee --model-group-code <code> --prompt "..." --duration 5` | 生视频估价 |
-| `lj-awb video create --model-group-code <code> --prompt "..." --dry-run` | 预览生视频请求 |
-| `lj-awb video create --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=./actor.png --duration 5 --yes` | 首帧生视频 |
-| `lj-awb video create --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=asset:<assetId> --duration 5 --yes` | 资产首帧生视频 |
-| `lj-awb video create --model-group-code <code> --prompt "<<<女主>>> 奔跑" --resource subject:reference:女主=asset:asset_xxx --duration 5 --yes` | 主体参考生视频 |
-| `lj-awb video create-batch --input-file ./video.jsonl --model-group-code <code> --yes` | 批量生视频 |
-| `lj-awb video status --task-id <id>` | 查询生视频任务 |
+| `lj-awb create video-fee --model-group-code <code> --prompt "..." --duration 5` | 生视频估价 |
+| `lj-awb create video --model-group-code <code> --prompt "..." --dry-run` | 预览生视频请求 |
+| `lj-awb create video --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=./actor.png --duration 5 --yes` | 首帧生视频 |
+| `lj-awb create video --model-group-code <code> --prompt "镜头推进" --resource image:first_frame=asset:<assetId> --duration 5 --yes` | 资产首帧生视频 |
+| `lj-awb create video --model-group-code <code> --prompt "<<<女主>>> 奔跑" --resource subject:reference:女主=asset:asset_xxx --duration 5 --yes` | 主体参考生视频 |
+| `lj-awb create video-batch --input-file ./video.jsonl --model-group-code <code> --yes` | 批量生视频 |
+| `lj-awb task video-status --task-id <id>` | 查询生视频任务 |
 | `lj-awb task wait --task-id <id> --task-type VIDEO_GROUP --wait-seconds 300` | 等待生视频结果 |
-| `lj-awb video subtitle-remove --video-url "https://..." --yes` | 提交去字幕任务 |
-| `lj-awb video subtitle-status --remote-task-id <id>` | 查询去字幕任务 |
+| `lj-awb create video-subtitle-removal --source-task-id <videoTaskId> --yes` | 基于来源视频任务提交去字幕任务 |
+| `lj-awb task video-subtitle-status --task-id <subtitleTaskId>` | 查询去字幕任务 |
 
 ## 创建参数
 
@@ -43,14 +43,14 @@ lj-awb model create-spec --model-group-code <modelGroupCode> -f json
 如果用户没有指定 `quality`、`duration` 或约束后仍可选的 `ratio`，先展示 `model options.params[].values` 和默认值让用户选择；用户确认后再执行：
 
 ```bash
-lj-awb video fee --model-group-code <modelGroupCode> --prompt "<prompt>" --duration <seconds>
-lj-awb video create --model-group-code <modelGroupCode> --prompt "<prompt>" --duration <seconds> --dry-run
+lj-awb create video-fee --model-group-code <modelGroupCode> --prompt "<prompt>" --duration <seconds>
+lj-awb create video --model-group-code <modelGroupCode> --prompt "<prompt>" --duration <seconds> --dry-run
 ```
 
 用户确认后：
 
 ```bash
-lj-awb video create \
+lj-awb create video \
   --model-group-code <modelGroupCode> \
   --prompt "<user prompt>" \
   --resource image:reference:hero=./hero.png \
@@ -72,31 +72,24 @@ lj-awb video create \
 - Agent 向用户解释模型能力时，默认说“支持参考图 / 首帧 / 首尾帧 / 主体引用”等正向能力；不要默认列“无音频参数、无多条数参数”。
 - `fee` 和 `create --dry-run` 前必须确认缺失的关键参数；不要把 `model options.params[].defaultValue` 当成用户选择。用户说“按默认”后才继续。
 - 面向用户列参数时，`needAudio` 说成“音效：是否需要输出音效”；不要用 CLI flag 加技术解释的写法。只有展示最终命令时才写 `--need-audio true/false`。
-- 用户上传音频、音乐或配音时，先检查 `model options.resources[]` 是否存在 `mediaType=AUDIO usage=reference`；存在时使用 `--resource audio:reference=...`，不存在时不要把音频文件硬塞给该模型。
-- 音频素材输入统一使用 `--resource audio:reference=...` 或 resources JSON 中的 `{ "type": "audio", "usage": "reference" }`，前提是模型明确暴露 AUDIO reference 资源。
-- 用户明确要在 prompt 中指代音频时，可以使用 `audio:reference:<key>=...`，并在 prompt 中插入同名 `<<<key>>>`。
-- 用户明确要输出音效时，先看 `model options.params` 是否有 `needAudio`；存在才传 `--need-audio true/false`。它不接收音频文件。
+- 音频参考：必须先确认 `model options.resources[]` 暴露 `mediaType=AUDIO usage=reference`，否则不要硬传；统一用 `--resource audio:reference=...` 或 JSON `{ "type": "audio", "usage": "reference" }`。
+- `--need-audio` / `audio:reference` / 资源模式互斥 / `reference_key` 对齐 / `<<<key>>>` 等创建协议统一见 [`create-contract.md`](create-contract.md) §素材组织 + §参数含义，不在本文重复。
 - 使用首帧 / 首尾帧等资源后，如果 `model options.constraints[]` 对 `ratio` 等目标参数返回 `effect=no_selectable_values`，不要再追问或传该参数。
-- `media=IMAGE` 的 `fileTypes` 不要机械理解成唯一允许格式：空列表表示不支持 webp，本地 webp 会自动转 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才按允许列表强校验并尝试转换。默认 text 里看 `formats` 和 `webpInput`，不要把 `formats=...|webp` 理解成“只支持 webp”。
-- `supportLastFrameOnly=false` 只表示不支持“仅尾帧”；不要据此判断不支持首尾帧过渡。是否可传 `image:last_frame` 看 `model options.resources[].usage` / `model create-spec.supportedIntents[].usage` 是否包含 `last_frame`。
-- prompt 中出现 `<<<key>>>` 时，必须有同名 `reference_key`，例如 `--resource image:reference:hero=./hero.png` 或 `--resource audio:reference:voice=./voice.wav`；反过来不强制。
-- 参考图生视频取值优先级：`backendPath`（`material/...`） > 本地文件 > 真正外部公网完整 URL，也可使用普通素材 `asset:<assetId>`。这和 `subject:reference:<key>=asset:<externalId>` 不是一回事。
-- 参考音频取值优先级同上；并且必须以 `model options.resources[]` 暴露 AUDIO reference 为准。
-- 首帧 / 尾帧取值优先级：`backendPath` > 本地文件 > 外部公网 URL，也可以是 `asset:<assetId>`。
-- 关键帧 `image:keyframe#1=...` 取值优先级：`backendPath` > 本地文件 > 外部公网 URL。
-- **平台素材一律用 `backendPath`，不要把 `upload files` 回显的 `url`（`https://*.myqcloud.com/material/...`）当作 source.value 直接复用。**
-- `image:first_frame=asset:<assetId>` 是资产首帧；`subject:reference:<key>=asset:<externalId>` 是主体引用，两者不是同一类资源。
-- 主体引用必须先 `subject publish` + `subject wait` 得到 `externalId`。
+- `media=IMAGE` 的 `fileTypes` 不要机械理解成唯一允许格式：空列表表示不支持 webp，本地 webp 会自动转 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才按允许列表强校验并尝试转换。默认 text 里看 `formats` 和 `webpInput`，不要把 `formats=...|webp` 理解成"只支持 webp"。
+- `supportLastFrameOnly=false` 只表示不支持"仅尾帧"；不要据此判断不支持首尾帧过渡。是否可传 `image:last_frame` 看 `model options.resources[].usage` / `model create-spec.supportedIntents[].usage` 是否包含 `last_frame`。
+- 视频素材（参考图 / 首帧 / 尾帧 / 关键帧 / 音频）source.value 取值优先级、不要复用 myqcloud 完整 URL 规则统一在 [`create-contract.md`](create-contract.md) §素材组织。`image:reference=asset:<assetId>` / `image:first_frame=asset:<assetId>` / `image:last_frame=asset:<assetId>` 是素材引用；`subject:reference:<key>=asset:<subjectId>` 是主体引用。主体引用必须先 `create subject` + `create subject-wait` 得到 `externalId`。
 - 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`duration`、`need_audio`、`resources`、`resource`、`customBizId`；其中 `need_audio` 表示是否需要输出音效，音频素材仍写入 `resources`。
+- **批量是 best-effort**：`create-batch` 子任务**单条失败不会回滚整批**，已成功项依然扣分并产生 taskId。提交后必读响应里每项的 `status` / `taskId` / `error`，给用户汇总"成功 N / 失败 M"，对失败项单独 fix + 重跑（不要全批重跑）。
 - 视频任务默认可能耗时较长，批量和复杂任务应异步提交并记录 task id。
-- **多镜头 / 多分镜时主动建议并行**：用户一次给出 ≥2 个同模型同参数的视频任务（典型场景：分镜流水线、批量首尾帧动画）时，Agent 必须先告知"这批可以用 `video create-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 → 继续单条 create。**不要默认一条一条串行还不告知**。
-- 去字幕服务适合处理 Seedance 原始结果链接，不要把无关 CDN 链接误传。
+- **多镜头 / 多分镜时主动建议并行**：用户一次给出 ≥2 个同模型同参数的视频任务（典型场景：分镜流水线、批量首尾帧动画）时，Agent 必须先告知"这批可以用 `create video-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 → 继续单条 create。**不要默认一条一条串行还不告知**。
+- 去字幕统一走 material 任务体系：用已成功的视频来源任务 ID `create video-subtitle-removal --source-task-id <videoTaskId> --dry-run`，不要直连外部服务；`task video-subtitle-status` 只接收 material 去字幕任务的 `--task-id`。
 - 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"生图 / 生视频"小节；错误恢复（积分 / 模型 / 资源约束）见 [`../references/error-codes.md`](../references/error-codes.md)。
 
 ## 下一步
 
-- `video create` 返回 `taskId` + `nextCommand` → 立刻 `task wait --task-id <id> --task-type VIDEO_GROUP --wait-seconds 300`。
-- `video create-batch` 写 `.awb/tasks.jsonl`，用 [`task.md`](task.md) → `task record-poll` 批量等。
+- `create video` 返回 `taskId` + `nextCommand` → 立刻 `task wait --task-id <id> --task-type VIDEO_GROUP --wait-seconds 300`。
+- `create video-batch` 写 `.awb/tasks.jsonl`，用 [`task.md`](task.md) → `task record-poll` 批量等。
 - 任务终态 `resultUrls` → 通常按集 / 场 / 镜头回写到 [`artifact/video.md`](artifact/video.md)：`artifact video update-clip-urls --project-id <id> --episode-id ... --scene-id ... --clip-id ... --video-urls-json '[...]'`。
-- Seedance 原始视频带英文字幕 → `video subtitle-remove --video-url <result-url> --yes` → `video subtitle-status --remote-task-id <id>`。
-- 想长期复用同一角色（避免每次都传图） → [`subject.md`](subject.md) 先 `subject publish` + `wait` 拿 externalId。
+- 任务 `SUCCESS` 后**立刻**用素材库接口找这条视频时可能查不到——后端 `saveResourceToMaterial` 是事务提交后异步执行，详见 [`task.md`](task.md) 规则。优先用 `resultUrls` 直接消费；非要列素材库时先 sleep 2-3 秒。
+- Seedance 原始视频带英文字幕 → 对成功的视频任务运行 `create video-subtitle-removal --source-task-id <videoTaskId> --yes` → `task video-subtitle-status --task-id <subtitleTaskId>`。
+- 想长期复用同一角色（避免每次都传图） → [`subject.md`](subject.md) 先 `create subject` + `wait` 拿 externalId。

package/skills/lj-awb/modules/workflows.md

@@ -4,217 +4,94 @@
 
 ## 目录
 
-- [通用启动流程](#通用启动流程) — `doctor` / `schema` / `account info` / `project current`
-- [Schema 决策规则](#schema-决策规则) — 怎么读 schema 选 command 和必填项
+- [通用启动流程](#通用启动流程) — `doctor` / `account info` / `project current`
 - [模型到任务参数决策流程](#模型到任务参数决策流程) — 模型筛选 → `model options` / `create-spec` → fee → dry-run
 - [参考图生成视频](#参考图生成视频) — 用户给一张图生成一段视频
-- [主体参考生成视频](#主体参考生成视频) — `subject publish` + `subject:reference:<key>`
+- [主体参考生成视频](#主体参考生成视频) — `create subject` + `subject:reference:<key>`
 - [参考图生成图片](#参考图生成图片) — `image:reference=...`，不用 `<<<key>>>`
 - [批量任务](#批量任务) — `create-batch --concurrency`
 - [分镜流水线（分镜图 → 视频）](#分镜流水线分镜图--视频) — GPT Image 2 分镜 → 视频生成
 - [预上传后批量复用](#预上传后批量复用) — `upload files` 一次，多任务复用 `backendPath`
-- [素材库加白后生视频](#素材库加白后生视频) — Seedance / 即梦的 `asset register` → 视频
+- [素材库加白后生视频](#素材库加白后生视频) — Seedance / 即梦的 `create asset` → 视频
 - [Artifact 流水线错误恢复](#artifact-流水线错误恢复) — `import-storyboard` / 批量写入失败的局部重试
 
 ## 通用启动流程
 
 ```bash
 lj-awb doctor --verify
-lj-awb schema -f json
 lj-awb account info
 lj-awb project current
 ```
 
-规则：
-
+- 以上命令只在本轮缺少认证 / 账号 / 项目组上下文时执行；已有状态账本时直接复用，不要每个子任务都跑一遍。
 - `doctor` 返回 `doctorStatus=error` 时停止，不要提交创作任务。
-- `doctorStatus=warning` 时读取 `checks`，只处理与当前任务相关的风险，例如认证、项目组、UTF-8、skill 缺失。
-- `schema` 是机器可读命令契约；Agent 应根据 `commands[].options` 组装参数。
-- `schema.commands[].safety.safeToAutoRun=false` 的命令，不要静默执行；先说明副作用和确认需求。
-- `schema.commands[].requiredOptions` 是硬必填；`requiredAnyOptions` 表示至少满足其中一组输入。
-- `schema.commands[].workflow.recommendedPreflight` 是推荐前置步骤；创作类命令不要跳过模型查询、估价和 dry-run。
-- 用户没有明确项目组时，不要静默选择；先用 `account info` / `project list` 确认云端当前项目组，并把项目组名称、编号展示给用户；积分摘要中优先展示可扣积分余额，项目组只展示预算余额。
-- 如果 `project current`、`project list`、`account info` 的项目组结论不一致，停止创建任务，重新查询并向用户说明差异；不要带着冲突状态估价或提交。
+- 默认项目组优先级和积分口径见 [`driver.md`](driver.md) 的状态账本与 [`../references/output-fields.md`](../references/output-fields.md)；若 `project current` / `project list` / `account info` 项目组不一致先停下来澄清。
+- **`--project-group-no` 默认必传**：`image` / `video` 的 fee / create / create-batch 不传该参数时，后端会跳过项目组预算隔离检查，扣的是账号通用积分而不是项目预算，等于把这次消费记到"杂项"账上。即使用户没提项目组，也先 `project current` 拿当前默认项目组带上。`subject *` 和 `create asset` 不接受该参数。
+- schema / requiredOptions / safety 决策口径见 [`driver.md`](driver.md)，不在此重复。
 
-## Schema 决策规则
+## 模型到任务参数决策流程
 
-Agent 读取 `lj-awb schema -f json` 后，按以下顺序决策：
+把"目的"拆成模型能力和创建参数：
 
-1. 根据用户任务选择 `domain` 和 `command`，必要时用 `lj-awb schema --domain <domain> --command <command> -f json` 缩小上下文。
-2. 检查 `requiredOptions`，缺字段就先追问或通过查询命令补齐。
-3. 检查 `requiredAnyOptions`，每个分组至少满足一个字段，例如视频创建需要 `prompt`、`resource`、`resourcesJson` 中至少一个。
-4. 检查 `safety`，如果 `requiresConfirmation=true` 或 `costsPoints=true`，先确认缺失关键参数，再跑 fee / dry-run，最后向用户确认后追加 `--yes`。
-5. 执行后根据 `workflow.nextActions` 判断下一步，例如提交任务后等待 `task wait`。
+1. 任务类型分流：生图 `model image-models`，生视频 `model video-models`；按目的筛候选。
+2. 「三步走候选展示」（基本信息 → 并行 `model options` → 看完真实选项再追问关键参数）见 [`driver.md`](driver.md)。
+3. 用户确认模型后复用或补跑 `model options` + `model create-spec`；读取字段口径见 [`model.md`](model.md)、读默认 text 见 [`../references/model-options-read.md`](../references/model-options-read.md)。
+4. 按 [`task-manual.md`](task-manual.md) 选资源模式、按 [`create-contract.md`](create-contract.md) 校验素材 / `reference_key` / `<<<key>>>` / `--need-audio`。
+5. `fee` + `create --dry-run` 前确认用户未提供的关键参数候选值；用户确认后才能正式提交。
 
-## 模型到任务参数决策流程
+意图 → 模型能力关键词速查：
 
-创作类任务不要从用户一句话直接进入 `image create` / `video create`。Agent 必须先把“目的”拆成模型能力和创建参数：
-
-1. 判断任务类型：生图用 `model image-models`，生视频用 `model video-models`。
-2. 按用户目的筛候选，例如参考图、首帧、主体一致性、速度、清晰度。
-3. 展示候选模型的 `displayName`、`modelGroupCode`、`provider`、`feeCalcType`、`modelStatus`、`taskQueueNum`，以及必要的 `inputModes` / `params`；模型列表摘要只用于初筛，不要直接生成最终能力结论。
-4. 用户确认模型后先运行 `model options --model-group-code <code> -f json`。
-5. 读取 `params[].values` / `params[].defaultValue` 和 `resources[]`，把可控参数映射为 CLI 参数并校验素材限制。
-6. 再运行 `model create-spec --model-group-code <code> -f json`。
-7. 读取 `inputRequirement` 和 `supportedIntents` 判断当前用户意图是否被模型支持。
-8. 读取 `validationRules` 和 `agentGuidance` 做创建前检查和回复约束。
-9. 按 [`task-manual.md`](task-manual.md) 选择素材语法，并组装最终 prompt；如有可见文本变化，先展示给用户。
-10. 在 `fee` / `create --dry-run` 前确认用户未提供的关键参数候选值；用户确认后再估价和预览请求。
-11. 跑 `fee` 和 `create --dry-run`，再向用户确认。
-
-关键原则：
-
-- `model options` 是 Agent 创建任务前查看参数、素材约束和条件约束的入口；`model create-spec` 负责说明如何组装创建任务。
-- 资源语法（`image:reference` / `audio:reference` / `subject:reference` / `image:first_frame` / `image:last_frame`）和 `reference_key` / `<<<key>>>` 的使用规则统一在 [`create-contract.md`](create-contract.md) §资源语法 / §Prompt 组装原则，本模块不再重复，遇到歧义以该模块为准。
-- 如果用户说“我要用一张参考图生成视频”，优先找 `supportedIntents.mode=reference` 的视频模型。
-- 如果用户说“上传音频 / 使用音乐 / 配音 / 音频参考”，必须先找 `model options.resources[]` 中的 `mediaType=AUDIO usage=reference`；存在时才能传入音频参考，不要仅凭 `supportedIntents.mode=reference` 判断支持音频，也不要把音频文件当成 `--need-audio`。
-- 如果用户说“首尾帧过渡”，优先找 `supportedIntents.mode=frames` 且 usage 包含 `last_frame`。
-- 如果用户说“固定角色长期复用”，先走 `subject publish`，再用 `subject:reference:<key>=asset:<externalId>` 作为 reference 资源。
-- 如果 `inputRequirement.visualInputRequired=true`，必须让用户提供参考图、首帧、首尾帧或主体 externalId；不要提交纯 prompt。
-- 不要默认向用户列“不支持音频参数 / 不支持一次多条”这类负面清单。只有用户明确要求“是否需要输出音效”或单任务多结果时，才检查 `model options.params` 是否有 `needAudio` / `generateNum`。
-- `quality`、`duration`、约束后仍可选的 `ratio`、图片 `generateNum` 这类价格 / 效果参数不能静默用默认值；把 `model options.params[].values` 和默认值列出来，请用户选择或确认“按默认”后再 fee / dry-run。
-- 费用确认时优先说 `billingPointBalance -> billingPointRemainingAfter`，这是实际可扣积分；`projectBudgetBalance -> projectBudgetRemainingAfter` 只作为项目组预算信息补充。
+- "参考图生视频" → `supportedIntents.mode=reference`。
+- "上传音频 / 配音 / 音频参考" → `model options.resources[]` 含 `mediaType=AUDIO usage=reference`；不要把音频塞给 `--need-audio`。
+- "首尾帧过渡 / 仅尾帧" → `supportedIntents.mode=frames` 且 frames 资源 `usage` 包含 `last_frame`。
+- "固定角色长期复用" → 先 `create subject` 拿 externalId，再用 `subject:reference:<key>=asset:<externalId>`。
+- `inputRequirement.visualInputRequired=true` 时不能纯 prompt 创建。
 
 任务选型细节见 [`task-manual.md`](task-manual.md)；多轮对话反模式见 [`evals.md`](evals.md)。
 
 ## 参考图生成视频
 
-适用于用户给一张本地图片或 URL，希望生成一段视频。
-
 ```bash
 lj-awb model video-models --model Seedance
 lj-awb model options --model-group-code <modelGroupCode> -f json
 lj-awb model create-spec --model-group-code <modelGroupCode> -f json
-```
-
-如果用户没有指定画质、时长或约束后仍可选的比例，先给出候选值让用户选择；用户确认后再执行：
 
-```bash
-lj-awb video fee \
-  --model-group-code <modelGroupCode> \
-  --prompt "<user prompt>" \
+lj-awb create video-fee --model-group-code <code> --prompt "<...>" \
   --resource image:reference=<path-or-url> \
-  --ratio <ratio> \
-  --quality <quality> \
-  --duration <seconds> \
-  --project-group-no <projectGroupNo> \
-
+  --ratio <ratio> --quality <quality> --duration <seconds> \
+  --project-group-no <projectGroupNo>
 
-lj-awb video create \
-  --model-group-code <modelGroupCode> \
-  --prompt "<user prompt>" \
+lj-awb create video --model-group-code <code> --prompt "<...>" \
   --resource image:reference=<path-or-url> \
-  --ratio <ratio> \
-  --quality <quality> \
-  --duration <seconds> \
-  --project-group-no <projectGroupNo> \
-  --dry-run \
+  --ratio <ratio> --quality <quality> --duration <seconds> \
+  --project-group-no <projectGroupNo> --task-record-file .awb/tasks.jsonl --dry-run
 
+# 用户确认后把 --dry-run 换成 --yes 正式提交，再 task wait --task-id <id> --task-type VIDEO_GROUP
 ```
 
-确认点：
-
-- 向用户确认模型组、比例、清晰度、时长、参考图、最终 prompt 文本、预估积分、可扣积分余额和项目组预算。
-- 用户确认后，把 `--dry-run` 换成 `--yes` 正式提交。
-- 提交成功后使用返回的 `nextCommand` 或自行调用 `task wait`。
-
-```bash
-lj-awb video create \
-  --model-group-code <modelGroupCode> \
-  --prompt "<user prompt>" \
-  --resource image:reference=<path-or-url> \
-  --ratio <ratio> \
-  --quality <quality> \
-  --duration <seconds> \
-  --project-group-no <projectGroupNo> \
-  --task-record-file .awb/tasks.jsonl \
-  --yes \
-
-
-lj-awb task wait \
-  --task-id <id> \
-  --task-type VIDEO_GROUP \
-  --project-group-no <projectGroupNo> \
-  --wait-seconds 300 \
-
-```
+向用户确认：模型组、比例、清晰度、时长、参考图、最终 prompt、预估积分、可扣积分余额、项目组预算。
 
 ## 主体参考生成视频
 
-适用于角色会被多次复用的场景。先发布主体，再用主体 externalId 创建视频。
+角色多次复用走主体；详细命令、参数和 wait 流程见 [`subject.md`](subject.md)：
 
-```bash
-lj-awb subject publish \
-  --name <subjectName> \
-  --primary-file <imagePath> \
-  --dry-run \
-
-
-lj-awb subject publish \
-  --name <subjectName> \
-  --primary-file <imagePath> \
-  --yes \
-
-
-lj-awb subject wait \
-  --element-id <elementId> \
-  --wait-seconds 300 \
-
-```
-
-后续视频创建：
-
-```bash
-lj-awb video create \
-  --model-group-code <modelGroupCode> \
-  --prompt "<<<subjectKey>>> <action prompt>" \
-  --resource subject:reference:<subjectKey>=asset:<externalId> \
-  --duration <seconds> \
-  --project-group-no <projectGroupNo> \
-  --yes \
-
-```
-
-规则：
-
-- `subject wait` 成功后优先使用返回的 `nextRefSubject`，不要手写 `asset:<externalId>`。
-- 角色需要长期复用时走主体；一次性参考图可以直接用 `image:reference`。
-- prompt 中的 `<<<subjectKey>>>` 必须和 `--resource subject:reference:<subjectKey>=...` 的 key 对齐。
+1. `create subject --model-code tx|vidu --name <subjectName> --resource primary:<imagePath>` → `create subject-wait --element-id <elementId>` 拿 `externalId`。
+2. `create video --resource subject:reference:<subjectKey>=asset:<externalId>`；prompt 中 `<<<subjectKey>>>` 必须和 reference_key 对齐。
+3. 优先用 `create subject-wait` 返回的 `nextRefSubject`，不要手拼 `asset:<externalId>`。
+4. **必须先 create subject + create subject-wait 拿到 externalId 才能用作 subject 参考**：不要把刚创建返回的 `elementId` 当成 `externalId` 直接写进 `--resource subject:reference:...=asset:<...>`，会被后端拒。
 
 ## 参考图生成图片
 
-```bash
-lj-awb model image-models --model Banana
-lj-awb model options --model-group-code <modelGroupCode> -f json
-lj-awb model create-spec --model-group-code <modelGroupCode> -f json
-```
-
-如果用户没有指定比例、清晰度或生成张数，先给出候选值让用户选择；用户确认后再执行：
-
-```bash
-lj-awb image create \
-  --model-group-code <modelGroupCode> \
-  --prompt "<user prompt>" \
-  --resource image:reference=<path-or-url> \
-  --ratio <ratio> \
-  --quality <quality> \
-  --project-group-no <projectGroupNo> \
-  --dry-run \
-
-```
-
-用户确认后：
+完整命令面见 [`image.md`](image.md)；最小骨架：
 
 ```bash
-lj-awb image create \
-  --model-group-code <modelGroupCode> \
-  --prompt "<user prompt>" \
+lj-awb model image-models --model <keyword>
+lj-awb model options --model-group-code <code> -f json
+lj-awb create image --model-group-code <code> --prompt "<...>" \
   --resource image:reference=<path-or-url> \
-  --ratio <ratio> \
-  --quality <quality> \
-  --project-group-no <projectGroupNo> \
-  --yes \
-
+  --ratio <ratio> --quality <quality> \
+  --project-group-no <projectGroupNo> --dry-run
+# 用户确认后把 --dry-run 换成 --yes
 ```
 
 ## 批量任务
@@ -226,7 +103,7 @@ lj-awb image create \
 ```
 
 ```bash
-lj-awb video create-batch \
+lj-awb create video-batch \
   --input-file ./video.jsonl \
   --model-group-code <modelGroupCode> \
   --project-group-no <projectGroupNo> \
@@ -254,7 +131,7 @@ lj-awb task record-poll \
 - 批量任务必须使用 `--task-record-file`，否则 Agent 难以恢复上下文。
 - 单条失败不代表整批失败；读取每项 `status`、`taskId`、`error` 再汇总。
 - 不要把全部结果原始 JSON 粘给用户，只汇报成功数、失败数、任务 ID 和结果 URL。
-- **不要用 `image create` / `video create` 单条循环跑 ≥2 个同模型同参数任务**：识别到这种场景，先告知用户可以走 batch + 并行（n 个任务、预估耗时、单次估价 × n），询问后再决定走 batch 还是单条。
+- **不要用 `create image` / `create video` 单条循环跑 ≥2 个同模型同参数任务**：识别到这种场景，先告知用户可以走 batch + 并行（n 个任务、预估耗时、单次估价 × n），询问后再决定走 batch 还是单条。
 
 ## 分镜流水线（分镜图 → 视频）
 
@@ -270,7 +147,7 @@ lj-awb task record-poll \
 2. 批量生分镜图（GPT Image 2 通道，并行 4）：
 
    ```bash
-   lj-awb image create-batch \
+   lj-awb create image-batch \
      --input-file ./image.jsonl \
      --model-group-code GPT2_ImageCreate_Group_Discount \
      --project-group-no <projectGroupNo> \
@@ -297,7 +174,7 @@ lj-awb task record-poll \
 5. 批量生视频（视频模型通道，并行 3）：
 
    ```bash
-   lj-awb video create-batch \
+   lj-awb create video-batch \
      --input-file ./video.jsonl \
      --model-group-code <video-model-group-code> \
      --project-group-no <projectGroupNo> \
@@ -311,11 +188,11 @@ lj-awb task record-poll \
 - 步骤 2 / 5 提交前各做一次 `--dry-run`，把请求体打给用户看，确认 prompt 和参考图无误。
 - 单次价格 × n 后总积分超过 50 或项目预算接近耗尽时，必须先向用户确认。
 - 步骤 4 复用步骤 2 的结果时，资源 `source.value` 必须用 `backendPath`（`material/...`）形式，不要复制 `result.url` 字段里的完整 https URL。
-- 中途要修改单个镜头 prompt 时，单独跑 `image create` / `video create`，不要全批重跑。
+- 中途要修改单个镜头 prompt 时，单独跑 `create image` / `create video`，不要全批重跑。
 
 ## 预上传后批量复用
 
-适用：同一份参考图 / 首帧 / 音频要在多个任务里使用（典型场景：批量生图 / 生视频跑同一份角色参考）。`image create` / `video create` / `subject publish` 传本地路径**会自动上传**，但每个任务都重新上传同一份文件浪费时间和带宽；先 `upload files` 拿到 `backendPath`，再喂给所有下游任务。
+适用：同一份参考图 / 首帧 / 音频要在多个任务里使用（典型场景：批量生图 / 生视频跑同一份角色参考）。`create image` / `create video` / `create subject` 传本地路径**会自动上传**，但每个任务都重新上传同一份文件浪费时间和带宽；先 `upload files` 拿到 `backendPath`，再喂给所有下游任务。
 
 ```bash
 lj-awb upload files \
@@ -327,7 +204,7 @@ lj-awb upload files \
 读取响应 `data.uploads[].backendPath`（形如 `material/...`），把这个值（**不是 `url` 字段**）写入下游：
 
 ```bash
-lj-awb video create-batch \
+lj-awb create video-batch \
   --input-file ./video.jsonl \
   --model-group-code <modelGroupCode> \
   --project-group-no <projectGroupNo> \
@@ -345,54 +222,54 @@ lj-awb video create-batch \
 
 规则：
 
-- 只跑 1-2 个任务、且不需要看 backendPath 时，直接把本地路径传给 `image create` / `video create`，让 CLI 自动上传。
+- 只跑 1-2 个任务、且不需要看 backendPath 时，直接把本地路径传给 `create image` / `create video`，让 CLI 自动上传。
 - 跑 ≥3 个同模型同参考素材的任务时，先 `upload files` 拿 `backendPath`，再批量复用。
 - `source.value` 必须是 `material/...` 这类 `backendPath`，**不要**复制返回的 `url`（完整 https） — 详见 [`upload.md`](upload.md) 规则。
 
 ## 素材库加白后生视频
 
-适用：Seedance / BytePlus / 即梦系列视频模型，要求参考图先在素材库登记并完成"加白"才能用于生视频。可灵 / KeLing 系列不走 asset，改走 [主体参考生成视频](#主体参考生成视频)。
+适用：Seedance / BytePlus / 即梦系列视频模型，要求参考图先在素材库登记并完成"加白"才能用于生视频。可灵 / KeLing 和 Vidu 系列可走 [主体参考生成视频](#主体参考生成视频)，不走 asset。
 
 ```bash
 # 1. 找/建分组
-lj-awb asset groups --name "项目X-角色"
-lj-awb asset group-create --name "项目X-角色" --dry-run
-lj-awb asset group-create --name "项目X-角色" --yes
+lj-awb create asset-groups --name "项目X-角色"
+lj-awb create asset-group --name "项目X-角色" --dry-run
+lj-awb create asset-group --name "项目X-角色" --yes
 
 # 2. 注册参考图（本地文件版，--file 在 --yes 阶段自动上传 + 注册一步完成）
-lj-awb asset register \
+lj-awb create asset \
   --group-id <groupId> \
   --file ./hero.png \
   --name "主角正面" \
   --dry-run
 
-lj-awb asset register \
+lj-awb create asset \
   --group-id <groupId> \
   --file ./hero.png \
   --name "主角正面" \
   --yes
 
-# 3. 等加白审核（asset register 返回 taskId 时必须等终态）
+# 3. 等加白审核（create asset 返回 taskId 时必须等终态）
 lj-awb task wait \
   --task-id <id> \
   --task-type ASSET_REGISTER \
   --wait-seconds 180
 
 # 4. 加白成功后拿到的 assetPath 用于视频创建
-lj-awb video fee \
+lj-awb create video-fee \
   --model-group-code <seedance-code> \
   --prompt "<...>" \
   --resource image:reference=material/assets/hero.png \
   --project-group-no <projectGroupNo>
 
-lj-awb video create \
+lj-awb create video \
   --model-group-code <seedance-code> \
   --prompt "<...>" \
   --resource image:reference=material/assets/hero.png \
   --project-group-no <projectGroupNo> \
   --dry-run
 
-lj-awb video create \
+lj-awb create video \
   --model-group-code <seedance-code> \
   --prompt "<...>" \
   --resource image:reference=material/assets/hero.png \
@@ -402,7 +279,7 @@ lj-awb video create \
 
 规则：
 
-- 用户描述"我有这样一个角色，平台上有没有现成的"时，先跑 `asset match-actor --description ... --tags-json '...'`，命中合适候选就跳过 register。
+- 用户描述"我有这样一个角色，平台上有没有现成的"时，先跑 `create asset-match-actor --description ... --tags-json '...'`，命中合适候选就跳过 register。
 - 加白未终态时直接拿 `assetPath` 喂给视频，平台会拒；必须先 `task wait` 到 `taskStatus=success`。
 - 同一角色后续视频任务复用同一 `assetPath`，不要每次重新 register。
 - asset 系列只服务于 Seedance / BytePlus / 即梦，**不要**把 `assetPath` 当成可灵的 `subject:reference` 用，反之亦然。
@@ -479,4 +356,4 @@ lj-awb artifact clip update-status \
 
 - 不要在 import 失败后默认建议"全删重来"；先看错误类型 — argument_error 直接修文件重跑；部分 upsert 失败用单条补写。
 - 删除是云端写入（虽然是逻辑删除），必须 `--dry-run` + `--yes` 两步走，不要看到 batch 报错就静默跑 delete。
-- artifact 系列写入失败不会扣积分；只有创作类（image/video/asset register/subject publish）才有费用，恢复时不需要重新跑 `credits balance`。
+- artifact 系列写入失败不会扣积分；只有创作类（image/video/create asset/create subject）才有费用，恢复时不需要重新跑 `credits balance`。

package/skills/lj-awb/references/error-codes.md

@@ -14,13 +14,16 @@ CLI 失败时 envelope 形如：
 |---------:|------------|------|----------------|
 | `0` | — | 成功 | 继续后续步骤 |
 | `1` | `runtime_error` / `api_error` | 平台业务失败或一般运行异常 | 看 `message` / `details`；不要自动重试相同请求 |
+| `1` | `subject_failed` | 主体创建任务已失败 | 看 `details.errorMessage`，调整参考资源 / 模型后重新创建 |
+| `1` | `subject_voice_failed` | 主体音色创建任务已失败 | 看 `details.errorMessage`，调整音频 / 视频来源后重新创建 |
 | `2` | `argument_error` | 必填参数缺失、参数格式 / 枚举不合法 | 按 `hint` 补参数；用 `lj-awb schema --command <name> -f json` 查 `requiredOptions / requiredAnyOptions` |
 | `2` | `unknown_command` / `unknown_option` | 命令名 / 参数名打错 | 跑 `lj-awb -h` 或对应子域 `lj-awb <domain> -h` 重查命令 |
 | `3` | `auth_required` | 缺少 access key | 提示用户 `lj-awb auth login --access-key <key> --yes` 或设置 `LINGJING_AWB_ACCESS_KEY` |
 | `3` | `auth_failed` | access key 无效 / 已过期（HTTP 401） | 跑 `auth verify` 确认；提示重新登录 |
 | `10` | `confirmation_required` | 写入 / 扣费 / 切换上下文动作未确认 | 向用户复述 `details.action` 后追加 `--yes` 重跑 |
 | `20` | `task_still_running` | 等待窗口结束但任务未终态 | 直接续跑 `task wait --task-id ... --wait-seconds <n>`，**不代表失败** |
-| `20` | `subject_still_pending` | 主体 externalId 尚未回填 | 续跑 `subject wait --element-id ... --wait-seconds <n>` |
+| `20` | `subject_still_pending` | 主体 externalId 尚未回填 | 续跑 `create subject-wait --element-id ... --wait-seconds <n>` |
+| `20` | `subject_voice_still_pending` | 主体音色 externalId 尚未回填 | 续跑 `create subject-voice-wait --voice-record-id ... --wait-seconds <n>` |
 | `30` | `network_error` | TLS / DNS / 连接失败 / 平台 5xx | 检查网络；macOS 证书问题用 `lj-awb`（shell wrapper）而不是直接 `node bin/lj-awb.js` |
 | `30` | `http_error` | 非 401 的 HTTP 错误（4xx / 5xx） | 看 `message`；429 等限流时退避重试 |
 | `30` | `upload_failed` | COS 上传失败 | 重试一次；持续失败检查文件大小 / mimeType / 网络 |
@@ -92,11 +95,15 @@ lj-awb auth verify           # 实际打一次平台 API
 - 模型不可用：跑 `model image-models` / `video-models` 看 `taskQueueNum` 和上下架状态。
 - 项目组无权限：跑 `project list` 看用户在哪个项目组，必要时 `project use --project-group-no <no> --yes`。
 
-## 与 `task wait` / `subject wait` 的边界
+### 场景 8：api_error code=1007（视频素材模式混用）
 
-`exit 20` 是**预期内的"还没到终态"**信号，agent 看到不要慌、不要重提任务，直接续 wait 即可。只有当：
+```text
+{"status":"error","error":{"type":"api_error","message":"CLI 视频任务暂不支持 first_frame/last_frame 与 reference 混用","details":{"code":1007}}}
+```
+
+`create video` 的两种素材模式不能同时出现：
 
-- 同一任务连续多轮（默认 `wait-seconds=180`，4-5 轮共 12-15 分钟）仍未终态
-- 或 `task wait` 输出 `taskStatus=FAILED` / `errorMessage` 非空
+- **frames 模式**：`image:first_frame` / `image:last_frame`
+- **reference 模式**：`image:reference` / `audio:reference` / `video:reference` / `subject:reference`
 
-才是真正的失败，需要按 `errorMessage` 处理（积分 / 模型 / 资源 / 参数）。
+恢复路径：把 `image:first_frame=<source>` 改成 `image:reference=<source>`，让所有素材都在 reference 模式（保留 audio / video / subject 参考），再 `--dry-run` 复核后重跑。不要简单删掉某个素材，应该统一模式。

package/skills/lj-awb/references/model-options-read.md

@@ -10,7 +10,7 @@
 - `resources[]`：模型暴露的素材媒体约束；这里只给媒体类型、用途和文件限制，不给 `--resource` 写法。
 - `media`：素材媒体类型，例如 `IMAGE`、`VIDEO`、`AUDIO`、`SUBJECT`。
 - `usage`：素材用途，例如 `reference`、`first_frame`、`last_frame`、`keyframe`；同一个资源约束可同时列出 `first_frame|last_frame`。
-- `sources=file|url|platformPath|asset`：可接受本地文件、公网 URL、平台上传后返回的 `backendPath`、普通资产 ID。
+- `valueShapes=file|url|platformPath|asset`：声明这个资源 **value 的形状**，可接受本地文件、公网 URL、平台上传后返回的 `backendPath`、平台资产 ID。注意：这不是 `source.kind` 的枚举；`source.kind` 永远只有 `url`、`asset_id` 两种取值——前三种形状统一传 `kind=url`（CLI 按 value 自动识别），最后一种传 `kind=asset_id`。
 - `formats`：文件后缀白名单。
 - `files=<=N` / `files=1`：素材数量约束。
 - `lastFrameOnly` / JSON `supportLastFrameOnly`：只表示是否支持“仅尾帧”这种特殊输入；不用于判断 `first_frame + last_frame` 是否成立。没有该能力时，尾帧应和首帧成对使用。
@@ -42,7 +42,7 @@ JSON 里会保留更完整的参数 / 资源 / 条件约束字段，但仍不承
 - 不在 `params[]` 里的 CLI 参数不要传。
 - 不在 `resources[]` 里的媒体类型 / 用途不要硬拼。
 - 当前用户输入满足 `constraints[].conditions` 时，按 `allowValues` 收窄目标参数；`effect=no_selectable_values` 时不要传该目标参数。
-- 主体参考看 `media=SUBJECT usage=reference sources=asset`；reference_key 和 externalId 写法看 `model create-spec` / `model input-guide`。
+- 主体参考看 `media=SUBJECT usage=reference valueShapes=asset`；reference_key 和 externalId 写法看 `model create-spec` / `model input-guide`。
 - 图片生图参考图不使用 reference_key；只传 `image:reference=...`，prompt 里用图一、图二、参考图等自然描述。
 - 音频素材参考看 `media=AUDIO usage=reference`；`needAudio` / `--need-audio` 表示是否需要输出音效。
 - `media=IMAGE` 的 `supportedFileTypes` 是 webp 能力标记：空表示不支持 webp，单独 `webp` 表示普通图片格式外也支持 webp，多值才表示强允许列表。默认 text 里 `webpInput=accepted` 表示可直接传 webp；`webpInput=autoConvertToJPG` 表示本地 webp 会先转成 jpg。