@lingjingai/lj-awb-cli-pre 0.3.15

package/skills/lj-awb/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: lj-awb
+version: 0.3.15
+description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、生图、生视频、任务查询、最终产物 artifact CRUD 与本地 JSON 导入。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
+metadata:
+  requires:
+    bins: ["lj-awb"]
+  cliHelp: "lj-awb --help"
+---
+
+# lj-awb CLI Skill
+
+本 skill 教 Agent 如何使用 `lj-awb` CLI。CLI 是传统确定性程序，skill 只负责编排和安全规则，不承载业务 API 调用。
+
+## 1. CLI 入口
+
+```bash
+LINGJING_AWB_CMD="$(bash "$(dirname "$0")/scripts/resolve-lj-awb-cmd.sh")"
+```
+
+在普通 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
+```
+
+## 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
+```
+
+本地源码调试：
+
+```bash
+cd anime-cli
+node packages/awb-cli/bin/lj-awb.js --help
+```
+
+版本文件：
+
+- [`VERSION`](VERSION)
+- [`compat.json`](compat.json)

package/skills/lj-awb/VERSION

@@ -0,0 +1 @@
+0.3.15

package/skills/lj-awb/compat.json

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

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

@@ -0,0 +1,30 @@
+# Account Module
+
+账号模块确认"我是谁、在哪个团队"。**team** 是更高一级的上下文（团队下含多个项目组），不要和 **project group**（[`project.md`](project.md)）混为一谈。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb account info` | 当前用户、团队、项目组、积分摘要（启动后第一条信息） |
+| `lj-awb account teams` | 列出当前账号可访问的团队 |
+| `lj-awb account switch-team --group-id <id> --dry-run` | 预览切换团队 |
+| `lj-awb account switch-team --group-id <id> --yes` | 切换团队（云端写入） |
+
+## 什么时候切团队
+
+- 用户明确说"切换到团队 X / 换个团队 / 我在错误的团队下"。
+- `account info` 显示的 `groupName` 与用户预期不符。
+- 用户访问不到某项目组（`project list` 缺项 / `auth_failed` 但 access key 没变）。
+
+不该切换的场景：
+
+- 用户只是要换"项目"——那是 [`project use`](project.md)，**不是 switch-team**。
+- 用户没明确说要切——`account teams` 列出来给用户挑就够，别擅自切。
+
+## 规则
+
+- `account switch-team` 改变团队上下文，**必须确认**后追加 `--yes`。
+- 切换团队会**重置项目组上下文**：之后跑 `project current` 必然为空，需要让用户重新 `project use --project-group-no <no>` 选一个。
+- 不要把 `account info.groupName`（团队名）当作项目组名报告给用户。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"账号与项目组"小节。

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

@@ -0,0 +1,64 @@
+# Artifact · Asset 子域
+
+资产分三类：角色 (`actor`) / 道具 (`prop`) / 场景 (`location`)，每类都有"主体"和"状态"两级——主体描述资产本身，状态描述某个时刻的造型 / 状态 / 镜头。
+
+所有命令都要求 `--project-id <projectId>`（项目 ID，不是项目组编号）。回到 [`../artifact.md`](../artifact.md) 看完整域概览和导入工作流。
+
+## 查询
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb artifact asset get --project-id <id>` | 查询完整资产产物（含三类全部） |
+| `lj-awb artifact asset actors --project-id <id> --include-states true` | 查询角色列表 |
+| `lj-awb artifact asset actor --project-id <id> --actor-key act_001` | 查询单个角色 |
+| `lj-awb artifact asset props --project-id <id>` | 查询道具列表 |
+| `lj-awb artifact asset prop --project-id <id> --prop-key prop_001` | 查询单个道具 |
+| `lj-awb artifact asset locations --project-id <id>` | 查询场景列表 |
+| `lj-awb artifact asset location --project-id <id> --location-key loc_001` | 查询单个场景 |
+
+## 主体写入 / 删除
+
+```bash
+lj-awb artifact asset upsert-actor --project-id <id> --input-file actor.json --dry-run
+lj-awb artifact asset upsert-prop --project-id <id> --input-file prop.json --dry-run
+lj-awb artifact asset upsert-location --project-id <id> --input-file location.json --dry-run
+
+lj-awb artifact asset delete-actor --project-id <id> --actor-key act_001 --dry-run
+lj-awb artifact asset delete-prop --project-id <id> --prop-key prop_001 --dry-run
+lj-awb artifact asset delete-location --project-id <id> --location-key loc_001 --dry-run
+```
+
+删除主体会级联删除该主体下的所有状态。**删主体和删状态是两个不同操作，用户说"撤回 / 删掉"时先确认是哪一种。**
+
+## 状态写入 / 删除
+
+```bash
+lj-awb artifact asset upsert-actor-state --project-id <id> --actor-key act_001 --input-file state.json --dry-run
+lj-awb artifact asset upsert-prop-state --project-id <id> --prop-key prop_001 --input-file state.json --dry-run
+lj-awb artifact asset upsert-location-state --project-id <id> --location-key loc_001 --input-file state.json --dry-run
+
+lj-awb artifact asset delete-actor-state --project-id <id> --actor-key act_001 --state-key state_001 --dry-run
+lj-awb artifact asset delete-prop-state --project-id <id> --prop-key prop_001 --state-key state_001 --dry-run
+lj-awb artifact asset delete-location-state --project-id <id> --location-key loc_001 --state-key state_001 --dry-run
+```
+
+## 批量导入
+
+```bash
+lj-awb artifact asset import --project-id <id> --input-dir 2_asset/output --dry-run
+```
+
+`asset import` 在 `--input-dir` 下查找 `actors/actors.json`、`props/props.json`、`locations/locations.json`，也兼容扁平的 `actors.json` / `props.json` / `locations.json`；缺哪类资产就跳过哪类，不会报错。
+
+## 规则
+
+- 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传 `id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted` 等审计字段。
+- 写入 / 删除都是逻辑写入，但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
+- 不确定参数时先读 `lj-awb schema --domain artifact --command asset <subcommand> -f json`。
+- 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
+
+## 下一步
+
+- `asset import` 完成 → 接 [`video.md`](video.md) 导入视频集 / 场 / clip。
+- 想给角色加一种新造型 → 用 `upsert-actor-state` 而不是 `upsert-actor`（避免覆盖主体描述）。
+- 不要把这里的 `actor` / `prop` / `location` 和 [`../asset.md`](../asset.md) 的素材库（"加白"用）混为一谈：这里是剧本结构里的资产，那里是平台素材库。

package/skills/lj-awb/modules/artifact/clip.md

@@ -0,0 +1,65 @@
+# Artifact · Clip 子域
+
+剪辑阶段把一个视频集打包成一行宽表产物。和 [`video 子域`](video.md) 不同的是，clip 域里每行只对应一集（不是一个镜头）。
+
+所有命令都要求 `--project-id <projectId>`（项目 ID，不是项目组编号）。回到 [`../artifact.md`](../artifact.md) 看完整域概览和导入工作流。
+
+## ID 矩阵（重要）
+
+clip 子域同时存在两种 ID，搞错会导致命令报参数错或读到错数据：
+
+| 命令 | 用哪个 ID 定位 | 说明 |
+|------|----------------|------|
+| `clip get` | 不需要定位 ID | 返回项目下所有剪辑产物 |
+| `clip episodes` | 不需要定位 ID | 列出项目所有剪辑产物 |
+| `clip episode` | `--video-episode-id <数字>` | 数字主键，由 `upsert-episode` 或 `artifact video episode` 返回的 `id` 字段提供 |
+| `clip episode-by-id` | `--episode-id ep_001` | 业务键（ep_001 等） |
+| `clip upsert-episode` | 不需要定位 ID | body 内含 `videoEpisodeId`，作为本次写入的目标 |
+| `clip upsert-batch` | 不需要定位 ID | body 是数组，每项含 `videoEpisodeId` |
+| `clip update-status` | `--video-episode-id <数字>` | 必须先查到主键 |
+| `clip delete-episode` | `--video-episode-id <数字>` | 必须先查到主键 |
+
+要从业务键拿到数字主键，最常见的链路是：
+
+```bash
+lj-awb artifact video episode --project-id <id> --episode-id ep_001 -f json
+# 取响应 .data.id 作为 video-episode-id
+```
+
+## 查询
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb artifact clip get --project-id <id>` | 查询项目完整剪辑产物 |
+| `lj-awb artifact clip episodes --project-id <id>` | 查询剪辑产物列表 |
+| `lj-awb artifact clip episode --project-id <id> --video-episode-id 101` | 按主键查询单集 |
+| `lj-awb artifact clip episode-by-id --project-id <id> --episode-id ep_001` | 按业务键查询单集 |
+
+## 写入 / 状态 / 删除
+
+```bash
+lj-awb artifact clip upsert-episode --project-id <id> --input-file clip-output.json --dry-run
+lj-awb artifact clip upsert-batch --project-id <id> --input-file clip-batch.json --dry-run
+
+lj-awb artifact clip update-status \
+  --project-id <id> \
+  --video-episode-id 101 \
+  --status music_success \
+  --messages-json '[{"level":"info","step":"music","message":"配乐完成"}]' \
+  --dry-run
+
+lj-awb artifact clip delete-episode --project-id <id> --video-episode-id 101 --dry-run
+```
+
+## 规则
+
+- 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传 `id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted` 等审计字段。
+- 写入 / 删除都是逻辑写入，但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
+- 不确定参数时先读 `lj-awb schema --domain artifact --command clip <subcommand> -f json`。
+- 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
+
+## 下一步
+
+- 想拿到数字主键 `videoEpisodeId` → 先跑 `artifact video episode --project-id <id> --episode-id ep_001 -f json`，取 `.data.id`。
+- 配乐 / 字幕烧录等阶段汇报 → `update-status --video-episode-id <id> --status <state> --messages-json '[...]'`，不要 upsert 整行。
+- 整集失败要回滚 → `delete-episode --video-episode-id <id> --yes`，然后重新 `upsert-episode`。

package/skills/lj-awb/modules/artifact/script.md

@@ -0,0 +1,37 @@
+# Artifact · Script 子域
+
+剧本最终产物按 `rowKind` 分行存储：`document / asset / state / speaker / episode / scene / action`。`document` 是根记录，其余行通过 `entityKey` 和 `parentKey` 串联。
+
+所有命令都要求 `--project-id <projectId>`（项目 ID，不是项目组编号）。回到 [`../artifact.md`](../artifact.md) 看完整域概览和导入工作流。
+
+## 查询
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb artifact script get --project-id <id>` | 查询完整剧本产物（含所有行） |
+| `lj-awb artifact script document --project-id <id>` | 仅查询 document 根记录 |
+| `lj-awb artifact script rows --project-id <id> --row-kind scene` | 查询某种 rowKind 的所有行 |
+| `lj-awb artifact script row --project-id <id> --row-kind action --entity-key "ep_001/scn_001#0"` | 查询单行 |
+| `lj-awb artifact script children --project-id <id> --parent-key scn_001 --row-kind action` | 按 parentKey 查询子节点 |
+
+## 写入 / 删除
+
+```bash
+lj-awb artifact script upsert-row --project-id <id> --input-file row.json --dry-run
+lj-awb artifact script delete-row --project-id <id> --row-kind action --entity-key "ep_001/scn_001#0" --dry-run
+lj-awb artifact script import --project-id <id> --input-file script.json --dry-run
+```
+
+`script import` 会把 `script.json` 拆成 document / asset / state / speaker / episode / scene / action 行批量导入。
+
+## 规则
+
+- 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传内部审计字段（`id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted`），CLI 会自动注入或忽略。
+- 写入 / 删除都是逻辑写入（不真删数据），但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
+- 不确定参数时先读 `lj-awb schema --domain artifact --command script <subcommand> -f json`。
+- 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
+
+## 下一步
+
+- `script import` 完成 → 接 [`asset.md`](asset.md) 导入角色 / 道具 / 场景。
+- 查到某行需要修改 → 用 `upsert-row --input-file <一条 row.json>` 单条更新，不必重新跑 `import`。

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

@@ -0,0 +1,65 @@
+# Artifact · Video 子域
+
+视频最终产物三级结构：集 (`episode`) → 场 (`scene`) → 镜头 (`clip`)。`import-storyboard` 把 `epXXX_storyboard.json` 拆成 episode + scenes + clips 一次导入；`episodeId` 优先取 JSON 字段，否则从 `ep001_storyboard.json` 文件名推断。
+
+所有命令都要求 `--project-id <projectId>`（项目 ID，不是项目组编号）。回到 [`../artifact.md`](../artifact.md) 看完整域概览和导入工作流。
+
+## 查询
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb artifact video get --project-id <id>` | 查询完整视频产物（含全部 episodes/scenes/clips） |
+| `lj-awb artifact video episodes --project-id <id>` | 查询视频集列表 |
+| `lj-awb artifact video episode --project-id <id> --episode-id ep_001` | 查询单集 |
+| `lj-awb artifact video scenes --project-id <id> --episode-id ep_001` | 查询某集下的场列表 |
+| `lj-awb artifact video scene --project-id <id> --episode-id ep_001 --scene-id scn_001` | 查询单场 |
+| `lj-awb artifact video clips --project-id <id> --episode-id ep_001 --scene-id scn_001` | 查询某场下的 clip 列表 |
+| `lj-awb artifact video clip --project-id <id> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001` | 查询单个 clip |
+
+## 写入 / 回写 / 删除
+
+```bash
+lj-awb artifact video upsert-episode --project-id <id> --input-file episode.json --dry-run
+lj-awb artifact video upsert-scene --project-id <id> --episode-id ep_001 --input-file scene.json --dry-run
+lj-awb artifact video upsert-clip --project-id <id> --episode-id ep_001 --scene-id scn_001 --input-file clip.json --dry-run
+
+lj-awb artifact video delete-episode --project-id <id> --episode-id ep_001 --dry-run
+lj-awb artifact video delete-scene --project-id <id> --episode-id ep_001 --scene-id scn_001 --dry-run
+lj-awb artifact video delete-clip --project-id <id> --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 --dry-run
+```
+
+删除 episode 会级联 scenes/clips；删除 scene 会级联 clips。
+
+视频生成完成后只回写 clip 链接（不覆盖 prompt / duration / payload）：
+
+```bash
+lj-awb artifact video update-clip-urls \
+  --project-id <id> \
+  --episode-id ep_001 \
+  --scene-id scn_001 \
+  --clip-id clip_001 \
+  --video-urls-json '["https://example.com/a.mp4"]' \
+  --dry-run
+```
+
+## 批量导入
+
+```bash
+lj-awb artifact video import-storyboard --project-id <id> --input-file ep001_storyboard.json --dry-run
+```
+
+批量 storyboard 需要逐个 episode 文件执行 `import-storyboard`。
+
+## 规则
+
+- 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传 `id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted` 等审计字段。
+- `upsert-episode` 返回的 `id` 是数字主键，下游 [`clip 子域`](clip.md) 的 `--video-episode-id` 必须用这个值，不是 `ep_001` 业务键。
+- 写入 / 删除都是逻辑写入，但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
+- 不确定参数时先读 `lj-awb schema --domain artifact --command video <subcommand> -f json`。
+- 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
+
+## 下一步
+
+- `import-storyboard` 完成 → 进 [`clip.md`](clip.md) 处理剪辑阶段（clip 子域用的 `videoEpisodeId` 就是这里 `upsert-episode` 返回的 `id` 数字主键）。
+- 视频任务终态拿到 `resultUrls` → `update-clip-urls --project-id ... --episode-id ... --scene-id ... --clip-id ... --video-urls-json '[...]'`，只回写链接，不动 prompt / duration。
+- 想看完整三级结构 → `artifact video get --project-id <id>`；只看某集 → `episode` / `scenes` / `clips`。

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

@@ -0,0 +1,65 @@
+# Artifact Module
+
+artifact 模块用于把沙箱 / 本地流水线产出的最终 JSON 写入 AWB 数据库化产物，也可直接查询或单条 CRUD。写入都是云端动作，必须先 dry-run，再经用户确认后追加 `--yes`。
+
+artifact 下有四个子域，结构和 `lj-awb artifact -h` 一致。按用户意图选子域，不要把所有命令塞进一个流程：
+
+| 子域 | 处理的内容 | 入口 |
+|------|------------|------|
+| `artifact script` | 剧本 document / asset / state / speaker / episode / scene / action 行 | [`artifact/script.md`](artifact/script.md) |
+| `artifact asset` | 角色 / 道具 / 场景 及各自状态 | [`artifact/asset.md`](artifact/asset.md) |
+| `artifact video` | 视频集 / 场 / clip 三级最终产物 | [`artifact/video.md`](artifact/video.md) |
+| `artifact clip` | 剪辑宽表（按集组织） | [`artifact/clip.md`](artifact/clip.md) |
+
+## 项目 ID
+
+所有 artifact 命令都需要 `--project-id <projectId>`。沙箱环境通常从环境变量读取：
+
+```bash
+PROJECT_ID="${SANDBOX_PROJECT_ID:?missing SANDBOX_PROJECT_ID}"
+```
+
+`--project-id` 是项目本身的标识，和 `--project-group-no`（项目组编号，用于积分 / 创作类命令）不是同一个概念，不要混用。
+
+## 标准导入工作流
+
+完整流水线推荐顺序：script → asset → video → clip。每步独立，前一步不强依赖后一步，但 clip 的 `videoEpisodeId` 来自 video 阶段返回的主键。
+
+```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-episode \
+  --project-id "$PROJECT_ID" \
+  --input-file 4_clip/output/ep001_clip_output.json \
+  --dry-run
+```
+
+用户确认后，把对应命令的 `--dry-run` 替换为 `--yes`。批量 storyboard 逐 episode 调用；批量 clip 用 `artifact clip upsert-batch`。
+
+## 通用规则
+
+- 不确定命令参数时先读 `lj-awb schema --domain artifact -f json`，再回到对应子域文件。
+- 写入 / 删除全部是逻辑写入（不真删数据），但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
+- 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传内部审计字段（`id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted`），CLI 会自动注入或忽略。
+- 用户说"存一下 / 写到 AWB / 同步上去"但没指明哪类产物时，先确认是 script / asset / video / clip 哪个子域，再走对应子域文件，不要默认选一个开干。
+- 用户说"删掉某条 / 撤回"涉及 asset 子域时，先确认是删主体还是删状态（删主体会级联删状态）。
+- 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"Artifact"小节；写入失败 / argument_error 见 [`../references/error-codes.md`](../references/error-codes.md)。
+
+## 下一步
+
+- 整条流水线：[script.md](artifact/script.md) → [asset.md](artifact/asset.md) → [video.md](artifact/video.md) → [clip.md](artifact/clip.md)，按顺序导入。
+- 视频任务结果回写产物：拿到 `task wait` 的 `resultUrls` → `artifact video update-clip-urls --project-id <id> --episode-id <ep> --scene-id <scn> --clip-id <clip> --video-urls-json '[...]'`。
+- 剪辑阶段状态汇报：`artifact clip update-status --video-episode-id <数字主键> --status <state> --messages-json '[...]'`。

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

@@ -0,0 +1,53 @@
+# Asset Module
+
+资产模块负责素材库的"分组管理 + 素材注册 + 候选匹配"，**专为 Seedance / BytePlus / 即梦系列生视频前的"加白 / 过审"流程服务**。可灵 / KeLing 系列用 [`subject.md`](subject.md) 的 `subject publish`，不走 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"}]'` | 候选匹配（角色画风 / 标签） |
+
+## 什么时候用 match-actor
+
+用户描述"我有这样一个角色，平台上有没有现成可用的"——`match-actor` 按 description + tags 返回候选；命中即免上传 + 注册。具体何时跳过、何时继续注册取决于用户对候选评分的接受度。
+
+## 完整加白流程
+
+```bash
+# 1. 找/建分组
+lj-awb asset groups --name "项目X-角色"
+lj-awb asset group-create --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
+
+# 3. 等审核（asset register 返回 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> \
+  --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 推断结果。
+- 输出字段速查见 [`../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>`。
+- 长期复用同一角色（可灵）→ 改走 [`subject.md`](subject.md)。

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

@@ -0,0 +1,30 @@
+# Auth Module
+
+任何 AWB 工作流开始前，先确认认证状态。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `lj-awb auth status` | 查看本地是否有 access key |
+| `lj-awb auth verify` | 联网校验 access key 是否远端有效 |
+| `lj-awb account info` | 联网确认 access key 有效，并查看当前用户 / 团队 / 项目组 |
+| `lj-awb doctor --verify` | 联网体检认证、API、项目组和运行环境 |
+| `lj-awb auth login --access-key <key>` | 校验并保存 access key |
+| `LINGJING_AWB_ACCESS_KEY=<key> lj-awb auth login` | 从环境变量保存 access key（CLI 自动读环境变量） |
+| `lj-awb auth login --access-key <key> --skip-verify` | 仅保存，不联网校验 |
+| `lj-awb auth clear --dry-run` | 预览清空本地认证 |
+| `lj-awb auth clear --yes` | 确认清空本地认证 |
+
+## 规则
+
+- 自动化环境优先使用 `LINGJING_AWB_ACCESS_KEY`，兼容 `AWB_ACCESS_KEY` / `AWB_CODE` / `ANIME_ACCESS_KEY`。
+- 不要把 access key 明文写入对话、日志、文档或任务台账。
+- `auth status` 只读本地配置；正式创作前用 `auth verify`、`account info` 或 `doctor --verify` 确认远端可用。
+- `auth clear` 是本地破坏性动作，必须先确认或 dry-run。
+- 错误恢复（exit 3 / auth_failed / auth_required）见 [`../references/error-codes.md`](../references/error-codes.md) 场景 4。
+
+## 下一步
+
+- 认证成功 → 进 [`account.md`](account.md) 看用户 / 团队，或直接 [`project.md`](project.md) 选项目组。
+- `auth verify` / `doctor --verify` 通过后，所有创作命令都可以开始。