内容
# 动态图表
由智能代理驱动的动态图表渲染器。将 API/流程/架构描述转换为 **动态 MP4**（发光脉冲遍历边缘，节点弹出，相机聚焦，8 位音效）或 **Instagram 风格的轮播**（静默 GIF + WebP 幻灯片）。
为内容创作者打造。通过 **MCP** 驱动设计场景，该工具进行渲染。
## 技术栈
- Remotion（React → MP4 通过无头 Chrome + ffmpeg）
- dagre（自动布局）
- ffmpeg（音效合成，GIF→WebP）
- MCP SDK（智能代理接口）
## 安装
```bash
# 一次性安装，无需全局安装
npx motion-diagram render examples/login-flow.json -- --out login.mp4
# 或全局安装
npm install -g motion-diagram
# 或从克隆仓库安装
npm install
```
检查前提条件（Node >=18，ffmpeg，依赖项）：
```bash
npx motion-diagram doctor
```
首次渲染下载无头 Chrome（~一次）。完整指南：`docs/INSTALL.md`。
## 命令行界面
```bash
# 视频（MP4 + 音效）
npm run render examples/login-flow.json -- --out output/login-flow.mp4
# 轮播（GIF + WebP 按节点组）
npm run render examples/login-flow.json -- --mode carousel --out output/login-carousel
# 直播预览工作室
npm run studio
```
## 场景 JSON
智能代理发出节点、边缘和时间线。参见 `docs/SCHEMA.md`。
```jsonc
{
"meta": { "title": "登录流程", "fps": 30, "width": 1920, "height": 1080 },
"nodes": [
{ "id": "client", "label": "客户端", "shape": "rect", "icon": "user" },
{ "id": "api", "label": "API", "shape": "rect", "icon": "server" },
{ "id": "db", "label": "数据库", "shape": "stadium", "icon": "database" },
],
"edges": [
{ "id": "e1", "from": "client", "to": "api", "label": "POST /login" },
{ "id": "e2", "from": "api", "to": "db", "label": "查询" },
],
"timeline": [
{ "at": 0, "type": "reveal-node", "target": "client" },
{ "at": 8, "type": "reveal-node", "target": "api" },
{ "at": 16, "type": "reveal-node", "target": "db" },
{ "at": 24, "type": "reveal-edge", "target": "e1" },
{ "at": 42, "type": "reveal-edge", "target": "e2" },
{
"at": 60,
"type": "pulse",
"edge": "e1",
"color": "#38bdf8",
"onArrive": { "flash": true, "sfx": "beep" },
},
{
"at": 95,
"type": "pulse",
"edge": "e2",
"color": "#34d399",
"onArrive": { "flash": true, "sfx": "ding" },
},
],
}
```
## 动态基元
| 类型 | 效果 |
| ------------- | --------------------------------------------------- |
| `reveal-node` | 节点弹出（弹簧缩放 + 淡入） |
| `reveal-edge` | 边缘绘制像笔 |
| `pulse` | 发光彗星遍历边缘（数据流），多色 |
| `flash` | 节点发光爆发 |
| `camera` | 平移/缩放聚焦到节点 |
## 音效
`public/sfx/` 中捆绑的 8 位音效：`beep`，`whoosh`，`ding`。由智能代理按事件选择（`sfx` / `onArrive.sfx`），或 `none`。交换 WAV 文件以重新品牌。
## 图标
`user client server api database cloud queue cache lock key gear bolt globe mobile mail file check cross warning`
## MCP + 技能安装（适用于 AI 智能代理）
动态图表设计为通过 MCP 由 AI 智能代理驱动。使用一条命令将技能安装到您的智能代理中：
```bash
# 自动检测已安装的智能代理并注册 MCP 服务器
npx motion-diagram install-skill
# 或针对特定客户端
npx motion-diagram install-skill --client cursor
npx motion-diagram install-skill --client claude
npx motion-diagram install-skill --client pi
```
这会在每个智能代理的 MCP 配置中写入一个 `motion-diagram` 条目：
| 智能代理 | 配置文件 |
| -------------- | ---------------------------------------------- |
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop | `claude_desktop_config.json`（OS 特定目录） |
| Pi | `~/.pi/agent/mcp.json` |
安装 npm 包也会自动运行此操作（`postinstall`），因此普通的 `npm install -g motion-diagram` 会为任何检测到的智能代理注册技能。之后重启您的智能代理以加载工具。
### 手动配置
任何 MCP 客户端都可以使用 — 指向 `motion-diagram-mcp` 命令：
```json
{
"mcpServers": {
"motion-diagram": {
"command": "npx",
"args": ["-y", "motion-diagram-mcp"]
}
}
}
```
直接运行服务器进行调试：
```bash
npx motion-diagram-mcp # 或，从克隆仓库：npm run mcp
```
工具：
- `get_scene_schema` — 调用首先，返回创作合约
- `render_motion_diagram` — 场景 → MP4
- `render_carousel` — 场景 → GIF/WebP 幻灯片（按节点 `group`）
智能代理指南：`docs/AGENT_SKILL.md`。贡献：`CONTRIBUTING.md`。
## 项目布局
```
src/core/ 解析器，布局（dagre），时间线标准化
src/scenes/ Remotion 组件（节点，边缘，脉冲，合成，根）
src/render/ MP4 + 轮播渲染编排
src/cli/ 命令行界面入口
src/mcp/ MCP 服务器
public/sfx/ 捆绑的 8 位音效
docs/ 规格，模式，智能代理技能
examples/ 示例场景
```
