Agent 分镜台 · Agent Storyboard

让 Codex、Claude Code 帮你把视频从想法做到分镜、素材和配音。
一个本地优先的分镜工作台：Agent 负责写和生成，你在一张表里检查、调整、验收。

快速开始 · 工作方式 · 功能 · 环境 · MCP 工具 · 开发 · 社区方案

--- ## 为什么做它做一条短视频，脚本在文档里，分镜在表格里，图片在生图网页里，配音在另一个工具里，素材散落在文件夹里。每换一个窗口，上下文就丢一次。 Agent 分镜台把这些收进同一张**本地分镜表**： - **Agent 直接写入**：一句话让 Agent 建好完整项目，不需要控制浏览器。 - **结果自动回填**：Agent 生成的图片、视频和配音，落进对应镜头，不用手动对文件名。 - **你只做验收**：所有自动化结果都在表格里，能一眼看到、直接改。 - **数据都在本机**：项目、脚本和素材保存在你的电脑上。

_{Agent 生成素材，结果自动回填到对应镜头}

## 🚀 快速开始需要 Node.js 18 或更高版本，以及 Codex 或 Claude Code 之一。 **1. 安装插件**

**Codex** ```bash codex plugin marketplace add Yuuhann1999/agent-storyboard codex plugin add agent-storyboard@agent-storyboard ```

**Claude Code** ```bash claude plugin marketplace add Yuuhann1999/agent-storyboard claude plugin install agent-storyboard@agent-storyboard ```

安装后新开一个对话，让 MCP 工具重新加载（Claude Code 里可以用 `/mcp` 确认 `agent-storyboard` 已连接）。 **2. 打开分镜台** ```text 打开 Agent 分镜台。 ``` 插件会自动启动内置的本地工作台，并给出链接（默认 `http://127.0.0.1:43218`），在侧边栏或浏览器里打开即可。 **3. 创建第一个项目** ```text 创建一个 9:16 的短视频分镜项目，主题是“独居第三年，我把 20㎡出租屋改成了工作室”，风格干净、节奏快，适合抖音。写好台词和画面描述。 ``` **4. 生成素材** 在分镜台里点镜头的「生成素材」，或点顶栏的「批量生成」，然后对 Agent 说： ```text 处理 Agent 分镜台里所有待生成素材。 ``` ## 🧭 它是怎么工作的 ```mermaid flowchart LR A["你：视频主题和要求"] --> B["Agent 通过 MCP
写入完整分镜项目"] B --> C["你在分镜表里
检查、调整"] C --> D["加入生成队列
单镜头 / 批量"] D --> E["Agent 生成
图片 · 动效视频 · 配音"] E --> F["素材自动回填
到对应镜头"] F --> C ``` 分镜台是一个本地网页服务，Agent 通过 MCP 工具和它对话。三种生成方式按镜头选择： | 生成方式 | 做什么 | 由谁完成 | | --- | --- | --- | | **AI 生图** | 按画面描述生成图片 | Codex 用自带的 image_gen；Claude Code 通过 `generate_storyboard_image` 调用本机 Codex 出图 | | **HyperFrames / Remotion 动效** | 用代码渲染字幕、信息图、转场等视频 | Agent 在本地渲染（需要对应插件和渲染工具链） | | **手动素材** | 自己拍的、自己剪的 | 你上传图片或视频 | ## ✨ 功能一览 ### 一张表看完整个分镜镜头类型、媒体、时长、台词、画面描述、生成方式、素材预览和备注都在同一行。长项目切到「紧凑」，一屏看更多镜头；节奏有问题的镜头会直接标出提示。

_详细视图

_{紧凑视图，一屏 7 个镜头}

- 拖拽或 `Alt + ↑/↓` 调整顺序，复制镜头、在下方插入，误删可以撤销。 - 素材文件名带镜头序号，调整顺序后会自动同步，不会互相覆盖。 - 按台词、画面、备注搜索；顶栏实时显示「生成中 / 排队 / 失败」数量，点一下定位。 ### 口播配音，和台词对齐在脚本页生成配音，可以描述声音风格，也可以上传参考音频克隆音色。生成后用本地 Whisper 识别，把配音对齐到每个镜头的台词，再一键应用镜头时长。

### 素材总览与封面工作台只列做出来的素材，一眼看到进度。封面按竖屏 9:16 和横屏 16:9 分别管理，支持模板、参考图和提示词。

_素材总览

_{封面工作台}

### 风格库与 DESIGN.md 12 种内置视觉风格，选中后写入项目的 `DESIGN.md`。之后所有图片和视频素材都会遵循这份视觉规范，单个镜头的明确要求优先。

### 深色模式，也适合窄窗口跟随你的习惯切换主题。放进 Agent 的侧边栏这类窄窗口时，分镜表会自动变成卡片布局。

### 更多 | | | | --- | --- | | 多项目管理 | 新建、重命名、复制、搜索和删除项目 | | 多画面比例 | `9:16`、`16:9`、`3:4`、`4:3`、`1:1` | | 演示模式 | 逐镜头全屏预览，检查节奏 | | 导出 | Markdown、HTML、Word、纯文本 | | 本地素材 | 上传图片 / 视频，放大预览、替换和删除 | ## 🔧 环境与依赖不需要 Python。VoxCPM 独立调用示例、参考音频参数和配音依赖见 [配音运行说明](docs/voice-runtime.md)。设置里的「环境检查」只列真正需要关心的项目：

| 项目 | 用途 | 缺少时 | | --- | --- | --- | | 配音服务 | VoxCPM 在线服务（纯 Node 调用） | 需要联网 | | FFmpeg | 配音转码、时长读取 | `brew install ffmpeg` | | Whisper | 把配音对齐到台词 | 没有它仍可生成配音；`brew install whisper-cpp` | | Codex CLI | 让 Claude Code 通过 Codex 生图 | 可选，也可用 Agent 自带生图或手动上传 |

环境变量

旧版的 `CODEX_STORYBOARD_*` 仍然有效，新变量优先。 ```text AGENT_STORYBOARD_DATA_DIR 数据目录 AGENT_STORYBOARD_PORT 端口，默认 43218 AGENT_STORYBOARD_FFMPEG FFmpeg 路径（同理 _FFPROBE、_WHISPER、_WHISPER_MODEL） AGENT_STORYBOARD_VOXCPM_URL 自建配音服务地址 AGENT_STORYBOARD_VOICE_CHUNK_CHARS 配音分段目标字数（默认 800，按句尾切分，非严格上限）。越大接缝越少但音色越容易后段偏移，越小越稳但接缝越多 AGENT_STORYBOARD_CODEX Codex CLI 路径 AGENT_STORYBOARD_CODEX_MODEL 生图时指定 Codex 模型（默认沿用 Codex 配置；若该模型不支持 ChatGPT 账号，会自动改用 gpt-5.5 重试） ```

## 🧰 MCP 工具 Agent 通过这些工具工作，不需要控制浏览器，也不会直接改数据文件。 | 工具 | 作用 | | --- | --- | | `open_storyboard` | 启动或连接本地分镜台，返回链接 | | `create_storyboard_project` | 一次性创建完整项目、全部镜头和可选 `DESIGN.md` | | `list_storyboard_projects` / `get_storyboard_project` | 查找项目、读取完整镜头 | | `update_storyboard_project` / `delete_storyboard_project` | 修改镜头、比例、视觉规范；删除项目 | | `list_storyboard_generation_tasks` | 读取待处理的生成任务 | | `generate_storyboard_image` | 一次调用完成：认领任务、通过 Codex 出图、校验、回填 | | `claim_…` / `complete_…` / `fail_…` / `heartbeat_storyboard_generation_task` | 处理动效视频等长任务 | | `plan_broll_motion` | B-roll 动效的方案确认关口 | | `manage_storyboard_audio` | 生成配音、选择版本、对齐台词、应用镜头时长 | | `inspect_storyboard_environment` | 检查配音、FFmpeg、Whisper 和本机 Agent |

常用提示词

```text 打开 Agent 分镜台。创建一个 9:16 的“AI 工具使用技巧”短视频分镜项目，直接写入分镜台。帮我把这个项目补成 8 个镜头，每个镜头写出台词、画面描述、时长和生成方式。处理所有待生成素材。优先生成 AI 生图，再生成动效视频。查看当前有哪些分镜项目，找到标题里包含“AI 工具”的项目。 ```

## 🔒 数据与隐私 - 项目、脚本和素材保存在本机，默认目录 `~/.agent-storyboard/`。用过旧版的话，已有的 `~/.codex-storyboard/` 会继续沿用，不会搬动或丢失。 - 本地服务只监听 `127.0.0.1`，并拒绝跨域请求。 - 配音会把台词发送到 VoxCPM 在线服务；通过 Codex 生图时，提示词会发送到 ChatGPT 的图片服务。请注意对应服务的隐私条款。 ```text ~/.agent-storyboard/ projects.json projects// project.json DESIGN.md media/ generation/ ``` ## 🛠 开发 ```bash git clone https://github.com/Yuuhann1999/agent-storyboard.git cd agent-storyboard npm start # http://127.0.0.1:43218，数据在仓库内 ./data npm run check # 语法检查 npm test # 单元与集成测试 ``` 网页使用原生 HTML、CSS 和 JavaScript，本地服务只用 Node.js 标准库，没有运行时 npm 依赖。

项目结构

```text . ├── server.mjs 本地服务（项目、生成任务、配音 API） ├── public/ 前端 ├── voxcpm.mjs 配音在线服务客户端 ├── codex-image.mjs 通过 Codex CLI 出图的桥接 ├── runtime.mjs / audio.mjs 环境检查、FFmpeg / Whisper 调用 ├── plugins/agent-storyboard/ │ ├── .codex-plugin/ Codex 清单 │ ├── .claude-plugin/ Claude Code 清单 │ ├── .mcp.codex.json Codex 的 MCP 启动配置 │ ├── mcp/server.mjs MCP 服务 │ ├── skills/ Agent 使用说明 │ └── app/ 随插件打包的服务和前端副本 ├── .agents/plugins/marketplace.json Codex marketplace └── .claude-plugin/marketplace.json Claude Code marketplace ``` 根目录的 `server.mjs` 和 `public/` 是主要编辑入口，改完后同步到 `plugins/agent-storyboard/app/`（`npm test` 里有一致性检查）。

本地调试插件

```bash codex plugin marketplace add . codex plugin add agent-storyboard@agent-storyboard claude plugin marketplace add . claude plugin install agent-storyboard@agent-storyboard claude plugin validate . ```

主要本地 API

```text GET /api/health GET /api/environment GET /api/projects POST 可一次性传入 shots 创建完整项目 GET /api/projects/:id PUT / PATCH / DELETE GET /api/projects/:id/design POST / DELETE POST /api/projects/:id/shots PATCH / DELETE /shots/:shotId POST /api/projects/:id/shots/:shotId/media POST /api/projects/:id/audio/generate select / align / apply-durations GET /api/generation/tasks POST 入队 POST /api/generation/tasks/:taskId/claim complete / fail / cancel / heartbeat ```

## 社区方案 - [ToAPIs 图片/视频外部生成与任务回填（社区方案）](https://github.com/ToAPIs-2025/lower-cost-agent-storyboard-toapis/blob/main/README_zh-CN.md)：由 ToAPIs 第三方维护，与本项目无关；使用及计费问题请联系 ToAPIs 团队。 ## License [MIT](LICENSE)