@lingjingai/lj-awb-cli-pre 0.3.15

package/skills/lj-awb/modules/create-contract.md

@@ -0,0 +1,118 @@
+# Create Contract Module
+
+本模块定义 Agent 创建图片 / 视频任务前必须理解的输入契约。不要直接把平台旧参数塞给 `image create` / `video create`；先用 `model options` 查看参数值、素材约束和条件约束，再用 `model create-spec` 查看创建方式。
+
+## 参数含义
+
+| CLI 参数 | 含义 | 组织方式 |
+|----------|------|----------|
+| `--model-group-code` | 模型组编码，决定使用哪个模型、计费方式和参数白名单 | 来自 `model image-models` / `model video-models` |
+| `--prompt` | 提交给模型的最终提示词 | 以用户明确创作描述为基底，组装素材输入和模型约束；视频需要占位绑定时才做 key 对齐；没有明确需求时先追问或用最小中性表达 |
+| `--ratio` | 画幅比例 | 只能从 `model options.params[key=ratio].values` 选择 |
+| `--quality` | 清晰度 / 分辨率档位 | 只能从 `model options.params[key=quality].values` 选择 |
+| `--generate-num` | 生图张数 | 仅图片模型支持时使用 |
+| `--duration` | 生视频时长，单位秒 | 对应平台旧参数 `generated_time`，只能从允许值选择 |
+| `--need-audio` | 是否需要输出音效 | 仅用户明确要求输出音效，且 `model options.params[key=needAudio]` 存在时使用；不是上传音频入口 |
+| `--resource` | 单个素材输入，可重复传 | `type:usage[:key]=path|url|asset:<id>` |
+| `--resources-json` | 多素材输入，适合复杂 keyframe / 批量构造 | JSON 数组或 JSON 文件路径 |
+| `--project-group-no` | 任务归属项目组 | 用户明确指定，或来自当前项目组 |
+| `--custom-biz-id` | 外部追踪 ID | 可选；不传则请求不携带 |
+
+## 素材组织
+
+短语法：
+
+```bash
+# 图片生图 / 普通视频参考图
+--resource image:reference=./ref.png
+# 仅视频 reference 需要显式绑定对象时使用
+--resource image:reference:hero=./hero.png
+--resource image:reference:hero=asset:<assetId>
+--resource image:first_frame=./first.png
+--resource image:first_frame=asset:<assetId>
+--resource image:last_frame=./last.png
+--resource image:last_frame=asset:<assetId>
+--resource video:reference:motion=./motion.mp4
+--resource audio:reference=./music.mp3
+--resource audio:reference:voice=./voice.wav
+--resource subject:reference:hero=asset:<externalId>
+```
+
+JSON 语法：
+
+```json
+[
+  {
+    "type": "image",
+    "usage": "reference",
+    "source": { "kind": "url", "value": "./hero.png" }
+  }
+]
+```
+
+规则：
+
+- 图片生图一次性参考图只用 `image:reference=...`，不传 `reference_key`，prompt 中也不写 `<<<key>>>`；用“图一 / 图二 / 参考图 / 白发女 / 背景图”等自然语言指代。
+- 视频 reference 的 `reference_key` 用于和 prompt 中的 `<<<key>>>` 对齐，例如 `<<<hero>>>`；这是可选绑定，prompt 不写占位符时资源可以不带 key。
+- 视频一次性参考图用 `image:reference=...`；需要在 prompt 中明确绑定对象时才用 `image:reference:<key>=...`。取值优先级：平台素材的 `backendPath`（`material/...`） > 本地文件路径 > 真正外部公网完整 URL；视频参考生还可使用普通素材 `asset:<assetId>`。**不要把 `lj-awb upload files` 回显的 `url`（`https://*.myqcloud.com/material/...`）当作 source.value 直接复用，应改用 `backendPath`。**
+- 参考音频 / 音乐 / 配音只有在 `model options.resources[]` 暴露 `media=AUDIO usage=reference` 时，才可用 `audio:reference=...` 或 `audio:reference:<key>=...`，作为参考资源进入 `promptParams.resources[]`。**不要把参考音频塞进 `--need-audio`**：`--need-audio` 只是输出音效开关，不接收音频文件。
+- 用户明确要求在 prompt 中指代音频时，可以使用 `audio:reference:<key>=...` 并在 prompt 中插入同名 `<<<key>>>`。
+- 可长期复用角色用 `subject publish` 生成主体，再用 `subject:reference:<key>=asset:<externalId>`。
+- 首尾帧用 `image:first_frame=...` / `image:last_frame=...`；取值优先级与参考图一致：`backendPath` > 本地文件 > 真正外部公网完整 URL，也可以是 `asset:<assetId>`。
+- `image:last_frame` 默认和 `image:first_frame` 成对使用；只有模型资源约束声明 `supportLastFrameOnly=true` 时才可仅传尾帧。
+- `subject:reference:<key>=asset:<externalId>` 表示主体引用；`image:first_frame=asset:<assetId>` 表示首尾帧资产，两者语义不同，不要混用。
+
+## Prompt 组装原则
+
+创建任务时，Prompt 的核心能力是组装可执行请求：
+
+- 用户有明确创作描述或提示词时，以该文本为基底，只做必要的素材组织、视频 key 对齐和转义清理，不要强行补资源占位符。
+- “使用某模型 / 参考生 / 生成视频 / 用这张图 / 用这个音频”等操作性指令只用于选择模型和资源，不要改写成新的画面描述。
+- 用户没有比较明确的创作需求或提示词时，先追问关键创作意图，或使用最小中性表达；不要为了让 prompt 好看而主动补风格、镜头、剧情细节。
+- 用户只是描述任务目标时，不要默认补资源占位符；图片生图永远不用 `<<<key>>>`，视频只有用户明确要在 prompt 中绑定某个参考对象时才使用。
+- 参考图已经作为资源输入时，不要从图片内容中推断“山谷、街道、室内、人物外观”等画面描述塞进 prompt；除非用户明确要求看图补充描述。
+- 用户要求优化 / 改写 / 创作 prompt 时，可以进行提示词创作，但创建任务前仍要展示最终 prompt。
+
+规则：
+
+- 图片生图不接受 `reference_key` 或 `<<<key>>>`；多图映射用 prompt 自然描述和资源顺序。
+- 视频 prompt 中出现 `<<<key>>>` 时，必须有同名 `reference_key`；资源带 `reference_key` 但 prompt 不引用时也允许。
+- `image:first_frame` / `image:last_frame` 是首尾帧，不要求 `<<<key>>>`。
+- `subject:reference:<key>` 必须携带 key；是否在 prompt 中写 `<<<key>>>` 由用户表达需要决定。
+- 音频参考可以不带 key；用户要求音频也显式参考时，可以使用 `audio:reference:<key>` 并在 prompt 中引用同名 `<<<key>>>`。
+
+## 模型配置到创建参数的关系
+
+`model options` 会返回可传参数和取值，`model create-spec` 会返回创建方式，不需要 Agent 记忆平台旧参数：
+
+| 平台模型参数 | CLI 参数 | 请求位置 | Material 旧参数 |
+|--------------|----------|----------|-----------------|
+| `prompt` | `--prompt` | `promptParams.prompt` | `prompt` |
+| `ratio` | `--ratio` | `promptParams.ratio` | `ratio` |
+| `quality` | `--quality` | `promptParams.quality` | `quality` |
+| `generate_num` | `--generate-num` | `promptParams.generate_num` | `generate_num` |
+| `generated_time` | `--duration` | `promptParams.duration` | `generated_time` |
+| `iref` | `--resource image:reference=...` | `promptParams.resources[]` | `iref` |
+| `frames` | `--resource image:first_frame=...` | `promptParams.resources[]` | `frames` |
+| `multi_param` | `--resource image/video/audio/subject:reference[:key]=...` | `promptParams.resources[]` | `multi_param` |
+| `generated_mode` | 不暴露为 CLI 参数 | 由资源推导 | `generated_mode` |
+
+## 创建前校验
+
+Agent 必须按顺序做：
+
+1. `doctor --verify`，确认认证、API、项目组和 UTF-8 环境。
+2. `model image-models` 或 `model video-models`，按用户目的筛候选模型。
+3. 向用户展示 2-4 个候选：模型名、`modelGroupCode`、是否支持参考图 / 首尾帧 / 主体引用、计费类型、排队状态。
+4. 对用户选中的模型运行 `model options --model-group-code <code> -f json`。
+5. 再运行 `model create-spec --model-group-code <code> -f json`。
+6. 先读 `inputRequirement`，确认是否必须提供视觉输入。
+7. 用 `supportedIntents[]` 匹配用户意图；不要只看模型列表摘要就生成最终能力结论。
+8. 参数枚举值只从 `model options.params[].values` 选择，素材限制只从 `model options.resources[]` 校验，参数 / 资源联动限制按 `model options.constraints[]` 收窄。
+9. 不主动列举所有缺失控制项；只追问会影响价格 / 效果的关键参数。视频包括 `quality`、`duration`、约束后仍可选的 `ratio`，以及用户明确要求输出音效时的 `needAudio`；图片包括 `quality`、`ratio`、`generateNum`。
+10. 组装最终 prompt；如果可见文本发生变化，先展示给用户。
+11. 若用户上传或指定音频文件，必须先确认 `model options.resources[]` 中存在 `mediaType=AUDIO usage=reference` 后再组织 `audio:reference` 资源；只有用户明确要求“输出是否带模型生成音效/音频”时，才检查 `model options.params[]` 是否存在 `needAudio`。
+12. 用户未提供关键参数时，把 `model options.params[].values` 和 `defaultValue` 转成候选问题；用户选择或确认“按默认”前，不跑 `image fee` / `video fee`，也不跑 `create --dry-run`。
+13. 跑 `image fee` / `video fee` 获取预估积分。
+14. 跑 `create --dry-run` 检查请求体和本地素材。
+15. 用户确认模型、项目组、最终 prompt 文本、素材、关键参数和积分后，才追加 `--yes` 正式提交。

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

@@ -0,0 +1,28 @@
+# Credits Module
+
+积分模块用于预算确认和项目用量统计。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb credits balance` | 查看可扣积分余额和当前项目组预算 |
+| `lj-awb credits balance --project-group-no <no>` | 查看可扣积分余额和指定项目组预算 |
+| `lj-awb credits usage --project-group-no <no> --last-hours 24` | 汇总最近任务消耗 |
+| `lj-awb credits usage --project-group-no <no> --task-types IMAGE_CREATE,VIDEO_GROUP --include-tasks` | 汇总并附带任务明细 |
+
+## 规则
+
+- 正式创作前需要先估价，再结合可扣积分余额给用户确认；估价前必须先确认缺失的价格 / 效果关键参数，不能用默认值替用户先跑费用。
+- 低费用不代表可以跳过确认。
+- 预算摘要必须优先展示 `billingPointBalance` / `billingPointRemainingAfter`，它来自 `/api/anime/member/benefits/queryGroupPoint`，表示当前团队 / 账户真正可扣的积分余额。
+- `projectBudgetBalance` / `projectBudgetRemainingAfter` 来自项目组积分接口，只表示该项目当前还可使用多少项目预算，偏 ROI / 项目规划视角；不要把它说成“积分余额”或扣费账户余额。
+- 预算摘要要包含模型组、候选数量、清晰度、比例、预估积分、可扣积分扣前 / 扣后余额，以及项目组预算信息。
+- `credits balance` 不等价于切换项目组；如果项目组归属会影响判断，先用 `account info` 或 `project current` 确认当前项目组编号。
+- `usage` 是统计工具，不等价于精确财务账单。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"积分"小节。
+
+## 下一步
+
+- 积分够 → 进 [`model.md`](model.md) 选模型，或直接 [`image.md`](image.md) / [`video.md`](video.md) 估价。
+- 积分不够 → 提示用户充值；不要默认换更便宜模型，先问用户偏好。

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

@@ -0,0 +1,186 @@
+# Evals Module
+
+本模块用于压测 Agent 是否真的理解 AWB CLI，而不是机械拼命令。每个用例都应在真实对话或 dry-run 中验证。
+
+## 评估标准
+
+- 先查模型、`model options` 和 `model create-spec`，不凭记忆判断能力。
+- 能区分参考图、首帧、首尾帧、音频参考、主体复用。
+- 能区分 `audio:reference` 和 `--need-audio`。
+- 不使用 `audio:source`、平台旧字段、`generated_time`、`multi_param`、`frames` 作为 create 入参。
+- 能把用户意图、素材引用和模型约束组装成可执行 prompt；没有明确需求时不主动编内容补空白；图片生图不生成 `reference_key` 或 `<<<key>>>`。
+- `fee` 和 `create --dry-run` 前必须先确认用户未提供的关键价格 / 效果参数；不能静默用默认值跑估价。
+- 正式扣费前必须 fee + dry-run + 用户确认。
+
+## 多轮压测用例
+
+### 1. 参考图 + SD2 Fast + 音频
+
+用户：“我想用这张图 SD2 fast 生视频，动作是选择跳跃，还用这个音频。”
+
+期望：
+
+- 查询 `model video-models --model "SD2"` 或相关关键词，再查被选模型的 `create-spec`。
+- 视频参考图可使用 `image:reference:hero=<image>`，音频使用 `audio:reference=<audio>`。
+- prompt 可以组装为 `<<<hero>>> 选择跳跃`，但不能自动加电影感、镜头推进等额外内容。
+- 不要根据参考图画面内容自动补“山谷、街道、室内、服装”等场景描述。
+- 不先寻找 `needAudio`；不输出“该模型不支持音频参数”这类误导结论。
+- 如果用户没有指定画质、时长或约束后仍可选的比例，dry-run 前必须给出候选值和默认值让用户选择。
+
+禁止：
+
+- `--resource audio:source=...`
+- `--need-audio <audioFile>`
+- `--prompt "选择跳跃"` 同时带 `image:reference:hero=...`
+- 未确认 `quality` / `duration` 就先跑 `video fee` 或 `video create --dry-run`。
+
+### 1.1 参考图 + 音频原句保留
+
+用户：“一个女人在图片上走动 一边说音频。使用 sd2fast参考生。”
+
+期望：
+
+- `sd2fast`、`参考生` 只用于模型和资源选择，不进入 prompt。
+- 可以把参考图占位符补进 prompt，例如 `<<<scene>>> 一个女人在图片上走动 一边说音频`。
+- 不要根据图片内容自动补“山谷风景”等场景描述。
+- 不要把“一边说音频”改写成“口型跟随参考音频”，除非用户要求优化。
+
+禁止：
+
+- `在 <<<scene>>> 的山谷风景中，一个女人自然走动，一边说话，口型跟随参考音频。`
+
+### 1.2 指定模型和主体资产但缺少价格参数
+
+用户：“妈妈在图中跳广场舞，并且一边说音频内容。使用 sd2fast 生视频，妈妈的资产 id 是 asset-20260511135015-7nhph。”
+
+期望：
+
+- 可以先查 `doctor --verify`、模型候选、`model options`、`model create-spec`、账号和项目组。
+- 识别创作描述接近“妈妈在图中跳广场舞，并且一边说音频内容”，`sd2fast` 只用于模型选择，资产 id 只用于资源组织。
+- 如果 `quality`、`duration` 或约束后仍可选的 `ratio` 未给出，先向用户追问并列出候选值和默认值。
+- 用户确认关键参数前，不运行 `video fee`，也不运行 `video create --dry-run`。
+
+禁止：
+
+- 直接采用默认画质 / 时长跑估价。
+- 先 dry-run 再让用户修改参数。
+
+### 1.3 Banana 参考图生图
+
+用户：“用 banana 生图。让第一张里的白发女保持金鱼嘴表情，在第二张场景里坐秋千。”
+
+期望：
+
+- 使用 `model image-models --model "Banana"`，再查 `model options` / `model create-spec`。
+- 资源使用 `image:reference=<first>` 和 `image:reference=<second>`。
+- prompt 保留自然指代，例如“第一张里的白发女保持金鱼嘴表情，在第二张场景里坐秋千”。
+- 如果缺少 `ratio`、`quality` 或 `generateNum`，先给候选值和默认值让用户确认。
+
+禁止：
+
+- 把 prompt 改成 `<<<白发女>>> ... <<<scene>>> ...`。
+- 使用 `image:reference:白发女=...`、`image:reference:scene=...` 或 JSON `reference_key`。
+
+### 2. 生视频用户要求原文 prompt
+
+用户：“prompt 就用：选择跳跃，不要改。参考这张图生视频。”
+
+期望：
+
+- 识别到用户明确要求不改 prompt。
+- 如果 Agent 选择视频 keyed 参考图绑定，先询问：“是否允许把 prompt 从 `选择跳跃` 调整为 `<<<hero>>> 选择跳跃`？”也可以保持原 prompt 并使用不带 key 的 `image:reference=...`。
+- 用户确认前不提交 create。
+
+禁止：
+
+- 静默改成 `<<<hero>>> 选择跳跃` 后直接提交。
+- 扩写为更华丽的视频描述。
+
+### 3. 让图片动起来
+
+用户：“就让这张图动起来，镜头慢慢推进。”
+
+期望：
+
+- 优先选择 `image:first_frame=<image>`，不是 `image:reference:<key>`。
+- prompt 使用用户动作描述，例如 `镜头慢慢推进`。
+- 不强制插入 `<<<hero>>>`。
+
+禁止：
+
+- 把首帧资产误写成 `subject:reference`。
+- 因为没有 `<<<key>>>` 而阻塞首帧任务。
+
+### 4. 首尾帧过渡
+
+用户：“用第一张做开头，第二张做结尾，生成 5 秒过渡。”
+
+期望：
+
+- 使用 `image:first_frame=<first>` + `image:last_frame=<last>`。
+- 检查模型 `supportedIntents.mode=frames`。
+- `duration` 只能从 allowedValues 选择；如果 5 秒不支持，提示可选值。
+
+禁止：
+
+- 把两张图都塞进 `image:reference`。
+
+### 5. 主体长期复用
+
+用户：“这个角色后面要反复用，先帮我建成主体，再用它生成一个转身视频。”
+
+期望：
+
+- 先 `subject publish --dry-run`，确认后 `subject publish --yes`。
+- `subject wait` 成功后使用 `nextRefSubject`。
+- 视频使用 `subject:reference:<key>=asset:<externalId>`，prompt 包含 `<<<key>>>`。
+
+禁止：
+
+- 直接把主体图当作普通首帧。
+- 把普通图片 assetId 当成主体 externalId。
+
+### 6. 用户要求优化 prompt
+
+用户：“帮我把这个 prompt 优化成更适合生视频：女孩跑过雨夜街道。”
+
+期望：
+
+- 识别到用户要求优化 prompt。
+- 可以给出优化版 prompt，但先展示给用户确认。
+- 用户确认前不执行扣费 create。
+
+禁止：
+
+- 以“不能改 prompt”为由拒绝优化。
+- 优化后不展示最终文本直接提交。
+
+### 7. 只指定模型，不清楚输入
+
+用户：“用 JiMeng Seedance 2 Fast 生成视频。”
+
+期望：
+
+- 查 `create-spec` 后说明该模型是否要求视觉输入。
+- 如果 `visualInputRequired=true`，追问用户要参考图、首帧、首尾帧还是主体引用。
+- 不提交纯 prompt 任务。
+
+禁止：
+
+- 因用户没给图而瞎编资源。
+- 直接纯 prompt 创建导致失败。
+
+### 8. 用户问能用哪些模型
+
+用户：“我想做一个参考图生视频，哪些模型适合？”
+
+期望：
+
+- 查询候选视频模型，并用 `supportedIntents.mode=reference` 筛选。
+- 展示 2-4 个候选，包含模型名、`modelGroupCode`、速度 / 清晰度 / 费用 / 排队信息。
+- 不默认列负面能力清单；只解释与参考图生视频相关的能力。
+
+禁止：
+
+- 只按模型名字猜。
+- 只看模型列表摘要就当最终能力判定，不查 `create-spec`。

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

@@ -0,0 +1,75 @@
+# Image Module
+
+图片模块用于生图模型选择、估价、提交、批量提交和查询结果。创建前必须先读取 `model options` 和 `model create-spec`。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb image fee --model-group-code <code> --prompt "..."` | 生图估价 |
+| `lj-awb image create --model-group-code <code> --prompt "..." --dry-run` | 预览生图请求 |
+| `lj-awb image create --model-group-code <code> --prompt "..." --resource image:reference=./ref.png --project-group-no <no> --yes` | 提交参考图生图任务 |
+| `lj-awb image create-batch --input-file ./image.jsonl --model-group-code <code> --yes` | 批量生图 |
+| `lj-awb image status --task-id <id>` | 查询生图任务 |
+| `lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180` | 等待生图结果 |
+
+## 创建参数
+
+| 参数 | 何时使用 | 约束来源 |
+|------|----------|----------|
+| `--prompt` | 所有生图任务 | 以用户明确创作描述为基底组装的最终提交文本；没有明确需求时先追问或用最小中性表达 |
+| `--ratio` | 需要指定画幅时 | `model options.params[key=ratio].values` |
+| `--quality` | 需要指定清晰度时 | `model options.params[key=quality].values` |
+| `--generate-num` | 指定生成张数；模型暴露该控制项时属于价格关键参数 | `model options.params[key=generateNum].values` |
+| `--resource image:reference=...` | 参考图生图 | `model create-spec.supportedIntents.mode=reference` 必须存在 |
+| `--resources-json` | 多参考图或程序化构造 | 同 `--resource`，但用 JSON 数组表达 |
+
+## 标准流程
+
+```bash
+lj-awb model image-models --model "<keyword>"
+lj-awb model options --model-group-code <modelGroupCode> -f json
+lj-awb model create-spec --model-group-code <modelGroupCode> -f json
+```
+
+如果用户没有指定 `ratio`、`quality` 或 `generateNum`，先展示 `model options.params[].values` 和默认值让用户选择；用户确认后再执行：
+
+```bash
+lj-awb image fee --model-group-code <modelGroupCode> --prompt "<prompt>"
+lj-awb image create --model-group-code <modelGroupCode> --prompt "<prompt>" --dry-run
+```
+
+用户确认后：
+
+```bash
+lj-awb image create \
+  --model-group-code <modelGroupCode> \
+  --prompt "<user prompt>" \
+  --ratio <allowedRatio> \
+  --quality <allowedQuality> \
+  --project-group-no <projectGroupNo> \
+  --yes \
+
+```
+
+## 规则
+
+- 不要提交 `generated_time`、`iref`、`frames`、`multi_param`、`generated_mode` 这类平台旧字段。
+- `--prompt` 的重点是组装资源、参数和模型约束；用户没有明确需求时不要主动编内容补空白，用户要求优化时再做提示词创作。
+- 参考素材统一使用 `--resource image:reference=...` 或 `--resources-json`。
+- 参考图取值优先级：**平台素材的 `backendPath`（`material/...`） > 本地文件路径 > 真正外部公网完整 URL**。`lj-awb upload files` 回显的 `backendPath`、历史任务结果里的 COS 对象路径，都必须用 `backendPath` 形式传入；不要把回显的 `url`（`https://*.myqcloud.com/material/...`）当作 source.value 直接复用。
+- 生图参考资源不使用 `reference_key`，不要写 `image:reference:<key>=...`，也不要在 prompt 中插入 `<<<key>>>`。
+- 多张参考图用资源顺序和自然语言描述映射，例如“图一中的白发女保持表情，在图二背景里坐秋千”。
+- `ratio` / `quality` / `generate-num` 不确定时，先查 `model options`，不要猜一个模型不支持的值。
+- `fee` 和 `create --dry-run` 前必须确认缺失的 `ratio`、`quality`、`generate-num`；不要静默用默认值估价。用户说“按默认”后才继续。
+- 正式提交必须带 `--yes`；如果需要看请求体，先用 `--dry-run`。
+- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`generate_num`、`resources`、`resource`、`customBizId`；模型组和项目组放命令行公共参数。
+- **多镜头 / 多 prompt 时主动建议并行**：用户一次给出 ≥2 个同模型同参数的图片任务（典型场景：分镜、组图、多 prompt 候选）时，Agent 必须先告知"这批可以用 `image create-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 / 调 prompt → 继续单条 create。**不要默认一条一条串行还不告知**，这种沉默会浪费用户时间。
+- 等待超时只代表本轮轮询结束，不能对用户说任务失败。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"生图 / 生视频"小节；错误恢复见 [`../references/error-codes.md`](../references/error-codes.md)。
+
+## 下一步
+
+- `image create` 返回 `taskId` + `nextCommand`（通常 = `task wait`）→ **立刻接着跑** `task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180`，不要让用户再问"好了没"。
+- `image create-batch` 写入 `.awb/tasks.jsonl`，用 [`task.md`](task.md) → `task record-poll` 批量等。
+- 任务终态拿到 `resultUrls` → 视场景决定：① 直接交付给用户；② 用作下一轮生图 / 生视频的参考图（直接以 result URL 喂 `--resource image:reference=<url>`）；③ 写回 [`artifact/asset.md`](artifact/asset.md) 的角色 / 道具 / 场景产物。

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

@@ -0,0 +1,110 @@
+# Model Module
+
+模型模块用于“发现候选模型”和“查看指定模型的创建用法”。Agent 不要把平台原始参数直接当成 create 参数。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb model image-models --model "<keyword>"` | 查询生图候选模型 |
+| `lj-awb model video-models --model "<keyword>"` | 查询生视频候选模型 |
+| `lj-awb model input-guide -f json` | 查看统一创建参数、resources 字段和素材绑定规则 |
+| `lj-awb model options --model-group-code <code> -f json` | 查看该模型支持的 CLI 参数、枚举值、默认值、素材约束和条件约束 |
+| `lj-awb model create-spec --model-group-code <code> -f json` | 查看该模型如何创建任务：输入模式、素材绑定规则、示例和前置步骤 |
+
+## 选择模型
+
+用户只描述目标、没指定模型时，Agent 先按任务类型查候选：
+
+```bash
+lj-awb model image-models --model "<keyword>"
+lj-awb model video-models --model "<keyword>"
+```
+
+向用户展示候选时只保留决策字段：
+
+- `displayName`：模型展示名。
+- `modelGroupCode`：后续创建任务必须使用的编码。
+- `provider`：供应商。
+- `feeCalcType`：计费类型。
+- `modelStatus` / `taskQueueNum`：当前负载和排队参考。
+- `inputModes`：模型列表阶段用于粗筛的输入方式摘要，例如 `prompt_only`、`reference`、`frames`、`storyboard`。
+- `params`：模型列表阶段用于粗筛的可控参数摘要，例如 `ratio`、`quality`、`duration`；最终枚举值和限制以 `model options` 为准。
+
+不要一次展示完整原始 JSON；让用户在 2-4 个候选中确认。
+
+## 获取参数约束
+
+用户选定模型后先运行：
+
+```bash
+lj-awb model options --model-group-code <modelGroupCode> -f json
+```
+
+默认 text 输出的字段解释见 [`../references/model-options-read.md`](../references/model-options-read.md)。需要程序化校验时才用 `-f json`。
+
+Agent 读取这些字段：
+
+- `params[]`：模型暴露的参数 key 和约束；创建命令 flag 看 `model create-spec`。
+- `params[].values`：枚举取值，创建任务时只能从这里选。
+- `params[].defaultValue`：模型默认值；关键参数不能静默采用默认值，用户选择或确认“按默认”后才继续 fee / dry-run。
+- `params[].maxLength`：prompt 等文本参数的长度限制。
+- `resources[]`：素材媒体约束，包含 `mode`、`mediaType`、`usage`、`sources`、`fileTypes`、数量 / 大小 / 时长限制；frames 资源的 `usage` 可同时包含 `first_frame|last_frame`。
+- `media=IMAGE` 的 `fileTypes` 是特殊语义：空列表表示不支持 webp，CLI 会把本地 webp 自动转成 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才是强控制允许格式。默认 text 会把它翻译成 `formats=...` 和 `webpInput=accepted|autoConvertToJPG`。
+- `constraints[]`：条件约束全景，描述某个输入或参数出现后，会限制哪个目标参数的可选值；例如 `target=ratio` 且 `when=resource.image.frame=present`、`effect=no_selectable_values` 表示首帧 / 首尾帧输入后不要让用户继续选择比例。
+
+`model options` 不输出 `--resource` 写法、prompt key 绑定或下一步创建命令；这些属于 `model create-spec`。
+
+## 获取创建规格
+
+用户选定模型后运行：
+
+```bash
+lj-awb model create-spec --model-group-code <modelGroupCode> -f json
+```
+
+Agent 读取这些字段：
+
+- `taskKind`：`image` 或 `video`，决定使用 `image create` 还是 `video create`。
+- `optionsCommand`：查看本模型参数约束的命令。
+- `inputRequirement`：是否必须提供视觉输入，以及不能只传 prompt 的原因。
+- `supportedIntents[]`：用户意图到统一输入方式的权威映射，例如 `prompt_only`、`reference`、`frames`、`storyboard`。
+- `validationRules[]`：创建前必须检查的规则。
+- `agentGuidance[]`：Agent 使用该规格时必须遵守的解释和决策规则。
+- `preflight[]`：建议前置流程。
+- `examples[]`：针对该模型生成的 create 示例。
+
+## 关键映射
+
+模型配置中的参数名不等于 CLI 参数名：
+
+| 模型配置 | CLI create 参数 | 说明 |
+|----------|-----------------|------|
+| `generated_time` | `--duration` | 视频时长 |
+| `generate_num` | `--generate-num` | 图片张数 |
+| `iref` | `--resource image:reference=...` | 图片参考图 |
+| `frames` | `--resource image:first_frame=...` / `image:last_frame=...`，可传文件/URL/backendPath/`asset:<assetId>` | 视频首尾帧 |
+| `multi_param` | `--resource image/video/audio:reference[:key]=...` / `subject:reference:<key>=asset:<id>` | 多参考素材 / 音频参考 / 主体引用 |
+| `generated_mode` | 不传 | 由资源类型推导 |
+
+规则：
+
+- `ratio`、`quality`、`duration`、`generateNum` 必须从 `model options.params[].values` 选择。
+- 用户没有给出会影响价格 / 效果的关键参数时，先把候选值和默认值转成追问；`fee` 和 `create --dry-run` 必须等用户选择或确认默认后再跑。
+- 如果 `model options.constraints[]` 命中了当前用户输入，必须按约束收窄参数选择；`effect=no_selectable_values` 表示触发后目标参数没有可选枚举，不要追问或传入该参数。
+- `model options` 是参数和素材约束入口；`model create-spec` 是创建方式入口。
+- 判断用户需求能否满足时，优先看 `model create-spec.supportedIntents[]`，素材格式 / 数量 / 时长限制看 `model options.resources[]`；不要根据缺失控制项生成“模型不支持音频参数”这类默认回复。
+- 用户说“上传音频 / 使用音乐 / 配音 / 音频参考”时，这是素材输入，优先使用 `--resource audio:reference=...`，不要先找 `needAudio`。
+- 音频参考可以使用 `audio:reference`；只有用户明确要在 prompt 中指代音频时，才使用 `audio:reference:<key>`。
+- 图片生图不使用 `reference_key` 或 `<<<key>>>`；用 `image:reference=...` 传参考图，并在 prompt 中用自然语言指代图一、图二、参考图、主体等。
+- 视频 `reference_key` 是可选绑定；prompt 中出现 `<<<key>>>` 时，必须有同名 reference 资源，反过来不强制。
+- `supportLastFrameOnly` 只表示模型是否支持“仅尾帧”输入；首尾帧过渡能力看 frames 资源的 `usage` 是否包含 `last_frame` 和数量约束。
+- 只有用户明确问“是否需要输出音效”时，才检查 `model options.params[]` 是否有 `needAudio`；没有时只说“当前模型没有暴露输出音效控制项，不要传 --need-audio”。
+- 如果 `inputRequirement.visualInputRequired=true`，创建任务必须带 `supportedIntents[]` 中声明的视觉输入资源。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"模型"小节。
+
+## 下一步
+
+- 模型 + 参数定下后 → [`image.md`](image.md) 或 [`video.md`](video.md) 跑 `fee` + `create --dry-run` + 确认 + `--yes`。
+- 模型 `taskQueueNum` 很大（>100）→ 向用户提示排队风险，可让用户在候选间换；不要默认换。
+- 不要重复跑 `model image-models / video-models` —— `modelGroupCode` 一旦确定，整个对话内复用。

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

@@ -0,0 +1,30 @@
+# Project Module
+
+项目模块用于确认和管理任务归属项目组。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb project list` | 列出项目组 |
+| `lj-awb project list --name "<keyword>"` | 按名称过滤项目组 |
+| `lj-awb project current` | 查看云端当前项目组和项目预算 |
+| `lj-awb project use --project-group-no <no> --yes` | 切换项目组 |
+| `lj-awb project users` | 列出创建项目组可选成员 |
+| `lj-awb project create --name "<name>" --point 1000 --yes` | 创建并切换项目组 |
+| `lj-awb project update --project-group-no <no> --name "<name>" --yes` | 修改项目组 |
+| `lj-awb project ensure --name "<name>" --point 1000 --yes` | 确保项目组存在 |
+
+## 规则
+
+- 正式生图 / 生视频前必须确认任务会挂到哪个项目组。
+- 如果项目组不明显匹配用户意图，先询问用户，不要静默选择。
+- 联网场景下以 `project current` / `project list` 返回的云端当前项目组为准，不要把本地 `state.json` 当成权威来源。
+- 如果多个查询结果不一致，先重新运行 `account info` 和 `project list` 收敛结论，再继续估价或创建任务。
+- `project use`、`project create`、`project update`、`project ensure` 都会改变云端或本地上下文，必须确认后追加 `--yes`。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"账号与项目组"小节。
+
+## 下一步
+
+- 项目组选定后 → [`credits.md`](credits.md) 查 `billingPointBalance` + `projectBudgetBalance`，判断是否够跑下一批任务。
+- 项目组不存在但用户想要 → `project create` 比 `project ensure` 更明确；`ensure` 适合脚本场景（已存在则复用）。

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

@@ -0,0 +1,32 @@
+# Subject Module
+
+主体模块用于创建 / 查询平台主体 element。视频主体参考应使用主体的 `externalId`，通过 `--resource subject:reference:<key>=asset:<externalId>` 传给视频创建命令。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb subject list --name "女主"` | 查询主体 / 元素 |
+| `lj-awb subject publish --name 女主 --resource primary:./three-view.png --dry-run` | 预览主体创建 |
+| `lj-awb subject publish --name 女主 --resource primary:./three-view.png --yes` | 创建主体并返回 elementId |
+| `lj-awb subject wait --element-id <elementId> --wait-seconds 300` | 等待 externalId 回填 |
+| `lj-awb subject publish --name 女主 --resource primary:material/assets/a.png --yes` | 用已上传素材创建主体 |
+| `lj-awb subject publish --name 女主 --resource primary:./pri.png --resource face:./face.png --resource side:./side.png --yes` | 多视角参考图 |
+| `lj-awb subject publish-batch --input-file ./subjects.jsonl --yes` | 批量发布主体 |
+
+## 规则
+
+- 发布前确认主体名称、主参考图、可选正脸 / 侧面 / 背面图、项目名。
+- 参考图统一通过 `--resource <slot>:<file|url>` 传入，slot ∈ `primary | three-view | face | side | back`。无 `primary` 时 `three-view` 自动升为主图；本地路径（`./` 或绝对路径）会自动上传，含 `://` 或 `material/` 前缀的视为已上传 URL。
+- `subject publish` 是提交动作；如果返回 `pending_external_id`，后续用 `subject wait --element-id <elementId>` 或 `subject list --name` 查询。
+- 成功 ready 后优先使用返回的 `externalId` / `nextRefSubject`。
+- 后续视频生成时传 `--resource subject:reference:女主=asset:<externalId>`，不要反复上传同一张人物图。
+- 主体发布是云端写入动作，必须确认。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"主体"小节；`subject_still_pending`（exit 20）见 [`../references/error-codes.md`](../references/error-codes.md) 场景 2。
+
+## 下一步
+
+- `subject publish` 返回 `elementId` → **立刻** `subject wait --element-id <elementId> --wait-seconds 300` 直到拿到 `externalId`。不要先去做别的事，否则用户视角是"角色没建好"。
+- `subject wait` 返回 `nextRefSubject`（形如 `女主=<externalId>`）→ 直接复制到 `video create --resource subject:reference:女主=asset:<externalId>` 即可，**不要手拼**。
+- 想看历史发布过的主体（避免重发）→ `subject list --name "<keyword>"`。
+- 批量主体发布走 `subject publish-batch` + [`task.md`](task.md) → `task record-poll`。