内容
# SkyCut
本地优先的MCP服务器（stdio，TypeScript），可将原始无人机拍摄的素材文件夹转化为精致的营销剪辑，通过Claude Code或Claude Desktop以对话方式驱动：
**扫描 → 分析（视觉）→ 素材图 → 建议剪辑 → 人工审批 → 渲染**
将原始无人机视频的USB驱动器指向该程序，即可生成60-90秒的营销剪辑，包含淡入淡出和可选的音乐背景。源驱动器被视为**只读**；所有派生工件（代理，帧，时间线，渲染）都存放在内部磁盘的`~/SkyCut/projects/<slug>/`中。
## 要求
- **Node 20+**
- **ffmpeg + ffprobe** — `brew install ffmpeg` （Apple Silicon videotoolbox硬件编码器用于所有渲染）
- **`ANTHROPIC_API_KEY`** — 用于视觉分析和剪辑建议
## 安装
```bash
npm install
npm run build
```
### Claude Code
```bash
claude mcp add skycut --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY -- node /绝对路径/to/skycut/dist/index.js
```
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"skycut": {
"command": "node",
"args": ["/绝对路径/to/skycut/dist/index.js"],
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}
```
### 使用MCP Inspector验证
```bash
npm run inspector
```
## 工作流程
与Claude进行普通对话的典型会话：
1. `skycut_list_volumes()` — 查找USB驱动器
2. `skycut_init_project("/Volumes/DJI/lodge-trip")` — 创建工作空间
3. `skycut_scan_footage()` — 索引剪辑，生成720p代理（幂等；之后可以拔掉驱动器）
4. `skycut_analyze_footage()` — Claude视觉评分每4秒关键帧到可搜索的素材图（缓存；询问后运行超过500帧）
5. `skycut_propose_cut("电影化90秒营销剪辑，缓慢构建，在黄金时段展示小屋", 90)` — AI导演组装时间线v1
6. `skycut_render_preview()` — 从代理快速渲染720p；观看
7. `skycut_apply_timeline_edit({ edits: [...] })` — 修订；每次编辑都是新的不可变版本
8. `skycut_render_final(2)` — 从原始素材全质量HEVC渲染（必须挂载驱动器）
使用 `skycut_search_moments({ subject: "小屋", min_aesthetic: 7 })` 和 `skycut_project_status()` 在中间进行探索。
## 工具
| 工具 | 用途 |
|---|---|
| `skycut_health()` | 依赖状态（ffmpeg，编码器，API密钥） |
| `skycut_list_volumes()` | 已挂载的具有空闲空间的卷 |
| `skycut_init_project(source_path, name?)` | 创建/重新打开项目；源是只读的 |
| `skycut_scan_footage()` | ffprobe元数据 + 清单 + SQLite + 720p代理 |
| `skycut_analyze_footage(force?, confirm?)` | 视觉分析 → 评分片段（素材图） |
| `skycut_search_moments(filters)` | 按主题/运动/质量/评分/文本查询片段 |
| `skycut_propose_cut(brief, duration_s, style?, music_path?)` | AI导演 → 验证的时间线版本 |
| `skycut_get_timeline(version?)` | 时间线JSON + 镜头列表 |
| `skycut_apply_timeline_edit(edits \| timeline)` | 结构化差异 → 新的不可变版本 |
| `skycut_render_preview(version?)` | 720p来自代理 |
| `skycut_render_final(version)` | 高达4K的HEVC来自原始素材；需要明确的版本 |
| `skycut_project_status()` | 管道状态 + 驱动器安装检查 |
## 安全防护
- USB源永远不会被写入；中途拔出会优雅地降级（代理保持预览工作）
- 时间线版本是不可变的 — 编辑始终创建`v<N+1>`
- 永远不会自动完成：`skycut_render_final`需要明确的版本
- 每个ffmpeg命令都会记录到项目的`logs/ffmpeg.log`
- 需要超过500帧的视觉运行会报告估计的成本并等待确认
## 开发
```bash
npm run build # tsc
npm test # vitest — 视觉/导演模拟；ffmpeg集成使用生成的testsrc剪辑
npm run inspector # 交互式探测服务器
```
## 文档
- **[docs/README.md](docs/README.md)** — 架构，设计决策，工作空间布局，故障排除，扩展
- **[docs/TOOLS.md](docs/TOOLS.md)** — 完整的工具API参考，时间线模式，编辑操作，错误约定
- **[CHANGELOG.md](CHANGELOG.md)** — 版本历史
- `prompt_plan.md` （原始规范）和 `progress.md` （每个阶段的构建历史）
