@lingjingai/lj-awb-cli-pre 0.3.15

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

@@ -0,0 +1,482 @@
+# Workflows Module
+
+本模块描述 Agent 面向任务的标准编排。CLI 只执行确定性命令；Agent 负责把用户输入映射为参数、确认风险、串联命令；prompt 处理重点是组装可执行请求。
+
+## 目录
+
+- [通用启动流程](#通用启动流程) — `doctor` / `schema` / `account info` / `project current`
+- [Schema 决策规则](#schema-决策规则) — 怎么读 schema 选 command 和必填项
+- [模型到任务参数决策流程](#模型到任务参数决策流程) — 模型筛选 → `model options` / `create-spec` → fee → dry-run
+- [参考图生成视频](#参考图生成视频) — 用户给一张图生成一段视频
+- [主体参考生成视频](#主体参考生成视频) — `subject publish` + `subject:reference:<key>`
+- [参考图生成图片](#参考图生成图片) — `image:reference=...`，不用 `<<<key>>>`
+- [批量任务](#批量任务) — `create-batch --concurrency`
+- [分镜流水线（分镜图 → 视频）](#分镜流水线分镜图--视频) — GPT Image 2 分镜 → 视频生成
+- [预上传后批量复用](#预上传后批量复用) — `upload files` 一次，多任务复用 `backendPath`
+- [素材库加白后生视频](#素材库加白后生视频) — Seedance / 即梦的 `asset register` → 视频
+- [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` 的项目组结论不一致，停止创建任务，重新查询并向用户说明差异；不要带着冲突状态估价或提交。
+
+## 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`。
+
+## 模型到任务参数决策流程
+
+创作类任务不要从用户一句话直接进入 `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` 只作为项目组预算信息补充。
+
+任务选型细节见 [`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>" \
+  --resource image:reference=<path-or-url> \
+  --ratio <ratio> \
+  --quality <quality> \
+  --duration <seconds> \
+  --project-group-no <projectGroupNo> \
+
+
+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> \
+  --dry-run \
+
+```
+
+确认点：
+
+- 向用户确认模型组、比例、清晰度、时长、参考图、最终 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 \
+
+```
+
+## 主体参考生成视频
+
+适用于角色会被多次复用的场景。先发布主体，再用主体 externalId 创建视频。
+
+```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 对齐。
+
+## 参考图生成图片
+
+```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 \
+
+```
+
+用户确认后：
+
+```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> \
+  --yes \
+
+```
+
+## 批量任务
+
+批量输入文件每行只写任务差异字段，公共字段放命令行。
+
+```json
+{"prompt":"镜头推进","duration":5,"quality":"720","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"./first.png"}}]}
+```
+
+```bash
+lj-awb video create-batch \
+  --input-file ./video.jsonl \
+  --model-group-code <modelGroupCode> \
+  --project-group-no <projectGroupNo> \
+  --task-record-file .awb/tasks.jsonl \
+  --concurrency 3 \
+  --yes \
+
+
+lj-awb task record-poll \
+  --task-record-file .awb/tasks.jsonl \
+  --pending-only \
+  --wait-seconds 300 \
+
+```
+
+并发数建议（`--concurrency`，默认 1）：
+
+- 生图：默认建议 `--concurrency 4`；上游图片模型并行较稳，账户额度通常可撑。
+- 生视频：默认建议 `--concurrency 3`；视频任务本身耗时长且更易触发上游限流，过高反而拖慢整体。
+- 出现 ≥30% 任务返回 `[任务创建失败]` 或上游 429 / 限流相关错误时，下次重跑降为 1-2。
+- 用户对成本敏感（想观察前几条结果再决定是否继续）时主动建议先 `--concurrency 1` 跑前 1-2 条。
+
+规则：
+
+- 批量任务必须使用 `--task-record-file`，否则 Agent 难以恢复上下文。
+- 单条失败不代表整批失败；读取每项 `status`、`taskId`、`error` 再汇总。
+- 不要把全部结果原始 JSON 粘给用户，只汇报成功数、失败数、任务 ID 和结果 URL。
+- **不要用 `image create` / `video create` 单条循环跑 ≥2 个同模型同参数任务**：识别到这种场景，先告知用户可以走 batch + 并行（n 个任务、预估耗时、单次估价 × n），询问后再决定走 batch 还是单条。
+
+## 分镜流水线（分镜图 → 视频）
+
+适用：用户给出多个镜头描述（例如剧本分镜、storyboard），希望 GPT Image 类模型先按一致角色 / 场景生成分镜图，再用视频模型把每张分镜图动起来。
+
+1. 准备 `image.jsonl`，每行一个镜头的 `prompt` 和共用参考图（人物、场景）：
+
+   ```json
+   {"prompt":"镜头1：徐然推开 502 户门，门缝透出暖光...","ratio":"9:16","quality":"2k","resources":[{"type":"image","usage":"reference","source":{"kind":"url","value":"material/image-edit/<人物参考>"}},{"type":"image","usage":"reference","source":{"kind":"url","value":"material/image-edit/<场景参考>"}}]}
+   {"prompt":"镜头2：徐然侧身贴墙，听门外脚步声...","ratio":"9:16","quality":"2k","resources":[{"type":"image","usage":"reference","source":{"kind":"url","value":"material/image-edit/<人物参考>"}}]}
+   ```
+
+2. 批量生分镜图（GPT Image 2 通道，并行 4）：
+
+   ```bash
+   lj-awb image create-batch \
+     --input-file ./image.jsonl \
+     --model-group-code GPT2_ImageCreate_Group_Discount \
+     --project-group-no <projectGroupNo> \
+     --task-record-file .awb/storyboard.jsonl \
+     --concurrency 4 \
+     --yes
+   ```
+
+3. 轮询全部完成并取结果 URL：
+
+   ```bash
+   lj-awb task record-poll \
+     --task-record-file .awb/storyboard.jsonl \
+     --pending-only --wait-seconds 600
+   ```
+
+4. 把每条 `taskId` 的 `result` 图（COS 对象路径，**用 `backendPath` 形式**）作为视频任务的 `first_frame`，组装 `video.jsonl`：
+
+   ```json
+   {"prompt":"镜头1 动起来：徐然缓慢推门，光线从门缝渐扩","duration":5,"ratio":"9:16","quality":"720","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"material/image-edit/<镜头1结果>"}}]}
+   {"prompt":"镜头2 动起来：徐然贴墙呼吸起伏，听门外动静","duration":5,"ratio":"9:16","quality":"720","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"material/image-edit/<镜头2结果>"}}]}
+   ```
+
+5. 批量生视频（视频模型通道，并行 3）：
+
+   ```bash
+   lj-awb video create-batch \
+     --input-file ./video.jsonl \
+     --model-group-code <video-model-group-code> \
+     --project-group-no <projectGroupNo> \
+     --task-record-file .awb/storyboard-video.jsonl \
+     --concurrency 3 \
+     --yes
+   ```
+
+执行约束：
+
+- 步骤 2 / 5 提交前各做一次 `--dry-run`，把请求体打给用户看，确认 prompt 和参考图无误。
+- 单次价格 × n 后总积分超过 50 或项目预算接近耗尽时，必须先向用户确认。
+- 步骤 4 复用步骤 2 的结果时，资源 `source.value` 必须用 `backendPath`（`material/...`）形式，不要复制 `result.url` 字段里的完整 https URL。
+- 中途要修改单个镜头 prompt 时，单独跑 `image create` / `video create`，不要全批重跑。
+
+## 预上传后批量复用
+
+适用：同一份参考图 / 首帧 / 音频要在多个任务里使用（典型场景：批量生图 / 生视频跑同一份角色参考）。`image create` / `video create` / `subject publish` 传本地路径**会自动上传**，但每个任务都重新上传同一份文件浪费时间和带宽；先 `upload files` 拿到 `backendPath`，再喂给所有下游任务。
+
+```bash
+lj-awb upload files \
+  --files ./hero.png,./scene.png \
+  --scene-type material-video-create \
+  -f json
+```
+
+读取响应 `data.uploads[].backendPath`（形如 `material/...`），把这个值（**不是 `url` 字段**）写入下游：
+
+```bash
+lj-awb video create-batch \
+  --input-file ./video.jsonl \
+  --model-group-code <modelGroupCode> \
+  --project-group-no <projectGroupNo> \
+  --task-record-file .awb/tasks.jsonl \
+  --concurrency 3 \
+  --yes
+```
+
+`video.jsonl` 内每行复用同一份 `backendPath`：
+
+```json
+{"prompt":"镜头1...","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"material/..."}}]}
+{"prompt":"镜头2...","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"material/..."}}]}
+```
+
+规则：
+
+- 只跑 1-2 个任务、且不需要看 backendPath 时，直接把本地路径传给 `image create` / `video create`，让 CLI 自动上传。
+- 跑 ≥3 个同模型同参考素材的任务时，先 `upload files` 拿 `backendPath`，再批量复用。
+- `source.value` 必须是 `material/...` 这类 `backendPath`，**不要**复制返回的 `url`（完整 https） — 详见 [`upload.md`](upload.md) 规则。
+
+## 素材库加白后生视频
+
+适用：Seedance / BytePlus / 即梦系列视频模型，要求参考图先在素材库登记并完成"加白"才能用于生视频。可灵 / KeLing 系列不走 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
+
+# 2. 注册参考图（本地文件版，--file 在 --yes 阶段自动上传 + 注册一步完成）
+lj-awb asset register \
+  --group-id <groupId> \
+  --file ./hero.png \
+  --name "主角正面" \
+  --dry-run
+
+lj-awb asset register \
+  --group-id <groupId> \
+  --file ./hero.png \
+  --name "主角正面" \
+  --yes
+
+# 3. 等加白审核（asset register 返回 taskId 时必须等终态）
+lj-awb task wait \
+  --task-id <id> \
+  --task-type ASSET_REGISTER \
+  --wait-seconds 180
+
+# 4. 加白成功后拿到的 assetPath 用于视频创建
+lj-awb video fee \
+  --model-group-code <seedance-code> \
+  --prompt "<...>" \
+  --resource image:reference=material/assets/hero.png \
+  --project-group-no <projectGroupNo>
+
+lj-awb video create \
+  --model-group-code <seedance-code> \
+  --prompt "<...>" \
+  --resource image:reference=material/assets/hero.png \
+  --project-group-no <projectGroupNo> \
+  --dry-run
+
+lj-awb video create \
+  --model-group-code <seedance-code> \
+  --prompt "<...>" \
+  --resource image:reference=material/assets/hero.png \
+  --project-group-no <projectGroupNo> \
+  --yes
+```
+
+规则：
+
+- 用户描述"我有这样一个角色，平台上有没有现成的"时，先跑 `asset match-actor --description ... --tags-json '...'`，命中合适候选就跳过 register。
+- 加白未终态时直接拿 `assetPath` 喂给视频，平台会拒；必须先 `task wait` 到 `taskStatus=success`。
+- 同一角色后续视频任务复用同一 `assetPath`，不要每次重新 register。
+- asset 系列只服务于 Seedance / BytePlus / 即梦，**不要**把 `assetPath` 当成可灵的 `subject:reference` 用，反之亦然。
+
+## Artifact 流水线错误恢复
+
+适用：把沙箱 / 本地流水线产出回写 AWB 时，`script import` / `asset import` / `video import-storyboard` / `clip upsert-batch` 部分失败的恢复路径。
+
+#### 全量预览，确认无误后再写
+
+整条流水线统一先 `--dry-run`，让用户在一次确认里看完所有变更面（script / asset / video / clip 各跑一遍预览，再统一 `--yes`），避免提交一半发现规模不对。
+
+```bash
+lj-awb artifact script import --project-id "$PROJECT_ID" --input-file 1_script/output/script.json --dry-run
+lj-awb artifact asset import --project-id "$PROJECT_ID" --input-dir 2_asset/output --dry-run
+lj-awb artifact video import-storyboard --project-id "$PROJECT_ID" --input-file 3_footage/output/ep001/ep001_storyboard.json --dry-run
+lj-awb artifact clip upsert-batch --project-id "$PROJECT_ID" --input-file 4_clip/output/ep001_clip_batch.json --dry-run
+```
+
+#### 单文件 import 失败（argument_error / 业务字段错）
+
+`exit=20 error.type=argument_error`：CLI 已经拒绝写入，整条 batch 不会被部分提交。修 JSON 后重跑同一条命令。**不要**手工跑 `delete-*` 回滚，因为云端根本没写入。
+
+#### 单条 upsert 失败（某 scene/clip 字段不合法）
+
+如果是 `upsert-batch` 已经 `--yes` 提交了一部分后某条失败：
+
+1. 读响应 `data.results[]`，区分 `succeeded` 和 `failed`；失败项的 `body` 里有具体字段错。
+2. 修这些失败行，单独跑 `upsert-clip` / `upsert-scene` / `upsert-episode` 补写，**不要**重跑整个 batch 文件（会把已成功的 episode/scene 再 upsert 一遍，浪费写入也容易盖掉已经手工修过的字段）。
+
+#### 整集需要回滚重导
+
+确认要整集重来（例如 episodeId 拼错、storyboard 结构整体不对）：
+
+```bash
+lj-awb artifact video delete-episode \
+  --project-id "$PROJECT_ID" \
+  --episode-id ep_001 \
+  --dry-run
+
+lj-awb artifact video delete-episode \
+  --project-id "$PROJECT_ID" \
+  --episode-id ep_001 \
+  --yes
+
+lj-awb artifact video import-storyboard \
+  --project-id "$PROJECT_ID" \
+  --input-file 3_footage/output/ep001/ep001_storyboard.json \
+  --yes
+```
+
+`delete-episode` 会级联删除该集下所有 scene / clip（详见 [`artifact/video.md`](artifact/video.md)）。
+
+#### clip 子域写入找不到 videoEpisodeId
+
+clip 子域用的是数字主键 `videoEpisodeId`，不是业务键 `ep_001`。先用 video 子域查到数字 id 再喂给 clip：
+
+```bash
+lj-awb artifact video episode \
+  --project-id "$PROJECT_ID" \
+  --episode-id ep_001 \
+  -f json
+# 取 .data.id
+
+lj-awb artifact clip update-status \
+  --project-id "$PROJECT_ID" \
+  --video-episode-id <上一步拿到的数字 id> \
+  --status music_success \
+  --messages-json '[{"level":"info","step":"music","message":"配乐完成"}]' \
+  --yes
+```
+
+规则：
+
+- 不要在 import 失败后默认建议"全删重来"；先看错误类型 — argument_error 直接修文件重跑；部分 upsert 失败用单条补写。
+- 删除是云端写入（虽然是逻辑删除），必须 `--dry-run` + `--yes` 两步走，不要看到 batch 报错就静默跑 delete。
+- artifact 系列写入失败不会扣积分；只有创作类（image/video/asset register/subject publish）才有费用，恢复时不需要重新跑 `credits balance`。

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

@@ -0,0 +1,102 @@
+# 错误处理速查表
+
+CLI 失败时 envelope 形如：
+
+```json
+{"status":"error","error":{"type":"<error-type>","message":"...","hint":"..."},"meta":{...}}
+```
+
+退出码与 `error.type` 一一对应，详见下表。`hint`（若有）是 CLI 给出的下一步建议，agent 应在用户消息中如实复述。
+
+## 退出码 × error.type 速查
+
+| exitCode | error.type | 含义 | agent 恢复路径 |
+|---------:|------------|------|----------------|
+| `0` | — | 成功 | 继续后续步骤 |
+| `1` | `runtime_error` / `api_error` | 平台业务失败或一般运行异常 | 看 `message` / `details`；不要自动重试相同请求 |
+| `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>` |
+| `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 / 网络 |
+
+## 常见恢复场景
+
+### 场景 1：confirmation_required（exit 10）
+
+```text
+{"status":"error","error":{"type":"confirmation_required","message":"...需要确认","details":{"action":"...","..."}}}
+```
+
+向用户清晰复述 `details`（要做什么、影响什么、扣多少积分），等用户确认后**用同一组参数追加 `--yes` 重跑**。不要自作主张追加 `--yes`。
+
+### 场景 2：task_still_running（exit 20）
+
+```text
+{"status":"error","error":{"type":"task_still_running","hint":"..."},"details":{"taskId":"...","waitedMs":180000}}
+```
+
+这是**等待窗口超时，不是任务失败**。直接续跑：
+
+```bash
+lj-awb task wait --task-id <id> --task-type <type> --wait-seconds 180
+```
+
+如果连续 3-4 轮都仍未终态，向用户说明并建议改用 `task record-poll`（批量）或稍后再来。
+
+### 场景 3：argument_error（exit 2）— 缺必填
+
+CLI 通常会在 `hint` 里给出补全方式。Agent 别凭记忆猜，应跑：
+
+```bash
+lj-awb schema --command <command-name> -f json
+```
+
+读取 `requiredOptions` / `requiredAnyOptions`，缺哪个补哪个。
+
+### 场景 4：auth_required / auth_failed（exit 3）
+
+先确认是没有 access key 还是 key 失效：
+
+```bash
+lj-awb auth status -f json   # 看 configured/verified
+lj-awb auth verify           # 实际打一次平台 API
+```
+
+- 没有：提示用户提供 access key（环境变量 `LINGJING_AWB_ACCESS_KEY` 或 `auth login`）。
+- 失效：提示用户重新登录；**绝不输出原始 access key 明文**。
+
+### 场景 5：network_error（exit 30）
+
+- macOS 上若是 TLS 证书问题，用 shell wrapper `lj-awb`（自动注入 `NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem`）。
+- 平台 5xx 一般稍候即恢复；不要疯狂重试，间隔 5-10 秒。
+
+### 场景 6：upload_failed（exit 30）
+
+重试一次。仍失败时：
+
+- 检查本地文件存在性 / 大小（COS 单文件有上限）
+- 看 `details.filePath / objectName`
+- 验证认证态没有过期（顺便 `auth verify`）
+
+### 场景 7：业务错误（exit 1，type=api_error）
+
+例如积分不足 / 模型不可用 / 项目组无权限：
+
+- 积分不足：跑 `credits balance` 给用户看余额，建议充值或换模型。
+- 模型不可用：跑 `model image-models` / `video-models` 看 `taskQueueNum` 和上下架状态。
+- 项目组无权限：跑 `project list` 看用户在哪个项目组，必要时 `project use --project-group-no <no> --yes`。
+
+## 与 `task wait` / `subject wait` 的边界
+
+`exit 20` 是**预期内的"还没到终态"**信号，agent 看到不要慌、不要重提任务，直接续 wait 即可。只有当：
+
+- 同一任务连续多轮（默认 `wait-seconds=180`，4-5 轮共 12-15 分钟）仍未终态
+- 或 `task wait` 输出 `taskStatus=FAILED` / `errorMessage` 非空
+
+才是真正的失败，需要按 `errorMessage` 处理（积分 / 模型 / 资源 / 参数）。

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

@@ -0,0 +1,49 @@
+# 读懂 `model options`
+
+`model options` 是指定模型组的实时参数约束。不要凭模型名、旧经验或模型列表摘要直接提交创建任务。
+
+## 默认 Text 怎么读
+
+- `params[]`：模型暴露的可控参数和约束；这里只给参数 key，不给 create 命令 flag。
+- `values`：枚举取值，只能从这里选。
+- `default`：模型默认值；用户没明确指定时通常不必显式传，但清晰度、比例、时长这类关键项仍要确认。
+- `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。
+- `formats`：文件后缀白名单。
+- `files=<=N` / `files=1`：素材数量约束。
+- `lastFrameOnly` / JSON `supportLastFrameOnly`：只表示是否支持“仅尾帧”这种特殊输入；不用于判断 `first_frame + last_frame` 是否成立。没有该能力时，尾帧应和首帧成对使用。
+- `durationMs` / `totalDurationMs`：单个素材和总素材时长约束。
+- `constraints[]`：参数 / 资源之间的联动约束；`target` 是被限制的 CLI 决策字段，`when` 是触发条件，`allowedValues=<none>` + `effect=no_selectable_values` 表示触发后不要再让用户选择该目标参数。
+
+## JSON 何时用
+
+只有需要程序化校验或查看完整嵌套结构时才用：
+
+```bash
+lj-awb model options --model-group-code <code> -f json
+```
+
+JSON 里会保留更完整的参数 / 资源 / 条件约束字段，但仍不承担 create 命令写法。`--resource` 语法、prompt key 绑定和示例统一看 `model create-spec`。
+
+## 使用顺序
+
+1. `model image-models` / `model video-models` 按关键词找候选。
+2. `model options --model-group-code <code>` 读取可传参数和素材约束。
+3. `model create-spec --model-group-code <code>` 读取输入模式、素材绑定规则和示例命令。
+4. 如果用户缺少关键价格 / 效果参数，先展示候选值和默认值，请用户选择或确认“按默认”。
+5. `fee` 估价。
+6. `create --dry-run` 预览请求。
+7. 用户确认后 `create --yes`。
+
+## 判断口径
+
+- 不在 `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`。
+- 图片生图参考图不使用 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。
+- 首帧 / 尾帧不使用 reference_key；是否可传尾帧看 `usage` 是否包含 `last_frame`，具体创建方式看 `model create-spec`。