@lingjingai/lj-awb-cli-pre 0.3.15

package/skills/lj-awb/modules/task-manual.md

@@ -0,0 +1,185 @@
+# Task Manual Module
+
+本模块是面向用户 / Agent 的任务手册：先判断用户真正要完成什么，再选择模型、素材语法和创建参数。不要从一句话直接拼 `image create` / `video create`。
+
+## 创作前固定流程
+
+1. 运行 `lj-awb doctor --verify`，确认认证、API、项目组、UTF-8。
+2. 运行 `model image-models` 或 `model video-models`，按用户目标筛 2-4 个候选。
+3. 用户选定模型后运行 `model options --model-group-code <code> -f json`，读取参数取值和素材约束。
+4. 再运行 `model create-spec --model-group-code <code> -f json`。
+5. 用 `inputRequirement` 判断是否必须有视觉输入；用 `supportedIntents` 判断素材模式；用 `model options.params` 判断 `ratio`、`quality`、`duration` 等枚举。
+6. 在 `fee` 或 `create --dry-run` 前，先确认用户未提供但会影响价格 / 效果的关键参数：视频 `quality`、`duration`、约束后仍可选的 `ratio`，以及用户明确要输出音效时的 `needAudio`；图片 `quality`、`ratio`、`generateNum`。
+7. 组装最终 prompt：以用户明确创作描述为基底，操作性指令只用于模型和资源选择；没有明确需求时先追问或用最小中性表达；只有视频 reference / subject 需要占位绑定时才考虑 `<<<key>>>`，并先展示最终文本。
+8. 用户确认关键参数和最终 prompt 后，先 `fee`，再 `create --dry-run`。
+9. 用户确认模型、项目组、最终 prompt、素材、参数和预估积分后，才加 `--yes`。
+
+## 确认选项和验证拆开
+
+- `model options` / `model create-spec` 是只读验证，可以先跑，用来收集候选值、默认值、素材模式和约束。
+- `fee` 会基于已选参数估价，`create --dry-run` 会基于已选参数组装请求；如果用户还没给 `quality`、`duration`、可选 `ratio`、`generateNum` 这类关键参数，先问用户，不要先用默认值跑一遍。
+- 追问时给出候选值和默认值，例如：“还差会影响价格 / 效果的参数：画质 720 / 1080（默认 720），时长 3-15 秒（默认 5）。你希望用哪组？”
+- 用户回复“按默认”后，才可以使用 `model options.params[].defaultValue` 继续估价和 dry-run。
+- 如果 `model options.constraints[]` 命中后让某个参数 `effect=no_selectable_values`，不要追问或传入该参数。
+
+## 任务选择速查
+
+| 用户目标 | 资源语法 | Prompt 处理 | 典型命令 |
+|----------|----------|-------------|----------|
+| 参考图生视频 | `--resource image:reference=<source>`；需要明确绑定时才用 `:key` | 普通参考不需要 `<<<key>>>`；显式绑定时 prompt 才出现同名占位符 | `video create` |
+| 让这张图动起来 / 从这张图开始 | `--resource image:first_frame=<source>` | 不需要 `<<<key>>>` | `video create` |
+| 首尾帧过渡 | `--resource image:first_frame=... --resource image:last_frame=...` | 不需要 `<<<key>>>` | `video create` |
+| 使用音乐 / 配音 / 音频参考 | `--resource audio:reference=<source>` | 只有需要引用具体音频对象时才加 key | `video create` |
+| 固定角色长期复用 | `subject publish` -> `subject wait` -> `--resource subject:reference:<key>=asset:<externalId>` | key 必填；是否写入 prompt 取决于用户表达 | `subject` + `video create` |
+| 参考图生图 | `--resource image:reference=<source>` | 不使用 key / `<<<>>>`；用“图一 / 图二 / 参考图 / 主体”等自然语言指代 | `image create` |
+
+`<source>` 可以是本地文件、material backendPath、完整 URL，或普通素材 `asset:<assetId>`；主体引用的 `asset:<externalId>` 只用于 `subject:reference`。
+
+`<source>` 优先级（**Agent 必须遵守**）：
+
+1. **平台已有素材** → 一律使用 `backendPath`（`material/...` 或 `/material/...`）。`lj-awb upload files` 返回的 `backendPath`、历史任务结果里的 COS 对象路径都属于这一类。
+2. **本地文件** → 直接传文件路径，CLI 会自动上传并改写为 `backendPath`。
+3. **真正外部公网素材** → 才用完整 https URL（例如用户自己贴的第三方域名链接）。
+
+不要把上传命令回显的 `url`（`https://*.myqcloud.com/material/...`）当作 `source.value` 重新塞回任务请求 — CLI 虽然会做自愈剥离，但请求体冗余且容易在跨命令复制时出错。
+
+## 参考图生图
+
+适合用户说“用这张参考图生成图片”“保持图一人物表情，在图二场景里做某事”。生图模型没有 `reference_key` 绑定，素材映射靠 prompt 的自然描述和资源顺序。
+
+```bash
+lj-awb image create \
+  --model-group-code <modelGroupCode> \
+  --prompt "图一中的白发女保持金鱼嘴表情，在图二背景里坐秋千" \
+  --resource image:reference=<firstSource> \
+  --resource image:reference=<secondSource> \
+  --ratio <allowedRatio> \
+  --quality <allowedQuality> \
+  --project-group-no <projectGroupNo> \
+  --dry-run \
+
+```
+
+判断要点：
+
+- 不要写 `image:reference:hero=...`、`reference_key` 或 `<<<hero>>>`。
+- 不要替用户自动生成 key；如果用户说“白发女 / 背景 / 图一 / 图二”，直接保留这些自然指代。
+- 用户未给 `ratio`、`quality`、`generateNum` 时，先给候选值和默认值让用户确认，再估价或 dry-run。
+
+## 参考图生视频
+
+适合用户说“参考这张图”“引用这个角色 / 构图 / 风格”“根据这张图生成视频”。普通参考不需要 key；只有用户需要在 prompt 中明确绑定某个对象时才用 `image:reference:<key>`，如果 prompt 写了占位符，必须有同名 reference 资源。
+
+```bash
+lj-awb video create \
+  --model-group-code <modelGroupCode> \
+  --prompt "<<<hero>>> 选择跳跃" \
+  --resource image:reference:hero=<source> \
+  --duration <seconds> \
+  --ratio <allowedRatio> \
+  --quality <allowedQuality> \
+  --project-group-no <projectGroupNo> \
+  --dry-run \
+
+```
+
+判断要点：
+
+- 用户只说“动作是选择跳跃”时，可以组装为 `<<<hero>>> 选择跳跃`，但不要额外加风格词。
+- 视频参考图已经通过 `image:reference:<key>` 传入时，不要把图片内容自动写成“山谷风景、室内场景、某种服装”等 prompt 文案；用 `<<<key>>>` 代表该参考对象即可。
+- 用户说“一个女人在图片上走动 一边说音频。使用 sd2fast参考生”时，正确处理是把 `sd2fast / 参考生` 当成模型和资源选择，把创作描述保留为接近 `<<<scene>>> 一个女人在图片上走动 一边说音频`，不要改成“山谷风景中、自然走动、口型跟随参考音频”。
+- 用户明确说“prompt 就用选择跳跃”时，先确认是否允许补成 `<<<hero>>> 选择跳跃`。
+- 如果模型 `inputRequirement.visualInputRequired=true`，不能只用 prompt 创建。
+
+## 首帧 / 首尾帧生视频
+
+适合用户说“让这张图动起来”“以这张图作为第一帧”“从 A 过渡到 B”。首帧和尾帧是画面起止状态，不是 reference subject，因此通常不需要 `<<<key>>>`。
+
+```bash
+lj-awb video create \
+  --model-group-code <modelGroupCode> \
+  --prompt "镜头推进，人物缓慢转身" \
+  --resource image:first_frame=<firstSource> \
+  --resource image:last_frame=<lastSource> \
+  --duration <seconds> \
+  --project-group-no <projectGroupNo> \
+  --dry-run \
+
+```
+
+判断要点：
+
+- 只有首帧时只传 `image:first_frame=...`。
+- 传 `image:last_frame=...` 前先确认 `model options.resources[].usage` 或 `model create-spec.supportedIntents[].usage` 包含 `last_frame`；`supportLastFrameOnly=false` 只是不支持仅尾帧。
+- 没有 `supportLastFrameOnly=true` 时，不要只传 `image:last_frame=...`；尾帧应和首帧成对表达起止画面。
+- 首尾帧都可以用本地文件、完整 URL、material backendPath 或 `asset:<assetId>`。
+- 不要把首帧资产误写成 `subject:reference`；主体引用只用于可复用主体 externalId。
+
+## 音频参考
+
+用户上传音频、指定音乐、配音、节奏参考时，这是素材输入，不是 `--need-audio`。
+
+```bash
+lj-awb video create \
+  --model-group-code <modelGroupCode> \
+  --prompt "<<<hero>>> 按音乐节奏跳舞" \
+  --resource image:reference:hero=<heroImage> \
+  --resource audio:reference=<audioSource> \
+  --duration <seconds> \
+  --project-group-no <projectGroupNo> \
+  --dry-run \
+
+```
+
+判断要点：
+
+- 固定使用 `audio:reference`，不要使用 `audio:source`。
+- 用户强调“音频也要参考 / 显式参考音频”时，可以使用 `audio:reference:voice=<audioSource>`，并在 prompt 中插入 `<<<voice>>>` 这类同名占位符。
+- 用户明确要输出音效时，先确认模型暴露 `needAudio`，再使用 `--need-audio true/false`；它不是上传音频入口。
+- 不要因为 `needAudio` 不存在就说“模型不支持音频参考”；音频参考能力只看 `model options.resources[]` 是否存在 `mediaType=AUDIO usage=reference`。
+
+## 主体复用
+
+适合用户要“这个角色以后反复使用”“保持同一角色一致性”。一次性参考图不需要先发布主体。
+
+```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
+
+lj-awb video create \
+  --model-group-code <modelGroupCode> \
+  --prompt "<<<hero>>> 转身看向镜头" \
+  --resource subject:reference:hero=asset:<externalId> \
+  --duration <seconds> \
+  --project-group-no <projectGroupNo> \
+  --dry-run \
+
+```
+
+判断要点：
+
+- `subject wait` 成功后优先使用返回的 `nextRefSubject`。
+- `subject:reference:<key>=asset:<externalId>` 的 `asset:` 后面是主体 externalId，不是普通图片 assetId。
+- prompt 中出现 `<<<key>>>` 时必须有同名 reference 资源；不出现时不强制补。
+
+## 创建前确认清单
+
+正式提交前，向用户确认这些不可替代信息：
+
+- 模型组：`displayName` 和 `modelGroupCode`。
+- 项目组：名称、编号、项目组预算余额；不要把项目组预算余额当作实际可扣积分余额。
+- 最终 prompt：如果做了占位符补齐、资源绑定或用户要求的提示词优化，要让用户确认实际提交文本。
+- 素材：每个资源的 type、usage、key、来源。
+- 参数：ratio、quality、duration、generate-num、need-audio 等只列实际使用项；没有由用户明确给出时，必须在 fee / dry-run 前完成选择确认。
+- 费用：预估积分、`billingPointBalance -> billingPointRemainingAfter` 实际可扣积分变化，以及 `projectBudgetBalance -> projectBudgetRemainingAfter` 项目组预算变化。

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

@@ -0,0 +1,62 @@
+# Task Module
+
+任务模块负责图片 / 视频 / 字幕等异步任务的等待、查询和台账恢复。所有异步任务必须先用 `image create` / `video create` / `subject publish` 拿到 `taskId` 或 `elementId`，再来这里。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb task list --task-type IMAGE_CREATE --project-group-no <no>` | 列出远端任务（按类型过滤） |
+| `lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180` | 等待单个任务进入终态 |
+| `lj-awb task records --task-record-file .awb/tasks.jsonl` | 读本地任务台账（未指定 `--task-record-file` 默认 `.awb/tasks.jsonl`） |
+| `lj-awb task records --pending-only --task-record-file .awb/tasks.jsonl` | 只看未终态记录 |
+| `lj-awb task record-poll --task-record-file .awb/tasks.jsonl --wait-seconds 180` | 一次性轮询台账里所有未终态任务 |
+
+## 典型使用场景
+
+### 单任务等待
+
+```bash
+# image / video create 返回 taskId 后立刻：
+lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180
+```
+
+返回 `task_still_running`（exit 20）= 等待窗口结束、任务**未失败**。直接续跑（增大 `--wait-seconds` 或重复几轮）。详见 [`../references/error-codes.md`](../references/error-codes.md) 场景 2。
+
+### 批量恢复
+
+`image create-batch` / `video create-batch` / `subject publish-batch` 默认把每个子任务写到 `.awb/tasks.jsonl`。当对话被打断或机器重启后：
+
+```bash
+# 1. 看还有几条未完
+lj-awb task records --pending-only
+
+# 2. 一键续等所有未完（推荐，免去逐个 wait）
+lj-awb task record-poll --wait-seconds 180
+
+# 3. 终态后做汇总
+lj-awb task records
+```
+
+### 历史查询
+
+不知道 `taskId` 但记得做过：
+
+```bash
+lj-awb task list --task-type VIDEO_GROUP --project-group-no <no>
+```
+
+按 `gmtCreate` 倒序，从最近找。
+
+## 规则
+
+- 异步任务必须保存 `taskId`，批量任务统一传 `--task-record-file .awb/tasks.jsonl`（默认即此路径）。
+- `task wait` 返回 `task_still_running` 时复述 hint，不要误报失败；`taskStatus=FAILED` 或 `errorMessage` 非空才是真失败。
+- 输出字段只提取 `taskId / taskStatus / isTerminal / resultUrls / errorMessage`，详见 [`../references/output-fields.md`](../references/output-fields.md) 的"生图 / 生视频"和"任务台账"小节。
+- 不要把大型 raw JSON 整段塞回上下文。
+- `task list` 是远端查询、`task records` 是本地台账；两者覆盖范围不同（台账只有本机创建的任务）。
+
+## 下一步
+
+- 任务终态 + `resultUrls` 非空 → 视具体场景写回 [`artifact/video.md`](artifact/video.md) (`update-clip-urls`) 或交付给用户。
+- 任务 `FAILED` → 看 `errorMessage`；常见原因（积分 / 模型 / 资源）按 [`../references/error-codes.md`](../references/error-codes.md) 场景 7 处理。

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

@@ -0,0 +1,33 @@
+# Upload Module
+
+上传模块用于把本地文件变成平台可访问素材。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb upload files --files ./a.png,./b.mp4 --dry-run` | 预览上传文件 |
+| `lj-awb upload files --file ./ref.png --scene-type material-video-create` | 上传单个参考素材 |
+| `lj-awb upload files --files-json ./files.json` | 按 JSON 清单上传 |
+
+## 规则
+
+- 上传命令返回 `backendPath`、`url`、`mimeType`、`size`、`width`、`height`。
+- 后续任务的 `source.value` 一律使用 `backendPath`（例如 `material/...` 或 `/material/...`），**不要使用回显的 `url` 字段**。`url` 只是用于人工预览，把完整 `https://*.myqcloud.com/...` 直接塞回任务请求会让请求体冗余，也会破坏请求一致性。
+- 对 Agent 来说，优先使用返回的结构化字段，不要从自然语言输出里猜 URL。
+- 不直接调用或暴露 COS 临时凭证接口。
+- 生图 / 生视频命令传本地参考文件时，会在内部自动上传；只有需要复用素材时才单独调用 `upload files`。
+- 即使把平台 COS 完整 URL 当作 `source.value` 传入，CLI 会自动剥离 host 还原为 `backendPath`；但不要依赖该自愈，仍以传 `backendPath` 为准。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"文件上传"小节；上传失败（exit 30 / `upload_failed`）见 [`../references/error-codes.md`](../references/error-codes.md) 场景 6。
+
+## 下一步
+
+拿到 `uploads[].backendPath`（形如 `material/...`）后立刻就近喂给下游命令，不要重复 upload：
+
+- 生图参考图：`lj-awb image create ... --resource image:reference=material/...`
+- 生视频首帧 / 尾帧 / 参考图：`lj-awb video create ... --resource image:first_frame=material/...`
+- 视频参考音频：`lj-awb video create ... --resource audio:reference=material/...`
+- 主体发布参考图：`lj-awb subject publish ... --resource primary:material/...`
+- 注册到素材库（长期复用）：`lj-awb asset register --group-id <id> --url material/... --name "..." --yes`
+
+> `image create` / `video create` / `subject publish` 传 `--file` / 本地路径时**会自动 upload**——只有需要"先看 backendPath / 跨任务复用同一份素材"时才单独跑 `upload files`。

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

@@ -0,0 +1,102 @@
+# Video Module
+
+视频模块用于生视频模型选择、估价、提交、批量提交、查询和去字幕。创建前必须先读取 `model options` 和 `model create-spec`，确认模型支持目标输入模式和素材约束。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `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 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>` | 查询去字幕任务 |
+
+## 创建参数
+
+| 参数 | 何时使用 | 约束来源 |
+|------|----------|----------|
+| `--prompt` | 视频提示词 | 以用户明确创作描述为基底组装的最终提交文本；没有明确需求时先追问或用最小中性表达 |
+| `--duration` | 指定视频秒数 | `model options.params[key=duration].values` |
+| `--ratio` | 指定画幅比例 | `model options.params[key=ratio].values`，并受 `model options.constraints[]` 联动限制 |
+| `--quality` | 指定清晰度 | `model options.params[key=quality].values` |
+| `--need-audio` | 是否需要输出音效 | 仅 `model options.params[key=needAudio]` 存在，且用户明确要求输出音效时 |
+| `--resource image:reference[:key]=...` | 参考图生视频 | `model create-spec.supportedIntents.mode=reference` 必须存在，格式 / 数量约束看 `model options.resources[]` |
+| `--resource audio:reference=...` | 参考音频 / 配乐 / 配音 / 节奏参考 | `model options.resources[]` 中必须存在 `mediaType=AUDIO usage=reference` |
+| `--resource image:first_frame=...` | 首帧生视频 | `model create-spec.supportedIntents.mode=frames` 必须存在，且 usage 包含 `first_frame` |
+| `--resource image:last_frame=...` | 首尾帧过渡 / 仅尾帧 | `model create-spec.supportedIntents.mode=frames` 必须存在，且 usage 包含 `last_frame` |
+| `--resource subject:reference:<key>=asset:<externalId>` | 长期复用主体 | `model create-spec.supportedIntents.mode=reference` 必须存在 |
+
+## 标准流程
+
+```bash
+lj-awb model video-models --model "<keyword>"
+lj-awb model options --model-group-code <modelGroupCode> -f json
+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
+```
+
+用户确认后：
+
+```bash
+lj-awb video create \
+  --model-group-code <modelGroupCode> \
+  --prompt "<user prompt>" \
+  --resource image:reference:hero=./hero.png \
+  --ratio <allowedRatio> \
+  --quality <allowedQuality> \
+  --duration <allowedSeconds> \
+  --project-group-no <projectGroupNo> \
+  --yes \
+
+```
+
+## 规则
+
+- 视频时长统一用 `--duration`，不要传平台旧字段 `generated_time`。
+- `--prompt` 的重点是组装资源、参数和模型约束；用户没有明确需求时不要主动编内容补空白，用户要求优化时再做提示词创作。
+- 素材统一用 `--resource type:usage[:key]=...` 或 `--resources-json`，不要直接传 `frames` / `multi_param`。
+- `generated_mode` 不需要也不允许用户填写；Material 会根据资源推导 `frames` 或 `multi_param`。
+- 创建前先看 `inputRequirement.visualInputRequired`。如果为 `true`，必须选择 `supportedIntents` 中的一种素材输入，不能纯 prompt 创建。
+- 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.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`。
+- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`duration`、`need_audio`、`resources`、`resource`、`customBizId`；其中 `need_audio` 表示是否需要输出音效，音频素材仍写入 `resources`。
+- 视频任务默认可能耗时较长，批量和复杂任务应异步提交并记录 task id。
+- **多镜头 / 多分镜时主动建议并行**：用户一次给出 ≥2 个同模型同参数的视频任务（典型场景：分镜流水线、批量首尾帧动画）时，Agent 必须先告知"这批可以用 `video create-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 → 继续单条 create。**不要默认一条一条串行还不告知**。
+- 去字幕服务适合处理 Seedance 原始结果链接，不要把无关 CDN 链接误传。
+- 输出字段速查见 [`../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` 批量等。
+- 任务终态 `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。