## 项目概述

html-video 是 nexu-io 旗下 Open Design 团队发布的 Apache-2.0 开源项目，定位为“面向编码智能体的程序化视频工具”：在本地把 HTML、CSS 与数据变成真实 MP4。用户可以用自然语言描述视频、粘贴文章链接或 GitHub 仓库，由本地 coding agent 生成多帧故事板与逐帧动画 HTML，再通过可插拔渲染引擎输出 MP4。项目当前已内置 Hyperframes 引擎（无头 Chromium 录制 + ffmpeg 编码），提供 21 个模板和可选 AI 配乐/旁白，无按渲染次数收费、无供应商锁定。

## 核心功能

- 编码智能体驱动：支持 Open Design (Vela)、Windsurf CLI、Trae CLI、Claude Code、Cursor Agent、Codex CLI、Gemini CLI、Grok Build、Qwen Code、OpenCode、GitHub Copilot CLI、Aider、Hermes、Anthropic Messages API 等 14 种后端，自动检测 PATH 并可在 Studio 顶栏切换。
- 链接/仓库转视频：粘贴网页文章（含微信公众账号文章）或 GitHub 仓库链接，服务端抓取并扁平化为 Markdown，再交给 agent 生成视频。
- 真实 MP4 本地渲染：无头 Chromium 逐帧录制动画 HTML 为 WebM，ffmpeg 以 libx264 编码并拼接为 MP4。
- 21 个模板：涵盖数据可视化、标题/VFX、Hero、电影感、产品宣传片、解释器等多种类型，模板带 `template.html-video.yaml` 清单，供 agent 自动读取输入 schema 与许可信息。
- 多帧故事板（content-graph）：以节点+边构成内容图，拓扑排序成帧顺序与时长，支持逐帧文本编辑、重排和重新渲染。
- AI 配乐与旁白：在 Studio 设置 MiniMax API Key 后，可生成背景音乐和 TTS 旁白，导出时用 ffmpeg 混入 MP4。
- 本地 Studio 与 CLI：浏览器界面工作室与 `html-video` 命令行工具（`doctor`、`search-templates` 等）。

## 适用与不适用场景

适用场景：
- 想让本地 coding agent 快速把一篇文章、一个 GitHub 仓库或一段文字描述变成解说/宣传短视频。
- 团队需要可审计、可脚本化、license-clean 的模板与本地渲染流程，避免按渲染次数付费的云服务。
- 需要程序化批量产出视频，并把 HTML/CSS/数据作为视频源。

不适用场景：
- 需要精细时间轴剪辑、多轨音频处理等专业视频编辑能力——本项目不是通用 NLE（非线性编辑器）。
- 期望立即使用 Remotion、Motion Canvas、Revideo、Manim 等其它引擎：当前只有 Hyperframes 引擎已完全可用，其余在路线图上但适配器尚未实现。
- 无法安装或使用 Node.js 20+、pnpm 9+、ffmpeg、Chromium/Playwright 的环境（例如纯浏览器在线场景，项目是本地运行）。
- 需要完全离线的 AI 音轨：AI 配乐/旁白依赖 MiniMax API，属于可选外部服务。

## 技术架构与依赖

项目是 pnpm workspace monorepo，主要目录：
- `packages/core`：Project/Asset/ContentGraph 等类型、注册表、编排器、MiniMax provider、ffmpeg 音频混流。
- `packages/content-graph`：多帧故事板 IR（节点+边，拓扑排序）。
- `packages/runtime`：agent 运行时，检测/启动/流式输出，支持 14 种 agent 后端。
- `packages/adapter-hyperframes`：Hyperframes 引擎适配器（Chromium + ffmpeg 真实渲染）。
- `packages/cli`：`html-video` 命令、Studio HTTP 服务器、来源抓取。
- `packages/project-studio`：浏览器端 Studio UI（对话、模板画廊、帧编辑、配乐、导出）。
- `templates/`：21 个精选、license-clean 模板。
- `research/`：RFC（引擎适配器、模板元数据、agent skill、content-graph 等）。

渲染管线：prompt/链接/仓库 → 来源抓取 → agent loop（生成 content-graph + 每帧 HTML）→ 内容图排序 → 逐帧 HTML → Hyperframes 通过无头 Chromium 录制 → ffmpeg 编码拼接 MP4。

依赖（仓库写明的 Prerequisites）：
- Node.js 20+
- pnpm 9+
- ffmpeg
- Chromium（或 `npx playwright install chromium`）
- 可选：MiniMax API Key（仅涉及 AI 配乐/旁白）

## 安装与快速开始

前置检查：

```bash
node --version
pnpm --version
ffmpeg -version
npx playwright install chromium
```

克隆并安装：

```bash
git clone https://github.com/nexu-io/html-video.git
cd html-video
pnpm install
pnpm -r build
```

启动 Studio：

```bash
node packages/cli/dist/bin.js studio
# 打开 http://127.0.0.1:3071
```

CLI 工具：

```bash
node packages/cli/dist/bin.js doctor
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3
```

仓库资料中未提供 npm 包名、发布渠道、Docker 镜像或云部署方式；当前安装方式以 GitHub 源码与 pnpm workspace 为准。

## 典型使用方法

1. 链接转视频：在 Studio 对话中粘贴文章或仓库 URL，例如“做一个解读视频 https://mp.weixin.qq.com/s/...”，agent 会抓取内容并生成基于真实内容的多帧解说视频。
2. 纯提示词生成：直接描述视频主题，agent 从零编写内容与故事板。
3. 模板驱动：在 Studio 模板画廊中选一个模板（如 NYT 风格数据图、故障艺术标题、液态背景 Hero），让 agent 按模板输入 schema 填内容。
4. 配乐与旁白：在 Settings → Audio 配置 MiniMax API Key，在 Soundtrack 面板描述背景音乐情绪或输入旁白脚本，导出时混入 MP4。
5. CLI 检查环境：`node packages/cli/dist/bin.js doctor` 查看已检测到的 agent 与引擎。

## 配置与部署要点

- 本地优先：所有渲染发生在自己机器上；唯一的网络调用是可选的来源抓取（如网页/仓库）和可选的 AI 音轨请求。
- Agent 配置：agent 通过 PATH 自动检测；若本机已安装多个 CLI，可在 Studio 顶栏切换；未安装任何 CLI 时可配置 Anthropic API Key 直连 Messages API。
- Studio 地址：默认 `http://127.0.0.1:3071`。
- 音频配置：MiniMax Key 仅用于可选音乐/旁白；不配置不影响其余功能。
- 模板扩展：新增模板需遵循 RFC-07 来源规范（仅允许 MIT、Apache-2.0、BSD、CC-BY、CC-BY-SA 等宽松许可，并记录三层 provenance），并放置 `template.html-video.yaml` 清单。
- 引擎扩展：新增引擎需实现 `EngineAdapter` 接口（validate/render/preview 等），并遵循进程隔离、进度报告、取消清理等 RFC-01 约定；核心会自动发现 `packages/` 下的适配器。
- 仓库资料未提供官方 Docker、Kubernetes、CI/CD 或云端托管配置，相关内容需参阅社区或后续发布。

## 限制、风险与许可证

限制：
- 当前可运行渲染引擎只有 Hyperframes；Remotion、Motion Canvas/Revideo、Manim 均在路线图中，适配器尚未发布。
- 需要本地 Chromium 与 ffmpeg；首次使用需安装 Playwright Chromium。
- HTML 模板与来源内容的许可责任由使用者承担；项目模板层面有 license gate 与 provenance 记录，但用户输入的内容仍需自行确认。
- AI 配乐/旁白依赖 MiniMax 外部服务，可能涉及网络传输与第三方条款。
- 仓库未提供最新的 release tag 或版本号，具体版本状态需以仓库为准。

许可证：
- 项目整体为 Apache-2.0（见仓库 LICENSE），无按渲染收费、无席位上限、无需 CLA。
- 仓库资料声明模板逐一记录 SPDX 与归属信息，且仅纳入宽松许可来源。

## 官方链接

- 项目主页/GitHub：https://github.com/nexu-io/html-video
- Open Design：https://github.com/nexu-io/open-design · https://open-design.ai
- Hyperframes（已内置引擎）：https://github.com/heygen-com/hyperframes
- 团队成员/社区：https://x.com/nexudotio
- Discord（README 指向 Open Design 社区）：https://github.com/nexu-io/open-design#community

## 信息来源和分析时间

信息来源：GitHub 仓库元数据、README、CONTRIBUTING.md 及其中引用的 RFC 文档路径。
分析时间：仓库抓取时未标注具体时间；本摘要中的“当前”“已发布”均以抓取到的仓库快照为准。