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

package/packages/awb-core/src/update.js

@@ -0,0 +1,327 @@
+import { execFile } from 'node:child_process';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import {
+  LingjingAwbCliError,
+  loadState,
+  nowIso,
+  saveState,
+  toBool,
+  toInt,
+  trimToNull,
+} from './common.js';
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_CLI_PACKAGE_NAME = '@lingjingai/lj-awb-cli';
+const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org/';
+const DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_NPM_TIMEOUT_MS = 15_000;
+const AUTO_CHECK_TIMEOUT_MS = 4_000;
+
+function commandPrefix() {
+  return process.env.LINGJING_AWB_COMMAND_PREFIX || 'lj-awb';
+}
+
+function boolEnv(value) {
+  return ['1', 'true', 'yes', 'y', 'on'].includes(String(value ?? '').trim().toLowerCase());
+}
+
+function readPackageJsonSync(packagePath) {
+  try {
+    return JSON.parse(fsSync.readFileSync(packagePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function corePackagePath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+}
+
+function rootPackagePath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
+}
+
+export async function readCurrentCliVersion() {
+  const pkg = JSON.parse(await fs.readFile(corePackagePath(), 'utf8'));
+  return pkg.version || 'unknown';
+}
+
+function currentRootDir() {
+  return path.dirname(rootPackagePath());
+}
+
+function isLocalCheckout() {
+  return fsSync.existsSync(path.join(currentRootDir(), '.git'));
+}
+
+export function resolveCliPackageName(kwargs = {}) {
+  const explicit = trimToNull(kwargs.packageName || kwargs.package || process.env.LINGJING_AWB_CLI_PACKAGE);
+  if (explicit) return explicit;
+  const rootPkg = readPackageJsonSync(rootPackagePath());
+  const name = trimToNull(rootPkg?.name);
+  return name?.startsWith('@lingjingai/lj-awb-cli') ? name : DEFAULT_CLI_PACKAGE_NAME;
+}
+
+function resolveRegistry(kwargs = {}) {
+  return trimToNull(
+    kwargs.registry
+    || process.env.LINGJING_AWB_UPDATE_REGISTRY
+    || process.env.NPM_CONFIG_REGISTRY
+    || process.env.npm_config_registry,
+  ) || DEFAULT_NPM_REGISTRY;
+}
+
+function updateCheckIntervalMs() {
+  const raw = process.env.LINGJING_AWB_UPDATE_CHECK_INTERVAL_MS;
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_CHECK_INTERVAL_MS;
+  return Math.max(0, toInt(raw, DEFAULT_CHECK_INTERVAL_MS));
+}
+
+function updateCheckDisabled() {
+  return boolEnv(process.env.LINGJING_AWB_DISABLE_UPDATE_CHECK)
+    || boolEnv(process.env.AWB_DISABLE_UPDATE_CHECK)
+    || ['0', 'false', 'off', 'no'].includes(String(process.env.LINGJING_AWB_UPDATE_CHECK ?? '').trim().toLowerCase());
+}
+
+function forceAutoUpdateCheck() {
+  return boolEnv(process.env.LINGJING_AWB_UPDATE_CHECK)
+    || String(process.env.LINGJING_AWB_UPDATE_CHECK || '').trim().toLowerCase() === 'force';
+}
+
+function parseVersion(value) {
+  const text = String(value || '').trim().replace(/^v/i, '');
+  const [main, pre = ''] = text.split('-', 2);
+  const parts = main.split('.').map((item) => Number.parseInt(item, 10));
+  if (parts.some((item) => !Number.isFinite(item))) return null;
+  return { parts, pre };
+}
+
+export function semverLessThan(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return false;
+  for (let index = 0; index < 3; index += 1) {
+    const lv = left.parts[index] || 0;
+    const rv = right.parts[index] || 0;
+    if (lv < rv) return true;
+    if (lv > rv) return false;
+  }
+  if (left.pre && !right.pre) return true;
+  if (!left.pre && right.pre) return false;
+  return left.pre < right.pre;
+}
+
+function npmArgsWithRegistry(args, registry) {
+  return registry ? [...args, `--registry=${registry}`] : args;
+}
+
+function npmInstallSpec(packageName, version) {
+  return version && version !== 'latest' ? `${packageName}@${version}` : packageName;
+}
+
+async function runNpm(args, options = {}) {
+  try {
+    const result = await execFileAsync('npm', args, {
+      cwd: currentRootDir(),
+      encoding: 'utf8',
+      timeout: options.timeoutMs || DEFAULT_NPM_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+      env: process.env,
+    });
+    return result;
+  } catch (error) {
+    const stderr = String(error.stderr || '').trim();
+    const stdout = String(error.stdout || '').trim();
+    throw new LingjingAwbCliError('npm 命令执行失败', {
+      type: 'network_error',
+      exitCode: 30,
+      hint: stderr || stdout || error.message || '请确认 npm 可用，并且当前网络可以访问 npm registry。',
+      details: {
+        command: `npm ${args.join(' ')}`,
+        code: error.code,
+        signal: error.signal,
+      },
+    });
+  }
+}
+
+export async function fetchLatestCliVersion(options = {}) {
+  const mocked = trimToNull(process.env.LINGJING_AWB_UPDATE_LATEST_VERSION);
+  if (mocked) return mocked;
+  const packageName = options.packageName || resolveCliPackageName(options);
+  const registry = options.registry || resolveRegistry(options);
+  const result = await runNpm(
+    npmArgsWithRegistry(['view', packageName, 'version'], registry),
+    { timeoutMs: options.timeoutMs || DEFAULT_NPM_TIMEOUT_MS },
+  );
+  const version = String(result.stdout || '').trim().replace(/^"|"$/g, '');
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new LingjingAwbCliError('无法识别 npm latest 版本', {
+      type: 'runtime_error',
+      exitCode: 1,
+      hint: `npm view ${packageName} version 返回了非 semver 内容。`,
+      details: { version },
+    });
+  }
+  return version;
+}
+
+function buildUpdateNotice({ currentVersion, latestVersion, packageName, checkedAt }) {
+  const command = `${commandPrefix()} update`;
+  return {
+    message: `检测到 ${commandPrefix()} 新版本 ${latestVersion}（当前 ${currentVersion}）。运行 ${command} 更新 CLI 和 skill。`,
+    command,
+    checkCommand: `${commandPrefix()} update --check`,
+    packageName,
+    currentVersion,
+    latestVersion,
+    checkedAt,
+  };
+}
+
+function cachedNotice(state, currentVersion, packageName) {
+  const cached = state?.updateCheck;
+  if (!cached || cached.packageName !== packageName || cached.currentVersion !== currentVersion) return null;
+  if (!cached.latestVersion || !semverLessThan(currentVersion, cached.latestVersion)) return null;
+  return buildUpdateNotice({
+    currentVersion,
+    latestVersion: cached.latestVersion,
+    packageName,
+    checkedAt: cached.checkedAtText || null,
+  });
+}
+
+function shouldSkipAutoCheck() {
+  if (updateCheckDisabled()) return true;
+  if (forceAutoUpdateCheck()) return false;
+  if (process.env.CI) return true;
+  if (isLocalCheckout()) return true;
+  return false;
+}
+
+export async function checkCliUpdate(options = {}) {
+  const currentVersion = options.currentVersion || await readCurrentCliVersion().catch(() => 'unknown');
+  const packageName = resolveCliPackageName(options);
+  if (!currentVersion || currentVersion === 'unknown' || shouldSkipAutoCheck()) return null;
+
+  const state = await loadState().catch(() => ({}));
+  const cached = state?.updateCheck || {};
+  const now = Date.now();
+  const intervalMs = options.force ? 0 : updateCheckIntervalMs();
+  const cacheHit = cached.packageName === packageName
+    && cached.currentVersion === currentVersion
+    && cached.checkedAt
+    && (now - Number(cached.checkedAt) < intervalMs);
+  if (cacheHit) return cachedNotice(state, currentVersion, packageName);
+
+  try {
+    const registry = resolveRegistry(options);
+    const latestVersion = await fetchLatestCliVersion({
+      packageName,
+      registry,
+      timeoutMs: options.timeoutMs || AUTO_CHECK_TIMEOUT_MS,
+    });
+    const checkedAtText = nowIso();
+    await saveState({
+      updateCheck: {
+        packageName,
+        registry,
+        currentVersion,
+        latestVersion,
+        checkedAt: now,
+        checkedAtText,
+      },
+    }).catch(() => {});
+    if (!semverLessThan(currentVersion, latestVersion)) return null;
+    return buildUpdateNotice({ currentVersion, latestVersion, packageName, checkedAt: checkedAtText });
+  } catch (error) {
+    await saveState({
+      updateCheck: {
+        packageName,
+        currentVersion,
+        latestVersion: cached.latestVersion || null,
+        checkedAt: now,
+        checkedAtText: nowIso(),
+        error: error.message || String(error),
+      },
+    }).catch(() => {});
+    return cachedNotice({ updateCheck: cached }, currentVersion, packageName);
+  }
+}
+
+function tailLines(value, limit = 8) {
+  const lines = String(value || '').trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(Math.max(0, lines.length - limit));
+}
+
+export async function runCliUpdate(kwargs = {}) {
+  const currentVersion = await readCurrentCliVersion().catch(() => 'unknown');
+  const packageName = resolveCliPackageName(kwargs);
+  const registry = resolveRegistry(kwargs);
+  const latestVersion = await fetchLatestCliVersion({ packageName, registry });
+  const updateAvailable = currentVersion !== 'unknown' && semverLessThan(currentVersion, latestVersion);
+  const checkOnly = toBool(kwargs.check);
+  const force = toBool(kwargs.force);
+  const installVersion = latestVersion || 'latest';
+  const installSpec = npmInstallSpec(packageName, force ? 'latest' : installVersion);
+  const installArgs = npmArgsWithRegistry(['install', '-g', installSpec], registry);
+
+  if (checkOnly) {
+    return {
+      checked: true,
+      updated: false,
+      updateAvailable,
+      packageName,
+      currentVersion,
+      latestVersion,
+      command: updateAvailable ? `${commandPrefix()} update` : null,
+      message: updateAvailable
+        ? `发现新版本 ${latestVersion}，运行 ${commandPrefix()} update 更新。`
+        : '当前已是最新版本。',
+    };
+  }
+
+  if (!updateAvailable && !force) {
+    return {
+      checked: true,
+      updated: false,
+      updateAvailable: false,
+      packageName,
+      currentVersion,
+      latestVersion,
+      message: '当前已是最新版本。',
+    };
+  }
+
+  const result = await runNpm(installArgs, { timeoutMs: 120_000 });
+  await saveState({
+    updateCheck: {
+      packageName,
+      registry,
+      currentVersion: latestVersion,
+      latestVersion,
+      checkedAt: Date.now(),
+      checkedAtText: nowIso(),
+    },
+  }).catch(() => {});
+
+  return {
+    checked: true,
+    updated: true,
+    updateAvailable,
+    packageName,
+    previousVersion: currentVersion,
+    currentVersion: latestVersion,
+    latestVersion,
+    command: `npm ${installArgs.join(' ')}`,
+    skillUpdated: true,
+    restartRecommended: true,
+    message: '更新完成。请退出并重新打开 AI Agent，以加载最新 CLI 和 skill。',
+    stdoutTail: tailLines(result.stdout),
+    stderrTail: tailLines(result.stderr),
+  };
+}

package/skills/lj-awb/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: lj-awb
-version: 0.3.18
-description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、统一 create 创建域、任务查询、最终产物 artifact CRUD 与本地 JSON 导入。用户说生图、生视频、主体、音色、素材加白、去字幕、artifact 写入或查询时使用。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
+version: 0.4.5
+description: "灵境 AWB CLI skill。使用 `lj-awb` 命令调用动漫平台 / AWB 云端能力，覆盖认证、项目组、积分、模型发现、上传、统一 create 创建域、任务查询、视频超分、最终产物 artifact CRUD 与本地 JSON 导入。用户说生图、生视频、视频超分、主体、音色、素材加白、去字幕、artifact 写入或查询时使用。正式生成、切换项目组、清空认证、artifact 写入等写入或扣费动作前必须确认。"
 metadata:
-  requires:
-    bins: ["lj-awb"]
+  bootstrap:
+    package: "@lingjingai/lj-awb-cli"
+    version: "0.4.5"
+    bin: "lj-awb"
   cliHelp: "lj-awb --help"
 ---
 
 # lj-awb CLI Skill
 
 `lj-awb` 是确定性 CLI，skill 的职责是调度：少查、少问、少重跑，按 schema 和业务链条把命令串对。不要把本 skill 当成一堆命令片段来拼。
+普通命令如果 JSON 输出里出现 `meta._notice.update`，先完成当前用户请求，再告诉用户当前版本和最新版本，并建议执行 `lj-awb update`；更新后提醒重新打开 AI Agent。
 
 ## 先读驱动器
 
@@ -21,31 +24,47 @@ metadata:
 - 创作、批量、主体、音色、素材加白、artifact 的最短链条。
 - 禁止清单：旧命令域、默认参数代决策、单条循环批量任务、直连后端等。
 
-只在驱动器把你引到某个细节模块时才继续读该模块。
+只在驱动器把你引到某个细节模块时才继续读该模块。不要为了“掌握全部功能”一次性加载所有模块。
 
 ## 入口命令
 
-优先直接使用全局 CLI：
+本 skill 是完整入口：如果用户只安装了 skill，也要先自举补齐 CLI。每个新环境第一次使用 `lj-awb` 前，先解析命令：
 
 ```bash
-lj-awb --help
+for dir in "$PWD/skills/lj-awb" "$HOME/.codex/skills/lj-awb" "$HOME/.claude/skills/lj-awb" "$HOME/.cc-switch/skills/lj-awb"; do
+  if [ -x "$dir/scripts/resolve-lj-awb-cmd.sh" ]; then
+    LINGJING_AWB_CMD="$(bash "$dir/scripts/resolve-lj-awb-cmd.sh")"
+    break
+  fi
+done
+: "${LINGJING_AWB_CMD:?lj-awb bootstrap script not found}"
 ```
 
-源码调试或不确定路径时再解析：
+`resolve-lj-awb-cmd.sh` 会按顺序处理：
+
+- 已存在兼容版本 `lj-awb`：直接返回命令路径。
+- 未安装或版本低于 [`compat.json`](compat.json) 的 `minCliVersion`：自动执行 `npm install -g @lingjingai/lj-awb-cli@<minCliVersion>`。
+- 用户要预发环境时，安装前设置 `LINGJING_AWB_CLI_PACKAGE=@lingjingai/lj-awb-cli-pre`。
+- 缺少 npm / Node 时，提示用户先安装 Node.js `>=20`，再重试。
+
+脚本 stdout 只输出可执行命令；安装日志和错误走 stderr。后续命令优先使用解析结果：
 
 ```bash
-LINGJING_AWB_CMD="$(bash "$(dirname "$0")/scripts/resolve-lj-awb-cmd.sh")"
+"$LINGJING_AWB_CMD" --help
 ```
 
 非单条查询任务、命令不确定或涉及写入 / 扣费时，本轮只读一次机器契约：
 
 ```bash
-lj-awb schema -f json
+"$LINGJING_AWB_CMD" schema --brief -f json
 ```
 
-如果只是不确定某个命令参数，优先读精确契约，例如 `lj-awb schema --domain model --command video-models -f json`。schema 查询必须先返回，再组织业务命令；不要把 schema 查询和猜测命令放进同一批并行调用。
+`schema --brief` 只用于掌握能力域、安全分组、业务路由和 agentContract。执行具体命令前，如果命令、参数、requiredOptions、safety 或 nextActions 不确定，再读精确契约，例如 `lj-awb schema --domain model --command video-models -f json`。不要把完整 `lj-awb schema -f json` 当默认入口；只有校验覆盖、脚本生成或 brief 缺失字段时才读完整 schema。
+
+schema 查询必须先返回，再组织业务命令；不要把 schema 查询和猜测命令放进同一批并行调用。
 
 如果用户已经给出完整只读命令，且该命令在本 skill 已知范围内，可以直接执行，不必为了形式补跑 schema。命令名、参数名、requiredOptions、safety、workflow.nextActions 都以 schema 为准。旧根域 `image` / `video` / `asset` / `subject` 不存在，不要尝试旧入口。
+`update` 只做显式安装；`update --check` 只检查不安装。
 
 ## 能力地图
 
@@ -68,6 +87,7 @@ lj-awb schema -f json
 | “有哪些模型 / 推荐模型 / 用某某模型” | [`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) |
+| “超分 / 放大到 2K / 1080P” | [`modules/video.md`](modules/video.md)，传 `objectName` 走 material 视频超分任务体系 |
 | “固定角色 / 主体 / 同一个人 / 可灵或 Vidu 角色一致” | [`modules/subject.md`](modules/subject.md) |
 | “主体音色 / 音色克隆 / 给主体配音色” | [`modules/subject.md`](modules/subject.md) |
 | “素材加白 / 白名单 / 过审 / 素材组” | [`modules/asset.md`](modules/asset.md) |
@@ -86,8 +106,9 @@ lj-awb schema -f json
 - `fee` 是最终估价，不是参数探索工具。不要为多个 quality / duration / ratio / 渠道组合反复跑 fee。
 - 正式图片 / 视频任务要带 `--project-group-no`，除非命令 schema 没有该参数。
 - 命令返回 `nextCommand`、`nextRefSubject`、`nextVoiceArg` 时优先复用返回值，不手拼。
-- compact text 是默认输出；复杂模型命令按 `section:` + 缩进 `key=value` 输出，先按分区读 `summary` / `params` / `resources` / `constraints` / `intents` / `examples` / `next`。只有 schema、options、create-spec、完整嵌套结构或脚本解析时用 `-f json`。
+- 默认输出是面向人类的 pretty 表格；Agent 不要解析 pretty，默认显式传 `-f text` 读取稳定的分区 key=value。只有脚本严格解析或必须读完整嵌套结构时才用 `-f json`。
 - 模型口语名命中后必须过“候选展示门”：先把候选模型、真实参数取值和资源能力转成用户可见清单，再推荐或追问；不能只在内部读完 `model options` 就直接代选默认模型 / 参数。
+- 候选展示门是 STOP gate：输出清单后必须停下等待用户选择模型和关键参数，或等待用户明确说“按默认 / 你来选”。在此之前不得继续 `model create-spec`、`fee`、`dry-run`、写 JSONL 或 `create`。
 - 积分口径只把 `billingPointBalance` 当可扣积分余额；`projectBudgetBalance` 是项目组预算，不要混说。
 - 不直连 material / asset / 外部服务；所有业务能力统一通过 `lj-awb`。
 
@@ -102,6 +123,8 @@ lj-awb schema -f json
 
 ## 安装与版本
 
+如果用户只安装了 skill，第一次使用时会由 bootstrap 脚本自动安装 CLI。手动安装命令如下：
+
 ```bash
 npm install -g @lingjingai/lj-awb-cli
 ```

package/skills/lj-awb/VERSION

@@ -1 +1 @@
-0.3.18
+0.4.5

package/skills/lj-awb/compat.json

@@ -1,6 +1,6 @@
 {
-  "skillVersion": "0.3.18",
-  "minCliVersion": "0.3.18",
+  "skillVersion": "0.4.5",
+  "minCliVersion": "0.4.5",
   "preferredCommand": "lj-awb",
-  "updatedAt": "2026-05-19"
+  "updatedAt": "2026-06-10"
 }

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

@@ -54,7 +54,7 @@ lj-awb artifact asset import --project-id <id> --input-dir 2_asset/output --dry-
 
 - 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传 `id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted` 等审计字段。
 - 写入 / 删除都是逻辑写入，但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
-- 不确定参数时先读 `lj-awb schema --domain artifact --command asset <subcommand> -f json`。
+- 不确定参数时先读精确 schema，例如 `lj-awb schema --domain artifact --command "asset upsert-actor" -f json`。
 - 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
 
 ## 下一步

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

@@ -55,7 +55,7 @@ lj-awb artifact clip delete-episode --project-id <id> --video-episode-id 101 --d
 
 - 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传 `id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted` 等审计字段。
 - 写入 / 删除都是逻辑写入，但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
-- 不确定参数时先读 `lj-awb schema --domain artifact --command clip <subcommand> -f json`。
+- 不确定参数时先读精确 schema，例如 `lj-awb schema --domain artifact --command "clip upsert-episode" -f json`。
 - 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
 
 ## 下一步

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

@@ -28,7 +28,7 @@ lj-awb artifact script import --project-id <id> --input-file script.json --dry-r
 
 - 单条 body 使用 AWB 接口的 camelCase 字段；不要在 body 里传内部审计字段（`id`、`projectId`、`createdAt`、`updatedAt`、`isDeleted`），CLI 会自动注入或忽略。
 - 写入 / 删除都是逻辑写入（不真删数据），但仍需 `--dry-run` 预览 + `--yes` 确认两步走。
-- 不确定参数时先读 `lj-awb schema --domain artifact --command script <subcommand> -f json`。
+- 不确定参数时先读精确 schema，例如 `lj-awb schema --domain artifact --command "script import" -f json`。
 - 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
 
 ## 下一步

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

@@ -55,7 +55,7 @@ lj-awb artifact video import-storyboard --project-id <id> --input-file ep001_sto
 - 单条 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`。
+- 不确定参数时先读精确 schema，例如 `lj-awb schema --domain artifact --command "video upsert-episode" -f json`。
 - 输出字段速查见 [`../../references/output-fields.md`](../../references/output-fields.md) 的"Artifact"小节。
 
 ## 下一步

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

@@ -12,8 +12,11 @@
 | `lj-awb create asset-group --platform JIMENG --name "<name>" --dry-run` | 预览创建素材组 |
 | `lj-awb create asset-group --platform JIMENG --name "<name>" --yes` | 创建素材组（云端写入） |
 | `lj-awb create asset-group-update --group-id <id> --platform JIMENG --name "<name>" --yes` | 改指定平台素材组名 |
-| `lj-awb create asset --group-id <id> --platform JIMENG --url "asset-review/a.png" --name "女主正面" --yes` | 注册已上传素材 |
+| `lj-awb create asset --group-id <id> --platform JIMENG --url "asset-review/a.png" --name "女主正面" --yes` | 注册已上传素材；CLI 自动按扩展名传 `assetType` |
 | `lj-awb create asset --group-id <id> --platform JIMENG --file ./a.png --name "女主正面" --yes` | 先上传到 asset-review 场景再注册（一步完成） |
+| `lj-awb create asset --group-id <id> --platform JIMENG --file ./clip.mp4 --name "参考视频" --dry-run` | 视频素材加白，自动传 `assetType=Video` |
+| `lj-awb create asset --group-id <id> --platform JIMENG --file ./voice.wav --name "参考音频" --dry-run` | 音频素材加白，自动传 `assetType=Audio` |
+| `lj-awb create asset --group-id <id> --platform JIMENG --file ./clip.mov --name "参考视频" --auto-convert --yes` | 本地素材不合法时自动转码为加白规格后上传 |
 | `lj-awb create asset-match-actor --description "..." --tags-json '[{"tagId":"o_102"}]'` | 候选匹配（角色画风 / 标签） |
 
 ## 什么时候用 match-actor
@@ -47,6 +50,12 @@ lj-awb create video --model-group-code <videoModelGroupCode> \
 
 - `create asset-group` / `create asset-group-update` / `create asset` 都是云端写入，**必须确认**后追加 `--yes`。
 - `create asset-*` 平台必须显式传 `--platform JIMENG|BYTEPLUS`；不要依赖默认平台，不要传中文名、小写名或供应商别名。
+- `create asset` 会自动判断并传入 `assetType=Image|Video|Audio`；不要让用户手填资产类型。本地 `--file` 会在提交前校验格式、大小、尺寸、时长、帧率等规则。
+- 本地图片限制：格式 jpeg/jpg、png、webp、bmp、tiff/tif、gif、heic/heif；宽高比（宽/高）在 [0.4,2.5]；宽和高都在 [300,6000] px；单张图片小于 30MB。
+- 本地视频限制：格式 mp4、mov；时长 [2,15] 秒；宽高比（宽/高）在 [0.4,2.5]；宽和高都在 [300,6000] px；总像素数在 [409600,927408]；单个视频不超过 50MB；FPS 在 [24,60]。平台文档里的 480p / 720p 体现在自动转码目标会压到合法像素区间，不再用“短边必须等于 480/720”作为源文件硬过滤。
+- 本地音频限制：格式 wav、mp3；时长 [2,15] 秒。
+- 本地素材不合法时，`--dry-run` 不上传，会返回 `conversionRequired=true` 和 `conversionPlan`；正式执行会询问是否自动转码为合法规格后继续。非交互脚本可追加 `--auto-convert --yes`。
+- 如果本机缺少 `ffprobe` / `ffmpeg`，CLI 在 macOS + Homebrew 环境下会自动运行 `brew install ffmpeg`；其他环境会提示安装命令。需要关闭自动安装时设置 `LINGJING_AWB_AUTO_INSTALL_FFPROBE=0`。
 - `model asset-review-models` 只做发现，不自动创建资产组或素材；不要把 `modelGroupCode` 塞进资产创建命令。
 - 不使用 `/assets/submissions` 这类隐式自动补组流程；资产组是否复用、是否新建由当前任务显式决定。
 - 主体 element（视频里的"同一个人"概念）优先走 `create subject`，不要把素材组 / 素材 ID 当 subjectId 用——两者对应平台不同业务实体。

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

@@ -10,9 +10,13 @@
 | `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 |
+| `lj-awb auth login` | 浏览器授权登录：创建登录任务、展示链接、轮询直到授权成功并自动保存 access key |
+| `lj-awb auth login --no-wait --json` | 只创建登录任务，返回 `flowId` / `verifyUrl`，不阻塞（AI agent / 脚本用） |
+| `lj-awb auth login --flow-id <flowId>` | 复用已有登录任务继续轮询（配合 `--no-wait`，不要重复发起新 login） |
+| `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 logout` | 退出登录：清除本地保存的 access key（无需 `--yes`） |
 | `lj-awb auth clear --dry-run` | 预览清空本地认证 |
 | `lj-awb auth clear --yes` | 确认清空本地认证 |
 
@@ -21,6 +25,10 @@
 - 自动化环境只使用 `LINGJING_AWB_ACCESS_KEY`。
 - 不要把 access key 明文写入对话、日志、文档或任务台账。
 - `auth status` 只读本地配置；正式创作前用 `auth verify`、`account info` 或 `doctor --verify` 确认远端可用。
+- 浏览器授权登录（`auth login` 不带 `--access-key`）默认阻塞轮询，**最长约 10 分钟**等用户在浏览器完成授权；runner 的 timeout 需 ≥ 600s。
+- AI agent / 无法实时看输出的场景：先 `auth login --no-wait --json` 拿 `flowId` + `verifyUrl` 给用户，待用户授权后再 `auth login --flow-id <flowId>` 续轮询；**不要重复发起新的 login**，否则会生成新 `flowId` 使旧链接失效。
+- `auth logout` 退出登录：只清本地 access key，无需 `--yes`。
+- 登录流程相关错误（`auth_flow_expired` / `auth_flow_canceled` / `auth_flow_pending`）见 [`../references/error-codes.md`](../references/error-codes.md)。
 - `auth clear` 是本地破坏性动作，必须先确认或 dry-run。
 - 错误恢复（exit 3 / auth_failed / auth_required）见 [`../references/error-codes.md`](../references/error-codes.md) 场景 4。
 

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

@@ -13,6 +13,8 @@
 | `--generate-num` | 生图张数 | 仅图片模型支持时使用 |
 | `--duration` | 生视频时长，单位秒 | 对应平台旧参数 `generated_time`，只能从允许值选择 |
 | `--need-audio` | 是否需要输出音效 | 仅用户明确要求输出音效，且 `model options.params[key=needAudio]` 存在时使用；不是上传音频入口。模型未暴露该 param 时**不要为了"显式关闭"传 `--need-audio false`**，CLI 会以 `argument_error: 模型不支持参数：needAudio` 拒绝；不传等价于不开音效 |
+| `--model-param key=value` | 新增 / 未硬编码的模型配置参数 | key 必须来自 `model options.params[]`；可重复传。适合 `generation_effort=high` 这类通用 Enum / Boolean / Number / String 配置 |
+| `--model-params-json` | 一次传多个通用模型配置参数 | JSON 对象或 JSON 文件路径；命令行专用参数如 `--ratio`、`--quality`、`--duration` 优先级更高 |
 | `--resource` | 单个素材输入，可重复传 | `type:usage[:key]=path|url|asset:<id>` |
 | `--resources-json` | 多素材输入，适合复杂 keyframe / 批量构造 | JSON 数组或 JSON 文件路径 |
 | `--project-group-no` | 任务归属项目组 | 用户明确指定，或来自当前项目组 |
@@ -94,6 +96,7 @@ JSON 语法：
 | `quality` | `--quality` | `promptParams.quality` | `quality` |
 | `generate_num` | `--generate-num` | `promptParams.generate_num` | `generate_num` |
 | `generated_time` | `--duration` | `promptParams.duration` | `generated_time` |
+| 其他带 `cliArg` 的模型配置参数 | `--model-param <key>=...` / `--model-params-json` | `promptParams.<key>` | 同名透传 |
 | `iref` | `--resource image:reference=...` | `promptParams.resources[]` | `iref` |
 | `frames` | `--resource image:first_frame=...` | `promptParams.resources[]` | `frames` |
 | `multi_param` | `--resource image/video/audio/subject:reference[:key]=...` | `promptParams.resources[]` | `multi_param` |
@@ -117,11 +120,11 @@ Agent 必须按顺序做：
 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[]` 收窄。
+8. 参数枚举值只从 `model options.params[].values` 选择，素材限制只从 `model options.resources[]` 校验，参数 / 资源联动限制按 `model options.constraints[]` 收窄。新增通用参数只要在 `params[]` 中出现且带 `cliArg`，就通过 `--model-param` / `--model-params-json` 显式传入。
 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` 转成候选问题；用户选择或确认“按默认”前，不跑 `create image-fee` / `create video-fee`，也不跑 `create --dry-run`。
+12. 用户未提供关键参数时，把 `model options.params[].values` 和 `defaultValue` 转成候选问题；用户选择或确认“按默认”前，不跑 `create image-fee` / `create video-fee`，也不跑 `create --dry-run`。即使模型给了 `defaultValue`，也不要静默写入请求。
 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

@@ -12,6 +12,8 @@
 | `lj-awb create video ...` | 提交单条生视频任务 |
 | `lj-awb create video-batch ...` | 批量提交生视频任务 |
 | `lj-awb create video-fee ...` | 生视频估价；关键参数确认后只跑一次 |
+| `lj-awb create video-super-resolution ...` | 基于 objectName 提交视频超分任务 |
+| `lj-awb create video-super-resolution-fee ...` | 视频超分估价；先确认 objectName |
 | `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 |
@@ -30,8 +32,8 @@
 ## 编排
 
 - 图片 / 视频创建参数和资源绑定仍按 [`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` 域：`create image-fee` / `create video-fee` / `create video-super-resolution-fee`；只在关键参数确认后执行。
+- 状态和等待仍在查询域：`task image-status` / `task video-status` / `task wait` / `create subject-wait` / `create subject-voice-wait` / `task video-subtitle-status` / `task video-super-resolution-status`。
 - 所有 `create` 写入或扣费命令正式执行前必须先 `--dry-run`，用户确认后再 `--yes`。
 - 查询型 create 子命令（`subject-list`、`subject-voice-list`、`asset-groups`、`asset-group-get`、`asset-match-actor`）是为了避免重复创建；创建前优先查重。
 - `asset-groups` / `asset-group-get` / `asset-group` / `asset-group-update` / `asset` 都必须显式传 `--platform`；平台先由 `model asset-review-models` 或用户选择确定。