@kanesong/wj

v0.4.0

Published

2 months ago

WenJing Agent-Native CLI — 文镜内容生成与影视画布编辑命令行工具

0High
0Medium
0Low

kanesong

wenjing cli ai agent mcp

wj — WenJing CLI

文镜平台内容生成与受控管理 API 命令行工具，面向 Codex、Claude Code、Cursor、OpenClaw 等 AI Agent 使用。

公共包提供视频、图片、图片编辑、音频、文本生成、影视画布读写与视频上传，以及 Portal/CRM 独立登录、任务查询、raw API、参数 schema 和 skills 安装。CRM 业务仍通过 raw API 调用，不重新暴露组织、支付、素材或部署等高风险封装命令。

安装

npm install -g @kanesong/wj
# 或临时使用
npx @kanesong/wj --version

快速开始

# Portal 登录、身份与余额
wj login --username 13800138000
wj whoami

# CRM 使用独立凭据
wj login --service crm --username admin
wj whoami --service crm

# 检查影视画布 CLI，并列出可见项目
wj --json canvas.doctor
wj canvas.projects --limit 20

# 生成图片
wj image.create --model gpt-image-2 --prompt "一只穿着宇航服的猫在月球上" --ratio 9:16 --resolution 2K --wait

# 生成视频并等待完成
wj video.create --model kling-omni --prompt "一只猫咪在草地上奔跑" --wait

# 独立视频超清（客户端 Token；由 DWP 超分优先队列执行）
wj video.upscale --video-url https://qkk-wenjing.oss-cn-beijing.aliyuncs.com/video/USER_ID/source.mp4 --target-resolution 1080P --wait --max-wait 6h

# Grok 4.5 文本推理（同步 / 流式）
wj text.request --model grok-4.5 --content "写一段产品介绍"
wj text.stream --model grok-4.5-stream --content "写一段产品介绍"

# 查看命令参数
wj schema image.create --model gpt-image-2
wj schema api
wj schema

命令体系

| 类型 | 示例 | 适合 | |---|---|---| | 快捷命令 | wj generate video --model kling-omni | 人类 + AI Agent | | 资源命令 | wj video.create --model kling-omni | 稳定业务能力 | | 画布命令 | wj canvas.node.update --project ... --node ... | Agent 安全编辑影视画布 | | Raw API | wj api --service crm GET /api/crm/platform-routing/list | 尚未封装的 Portal/CRM API | | 参数说明 | wj schema image.create --model gpt-image-2 | 查询可用参数 |

可用能力

| 能力 | 主要命令 | |---|---| | 视频生成与超清 | video.create, video.upscale, video.query, generate video | | 图片生成 | image.create, image.query, generate image | | 图片编辑 | image.edit | | 音频生成 | audio.create, audio.query, audio.voices, audio.voice-clone | | 文本推理 | text.request, text.stream, text.conversation | | 影视画布 | canvas.graph, canvas.node.*, canvas.edge.*, canvas.lock.*, canvas.video.* | | 账户 | login, logout, whoami，支持 portal|crm | | 工具 | api, schema, skills add |

公共包不包含组织、支付、素材授权商城或部署命令。CRM 的写操作会直接影响生产数据，使用 raw API 时必须先确认目标、方法和请求体。

当前接口契约

CLI 0.4.0 已按 Portal 当前接口同步（普通模型使用 Portal Web 路由；Moring/独立超清等专属能力使用 Client 路由），包含：

视频：Seedance 2.x、Seedance 1.5、Seedance 1.0、Seedance 1.0 Pro Fast、HappyHorse，以及独立视频超清。
图片：Seedream 4.5、5.0、5.0 Lite、5.0 Pro，以及 Moring Image、GPT Image 2 和图片编辑。
文本：稳定 chat/chat/stream、GPT-5.6 Terra/Luna、DeepSeek V4 Pro/Flash、Qwen3.8 Max、稳定视觉入口。

使用 wj schema <command> [--model <model>] 查看与当前接口对应的请求字段和端点。wj --version 应显示 0.4.0。

Raw API

# Portal（默认）
wj api GET /health
wj api POST /api/ai123/3d/create '{"imageUrl":"https://example.com/a.png"}'

# CRM
wj api --service crm GET /api/crm/platform-routing/list

# 从 UTF-8 JSON 文件或标准输入读取 body
wj api POST /api/example @body.json
Get-Content body.json | wj api POST /api/example @-

# 为慢接口设置 180 秒超时
wj api --timeout 180000 POST /api/example @body.json

支持 GET / POST / PUT / PATCH / DELETE。Portal 与 CRM token 分开存储和发送，不会跨服务复用。

影视画布 CLI

wj canvas.* 直接编辑文镜现有影视画布数据，不建立第二套工程格式。支持 14 种现有节点、节点合并补丁、画布连线、组织编辑锁、乐观版本保护，以及本地视频 multipart 上传和镜头版本绑定。

先查看命令参数，不要猜字段：

wj schema canvas.node.update
wj schema canvas.edge.create
wj schema canvas.video.upload

安全写入流程

# 1. 检查本机、登录和 Portal 连通性
wj --json canvas.doctor

# 2. 把 URL、项目 ID 或唯一项目名解析为稳定 ID
$resolved = wj canvas.project.resolve "项目名" | ConvertFrom-Json
$projectId = $resolved.data.id

# 3. 读取当前草稿版本
$graph = wj canvas.graph --project $projectId | ConvertFrom-Json
$version = $graph.data.summary.draftVersionNo

# 4. 先预演，预演不会获取编辑锁或写入
wj canvas.node.update --project $projectId --node shot_01 `
  --patch '{"data":{"name":"新的镜头名称"}}' `
  --expected-version $version --dry-run

# 5. 已有组织项目先获取本人编辑锁，再带锁和版本执行一次写入
$lock = wj canvas.lock.acquire --project $projectId | ConvertFrom-Json
wj canvas.node.update --project $projectId --node shot_01 `
  --patch '{"data":{"name":"新的镜头名称"}}' `
  --expected-version $version --lock-id $lock.data.id
wj canvas.lock.release --project $projectId --lock-id $lock.data.id

每次真实保存后重新读取 draftVersionNo。版本冲突时停止并重新审阅差异，不要用旧版本自动重试。CLI 会续租并核对编辑锁的 editorUserId；它不会借用其他用户的锁。

节点与连线

支持的节点类型：character、scene、prop、effect、shot、audio、emotion、keyframe、extend、ref-video、ref-audio、ref-image、story-selector、story-variable。

# 创建剧情选择器；--data/--node/--patch 支持 JSON、@file.json 和 @- 标准输入
wj canvas.node.create --project $projectId --type story-selector `
  --name "选择后续剧情" --x 640 --y 240 --dry-run

# 镜头 -> 选择器会推断现有画布 handle
wj canvas.edge.create --project $projectId `
  --source shot_01 --target selector_01 --dry-run

# 选择器 -> 后续镜头必须指定选择器 outputs 中的稳定出口 ID
wj canvas.edge.create --project $projectId `
  --source selector_01 --target shot_02 --output-id option_a --dry-run

实时删除节点或连线时，--confirm 必须与目标 ID 完全一致。剧情变量从节点下方连接点连到选择器变量输入，CLI 会沿用 Web 画布已有的 story-variable-out -> story-variable-in handle。

视频上传与绑定

上传和改画布是两个独立动作。upload --dry-run 只检查文件并计算 SHA-256，不访问网络；真实上传支持 MP4、WebM、MOV。

wj canvas.video.upload --file C:\media\shot-01.mp4 --dry-run
$upload = wj canvas.video.upload --file C:\media\shot-01.mp4 --concurrency 3 | ConvertFrom-Json
$graph = wj canvas.graph --project $projectId | ConvertFrom-Json
$version = $graph.data.summary.draftVersionNo
$lock = wj canvas.lock.acquire --project $projectId | ConvertFrom-Json

wj canvas.video.bind --project $projectId --node shot_01 `
  --url $upload.data.url --version-id cli-v1 --pin `
  --expected-version $version --lock-id $lock.data.id
wj canvas.lock.release --project $projectId --lock-id $lock.data.id

上传链路为 init -> presign -> PUT parts -> complete。预签名 PUT 不携带 Portal Authorization；分片连续失败三次后 CLI 调用 abort。绑定只接受稳定 HTTPS URL（本机回环测试除外），拒绝带查询签名或片段的临时 URL，单个镜头最多保留 5 个视频版本。

JSON 合同与退出码

画布命令成功时输出：

{"ok":true,"command":"canvas.graph","data":{}}

失败写入 stderr：

{"ok":false,"command":"canvas.graph","error":{"code":"NOT_FOUND","message":"..."}}

| 退出码 | 类型 | |---:|---| | 2 | 输入或 JSON 非法 | | 3 | 缺少认证或无法核对用户身份 | | 4 | 项目/节点不存在，或名称匹配不唯一 | | 5 | 版本冲突、锁冲突或非法连线 | | 6 | Portal API 或网络错误 | | 7 | 视频上传失败 |

完整的脱敏端点、保存和上传合同见 docs/canvas-api-contract.md。

模型与参数

使用 wj schema 查看完整命令列表：

wj schema video.create --model kling-omni
wj schema image.create --model gpt-image-2
wj schema image.edit --model inpainting
wj schema audio.create --model minimax-tts
wj schema text.request --model grok-4.5

独立视频超清

video.upscale 调用 Client 接口创建异步任务，输入必须是文镜主 OSS 当前用户目录下的 HTTPS MP4 URL（/video/<userId>/*.mp4，不含查询串或片段）；可用 wj whoami 获取当前用户 ID。目标分辨率支持 720P、1080P、1440P、4K。省略 --idempotency-key 时，CLI 会在第一次 POST 前按规范化请求生成并持久化稳定 key；创建结果不明确时不要换 key 自动重发。

# 创建后立即返回任务 ID
wj video.upscale \
  --video-url https://qkk-wenjing.oss-cn-beijing.aliyuncs.com/video/USER_ID/source-480p.mp4 \
  --target-resolution 1080P \
  --idempotency-key project-a-revision-0001

# 复用统一视频查询命令
wj video.query --id video_xxx --model video-super-resolution --poll --max-wait 6h

创建端点为 POST /api/video/client/super-resolution/create，查询端点为 GET /api/video/client/super-resolution/query/{id}。PENDING 表示任务正在 DWP 超分队列等待，不是失败；IDLE 只表示优先级低于现有交互式图片/视频超分，整个超分队列仍优先于动态壁纸 Topaz。前台 --max-wait 超时不会取消服务端任务。支持 480P 升至 720P/1080P/1440P/4K，以及 720P 升至 1080P/1440P/4K；服务端按探测到的视频时长向上取整，以每秒 0.5 摹映币计费。

安装 AI Agent Skills

wj skills add
wj skills add --global
wj skills add --all --yes

支持 Codex、Claude Code、Cursor 和 OpenClaw。随包 skills 包含 wj-shared、wj-canvas、wj-video、wj-image、wj-image-edit、wj-audio、wj-text。

环境变量

| 变量 | 说明 | 默认值 | |---|---|---| | WJ_PORTAL_URL | Portal 内容生成服务地址 | https://api.wenjing.art | | WJ_CRM_URL | CRM 服务地址 | https://crm.wenjing.art | | WJ_USERNAME / WJ_PASSWORD | Portal 默认账号/密码 | — | | WJ_CRM_USERNAME / WJ_CRM_PASSWORD | CRM 默认账号/密码 | — | | WJ_CREDENTIAL_BACKEND=file | CI/测试时禁用 OS keychain，使用本机加密文件 | — | | WJ_PORTAL_TOKEN | 非交互进程临时注入 Portal 用户 Token；优先于 OS keychain，不落盘 | — | | WJ_PORTAL_USER_ID | 使用 WJ_PORTAL_TOKEN 时提供用户 ID，用于核对编辑锁归属 | — | | WJ_PORTAL_CLIENT_TOKEN | 非交互服务进程调用 /client/ 接口，无需执行 wj login；仅从父进程临时注入，不写入磁盘 | — |

本地开发时显式覆盖地址：

WJ_PORTAL_URL=http://localhost:8088 WJ_CRM_URL=http://localhost:8080 wj api --service crm GET /health

安全说明

Portal 与 CRM JWT 分别存储在 OS keychain，CLI 不提供导出 token 的命令。
客户端 /client/ 路由继续使用独立 client token。
画布真实写入应先 --dry-run；已有组织项目必须带当前草稿版本和本人编辑锁。
错误输出会清除 Authorization/Cookie 等敏感头。
所有命令默认输出 JSON，调用记录写入 ~/.wenjing/audit.log。
生产生成会真实扣费；CRM raw API 可能修改生产数据。

开发

cd wenjing-cli
npm install
npm test
npm run build
npm pack --dry-run