Skip to Content
外部 Agent 接入

外部 Agent 接入

Codex 和其他外部 Agent 通过 ai-short-studio CLI 操作项目、画布、任务和素材。安装 CLI 后，再加载 using-vvicat-ai-short-studio-cli Skill，让 Agent 按其中的命令和制作规则执行。

Agent 需要终端和文件读取权限，才能执行 CLI 并读取 Skill 目录里的 SKILL.md 和参考文件。如果你打算直接在平台里创作，可以使用画布 Agent，无需在本机安装。

视频资产列表会按当前选版的正式镜号区分同名素材；缺少镜号证据时显示稳定标识。点击视频可播放预览，右侧“＋”单独加入画布；预览不会切换选版或重新生成视频。

聊天中附带照片后，可以直接要求画布助手“将这张照片加入画布并用作参考”。助手会把照片保存为当前分集的图片资产和节点，再引用实际版本继续制作。只讨论照片时不会自动导入。

打开画布制作助手时，连接准备与界面资源加载会同时进行。首次打开仍需等待资源下载和当前会话历史就绪；之后浏览器会复用带版本标识的静态资源。离开当前画布或切换会话会取消当前启动流程。

1. 安装 CLI

需要 Node.js 22 或更高版本。在 Agent 使用的终端环境中运行：

npm install --global @aswless_854771076/ai_short_studio_cli@latest
ai-short-studio --version

安装脚本默认尝试将随包 Skill 放入 ~/.codex/skills。如果日志提示跳过 Skill 安装，按第 3 步检查；这不一定表示 CLI 安装失败。

CLI 随包提供的主 Skill 是 using-vvicat-ai-short-studio-cli。short-drama 和 humanizer 若已在 Agent 中另行安装，可以用于剧本创作和文字润色；不要把它们当成 CLI 必然附带的 Skill，也不要直接套用未出现在本机 --help 中的 --skill 选项。

2. 登录服务

首次登录时同时指定服务地址和 profile：

ai-short-studio auth login \
  --profile vvicat \
  --base-url https://ai-short-studio.vvicat.dev \
  --json

CLI 默认打开浏览器完成 MemHub 授权，并将长期凭据保存到系统钥匙串。这是 CLI 的登录流程，不需要 Agent 查询 MemHub 知识库。

登录会保存服务地址，后续命令沿用 --profile vvicat。连接其他服务时使用独立 profile，避免混用认证。同一台机器上的交互式终端能登录，不代表容器、远程主机或其他系统用户也能读取这份登录状态；请在 Agent 实际执行命令的环境中检查。

3. 让 Agent 加载 Skill

Codex

检查安装状态，缺失时安装：

ai-short-studio skill status --target codex --json
ai-short-studio skill install --target codex --json

默认路径为 ~/.codex/skills/using-vvicat-ai-short-studio-cli/SKILL.md。如果 Codex 已打开，安装后新建任务，让它重新发现 Skill。

其他支持 Skill 的 Agent

CLI 提供 agents 安装目标，默认写入 ~/.agents/skills：

ai-short-studio skill install --target agents --json
ai-short-studio skill status --target agents --json
export VVICAT_SKILLS_ROOT="$HOME/.agents/skills"

--target agents 只决定文件安装位置，不会自动替每个 Agent 配置 Skill 发现规则。请在所用 Agent 中确认它会读取该目录。

如果 Agent 使用其他目录，将 --root 换成它实际读取的 Skills 父目录。例如下面使用一个自定义目录：

ai-short-studio skill install --root "$HOME/my-agent-skills" --json
ai-short-studio skill status --root "$HOME/my-agent-skills" --json
ai-short-studio skill path --root "$HOME/my-agent-skills" --json

skill path --json 的 skills[].path 是安装目录，顶层 path 是 CLI 随包源目录。为 Agent 配置加载路径时，使用安装目录中的 SKILL.md。

在 Agent 的设置或任务说明中填入 $HOME/my-agent-skills/using-vvicat-ai-short-studio-cli/SKILL.md，并允许它按需读取同目录下的参考文件。--root 是父目录；旧参数 --directory 指主 Skill 的精确目录，两者不能同时使用。

自定义目录还需要让 CLI 的 preflight 检查同一份 Skill。在启动 Agent 的环境中设置：

export VVICAT_SKILLS_ROOT="$HOME/my-agent-skills"

上面的 agents 示例已将这个变量设为 "$HOME/.agents/skills"，让 preflight 与 Agent 检查同一个目录。未指定目录时，preflight 会先检查 Codex 目录，再检查 agents 目录，找到已安装的主 Skill 就使用它。

能运行命令，但不会自动发现 Skill 的 Agent

先按上面的自定义目录方式安装，再明确要求 Agent 阅读 SKILL.md，按其中的索引加载所需参考文件，并通过 CLI 执行操作。它还需要终端和文件读取权限；仅复制 Skill 名称到对话里不会建立连接。这条接入路径使用 CLI，不需要给 Agent 填写 MCP 服务地址。

4. 检查版本与创作配置

在 Agent 的执行环境中运行：

ai-short-studio preflight --profile vvicat --json

检查以下字段：

  • version.restartRequired：若为 true，CLI 刚完成更新，需要重新运行 preflight。
  • skill.skillReady：应为 true，并核对 skill.target 是 Agent 实际加载的目录。
  • ready 和 missing：ready: true 表示模型配置检查通过；若有缺项，先在平台补齐供应商和默认模型。

Skill 状态中的 current: true 只表示内容与本机安装包一致。检查 CLI 是否需要更新仍要看 preflight 的版本结果。preflight 默认允许自动更新 CLI；只检查时可以加 --no-update。

CLI 更新后检查 Skill：

ai-short-studio skill status --target codex --json
ai-short-studio skill update --target codex --json

其他 Agent 将 --target codex 换成 --target agents，或沿用安装时的 --root。如果 Skill 已被手工修改，更新会跳过它；先用相同目录参数运行 skill diff，核对后再合并。skill install --force 会覆盖本地修改，只在确认要替换时使用。

API Key 应配置在平台账号设置或安全输入中。不要将密钥粘贴到 Agent 对话、命令参数或仓库文件。

5. 开始创作

在 Codex 中发送日语校园恋爱喜剧的制作需求，Agent 读取 Skill 并检查制作配置
Codex 对话示例（用户提供）。先说明时长、角色、语言、模型和画幅，Agent 再检查制作条件。版本、耗时和模型能力以当前检查结果为准。

在 Codex 或已完成接入的 Agent 中发送：

使用 using-vvicat-ai-short-studio-cli，通过 --profile vvicat 操作 PixelShort。
我要制作[内容主题]，用于[发布平台]，画幅为[9:16 / 16:9]，时长约[秒数]，风格是[风格描述]。
请先读取 Skill，检查登录、版本和项目配置，汇总尚未确定的选择。
先完成剧本、分镜和制作计划，等我确认生成范围后再提交媒体任务。

也可以提供剧本、参考图或已有项目。说明要新建还是继续项目，以及本次希望停在哪个阶段。Agent 会沿用你已确认的配置和授权，有关键选择未确定时再询问。

素材生成可能产生供应商模型费用。确认制作范围后，Agent 通过 CLI 提交任务、核对结果，并交你确认素材和分镜，再继续后续制作。任务完成只表示生成结束，画面、对白和声音仍需审核。

常见问题

Agent 找不到 Skill

用安装时相同的 --target 或 --root 运行 skill status 和 skill path，核对 Agent 的读取目录。安装或更新后重新加载 Skill，必要时新建任务。其他 Agent 不一定会自动扫描 ~/.codex/skills。

preflight 显示未登录

确认登录和 preflight 使用同一 profile、同一服务地址，并在相同系统用户和执行环境中运行。远程 Agent 需要自己的登录环境。

ready 为 true，但 Skill 仍未就绪

分别处理模型配置和 Skill 状态。检查 skill.skillReady、skill.state 和 skill.target，修复缺失、旧版或目录不一致后再开始创作。

内置助手如何制作字幕和配乐

首次制作会询问是否需要背景音乐，已确认的选择写入声音计划，续跑时沿用。需要时调用 Suno 生成纯音乐，再接入混音；无需配乐时不生成 BGM。

字幕先调用 ASR 识别实际视频音轨，再使用上游返回的原文和分段时间。翻译字幕沿用原声时间，绑定转写版本和段号；每次渲染输出一个目标语言的 SRT，并可同时烧录进成片。换视频或转写版本后需要更新剪辑计划。单镜整轨转写上限为 180 秒，不会静默截断。ASR 不能替代完整听音、口型和音色审核，目标模式在最终成片统一验收。

画布 Agent 使用