内容
# OpenVideoKit
> 基于场景的AI视频编辑器。内置的副驾驶提出编辑建议，用户可以接受或拒绝，任何MCP代理都可以驱动它。
**[官网](https://www.openvideokit.com/)** · **[快速开始](https://www.openvideokit.com/get-started)** · **[模板画廊](https://www.openvideokit.com/templates)** · [PyPI](https://pypi.org/project/openvideokit/) · [文档](docs/)
## 演示
<table>
<tr>
<td colspan="2" align="center" valign="top">
<h3>🎬 OpenVideoKit 介绍</h3>
<a href="https://youtu.be/M9SWPo5Pa-k" target="_blank">
<img src="https://img.youtube.com/vi/M9SWPo5Pa-k/maxresdefault.jpg" alt="Introducing OpenVideoKit" width="70%" />
</a>
<p><strong>▶ <a href="https://youtu.be/M9SWPo5Pa-k" target="_blank">在 YouTube 上观看</a></strong></p>
<p><em>简要介绍：基于场景的编辑、AI副驾驶、MCP代理和MP4导出。</em></p>
</td>
</tr>
<tr>
<td width="50%" align="center" valign="top">
<h3>🎬 模板展示</h3>
<a href="https://youtu.be/2LjwjLw5m_o" target="_blank">
<img src="https://img.youtube.com/vi/2LjwjLw5m_o/maxresdefault.jpg" alt="OpenVideoKit demo video" width="100%" />
</a>
<p><strong>▶ <a href="https://youtu.be/2LjwjLw5m_o" target="_blank">在 YouTube 上观看</a></strong></p>
</td>
<td width="50%" align="center" valign="top">
<h3>🖼️ 编辑器截图</h3>
<img src="https://cdn.jsdelivr.net/gh/quanhua92/openvideokit@main/demo.jpg" alt="Editor screenshot with the prompt that generated the demo video" width="100%" />
<p><em>编辑器显示生成演示视频的AI提示。</em></p>
</td>
</tr>
<tr>
<td colspan="2" align="center" valign="top">
<h3>🌍 文本转语音引擎展示 — 44秒内7种语言</h3>
<a href="https://youtu.be/ABBA2DqWrq0" target="_blank">
<img src="https://img.youtube.com/vi/ABBA2DqWrq0/maxresdefault.jpg" alt="Global Voices demo — edge-tts voiceover across 7 languages" width="70%" />
</a>
<p><strong>▶ <a href="https://youtu.be/ABBA2DqWrq0" target="_blank">在 YouTube 上观看</a></strong></p>
<p><em>edge-tts语音展示：🇺🇸 Ava Multilingual → 🇫🇷 Vivienne → 🇩🇪 Florian → 🇯🇵 Nanami → 🇻🇳 Hoài My → 🇨🇳 Xiaoxiao → 🇧🇷 Thalita → 🇺🇸 Ava Multilingual。</em></p>
</td>
</tr>
</table>
---
OpenVideoKit 是一个视频模板管道：编辑网页UI中的幻灯片 → Python SSR 将值印章到自包含的GSAP合成中 → `<hyperframes-player>` 实时渲染 → edge-tts 生成语音音频 → 通过 HyperFrames 导出为 MP4。 LangGraph AI 代理提出编辑建议（与人类相同的 `EditOp`），用户接受或拒绝 — 撤销/重做功能统一。
幻灯片从**精选模板目录**中选择布局（`templates/slides/<author>/<name>/`）及其**媒体（图像/视频/音频）**是存储在幻灯片字段中的URL字符串 — 上传到基于内容的后端存储或任何远程URL（picsum，S3）。
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ovk-web │ │ Python API │ │ 磁盘 │
│ （React SPA）│ │ （FastAPI）│ │ （每张幻灯片）│
│ :3000 │←──→│ :8000 │←──→│ 数据/ │
│ │ │ │ │ │
│ <hf-player> │ │ 印章HTML │ │ 项目.json │
│ EditBus │ │ 推送/ SSE /修订│ │ audio-{hash} │
│ 播放器 │ │ edge-tts │ │ 资产/ │
│ 字幕 │ │ 渲染MP4 │ │ 作业/ │
│ AIDock │ │ LangGraph AI│ │ 作业.json │
│ 属性 │ │ 模板 │ │ │
│ +媒体 │ │ +资产 │ │ │
└──────────────┘ │ /mcp （MCP）│ └──────────────┘
│ 29 个工具 │
└──────┬───────┘
│
┌─────────────┼─────────────┐
│ │ │
┌────┴────┐ ┌─────┴───┐ ┌──────┴──┐
│Claude │ │Cursor │ │Gemini CLI│
│代码 │ │ │ │Goose │
│（MCP） │ │（MCP） │ │（MCP） │
└─────────┘ └─────────┘ └─────────┘
外部AI代理通过MCP工具编辑（→ Python API，而不是磁盘）
```
## 快速开始
### 选项1 — 从PyPI安装（推荐用户）
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install openvideokit
ovk serve # http://0.0.0.0:8000
```
首次运行 `ovk serve` 时，OpenVideoKit会将一个记录配置文件的文档写入 `~/.openvideokit/config.toml`（chmod 600 — 密码安全）。要启用AI，请编辑它并重启：
```bash
ovk config edit # 打开 $EDITOR；设置 [ai].openai_api_key
ovk serve # 重启以应用
```
就是这样。捆绑的SPA、所有25个幻灯片模板、edge-tts语音、MP4导出、LangGraph AI副驾驶和MCP服务器供外部代理使用都包含在轮子中。
- **编辑器** → `http://localhost:8000`
- **AI连接测试** → `ovk llm test`
- **浏览免费模型** → `ovk llm free` （列出免费的OpenRouter模型，带有上下文、推理、工具和正常运行时间）
- **设置页面** → `http://localhost:8000/settings` （只读运行时配置 + 编辑指南）
- **MCP端点** → `http://localhost:8000/mcp/`
参见 [`docs/config.md`](docs/config.md) 了解完整的优先级链（环境变量 > `.env` > `config.toml` > 默认值），工作流程演练和 `ovk config init|get|set|edit` CLI参考。
### 选项2 — 开发检查（推荐贡献者）
```bash
git clone <此仓库>
cd openvideokit
uv sync --extra dev # 安装Python依赖
cp .env.example .env # 然后编辑.env（设置OPENAI_API_KEY以启用AI）
cd ovk-web && pnpm install && cd .. # 安装前端依赖
```
### 运行开发栈 — 两个终端（推荐）
`scripts/dev.sh` 在后台运行两个服务器，使用`nohup`，因此导入错误、端口冲突和缺少环境失败都隐藏在 `/tmp/*.log` 中，脚本在服务器已死时仍报告成功。 **在自己的前台终端中运行每个服务器** — 您获得实时日志，并且 `Ctrl-C` 清洁停止。
**终端 1 — Python API** （端口 8000）：
```bash
uv run ovk serve --reload
```
**终端 2 — Vite 开发** （端口 3000，代理 `/api` → `:8000`）：
```bash
cd ovk-web && pnpm dev -- --port 3000 --host
```
然后打开 `http://localhost:3000`。
- **Python API** → `http://localhost:8000`
- **Vite 开发** → `http://localhost:3000` （代理 `/api` → `:8000`）
- **AI连接测试** → `uv run ovk llm test`
- **浏览免费模型** → `uv run ovk llm free` （列出免费的OpenRouter模型，带有上下文、推理、工具和正常运行时间）
### 替代方案：`scripts/dev.sh` （后台运行两个服务器）
如果您更喜欢一个命令并且不需要实时日志：
```bash
./scripts/dev.sh # 启动两个服务器（后台）
./scripts/dev.sh --stop # 停止两个服务器
tail -f /tmp/ovk-server.log # API 日志
tail -f /tmp/ovk-vite.log # Vite 日志
```
注意：脚本立即返回，服务器保持运行 — 如果出现问题，请检查上面的日志。
## 通过MCP连接AI代理
MCP服务器在端口8000的`/mcp/` **默认启用**。任何MCP兼容的客户端都可以连接并通过与应用内AI相同的工具集编辑项目 — 直接不触摸文件。
### Claude 代码
创建 `.claude/mcp.json` （或 `~/.config/claude-code/mcp.json`）：
```json
{
"mcpServers": {
"openvideokit": {
"url": "http://localhost:8000/mcp/"
}
}
}
```
然后询问Claude Code： *"创建3张幻灯片的产品视频并设置每张幻灯片的标题。"* 它将调用 `create_project_tool`、`set_field`、`add_slide` 等 — 每个突变都会立即持久化到磁盘。
### Cursor / Gemini CLI / Goose
```json
{
"mcpServers": {
"openvideokit": {
"transport": { "type": "streamable_http", "url": "http://localhost:8000/mcp/" }
}
}
}
```
### 验证
```bash
uv run python scripts/test-mcp.py --no-tts # 32次检查，所有29个工具
```
参见 [docs/mcp.md](docs/mcp.md) 了解完整的设计（执行调用语义、路径安全合约、语音TTS循环、撤销权衡）。
## 命令
用户界面（适用于 `pip install openvideokit` 和开发检查）：
| 任务 | 命令 |
|---|---|
| 运行服务器 | `ovk serve` （开发：`uv run ovk serve --reload`） |
| 编辑配置 | `ovk config edit` （打开 `$EDITOR` on `~/.openvideokit/config.toml`） |
| AI连接测试 | `ovk llm test` |
| 浏览免费模型 | `ovk llm free` |
仅限开发检查：
| 任务 | 命令 |
|---|---|
| 启动开发栈 | `./scripts/dev.sh` |
| 停止 | `./scripts/dev.sh --stop` |
| MCP端到端测试 | `uv run --extra dev python scripts/test-mcp.py --no-tts` |
| Python lint | `uv run ruff check src scripts tests` |
| Python 单元测试（快速） | `uv run pytest tests/` |
| Python 单元测试（包括渲染） | `uv run pytest tests/ --run-slow` |
| Python AI 测试 | `uv run pytest tests/ai/` |
| Python MCP 测试 | `uv run pytest tests/mcp/` |
| Python端到端测试 | `uv run --extra dev python scripts/test-e2e.py` |
| 前端开发 | `cd ovk-web && pnpm dev` |
| 前端测试 | `cd ovk-web && pnpm test` |
| 前端lint | `cd ovk-web && pnpm exec biome check src/` |
| 安装Web浏览器 | `uv run playwright install chromium` |
## 架构
- **Python SSR** (`src/openvideokit/`): FastAPI 提供印章的HF合成、项目JSON、TTS、SSE和MP4导出。基于磁盘的存储，每个幻灯片的文件夹、`fcntl.flock`和`watchdog`文件监视器。
- **前端** (`ovk-web/`): React 19 SPA，带有`<hyperframes-player>`、EditBus进行突变、Zustand播放器、TanStack Query + 乐观锁定（内容哈希修订）。
- **AI** (`src/openvideokit/ai/`): LangGraph 代理，探索项目，带有只读工具，并提出编辑建议为 `EditOp` 列表， 通过SSE。前端 `AIDock` 通过相同的 `EditBus` 发送每个操作 — 所以撤销/重做、lint门和SSE同步是保留的（AI流程 == 人类流程）。 默认模型 `gpt-5.4-nano`；任何OpenAI兼容的端点通过 `OPENAI_BASE_URL` （OpenAI / OpenRouter / Ollama / vLLM / LM Studio）。始终注册的 `web_search` （DuckDuckGo）+ `web_fetch`（crawl4ai）工具在运行时由 `OVK_ENABLE_WEB` 控制。 接受建议自动继续带有标记的收据（ `[AI PROPOSED]` / `[USER ACCEPTED]`）携带创建的幻灯片ID和字段值（`VITE_AI_AUTOCONTINUE`，默认为开启）。 参见 [docs/ai.md](docs/ai.md)。
- **TTS**：edge-tts 生成内容寻址的 `audio-{hash}.mp3` 每张幻灯片。手动生成按钮（不自动触发）。语音数据存在于 `audio.json` 中，与 `index.json` 分开。
- **导出**：`npx hyperframes render` 子进程在一个有界的ThreadPoolExecutor上（`OVK_MAX_CONCURRENT_RENDERS`）。语音音频从每张幻灯片的TTS合并成单个音轨。作业元数据持久化到 `{project_id}/jobs.json`。 参见 [docs/web/export.md](docs/web/export.md)。
- **字幕**：字幕层定时 + HTML + GSAP + CSS（`captions.py`）。预览和渲染共享相同的GSAP时间线 — 没有单独的叠加系统。设置在 `root.captions` via EditBus.
- **模板**：精选的只读幻灯片布局目录 `templates/slides/<author>/<name>/`（16个 `ovk` 布局随附）。每个都是一个裸 `<template>` 使用 `__` 词汇字段；背景用户可主题化通过 `bg_color` 字段。 REST：`GET /api/projects/{id}/templates` + `GET /api/projects/{id}/templates/{author}/{name}`。 AI 工具：`list_templates`、`read_templates`、`apply_template`；`add_slide`/`add_many_slides` 直接获取 `template_id`。 参见 [docs/templates.md](docs/templates.md)。
- **媒体资产**：图像/视频/音频存于 `slide.fields` 作为 **URL 字符串** 通过 `set_field` 设置（无需客户端 blob 存储）。上传 `POST /api/projects/{id}/assets` → 后端基于内容的存储（键 = `sha256(project_id + bytes)`，因此每个项目的资产都是隔离的），在 `GET /api/assets/{key}` 处提供（带有美观的 `.ext`）。`OVK_ASSETS_BASE_URL` 是 S3/CDN 缝合处。 参见 [docs/assets.md](docs/assets.md)。
- **MCP服务器** (`src/openvideokit/mcp/`): 对所有 **26 个编辑工具** + 2 个项目管理工具（共 28 个）暴露给 **任何**MCP兼容的AI代理，通过 `/mcp/` 处的Model Context Protocol。Claude Code、Cursor、Gemini CLI、Goose直接连接 — 调用时执行突变（通过与Web使用的相同`store.update_project`持久化到磁盘）。 默认启用（`OVK_MCP_ENABLED=true`）。 参见 [docs/mcp.md](docs/mcp.md).
参见 [docs/web/](docs/web/) 了解详细的架构、API参考、导出管道和并发模型， 和 [docs/ai.md](docs/ai.md) 了解 AI 实现合约。
## 调试AI
每次AI操作都可以将完整的LLM上下文（系统提示 + 工具 + 消息 + 项目快照）以及实时执行跟踪（每个工具调用带有输入、输出和持续时间）转储到每个运行的Markdown文件中。 默认情况下在初始开发过程中开启；通过 `.env` 中的 `OVK_AI_MONITORING=false` 关闭。
```bash
# 日志归档于此处（每个 run_agent 调用一个 .md 文件，UTC 时间戳）：
data/{project_id}/monitor/
├── 20260703-102345Z.md ← 跟踪（头部 → 上下文 → 事件 → 总结）
├── latest.md ← 链接 → 最新（每次操作后刷新）
└── index.md ← 生成的表格，新建的在前
# 实时跟踪正在进行的运行：
tail -f data/proj-1/monitor/latest.md
# 对比两次运行以查看更改：
diff data/proj-1/monitor/20260703-102345Z.md data/proj-1/monitor/20260703-102400Z.md
```
跟踪记录了模型实际获得的内容和实际执行的操作，因此当代理行为异常时，您可以准确定位问题出在提示、工具连线、消息历史还是模型本身。有关实际令牌使用和仪表板，请参见 [docs/ai-monitoring.md](docs/ai-monitoring.md) 中的 LangSmith 替代方案。
## 项目结构
```
openvideokit/
├── src/openvideokit/ # Python SSR 服务器
│ ├── app.py # FastAPI + 生存期（存储、执行器、监视器、MCP 挂载）
│ ├── routes.py # /api 端点（项目、TTS、导出、SSE、AI 聊天、聊天、模板、资产）
│ ├── store.py # 基于磁盘的存储 + 版本控制 + 文件锁
│ ├── validation.py # 标识符正则门控（路径安全性，在路径帮助器中强制执行）
│ ├── gsap_validator.py # GSAP <script> 正文验证器（保留 - 参见 docs/animation.md）
│ ├── composition.py # 自包含的 GSAP 合成构建器
│ ├── captions.py # 字幕层：时间 + HTML + GSAP + CSS
│ ├── rendering.py # 导出管道：执行器、作业、语音合成、串联
│ ├── voiceover.py # edge-tts 管道 + 内容寻址缓存
│ ├── config.py # 环境变量 + .env 自动加载（python-dotenv）
│ ├── events.py # SSE 发布/订阅（线程安全）
│ ├── watcher.py # 监视狗文件监视器
│ ├── stamp.py # __OVK_*__ 令牌盖章
│ ├── templates.py # 幻灯片模板目录读取器（lint 保护）
│ ├── assets.py # 媒体资产存储（内容寻址，项目隔离）
│ ├── seed.py # 固定项目
│ ├── chats.py # JSONL 聊天持久性（参见 docs/chat.md）
│ ├── cli.py # `ovk serve` + `ovk llm test` + `ovk llm free` （Typer）
│ ├── mcp/ # MCP 服务器，用于外部 AI 代理（参见 docs/mcp.md）
│ │ ├── apply_op.py # 纯 EditOp 减少器（ovk-web applyOp.ts 端口）
│ │ ├── persist.py # 执行调用：折叠操作 + store.update_project + TTS
│ │ └── server.py # FastMCP 服务器，在 /mcp/ 处封装 29 个工具
│ └── ai/ # LangGraph 代理（参见 docs/ai.md）
│ ├── config.py # OPENAI_BASE_URL / OPENAI_API_KEY / OVK_AI_MODEL
│ ├── ops.py # EditOp 镜像 ovk-web ops.ts
│ ├── graph.py # create_agent ReAct 循环
│ ├── server.py # run_agent → SSE 流
│ ├── prompts/ # 模块化 .py 提示部分（按固定顺序组装）
│ ├── tools/ # 只读 + OVK EditOp 发射器工具（参见 src/openvideokit/ai/tools/）
│ └── monitor/ # AI 可观察性 - 文件式每运行跟踪转储（参见 docs/ai-monitoring.md）
├── ovk-web/ # React SPA
├── templates/slides/ovk/ #精选的幻灯片布局模板（ovk/ovk-data/ovk-type/ovk-draw 中有 25 个）- 参见 docs/templates.md
├── tests/ # Python 单元测试（pytest）- 包括 tests/security/
├── scripts/ # dev.sh, test-e2e.py, test-mcp.py, migrate_assets.py, gc_assets.py
├── docs/ # mcp.md + ai.md + assets.md + templates.md + animation.md + security/ + web/ + rfc/
└── legacy/ # 冻结的 MVP（未导入）
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器