davinci-resolve-ai-bridge

# 开始使用：打开 `00_START_HERE.html` **为了最清晰的设置，请先打开 [`00_START_HERE.html`](./00_START_HERE.html)**。它是 macOS、Windows、Antigravity、Claude Code、Codex、Cursor 和 Remotion 的可视化逐步指南。在使用时，请保持整个文件夹在一起。 # 解析 AI 桥接 解析 AI 桥接是一个 MIT 许可的本地 MCP 桥接，允许兼容的 AI 客户端检查和控制 DaVinci Resolve 中当前打开的项目。 设计故意保持小巧： 1. `ResolveConsole.py` 在 Resolve 的 Python 3 控制台中启动，并捕获内部 Resolve API 对象。 2. 一个守护线程从 `~/.resolve-ai-bridge/inbox` 读取已认证的 JSON 作业，同时控制台保持可用。 3. `bridge/server.py` 通过 stdio 向 AI 客户端公开一组专注的 MCP 工具。 4. 回复通过 `~/.resolve-ai-bridge/outbox` 返回。 没有托管的桥接账户，也没有网络监听器。您的 AI 提供商仍可能根据其自己的隐私政策处理提示。 ## 要求 - 具有内部 Python 3 控制台的 DaVinci Resolve - 计算机上安装 Python 3.10 或更高版本 - 兼容 MCP 的客户端，如 Antigravity、Claude Code、Codex 或 Cursor - 安装期间需要互联网访问，以便 pip 可以安装 Python MCP 包 - 强烈建议使用 Node.js 当前 LTS 版本进行 Remotion 动态图形 桥接本身不需要 Node.js。Node.js 用于推荐的 Remotion 工作流程。 ## 快速设置 ### 1. 下载完整的存储库 在 GitHub 上选择 **代码**，然后选择 **下载 ZIP**，并解压它。不要只复制 `install.py`；它需要 `agent`、`bridge` 和 `skills` 文件夹位于其旁边。 您可以重命名下载的存储库文件夹。安装程序将运行时文件复制到固定位置，因此稍后的存储库重命名不会破坏控制台行。 ### 2. 运行安装程序 macOS: ```bash python3 install.py ``` Windows PowerShell: ```powershell py install.py ``` 安装程序： - 将运行时复制到 `~/.resolve-ai-bridge` - 保留或创建私有 `rab_...`令牌 - 创建 `~/.resolve-ai-bridge/.venv` - 在该虚拟环境中安装官方 Python MCP 依赖项 - 编写填充的 MCP JSON 以及精确的控制台、Claude Code 和 Codex 命令文件 - 安装包含的 Resolve 编辑技能，适用于 Claude Code 和 Codex 技能位置 它不会重写 AI 客户端现有的 MCP 设置。 ### 3. 在 Resolve 中启动代理 1. 打开 Resolve 和您要编辑的项目。 2. 打开 **工作区 > 控制台**。 3. 选择 **Py3**。 4. 粘贴安装程序打印的确切行。 macOS 形状： ```python exec(open("/Users/YOUR_NAME/.resolve-ai-bridge/ResolveConsole.py", encoding="utf-8").read()) ``` Windows 形状： ```python exec(open(r"C:\Users\YOUR_NAME\.resolve-ai-bridge\ResolveConsole.py", encoding="utf-8").read()) ``` 原始安装文件名是 **`ResolveConsole.py`**。不要重命名该安装文件。如果它被移动或重命名，请再次运行安装程序，并使用其新打印的行。 控制台应立即打印： - `RESOLVE AI BRIDGE READY` - 本地令牌 - 单服务器 MCP 对象 - 完整的 `mcpServers` JSON 块 工作线程是守护线程，因此粘贴的行返回并立即释放控制台。 要在同一个 Resolve 会话中停止它： ```python __resolve_ai_bridge_runtime__.stop() ``` ### 4. 将 MCP 服务器添加到您的 AI 客户端 使用 Resolve 打印的填充 JSON 或打开： ```text ~/.resolve-ai-bridge/mcp-config.json ``` 其形状是： ```json { "mcpServers": { "resolve-ai-bridge": { "command": "/ABSOLUTE/PATH/TO/.resolve-ai-bridge/.venv/bin/python", "args": [ "/ABSOLUTE/PATH/TO/.resolve-ai-bridge/bridge/server.py" ], "env": { "RESOLVE_AI_BRIDGE_TOKEN": "RAB_TOKEN_PRINTED_IN_RESOLVE" } } } } ``` 在 MCP 设置中不要使用 `~` 或相对路径。使用安装程序生成的绝对路径。 #### Antigravity 1. 打开代理面板。 2. 打开三点菜单并选择 **MCP 服务器**。 3. 选择 **管理 MCP 服务器**，然后选择 **查看原始配置**。 4. 将 `resolve-ai-bridge` 条目合并到现有的 `mcpServers` 对象中。 5. 保留文件中已有的每个服务器。 6. 保存，刷新 MCP 列表，并在需要时重启 Antigravity。 通过应用程序打开原始配置可以避免猜测特定 Antigravity 版本使用哪个配置路径。 #### Claude Code 安装程序和 Resolve 控制台打印一个精确的命令，可以安全地读取生成的 JSON 文件。在正常终端中运行该命令。它具有这种 macOS 形状： ```bash claude mcp add-json resolve-ai-bridge "$(cat ~/.resolve-ai-bridge/claude-server-entry.json)" --scope user ``` 在 Windows 上，使用安装程序打印的 PowerShell 命令。确切的命令也保存在 `~/.resolve-ai-bridge/claude-command.txt` 中。重启 Claude Code 并运行 `/mcp`。如果您的安装版本不支持 `add-json`，请通过其 MCP 设置合并完整 JSON。 #### Codex Resolve 控制台和安装程序都为您的安装路径和令牌打印一个精确的命令。它具有这种形状： ```bash codex mcp add resolve-ai-bridge --env RESOLVE_AI_BRIDGE_TOKEN=TOKEN -- /absolute/path/to/.venv/python /absolute/path/to/bridge/server.py ``` 在正常终端中运行填充的命令，然后使用 `codex mcp list`。相同的填充行保存在 `~/.resolve-ai-bridge/codex-command.txt` 中。Codex 应用程序和 CLI 还允许您通过 **设置 > MCP 服务器** 添加本地 STDIO 服务器。 #### Cursor 打开 **Cursor 设置**，搜索 **MCP**，选择 **添加新的全局 MCP 服务器**，并将生成的条目合并到 `mcpServers` 中。保存并启用它。 ### 5. 验证后再编辑 保持控制台代理运行，然后运行： ```bash python3 tools/doctor.py ``` 在 Windows 上： ```powershell py tools/doctor.py ``` 然后询问您的 AI： ```text 调用 resolve_status 并告诉我打开的项目和时间线。不要编辑任何内容。 ``` 对于安全的第一笔写入： ```text 检查时间线。在当前播放头添加一个名为 Bridge test 的蓝色标记，然后再次检查以验证它。 ``` ## 令牌行为 令牌是功能性的，不是装饰性的。 - 安装程序将其写入 `~/.resolve-ai-bridge/token.txt`，并在支持的位置使用受限权限。 - MCP 进程通过其环境接收相同的令牌。 - 每个作业都包含令牌。 - 代理在执行操作之前会比较令牌。 - 不匹配的请求将被拒绝。 令牌保护此本地队列免受意外或无关的本地请求的干扰。它不是互联网登录。不要提交它，发布它，或将其粘贴到公共问题中。 如果暴露，请旋转它： ```bash python3 install.py --rotate-token ``` 然后重启 Resolve 代理并替换 AI 客户端中的旧 MCP 条目。 ## MCP 工具 服务器故意暴露少于 20 个专注的工具，以便模型可以可靠地选择它们。 | 工具 | 目的 | | --- | --- | | `resolve_status` | 检查代理、Resolve、项目、时间线和令牌 ID | | `project_info` | 读取项目帧率和分辨率 | | `list_timelines` | 列出所有时间线 | | `open_timeline` | 按名称或索引选择时间线 | | `timeline_overview` | 检查轨道、标记、剪辑和稳定 ID | | `list_media` | 遍历媒体池箱 | | `import_media` | 导入绝对本地文件路径 | | `append_media` | 追加媒体 ID 或导入路径 | | `create_timeline` | 创建空时间线 | | `set_playhead` | 移动到时间码 | | `add_marker` | 添加时间线标记 | | `delete_marker` | 删除相对帧处的标记 | | `set_clip_property` | 更改支持的时间线项目属性 | | `set_clip_enabled` | 启用或禁用一个项目 | | `set_clip_color` | 设置或清除 Resolve 剪辑颜色 | | `delete_clips` | 在批准后删除选定的项目 | | `save_project` | 保存打开的项目 | | `render_current_timeline` | 在批准后排队或启动渲染 | MCP 服务器还提供 `resolve://guide` 和 `edit_video` 提示。 ## 获取更好的 AI 编辑 包含的 `resolve-ai-editing` 技能使用检查、计划、编辑、验证工作流程。安装程序将其复制到 Claude Code 和 Codex 技能文件夹，并保留一个引用副本： ```text ~/.resolve-ai-bridge/skills/resolve-ai-editing/SKILL.md ``` 以以下内容开始复杂请求： ```text 首先检查打开的项目和时间线。总结那里有什么，说明一个简短的编辑计划，并列出假设。以小步骤工作，并在每次更改后验证。在删除剪辑或启动渲染之前询问。 ``` 好的提示包括： - 目标平台和长宽比 - 期望时长 - 受众和故事目标 - 参考样式 - 什么不能改变 - 是否允许删除和渲染 技能可以提高 API 使用和规划能力。它们并不能使主观编辑质量自动化。审查时间线并使用项目备份。 ## Remotion 设置，强烈推荐 [Remotion](https://www.remotion.dev/) 使用 React 创建视频。它适用于动态图形、动画类型、解说员和 Resolve 脚本 API 不适用的设计场景。 Remotion 不控制 Resolve，也不安装在 Python 桥接中。实际工作流程是： 1. 使用编码代理和 Remotion 构建和预览设计剪辑。 2. 将剪辑渲染为本地媒体文件。 3. 通过 Resolve AI 桥接导入该文件。 4. 在追加之前询问应放置在哪里。 ### 安装 Node.js 从 [nodejs.org](https://nodejs.org/) 安装当前 LTS 版本。打开一个新的普通终端并验证： ```bash node --version npm --version ``` ### 安装官方 Remotion 技能并创建项目 在正常终端中运行，而不是 Resolve 控制台： ```bash npx -y skills@latest add remotion-dev/skills -g -y npx create-video@latest --yes --blank my-video cd my-video npm install npx remotion skills add npm run dev ``` 维护的 `remotion-dev/skills` 包教导支持的编码代理 Remotion 组成、时间、媒体和动画实践。在 `my-video` 文件夹中打开您的 AI 客户端。 示例提示： ```text 使用官方 Remotion 技能。在编码之前，提出一个 15 秒 1920x1080 的动态图形，包含三个场景。使用您的确切副本，克制排版和流畅的过渡。保持重要内容在安全边距内。构建它，运行检查，并打开 Remotion Studio，以便我在渲染之前查看。 ``` 渲染批准的合成： ```bash npx remotion render <CompositionId> out/video.mp4 ``` 然后将绝对输出路径交给您的 Resolve AI： ```text 导入 /absolute/path/to/my-video/out/video.mp4。检查当前时间线并询问我在哪里放置它，然后再追加它。 ``` 有关详细的工作流程和提示清单，请参见 `docs/REMOTION.md`。 ## 架构 ```text AI 客户端 | 通过 stdio 的 MCP v ~/.resolve-ai-bridge/bridge/server.py | 身份验证的 JSON 文件 v ~/.resolve-ai-bridge/inbox 和 outbox | v ResolveConsole.py 守护线程位于 Resolve 内部 | v 当前 Resolve 项目和时间线 ``` ## 已知边界 - Resolve 的公共脚本 API 不公开编辑页面的每个操作。 - 转换创建和任意时间线重新定位不可用，因为它们无法使用文档化的 API 表面可靠地实现。 - Resolve 内部对象的后台线程访问因 Resolve 版本而异。控制台根据设计立即返回，但实际兼容性必须在您的确切版本上验证。 - 渲染预设必须已经存在于 Resolve 中。 - 复杂的 Fusion 自动化不在此第一个简单版本中故意包含。使用 Remotion 进行设计动态，或仅在测试了真实项目后添加 Fusion 操作。 - 桥接器适用于当前打开的本地项目。它不是远程协作服务器。 ## 验证状态 - React 指令应用程序使用 Vite 构建作为存储库验证的一部分。 - `tools/doctor.py` 在检查安装之前在内存中编译每个 Python 源。 - 仍然需要一个真实的 Resolve 会话来验证注入的 API 对象和特定 Resolve 版本上的每个编辑操作。 不要将成功的网络构建解释为证明特定 Resolve API 操作在每个 Resolve 版本上都有效。 ## 存储库布局 ```text 00_START_HERE.html 视觉设置指南 README.md 完整的书面参考 install.py 跨平台安装程序 install-macos.command macOS 双击包装器 install-windows.bat Windows 双击包装器 requirements.txt Python MCP 依赖项 agent/ResolveConsole.py 内部 Resolve 控制台代理 bridge/client.py 身份验证的文件队列 bridge/server.py 通过 stdio 的 MCP 工具 tools/doctor.py 语法、安装、心跳和往返检查 skills/resolve-ai-editing/ 包含的代理技能 docs/ 故障排除、食谱和 Remotion 指南 src/ 视觉指南的源代码 ``` ## 开发 网页指南： ```bash npm install npm run dev npm run build ``` Python 语法和本地安装检查： ```bash python3 tools/doctor.py ``` 重要的贡献者规则在 `AGENTS.md` 中。 ## 需要提供商帮助？ 在遵循上述步骤后，将以下内容粘贴到 Antigravity、Claude Code、Codex 或另一个本地编码代理中： ```text 阅读本项目中的 00_START_HERE.html 和 README.md。运行 tools/doctor.py，检查 ~/.resolve-ai-bridge/mcp-config.json，并为 resolve-ai-bridge 配置您自己的 MCP 设置。保留我现有的 MCP 服务器。不要更改或公开令牌。仅使用 resolve_status 进行测试，并用简单的步骤解释任何错误。 ``` ## 许可证 MIT。参见 [`LICENSE`](./LICENSE)。