Skip to content
Back to search

agent-storyboard

MarketplaceWorks with Claude CodeGitHub

本地优先的 Agent 视频分镜工作台:让 Codex、Claude Code 通过 MCP 写分镜、生成图片/视频素材和配音,并自动回填。Local-first storyboard workbench for AI agents (Codex, Claude Code).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yuuhann1999--agent-storyboard/badge.svg)](/listings/yuuhann1999--agent-storyboard)

HTML

<a href="/listings/yuuhann1999--agent-storyboard"><img src="/api/listings/yuuhann1999--agent-storyboard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "agent-storyboard",
  3. "owner": { "name": "Yuuhann" },
  4. "metadata": { "description": "Agent Storyboard: a local storyboard workbench for Codex and Claude Code." },
  5. "plugins": [
  6. {
  7. "name": "agent-storyboard",
  8. "source": "./plugins/agent-storyboard",
  9. "description": "Create storyboard projects, generate image and video assets per shot, add voiceover, and see results land in the right row.",
  10. "version": "0.8.0",
  11. "category": "productivity"
  12. }
  13. ]
  14. }
README.md · README · 342 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="docs/assets/agent-storyboard-cover.png" alt="Agent 分镜台" width="100%">
  3. <h1>Agent 分镜台 · Agent Storyboard</h1>
  4. <p><b>让 Codex、Claude Code 帮你把视频从想法做到分镜、素材和配音。</b><br>
  5. 一个本地优先的分镜工作台:Agent 负责写和生成,你在一张表里检查、调整、验收。</p>
  6. <p>
  7. <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-22c55e.svg" alt="MIT"></a>
  8. <img src="https://img.shields.io/badge/Codex-Plugin-111827" alt="Codex Plugin">
  9. <img src="https://img.shields.io/badge/Claude%20Code-Plugin-d97757" alt="Claude Code Plugin">
  10. <img src="https://img.shields.io/badge/MCP-Ready-0ea5e9" alt="MCP Ready">
  11. <img src="https://img.shields.io/badge/Node.js-18%2B-339933" alt="Node.js 18+">
  12. <img src="https://img.shields.io/badge/Local--first-Yes-2563eb" alt="Local first">
  13. </p>
  14. <p>
  15. <a href="#-快速开始">快速开始</a> ·
  16. <a href="#-它是怎么工作的">工作方式</a> ·
  17. <a href="#-功能一览">功能</a> ·
  18. <a href="#-环境与依赖">环境</a> ·
  19. <a href="#-mcp-工具">MCP 工具</a> ·
  20. <a href="#-开发">开发</a> ·
  21. <a href="#社区方案">社区方案</a>
  22. </p>
  23. </div>
  24. ---
  25. ## 为什么做它
  26. 做一条短视频,脚本在文档里,分镜在表格里,图片在生图网页里,配音在另一个工具里,素材散落在文件夹里。每换一个窗口,上下文就丢一次。
  27. Agent 分镜台把这些收进同一张**本地分镜表**:
  28. - **Agent 直接写入**:一句话让 Agent 建好完整项目,不需要控制浏览器。
  29. - **结果自动回填**:Agent 生成的图片、视频和配音,落进对应镜头,不用手动对文件名。
  30. - **你只做验收**:所有自动化结果都在表格里,能一眼看到、直接改。
  31. - **数据都在本机**:项目、脚本和素材保存在你的电脑上。
  32. <div align="center">
  33. <img src="docs/assets/demo-fill.gif" alt="素材生成后自动回填到分镜表" width="86%">
  34. <br><sub>Agent 生成素材,结果自动回填到对应镜头</sub>
  35. </div>
  36. ## 🚀 快速开始
  37. 需要 Node.js 18 或更高版本,以及 Codex 或 Claude Code 之一。
  38. **1. 安装插件**
  39. <table>
  40. <tr>
  41. <td width="50%" valign="top">
  42. **Codex**
  43. ```bash
  44. codex plugin marketplace add Yuuhann1999/agent-storyboard
  45. codex plugin add agent-storyboard@agent-storyboard
  46. ```
  47. </td>
  48. <td width="50%" valign="top">
  49. **Claude Code**
  50. ```bash
  51. claude plugin marketplace add Yuuhann1999/agent-storyboard
  52. claude plugin install agent-storyboard@agent-storyboard
  53. ```
  54. </td>
  55. </tr>
  56. </table>
  57. 安装后新开一个对话,让 MCP 工具重新加载(Claude Code 里可以用 `/mcp` 确认 `agent-storyboard` 已连接)。
  58. **2. 打开分镜台**
  59. ```text
  60. 打开 Agent 分镜台。
  61. ```
  62. 插件会自动启动内置的本地工作台,并给出链接(默认 `http://127.0.0.1:43218`),在侧边栏或浏览器里打开即可。
  63. **3. 创建第一个项目**
  64. ```text
  65. 创建一个 9:16 的短视频分镜项目,主题是“独居第三年,我把 20㎡ 出租屋改成了工作室”,
  66. 风格干净、节奏快,适合抖音。写好台词和画面描述。
  67. ```
  68. **4. 生成素材**
  69. 在分镜台里点镜头的「生成素材」,或点顶栏的「批量生成」,然后对 Agent 说:
  70. ```text
  71. 处理 Agent 分镜台里所有待生成素材。
  72. ```
  73. ## 🧭 它是怎么工作的
  74. ```mermaid
  75. flowchart LR
  76. A["你:视频主题和要求"] --> B["Agent 通过 MCP<br/>写入完整分镜项目"]
  77. B --> C["你在分镜表里<br/>检查、调整"]
  78. C --> D["加入生成队列<br/>单镜头 / 批量"]
  79. D --> E["Agent 生成<br/>图片 · 动效视频 · 配音"]
  80. E --> F["素材自动回填<br/>到对应镜头"]
  81. F --> C
  82. ```
  83. 分镜台是一个本地网页服务,Agent 通过 MCP 工具和它对话。三种生成方式按镜头选择:
  84. | 生成方式 | 做什么 | 由谁完成 |
  85. | --- | --- | --- |
  86. | **AI 生图** | 按画面描述生成图片 | Codex 用自带的 image_gen;Claude Code 通过 `generate_storyboard_image` 调用本机 Codex 出图 |
  87. | **HyperFrames / Remotion 动效** | 用代码渲染字幕、信息图、转场等视频 | Agent 在本地渲染(需要对应插件和渲染工具链) |
  88. | **手动素材** | 自己拍的、自己剪的 | 你上传图片或视频 |
  89. ## ✨ 功能一览
  90. ### 一张表看完整个分镜
  91. 镜头类型、媒体、时长、台词、画面描述、生成方式、素材预览和备注都在同一行。长项目切到「紧凑」,一屏看更多镜头;节奏有问题的镜头会直接标出提示。
  92. <table>
  93. <tr>
  94. <td width="50%"><img src="docs/assets/table.png" alt="分镜表:详细视图"><br><sub>详细视图</sub></td>
  95. <td width="50%"><img src="docs/assets/table-compact.png" alt="分镜表:紧凑视图"><br><sub>紧凑视图,一屏 7 个镜头</sub></td>
  96. </tr>
  97. </table>
  98. - 拖拽或 `Alt + ↑/↓` 调整顺序,复制镜头、在下方插入,误删可以撤销。
  99. - 素材文件名带镜头序号,调整顺序后会自动同步,不会互相覆盖。
  100. - 按台词、画面、备注搜索;顶栏实时显示「生成中 / 排队 / 失败」数量,点一下定位。
  101. ### 口播配音,和台词对齐
  102. 在脚本页生成配音,可以描述声音风格,也可以上传参考音频克隆音色。生成后用本地 Whisper 识别,把配音对齐到每个镜头的台词,再一键应用镜头时长。
  103. <div align="center"><img src="docs/assets/script-voice.png" alt="脚本与口播配音" width="88%"></div>
  104. ### 素材总览与封面工作台
  105. 只列做出来的素材,一眼看到进度。封面按竖屏 9:16 和横屏 16:9 分别管理,支持模板、参考图和提示词。
  106. <table>
  107. <tr>
  108. <td width="50%"><img src="docs/assets/assets.png" alt="素材总览"><br><sub>素材总览</sub></td>
  109. <td width="50%"><img src="docs/assets/cover.png" alt="封面工作台"><br><sub>封面工作台</sub></td>
  110. </tr>
  111. </table>
  112. ### 风格库与 DESIGN.md
  113. 12 种内置视觉风格,选中后写入项目的 `DESIGN.md`。之后所有图片和视频素材都会遵循这份视觉规范,单个镜头的明确要求优先。
  114. <div align="center"><img src="docs/assets/styles.png" alt="风格库" width="88%"></div>
  115. ### 深色模式,也适合窄窗口
  116. 跟随你的习惯切换主题。放进 Agent 的侧边栏这类窄窗口时,分镜表会自动变成卡片布局。
  117. <table>
  118. <tr>
  119. <td width="66%"><img src="docs/assets/table-dark.png" alt="深色模式"></td>
  120. <td width="34%"><img src="docs/assets/sidebar.png" alt="窄窗口卡片布局"></td>
  121. </tr>
  122. </table>
  123. ### 更多
  124. | | |
  125. | --- | --- |
  126. | 多项目管理 | 新建、重命名、复制、搜索和删除项目 |
  127. | 多画面比例 | `9:16`、`16:9`、`3:4`、`4:3`、`1:1` |
  128. | 演示模式 | 逐镜头全屏预览,检查节奏 |
  129. | 导出 | Markdown、HTML、Word、纯文本 |
  130. | 本地素材 | 上传图片 / 视频,放大预览、替换和删除 |
  131. ## 🔧 环境与依赖
  132. 不需要 Python。VoxCPM 独立调用示例、参考音频参数和配音依赖见 [配音运行说明](docs/voice-runtime.md)。设置里的「环境检查」只列真正需要关心的项目:
  133. <table>
  134. <tr>
  135. <td width="55%" valign="top">
  136. | 项目 | 用途 | 缺少时 |
  137. | --- | --- | --- |
  138. | 配音服务 | VoxCPM 在线服务(纯 Node 调用) | 需要联网 |
  139. | FFmpeg | 配音转码、时长读取 | `brew install ffmpeg` |
  140. | Whisper | 把配音对齐到台词 | 没有它仍可生成配音;`brew install whisper-cpp` |
  141. | Codex CLI | 让 Claude Code 通过 Codex 生图 | 可选,也可用 Agent 自带生图或手动上传 |
  142. </td>
  143. <td width="45%" valign="top"><img src="docs/assets/environment.png" alt="环境检查"></td>
  144. </tr>
  145. </table>
  146. <details>
  147. <summary>环境变量</summary>
  148. 旧版的 `CODEX_STORYBOARD_*` 仍然有效,新变量优先。
  149. ```text
  150. AGENT_STORYBOARD_DATA_DIR 数据目录
  151. AGENT_STORYBOARD_PORT 端口,默认 43218
  152. AGENT_STORYBOARD_FFMPEG FFmpeg 路径(同理 _FFPROBE、_WHISPER、_WHISPER_MODEL)
  153. AGENT_STORYBOARD_VOXCPM_URL 自建配音服务地址
  154. AGENT_STORYBOARD_VOICE_CHUNK_CHARS 配音分段目标字数(默认 800,按句尾切分,非严格上限)。越大接缝越少但音色越容易后段偏移,越小越稳但接缝越多
  155. AGENT_STORYBOARD_CODEX Codex CLI 路径
  156. AGENT_STORYBOARD_CODEX_MODEL 生图时指定 Codex 模型(默认沿用 Codex 配置;若该模型不支持 ChatGPT 账号,会自动改用 gpt-5.5 重试)
  157. ```
  158. </details>
  159. ## 🧰 MCP 工具
  160. Agent 通过这些工具工作,不需要控制浏览器,也不会直接改数据文件。
  161. | 工具 | 作用 |
  162. | --- | --- |
  163. | `open_storyboard` | 启动或连接本地分镜台,返回链接 |
  164. | `create_storyboard_project` | 一次性创建完整项目、全部镜头和可选 `DESIGN.md` |
  165. | `list_storyboard_projects` / `get_storyboard_project` | 查找项目、读取完整镜头 |
  166. | `update_storyboard_project` / `delete_storyboard_project` | 修改镜头、比例、视觉规范;删除项目 |
  167. | `list_storyboard_generation_tasks` | 读取待处理的生成任务 |
  168. | `generate_storyboard_image` | 一次调用完成:认领任务、通过 Codex 出图、校验、回填 |
  169. | `claim_…` / `complete_…` / `fail_…` / `heartbeat_storyboard_generation_task` | 处理动效视频等长任务 |
  170. | `plan_broll_motion` | B-roll 动效的方案确认关口 |
  171. | `manage_storyboard_audio` | 生成配音、选择版本、对齐台词、应用镜头时长 |
  172. | `inspect_storyboard_environment` | 检查配音、FFmpeg、Whisper 和本机 Agent |
  173. <details>
  174. <summary>常用提示词</summary>
  175. ```text
  176. 打开 Agent 分镜台。
  177. 创建一个 9:16 的“AI 工具使用技巧”短视频分镜项目,直接写入分镜台。
  178. 帮我把这个项目补成 8 个镜头,每个镜头写出台词、画面描述、时长和生成方式。
  179. 处理所有待生成素材。优先生成 AI 生图,再生成动效视频。
  180. 查看当前有哪些分镜项目,找到标题里包含“AI 工具”的项目。
  181. ```
  182. </details>
  183. ## 🔒 数据与隐私
  184. - 项目、脚本和素材保存在本机,默认目录 `~/.agent-storyboard/`。用过旧版的话,已有的 `~/.codex-storyboard/` 会继续沿用,不会搬动或丢失。
  185. - 本地服务只监听 `127.0.0.1`,并拒绝跨域请求。
  186. - 配音会把台词发送到 VoxCPM 在线服务;通过 Codex 生图时,提示词会发送到 ChatGPT 的图片服务。请注意对应服务的隐私条款。
  187. ```text
  188. ~/.agent-storyboard/
  189. projects.json
  190. projects/<project-id>/
  191. project.json DESIGN.md media/ generation/
  192. ```
  193. ## 🛠 开发
  194. ```bash
  195. git clone https://github.com/Yuuhann1999/agent-storyboard.git
  196. cd agent-storyboard
  197. npm start # http://127.0.0.1:43218,数据在仓库内 ./data
  198. npm run check # 语法检查
  199. npm test # 单元与集成测试
  200. ```
  201. 网页使用原生 HTML、CSS 和 JavaScript,本地服务只用 Node.js 标准库,没有运行时 npm 依赖。
  202. <details>
  203. <summary>项目结构</summary>
  204. ```text
  205. .
  206. ├── server.mjs 本地服务(项目、生成任务、配音 API)
  207. ├── public/ 前端
  208. ├── voxcpm.mjs 配音在线服务客户端
  209. ├── codex-image.mjs 通过 Codex CLI 出图的桥接
  210. ├── runtime.mjs / audio.mjs 环境检查、FFmpeg / Whisper 调用
  211. ├── plugins/agent-storyboard/
  212. │ ├── .codex-plugin/ Codex 清单
  213. │ ├── .claude-plugin/ Claude Code 清单
  214. │ ├── .mcp.codex.json Codex 的 MCP 启动配置
  215. │ ├── mcp/server.mjs MCP 服务
  216. │ ├── skills/ Agent 使用说明
  217. │ └── app/ 随插件打包的服务和前端副本
  218. ├── .agents/plugins/marketplace.json Codex marketplace
  219. └── .claude-plugin/marketplace.json Claude Code marketplace
  220. ```
  221. 根目录的 `server.mjs` 和 `public/` 是主要编辑入口,改完后同步到 `plugins/agent-storyboard/app/`(`npm test` 里有一致性检查)。
  222. </details>
  223. <details>
  224. <summary>本地调试插件</summary>
  225. ```bash
  226. codex plugin marketplace add .
  227. codex plugin add agent-storyboard@agent-storyboard
  228. claude plugin marketplace add .
  229. claude plugin install agent-storyboard@agent-storyboard
  230. claude plugin validate .
  231. ```
  232. </details>
  233. <details>
  234. <summary>主要本地 API</summary>
  235. ```text
  236. GET /api/health
  237. GET /api/environment
  238. GET /api/projects POST 可一次性传入 shots 创建完整项目
  239. GET /api/projects/:id PUT / PATCH / DELETE
  240. GET /api/projects/:id/design POST / DELETE
  241. POST /api/projects/:id/shots PATCH / DELETE /shots/:shotId
  242. POST /api/projects/:id/shots/:shotId/media
  243. POST /api/projects/:id/audio/generate select / align / apply-durations
  244. GET /api/generation/tasks POST 入队
  245. POST /api/generation/tasks/:taskId/claim complete / fail / cancel / heartbeat
  246. ```
  247. </details>
  248. ## 社区方案
  249. - [ToAPIs 图片/视频外部生成与任务回填(社区方案)](https://github.com/ToAPIs-2025/lower-cost-agent-storyboard-toapis/blob/main/README_zh-CN.md):由 ToAPIs 第三方维护,与本项目无关;使用及计费问题请联系 ToAPIs 团队。
  250. ## License
  251. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.