内容
# 导演台
**一个本地的 AI 短片「导演台 / 台账」——管创作结构和搬文件杂活，真正烧 GPU 的生成外包给你已经在用的网页生视频平台（即梦 / Seedance / Kling …）。**
<!--
📸 截图占位
把一张干净的界面截图放到：docs/screenshot.png
· 截之前请清空/改掉「监听下载夹」那栏和「平台网址」那栏，别把真实路径/网址截进去
· 用演示项目或中性内容即可
放好后下面这张图就会自动显示，建议宽度 ~1400px。
-->
---
## 两条铁律（整个设计的出发点）
1. **绝不做生成。** 不接任何生视频 / LLM API，生成永远是网页平台的活。
2. **绝不自动化浏览器。** 只用 `shell.openExternal` 打开**系统默认浏览器**（保留你的登录态和代理链），不做点击 / 填表 / 抓网页；App 只碰**你下载夹里已经落地的文件**。
下面所有功能都是这两条的延伸。
---
## 核心特性
- **无限画布 · 层级时间线** —— `整片 → 场 → 镜头`，基于 [tldraw](https://tldraw.dev)。场和镜头卡都是**自由摆放**（拖到哪停哪，不弹回）；场序按纵向位置、镜序按横向位置自动推导。
- **结构化镜头卡** —— 每个镜头带 8 个分镜元素（时长 / 景别 / 构图 / 机位 / 运镜 / 内容 / 音效 / 台词）、生视频 **prompt**、`@` 资产引用、以及生成回来的视频变体。
- **状态机 + 过期检测** —— 每个镜头自动推导状态（`空 → 已拟 → 已拍 → 已定`）。改了 prompt 但挂着的视频比这次改动更旧，镜头就打 **⚠️ 过期**。
- **主链路：待命 → 抓取** —— 点镜头上的**生成**：把 prompt 复制到剪贴板、把镜头标记为「待命」（**不会**自动打开任何东西）。你去平台粘贴生成、下载，文件监听（[chokidar](https://github.com/paulmillr/chokidar)）抓到新视频，自动挂到待命镜头上作为一个变体。音频进**声音架**；没镜头待命时抓到的视频进 **inbox**。
- **非破坏** —— 抓到的文件**复制**进项目的 `media/` 夹，下载夹原件绝不移动或删除；撤销只摘掉变体并删掉那份复制。
- **按序预览** —— 按 场序 → 镜序 连续播放各镜头的定稿变体。（真正的拼接 / 导出是后续项。）
- **画布全屏** —— 一个切换按钮（或 `⌘\`）收起左右侧栏让画布铺满窗口，状态关重开还记得。
- **给 AI 的第二张脸** —— 一个本地 MCP server，让 AI 客户端读写同一套项目数据，且每一次写入都要经过**预览 + 确认**关卡（见下）。
---
## 架构 —— 一个内核，两张脸
把**内核**（数据 + 规则 + 文件路由决策）跟界面彻底分开。GUI 只是内核的第一个消费者，MCP server 是第二个——两者复用同一个内核，业务逻辑一行不重写。
```
src/core/ 纯逻辑（TypeScript，不依赖 Electron / DOM）：
数据模型、状态机、过期计算、watcher 路由决策
src/services/ 两张脸共用的编排（文件吸入、MCP 工具实现）：
纯函数 + 注入副作用，不碰 Electron / fs / React
src/main/ Electron 主进程：chokidar 监听、文件复制、剪贴板、
shell.openExternal、MCP socket 桥
src/renderer/ 第一张脸 —— React 界面：tldraw 画布、镜头卡、侧栏、提案卡
src/mcp/ 第二张脸 —— 本地 stdio MCP server（内核的薄适配器）
src/shared/ 共享类型
```
- **第一张脸 · GUI**：Electron / React 应用。
- **第二张脸 · MCP**：一个 stdio server，把工具调用经本地 unix socket 转发给**正在运行的 App**——数据以 App 为唯一真相，写操作绝不绕过你在屏幕上的确认。
项目数据存在**仓库之外**，在 `~/DirectorDesk/<项目名>/`，形式是 `project.json` + 一个 `media/` 夹（小到可以塞进 git 存档）。
---
## 安装 / 运行
**平台：** macOS。（MCP 桥用了 `~/Library/Application Support/` 下的 unix socket，打包目标也是 macOS `.app`。）
**依赖：** Node.js 18+ 与 npm。
```bash
git clone <本仓库地址> ~/director-desk
cd ~/director-desk
npm install
# 开发（热更新）
npm run dev
# 跑测试（纯内核 / services / 画布布局）
npm test
# 打包成可双击的 macOS 应用，产物在 release/mac-arm64/
npm run dist
```
打包后把 `release/mac-arm64/` 里的应用拖进「应用程序」即可双击使用。打包细节（图标、app 名锁定等）见 [docs/BUILD.md](docs/BUILD.md)。
项目在 `~/DirectorDesk/` 下创建和保存；App 启动时自动重开上次的项目。
---
## MCP —— 让 AI 客户端来驱动导演台
一个本地 **stdio** MCP server，暴露 **16 把工具**（6 读 / 10 写）。读工具随便调；**每一把写工具都会在 App 里弹出一张提案卡，你点 ✅ 才真正写入**——点 ✗ 驳回则什么都不动。每次确认执行前还会先给 `project.json` 存一份快照，一键可退回。
工具覆盖：列/读镜头与场、揪出过期镜头、资产反查、看 inbox；以及（需确认）建场 / 建镜头、改 prompt / 元素、绑资产、移动镜头、归置媒体、选定稿、填构思板文本框。
按设计，MCP server **不**暴露生成、浏览器自动化、文件抓取、破坏性文件操作——这些留给你的手或自动 watcher。
👉 完整工具清单、注册片段、传输设计：**[docs/MCP.md](docs/MCP.md)**。
---
## 技术栈
Electron 31 · React 18 · TypeScript · [tldraw](https://tldraw.dev) 5（画布）· [chokidar](https://github.com/paulmillr/chokidar)（监听）· [zustand](https://github.com/pmndrs/zustand)（界面状态）· [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) · electron-builder（打包）。
## 现状
早期 / 个人工具阶段（`v0.1`）。主链路（画布 + 待命 + 文件抓取 + 持久化）和 MCP 第二张脸都能跑通。还没做：完整的构思板、完整的资产系统、成片拼接 / 导出。
## 授权与依赖说明
- **本项目自身采用 MIT 许可**（MIT © yyhuiru091005-cmyk，见 [LICENSE](LICENSE)）。但该许可**仅覆盖本项目自己的代码**，不覆盖 tldraw 等第三方依赖各自的条款。
- **画布功能基于开源库 [tldraw](https://tldraw.dev)**，它采用 tldraw 自家的授权（并非 MIT）。本项目当前使用其**免费授权**（免费档在画布上带有 "Get a license for production" 水印）。
- **本项目仅供个人使用与学习交流。** 如需**商业用途**，请自行前往 [tldraw 官网](https://tldraw.dev)购买相应授权；tldraw 及其它第三方依赖的授权义务由使用者自行承担。
