@lingjingai/lj-awb-cli-pre 0.3.18 → 0.4.5

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

@@ -4,11 +4,13 @@
 
 ## 核心原则
 
-- CLI schema 是命令事实来源：非单条查询任务、命令不确定或涉及写入 / 扣费时，本轮只读一次 `lj-awb schema -f json`，命令名、参数名、安全规则和 nextActions 都以 schema 为准。
-- 命令或参数不确定时，schema 查询是阻塞前置步骤：先运行精确 schema（例如 `lj-awb schema --domain model --command video-models -f json`）并等结果返回，再根据 `options[].flag` 组织业务命令；不要把 schema 查询和猜测命令放在同一批并行工具调用里。
+- CLI schema 是命令事实来源，但不要默认吞完整 schema：非单条查询任务先读一次 `lj-awb schema --brief -f json`，掌握能力域、安全分组、路由和 agentContract。
+- 执行具体命令前，如果命令、参数、requiredOptions、safety 或 nextActions 不确定，运行精确 schema（例如 `lj-awb schema --domain model --command video-models -f json`）并等结果返回，再根据 `options[].flag` 组织业务命令；不要把 schema 查询和猜测命令放在同一批并行工具调用里。
+- 只有生成覆盖报告、调试 schema 本身或 brief 缺失字段时，才运行完整 `lj-awb schema -f json`。
 - Skill 是驱动器，不是命令百科。先在本模块决定链路，只在需要时加载一个细节模块。
 - 同一对话维护 AWB 状态账本；除非用户切换账号、团队、项目组、模型、素材、prompt 或关键参数，否则不要重复跑同样的查询。
 - 写入 / 扣费命令遵循 schema safety：`supportsDryRun=true` 先 dry-run，`requiresConfirmation=true` 经用户确认后再 `--yes`。
+- 如果 JSON 输出带 `meta._notice.update`，先继续完成当前业务链路，收尾时告知当前版本 / 最新版本并建议 `lj-awb update`；不要静默忽略更新提示。
 - 旧根域 `image` / `video` / `asset` / `subject` 已移除，不要尝试旧入口，也不要给旧命令做兼容推理。
 
 ## 状态账本
@@ -17,7 +19,8 @@ Agent 在当前任务中记录这些值，后续直接复用：
 
 | 键 | 来源 | 失效条件 |
 |----|------|----------|
-| `schema` | `lj-awb schema -f json` | CLI 版本变化 |
+| `agentBrief` | `lj-awb schema --brief -f json` | CLI 版本变化 |
+| `commandSchema:<name>` | `lj-awb schema --domain <domain> --command <command> -f json` | CLI 版本变化或命令不匹配 |
 | `auth/account/team` | `doctor --verify`、`account info` | 登录 / 团队切换 |
 | `projectGroupNo` | `project current` 或用户指定 | 项目组切换 |
 | `modelCandidates` | `model image-models` / `model video-models` | 任务类型或关键词变化 |
@@ -29,7 +32,7 @@ Agent 在当前任务中记录这些值，后续直接复用：
 | `voice` | `create subject-voice-list` / `create subject-voice-wait` | 音色名或来源变化 |
 | `artifactProjectId` | 用户给定或 artifact 查询 | 项目切换 |
 
-不要为了“保险”重复跑 `schema`、`doctor --verify`、`project current`、`model options`、`model create-spec`、`fee`、`upload files`。缓存值不够时只补缺的那一步。
+不要为了“保险”重复跑 `schema --brief`、精确 schema、`doctor --verify`、`project current`、`model options`、`model create-spec`、`fee`、`upload files`。缓存值不够时只补缺的那一步。
 
 ## 能力边界
 
@@ -52,7 +55,7 @@ CLI 当前能力分为：
 1. 若本轮未验证远端认证和项目组，运行 `doctor --verify`，必要时 `project current`。
 2. 根据用户目标选任务类型：生图查 `model image-models`，生视频查 `model video-models`。
 3. 如果同一关键词已有候选，不重复查列表；只在用户换模型关键词时刷新。
-4. 对候选跑 `model options`，通过“模型候选展示门”把真实参数和资源能力展示给用户；用户选定模型后补 `model create-spec`。
+4. 对候选跑 `model options`，通过“模型候选展示门”把真实参数和资源能力展示给用户，然后 STOP 等用户选择或明确授权默认；用户选定模型后补 `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 做多组合探索。
@@ -61,13 +64,16 @@ CLI 当前能力分为：
 
 ### 模型候选展示门
 
-只要用户给了模型口语名（如 `sd2`、`gpt`、`banana`、`可灵`）或模型查询返回候选，Agent 必须先完成这个门槛，才能推荐默认模型 / 默认参数、进入 `fee` 或 `create --dry-run`。
+只要用户给了模型口语名（如 `sd2`、`gpt`、`banana`、`可灵`）或模型查询返回候选，Agent 必须先完成这个门槛，才能推荐默认模型 / 默认参数、进入 `model create-spec`、`fee` 或 `create --dry-run`。
+
+这是硬 STOP 门，不是内部检查清单。Agent 输出候选清单后必须停下，等待用户选择模型和关键参数，或等待用户明确说“按默认 / 你来选”。没有这个确认，不得写批量输入文件、不得估价、不得 dry-run、不得正式 create。
 
 1. 用 schema 或命令帮助确认过滤参数名，模型关键词统一走 `--model <keyword>`，不要猜 `--keyword`。
 2. 跑 `model image-models --model <keyword> -f json` 或 `model video-models --model <keyword> -f json`。用户已经给出口语名时，同族候选全部保留；不要只取第一个。
 3. 对每个候选并行跑 `model options --model-group-code <code> -f json`，读取真实 `quality`、`ratio`、`duration` / `generateNum`、默认值、资源模式和约束。
 4. 必须向用户输出可见清单：模型显示名、描述、排队状态、可选参数、默认值、支持的资源模式（图片 / 视频 / 音频 reference、首帧 / 首尾帧、主体等）、渠道差异。`modelGroupCode` 默认只内部使用，除非用户主动问技术 ID。
 5. 用户看完清单后再问关键参数或给建议。即使只命中 1 个候选，也要展示该模型的真实可选项；不要用“我倾向 4:3 / 5s / 720P”代替候选清单。
+6. 如果精确关键词 0 命中后扩展搜索，必须明确说明“未命中 <原词>，以下是 <扩展词> 候选”，并在清单后 STOP；不要直接把扩展候选当成用户已选模型。
 
 ### 批量任务
 

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

@@ -21,6 +21,7 @@
 | `--ratio` | 需要指定画幅时 | `model options.params[key=ratio].values` |
 | `--quality` | 需要指定清晰度时 | `model options.params[key=quality].values` |
 | `--generate-num` | 指定生成张数；模型暴露该控制项时属于价格关键参数 | `model options.params[key=generateNum].values` |
+| `--model-param key=value` / `--model-params-json` | 新增通用模型配置参数，如 `generation_effort` | `model options.params[]` 中带 `cliArg` / `genericModelParam` 的参数 |
 | `--resource image:reference=...` | 参考图生图 | `model create-spec.supportedIntents.mode=reference` 必须存在 |
 | `--resources-json` | 多参考图或程序化构造 | 同 `--resource`，但用 JSON 数组表达 |
 
@@ -60,8 +61,9 @@ lj-awb create image \
 - 参考图 source.value 取值优先级、"不要复用 myqcloud 完整 URL"、图片生图不使用 `reference_key` / `<<<key>>>` 等规则统一在 [`create-contract.md`](create-contract.md) §素材组织 + §Prompt 组装原则；多张参考图用资源顺序和自然语言指代映射（例如"图一中的白发女保持表情，在图二背景里坐秋千"），不要替用户编 key。
 - `ratio` / `quality` / `generate-num` 不确定时，先查 `model options`，不要猜一个模型不支持的值。
 - `fee` 和 `create --dry-run` 前必须确认缺失的 `ratio`、`quality`、`generate-num`；不要静默用默认值估价。用户说“按默认”后才继续。
+- `generation_effort` 这类新增模型配置参数如果出现在 `model options.params[]`，先把可选值 / `defaultValue` 展示给用户；用户确认后用 `--model-param generation_effort=<value>` 或 `--model-params-json` 传入，不要等专用 CLI flag。
 - 正式提交必须带 `--yes`；如果需要看请求体，先用 `--dry-run`。
-- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`generate_num`、`resources`、`resource`、`customBizId`；模型组和项目组放命令行公共参数。
+- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`generate_num`、`resources`、`resource`、`model_params`、`customBizId`，也可直接写模型配置下划线参数；模型组和项目组放命令行公共参数。
 - **批量是 best-effort**：`create-batch` 子任务**单条失败不会回滚整批**，已成功项依然扣分并产生 taskId。提交后必读响应里每项的 `status` / `taskId` / `error`，给用户汇总"成功 N / 失败 M"，对失败项单独 fix + 重跑（不要全批重跑）。
 - **多镜头 / 多 prompt 时主动建议并行**：用户一次给出 ≥2 个同模型同参数的图片任务（典型场景：分镜、组图、多 prompt 候选）时，Agent 必须先告知"这批可以用 `create image-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 / 调 prompt → 继续单条 create。**不要默认一条一条串行还不告知**，这种沉默会浪费用户时间。
 - 等待超时只代表本轮轮询结束，不能对用户说任务失败。

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

@@ -22,7 +22,7 @@ lj-awb model image-models --model "<keyword>"
 lj-awb model video-models --model "<keyword>"
 ```
 
-候选展示走 [`driver.md`](driver.md) 的“模型候选展示门”：基本信息 → 并行跑 `model options` 列真实参数取值和资源能力 → 看完真实选项后追问。不要把原始 JSON 整段粘给用户，但必须把候选转成用户可读清单；不能只在内部读完 options 后直接代选模型或参数。
+候选展示走 [`driver.md`](driver.md) 的“模型候选展示门”：基本信息 → 并行跑 `model options` 列真实参数取值和资源能力 → 输出用户可读清单 → STOP 等用户选择或明确授权默认。不要把原始 JSON 整段粘给用户，但必须把候选转成用户可读清单；不能只在内部读完 options 后直接代选模型或参数。
 
 用户可见清单至少包含：
 
@@ -31,6 +31,8 @@ lj-awb model video-models --model "<keyword>"
 - 资源能力：reference 支持哪些媒体，是否支持音频参考、视频参考、首帧 / 首尾帧、主体引用。
 - 同底模不同渠道 / Fast / Pro 等差异；如果参数完全一致，可以说明主要按队列、渠道或用户偏好选择。
 
+清单输出后必须停下；没有用户选择或“按默认 / 你来选”的明确授权，不得继续 `model create-spec`、`fee`、`dry-run`、写批量输入文件或 `create`。
+
 模型列表里 `inputModes` / `params` 摘要只用于**初筛**；最终枚举值和限制以 `model options` 为准。`modelGroupCode` 是技术 ID，agent 内部跑命令用，**默认不展示给用户**。
 
 ## 获取参数约束
@@ -38,20 +40,20 @@ lj-awb model video-models --model "<keyword>"
 用户选定模型后，若本轮未缓存该模型的参数约束，运行：
 
 ```bash
-lj-awb model options --model-group-code <modelGroupCode> -f json
+lj-awb model options --model-group-code <modelGroupCode> -f text
 ```
 
-默认 text 输出的字段解释见 [`../references/model-options-read.md`](../references/model-options-read.md)。需要程序化校验时才用 `-f json`。
+默认 pretty 适合展示给用户；Agent 做字段级决策时显式读 `-f text`，字段解释见 [`../references/model-options-read.md`](../references/model-options-read.md)。需要程序化校验完整嵌套结构时才用 `-f json`。
 
 Agent 读取这些字段：
 
-- `params[]`：模型暴露的参数 key 和约束；创建命令 flag 看 `model create-spec`。
+- `params[]`：模型暴露的参数 key 和约束；创建命令写法看 `params[].cliArg` 和 `model create-spec`。新增通用模型配置参数会带 `genericModelParam=true`，用 `--model-param key=value` 或 `--model-params-json` 传入。
 - `params[].values`：枚举取值，创建任务时只能从这里选。
-- `params[].defaultValue`：模型默认值；关键参数不能静默采用默认值，用户选择或确认“按默认”后才继续 fee / dry-run。
+- `params[].defaultValue`：模型默认值；关键参数和有可选值的新增参数不能静默采用默认值，用户选择或确认“按默认”后才继续 fee / dry-run，并在创建命令中显式传入。
 - `params[].maxLength`：prompt 等文本参数的长度限制。
 - `resources[]`：素材媒体约束，包含 `mode`、`mediaType`、`usage`、`valueShapes`、`fileTypes`、数量 / 大小 / 时长限制；frames 资源的 `usage` 可同时包含 `first_frame|last_frame`。`valueShapes` 描述允许的 value 形状（`file|url|platformPath|asset`），与 `source.kind` 的两值枚举不同，详见 [`../references/model-options-read.md`](../references/model-options-read.md)。
-- `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` 表示首帧 / 首尾帧输入后不要让用户继续选择比例。
+- `media=IMAGE` 的 `fileTypes` 是特殊语义：空列表表示不支持 webp，CLI 会把本地或可下载远端 webp 自动转成 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才是强控制允许格式。pretty/text 会把它翻译成 `formats=...` 和 `webpInput=accepted|autoConvertToJPG`。
+- `constraints[]`：条件约束全景，描述某个输入或参数出现后，会限制哪个目标参数或资源能力；例如 `target=ratio` 且 `when=resource.image.frame=present`、`effect=no_selectable_values` 表示首帧 / 首尾帧输入后不要让用户继续选择比例；`effect=resource_limit_overrides` 表示某类素材的数量、大小或时长随条件收紧，读取 `limits`。
 
 ## 获取创建规格
 
@@ -84,14 +86,15 @@ Agent 读取这些字段：
 | `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` | 不传 | 由资源类型推导 |
+| 其他 `params[]` 中带 `cliArg` 的 key | `--model-param <key>=...` / `--model-params-json` / 同名下划线长参数 | 通用模型配置参数，例如 `generation_effort` |
 
 规则：
 
-- `model options` 是参数和素材约束入口；`model create-spec` 是创建方式入口。判断用户需求能否满足，优先看 `create-spec.supportedIntents[]`；素材格式 / 数量 / 时长限制看 `options.resources[]`；参数 / 资源联动看 `options.constraints[]`（`effect=no_selectable_values` 表示触发后该目标参数没有可选枚举，不要追问或传入）。
+- `model options` 是参数和素材约束入口；`model create-spec` 是创建方式入口。判断用户需求能否满足，优先看 `create-spec.supportedIntents[]`；素材格式 / 数量 / 时长限制看 `options.resources[]`；参数 / 资源联动看 `options.constraints[]`（`effect=no_selectable_values` 表示触发后该目标参数没有可选枚举，不要追问或传入；`effect=resource_limit_overrides` 表示触发后按 `limits` 收紧素材约束）。
 - `supportLastFrameOnly` 只表示模型是否支持「仅尾帧」输入；首尾帧过渡能力看 frames 资源的 `usage` 是否包含 `last_frame` 和数量约束。
 - 用户说「上传音频 / 使用音乐 / 配音 / 音频参考」是**素材输入**，先看 `options.resources[]` 有没有 `mediaType=AUDIO usage=reference`；**不要先去找 `needAudio`**（那是输出音效开关）。具体使用规则、`reference_key` / `<<<key>>>` 对齐和 `--need-audio` 不是音频入口等都见 [`create-contract.md`](create-contract.md) §素材组织 + §Prompt 组装原则。
 - 用户要走素材加白 / 素材库过审时，先跑 `model asset-review-models --model-group-code <code>` 判断该模型是否支持以及平台值；不要根据模型名称猜平台，也不要把 `modelGroupCode` 放进资产组或素材创建命令。
-- 关键参数选择、`fee` / `create --dry-run` 前的追问流程、`inputRequirement.visualInputRequired` 检查等创建前校验见 [`create-contract.md`](create-contract.md) §创建前校验。
+- 关键参数选择、`fee` / `create --dry-run` 前的追问流程、`inputRequirement.visualInputRequired` 检查等创建前校验见 [`create-contract.md`](create-contract.md) §创建前校验。`defaultValue` 只用于展示候选默认，不是 Agent 自动代选的依据。
 - 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"模型"小节。
 
 ## 下一步

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

@@ -1,6 +1,6 @@
 # Task Module
 
-任务模块负责图片 / 视频 / 字幕等异步任务的等待、查询和台账恢复。图片 / 视频 / 去字幕任务先用 `create ...` 拿到 `taskId`，主体 / 音色回填用 `create subject-wait` / `create subject-voice-wait`，不要误走 `task wait`。
+任务模块负责图片 / 视频 / 字幕 / 超分等异步任务的等待、查询和台账恢复。图片 / 视频任务可用 `task wait`，去字幕和视频超分优先使用创建响应里的专用 `nextCommand`；主体 / 音色回填用 `create subject-wait` / `create subject-voice-wait`，不要误走 `task wait`。
 
 ## 命令
 
@@ -8,6 +8,8 @@
 |------|------|
 | `lj-awb task list --task-type IMAGE_CREATE --project-group-no <no>` | 列出远端任务（按类型过滤） |
 | `lj-awb task wait --task-id <id> --task-type IMAGE_CREATE --wait-seconds 180` | 等待单个任务进入终态 |
+| `lj-awb task video-subtitle-status --task-id <id>` | 查询去字幕 material 任务 |
+| `lj-awb task video-super-resolution-status --task-id <id>` | 查询视频超分 material 任务 |
 | `lj-awb task records --task-record-file .awb/tasks.jsonl` | 读本地任务台账（未指定 `--task-record-file` 默认 `.awb/tasks.jsonl`） |
 | `lj-awb task records --pending-only --task-record-file .awb/tasks.jsonl` | 只看未终态记录 |
 | `lj-awb task record-poll --task-record-file .awb/tasks.jsonl --wait-seconds 180` | 一次性轮询台账里所有未终态任务 |
@@ -72,6 +74,7 @@ CLI 当前**不暴露 task cancel**；用户问"能不能停掉这个任务"时
 - `task wait` 返回 `task_still_running` 时复述 hint，不要误报失败；`taskStatus=FAILED` 或 `errorMessage` 非空才是真失败。
 - **`task wait` 成功 ≠ 素材库立刻可读**：后端在事务提交后**异步**执行 `saveResourceToMaterial`（`afterCommit` 钩子），即使 `taskStatus=SUCCESS` 拿到 `resultUrls`，对应的 `material` / `asset` 行也可能还没落库。需要立刻复用结果时，优先使用 `resultUrls` / `assetPath` / `taskRecordId` 直接推进；非要查素材库时先 sleep 2-3 秒，不要靠 list 接口密集轮询。
 - 输出字段只提取 `taskId / taskStatus / isTerminal / resultUrls / errorMessage`，详见 [`../references/output-fields.md`](../references/output-fields.md) 的"生图 / 生视频"和"任务台账"小节。
+- `create video-subtitle-removal` / `create video-super-resolution` 返回 `nextCommand` 时直接执行该命令；不要把它改写成通用 `task wait`。
 - 不要把大型 raw JSON 整段塞回上下文。
 - `task list` 是远端查询、`task records` 是本地台账；两者覆盖范围不同（台账只有本机创建的任务）。
 

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

@@ -29,6 +29,6 @@
 - 生视频首帧 / 尾帧 / 参考图：`lj-awb create video ... --resource image:first_frame=material/...`
 - 视频参考音频：`lj-awb create video ... --resource audio:reference=material/...`
 - 主体发布参考图：`lj-awb create subject ... --resource primary:material/...`
-- 注册到素材库（素材加白）：优先让 `lj-awb create asset --group-id <id> --platform <platform> --file ./a.png --name "..." --yes` 自动上传到 `asset-review` 场景；若已单独上传，使用 `--backend-path asset-review/...` 或 `--url asset-review/...`。
+- 注册到素材库（素材加白）：优先让 `lj-awb create asset --group-id <id> --platform <platform> --file ./a.png --name "..." --yes` 自动上传到 `asset-review` 场景；CLI 会按文件类型传 `assetType=Image|Video|Audio`，并对本地文件做图片/视频/音频加白规格预检。不合法时正式执行会询问是否转码，非交互脚本可用 `--auto-convert --yes`。若已单独上传，使用 `--backend-path asset-review/...` 或 `--url asset-review/...`，这类远程路径只能按扩展名推断类型，尺寸 / 帧率 / 时长交给后端校验。
 
 > `create image` / `create video` / `create subject` 传 `--file` / 本地路径时**会自动 upload**——只有需要"先看 backendPath / 跨任务复用同一份素材"时才单独跑 `upload files`。

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

@@ -14,6 +14,9 @@
 | `lj-awb create video-batch --input-file ./video.jsonl --model-group-code <code> --yes` | 批量生视频 |
 | `lj-awb task video-status --task-id <id>` | 查询生视频任务 |
 | `lj-awb task wait --task-id <id> --task-type VIDEO_GROUP --wait-seconds 300` | 等待生视频结果 |
+| `lj-awb create video-super-resolution --object-name <objectName> --yes` | 基于 material objectName 提交视频超分任务 |
+| `lj-awb create video-super-resolution-fee --object-name <objectName>` | 计算视频超分预计积分 |
+| `lj-awb task video-super-resolution-status --task-id <id>` | 查询视频超分任务 |
 | `lj-awb create video-subtitle-removal --source-task-id <videoTaskId> --yes` | 基于来源视频任务提交去字幕任务 |
 | `lj-awb task video-subtitle-status --task-id <subtitleTaskId>` | 查询去字幕任务 |
 
@@ -26,6 +29,7 @@
 | `--ratio` | 指定画幅比例 | `model options.params[key=ratio].values`，并受 `model options.constraints[]` 联动限制 |
 | `--quality` | 指定清晰度 | `model options.params[key=quality].values` |
 | `--need-audio` | 是否需要输出音效 | 仅 `model options.params[key=needAudio]` 存在，且用户明确要求输出音效时 |
+| `--model-param key=value` / `--model-params-json` | 新增通用模型配置参数，如 `generation_effort` | `model options.params[]` 中带 `cliArg` / `genericModelParam` 的参数 |
 | `--resource image:reference[:key]=...` | 参考图生视频 | `model create-spec.supportedIntents.mode=reference` 必须存在，格式 / 数量约束看 `model options.resources[]` |
 | `--resource audio:reference=...` | 参考音频 / 配乐 / 配音 / 节奏参考 | `model options.resources[]` 中必须存在 `mediaType=AUDIO usage=reference` |
 | `--resource image:first_frame=...` | 首帧生视频 | `model create-spec.supportedIntents.mode=frames` 必须存在，且 usage 包含 `first_frame` |
@@ -71,25 +75,30 @@ lj-awb create video \
 - 创建前先看 `inputRequirement.visualInputRequired`。如果为 `true`，必须选择 `supportedIntents` 中的一种素材输入，不能纯 prompt 创建。
 - Agent 向用户解释模型能力时，默认说“支持参考图 / 首帧 / 首尾帧 / 主体引用”等正向能力；不要默认列“无音频参数、无多条数参数”。
 - `fee` 和 `create --dry-run` 前必须确认缺失的关键参数；不要把 `model options.params[].defaultValue` 当成用户选择。用户说“按默认”后才继续。
+- `generation_effort` 这类新增模型配置参数如果出现在 `model options.params[]`，先把可选值 / `defaultValue` 展示给用户；用户确认后用 `--model-param generation_effort=<value>` 或 `--model-params-json` 传入，不要等专用 CLI flag。
 - 面向用户列参数时，`needAudio` 说成“音效：是否需要输出音效”；不要用 CLI flag 加技术解释的写法。只有展示最终命令时才写 `--need-audio true/false`。
 - 音频参考：必须先确认 `model options.resources[]` 暴露 `mediaType=AUDIO usage=reference`，否则不要硬传；统一用 `--resource audio:reference=...` 或 JSON `{ "type": "audio", "usage": "reference" }`。
 - `--need-audio` / `audio:reference` / 资源模式互斥 / `reference_key` 对齐 / `<<<key>>>` 等创建协议统一见 [`create-contract.md`](create-contract.md) §素材组织 + §参数含义，不在本文重复。
 - 使用首帧 / 首尾帧等资源后，如果 `model options.constraints[]` 对 `ratio` 等目标参数返回 `effect=no_selectable_values`，不要再追问或传该参数。
-- `media=IMAGE` 的 `fileTypes` 不要机械理解成唯一允许格式：空列表表示不支持 webp，本地 webp 会自动转 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才按允许列表强校验并尝试转换。默认 text 里看 `formats` 和 `webpInput`，不要把 `formats=...|webp` 理解成"只支持 webp"。
+- `media=IMAGE` 的 `fileTypes` 不要机械理解成唯一允许格式：空列表表示不支持 webp，本地或可下载远端 webp 会自动转 jpg；仅 `webp` 表示普通图片格式外也支持 webp；多值列表才按允许列表强校验并尝试转换。默认 text 里看 `formats` 和 `webpInput`，不要把 `formats=...|webp` 理解成"只支持 webp"。
 - `supportLastFrameOnly=false` 只表示不支持"仅尾帧"；不要据此判断不支持首尾帧过渡。是否可传 `image:last_frame` 看 `model options.resources[].usage` / `model create-spec.supportedIntents[].usage` 是否包含 `last_frame`。
 - 视频素材（参考图 / 首帧 / 尾帧 / 关键帧 / 音频）source.value 取值优先级、不要复用 myqcloud 完整 URL 规则统一在 [`create-contract.md`](create-contract.md) §素材组织。`image:reference=asset:<assetId>` / `image:first_frame=asset:<assetId>` / `image:last_frame=asset:<assetId>` 是素材引用；`subject:reference:<key>=asset:<subjectId>` 是主体引用。主体引用必须先 `create subject` + `create subject-wait` 得到 `externalId`。
-- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`duration`、`need_audio`、`resources`、`resource`、`customBizId`；其中 `need_audio` 表示是否需要输出音效，音频素材仍写入 `resources`。
+- 批量 JSON/JSONL 每项只写 `prompt`、`ratio`、`quality`、`duration`、`need_audio`、`resources`、`resource`、`model_params`、`customBizId`，也可直接写模型配置下划线参数；其中 `need_audio` 表示是否需要输出音效，音频素材仍写入 `resources`。
 - **批量是 best-effort**：`create-batch` 子任务**单条失败不会回滚整批**，已成功项依然扣分并产生 taskId。提交后必读响应里每项的 `status` / `taskId` / `error`，给用户汇总"成功 N / 失败 M"，对失败项单独 fix + 重跑（不要全批重跑）。
 - 视频任务默认可能耗时较长，批量和复杂任务应异步提交并记录 task id。
+- 视频超分直接传 `objectName`，通常是 material backendPath 或 COS 对象路径；正式提交前先跑 `create video-super-resolution-fee`，再 `--dry-run`，确认后 `--yes`，返回后按 `nextCommand` 或 `task video-super-resolution-status` 查询。
 - **多镜头 / 多分镜时主动建议并行**：用户一次给出 ≥2 个同模型同参数的视频任务（典型场景：分镜流水线、批量首尾帧动画）时，Agent 必须先告知"这批可以用 `create video-batch --concurrency N` 并行执行（n 个任务，预计耗时 / 单次估价 × n）"，并询问用户是否要并行。用户同意 → 走 batch；用户希望逐条审稿 → 继续单条 create。**不要默认一条一条串行还不告知**。
+- 视频超分不走 model options/create-spec；它是 material 的对象路径任务，和生视频模型选择链路分离。
 - 去字幕统一走 material 任务体系：用已成功的视频来源任务 ID `create video-subtitle-removal --source-task-id <videoTaskId> --dry-run`，不要直连外部服务；`task video-subtitle-status` 只接收 material 去字幕任务的 `--task-id`。
 - 输出字段速查见 [`../references/output-fields.md`](../references/output-fields.md) 的"生图 / 生视频"小节；错误恢复（积分 / 模型 / 资源约束）见 [`../references/error-codes.md`](../references/error-codes.md)。
 
 ## 下一步
 
 - `create video` 返回 `taskId` + `nextCommand` → 立刻 `task wait --task-id <id> --task-type VIDEO_GROUP --wait-seconds 300`。
+- `create video-super-resolution` 返回 `taskId` + `nextCommand` → 立刻运行返回的 `task video-super-resolution-status --task-id <id>`。
 - `create video-batch` 写 `.awb/tasks.jsonl`，用 [`task.md`](task.md) → `task record-poll` 批量等。
 - 任务终态 `resultUrls` → 通常按集 / 场 / 镜头回写到 [`artifact/video.md`](artifact/video.md)：`artifact video update-clip-urls --project-id <id> --episode-id ... --scene-id ... --clip-id ... --video-urls-json '[...]'`。
 - 任务 `SUCCESS` 后**立刻**用素材库接口找这条视频时可能查不到——后端 `saveResourceToMaterial` 是事务提交后异步执行，详见 [`task.md`](task.md) 规则。优先用 `resultUrls` 直接消费；非要列素材库时先 sleep 2-3 秒。
 - Seedance 原始视频带英文字幕 → 对成功的视频任务运行 `create video-subtitle-removal --source-task-id <videoTaskId> --yes` → `task video-subtitle-status --task-id <subtitleTaskId>`。
+- 需要对现有视频做清晰度提升 → 先确认 `objectName`（material backendPath 或 COS 对象路径），再 `create video-super-resolution-fee` 和 `create video-super-resolution`。
 - 想长期复用同一角色（避免每次都传图） → [`subject.md`](subject.md) 先 `create subject` + `wait` 拿 externalId。

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

@@ -238,7 +238,9 @@ lj-awb create asset-groups --platform JIMENG --name "项目X-角色"
 lj-awb create asset-group --platform JIMENG --name "项目X-角色" --dry-run
 lj-awb create asset-group --platform JIMENG --name "项目X-角色" --yes
 
-# 2. 注册参考图（本地文件版，--file 在 --yes 阶段自动上传 + 注册一步完成）
+# 2. 注册参考素材（本地文件版，--file 在 --yes 阶段自动上传 + 注册一步完成）
+# CLI 会自动按扩展名传 assetType=Image/Video/Audio；本地文件会先校验加白规格。
+# 不合法素材正式执行时会询问是否转码；非交互脚本可追加 --auto-convert。
 lj-awb create asset \
   --group-id <groupId> \
   --platform JIMENG \

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

@@ -20,10 +20,14 @@ CLI 失败时 envelope 形如：
 | `2` | `unknown_command` / `unknown_option` | 命令名 / 参数名打错 | 跑 `lj-awb -h` 或对应子域 `lj-awb <domain> -h` 重查命令 |
 | `3` | `auth_required` | 缺少 access key | 提示用户 `lj-awb auth login --access-key <key>` 或设置 `LINGJING_AWB_ACCESS_KEY` |
 | `3` | `auth_failed` | access key 无效 / 已过期（HTTP 401） | 跑 `auth verify` 确认；提示重新登录 |
+| `3` | `auth_flow_expired` | 浏览器授权链接已过期 | 重新跑 `auth login` 获取新链接 |
+| `3` | `auth_flow_canceled` | 用户在浏览器取消了授权 | 重新跑 `auth login` 重新发起 |
+| `3` | `auth_flow_failed` | 创建登录任务失败 / 授权成功但未返回 accessKey | 看 `details`，稍后重试 `auth login`；持续失败联系平台 |
 | `10` | `confirmation_required` | 写入 / 扣费 / 切换上下文动作未确认 | 向用户复述 `details.action` 后追加 `--yes` 重跑 |
 | `20` | `task_still_running` | 等待窗口结束但任务未终态 | 直接续跑 `task wait --task-id ... --wait-seconds <n>`，**不代表失败** |
 | `20` | `subject_still_pending` | 主体 externalId 尚未回填 | 续跑 `create subject-wait --element-id ... --wait-seconds <n>` |
 | `20` | `subject_voice_still_pending` | 主体音色 externalId 尚未回填 | 续跑 `create subject-voice-wait --voice-record-id ... --wait-seconds <n>` |
+| `20` | `auth_flow_pending` | 浏览器授权等待窗口结束但用户尚未授权 | 用 `details.flowId` 续跑 `auth login --flow-id <flowId>`，**不要重发新 login**，**不代表失败** |
 | `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 / 网络 |
@@ -107,3 +111,23 @@ lj-awb auth verify           # 实际打一次平台 API
 - **reference 模式**：`image:reference` / `audio:reference` / `video:reference` / `subject:reference`
 
 恢复路径：把 `image:first_frame=<source>` 改成 `image:reference=<source>`，让所有素材都在 reference 模式（保留 audio / video / subject 参考），再 `--dry-run` 复核后重跑。不要简单删掉某个素材，应该统一模式。
+
+### 场景 9：浏览器授权登录（auth_flow_*）
+
+浏览器授权登录（`auth login` 不带 `--access-key`）的几种结果：
+
+- `auth_flow_pending`（exit 20）：等待窗口结束、用户还没授权。**不是失败**。用 `details.flowId` 续跑，不要重发新 login：
+
+  ```bash
+  lj-awb auth login --flow-id <flowId>
+  ```
+
+- `auth_flow_expired`（exit 3）：授权链接过期 → 重新 `auth login` 拿新链接。
+- `auth_flow_canceled`（exit 3）：用户在浏览器取消 → 重新 `auth login`。
+
+AI agent / 无法实时看输出时的标准流程：
+
+```bash
+lj-awb auth login --no-wait --json     # 拿 flowId + verifyUrl，发给用户去浏览器授权
+lj-awb auth login --flow-id <flowId>   # 用户授权后续轮询，拿到并保存 accessKey
+```

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

@@ -2,21 +2,26 @@
 
 `model options` 是指定模型组的实时参数约束。不要凭模型名、旧经验或模型列表摘要直接提交创建任务。
 
-## 默认 Text 怎么读
+## 默认 Pretty 怎么读
 
-- 默认 text 是“分区 key=value”：先看 `summary:`，再看 `params:`、`resources:`、`constraints:`，最后看 `next:`。每个分区的 `count` 表示列表数量，列表项使用 `[0]: key=value ...`。
-- `params[]`：模型暴露的可控参数和约束；这里只给参数 key，不给 create 命令 flag。
+- 默认 pretty 会把 `summary`、`params`、`resources`、`constraints`、`next` 渲染成中文摘要和终端表格，适合给用户展示候选模型能力。
+- Agent 做字段级决策时优先用 `-f text`；只有脚本严格解析或必须读完整嵌套结构时才用 `-f json`。
+
+## `-f text` 怎么读
+
+- text 是“分区 key=value”：先看 `summary:`，再看 `params:`、`resources:`、`constraints:`，最后看 `next:`。每个分区的 `count` 表示列表数量，列表项使用 `[0]: key=value ...`。
+- `params[]`：模型暴露的可控参数和约束；优先看 `key`、`cliArg`、`values`、`defaultValue`。已知参数会给专用 flag，新增通用模型配置参数会显示 `cliArg=--model-param / --model-params-json` 和 `genericModelParam=true`。
 - `values`：枚举取值，只能从这里选。
-- `default`：模型默认值；用户没明确指定时通常不必显式传，但清晰度、比例、时长这类关键项仍要确认。
+- `default` / `defaultValue`：模型默认值，只能作为候选默认展示。带可选值或 `defaultValue` 的关键参数不应静默采用；用户明确选择或说“按默认”后才继续 fee / dry-run。
 - `resources[]`：模型暴露的素材媒体约束；这里只给媒体类型、用途和文件限制，不给 `--resource` 写法。
 - `media`：素材媒体类型，例如 `IMAGE`、`VIDEO`、`AUDIO`、`SUBJECT`。
 - `usage`：素材用途，例如 `reference`、`first_frame`、`last_frame`、`keyframe`；同一个资源约束可同时列出 `first_frame|last_frame`。
 - `valueShapes=file|url|platformPath|asset`：声明这个资源 **value 的形状**，可接受本地文件、公网 URL、平台上传后返回的 `backendPath`、平台资产 ID。注意：这不是 `source.kind` 的枚举；`source.kind` 永远只有 `url`、`asset_id` 两种取值——前三种形状统一传 `kind=url`（CLI 按 value 自动识别），最后一种传 `kind=asset_id`。
-- `formats`：文件后缀白名单。
+- `formats`：文件后缀白名单；当 `webpInput=autoConvertToJPG` 时，本地或可下载远端 webp 会在提交前转成 jpg。
 - `files=<=N` / `files=1`：素材数量约束。
 - `lastFrameOnly` / JSON `supportLastFrameOnly`：只表示是否支持“仅尾帧”这种特殊输入；不用于判断 `first_frame + last_frame` 是否成立。没有该能力时，尾帧应和首帧成对使用。
 - `durationMs` / `totalDurationMs`：单个素材和总素材时长约束。
-- `constraints[]`：参数 / 资源之间的联动约束；`target` 是被限制的 CLI 决策字段，`when` 是触发条件，`allowedValues=<none>` + `effect=no_selectable_values` 表示触发后不要再让用户选择该目标参数。
+- `constraints[]`：参数 / 资源之间的联动约束；`target` 是被限制的 CLI 决策字段或资源能力，`when` 是触发条件。`effect=no_selectable_values` 表示触发后不要再让用户选择该目标参数；`effect=resource_limit_overrides` 表示某类素材的数量、大小或时长会随条件收紧，读取 `limits`。
 
 ## JSON 何时用
 
@@ -26,7 +31,7 @@
 lj-awb model options --model-group-code <code> -f json
 ```
 
-JSON 里会保留更完整的参数 / 资源 / 条件约束字段，但仍不承担 create 命令写法。`--resource` 语法、prompt key 绑定和示例统一看 `model create-spec`。
+JSON 里会保留更完整的参数 / 资源 / 条件约束字段。`params[].cliArg` 可直接告诉你创建写法；通用模型配置参数用 `--model-param key=value`、`--model-params-json '{"key":"value"}'`，或同名下划线长参数（如 `--generation-effort high`）传入。`--resource` 语法、prompt key 绑定和示例统一看 `model create-spec`。
 
 ## 使用顺序
 
@@ -41,11 +46,12 @@ JSON 里会保留更完整的参数 / 资源 / 条件约束字段，但仍不承
 
 ## 判断口径
 
-- 不在 `params[]` 里的 CLI 参数不要传。
+- 不在 `params[]` 里的模型配置参数不要传；新增参数如果已出现在 `params[]` 且有 `cliArg`，无需等待 skill/CLI 硬编码专用 flag。
+- `params[].defaultValue` 不是用户选择；把它展示给用户，用户确认后再通过专用 flag 或 `--model-param` 显式传入。
 - 不在 `resources[]` 里的媒体类型 / 用途不要硬拼。
-- 当前用户输入满足 `constraints[].conditions` 时，按 `allowValues` 收窄目标参数；`effect=no_selectable_values` 时不要传该目标参数。
+- 当前用户输入满足 `constraints[].conditions` 时，按 `allowValues` 收窄目标参数；`effect=no_selectable_values` 时不要传该目标参数；`effect=resource_limit_overrides` 时按 `limits` 覆盖对应 `resources[]` 的数量 / 时长等限制。
 - 主体参考看 `media=SUBJECT usage=reference valueShapes=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。
+- `media=IMAGE` 的 `supportedFileTypes` 是 webp 能力标记：空表示不支持 webp，单独 `webp` 表示普通图片格式外也支持 webp，多值才表示强允许列表。pretty/text 里 `WebP=accepted` 或 `webpInput=accepted` 表示可直接传 webp；`autoConvertToJPG` 表示本地或可下载远端 webp 会先转成 jpg。
 - 首帧 / 尾帧不使用 reference_key；是否可传尾帧看 `usage` 是否包含 `last_frame`，具体创建方式看 `model create-spec`。

package/skills/lj-awb/references/output-fields.md

@@ -1,6 +1,6 @@
 # 输出字段速查表
 
-只有以下场景需要展开 `-f json` 读结构化字段：脚本严格解析、模型 / 资源约束读取、批量结果汇总、错误恢复。其他场景默认读 compact text。
+默认输出是给人看的 pretty 表格；Agent 需要读字段时默认显式传 `-f text`，不要从 pretty 里解析字段。只有脚本严格解析或必须读完整嵌套结构时才传 `-f json`。
 
 通用 envelope：`{ status, data, meta, error? }`。任何命令失败时 `status='error'`，详见 [`error-codes.md`](error-codes.md)。
 
@@ -38,9 +38,9 @@
 
 | outputKind | 命令 | 必报给用户 | agent 内部用 | 可丢弃 |
 |------------|------|-----------|--------------|--------|
-| `model_list` | `model image-models` / `video-models` | 模型名、`modelGroupCode`、`taskQueueNum`（排队数） | `modelGroupCode`（下游 create 必填） | 完整 modelList 嵌套 |
-| `model_options` | `model options` | `params[].label/values/defaultValue`、`resources[]`、`constraints[]` | 全部字段（决定 create 入参）。JSON 形状：`params[].{key,label,valueType,values,defaultValue,defaultName}`（参数名是 `key`，**不是** `name`）；`resources[].{media,usage,valueShapes,formats,...}`；`constraints[].{target,when,allowedValues,effect}` | — |
-| `model_create_spec` | `model create-spec` | `intents[]`、`requiredArgs`、`examples` | 全部 | — |
+| `model_list` | `model image-models` / `video-models` | 模型名、`modelGroupCode`、`taskQueueNum`（排队数）、`successRate`（成功率） | `modelGroupCode`（下游 create 必填） | 完整 modelList 嵌套 |
+| `model_options` | `model options` | `params[].label/values/defaultValue/cliArg`、`resources[]`、`constraints[]` | 全部字段（决定 create 入参）。JSON 形状：`params[].{key,label,valueType,values,defaultValue,defaultName,cliArg,genericModelParam}`（参数名是 `key`，**不是** `name`）；通用参数用 `--model-param key=value`；`resources[].{media,usage,valueShapes,formats,...}`；`constraints[].{target,when,allowedValues,effect,limits}`，其中 `resource_limit_overrides` 表示素材数量 / 时长联动限制 | — |
+| `model_create_spec` | `model create-spec` | `intents[]`、`requiredArgs`、`examples`、`parameterControls.userParams[]` | 全部 | — |
 | `model_input_guide` | `model input-guide` | `supportedIntents`、`promptParams`、`resourceUsages` | 全部 | — |
 
 ## 文件上传
@@ -54,13 +54,15 @@
 | outputKind | 命令 | 必报给用户 | agent 内部用 | 可丢弃 |
 |------------|------|-----------|--------------|--------|
 | `fee_estimate` | `create image-fee` / `create video-fee` | `pointCost`、`billingPointBalance`、`billingPointRemainingAfter` | — | budget 嵌套 |
-| `task_submission` | `create image` / `create video` | `taskId`、`pointCost`、`billingPointRemainingAfter`、`nextCommand` | `taskId`、`taskType`（喂给 `task wait`） | uploads 数组、modelGroupCode |
+| `task_submission` | `create image` / `create video` | `taskId`、`pointCost`、`billingPointRemainingAfter`、`nextCommand`、`statusCommand` | `taskId`、`taskType`（喂给 `task wait`） | uploads 数组、modelGroupCode |
 | `batch_task_submission` | `create image-batch` / `create video-batch` | 成功 / 失败计数、首条 `taskId` 用于追踪 | `tasks[]` 每条 taskId + status | localFiles 详情 |
+| `fee_estimate` | `create video-super-resolution-fee` | `pointCost`、`billingPointBalance`、`billingPointRemainingAfter` | — | budget 嵌套 |
+| `task_submission` | `create video-super-resolution` | `taskId`、`pointCost`、`billingPointRemainingAfter`、`nextCommand` | `taskId`、`nextCommand`（喂给 `task video-super-resolution-status`） | request 嵌套 |
 | `task_status` | `task wait` / `task image-status` / `task video-status` | `taskStatus`、`isTerminal`、`resultUrls`、`errorMessage` | `isTerminal`（false → 续 wait）、`timedOut` | `waitedMs`、`gmtCreate` |
 | `subtitle_task_submission` | `create video-subtitle-removal` | `submitted`、`taskId`、`pointCost`、`nextCommand` | `taskId`、`sourceTaskId` | budget 嵌套 |
 | `subtitle_task_status` | `task video-subtitle-status` | `taskStatus`、`isTerminal`、`resultUrls`、`errorMessage` | `taskId` | `gmtCreate` |
 
-> `task_submission.nextCommand` 是平台给出的下一步建议命令（通常是 `task wait --task-id ...`）。看到就直接接着跑。
+> `task_submission.nextCommand` 是平台给出的下一步建议命令（通常是 `task wait --task-id ...`）；`task_submission.statusCommand` 是单次状态查询命令（通常是 `task image-status` / `task video-status`）。
 
 ## 任务台账
 
@@ -94,7 +96,7 @@
 | `asset_group_list` | `create asset-groups` | `platform`、`count` + 组名 | `groupId`（下游 register 必填） | — |
 | `asset_group_detail` | `create asset-group-get` | `platform`、组名、成员数 | `groupId` | — |
 | `asset_group_write_result` | `create asset-group / group-update` | `created/updated`、`groupId`、`platform` | — | — |
-| `asset_register_result` | `create asset` | `registered`、`assetId`、`assetPath`、`platform` | `assetId`（下游引用） | upload 嵌套 |
+| `asset_register_result` | `create asset` | `registered`、`assetId`、`assetPath`、`platform`、`assetType` | `assetId`（下游引用） | upload 嵌套 |
 
 ## Artifact（产物 CRUD）
 
@@ -107,6 +109,7 @@
 | `artifact_delete_result` | `delete-*` | `deleted`、`key`、级联 | — | — |
 | `artifact_import_result` | `* import` / `import-storyboard` / `upsert-batch` | `imported`、`rowCount/actorCount/...`、文件计数 | `rowsByKind`（用于断言） | `batch` 数组 |
 | `artifact_status_update` | `artifact clip update-status` | `updated`、`status` | — | messageCount |
+| `update_result` | `update` / `update --check` | `updateAvailable`、`currentVersion`、`latestVersion`、`command` | `skillUpdated`、`restartRecommended` | 安装日志 |
 
 ## Dry-run
 

package/skills/lj-awb/scripts/resolve-lj-awb-cmd.sh

@@ -1,10 +1,112 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-if command -v lj-awb >/dev/null 2>&1; then
-  printf 'lj-awb\n'
-  exit 0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd)"
+VERSION_FILE="$SKILL_DIR/VERSION"
+COMPAT_FILE="$SKILL_DIR/compat.json"
+
+read_json_string() {
+  local key="$1"
+  local file="$2"
+  sed -n "s/.*\"$key\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$file" 2>/dev/null | head -1
+}
+
+normalize_version() {
+  local version="${1#v}"
+  version="${version%%[-+]*}"
+  printf '%s' "$version"
+}
+
+semver_ge() {
+  local current required
+  current="$(normalize_version "$1")"
+  required="$(normalize_version "$2")"
+
+  local current_major current_minor current_patch
+  local required_major required_minor required_patch
+  IFS=. read -r current_major current_minor current_patch <<< "$current"
+  IFS=. read -r required_major required_minor required_patch <<< "$required"
+
+  current_major="${current_major:-0}"
+  current_minor="${current_minor:-0}"
+  current_patch="${current_patch:-0}"
+  required_major="${required_major:-0}"
+  required_minor="${required_minor:-0}"
+  required_patch="${required_patch:-0}"
+
+  if (( current_major != required_major )); then
+    (( current_major > required_major ))
+    return
+  fi
+  if (( current_minor != required_minor )); then
+    (( current_minor > required_minor ))
+    return
+  fi
+  (( current_patch >= required_patch ))
+}
+
+find_lj_awb() {
+  if command -v lj-awb >/dev/null 2>&1; then
+    command -v lj-awb
+    return 0
+  fi
+
+  if command -v npm >/dev/null 2>&1; then
+    local npm_prefix npm_bin
+    npm_prefix="$(npm prefix -g 2>/dev/null || true)"
+    npm_bin="$npm_prefix/bin/lj-awb"
+    if [ -n "$npm_prefix" ] && [ -x "$npm_bin" ]; then
+      printf '%s\n' "$npm_bin"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+command_version() {
+  local cmd="$1"
+  "$cmd" --version 2>/dev/null | grep -Eo 'v?[0-9]+(\.[0-9]+){2}([-+][0-9A-Za-z.-]+)?' | head -1
+}
+
+SKILL_VERSION="$(cat "$VERSION_FILE" 2>/dev/null || printf '0.4.0')"
+MIN_CLI_VERSION="$(read_json_string minCliVersion "$COMPAT_FILE")"
+MIN_CLI_VERSION="${MIN_CLI_VERSION:-$SKILL_VERSION}"
+CLI_VERSION="${LINGJING_AWB_CLI_VERSION:-$MIN_CLI_VERSION}"
+CLI_PACKAGE="${LINGJING_AWB_CLI_PACKAGE:-@lingjingai/lj-awb-cli}"
+CLI_PACKAGE_SPEC="${LINGJING_AWB_CLI_PACKAGE_SPEC:-$CLI_PACKAGE@$CLI_VERSION}"
+
+if LJ_AWB_CMD="$(find_lj_awb)"; then
+  INSTALLED_VERSION="$(command_version "$LJ_AWB_CMD" || true)"
+  if [ -n "$INSTALLED_VERSION" ] && semver_ge "$INSTALLED_VERSION" "$MIN_CLI_VERSION"; then
+    printf '%s\n' "$LJ_AWB_CMD"
+    exit 0
+  fi
+
+  printf 'Found lj-awb %s, but this skill requires >= %s.\n' "${INSTALLED_VERSION:-unknown}" "$MIN_CLI_VERSION" >&2
+fi
+
+if [ "${LINGJING_AWB_AUTO_INSTALL:-1}" = "0" ]; then
+  printf 'No compatible lj-awb CLI found. Install it first: npm install -g %s\n' "$CLI_PACKAGE_SPEC" >&2
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  printf 'No compatible lj-awb CLI found, and npm is unavailable. Install Node.js >=20 and npm, then run: npm install -g %s\n' "$CLI_PACKAGE_SPEC" >&2
+  exit 1
+fi
+
+printf 'Installing lj-awb CLI: npm install -g %s\n' "$CLI_PACKAGE_SPEC" >&2
+npm install -g "$CLI_PACKAGE_SPEC" >&2
+
+if LJ_AWB_CMD="$(find_lj_awb)"; then
+  INSTALLED_VERSION="$(command_version "$LJ_AWB_CMD" || true)"
+  if [ -n "$INSTALLED_VERSION" ] && semver_ge "$INSTALLED_VERSION" "$MIN_CLI_VERSION"; then
+    printf '%s\n' "$LJ_AWB_CMD"
+    exit 0
+  fi
 fi
 
-printf 'No usable lj-awb CLI found. Install `@lingjingai/lj-awb-cli` first.\n' >&2
+printf 'Installed %s, but lj-awb is still not available on PATH. Check npm global bin path, then retry.\n' "$CLI_PACKAGE_SPEC" >&2
 exit 1