@lingjingai/lj-video-cli-pre

v0.2.2

Published

19 hours ago

Lingjing Video Task Run CLI — 视频任务调度、状态协调和记录管理 (pre-release build pointing to https://animeworkbench-pre.lingjingai.cn)

0High
0Medium
0Low

video task agent cli lingjing

lj-video

lj-video 是灵境动漫平台的视频产物管理命令行工具。它把平台视频最终产物（集 / 场 / clip）CRUD 和视频任务执行记录管理封装成稳定、可脚本化、Agent 友好的命令，并随包分发一套 lj-video skill，方便 Codex、Claude 等 Agent 把自然语言任务编排成确定性的 CLI 调用。

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

能力概览

| 能力域 | 命令入口 | 说明 | | --- | --- | --- | | 系统 | doctor / schema | 环境体检、联网校验、机器可读命令 schema | | 认证 | auth | access key 状态、校验、保存、清空 | | 视频产物 | output | 项目级产物查询，集 / 场 / clip 的增删改查 | | 项目素材 | project-asset | 查询项目素材，如本地图片 local_image | | 任务记录 | task-run | 任务调度、状态协调、等待终态、记录管理 |

视频产物三级层级

Project
  └─ Episode（集）
       └─ Scene（场）
            └─ Clip（镜头 / 片段）

环境要求

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

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

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

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

认证与 lj-awb CLI 共享 ~/.lingjingai/awb/auth.json，已登录过 lj-awb 则无需重复认证。

安装

全局安装：

npm install -g @lingjingai/lj-video-cli
lj-video --help

安装包的 postinstall 会自动把随包分发的 lj-video skill 安装到：

~/.cc-switch/skills/lj-video
~/.codex/skills/lj-video
~/.claude/skills/lj-video

可用 LINGJING_VIDEO_SKILL_INSTALL_DIR 指定单一安装目录；用 LINGJING_VIDEO_SKIP_SKILL_INSTALL=1 跳过 skill 安装。

源码运行：

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

认证

# 保存 access key
lj-video auth login --access-key <key>

# 从环境变量保存
LINGJING_AWB_ACCESS_KEY=<key> lj-video auth login

# 查看本地状态（不联网）
lj-video auth status

# 联网校验 access key 是否有效
lj-video auth verify

# 环境体检
lj-video doctor --verify

# 清空本地认证
lj-video auth clear --dry-run
lj-video auth clear --yes

常用命令

视频产物查询

# 一次性拉取项目完整产物
lj-video output get --project-group-no PG_001

# 逐层查询
lj-video output episode list --project-group-no PG_001
lj-video output episode get --project-group-no PG_001 --episode-id ep_001
lj-video output scene list --project-group-no PG_001 --episode-id ep_001
lj-video output clip list --project-group-no PG_001 --episode-id ep_001 --scene-id scn_001
lj-video output clip get --project-group-no PG_001 --episode-id ep_001 --scene-id scn_001 --clip-id clip_001

视频产物写入

所有写入命令支持 --dry-run 预览和 --yes 确认两步走：

# 新增或更新集
lj-video output episode upsert \
  --project-group-no PG_001 \
  --body-json '{"episodeId":"ep_001","title":"第一集"}' \
  --dry-run

# 批量写入集
lj-video output episode batch \
  --project-group-no PG_001 \
  --body-json '[{"episodeId":"ep_001"},{"episodeId":"ep_002"}]' \
  --yes

# 更新 clip 视频链接（视频生成后回写）
lj-video output clip update-video-urls \
  --project-group-no PG_001 --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 \
  --body-json '{"videoUrls":["https://example.com/v.mp4"]}' \
  --yes

# 逻辑删除集（级联删除其下所有 scene/clip）
lj-video output episode delete --project-group-no PG_001 --episode-id ep_001 --yes

项目素材查询

# 查询本地图片素材（assetType 默认 local_image）
lj-video project-asset list --project-group-no PG_001

# 显式指定素材类型
lj-video project-asset list --project-group-no PG_001 --asset-type local_image

任务执行记录

# 查询任务记录
lj-video task-run list --project-group-no PG_001
lj-video task-run list --project-group-no PG_001 --task-type video
lj-video task-run get --project-group-no PG_001 --id 1001

# 调度任务（预览 → 确认）
lj-video task-run dispatch \
  --project-group-no PG_001 \
  --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 \
  --complete-prompt "真人影视风，主角推门而入" \
  --expected-duration 6s \
  --dry-run

lj-video task-run dispatch \
  --project-group-no PG_001 \
  --episode-id ep_001 --scene-id scn_001 --clip-id clip_001 \
  --complete-prompt "真人影视风，主角推门而入" \
  --expected-duration 6s \
  --yes

# 协调任务状态
lj-video task-run reconcile --project-group-no PG_001 --id 1001

# 等待任务完成
lj-video task-run reconcile-wait --project-group-no PG_001 --id 1001 --wait-seconds 120

JSON 输出契约

默认输出是 compact text，适合终端和 Agent 低 token 读取。追加 -f json 获取结构化 JSON envelope。

成功输出：

{
  "status": "success",
  "data": {},
  "meta": {
    "command": "output episode list",
    "elapsed_ms": 120,
    "api_origin": "https://animeworkbench.lingjingai.cn"
  }
}

失败输出：

{
  "status": "error",
  "error": {
    "type": "auth_required",
    "message": "缺少 access key",
    "hint": "请设置 LINGJING_AWB_ACCESS_KEY，或运行 lj-video auth login。"
  },
  "meta": { ... }
}

常见退出码：

| 退出码 | 含义 | | --- | --- | | 0 | 成功 | | 1 | 普通运行失败或平台业务失败 | | 2 | 参数错误或未知命令 | | 3 | 缺少认证或认证失败 | | 10 | 需要用户确认（追加 --yes 重跑） | | 30 | 网络、TLS、HTTP 或平台不可用 |

Agent 接入建议

Agent 进入任务前推荐先读取机器可读契约：

lj-video schema -f json
lj-video doctor --verify

schema 返回每个命令的参数定义和安全约束，Agent 应使用这些 key 生成 CLI 参数，而不是从记忆里拼：

requiredOptions：必须提供的参数。
safety.safeToAutoRun：是否允许 Agent 静默执行。
safety.requiresConfirmation：是否必须用户确认后追加 --yes。
safety.supportsDryRun：正式执行前是否可以先 --dry-run。

仓库结构

anime-video-cli/
├── package.json
├── install.mjs              # postinstall：安装 skill 到 Agent 目录
├── packages/
│   ├── video-core/          # 共享认证、API、服务、命令注册、standalone runtime
│   └── video-cli/           # lj-video bin 入口
├── skills/
│   └── lj-video/            # 随包分发的 Agent skill
├── build/                   # 构建和发布脚本
└── scripts/                 # 版本同步

开发命令

npm run check          # Node 语法检查 + shell wrapper 检查
npm run smoke          # 运行 --help、auth status、schema 基础验证
npm run version:sync -- 0.2.0   # 统一同步全部 package.json + skill 版本

发布

版本同步

发布前先同步版本号，会更新所有 package.json、skills/lj-video/VERSION、SKILL.md 和 compat.json：

npm run version:sync -- <semver>

本地预发布（指向 pre 环境 API）

打包并全局安装到本地，API 指向 https://animeworkbench-pre.lingjingai.cn：

npm run build:pre              # 全局安装
npm run build:pre -- --dry-run # 仅验证，不安装

预发布到 npm（包名 `@lingjingai/lj-video-cli-pre`）

以独立包名发布到 npm，API 指向 pre 环境，不影响生产包：

npm run build:pre-publish              # 正式发布
npm run build:pre-publish -- --dry-run # 仅预览

生产发布到 npm（包名 `@lingjingai/lj-video-cli`）

发布前会校验源码中 DEFAULT_API_ORIGIN 必须是生产地址，否则拒绝发布：

npm run build:prod              # 正式发布
npm run build:prod -- --dry-run # 仅预览

发布环境对比

| 目标 | 命令 | npm 包名 | API 地址 | | --- | --- | --- | --- | | 本地 pre | build:pre | — (全局安装) | https://animeworkbench-pre.lingjingai.cn | | npm pre | build:pre-publish | @lingjingai/lj-video-cli-pre | https://animeworkbench-pre.lingjingai.cn | | npm prod | build:prod | @lingjingai/lj-video-cli | https://animeworkbench.lingjingai.cn |

环境变量

| 变量 | 作用 | | --- | --- | | NPM_CONFIG_REGISTRY | npm registry 地址 | | NPM_PUBLISH_DRY_RUN=1 | 发布时 dry-run | | NPM_INSTALL_DRY_RUN=1 | 本地安装时 dry-run | | NPM_INSTALL_FORCE=1 | 强制安装 | | SKIP_CHECK=1 | 跳过发布前检查 | | LINGJING_VIDEO_SKILL_INSTALL_DIR | skill 安装目录 | | LINGJING_VIDEO_SKIP_SKILL_INSTALL=1 | 跳过 skill 安装 |

完整发布流程示例

# 1. 同步版本
npm run version:sync -- 0.2.0

# 2. 检查
npm run check
npm run smoke

# 3. 先发预发布验证
npm run build:pre-publish -- --dry-run
npm run build:pre-publish

# 4. 验证通过后发生产
npm run build:prod -- --dry-run
npm run build:prod