@lingjingai/lj-awb-cli-pre

v0.4.0

Published

6 days ago

Lingjing AWB CLI monorepo with shared core, standalone CLI, and agent skills (pre-release build pointing to https://animeworkbench-pre.lingjingai.cn)

Downloads

821

0High
0Medium
0Low

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
  -> pretty / text / JSON / YAML / CSV 结果

能力概览

| 能力域 | 命令入口 | 说明 | | --- | --- | --- | | 系统 | doctor / schema | 环境体检、联网校验、机器可读命令 schema | | 认证 | auth | access key 状态、校验、保存、清空 | | 账号 | account | 用户、团队和登录上下文 | | 项目 | project | 项目组查询、切换、创建和更新 | | 积分 | credits | 可扣积分余额、项目组预算、任务用量统计 | | 模型 | model | 生图 / 生视频模型发现、模型参数白名单 | | 上传 | upload | 本地图片 / 视频 / 音频上传为平台可访问素材 | | 创建 | create | 生图、生视频、主体、音色、素材和去字幕提交 | | 任务 | task | 任务列表、等待、任务台账和台账轮询 | | 最终产物 | artifact | Workbench 剧本、资产、视频最终产物 CRUD 与本地 JSON 导入 |

环境要求

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

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

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

lj-awb 只读取 LINGJING_AWB_ACCESS_KEY 作为环境变量 access key。

安装与运行

全局安装：

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

安装包的 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 --access-key <access_key>

从环境变量读取并保存：

LINGJING_AWB_ACCESS_KEY=<access_key> lj-awb auth login

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

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 --brief -f json
lj-awb schema -f json
lj-awb schema --domain create -f json
lj-awb auth status
lj-awb auth verify
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 input-guide
lj-awb model options --model-group-code <modelGroupCode>
lj-awb model create-spec --model-group-code <modelGroupCode>
lj-awb artifact script import --project-id <projectId> --input-file 1_script/output/script.json --dry-run
lj-awb artifact asset import --project-id <projectId> --input-dir 2_asset/output --dry-run
lj-awb artifact video import-storyboard --project-id <projectId> --input-file 3_footage/output/ep001/ep001_storyboard.json --dry-run

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

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

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

Agent 接入建议

Agent 不应该靠记忆猜命令参数。进入任务前先读轻量能力摘要；执行具体命令前再按需读取精确契约：

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

只有做覆盖校验、生成脚本或调试 schema 本身时，才需要读取完整 lj-awb schema -f json。

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

lj-awb doctor --verify

auth status 只检查本地是否配置 access key；auth verify 会联网校验 key 是否远端有效。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 input-guide
lj-awb model options --model-group-code <modelGroupCode>
lj-awb model create-spec --model-group-code <modelGroupCode>

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

示例：参考图生成视频

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

lj-awb create 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 create video \
  --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；是否可传尾帧以 model options.resources[].usage 是否包含 last_frame 为准：

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

输出契约

默认输出是 pretty：面向人类阅读的彩色标题、摘要区、自动换行表格和下一步建议。表格由 cli-table3 做终端渲染，不是 CSV；颜色由 chalk 渲染，设置 NO_COLOR=1 可关闭，FORCE_COLOR=1 或 LINGJING_AWB_COLOR=1 可强制开启。Agent / 脚本不要依赖默认 pretty 解析字段：需要稳定 envelope 时显式追加 -f json 或 --json；需要低 token 的紧凑 key-value 兼容输出时传 -f text；列表导出可用 -f csv，可读结构化输出可用 -f yaml。

schema 通常使用 JSON；model options 和 model create-spec 面向人类时可直接读默认 pretty，Agent 做参数决策时建议使用 -f text，脚本严格解析或需要完整嵌套结构时再切 -f json。

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

成功输出：

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

失败输出：

{
  "status": "error",
  "error": {
    "type": "auth_required",
    "message": "缺少 access key",
    "hint": "请设置 LINGJING_AWB_ACCESS_KEY，或运行 lj-awb auth login。"
  },
  "meta": {
    "command": "account info",
    "elapsed_ms": 1,
    "api_origin": "https://animeworkbench.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:local
npm run check
npm run smoke
npm run version:sync -- 0.3.5

npm run check:local 会做 Node 语法检查、shell wrapper 检查、skill 元数据和 schema 校验，不需要 access key。npm run check 会额外执行真实平台契约校验，需要本地或环境变量中有可用 access key。npm run build:pre / npm run build:prod 发布构建只自动执行 check:local，避免被本机过期平台凭据阻断；需要真实平台回归时单独运行 npm run check:real。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/：重要实现变更记录。