Skills
skills/skill.new.ndhy.com/branch-video-agent-cli

branch-video-agent-cli

SKILL.md

此 skill 用于通过通用 Agent CLI 调用分支互动视频业务能力，而不是手写底层 HTTP 请求。

这是一个面向 Agent 的长期重复执行 skill。默认策略不是每次都临时 npm exec，而是先完成一次全局安装，后续统一直接执行 branch-video-agent。

业务上常见名称包括：

  • 分支互动视频
  • 分支互动课件
  • 游戏化课件
  • 互动视频
  • 互动课件

默认业务站点与播放链接宿主为：https://bv.new.ndhy.com/

适用范围

当用户提出以下需求时优先使用本 skill：

  • 希望把现有 V3 脚本 JSON 创建为项目
  • 希望把现有 V3 脚本更新到已有项目
  • 希望在创建项目后立即发布一个版本
  • 希望返回一个可直接访问的播放链接给用户
  • 希望查看项目列表、项目详情、版本列表或版本详情
  • 希望通过 CLI 触发 AIHub workflow
  • 希望通过 CLI 导入 AIHub workflow 结果到 branch-video 公共库
  • 希望通过 CLI 查看 workflow 状态或 outputs
  • 希望通过 CLI 查询或写入 branch-video 项目
  • 希望通过 CLI 查询托管互动方案目录，或提交新的 preset JSON
  • 希望通过 CLI 查询版本、发布版本、触发生产任务
  • 希望查看生产状态，或重试失败的 production 任务
  • 希望让 Agent 直接消费统一 JSON envelope，而不是拼接 fetch/curl
  • 希望使用 --raw 做链式命令，或先跑 --help 检查 CLI 是否可用
  • 需要排查 AIHUB_AGENT_TOKEN、BRANCH_VIDEO_AGENT_BASE_URL、--wait、--raw、scope 权限等 CLI 使用问题

核心原则

  1. 优先全局安装并直接执行 CLI
  • 首次进入该 skill 时，优先检查 branch-video-agent --help 是否可用
  • 若不可用，默认先执行 npm install -g @mindscraft/branch-video-agent-cli
  • 安装成功后，后续命令统一直接执行 branch-video-agent <group> <action> [flags]
  • 仅当全局安装失败、权限受限、网络受限，或用户明确不希望全局安装时，临时回退到 npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- <group> <action> [-- <flags>...]
  • 仅当当前 workspace 就是 branch-video 仓库且前两种方式都不可用时，才回退到 npm run agent:cli -- <group> <action> [-- <flags>...]
  • 通过 npm exec 或 npm run 回退执行且还要继续传 --wait、--raw、--timeout 等 CLI flags 时，需要在 <action> 后再补一个 --，避免 npm 吞掉这些 flags
  • 只有在用户明确要求绕过 CLI 时，才改为直接调用 HTTP API

  1. 优先使用环境变量注入凭证

    • 优先读取 AIHUB_AGENT_TOKEN
    • 优先读取 BRANCH_VIDEO_AGENT_BASE_URL
    • 不在回复中回显明文 token

  2. 默认使用 stdin JSON 传业务参数

    • CLI 读取一个 JSON object 作为命令 payload
    • 仅把 --wait、--raw、--timeout、--poll-interval、--token-file、--base-url 这类控制项放在 flags

  3. V3 脚本业务优先走 create/update/publish 标准链路

  • 新脚本入库时，优先 project create
  • 已有项目覆盖脚本时，优先 project update
  • 脚本已完整可播时，优先紧接一次 version publish
  • 对“导入脚本后立刻发布”的需求，默认采用 create/update 后马上 publish 的连续执行方式
  1. 托管互动方案优先走 preset 标准链路
  • 查询当前托管方案目录时，优先 preset list
  • 新增或覆盖托管方案时，优先 preset upsert
  • preset upsert 默认通过 stdin 传单条 preset object、对象数组，或 {"items": [...]} 包装对象
  • preset list 服务端是公开读，但 CLI 执行通常仍需要可用的 baseUrl 与 token 配置
  1. AIHub 导入公共库优先走 project import-aihub
  • 当用户手里已经有 global_context_str、script_body_str、result_script_str、workflow_run_id 四段 AIHub 导入 payload 时，优先直接执行 project import-aihub
  • 该命令与其他 CLI 命令一样，统一走 AIHUB_AGENT_TOKEN Bearer 鉴权；服务端兼容旧的 X-AIHub-Import-Token 头，但 CLI 不再单独管理第二套 token

  1. 长任务优先使用 --wait

    • workflow run 需要最终 outputs 时，加 --wait
    • production start 或 production retry 需要最终生产状态时，加 --wait

  2. 链式命令优先使用 --raw

  • 当一个命令的输出要作为下一个命令的输入时，优先 --raw
  • 典型场景是 project create -> version publish -> 拼接播放链接
  • 对 preset list 需要交给其他工具继续处理时，也优先 --raw
  1. 写操作后做一次轻量校验或直接返回结果
  • project create/update/delete 后，按需补一次 project get/list
  • version publish 后，默认至少返回 projectId、version、playUrl
  • preset upsert 后，默认至少返回 id、name、defaultThemeId
  • production start/retry --wait 成功后，通常不需要再额外轮询

推荐工作流

步骤 1：必要时先读参考文档

如果不确定命令、payload 字段或 PowerShell 管道写法，先读取：

  • references/cli-reference.md
  • 已发布 CLI 的 --help 输出

如果当前就在 branch-video 仓库内，需要补充实现细节时，再读取：

  • docs/agent-aihub-api.md
  • tests/cli/workflow.cli.test.ts
  • tests/branchVideo.api.test.ts

步骤 2：确认执行上下文

  • 优先确认 branch-video-agent --help 可用
  • 若不可用，先执行 npm install -g @mindscraft/branch-video-agent-cli，再复检 branch-video-agent --help
  • 若全局安装失败或受限，再回退 npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- --help
  • 仅在当前 workspace 就是 branch-video 仓库且前两种方式都不可用时，才回退 npm run agent:cli -- --help
  • 如无明确指定环境，Agent 可默认按 https://bv.new.ndhy.com/ 解释业务 host 与播放链接 host；CLI 本身不会自动补 baseUrl，执行前仍需通过环境变量、stdin JSON 或 --base-url 显式提供
  • 缺少 baseUrl 或 token 时，先修正环境变量，再执行命令
  • 只有在使用仓库内回退脚本时，工作目录才必须是仓库根目录

步骤 3：优先判断是否属于 V3 脚本业务

对以下高频场景，优先按标准链路执行：

  • 新建项目：project create
  • 导入 AIHub 结果到公共库：project import-aihub
  • 覆盖已有项目脚本：project update
  • 脚本已完整可播：version publish
  • 创建后立即给用户可访问链接：project create 后紧跟 version publish，然后返回播放链接

播放链接优先按以下规则返回：

https://bv.new.ndhy.com/branch-video?projectId=<projectId>&version=<version>

如果需求属于托管互动方案维护，则优先按以下链路执行：

  • 查看托管方案：preset list
  • 新增或覆盖托管方案：preset upsert
  • 仅查看某个 preset：preset list 并传 presetId

步骤 4：构造 stdin JSON

PowerShell 下优先使用 here-string 管道，避免转义噪音：

@'
{
  "workflowType": "AVG立绘对话",
  "inputs": {
    "topic": "牛顿第二定律"
  }
}
'@ | branch-video-agent workflow run --wait

对现有 V3 脚本文件，优先从文件读入，再封装为 create/update payload；具体示例见 references/cli-reference.md。

对 preset 命令，优先直接传完整 preset JSON，例如：

@'
{
  "id": "judge-base",
  "name": "判断题-增强版",
  "defaultThemeId": "cat",
  "urlsByTheme": {
    "cat": "https://aic-view.sdp.101.com/view/judge-base-v2"
  },
  "configTemplate": {
    "waitForPageReady": true
  }
}
'@ | branch-video-agent preset upsert

步骤 5：选择输出模式

  • 默认模式：返回统一 envelope，适合 Agent 解释结果
  • --raw：返回服务端原始 JSON，适合继续管道传递给其他命令或工具

步骤 6：解释结果

默认输出结构：

{
  "ok": true,
  "data": {},
  "error": null,
  "code": null,
  "requestId": "...",
  "meta": {
    "command": "workflow.run",
    "wait": true
  }
}

失败时优先看：

  • code
  • error
  • requestId

对分支互动视频项目类任务，最终回复默认包含：

  • projectId
  • version（如果已发布）
  • playUrl
  • 必要时补充 title

命令选择规则

  • workflow run/status/outputs
    • 面向 AIHub workflow 代理能力
  • project list/get/create/update/delete
    • 面向分支互动视频项目
  • project import-aihub
    • 面向 AIHub workflow 产物导入公共库
  • version list/get/publish
    • 面向版本与发布
  • production schema/start/status/retry
    • 面向生产 schema、生产任务和重试
  • preset list/upsert
    • 面向托管互动方案目录查询与提交

高频默认链路：

  • 现有 V3 脚本创建项目：project create
  • 现有 V3 脚本更新项目：project update
  • 创建或更新后立刻发布：version publish
  • 查看项目当前状态与已发布版本：project get -> version list -> version get
  • 跟踪生产任务：production start --wait，或 production status/retry
  • 发布成功后拼接用户链接：https://bv.new.ndhy.com/branch-video?projectId=<projectId>&version=<version>
  • 查看托管互动方案目录：preset list
  • 新增或覆盖托管互动方案：preset upsert

精确字段、最小 payload 与常见示例放在 references/cli-reference.md。

故障排查规则

VALIDATION_ERROR

  • 先检查 stdin 是否是合法 JSON object
  • 再检查必填字段是否缺失，例如 runId、projectId、version、preset 的 id/defaultThemeId/urlsByTheme/configTemplate
  • 再检查 flags 是否缺值，例如 --timeout、--base-url

UNAUTHORIZED

  • 先检查 AIHUB_AGENT_TOKEN 是否存在且有效
  • 再检查 BRANCH_VIDEO_AGENT_BASE_URL 是否已经显式提供且指向正确环境；若用户未指定环境，Agent 可默认补成 https://bv.new.ndhy.com/

PERMISSION_DENIED

  • 检查 token 是否包含目标 scope
  • 对 branch-video 写命令，检查该 token 是否绑定 ownerUserId
  • 对 preset upsert，检查 token 是否具备 branch-video:write，且 ownerUserId 是否绑定管理员

TIMEOUT

  • 对长任务提高 --timeout
  • 持续轮询成本过高时，可切回非 --wait 模式，分两步执行 start/status

执行要求

  • 使用终端工具执行 CLI，不手写伪输出
  • 对长期重复场景，优先先完成一次全局安装，再统一使用 branch-video-agent ... 直接执行；不要把 npm exec 当作默认执行路径
  • 当用户要求“用 CLI 跑一遍”时，直接执行命令并汇报 JSON 结果要点
  • 当用户要求“帮我写调用方式”时，优先给出基于 branch-video-agent ... 的 PowerShell here-string 示例；只有在无法全局安装时才给 npm exec 回退示例
  • 当通过 npm exec 或 npm run 调 CLI 且 <action> 后还要继续传 flags 时，示例里显式写出第二个 --
  • 当用户要求“从 V3 脚本创建并发布”时，默认尝试 project create 或 project update 后紧接 version publish
  • 当用户要求“维护互动方案 preset”时，默认尝试 preset list 或 preset upsert，不要回退成手写 HTTP 请求
  • 当用户要求“给用户一个访问链接”时，默认返回 https://bv.new.ndhy.com/branch-video?projectId=<projectId>&version=<version>
  • 当用户要求“为什么 CLI 不工作”时，先执行最小只读命令或 --help 检查，再定位凭证、payload 或权限问题
Installs
4
Source
skill.new.ndhy.…gent-cli
First Seen
11 days ago