zenvfx-cli（zenvfx CLI 命令行）

ZenVFX CLI Skill

概述

ZenVFX CLI 是 AI 视频创作平台的命令行工具，通过画布（Canvas）中的节点（Node）+ 连线（Edge）构建 AI 生成任务。

• CLI 入口：zenvfx <command>
• 输出协议：stdout 纯 JSON（{"ok":true,"data":{...}} / {"ok":false,"error":{...}}），解析时用 2>/dev/null 过滤 stderr
• 优先级：系统中若同时存在 zenvfx-mcp，一律优先使用 zenvfx CLI，不要混用两者操作同一画布

认证与安装

# 安装
npm install -g @tencent/zenvfx-cli --registry https://mirrors.tencent.com/npm/

# 认证（自动保存 mcpToken/defaultProject/defaultWorkspace 等配置）
zenvfx auth:login <token>          # 可选 --host <host-url>

auth:login 返回 saved 字段标识各配置是否已自动设置。若 saved.defaultProject 或 saved.defaultWorkspace 为 false，需手动补全：

zenvfx project:list 2>/dev/null              # 查看可用项目
zenvfx project:switch <project-id>           # 一键切换项目（自动更新 workspace）

project:switch 自动解析 workspace 的规则（仅依赖 userId，不依赖 username，因为 username 是用户可自定义的别名）：

1. 精确匹配：/{projectId}/用户空间/ 下目录名以 _{userId} 结尾
2. 模糊匹配：目录名包含 userId
3. 均未命中则清空 defaultWorkspace，需手动设置

也可手动设置：

zenvfx config:set defaultProject <project-id>
zenvfx config:set defaultWorkspace "/<project-id>/用户空间/xxx"

也可通过环境变量：ZENVFX_MCP_TOKEN、ZENVFX_PROJECT

命令速查

配置

文件系统（路径格式：/<projectId>/目录/文件名）

画布管理（标 [S] 的命令需先 canvas:open）

节点操作 [S]

多节点时用 --position "x,y" 避免重叠，建议水平间隔 400px。

连线操作 [S]

查询（不需 Session）

守护进程

重要规则

1. 连线 handle 必须使用 pinName

--source-handle 和 --target-handle 必须用节点定义中的 pinName，不是后端 API 的 field_path。用错会导致连线保存成功但前端不显示。

通过 node:list 或 node:defs 查询正确的 pinName。常用速查：

2. 编辑命令自动保存 — 不要重复 save

canvas:node:add、canvas:node:remove、canvas:node:props、canvas:node:set、canvas:edge:add、canvas:edge:remove 执行成功后自动保存画布，无需额外调用 canvas:save。

3. 画布路径

canvas:create 返回的 canvasPath 不含 .canvas 后缀，canvas 类命令带不带后缀均可。file:stat 等文件命令需要完整文件名（带 .canvas）。

核心流程：生成 AI 视频

# 0. 认证（一次性）
zenvfx auth:login <your-mcp-token>

# 1. 创建画布
CREATE_RESULT=$(zenvfx canvas:create --name "测试画布" 2>/dev/null)
CANVAS_PATH=$(echo $CREATE_RESULT | grep -o '"canvasPath":"[^"]*"' | sed 's/"canvasPath":"//;s/"$//')

# 2. 打开画布
zenvfx canvas:open --canvas "${CANVAS_PATH}.canvas"

# 3. 添加节点
RESULT=$(zenvfx canvas:node:add normal_video_generator --name "文生视频" --position "0,0" --canvas "${CANVAS_PATH}" 2>/dev/null)
NODE_ID=$(echo $RESULT | grep -o '"id":"[^"]*"' | head -1 | sed 's/"id":"//;s/"$//')

# 4. 设置参数（model/clarity 等值须通过 node:model <type> 动态查询，勿硬编码）
zenvfx canvas:node:set --id $NODE_ID --options-json \
  '{"prompt":"傍晚的海边，小孩子嬉戏玩水","model":"kling","clarity":"RESOLUTION_720P","ratio":"16:9","duration":5}' \
  --canvas "${CANVAS_PATH}"

# 5. 运行并等待（推荐 --wait，超时 30 分钟）
zenvfx canvas:run --node $NODE_ID --canvas "${CANVAS_PATH}" --wait --timeout 1800000 2>/dev/null
# 返回: {"status":"completed","outputs":[{"url":"..."}]}

异步模式：不加 --wait 立即返回 taskId，再用 task:status <taskId> --canvas-id <canvasId> 轮询（建议 10 秒间隔，30 分钟超时）。canvasId 通过 file:path-to-id --path "${CANVAS_PATH}.canvas" 获取。

节点信息返回结构

canvas:node:info --id <id> 返回的 options 和 values 数组中，每个条目已 resolve 为：

示例：

{
  "options": [
    {"optionName": "prompt", "value": "一只猫咪", "type": "text"},
    {"optionName": "model", "value": "kling", "type": "string"},
    {"optionName": "ratio", "value": "16:9", "type": "string"}
  ]
}

节点参数

通过 --options-json 统一传参：

常用节点类型：

视频节点建议：模型 kling + RESOLUTION_720P（比 1080P 快 2-3 倍）。

Prompt @占位符

prompt 中可用 @参考图、@首帧图1、@尾帧图1、@参考视频、@参考音频 引用上游输入。通过 canvas:node:prompt 命令自动转换为模型特定格式：

用法：先调用 canvas:node:prompt 获取 resolved 字段，再写入节点。需连线已建立且上游已完成。

异常处理

daemon 异常强制清理：

zenvfx daemon:stop
kill $(cat ~/.config/zenvfx/daemon.pid) 2>/dev/null
rm -f ~/.config/zenvfx/daemon.sock ~/.config/zenvfx/daemon.pid