OpenFilm源码开发完全指南：从pnpm dev到添加自己的媒体Provider

OpenFilm 是一个开源的 AI 视频 Agent 项目：它把任何编程 Agent 变成"视频 Agent"，让 Codex、Claude Code 等直接写出电影（本质是网页），并提供一个本地编辑器 Studio 来修改它生成的任何内容。本文是一份面向新手的源码开发完整指南：带你用pnpm dev一键启动本地开发环境，理解 monorepo 结构，并亲手添加一个自己的媒体 Provider（为项目接入语音、音乐、图片、视频等媒体服务）。

1️⃣ 先认识 OpenFilm：电影就是网页

在动手改代码之前，先花一分钟理解项目的核心思路：

• 影片是网页：film.html把若干页面、素材和声音剪辑在一起，画面只依赖时间t；
• Studio 是本地编辑器：运行在浏览器里（用 Chromium 绘制画面），你可以手动或让 Agent 修改任何东西；
• openfilm命令：Agent 使用的手册式 CLI，openfilm get负责从你连接的各种服务获取媒体素材。

2️⃣ 开发环境准备：一条命令装好依赖

环境要求（见 CONTRIBUTING.md）：

安装步骤：

git clone https://gitcode.com/gh_mirrors/op/openfilm cd openfilm pnpm install pnpm --filter openfilm exec playwright-core install chromium-headless-shell

pnpm install会同时构建 Studio 编辑器（build:ui），最后的命令下载渲染画面所需的无头 Chromium。

3️⃣ 用 pnpm dev 启动本地 Studio

在项目根目录执行：

pnpm dev

这一条命令背后是 scripts/dev.mjs，它做了四件贴心事：

1. 启动 Studio 服务，默认监听4848端口（可用OPENFILM_STUDIO_PORT修改）；
2. 热更新：studio/ui有改动就重新构建编辑器（刷新页面即可），studio/server或src有改动会自动重启 Studio；
3. 隔离状态：开发状态和导出都放在packages/openfilm/.dev/（已被 git 忽略），不会干扰你正式安装的 OpenFilm；
4. 生成专属 CLI：在.dev/bin/openfilm写出一个指向本开发环境的命令，可以直接告诉你的编程 Agent"用这个命令做一部片子"，立刻验证你的改动。

启动成功后浏览器会自动打开一个示例影片，效果类似这样：

💡 提示：Ctrl+C即可停止全部进程；同一份 checkout 只允许一个pnpm dev（有 pid 锁保护）。

4️⃣ 仓库结构：五分钟看懂 monorepo

这是一个 pnpm workspace（见 pnpm-workspace.yaml），包含packages/*和apps/*三块：

packages/openfilm/ npm 包 openfilm：影片格式、CLI 和 Studio SPEC.md, MANUAL.md 影片格式规范；openfilm 为 Agent 打印的手册 bin/ openfilm 命令入口 src/ 解析 film.html、无头浏览器渲染、look 与 render studio/server/ Studio 服务：项目、编辑、历史、导出、媒体 Provider studio/ui/ Studio 编辑器（React + Vite） apps/desktop/ 桌面应用（Electron，内含 Agent 聊天窗口） packages/shared/ 桌面应用共享的聊天类型与工具（不发布） skills/ 引导编程 Agent 使用手册的 skill

根目录常用命令一览：

改完代码后建议随时跑pnpm test与pnpm typecheck；也可以只跑单个文件，例如node --test src/film-doc.test.mjs。

5️⃣ 添加自己的媒体 Provider 🚀

这是本次的重头戏。openfilm get支持十几种"动词"（verb）：tts（配音）、music、sfx（音效）、asr（转写）、image、video、web-search等。每个 Provider 就是一个模块，负责其中几类媒体的制作。

第一步：读懂 Provider 契约

所有 Provider 共同遵守 contract.mjs 中定义的Provider接口：

• id/name：标识与展示名；
• env：环境变量名（如GROQ_API_KEY），用户可直接用环境变量提供密钥；
• verbs：支持的动词列表；
• models：每类媒体可用的模型（第一个为默认）；
• run(verb, args, ctx)：真正干活的方法，返回文件、索引和回执。

仓库里的 groq.mjs 是最小的参考实现之一，建议从它抄起。

第二步：新建 Provider 文件

在 studio/server/providers/ 下新建myservice.mjs，骨架如下：

export default { id: 'myservice', name: 'MyService', env: 'MY_SERVICE_API_KEY', keysUrl: 'https://myservice.example/keys', billingUrl: 'https://myservice.example/billing', verbs: ['image'], async run(verb, args, ctx) { // 调用服务 API，返回 { files, index, receipt } }, };

请求工具都在 common.mjs 里：call（自动处理鉴权失败、余额不足等统一报错）、landing（规定文件落在assets/下）、needed（必填参数校验）等，无需重复造轮子。

第三步：注册到 Provider 列表

打开 index.mjs，把你的 Provider 加进OWN数组（按名称排序）：

const OWN = [elevenlabs, openai, google, fal, /* … */ myservice];

之后--via myservice、Studio 设置页的 Provider/模型选择、密钥管理就会自动生效。

第四步：为假服务写测试

官方要求：CI 里不消耗真实密钥。做法参考 groq.test.mjs——在127.0.0.1起一个假 HTTP 服务，再通过OPENFILM_<NAME>_URL环境变量把 Provider 指过去，断言"发了什么、落盘了什么、失败时用户看到什么"：

node --test studio/server/providers/myservice.test.mjs

第五步：补齐"门面"细节

1. 品牌标记：在 provider-marks.ts 里加一条 SVG mark（测试会强制要求每个 Provider 都有）；
2. 多语言：它在 Studio 中展示的每一句文案都要翻译进en / zh-CN / ja / ko / es五个语言文件（studio/ui/src/i18n/）；
3. changeset：pnpm changeset生成变更集并随 PR 提交。

接好 Provider 后，你在影片里能生成这样的素材：

6️⃣ 实战小贴士 💡

• 密钥安全：密钥保存在~/.openfilm/providers.json（权限 0600），只发往对应服务本身；编辑器页面永远只能看到密钥来源和后四位（逻辑见 keys.mjs）。测试和截图中严禁出现真实密钥；
• 用 Agent 验证改动：pnpm dev运行时，让 Agent 改用packages/openfilm/.dev/bin/openfilm，它生成的影片会直接出现在你的开发版 Studio 里；
• 提交前自检：pnpm test、pnpm typecheck、pnpm audit:public三件套必须全部通过（CI 在 macOS、Windows、Linux 三端都跑）。

结语

OpenFilm 的本地开发体验非常顺滑：一条pnpm dev就能获得热更新环境 + 专属 CLI + 隔离状态；而 Provider 体系用"一个文件 + 一份契约 + 假服务测试"的模式，把"接入一家新的媒体服务"压缩到了几小时的活。挑一个你最常用的 API，今天就把它变成你的第一个 Provider 吧！