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

package/skills/lj-awb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lj-awb
-version: 0.3.15
-description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、生图、生视频、任务查询、最终产物 artifact CRUD 与本地 JSON 导入。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
+version: 0.3.16
+description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、统一 create 创建域、任务查询、最终产物 artifact CRUD 与本地 JSON 导入。用户说生图、生视频、主体、音色、素材加白、去字幕、artifact 写入或查询时使用。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
 metadata:
   requires:
     bins: ["lj-awb"]
@@ -10,151 +10,98 @@ metadata:
 
 # lj-awb CLI Skill
 
-本 skill 教 Agent 如何使用 `lj-awb` CLI。CLI 是传统确定性程序，skill 只负责编排和安全规则，不承载业务 API 调用。
+`lj-awb` 是确定性 CLI，skill 的职责是调度：少查、少问、少重跑，按 schema 和业务链条把命令串对。不要把本 skill 当成一堆命令片段来拼。
 
-## 1. CLI 入口
+## 先读驱动器
+
+任何非单条查询任务，都先加载 [`modules/driver.md`](modules/driver.md)。它定义：
+
+- CLI 全部能力域和业务边界。
+- Agent 状态账本，避免重复跑 `model options`、`model create-spec`、`fee`、`upload`。
+- 创作、批量、主体、音色、素材加白、artifact 的最短链条。
+- 禁止清单：旧命令域、默认参数代决策、单条循环批量任务、直连后端等。
+
+只在驱动器把你引到某个细节模块时才继续读该模块。
+
+## 入口命令
+
+优先直接使用全局 CLI：
 
 ```bash
-LINGJING_AWB_CMD="$(bash "$(dirname "$0")/scripts/resolve-lj-awb-cmd.sh")"
+lj-awb --help
 ```
 
-在普通 Agent 环境中，可直接探测：
+源码调试或不确定路径时再解析：
 
 ```bash
-if ! command -v lj-awb >/dev/null 2>&1; then
-  echo "No usable lj-awb CLI found. Install @lingjingai/lj-awb-cli first." >&2
-  exit 1
-fi
+LINGJING_AWB_CMD="$(bash "$(dirname "$0")/scripts/resolve-lj-awb-cmd.sh")"
 ```
 
-## 2. 模块地图
-
-| 模块 | 处理的问题 | 入口 |
-|------|------------|------|
-| 认证 | access key、登录状态、本地凭据 | [`modules/auth.md`](modules/auth.md) |
-| 账号 | 用户、团队和登录上下文 | [`modules/account.md`](modules/account.md) |
-| 项目 | 项目组查询、切换、创建和更新 | [`modules/project.md`](modules/project.md) |
-| 积分 | 可扣积分余额、项目组预算和用量估算 | [`modules/credits.md`](modules/credits.md) |
-| 模型 | 生图 / 生视频模型、参数约束和创建用法 | [`modules/model.md`](modules/model.md) |
-| 创作入参 | 任务创建参数含义、素材组织、模型配置映射和校验 | [`modules/create-contract.md`](modules/create-contract.md) |
-| 任务手册 | 参考图、首帧、首尾帧、音频参考、主体复用等任务选型 | [`modules/task-manual.md`](modules/task-manual.md) |
-| 上传 | 本地文件上传、COS、素材 URL | [`modules/upload.md`](modules/upload.md) |
-| 图片 | 生图估价、提交、等待、批量 | [`modules/image.md`](modules/image.md) |
-| 视频 | 生视频估价、提交、等待、批量 | [`modules/video.md`](modules/video.md) |
-| 任务 | 任务列表、等待、任务台账 | [`modules/task.md`](modules/task.md) |
-| 资产 | 素材匹配、素材组、素材注册（"加白" / 过审 / 白名单，Seedance / BytePlus / 即梦 系列生视频前可选预处理） | [`modules/asset.md`](modules/asset.md) |
-| 最终产物 | 剧本、资产、视频、剪辑 CRUD 与本地 JSON 导入（artifact 域 4 个子领域共 51 个命令） | [`modules/artifact.md`](modules/artifact.md) |
-| 主体 | 主体发布与查询（KeLing / 可灵 系列生视频专用，提升角色一致性） | [`modules/subject.md`](modules/subject.md) |
-| 工作流 | Agent 面向任务的标准编排流程 | [`modules/workflows.md`](modules/workflows.md) |
-| 压测 | 多轮对话 eval 用例和反模式检查 | [`modules/evals.md`](modules/evals.md) |
-
-## 2.1 触发词索引（用户说什么 → 走哪个模块）
-
-Agent 必须先匹配用户描述里的关键词到对应模块，不要靠"看起来像 X"自由判断。
-
-| 用户描述关键词 | 对应模块 / 流程 | 关键命令 |
-|----------------|------------------|----------|
-| "环境是否就绪" / "能不能跑" / "认证好了吗" / "可以开始了吗" | 启动前自检 | `lj-awb doctor --verify` |
-| "切团队" / "换团队" / "我在哪个团队" / "团队列表" | 团队上下文 | [`account.md`](modules/account.md) → `account info / teams / switch-team` |
-| "切项目" / "换项目组" / "当前项目是哪个" / "新建项目组" | 项目组上下文 | [`project.md`](modules/project.md) → `project list / current / use / create` |
-| "余额" / "够不够" / "扣多少积分" / "查积分" / "项目预算" | 积分与预算 | [`credits.md`](modules/credits.md) → `credits balance / usage` |
-| "有哪些模型" / "支持参考图的模型" / "对比模型" / "推荐模型" / "可灵 / Seedance / GPT Image / Veo" | 模型查询 | [`model.md`](modules/model.md) → `model image-models / video-models / options / create-spec` |
-| "上传文件" / "把这张图传上去" / "上传素材到 COS" / "本地图能用吗" | 上传与素材路径 | [`upload.md`](modules/upload.md) → `upload files`；返回 `backendPath` 直接喂给 `--resource` |
-| "加白" / "加白名单" / "白名单" / "过审" / "走审核" / "预审" / "即梦审核" / "sd2fast 前处理" | 资产注册（Seedance / BytePlus / 即梦 系列生视频专用） | [`asset.md`](modules/asset.md) → `asset register` |
-| "素材组" / "新建素材组" / "白名单分组" / "已有的素材组" | 素材库分组 | [`asset.md`](modules/asset.md) → `asset groups / group / group-create / group-update` |
-| "已有的角色 / 主体" / "查主体" / "看看发布过哪些主体" | 主体查询（避免重复发布） | [`subject.md`](modules/subject.md) → `subject list` |
-| "主体" / "角色" / "角色复用" / "固定角色" / "同一个人" / "可灵生视频角色一致" / "长期复用人物" | 主体发布（KeLing / 可灵 系列生视频专用） | [`subject.md`](modules/subject.md) → `subject publish` → `subject wait` |
-| "参考图" / "用这张图" / "引用这张图" / "参考生" | 参考图生图 / 参考图生视频 | [`task-manual.md`](modules/task-manual.md) → `image:reference` |
-| "让这张图动起来" / "从这张图开始" / "首帧" | 首帧生视频 | [`task-manual.md`](modules/task-manual.md) → `image:first_frame` |
-| "首尾帧" / "从 A 过渡到 B" | 首尾帧生视频 | [`task-manual.md`](modules/task-manual.md) → `image:first_frame` + `image:last_frame` |
-| "音乐" / "配音" / "音频参考" / "节奏参考" / "按这段音频" | 音频参考（输入） | [`task-manual.md`](modules/task-manual.md) → `audio:reference` |
-| "输出音效" / "带不带声音" / "生成的视频有声音吗" | 是否输出音效（不是上传音频） | `--need-audio true/false` |
-| "去字幕" / "把英文字幕擦掉" / "Seedance 字幕处理" | 后处理：视频去字幕 | [`video.md`](modules/video.md) → `video subtitle-remove` |
-| "分镜" / "storyboard" / "镜头 1 / 2 / 3" | 分镜流水线（GPT Image 2 → 视频） | [`workflows.md`](modules/workflows.md) §分镜流水线 |
-| "批量" / "一次跑多条" / "并行" / "n 个任务一起" / "JSONL" / "JSON 数组" | 批量 + 并发 | [`workflows.md`](modules/workflows.md) §批量任务（`*-batch --concurrency`） |
-| "任务状态" / "好了吗" / "完成了没" / "结果出来没" / "继续等" | 任务等待与查询 | [`task.md`](modules/task.md) → `task wait / list / records / record-poll` |
-| "查产物" / "看已有的剧本 / 角色 / 视频 / 剪辑" / "列出所有 X" | artifact 查询 | 进对应 [`artifact/*.md`](modules/artifact.md) 看 `get / rows / row / children / document` |
-| "剧本产物" / "把这版剧本存到 AWB" / "剧本行 / 场 / 镜头节拍" / "script.json 导入" | artifact 之 script 子域 | [`artifact/script.md`](modules/artifact/script.md) |
-| "角色产物" / "道具产物" / "场景产物" / "actor / prop / location 资产" / "资产状态 / state" / "actors.json 导入" | artifact 之 asset 子域 | [`artifact/asset.md`](modules/artifact/asset.md) |
-| "视频集 / 场 / 镜头产物" / "把最终视频回写到项目" / "storyboard 导入" / "回写视频 URL" / "update-clip-urls" | artifact 之 video 子域 | [`artifact/video.md`](modules/artifact/video.md) |
-| "剪辑产物" / "配乐产物" / "字幕烧录产物" / "clip 宽表" / "更新剪辑状态" | artifact 之 clip 子域 | [`artifact/clip.md`](modules/artifact/clip.md) |
-| "本地 JSON 导入" / "最终产物" / "artifact"（笼统说法，没指明子域） | 先回到 artifact 入口选子域 | [`artifact.md`](modules/artifact.md) → 看 4 子域分流 |
-| "认证失败" / "401" / "积分不足" / "等超时" / "exit 10 / 20 / 30" | 错误码恢复 | [`references/error-codes.md`](references/error-codes.md) |
-| "加白边" / "白色边框" / "加白色背景" | **不是 `asset register`**，是图片视觉处理；先确认用户意图 | 不走加白 |
-
-歧义判断：
-
-- 用户说"加白"但描述含糊（既可能是审核也可能是图片视觉处理）时，必须先用一句话确认意图，再选模块。
-- 用户说"存一下 / 写到 AWB / 同步上去"但没指明是哪类产物时，先确认是 script / asset / video / clip 哪个子域，再走 artifact，不要默认选一个开干。
-- 用户说"删掉某条 / 清掉 / 撤回"涉及 artifact 时，先确认是删主体还是删状态（asset 子域里两者都存在，且删主体会级联删状态），不要默认按字面理解。
-- 用户给出复合描述（如"生视频 + 参考图 + 音乐 + 角色一致"）时按优先级路由：先选生成模块（`video.md`），再到 [`task-manual.md`](modules/task-manual.md) 确定资源映射（`image:reference` + `audio:reference` + `subject:reference`），最后回 model 查 `options / resources / constraints` 验证支持组合。不要拆成多次问答让用户重复说明。
-- 用户问"角色一致" / "同一个人"时，先看用户用的模型：KeLing / 可灵系列走 `subject publish`，其他系列（Seedance / 即梦）通常用参考图 + asset register 也能达到效果，不要默认推 subject。
-
-## 3. 深入参考
-
-只有对应 module 把你引到这里时才读：
-
-- [`references/model-options-read.md`](references/model-options-read.md) — 怎么读 `model options` 的默认 text 和 JSON 字段
-
-## 4. 全局规则
-
-§4 只放跨模块的协议级约束。资源短语法、`reference_key` / `<<<key>>>` 对齐、`--need-audio` 不是音频入口、prompt 组装原则等创建参数细节**统一在 [`modules/create-contract.md`](modules/create-contract.md)**，不要在 SKILL.md 里重复定义。
-
-### 4.1 必查（开工前的查询动作）
-
-- 进入正式任务前先运行 `lj-awb doctor --verify`，确认认证、API、项目组和 UTF-8 环境。
-- Agent 不确定命令参数时，优先运行 `lj-awb schema -f json`，不要从记忆里猜。
-- 读取 `schema.commands[].requiredOptions` 和 `requiredAnyOptions` 后再组装命令；缺少必填参数时先问用户或用查询命令补齐。
-- 只读验证命令可以先执行：`auth verify`、`doctor --verify`、模型列表、`model options`、`model create-spec`、账号 / 项目组查询；`auth status` 只看本地配置，不代表远端有效。
-- 不要凭记忆提交模型参数；创作任务前先 `model options` 看参数 / 资源 / 约束，再 `model create-spec` 看如何创建任务。详见 [`modules/create-contract.md`](modules/create-contract.md) §创建前校验。
-
-### 4.2 必确认（执行前的人在回路）
-
-- 读取 `schema.commands[].safety` 决定是否能自动执行：`safeToAutoRun=false` 必须先说明副作用；`requiresConfirmation=true` 时必须先确认再追加 `--yes`。
-- 关键参数是会影响价格或生成效果的枚举：视频 `quality` / `duration` / 约束后仍可选的 `ratio` / 用户明确要输出音效时的 `needAudio`；图片 `quality` / `ratio` / `generateNum`。候选值和默认值来自 `model options.params[]`，**不能静默用默认值**先估价或 dry-run；先把候选值和默认值转成追问。
-- `supportsDryRun=true` 的写入 / 扣费命令，在关键参数已确认后先跑 `--dry-run` 让用户确认请求体，再用 `--yes` 正式提交。
-- 所有正式创作前必须向用户确认：账号、团队、项目组、模型组、关键参数、最终 prompt 文本、参考素材、预估积分。
-- 遇到 exit code `10` / `error.type=confirmation_required`，向用户明确确认后再追加 `--yes` 重试；其他错误恢复策略见 [`references/error-codes.md`](references/error-codes.md)。
-
-### 4.3 必校验（参数 / 资源 / Prompt 组装）
-
-具体规则统一在 [`modules/create-contract.md`](modules/create-contract.md)，这里只列入口：
-
-- 参数枚举值只能从 `model options.params[].values` 选，素材约束按 `model options.resources[]`，参数 / 资源联动收窄按 `model options.constraints[]` — 见 §创建前校验。
-- 资源短语法（`image:reference` / `image:first_frame` / `image:last_frame` / `video:reference` / `audio:reference` / `subject:reference`）和取值优先级（`backendPath` > 本地文件 > 公网 URL > `asset:<id>`）— 见 §素材组织。
-- 视频 `reference_key` / `<<<key>>>` 对齐、图片生图不用 `<<<key>>>`、`--need-audio` 只是输出音效开关而**不是**音频输入 — 见 §素材组织 + §Prompt 组装原则。
-- Prompt 以用户文本为基底，参考图作为素材输入时不要从图像内容反推画面描述塞进 prompt — 见 §Prompt 组装原则。
-
-### 4.4 必规范输出（向用户报告的口径）
-
-- Agent 默认读取 compact text；只有 `schema`、`model options`、`model create-spec`、完整嵌套列表或脚本严格解析时才追加 `-f json`，并只抽取需要字段。
-- 积分确认必须优先报 `billingPointBalance`（来自 `/api/anime/member/benefits/queryGroupPoint`，表示实际可扣积分）；`projectBudgetBalance` 是项目组预算 / ROI 视角，仅作补充，不要说成"积分余额"。
-- CLI 输出字段已归一化（详见 `schema -f json` 的 `data.agentContract.canonicalFields`）。Agent 只识别规范名：`billingPointBalance` / `billingPointRemainingAfter` / `projectBudgetBalance` / `projectBudgetRemainingAfter` / `pointCost`。JSON 中出现 `teamPointBalance` / `projectPointBalance` / `points` 等旧名时，CLI 已在归一化层做 fallback，不要把旧名当成新字段对外报告。
-- 不要把模型列表摘要或缺失参数做成负面能力清单。默认只说明支持的创作意图、必需输入和可控参数；只有用户明确问音频 / 多条数等控制项时，才说明 `model options` 里没有对应参数或资源。
-- 面向用户列模型参数用自然语言：`needAudio` 说成"音效：是否需要输出音效"，不要用 CLI flag 加技术解释；只有展示最终命令时才出现 `--need-audio true/false`。
-- 各 outputKind 的必报字段速查见 [`references/output-fields.md`](references/output-fields.md)。
-
-### 4.5 其他
-
-- `task wait` 的超时只代表当前轮询窗口结束，不代表远端任务失败；继续 `task get` / `task wait` 或读响应里的 `nextCommand`。
-- skill 不直接写沙箱项目的 `output/`；项目级 skill 应在用户确认后负责写回正式产物。
-
-## 5. 安装与更新
-
-推荐安装：
+非单条查询任务、命令不确定或涉及写入 / 扣费时，本轮只读一次机器契约：
 
 ```bash
-npm install -g @lingjingai/lj-awb-cli
+lj-awb schema -f json
 ```
 
-本地源码调试：
+如果用户已经给出完整只读命令，且该命令在本 skill 已知范围内，可以直接执行，不必为了形式补跑 schema。命令名、参数名、requiredOptions、safety、workflow.nextActions 都以 schema 为准。旧根域 `image` / `video` / `asset` / `subject` 不存在，不要尝试旧入口。
+
+## 能力地图
+
+| 能力 | 命令域 | 细节模块 |
+|------|--------|----------|
+| 环境体检、schema | `system` | [`modules/auth.md`](modules/auth.md) |
+| 认证、账号、团队 | `auth` / `account` | [`modules/auth.md`](modules/auth.md)、[`modules/account.md`](modules/account.md) |
+| 项目组与预算上下文 | `project` / `credits` | [`modules/project.md`](modules/project.md)、[`modules/credits.md`](modules/credits.md) |
+| 模型发现、参数约束、创建规格 | `model` | [`modules/model.md`](modules/model.md) |
+| 本地文件上传为 backendPath | `upload` | [`modules/upload.md`](modules/upload.md) |
+| 图片 / 视频 / 去字幕 / 主体 / 音色 / 素材创建 | `create` | [`modules/create.md`](modules/create.md)、[`modules/create-contract.md`](modules/create-contract.md) |
+| 异步任务等待与本地台账 | `task` | [`modules/task.md`](modules/task.md) |
+| 剧本、资产、视频、剪辑最终产物 | `artifact` | [`modules/artifact.md`](modules/artifact.md) |
+
+## 触发分流
+
+| 用户意图 | 先走 |
+|----------|------|
+| “能不能跑 / 认证 / 当前项目 / 余额” | `doctor --verify`，再按需 `account` / `project` / `credits` |
+| “有哪些模型 / 推荐模型 / 用某某模型” | [`modules/model.md`](modules/model.md)，模型口语名默认是平台模型，不是本地工具 |
+| “生图 / 生成图片 / 参考图生图” | [`modules/driver.md`](modules/driver.md) 创作链条 + [`modules/create-contract.md`](modules/create-contract.md) |
+| “生视频 / 首帧 / 首尾帧 / 音频参考 / 让图动起来” | [`modules/driver.md`](modules/driver.md) 创作链条 + [`modules/task-manual.md`](modules/task-manual.md) |
+| “固定角色 / 主体 / 同一个人 / 可灵或 Vidu 角色一致” | [`modules/subject.md`](modules/subject.md) |
+| “主体音色 / 音色克隆 / 给主体配音色” | [`modules/subject.md`](modules/subject.md) |
+| “素材加白 / 白名单 / 过审 / 素材组” | [`modules/asset.md`](modules/asset.md) |
+| “去字幕 / 擦掉英文字幕” | [`modules/video.md`](modules/video.md)，只走 material 任务体系 |
+| “批量 / 多镜头 / 分镜 / JSONL / 并行” | [`modules/workflows.md`](modules/workflows.md) 的批量链条 |
+| “任务好了没 / 继续等 / 查状态” | [`modules/task.md`](modules/task.md) |
+| “写入 AWB / 最终产物 / script / actor / storyboard / clip” | [`modules/artifact.md`](modules/artifact.md) |
+
+歧义词先一句话澄清：`加白` 是素材审核还是视觉白边；`存一下` 是 artifact 哪个子域；`角色一致` 是主体还是一次性参考图。
+
+## 全局硬规则
+
+- schema 中 `safety.requiresConfirmation=true` 的命令必须先向用户确认，再追加 `--yes`。
+- schema 中 `safety.supportsDryRun=true` 的写入 / 扣费命令先 `--dry-run`，确认后再正式执行。
+- 创作类命令在 fee / dry-run 前必须确认会影响价格或效果的关键参数；用户明确说“按默认”后才使用 defaultValue。
+- `fee` 是最终估价，不是参数探索工具。不要为多个 quality / duration / ratio / 渠道组合反复跑 fee。
+- 正式图片 / 视频任务要带 `--project-group-no`，除非命令 schema 没有该参数。
+- 命令返回 `nextCommand`、`nextRefSubject`、`nextVoiceArg` 时优先复用返回值，不手拼。
+- compact text 是默认输出；只有 schema、options、create-spec、完整嵌套结构或脚本解析时用 `-f json`。
+- 积分口径只把 `billingPointBalance` 当可扣积分余额；`projectBudgetBalance` 是项目组预算，不要混说。
+- 不直连 material / asset / 外部服务；所有业务能力统一通过 `lj-awb`。
+
+## 关键参考
+
+- [`modules/driver.md`](modules/driver.md) — Agent 驱动链条和状态账本。
+- [`modules/create-contract.md`](modules/create-contract.md) — 创建参数、素材、prompt、模式互斥。
+- [`modules/task-manual.md`](modules/task-manual.md) — 参考图、首帧、首尾帧、音频参考、主体引用的选型。
+- [`references/error-codes.md`](references/error-codes.md) — 错误恢复。
+- [`references/output-fields.md`](references/output-fields.md) — 各 outputKind 必读字段。
+- [`references/model-options-read.md`](references/model-options-read.md) — 如何读 `model options`。
+
+## 安装与版本
 
 ```bash
-cd anime-cli
-node packages/awb-cli/bin/lj-awb.js --help
+npm install -g @lingjingai/lj-awb-cli
 ```
 
-版本文件：
-
 - [`VERSION`](VERSION)
 - [`compat.json`](compat.json)

package/skills/lj-awb/VERSION

@@ -1 +1 @@
-0.3.15
+0.3.16

package/skills/lj-awb/compat.json

@@ -1,6 +1,6 @@
 {
-  "skillVersion": "0.3.15",
-  "minCliVersion": "0.3.15",
+  "skillVersion": "0.3.16",
+  "minCliVersion": "0.3.16",
   "preferredCommand": "lj-awb",
-  "updatedAt": "2026-05-12"
+  "updatedAt": "2026-05-18"
 }

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

@@ -1,19 +1,19 @@
 # Asset Module
 
-资产模块负责素材库的"分组管理 + 素材注册 + 候选匹配"，**专为 Seedance / BytePlus / 即梦系列生视频前的"加白 / 过审"流程服务**。可灵 / KeLing 系列用 [`subject.md`](subject.md) 的 `subject publish`，不走 asset。
+资产模块负责素材库的"分组管理 + 素材注册 + 候选匹配"，**专为 Seedance / BytePlus / 即梦系列生视频前的"加白 / 过审"流程服务**。可灵 / KeLing 和 Vidu 系列用 [`subject.md`](subject.md) 的 `create subject`，不走 asset。
 
 ## 命令
 
 | 命令 | 用途 |
 |------|------|
-| `lj-awb asset groups --name "<keyword>"` | 查素材组（按名搜，避免重建已有的） |
-| `lj-awb asset group --group-id <id>` | 查素材组详情 + 成员 |
-| `lj-awb asset group-create --name "<name>" --dry-run` | 预览创建素材组 |
-| `lj-awb asset group-create --name "<name>" --yes` | 创建素材组（云端写入） |
-| `lj-awb asset group-update --group-id <id> --name "<name>" --yes` | 改素材组名 |
-| `lj-awb asset register --group-id <id> --url "material/assets/a.png" --name "女主正面" --yes` | 注册已上传素材 |
-| `lj-awb asset register --group-id <id> --file ./a.png --name "女主正面" --yes` | 先上传再注册（一步完成） |
-| `lj-awb asset match-actor --description "..." --tags-json '[{"tagId":"o_102"}]'` | 候选匹配（角色画风 / 标签） |
+| `lj-awb create asset-groups --name "<keyword>"` | 查素材组（按名搜，避免重建已有的） |
+| `lj-awb create asset-group-get --group-id <id>` | 查素材组详情 + 成员 |
+| `lj-awb create asset-group --name "<name>" --dry-run` | 预览创建素材组 |
+| `lj-awb create asset-group --name "<name>" --yes` | 创建素材组（云端写入） |
+| `lj-awb create asset-group-update --group-id <id> --name "<name>" --yes` | 改素材组名 |
+| `lj-awb create asset --group-id <id> --url "material/assets/a.png" --name "女主正面" --yes` | 注册已上传素材 |
+| `lj-awb create asset --group-id <id> --file ./a.png --name "女主正面" --yes` | 先上传再注册（一步完成） |
+| `lj-awb create asset-match-actor --description "..." --tags-json '[{"tagId":"o_102"}]'` | 候选匹配（角色画风 / 标签） |
 
 ## 什么时候用 match-actor
 
@@ -23,31 +23,31 @@
 
 ```bash
 # 1. 找/建分组
-lj-awb asset groups --name "项目X-角色"
-lj-awb asset group-create --name "项目X-角色" --yes
+lj-awb create asset-groups --name "项目X-角色"
+lj-awb create asset-group --name "项目X-角色" --yes
 
 # 2. 注册（本地文件版，自动上传）
-lj-awb asset register --group-id <id> --file ./hero.png --name "主角正面" --dry-run
-lj-awb asset register --group-id <id> --file ./hero.png --name "主角正面" --yes
+lj-awb create asset --group-id <id> --file ./hero.png --name "主角正面" --dry-run
+lj-awb create asset --group-id <id> --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. 终态后用于视频
-lj-awb video create --model-group-code <seedance-code> \
+lj-awb create video --model-group-code <seedance-code> \
   --resource image:reference=material/assets/hero.png \
   ...
 ```
 
 ## 规则
 
-- `asset group-create / group-update / register` 都是云端写入，**必须确认**后追加 `--yes`。
-- 主体 element（视频里的"同一个人"概念）优先走 `subject publish`，不要把素材组 / 素材 ID 当 subjectId 用——两者对应平台不同业务实体。
-- `asset register --file` 在 `--dry-run` 阶段不会真上传，只预览 backendPath 推断结果。
+- `create asset-group` / `create asset-group-update` / `create asset` 都是云端写入，**必须确认**后追加 `--yes`。
+- 主体 element（视频里的"同一个人"概念）优先走 `create subject`，不要把素材组 / 素材 ID 当 subjectId 用——两者对应平台不同业务实体。
+- `create asset --file` 在 `--dry-run` 阶段不会真上传，只预览 backendPath 推断结果。
 - 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"素材"小节。
 
 ## 下一步
 
-- 注册成功 → 把 `assetPath`（形如 `material/assets/a.png`）作为 `--resource image:reference=<path>` 传给 `video create`。
-- 想看 group 里有哪些素材 → `asset group --group-id <id>`。
+- 注册成功 → 把 `assetPath`（形如 `material/assets/a.png`）作为 `--resource image:reference=<path>` 传给 `create video`。
+- 想看 group 里有哪些素材 → `create asset-group-get --group-id <id>`。
 - 长期复用同一角色（可灵）→ 改走 [`subject.md`](subject.md)。

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

@@ -1,6 +1,6 @@
 # Create Contract Module
 
-本模块定义 Agent 创建图片 / 视频任务前必须理解的输入契约。不要直接把平台旧参数塞给 `image create` / `video create`；先用 `model options` 查看参数值、素材约束和条件约束，再用 `model create-spec` 查看创建方式。
+本模块定义 Agent 创建图片 / 视频任务前必须理解的输入契约。不要直接把平台旧参数塞给 `create image` / `create video`；先用 `model options` 查看参数值、素材约束和条件约束，再用 `model create-spec` 查看创建方式。
 
 ## 参数含义
 
@@ -12,7 +12,7 @@
 | `--quality` | 清晰度 / 分辨率档位 | 只能从 `model options.params[key=quality].values` 选择 |
 | `--generate-num` | 生图张数 | 仅图片模型支持时使用 |
 | `--duration` | 生视频时长，单位秒 | 对应平台旧参数 `generated_time`，只能从允许值选择 |
-| `--need-audio` | 是否需要输出音效 | 仅用户明确要求输出音效，且 `model options.params[key=needAudio]` 存在时使用；不是上传音频入口 |
+| `--need-audio` | 是否需要输出音效 | 仅用户明确要求输出音效，且 `model options.params[key=needAudio]` 存在时使用；不是上传音频入口。模型未暴露该 param 时**不要为了"显式关闭"传 `--need-audio false`**，CLI 会以 `argument_error: 模型不支持参数：needAudio` 拒绝；不传等价于不开音效 |
 | `--resource` | 单个素材输入，可重复传 | `type:usage[:key]=path|url|asset:<id>` |
 | `--resources-json` | 多素材输入，适合复杂 keyframe / 批量构造 | JSON 数组或 JSON 文件路径 |
 | `--project-group-no` | 任务归属项目组 | 用户明确指定，或来自当前项目组 |
@@ -57,10 +57,11 @@ JSON 语法：
 - 视频一次性参考图用 `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>`。
+- 可长期复用角色用 `create subject` 生成主体，再用 `subject:reference:<key>=asset:<subjectId>`；`subjectId` 来自 `create subject-wait` 返回的 `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>` 表示首尾帧资产，两者语义不同，不要混用。
+- `subject:reference:<key>=asset:<subjectId>` 表示主体引用，只放主体 ID；`image:reference=asset:<assetId>` / `image:first_frame=asset:<assetId>` / `image:last_frame=asset:<assetId>` 表示素材引用，只放素材资产 ID。主体和素材不要混用。
+- **视频素材模式互斥**：frames 模式（`image:first_frame` / `image:last_frame`）与 reference 模式（`image:reference` / `audio:reference` / `video:reference` / `subject:reference`）在同一次 `create video` 中**不能混用**。后端会以 `api_error code=1007: CLI 视频任务暂不支持 first_frame/last_frame 与 reference 混用` 拒绝。同时需要"图作为起点 + 音频/视频/主体参考"时，统一改用 `image:reference` + 其他 reference，让所有素材都在 reference 模式。
 
 ## Prompt 组装原则
 
@@ -80,6 +81,7 @@ JSON 语法：
 - `image:first_frame` / `image:last_frame` 是首尾帧，不要求 `<<<key>>>`。
 - `subject:reference:<key>` 必须携带 key；是否在 prompt 中写 `<<<key>>>` 由用户表达需要决定。
 - 音频参考可以不带 key；用户要求音频也显式参考时，可以使用 `audio:reference:<key>` 并在 prompt 中引用同名 `<<<key>>>`。
+- **`reference_key` 命名约束**：CLI 用正则 `<<<([^<>\s]+)>>>` 解析 prompt 占位符，所以 key 只要不含 `<` / `>` / 空白即可（中英文、数字、下划线都允许，例如 `hero` / `白发女` / `subject_01`）。Agent 推荐使用**对场景有指代意义的短英文 / 中文词**，避免 `r1` / `tmp` 这种无语义命名——key 会出现在 prompt 文本里，对模型理解和后续审稿都更友好。
 
 ## 模型配置到创建参数的关系
 
@@ -101,18 +103,25 @@ JSON 语法：
 
 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`。
+1. 本轮尚未验证时运行 `doctor --verify`，确认认证、API、项目组和 UTF-8 环境。
+2. 没有可复用候选时运行 `model image-models` 或 `model video-models`，按用户目的筛候选模型。
+3. 向用户展示候选时**不是只列名字**，按三步走：
+   - **基本信息**：`displayName` + `modelDesc`（运营填的特性描述，没填就只报 displayName）+ `taskQueueNum` 的人话表达（0 = 队列空闲 / 1-10 = 排队中 / >10 = 等待较长）。
+   - **参数取值**：对每个候选**并行**跑 `lj-awb model options --model-group-code <code> -f json`，把可控参数实际取值列出来：quality 档位列表 / ratio 比例列表 / video 的 duration 范围 / image 的 generateNum 上限 / 支持的资源模式（reference · first_frame · last_frame · audio · subject） / 是否暴露 needAudio / feeCalcType 转人话。
+   - **追问参数**：用户看完真实选项后再追问 quality / ratio / duration / generateNum。**不要在用户看过 `model options` 输出前就给出 16:9 / 720P 这类自编选项**——必须是模型真实支持的值。
+
+   **不要把 `modelGroupCode` 报给用户**——那是 agent 内部跑命令用的技术 ID，除非用户主动问"具体代码"。**不要自己从 `feeCalcType` / 参数上限里推**价格档 / 质量档 / 成功率。用户描述笼统时给 2-4 个常用候选；用户已经报了口语名时把同族所有变体（不同代次 / fast / pro / 不同渠道）全列出来；即使只匹配到 1 个也要把上面三步走完。
+
+   候选只是渠道差异（同款底模不同 vendor）时，**告诉用户**"这几个是同一底模的不同接入渠道"，并按 `model options` 确认参数是否一致后建议按队列 / 计费选。
+4. 对用户选中的模型，若本轮已读取 `model options` 则直接复用；否则运行 `model options --model-group-code <code> -f json`。
+5. 若本轮已读取 `model create-spec` 则直接复用；否则运行 `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` 获取预估积分。
+12. 用户未提供关键参数时，把 `model options.params[].values` 和 `defaultValue` 转成候选问题；用户选择或确认“按默认”前，不跑 `create image-fee` / `create video-fee`，也不跑 `create --dry-run`。
+13. 跑 `create image-fee` / `create video-fee` 获取预估积分——**只跑一次，参数取用户已确认的那组**。`fee` 是"用户敲定参数后的最终估价"，不是参数探索 / 候选比较工具：不要为了对比价格档跑 `fee` × 多个 `quality` / `duration` / `ratio` 组合，也不要为了横向比同款不同渠道跑 `fee` × 多个 `modelGroupCode`；价格档差异从 `model options.feeCalcType` + 参数取值表里就能口算/展示给用户，比较应该发生在 `model options` 阶段。
 14. 跑 `create --dry-run` 检查请求体和本地素材。
 15. 用户确认模型、项目组、最终 prompt 文本、素材、关键参数和积分后，才追加 `--yes` 正式提交。

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

@@ -0,0 +1,36 @@
+# Create Module
+
+`create` 是所有创建 / 提交动作的统一命令域。不要再拼旧的分散创建入口，也不要把图片 / 视频 / 主体 / 素材当根命令域。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb create image ...` | 提交单条生图任务 |
+| `lj-awb create image-batch ...` | 批量提交生图任务 |
+| `lj-awb create image-fee ...` | 生图估价；关键参数确认后只跑一次 |
+| `lj-awb create video ...` | 提交单条生视频任务 |
+| `lj-awb create video-batch ...` | 批量提交生视频任务 |
+| `lj-awb create video-fee ...` | 生视频估价；关键参数确认后只跑一次 |
+| `lj-awb create video-subtitle-removal --source-task-id <videoTaskId> ...` | 基于 material 来源视频任务提交去字幕 |
+| `lj-awb create subject-list ...` | 查询可复用主体，避免重复发布 |
+| `lj-awb create subject --model-code tx|vidu ...` | 创建可复用主体 element |
+| `lj-awb create subject-wait ...` | 等待主体 externalId 回填 |
+| `lj-awb create subject-batch ...` | 批量创建主体 |
+| `lj-awb create subject-voice-list ...` | 查询已创建音色，避免重复创建 |
+| `lj-awb create subject-voice ...` | 创建主体可引用的自定义音色 |
+| `lj-awb create subject-voice-wait ...` | 等待音色 externalId 回填 |
+| `lj-awb create asset-match-actor ...` | 按描述匹配素材库候选 |
+| `lj-awb create asset-groups ...` | 查询素材组 |
+| `lj-awb create asset-group-get ...` | 查询素材组详情 |
+| `lj-awb create asset-group ...` | 创建素材组 |
+| `lj-awb create asset-group-update ...` | 更新素材组 |
+| `lj-awb create asset ...` | 注册素材 |
+
+## 编排
+
+- 图片 / 视频创建参数和资源绑定仍按 [`create-contract.md`](create-contract.md) 校验。
+- 估价也在 `create` 域：`create image-fee` / `create video-fee`；只在关键参数确认后执行。
+- 状态和等待仍在查询域：`task image-status` / `task video-status` / `task wait` / `create subject-wait` / `create subject-voice-wait` / `task video-subtitle-status`。
+- 所有 `create` 写入或扣费命令正式执行前必须先 `--dry-run`，用户确认后再 `--yes`。
+- 查询型 create 子命令（`subject-list`、`subject-voice-list`、`asset-groups`、`asset-group-get`、`asset-match-actor`）是为了避免重复创建；创建前优先查重。

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

@@ -0,0 +1,106 @@
+# Agent Driver
+
+本模块是 lj-awb skill 的调度层。它不重复解释每个参数，而是规定 Agent 如何最短路径使用 CLI、如何缓存上下文、何时加载其它模块。
+
+## 核心原则
+
+- CLI schema 是命令事实来源：非单条查询任务、命令不确定或涉及写入 / 扣费时，本轮只读一次 `lj-awb schema -f json`，命令名、参数名、安全规则和 nextActions 都以 schema 为准。
+- Skill 是驱动器，不是命令百科。先在本模块决定链路，只在需要时加载一个细节模块。
+- 同一对话维护 AWB 状态账本；除非用户切换账号、团队、项目组、模型、素材、prompt 或关键参数，否则不要重复跑同样的查询。
+- 写入 / 扣费命令遵循 schema safety：`supportsDryRun=true` 先 dry-run，`requiresConfirmation=true` 经用户确认后再 `--yes`。
+- 旧根域 `image` / `video` / `asset` / `subject` 已移除，不要尝试旧入口，也不要给旧命令做兼容推理。
+
+## 状态账本
+
+Agent 在当前任务中记录这些值，后续直接复用：
+
+| 键 | 来源 | 失效条件 |
+|----|------|----------|
+| `schema` | `lj-awb schema -f json` | CLI 版本变化 |
+| `auth/account/team` | `doctor --verify`、`account info` | 登录 / 团队切换 |
+| `projectGroupNo` | `project current` 或用户指定 | 项目组切换 |
+| `modelCandidates` | `model image-models` / `model video-models` | 任务类型或关键词变化 |
+| `modelOptions` / `createSpec` | `model options` / `model create-spec` | `modelGroupCode` 变化 |
+| `backendPath` | `upload files` 或 create dry-run/yes 的 upload 输出 | 本地文件或远端 URL 变化 |
+| `task` | create 返回的 `taskId` / `nextCommand` / wait 结果 | 任务终态后只追加结果 |
+| `subject` | `create subject-list` / `create subject` / `create subject-wait` | 主体名或 `modelCode` 变化 |
+| `voice` | `create subject-voice-list` / `create subject-voice-wait` | 音色名或来源变化 |
+| `artifactProjectId` | 用户给定或 artifact 查询 | 项目切换 |
+
+不要为了“保险”重复跑 `schema`、`doctor --verify`、`project current`、`model options`、`model create-spec`、`fee`、`upload files`。缓存值不够时只补缺的那一步。
+
+## 能力边界
+
+CLI 当前能力分为：
+
+- `system`：`doctor`、`schema`。
+- `auth/account/project/credits`：认证、团队、项目组、积分与预算上下文。
+- `model`：发现图片 / 视频模型，读取参数约束和创建规格。
+- `upload`：把本地文件转成平台 `backendPath`。
+- `create`：图片、视频、视频去字幕、主体、主体音色、素材组和素材注册。
+- `task`：图片 / 视频 / 去字幕等异步任务状态、等待和本地台账。
+- `artifact`：剧本、资产、视频、剪辑最终产物 CRUD 与本地 JSON 导入。
+
+不要把概念名当 command domain。图片、视频、主体、素材是业务对象；命令入口是 `create` / `task` / `artifact`。
+
+## 驱动链条
+
+### 创作任务
+
+1. 若本轮未验证远端认证和项目组，运行 `doctor --verify`，必要时 `project current`。
+2. 根据用户目标选任务类型：生图查 `model image-models`，生视频查 `model video-models`。
+3. 如果同一关键词已有候选，不重复查列表；只在用户换模型关键词时刷新。
+4. 对候选跑 `model options`，展示真实参数和资源能力；用户选定模型后补 `model create-spec`。
+5. 按 [`task-manual.md`](task-manual.md) 选择资源模式，按 [`create-contract.md`](create-contract.md) 校验素材、占位符、`needAudio` 和模式互斥。
+6. 只追问会影响价格 / 效果且用户未给出的关键参数；用户说“默认”才使用 defaultValue。
+7. 参数确认后跑一次 `create image-fee` 或 `create video-fee`，不要用 fee 做多组合探索。
+8. 跑一次 `create image/video --dry-run` 展示最终 prompt、资源、参数、积分。
+9. 用户确认后 `--yes`。返回 `nextCommand` 时直接执行它等待结果。
+
+### 批量任务
+
+- 用户给出 2 条以上同模型同参数任务时，优先建议 `create image-batch` / `create video-batch`。
+- 批量必须带 `--task-record-file .awb/tasks.jsonl`，后续用 `task record-poll` 恢复。
+- 单条失败只重跑失败项，不全批重跑。
+
+### 主体与音色
+
+- 长期复用角色才创建主体；一次性参考图直接走 `image:reference` 或 `image:first_frame`。
+- 创建前先按名称查 `create subject-list`，避免重复发布。
+- `create subject` 必须传 `--model-code tx|vidu`：KeLing / 可灵用 `tx`，Vidu 用 `vidu`。
+- `create subject` 返回 `externalId` 为空时立刻 `create subject-wait`；只用 `externalId` / `nextRefSubject` 做视频主体引用，不要用 `elementId`。
+- 创建音色前先查 `create subject-voice-list`；新建后立刻 `create subject-voice-wait`，拿 `nextVoiceArg` 再创建主体。
+
+### 素材库与加白
+
+- Seedance / BytePlus / 即梦等素材预审走 `create asset-*`；KeLing / Vidu 角色一致性走主体，不走 asset。
+- 创建素材组前先 `create asset-groups --name` 查重；有可用组就复用。
+- `create asset --file` 会在正式阶段自动上传并注册；同一文件多任务复用时，先 `upload files` 缓存 `backendPath`。
+- 注册成功后优先使用 `assetPath`，不要重新上传同一文件。
+
+### Artifact
+
+- `artifact` 使用 `project-id`，不是 `project-group-no`。
+- 批量导入先把涉及的 script / asset / video / clip dry-run 全部跑完，再让用户一次性确认写入面。
+- 部分失败后只针对失败的 row / actor / episode / clip 重试，不删除或重导整批。
+
+## 何时加载其它模块
+
+- 模型候选、参数字段解释：[`model.md`](model.md)。
+- 图片 / 视频资源模式和 prompt 组装：[`task-manual.md`](task-manual.md)、[`create-contract.md`](create-contract.md)。
+- 单独图片或视频业务规则：[`image.md`](image.md)、[`video.md`](video.md)。
+- 主体 / 音色：[`subject.md`](subject.md)。
+- 素材库 / 加白：[`asset.md`](asset.md)。
+- 等待、台账、失败状态：[`task.md`](task.md)、[`../references/error-codes.md`](../references/error-codes.md)。
+- 最终产物：[`artifact.md`](artifact.md) 及其子模块。
+
+## 禁止清单
+
+- 不要重复跑同一个 `model options` / `model create-spec`。
+- 不要在关键参数未确认前 fee 或 dry-run。
+- 不要用默认参数替用户做决定，除非用户明确说按默认。
+- 不要把 `https://*.myqcloud.com/material/...` 回填为素材 source；用 `backendPath`。
+- 不要把 `--need-audio` 当音频输入；音频输入只能是 `audio:reference`。
+- 不要把主体 `elementId` 当 `externalId`。
+- 不要用单条 create 循环处理明显批量任务。
+- 不要直连 material / asset / 外部服务；统一走 `lj-awb`。