davinci-resolve-mcp源码结构导览Operation Envelope、执行追踪与内核架构设计【免费下载链接】davinci-resolve-mcpMCP server integration for DaVinci Resolve Studio项目地址: https://gitcode.com/gh_mirrors/da/davinci-resolve-mcpdavinci-resolve-mcp 是一个让 AI 助手通过官方脚本 API 操控 DaVinci Resolve Studio 的 MCP 服务器。它的源码里藏着三件最有意思的事用Operation Envelope统一所有工具的返回答案、用执行追踪回答AI 为什么这么剪、以及一套 9 个复合工具、136 个动作的内核Kernel架构。本文带你用一次导览看懂它的目录分层与核心设计。 一分钟看懂仓库分层打开仓库根目录你会看到五大块职责非常清晰目录角色说明src/在线 Python MCP 服务器驱动正在运行的 Resolve37 个 MCP 工具展开后 389 个动作resolve-advanced/离线 Node MCP 服务器不启动 Resolve直接读写.drp/.drt/.drx文件与项目数据库18 个工具docs/长期文档内核覆盖表、操作指南、API 覆盖参考tests/测试离线测试 大量live_*真机验证脚本scripts/辅助脚本安装器、免费版主桥接、差分对比、渲染压测等一句话概括双服务器设计在线的算应用离线的算计算——compute offline, apply live离线计算在线应用。 在线服务器的三层源码src/内部是一个自底向上的三层结构第一层类型化 API 封装—— src/granular/resolve_211.py、project.py、timeline.py、timeline_item.py、media_pool.py……每个文件对应官方 Scripting API 的一个对象Resolve、Project、Timeline、TimelineItem、MediaPool……把每个方法在哪个版本能用什么参数固化成 Python 类型而不是裸调用。这是它能做到100% API 覆盖的基础见 docs/reference/api-coverage.md。第二层治理与观测中间件—— src/utils/一百多个工具模块其中最重要的四个是本文主角operation_result.pyOperation Envelope、execution_trace.py执行追踪、execution_lifecycle.py生命周期钩子、readback.py回读验证。第三层工具注册与调度—— src/server.py所有复合工具的注册入口把 granular 层和 utils 层组装成 MCP 协议端点。 Operation Envelope让成没成功只有一种回答AI Agent 在每次工具调用后都要回答三个问题真的发生了吗验证过了吗改变了什么早期每个工具用自己的词汇回答readback.missing、succeeded/failed、partial、confirmation_requiredAgent 得逐个工具学习方言。operation_result.py 的 Operation Envelope 把答案统一成一个形状。它有两个关键设计决策源码注释写得非常诚实决策一不拍平用保留键挂载。调研发现status、operation、warnings这些词在领域负载里已经被大量占用status出现 22 处语义各不相同后台作业的 done、转写的 Transcribed、确认门的 confirmation_required。如果直接把信封键合并到顶层会把后台作业的 done 改写成 success让轮询作业永远看不到结束。所以默认dual模式下原始负载原样透传信封挂在保留键_operation之下见 operation_result.py#L53 的ENVELOPE_KEY——不遮蔽、不丢弃且永远只有一个地方可看。决策二状态归一化宁窄勿宽。normalize_status() 把任意结果收敛为四个状态success/partial/blocked/failed。它刻意不做看起来像就猜的启发式比如blocked看起来像门控标志其实它是未能解析的目标列表成功的 dry-run 也带着非空列表——若按它判断会报出一个从未发生的门控。此外还统一了三类证据见 extract_verification()warnings所有警告拍平成字符串列表verification回读证据归一为passed / failed / partial / contradiction / unverified——注意unverified表示没报证据不等于查过没问题changes语义变更量如items_added、items_deleted三种模式可用dual默认透传信封、pure只有信封、legacy无信封支持按调用、按会话、按环境变量切换。 执行追踪回答AI 编辑器为什么这么剪Envelope 解决单次调用execution_trace.py 解决跨多步的相关性。它把一连串工具调用缝成一条执行轨迹相关 ID每次执行生成exec_前缀的 IDexecution_trace.py#L72-L74跨日志和转录可关联每工具计时duration_ms与调用计数语义变更累加如items_deleted、items_added逐步累计验证汇总passed / checks / contradiction 滚雪球式合并有界存储内存环形缓冲只保留最近 100 次执行execution_trace.py#L62-L64落盘的追加日志 8MB 滚动一份execution_trace.py#L59-L60——默认开启的日志不允许无限增长生命周期钩子执行前算风险执行后验状态与追踪配对的是 execution_lifecycle.py——所有复合工具都要穿过的三阶段中间件1. Pre-flight起飞前风险分级 爆炸半径 dry-run 拦截 2. Execution执行中异常捕获 耗时记录 3. Post-flight落地后回读验证 状态漂移检测 轨迹汇总其中风险模型是它最亮眼的部分execution_lifecycle.py#L33-L47维度分级RiskLevellow只读/可逆编辑→medium可逆编辑、标记→high删除、波纹、批量→critical删项目、重置数据库BlastRadiusitem单个剪辑→track单轨道→timeline整条时间线→project整个工程→system宿主系统high及以上默认触发确认门confirmation token这就是 Envelope 里blocked状态的主要来源。一个RiskAssessment数据类execution_lifecycle.py#L50-L75把是否破坏性、是否需要确认、能否快照回滚全部量化——snapshot_available甚至允许不确定None因为没判断过和判断为无回滚是两回事。 内核架构9 个复合工具 × 136 个受护栏动作API 覆盖回答能不能碰到 Blackmagic 每个方法内核Kernel覆盖回答有哪些高层、受护栏的工作流。当前的账本docs/kernels/README.md 记载136 个动作横跨 9 个复合 MCP 工具内核MCP 工具代表动作时间线编辑timelineduplicate_clips、lift_range、create_variant_from_ranges媒体池/导入media_poolsafe_import_media、safe_relink、setup_multicam_timeline渲染/交付rendersafe_set_render_settings、safe_quick_export评论标注timeline_markerscopy_annotations、export_review_report调色timeline_item_colorsafe_set_cdl、safe_apply_drx、grade_version_restoreFusion 合成fusion_compsafe_add_tool、safe_connect_tools工程/数据库project_managersafe_project_create、safe_set_current_database扩展开发script_pluginsafe_install_extension、probe_dctl_lifecycle媒体分析media_analysisanalyze_clip、detect_sync_events、start_batch_job注意命名里的safe_前缀——每个内核文档都附Boundaries边界与Safety Rules安全规则两节。以 docs/kernels/project-lifecycle-kernel.md 为例安全建项目要求_mcp_前缀名、导出/归档路径必须落在系统临时目录、删工程必须显式close_currentTrue、数据库切换默认 dry-run。这些护栏不是文档口号是测试tests/逐条钉死的契约。⚡ 离线 Advanced 服务器不启动 Resolve 的那一半resolve-advanced/ 是超越 API的另一半Node 实现的 MCP 服务器直接编写和编辑 Resolve 的文件.drp/.drt/.drx并打项目数据库级别的补丁全程不需要 Resolve 运行。18 个工具包括drx逐剪辑调色编解码、conform时间线一致性检查、deliverable交付物 QC、pipelineYAML 规格编译为规范数据库 → 计划 → 执行 → 回读比对漂移等。它与在线服务器不是竞争关系而是接力离线侧算出色板生成可直接应用的.drx、出 QC 报告、规划改动在线侧通过脚本 API 落地应用。这也是仓库整体compute offline, apply live哲学的缩影。️ 控制面板同一份数据的人眼视图所有工具执行产生的状态、分析与历史都汇聚到一个本地浏览器控制面板docs/guides/control-panel.md。AI 控制台页可以直接观察工具调用与会话️ 阅读路线图按这个顺序读源码理解成本最低docs/README.md→ 文档总入口先知道有哪些内核和指南src/granular/resolve_211.py→ 看类型化 API 层如何固化官方 API 语义src/utils/operation_result.py→ 理解返回值的统一形状模块 docstring 本身就是设计说明src/utils/execution_lifecycle.pyexecution_trace.py→ 理解护栏 可观测中间件docs/kernels/→ 挑一个你熟悉的领域比如时间线编辑读它的动作表、边界与安全规则resolve-advanced/README.md→ 看离线半边如何把文件即真相落进数据库tests/→live_*前缀是真机验证离线测试守护行为契约test_operation_result.py 甚至有一条用例守护信封键_operation永远保留、不许被领域工具占用小结davinci-resolve-mcp 的源码结构本质上是一条信任链——类型化 API 保证调用的是真实 APIOperation Envelope 保证答案永远在同一处执行追踪与生命周期钩子保证每一步可回看、可验证内核护栏保证高危操作有门。读懂这四层你就读懂了它如何让 AI 敢在剪辑台上动手。【免费下载链接】davinci-resolve-mcpMCP server integration for DaVinci Resolve Studio项目地址: https://gitcode.com/gh_mirrors/da/davinci-resolve-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考