<div align="center">
# 鲲鹏导演台 · Kunpeng Director
**让导演和 AI Agent 在同一套 3D 白模预演工程中完成调度、动作、运镜与导出。**<br>
**A local-first 3D previs stage where directors and AI Agents share the same blocking, performance, camera and export workflow.**
[](LICENSE)
[](package.json)
[](plugins/kunpeng-director)
[](#privacy-and-reliability)
[中文](#中文) · [English](#english) · [Architecture](docs/architecture.md) · [Contributing](CONTRIBUTING.md)
</div>
---
<a id="中文"></a>
## 中文
### 这是什么
鲲鹏导演台是一套面向导演、分镜师、AI 短片创作者和编程 Agent 的开源 3D 白模预演工具。它不只是一个可视化舞台，也是一套可以被 Codex、Claude Code 等 Agent 精确操作的导演工程模型。
传统 AI 很会“说镜头”，却很难真正操作镜头：人物是谁、第几帧开始移动、摄影机看向哪里、哪一次人工修改不能再被 AI 覆盖，往往没有结构化答案。鲲鹏导演台将这些信息全部变成稳定 ID、24fps 帧、关键帧、路径、锁定和可撤销命令，让人和 Agent 真正在同一个工程中协作。
### 为什么做它
- **比文字分镜更具体：** 在生成正式分镜或 AI 视频前，先验证景别、站位、动作、轴线、节奏和运镜。
- **比传统 3D 软件更轻：** 不需要建模和复杂绑定，使用白模、灰模道具和动作模板快速完成预演。
- **比纯 Agent 工作流更可控：** Agent 必须读取真实工程 ID，遵守人工锁定，每一步都可验证、可撤销。
- **比一次性 AI 生成更可复用：** 人物、动作、摄影机和时间轴都是可编辑数据，而不是只能接受或推翻的结果。
### 核心能力
| 能力 | 说明 |
| --- | --- |
| 人物与道具 | 支持人物、儿童、动物、群众和灰模道具；每个对象都有稳定 ID、名称和身份颜色 |
| 人物表演 | 56 类可编辑动作模板、姿势预设、表演风格、关节精调和动作强度 |
| 调度与路径 | 人物位置、朝向、缩放、24fps 动作关键帧、插值方式和可拖拽贝塞尔路径 |
| 摄影机 | 28 类专业运镜模板，支持任意摄影机关键帧、位置、注视点、视场角和滚转角 |
| 专业时间轴 | 分镜轨、摄影机轨、人物动作轨、逐帧定位、导出入点/出点和任意位置播放 |
| 人工编排 | 在 3D 舞台中直接移动、旋转、缩放；修改人物姿势和关键帧；锁定已确认结果 |
| Agent 操作 | 15 个 MCP 工具覆盖读取、添加、编辑、K 帧、运镜、分镜管理、锁定、删除、撤销和验证 |
| 人机协作 | 导演助手对话抽屉可读取完整工程后执行命令；人工锁定内容不会被 Agent 静默覆盖 |
| 检查与历史 | 检查碰撞、动作重叠、路径连续性、越界和机位问题；支持 50 步撤销/重做 |
| 导出 | 当前帧 PNG，以及可自定义范围的 1080p、24fps、H.264 MP4；可选人物标签和输出文件夹 |
| 双语界面 | 默认中文，可切换英文 |
### 人和 Agent 如何协作
```mermaid
flowchart LR
Prompt["导演意图 / Directing intent"] --> Agent["Codex / Claude Code"]
Agent -->|MCP 命令| Service["导演命令服务"]
Human["人工可视化调整"] -->|HTTP localhost| Service
Service --> Project["同一套工程 ID、帧与锁定"]
Project --> Stage["Three.js 白模舞台"]
Project --> Validate["校验、撤销、导出"]
```
1. Agent 先调用 `director_get_state`，读取真实人物、分镜、动作和关键帧 ID。
2. Agent 根据导演意图提出调度方案，再以 24fps 整数帧写入动作与摄影机。
3. 用户可在舞台、属性面板和时间轴中继续精调，并将满意的结果锁定。
4. Agent 再次操作时必须保留人工锁定；完成后运行 `director_validate`。
5. 通过后可导出任意画面截图，或按时间轴入点/出点渲染 MP4。
### 适合谁
- 在正式拍摄前验证人物走位、轴线和运镜的导演与摄影师
- 需要将文字脚本快速转成可视化动作预演的分镜师
- 在生成 AI 分镜或视频前，希望先固定站位、节奏和镜头路径的 AI 影像创作者
- 需要一个结构化、可撤销、可验证的 3D 工具来测试 Agent 操作能力的开发者
### 快速开始
**环境要求：** Node.js 20 或更高版本，npm 10 或更高版本。MP4 导出需要 FFmpeg。
```bash
git clone https://github.com/pengfeiqiao/kunpeng-director.git
cd kunpeng-director
npm install
npm run build
```
本地开发时，在两个终端分别运行：
```bash
npm run server
npm run dev
```
打开 [http://127.0.0.1:5173](http://127.0.0.1:5173)。HTTP/MCP 服务只监听 `127.0.0.1:4318`。
生成内置完整 Web 舞台的可携带插件：
```bash
npm run plugin
node plugins/kunpeng-director/dist/mcp-server.js --http 4318
```
然后打开 [http://127.0.0.1:4318](http://127.0.0.1:4318)。
### 连接 Codex、Claude Code 或其他 MCP 客户端
`plugins/kunpeng-director` 已包含 Codex 和 Claude Code 插件清单、Agent Skill 与打包后的 MCP 服务。任意支持 stdio MCP 的客户端也可使用以下配置：
```json
{
"mcpServers": {
"kunpeng-director": {
"command": "node",
"args": ["/absolute/path/to/plugins/kunpeng-director/dist/mcp-server.js"]
}
}
}
```
可以这样向 Agent 提出需求：
> 先读取当前导演台工程。让两个人物在 8 秒内从画面两侧靠近并拥抱，设计自然的表演节拍和电影感运镜，保留所有人工锁定的关键帧，完成后检查工程。
### 本地数据、隐私与导出可靠性
- 默认工程保存在 `~/.kunpeng-director`，可通过 `KUNPENG_DIRECTOR_HOME` 更改。
- Core 舞台和 MCP 工具完全在本地运行，没有遥测，不上传工程。
- 可选的应用内导演助手使用本机已登录的 Codex CLI。
- JSON 工程通过临时文件原子替换写入，历史最多保留 50 个完整快照。
- MP4 导出使用 FFmpeg 编码，再通过 FFprobe 检查编码、尺寸和帧率，避免将损坏文件当成成片。
### 仓库结构
```text
apps/web/ React + Three.js 可视化导演台
packages/core/ 可序列化工程、动作/运镜模板、帧评估器
packages/mcp-server/ MCP 工具、本地存储、HTTP 桥接和渲染任务
plugins/kunpeng-director/ Codex 与 Claude Code 插件包
docs/ 架构和发布文档
```
### 开发与贡献
提交 PR 前请运行：
```bash
npm run check
```
请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [docs/architecture.md](docs/architecture.md)。项目使用 [MIT License](LICENSE)。
---
<a id="english"></a>
## English
### What is Kunpeng Director?
Kunpeng Director is an open-source 3D previs tool for directors, storyboard artists, AI filmmakers and coding Agents. It is both a visual blocking stage and a structured directing model that Codex, Claude Code and other MCP-capable Agents can operate precisely.
Most AI systems can describe a shot, but they cannot reliably operate one. They lose track of actor identity, exact timing, camera targets and which human decisions must remain untouched. Kunpeng Director turns those decisions into stable IDs, integer frames at 24fps, editable keyframes, motion paths, locks and reversible commands. Humans and Agents work on the same project instead of exchanging disposable text instructions.
### Why it exists
- **More concrete than a written shot list:** validate shot size, blocking, performance, screen direction, rhythm and camera movement before producing final storyboards or video.
- **Lighter than a traditional DCC:** build previs quickly with mannequins, greybox props and motion templates instead of modelling and rigging every asset.
- **More controllable than a prompt-only Agent:** Agents must read real project IDs, respect human locks and produce edits that can be validated and undone.
- **More reusable than one-shot generation:** actors, actions, cameras and timing remain editable project data rather than an all-or-nothing result.
### Core capabilities
| Capability | What it provides |
| --- | --- |
| Actors and props | People, children, animals, crowds and greybox props with stable IDs, visible names and identity colours |
| Performance | 56 editable motion templates, pose presets, performance profiles, joint controls and motion intensity |
| Blocking and paths | Position, orientation, scale, 24fps motion keyframes, interpolation modes and draggable Bezier handles |
| Camera | 28 professional camera templates plus arbitrary camera keyframes, position, target, FOV and roll |
| Professional timeline | Shot, camera and actor tracks, frame-accurate seeking, in/out ranges and playback from any position |
| Manual editing | Move, rotate and scale directly in the 3D stage; refine poses and keyframes; lock approved work |
| Agent control | 15 MCP tools for state, elements, actions, keyframes, cameras, shots, locks, deletion, history and validation |
| Human-Agent collaboration | The Director Agent reads the complete project before editing; human locks cannot be silently overwritten |
| Validation and history | Collision, overlap, path-continuity, range and camera checks, with up to 50 undo/redo snapshots |
| Export | Current-frame PNG and ranged 1080p, 24fps H.264 MP4 with optional actor labels and output directory |
| Bilingual UI | Chinese by default, with an English interface option |
### Human and Agent workflow
1. The Agent calls `director_get_state` before editing and reads the exact actor, shot, action and keyframe IDs.
2. It translates the directing intent into integer-frame action and camera edits at 24fps.
3. The director refines the result in the stage, inspectors and timeline, then locks approved decisions.
4. Later Agent passes must preserve those locks and finish by running `director_validate`.
5. The approved previs can be exported as any still frame or as an MP4 over the selected timeline in/out range.
### Who it is for
- Directors and cinematographers validating blocking, screen direction and camera movement before production
- Storyboard artists turning written scenes into visible motion previs
- AI filmmakers fixing staging, rhythm and camera paths before generating final images or video
- Agent developers who need a structured, reversible and testable 3D editing harness
### Quick start
**Requirements:** Node.js 20 or newer and npm 10 or newer. FFmpeg is required for MP4 export.
```bash
git clone https://github.com/pengfeiqiao/kunpeng-director.git
cd kunpeng-director
npm install
npm run build
```
For local development, run the following commands in separate terminals:
```bash
npm run server
npm run dev
```
Open [http://127.0.0.1:5173](http://127.0.0.1:5173). The HTTP/MCP service listens only on `127.0.0.1:4318`.
To create a portable plugin bundle with the visual stage embedded:
```bash
npm run plugin
node plugins/kunpeng-director/dist/mcp-server.js --http 4318
```
Then open [http://127.0.0.1:4318](http://127.0.0.1:4318).
### Connect Codex, Claude Code or another MCP client
`plugins/kunpeng-director` contains Codex and Claude Code manifests, the Agent skill and the bundled MCP server. Any client that supports stdio MCP can use the following configuration:
```json
{
"mcpServers": {
"kunpeng-director": {
"command": "node",
"args": ["/absolute/path/to/plugins/kunpeng-director/dist/mcp-server.js"]
}
}
}
```
Example Agent request:
> Read the current Director project first. Stage the two actors approaching from opposite sides and embracing within eight seconds. Design a natural performance rhythm and a cinematic camera move, preserve every manually locked keyframe, then validate the project.
<a id="privacy-and-reliability"></a>
### Privacy, storage and export reliability
- Projects are stored in `~/.kunpeng-director` by default. Override the location with `KUNPENG_DIRECTOR_HOME`.
- The core stage and MCP tools run locally, contain no telemetry and do not upload project data.
- The optional in-app Director Agent uses the locally authenticated Codex CLI.
- Project JSON is written through atomic temporary-file replacement, with up to 50 complete history snapshots.
- MP4 export is encoded with FFmpeg and validated through FFprobe for codec, dimensions and frame rate before finalization.
### Repository layout
```text
apps/web/ React + Three.js visual Director stage
packages/core/ Serializable project, templates and frame evaluator
packages/mcp-server/ MCP tools, local storage, HTTP bridge and render jobs
plugins/kunpeng-director/ Codex and Claude Code plugin bundle
docs/ Architecture and publication notes
```
### Development and contributing
Run the complete check before opening a pull request:
```bash
npm run check
```
See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and [docs/architecture.md](docs/architecture.md). Licensed under the [MIT License](LICENSE).