# JianYing Bridge

安全地把一个紧凑的 JSON 剪辑计划编译成**可继续编辑的剪映专业版草稿**。

A local Codex plugin and MCP server that compiles one compact JSON edit plan into a new, editable JianYing Pro draft.

> 非剪映官方项目。当前实机验证环境：macOS + 剪映专业版 11.4.2。

## 为什么做它

很多剪映自动化项目仍输出旧版 `draft_content.json`，或直接修改用户已有工程。JianYing Bridge 选择了更保守的边界：

- 只创建新草稿，不覆盖、删除或修补现有草稿；
- 先在沙盒生成并校验，再显式发布到剪映草稿库；
- 视频、音频会复制进草稿自身，降低 macOS 权限和源文件移动导致的丢失风险；
- 一次提交完整 manifest，避免“一个片段一次工具调用”的高频往返；
- 全程使用本地素材和本机工具，本身不消耗图片/视频生成额度。

## 已验证能力

- 剪映专业版 11.4.2（macOS）可发现并打开生成的草稿；
- 视频、BGM、中文字幕可正常进入时间线并播放；
- 剪映打开后会将草稿迁移为原生 `Timelines/project.json` 布局；
- 同名工程会被拒绝，绝不静默覆盖；
- MCP stdio 初始化、工具发现和调用通过；
- 5 项本地回归测试通过。

## MCP 工具

| 工具 | 用途 |
| --- | --- |
| `jianying_doctor` | 检查剪映、草稿目录、FFmpeg 和安全边界 |
| `jianying_build_project` | 在沙盒目录新建可编辑草稿 |
| `jianying_validate_project` | 检查项目身份、时间线和本地素材引用 |
| `jianying_publish_project` | 将已校验的新草稿复制到剪映项目库 |

## 快速开始

依赖：macOS、剪映专业版 11.4.x、Python 3.11+、[`uv`](https://docs.astral.sh/uv/)、FFmpeg/FFprobe。

```bash
git clone https://github.com/DeathKnight88/jianying-bridge.git
cd jianying-bridge
./scripts/launch_jianying_bridge
```

若作为 Codex 插件使用，可把仓库目录注册为本地插件源；`.mcp.json` 已配置好 stdio 服务入口。新安装的插件需要在新的 Codex 任务中加载。

## Manifest 示例

```json
{
  "version": 1,
  "project": {
    "name": "My_New_Project",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "video": [
    {
      "path": "/absolute/path/clip.mp4",
      "start": 0,
      "source_start": 0,
      "duration": 3,
      "track": "VideoTrack",
      "transition": {"name": "叠化", "duration": 0.3}
    }
  ],
  "audio": [
    {
      "path": "/absolute/path/music.mp3",
      "start": 0,
      "duration": 3,
      "track": "BGM",
      "volume": 0.2
    }
  ],
  "text": [
    {
      "content": "字幕",
      "start": 0,
      "duration": 3,
      "track": "Subtitles"
    }
  ]
}
```

时间单位统一为秒。相对素材路径以 manifest 所在目录为基准。完整模板见 [`assets/example-manifest.json`](assets/example-manifest.json)。

## 推荐工作流

```text
本地素材
  → FFprobe / Whisper / BaoCut / auto-editor（可选）
  → 一份 edit manifest
  → JianYing Bridge 沙盒生成 + 校验
  → 发布到剪映
  → 人工预览与导出
```

桥接器只负责执行已经确定的剪辑计划。转写、脚本判断、镜头选择等工作建议在生成 manifest 前一次性完成。

## 当前限制

- v0.1 仅支持**新建草稿**，不编辑剪映 11.x 已有加密工程；
- 发布时要求剪映主进程关闭，避免项目索引并发写入；
- 最终预览和导出仍需在剪映中完成；
- 当前只在 macOS 剪映专业版 11.4.2 做过端到端验证；Windows 和其他版本欢迎测试反馈；
- 剪映内部格式属于非公开实现，版本升级可能导致兼容性变化。

## 开发与验证

```bash
uv run --with pytest pytest -q tests
uv run --with pyyaml python /path/to/plugin-creator/scripts/validate_plugin.py .
```

## 第三方代码

运行时包含经过固定版本的 [`luoluoluo22/jianying-editor-skill`](https://github.com/luoluoluo22/jianying-editor-skill) 与其内嵌的 [`pyJianYingDraft`](https://github.com/GuanYixuan/pyJianYingDraft)。许可证和修改说明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。

## License

项目自身代码使用 MIT License。第三方代码继续遵循各自的 MIT 或 Apache-2.0 许可证。

“剪映”及相关商标归其权利人所有。本项目与字节跳动或剪映官方无隶属、授权或背书关系。