@lingjingai/lj-awb-cli

v0.3.13

Published

13 hours ago

Lingjing AWB CLI monorepo with shared core, standalone CLI, and agent skills

0High
0Medium
0Low

lizheyong

awb agent cli skill lingjing

lj-awb

lj-awb 是灵境 AWB / 动漫创作平台的命令行客户端。它把平台底层能力封装成稳定、可脚本化、Agent 友好的命令，并随包分发一套 lj-awb skill，方便 Codex、Claude 等 Agent 把自然语言任务编排成确定性的 CLI 调用。

CLI 本身只负责平台调用、参数校验、精简输出和安全确认；自然语言理解、任务规划、项目产物写回由上层 Agent / skill 完成。

用户 / Agent / CI
  -> lj-awb
  -> 灵境 AWB / 动漫平台 API
  -> compact text / JSON 结果

能力概览

| 能力域 | 命令入口 | 说明 | | --- | --- | --- | | 系统 | doctor / schema | 环境体检、联网校验、机器可读命令 schema | | 认证 | auth | access key 状态、校验、保存、清空 | | 账号 | account | 用户、团队和登录上下文 | | 项目 | project | 项目组查询、切换、创建和更新 | | 积分 | credits | 团队 / 项目组积分、任务用量统计 | | 模型 | model | 生图 / 生视频模型发现、模型参数白名单 | | 上传 | upload | 本地图片 / 视频 / 音频上传为平台可访问素材 | | 图片 | image | 生图估价、提交、批量提交、状态查询 | | 视频 | video | 生视频估价、提交、批量提交、状态查询、去字幕 | | 任务 | task | 任务列表、等待、任务台账和台账轮询 | | 资产 | asset | 素材库匹配、素材组、素材注册 | | 主体 | subject | 可复用主体资产发布与查询 |

环境要求

Node.js >=20
可访问灵境 AWB / 动漫平台 API
平台 access key

默认 API 地址由代码内置，也可以通过环境变量覆盖：

export LINGJING_AWB_API_ORIGIN=https://animeworkbench-pre.lingjingai.cn
export LINGJING_AWB_ACCESS_KEY=<access_key>

兼容的 access key 变量：LINGJING_AWB_ACCESS_KEY、AWB_ACCESS_KEY、AWB_CODE、ANIME_ACCESS_KEY。

安装与运行

全局安装：

npm install -g @lingjingai/lj-awb-cli
lj-awb --help
lj-awb auth status

安装包的 postinstall 会默认把随包分发的 lj-awb skill 安装到：

~/.cc-switch/skills/lj-awb
~/.codex/skills/lj-awb

如果设置了 CODEX_HOME，Codex skill 会安装到 $CODEX_HOME/skills/lj-awb。

可用 LINGJING_AWB_SKILL_INSTALL_DIR 指定单一安装目录；如果传入的是以 skills 结尾的根目录，安装器会自动追加 lj-awb。也可用 LINGJING_AWB_SKIP_SKILL_INSTALL=1 跳过 skill 安装。

源码运行：

cd anime-cli
npm run check
npm run smoke
node packages/awb-cli/bin/lj-awb.js --help
packages/awb-cli/bin/lj-awb auth status

macOS 本地 wrapper packages/awb-cli/bin/lj-awb 会自动补充 Node 证书链，适合直接调试 HTTPS 平台接口。

认证

保存 access key 到本地认证文件：

lj-awb auth login-key --access-key <access_key>

从环境变量读取并保存：

LINGJING_AWB_ACCESS_KEY=<access_key> lj-awb auth login-key --from-env

不落盘，直接让每次调用读取环境变量：

export LINGJING_AWB_ACCESS_KEY=<access_key>
lj-awb account info

本地状态文件默认写入：

~/.lingjingai/awb/auth.json
~/.lingjingai/awb/state.json

可用 LINGJING_AWB_STATE_DIR、LINGJING_AWB_AUTH_PATH、LINGJING_AWB_STATE_PATH 覆盖。

常用命令

lj-awb doctor
lj-awb doctor --verify
lj-awb schema -f json
lj-awb schema --domain video -f json
lj-awb auth status
lj-awb account info
lj-awb account teams
lj-awb project list
lj-awb project use --project-group-no <no> --yes
lj-awb credits balance
lj-awb credits usage --project-group-no <no> --last-hours 24
lj-awb model image-models --model Banana
lj-awb model video-models --model Seedance
lj-awb model options --model-group-code <modelGroupCode>
lj-awb model create-spec --model-group-code <modelGroupCode>

正式写入、切换上下文、批量和扣费命令都支持安全确认：

lj-awb image create ... --dry-run
lj-awb image create ... --yes

缺少 --yes 时，CLI 返回 confirmation_required，退出码为 10。task wait 超时返回 task_still_running，退出码为 20。

Agent 接入建议

Agent 不应该靠记忆猜命令参数。进入任务前推荐先读取机器可读契约：

lj-awb schema -f json
lj-awb schema --domain image -f json
lj-awb schema --domain video --command create -f json

正式创作前推荐做一次体检：

lj-awb doctor --verify

doctor 默认只做本地检查；追加 --verify 后会联网校验 access key、当前用户和项目组。schema 返回每个命令的 options[].key，Agent 应使用这些 key 生成 CLI 参数，而不是解析自然语言 help。

schema 还包含面向 Agent 的执行约束：

requiredOptions：必须提供的参数 key。
requiredAnyOptions：每个分组至少提供一个参数 key。
safety.safeToAutoRun：是否允许 Agent 静默执行。
safety.requiresConfirmation：是否必须用户确认后追加 --yes。
safety.supportsDryRun：正式执行前是否可以先 --dry-run。
workflow.recommendedPreflight：推荐前置步骤，例如 doctor、模型查询、估价和 dry-run。

创作任务前按两层读取模型信息：

lj-awb model options --model-group-code <modelGroupCode>
lj-awb model create-spec --model-group-code <modelGroupCode>

model options 专门返回模型参数和资源媒体约束，例如 params[].values、params[].defaultValue、resources[].mediaType、resources[].usage、resources[].fileTypes、resources[].maxFiles、resources[].minDurationMs/maxDurationMs。model create-spec 专门返回如何创建任务，例如 inputRequirement、supportedIntents、preflight 和 examples。默认 text 已经覆盖常用决策字段；只有脚本严格解析或需要完整嵌套结构时才追加 -f json。Agent 应用 options 选参数值和校验素材，再用 create-spec 组装 image create / video create，不要直接把平台旧参数传给 create。上传音频是 resources 素材输入，具体 audio:reference 写法看 create-spec；--need-audio 只是输出音频 / 音效布尔开关。

示例：参考图生成视频

lj-awb project current
lj-awb model video-models --model Seedance
lj-awb model options --model-group-code <modelGroupCode> -f json
lj-awb model create-spec --model-group-code <modelGroupCode> -f json

lj-awb video fee \
  --model-group-code <modelGroupCode> \
  --prompt "参考女主首帧，在雨夜街头奔跑，电影感运镜" \
  --resource image:first_frame=./actor.png \
  --ratio 9:16 \
  --quality 720 \
  --duration 5 \
  --project-group-no <projectGroupNo>

lj-awb video create \
  --model-group-code <modelGroupCode> \
  --prompt "参考女主首帧，在雨夜街头奔跑，电影感运镜" \
  --resource image:first_frame=./actor.png \
  --ratio 9:16 \
  --quality 720 \
  --duration 5 \
  --project-group-no <projectGroupNo> \
  --task-record-file .awb/tasks.jsonl \
  --yes

lj-awb task wait \
  --task-id <taskId> \
  --task-type VIDEO_GROUP \
  --project-group-no <projectGroupNo> \
  --wait-seconds 300

首尾帧也可以直接使用平台资产 ID：

lj-awb video create \
  --model-group-code <modelGroupCode> \
  --prompt "参考首帧生成一段镜头推进视频" \
  --resource image:first_frame=asset:<assetId> \
  --duration 5 \
  --dry-run

批量创建支持 JSON / JSONL / 纯文本 prompt。JSON/JSONL 每项只写单个任务的差异字段，模型组、项目组、台账文件等公共参数仍放在命令行：

{"prompt":"镜头推进","duration":5,"quality":"720","resources":[{"type":"image","usage":"first_frame","source":{"kind":"url","value":"./first.png"}}]}

如果参考图会复用，推荐先发布主体资产：

lj-awb subject publish --name 女主 --primary-file ./actor.png --yes
lj-awb subject wait --element-id <elementId> --wait-seconds 300
lj-awb video create \
  --model-group-code <modelGroupCode> \
  --prompt "<<<女主>>> 在雨夜街头奔跑，电影感运镜" \
  --resource subject:reference:女主=asset:<externalId> \
  --project-group-no <projectGroupNo> \
  --yes

JSON 输出契约

默认输出是 compact text，适合终端和 Agent 低 token 读取；只有需要完整嵌套结构、稳定 JSON envelope 或脚本严格解析时才追加 -f json 或 --json。schema 通常使用 JSON；model options 和 model create-spec 默认 text 先读，必要时再切 JSON。

输出字段只保留后续动作不可替代的信息。默认不返回平台原始 raw、COS 签名细节、重复的首个结果字段；任务结果统一使用 resultUrls 表达。

成功输出：

{
  "status": "success",
  "data": {},
  "meta": {
    "command": "auth status",
    "elapsed_ms": 12,
    "api_origin": "https://animeworkbench-pre.lingjingai.cn"
  }
}

失败输出：

{
  "status": "error",
  "error": {
    "type": "auth_required",
    "message": "缺少 access key",
    "hint": "请设置 LINGJING_AWB_ACCESS_KEY / AWB_ACCESS_KEY，或运行 lj-awb auth login-key。"
  },
  "meta": {
    "command": "account info",
    "elapsed_ms": 1,
    "api_origin": "https://animeworkbench-pre.lingjingai.cn"
  }
}

常见退出码：

| 退出码 | 含义 | | --- | --- | | 0 | 成功 | | 1 | 普通运行失败或平台业务失败 | | 2 | 参数错误或未知命令 | | 3 | 缺少认证或认证失败 | | 10 | 需要用户确认 | | 20 | 任务仍在运行或等待超时 | | 30 | 网络、TLS、HTTP 或外部平台不可用 |

仓库结构

anime-cli/
├── package.json
├── install.mjs
├── packages/
│   ├── awb-core/        # 共享认证、API、服务、命令注册、standalone runtime
│   └── awb-cli/         # lj-awb bin 入口
├── skills/
│   └── lj-awb/    # 随包分发的 Agent skill
├── scripts/             # 版本同步和 skill 元数据校验
└── docs/                # 设计、规划、变更和技术文档

更多实现细节见 docs/TECHNICAL.md。

开发命令

npm run check
npm run smoke
npm run version:sync -- 0.3.5

npm run check 会做 Node 语法检查、shell wrapper 检查和 skill 元数据校验。npm run smoke 会运行帮助命令和无网络写入风险的认证状态检查。

文档索引

docs/TECHNICAL.md：架构、运行时、数据契约、发布维护说明。
docs/01-cli-case-study.md：CLI 框架案例学习。
docs/02-e2b-interface-inventory.md：动漫平台基建接口分类。
docs/03-anime-cli-design.md：产品边界和早期技术设计。
docs/04-implementation-roadmap.md：分阶段开发路线。
docs/05-cli-command-planning-from-api.md：基于 API 清单的命令规划。
docs/06-lingjing-awb-functional-baseline.md：功能基线回归报告。
docs/changes/：重要实现变更记录。