ResolveMCP-ext

resolve-ext

一个 MCP 服务，为 DaVinci Resolve 21.1.2 和 21.2 增添主流 Resolve MCP 服务未涵盖的脚本接口——片段效果、

效果属性、粘贴属性、帧导出、缩略图网格、自动调色、ASC CDL 和媒体池文件夹查询。

它有意定位为扩展，而非替代品：将它与其他三个 Resolve MCP 服务一同注册，即可获得更广泛且互不重叠的功能——

参见完整设置。

它公开的所有功能都经过实时 Resolve 验证；如果调用结果表明某项功能已损坏，就会如实报告，而不会包装成成功。

effects              apply/list/remove/toggle/reorder clip effects


clip_attrs           copy attributes between clips (Paste Attributes)


export_frame         stills from a clip or media-pool item (+ 21.2 region-of-interest)


thumbnails           render named frames as one labelled grid image (21.2)


auto_color           automatic colour on a clip (21.2)


cdl                  read/write a node's ASC CDL (21.2)


folder_ops           which bin does this clip/folder live in


photo_albums         albums, photos, ratings, flags, versions, stills


node_graph           node labels, colours, enable state, LUTs, cache


project_extras       render presets, audio render formats, transcription


jobs                 status of the non-blocking analysis/render jobs (21.1)


clone_media          MediaStorage Clone Tool: copy a media tree (21.1)


camera_comparison    2x2 / split layouts, camera labels, markers


clip_position        move/trim clips, J-cut / L-cut (audio offset)


resolve_ext_status   health check

完整的 Resolve MCP 设置——四个服务，全部运行

Resolve 并非由一个 MCP 服务涵盖。**四个独立服务各司其职，要实现全面覆盖，就必须运行全部四个。**本项目是其中之一；

其他三个并非可有可无的补充。

服务	来源	工具	用途
Blackmagic 自带 ResolveMCP.exe	随 DaVinci Resolve 21 一同提供——无需下载	14	一个元服务：提供 Resolve 的脚本 API 存根和 Python 沙盒（run_script、search_scripting_api、get_whats_new），以及 LUT/DCTL 管理功能。它本身不会执行任何 Resolve 操作。
社区版 samuelgursky/davinci-resolve-mcp	npx 或 git	36 （使用 --full 时为 349）	主力服务：涵盖剪辑、媒体池、渲染、标记、调色、Fusion 等操作，并通过操作参数将相关操作分组。--full 版本提供相同的 API 功能，每个方法对应一个工具；它消耗的是上下文，而非能力。
社区版，高级 davinci-resolve-advanced-mcp	同一软件包，Node	18	**超越脚本 API。**读取和编辑 Resolve 文件——.drp / .drt / .drx 和项目的 SQLite Project.db——无需运行 Resolve。支持离线调色/QC 目录、整理/重新链接 QC、整个项目的节点图重新布局、来源追踪。这里没有其他服务能做到这些。
本项目 resolve-ext	pip	15	补足其他三个服务留下的空缺——参见下表。

第一个和第三个服务通过同一个单客户端脚本 API 驱动同一个 Resolve。高级服务完全不与 Resolve 通信——它直接处理文件——

因此可以与它们同时运行，也可以在未安装 Resolve 的机器上运行。

# 1. Blackmagic's — already on disk, just register it:


#    %ProgramFiles%\Blackmagic Design\DaVinci Resolve\ResolveMCP.exe   (Windows)


#    /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP


#    /opt/resolve/bin/ResolveMCP                                       (Linux)





# 2. the community server (use --clients manual when driving it non-interactively):


npx davinci-resolve-mcp setup





# 3. its advanced sibling — offline file access, needs Node and nothing else.


#    The optional deps are what unlock project_read / conform.verify / pipeline:


npm install --prefix <checkout>/resolve-advanced --include=optional


#    then register:  node <checkout>/bin/davinci-resolve-advanced-mcp.mjs





# 4. this project:


pip install https://github.com/CaptRauti/ResolveMCP-ext/releases/download/v1.0.5/resolve_ext-1.0.5-py3-none-any.whl


resolve-ext doctor

完整流程、各平台路径、Windows 上“Resolve 位于另一块磁盘”的情况，以及各服务的故障模式：AGENTS.md——其中的说明旨在让

AI Agent 能够无人值守地安装全部四个服务。

为什么创建此项目

DaVinci Resolve 21.1.2（2026 年 10 月 22 日）新增了一批脚本 API。主流的 MCP 服务都没有实现这些 API——我们通过两种方式进行了验证：在其源代码中搜索每个符号，并使用 hasattr 探测正在运行的 Resolve 对象（类型存根会记录 API；只有实际对象才能证明你的版本包含这些 API）。

Resolve 21.1.2 符号	主流 MCP 服务中的情况
Resolve.GetEffectsList	不存在
TimelineItem.AddEffect / GetEffects / DeleteEffects	不存在
Effect.GetInfo / Get/SetIsEnabled / Get/SetIndex	不存在
TimelineItem.CopyAttributes	不存在
TimelineItem.ExportFrame / MediaPoolItem.ExportFrame	不存在
MediaPoolItem.GetParentFolder / Folder.GetParentFolder	不存在
TimelineItem.Get/SetLeftOffset / GetPosition	不存在
Timeline.MoveItems / DeleteGaps / Get/SetIsEnabled	不存在
照片相册 API（PhotoAlbum、PhotoAlbumItem，53 个方法）	不存在
Graph.SetNodeLabel / Get/SetNodeColor / SetNodeEnabled	不存在
Project.GetAudioRenderFormats / GetAudioRenderCodecs	不存在
Project.UpdateRenderPreset / SetQuickExportEnabledForRenderPreset	不存在
MediaPoolItem.SetTranscription	不存在

仅 TimelineItem 在 21.1.2 中就提供了 113 个方法；在此服务出现之前，其中很大一部分都无法通过 MCP 访问。

安装

使用 AI Agent 安装？ 请让它参考 AGENTS.md——这是为 Agent 编写的分步操作指南， 其中包含故障处理方法。本节面向人工读者。

需要 Python 3.10+ 和 DaVinci Resolve Studio（外部脚本功能仅限 Studio 版——免费版不支持）。

从发行版本安装（推荐）

从发行页面下载 wheel 并安装：

pip install resolve_ext-1.0.5-py3-none-any.whl

该 wheel 是纯 Python 包，与平台无关——同一个文件可用于 Windows、macOS 和 Linux。

从 git 检出版本安装

pip install git+https://github.com/CaptRauti/ResolveMCP-ext

也可以从本地克隆安装：

git clone https://github.com/CaptRauti/ResolveMCP-ext


cd ResolveMCP-ext


pip install .

mcp 2.x 会导致 FastMCP 无法运行，因此依赖版本固定为 <2。此限制已写入包元数据，无需自行添加。

验证安装

resolve-ext doctor

resolve-ext 1.0.0





--- Python ---


  3.12.4 at /usr/bin/python3


  ok (3.10+)





--- DaVinci Resolve scripting API ---


platform      linux


api_path      /opt/resolve/Developer/Scripting  (found)


lib_path      /opt/resolve/libs/fusionscript.so  (found)





--- Import test ---


  ok: DaVinciResolveScript imports





--- Live connection ---


  ok: connected to Resolve; project = My Project





--- Result ---


  All checks passed.

一切正常时，doctor 会以 0 退出，否则以 1 退出，因此可用于安装脚本。如果有问题，它会指出缺失的确切路径以及需要启用的设置。

在 MCP 客户端中注册

服务会自动查找 Resolve 的脚本 API，因此在默认安装中无需任何配置：

{


  "mcpServers": {


    "resolve-ext": { "command": "resolve-ext" }


  }


}

如果 Resolve 安装位置不是标准路径，或者想查看明确的配置形式，请运行：

resolve-ext env

该命令会输出运行机器的配置信息——包括准确的 RESOLVE_SCRIPT_API、RESOLVE_SCRIPT_LIB 和 PYTHONPATH 值——并以通用 JSON 和 hermes mcp add 命令两种形式呈现。

将配置合并到现有客户端配置时，服务条目应直接放在客户端自己的 mcpServers 键下。不要再套一层 mcpServers——这会导致工具发现功能被静默禁用。

Resolve 设置

Resolve 必须正在运行，并设置为偏好设置 → 系统 → 常规 → 外部脚本使用方式 → 本地。

工具

effects

list_available(media_type?)          video (default) | photo | audio


list_applied(item_id?|name?, category?)


apply(item_id?|name?, category, id)


remove(item_id?|name?, category, indices?)


set_enabled(item_id?|name?, index, enabled, category?)


reorder(item_id?|name?, index, new_index, category?)

使用 item_id（GetUniqueId）定位时间线项目，或使用 name 加所在轨道定位（track_type 默认为 video，track_index 默认为 1）。

始终先调用 list_available——apply 需要使用它返回的 category 和 id。在原版 21.1.2 Studio 中，video 有 36 个 Fusion + 98 个 OFX 效果，此外 audio 还有 Fairlight 效果集。Fusion ID 的形式为 Fusion/Effects/<category>/<name>。

clip_attrs

options()                                    the full option vocabulary


copy(source_id?|source_name?, target_ids?|target_names?, options, ...)


read(item_id?|name?)

Edit 页面 粘贴属性 背后的 API——让每台摄像机的画面风格都能重复应用：调整一个片段，然后将相同属性应用到该摄像机的所有其他片段。

共 6 组、36 个选项（clip、video、zoom_crop_flip、retime、grade_fusion、audio）。简写：copy_all_video、copy_all_audio。

{"colorCorrection": true, "allZoomAttributes": true,


 "allCropAttributes": true, "videoPlugins": true}

export_frame

item(item_id?|name?, frame_offset, output_type?, file_path?, format?, max_dimension?,


     quality?, roi_x?, roi_y?, roi_width?, roi_height?)


media(clip_id, frame_offset, output_type?, file_path?, format?, max_dimension?)


timeline(frame_offset, ...)     # offset is RELATIVE to the timeline start

item 和 media 已验证可用。偏移量从 0 开始，且必须小于片段时长。output_type：file（需要 file_path）或 encodedString（默认）；后者会对 base64 解码并写入服务旁边的 out/，内联返回的内容只有一段短前缀。

21.2 新增了标准化感兴趣区域。 roi_x/roi_y/roi_width/roi_height 是帧尺寸的比例（0..1，默认整个帧），quality 是 JPEG 质量，范围为 1-100。比例按轴分别计算，因此在非正方形帧上，宽度和高度相等的区域并非正方形。在 21.2.0.6 上进行实时验证：roi 0.25/0.25/0.5/0.5 配合 max_dimension=512 会返回 512x288 的静帧——这是裁剪后的帧，无需渲染。

thumbnails（21.2）

item(item_id?|name?, frames, track_type?, track_index?, ...)


timeline(frames, ...)


media(clip_id, frames, ...)


album(album_id?|album_name?, frames, ...)

将多个指定帧渲染到一张带标签的网格图像中——无需查看 N 张静帧，整段片段的画面风格即可在一张图中一览无余。Resolve 按给定顺序从左到右、从上到下填充网格，并为每个单元格添加说明文字。

frames 是整数列表，也可以是 {frameOffset, label} 字典列表，以便自行设置单元格说明文字（时间码、片段名称）。偏移量从 0 开始——对于 item/media，从项目开始处计算；对于 timeline，从时间线开始处计算；album 使用从 1 开始的照片位置。output_type 为 file（需要 file_path，必须包含扩展名——否则 Resolve 会返回 filePath must have a valid image file extension）或 encodedString（默认，解码后写入 out/）。max_dimension 限制整张图较长边的尺寸，因此帧数越多，每个单元格越小。

返回 {success, target, sheet:{width,height,columns,rows,cellWidth, cellHeight}, path|saved_to, bytes}。已在 21.2.0.6 上对全部四种目标进行实时验证。

auto_color（21.2）

apply(item_id?|name?, track_type?, track_index?)


status(item_id?|name?, ...)


enable | disable(item_id?|name?, ...)


clear(item_id?|name?, ...)

对时间线片段进行自动色彩校正。ApplyAutoColor 会校正片段并启用自动色彩标志；clear 会将其移除；enable/disable 会切换此前 apply 已完成的校正——因此先调用 enable 合理地会返回 changed: false。必须显示 Color 页面（实测在 Edit 页面进行相同调用会返回 False，且不会产生任何变化）；该工具会自行切换到 Color 页面，并在切换时报告 page_switched_from。

也适用于照片相册项目：传入 target="photo" 和 photo_id，或传入 photo_name 以及 album_id/album_name。已在 21.2.0.6 上验证。

cdl（21.2）

get(item_id?|name?, node_index?, track_type?, track_index?)


set(item_id?|name?, node_index?, slope?, offset?, power?, saturation?, ...)

读取或写入片段节点的 ASC CDL。数值为以空格分隔的 RGB 字符串，例如 slope="1.1 1.0 0.9"、offset="0.0 0.0 0.0"；saturation 是浮点数（1.0 表示中性）。设置后读取会精确返回写入的值。get 需要 node_index——若未提供，API 会返回 None；这看起来像是结果为空，实际上只是缺少参数。必须使用 Color 页面，与 auto_color 相同。也适用于照片相册项目，只需传入 target="photo"。

四个值可以任意传入其中一部分。 SetCDL 本身需要全部四个键：部分字典会返回 False，且不会产生任何变化（在 21.2.0.6 上实测——仅传入 slope、传入 slope+offset，以及传入 slope+offset+power 都会失败；只有传入完整集合才能应用）。因此，该工具会读取节点当前的 CDL，并覆盖你传入的值，所以仅传入 slope 也能正常工作，同时保留原有的 offset/power/saturation。

folder_ops

parent_of_clip(clip_id)              which bin holds this clip


parent_of_folder(path?|folder_id?)   a folder's parent (root has none)


path(clip_id?|folder_id?)            "Master/Sub/Bin"


find_clip(clip_id)                   locate a clip anywhere in the tree

photo_albums

list() / current() / set_current(album_id?|name?)


create(name) / create_from_photos(name, clip_ids) / delete(album_ids?) / rename(...)


quick_export_presets() / render_settings(settings?)


photos(album_id?|name?) / add_photos(clip_ids) / remove_photos(photo_ids) / current_item()


stills(album_id?|name?, all_photos?)


photo(photo_id) / rate(photo_id, stars) / flag(photo_id, color?|clear?)


clip_color(photo_id, color?|clear?) / versions(photo_id)


add_version / load_version / delete_version


copy_grade / effects_list / effect_apply / effect_remove / fusion_comps / fusion_add

已在 21.1.2.10 上验证可用：**9/9 个 PhotoAlbum 方法、20/20 个

PhotoAlbumItem 方法**、CreatePhotoAlbumFromPhotos、可持久保存的评分／

标记／版本，以及对照片使用 AddFusionComp。

add_photos 在上游无法正常工作（AddToPhotoAlbum 不会添加任何内容）——该操作会通过重新读取相册来验证，并告知你结果。请使用经过验证的路径 create_from_photos。

请注意方法的分布：相册列表方法位于 Project 上，创建／添加方法位于 MediaPool 上，而 Resolve 不会响应其中任何一种调用。每次调用时，工具都会解析正确的对象，因为 Resolve 代理会导致 hasattr 将每个对象都报告为拥有所有方法。

node_graph

info(item_id?|name?|photo_id?)        node list with labels, colours, enabled


label(node_index, label)              "" clears the label


color(node_index, color)              "" clears the colour


enable(node_index, enabled)


tools(node_index)                     which Fusion/OFX tools sit in the node


lut(node_index, lut_path?)            read, or set


cache(node_index, mode?)              read, or set


reset_colors()                        photo graphs only


reset_grades(confirm=true)            destructive — clears the whole grade

有效的节点颜色：Orange、Apricot、Yellow、Lime、Olive、Green、Teal、Navy、

Blue、Purple、Violet、Pink、Tan、Beige、Brown、Chocolate。

可通过 item_id／name 指定时间线片段，或通过 photo_id 指定照片。标签

和颜色已验证可在多次调用间持久保存。

info 还会通过 Graph.GetNodeEnabled 报告每个节点的 enabled 标志；该功能在 21.2 中新增（已在该版本验证）。在较旧版本中，此调用会失败，届时将省略该键，而不是将其报告为 False。

project_extras

capabilities()                             what this build answers at all


render_presets()                           GetRenderPresetList


update_render_preset(preset_name)          GUI-dependent, see the broken table


quick_export_enable(preset_name, enabled)  GUI-dependent


audio_formats()                            {display name -> extension}


audio_codecs(format_extension)             {description -> codec name}


transcription(clip_id, use_nested?)        a clip's transcript


set_transcription(clip_id, transcription)  verified by reading back


playback_frame_rate()                      project playback vs timeline rate (21.2)


set_playback_frame_rate(rate)              SetSetting, read back (21.2)


extras_list()                              Extras Download Manager packages (21.2)


extras_install(name) / extras_uninstall(name)  queues a download / removal (21.2)

已验证 audio_formats／audio_codecs：包含 7 种实际格式

（FLAC, MP3, MP4, MXF OP-Atom, MXF OP1A (IMF), QuickTime, Wave）及其编解码器。已验证 render_presets：包含 37 个实际预设。

21.2 中新增的功能：playback_frame_rate 会读取

timelinePlaybackFrameRate（自 21.2 起可设置——已验证：设置为 '25'，读回

'25'，而 timelineFrameRate 保持为 24.0）；extras_list 会返回 Resolve 在这台机器上提供的 6 个 AI 包及其状态／进度／大小。

extras_install／extras_uninstall 会从 Blackmagic 下载（或取消正在进行的下载）——它们不是读取操作；请轮询 extras_list 查看进度。

注意：对于某些条目（例如 AI Voice

Training），Resolve 报告的 downloadSize 为负数——这是其自身数据中的一个怪异之处，会原样传递。

jobs (21.1)

async_status()                            every job status getter in one call


render_job(job_id)                        Project.GetRenderJobStatus

21.1 将分析 API 改为非阻塞：调用会将作业加入队列，然后你需要轮询。上游服务和本服务都未提供相应的 getter，因此调用方可以启动转录或场景切分分析，却永远不知道是否已完成。async_status 会读取全部 6 个状态——转录音频、分析场记板、智能重新构图、检测场景切换、根据音频创建字幕、使用快速导出进行渲染。每项都会返回 {JobStatus, CompletionPercentage, …}；值为 null 表示此版本无法响应相应的 getter。

clone_media (21.1)

status()                                  GetCloneStatus


settings(preserve_folder_name?, checksum_type?)   SetCloneToolSettings


start(source_dir, target_dirs, …)         StartCloneMedia


stop()                                    StopCloneMedia

MediaStorage Clone Tool——将媒体目录树复制到一个或多个目标位置，并可选择进行校验和验证（none、filesize、crc32、

md5、sha256、sha512、xxh64）。上游服务完全未覆盖此功能，因此此前脚本化迁移媒体无路可走。

复制在后台运行：作业加入队列后，start 会立即返回（JobStatus: InProgress），因此请轮询 status，直到状态变为 Complete。已在 21.2.0.6 上端到端验证：源文件加入队列并完成复制，校验和清单也生成在其旁边。

Windows 路径注意事项： Resolve 在此处会拒绝正斜杠——它会返回 False 且不复制任何内容（实测：C:/… 会失败，C:\… 可用）。工具会进行转换，因此传入哪种格式都可以。

camera_comparison

detect()                 which camera each clip is (from its name)


grid_2x2()               four cameras in quadrants, scale 0.5


split_h() / split_v()    two-up, side by side or stacked


layout(assignments)      explicit {clip_id: {x, y, scale}} — fractions of raster


fullframe(clip_ids)      back to 1.0 zoom, centred


markers()                timeline markers naming each camera


sort_to_bins()           file clips into per-camera bins by name


build_timeline()         one video track per camera, scenes synced


read()                   current transform of every clip

摄像机检测，按前缀最长优先：

| 前缀 | 摄像机 | 标记 |

|---|---|---|

| ace* | Insta360 AcePro | 橙色 |

| go* | Insta360 Go Ultra | 绿色 |

| luna* | Insta360 Luna Ultra | 青色 |

| x* | Insta360 X5 | 蓝色 |

| vid_* | Handy（Android 文件） | 灰色 |

此工具存在的原因：它取代的那些宽松脚本使用 SetProperty("PositionX", …) / "PositionY" 来定位片段。在 21.1.2.10 上实测，这些键会返回 False，并被静默忽略——GetProperty 也会返回 False。缩放有效，但定位始终无效。真正的键是 Pan（x，+向右）和 Tilt（y，+向上），单位为像素。此处每次写入后都会读取验证；未生效的变换会报告为失败。

已验证：在 3840x2160 时间线上，grid_2x2 会将 AcePro 放在 Pan -960, Tilt 540（左上），将 Go Ultra 放在 Pan 960, Tilt 540（右上），并读取验证。

clip_position

get(item_id?|name?)                                 position + handle offsets (read-only)


set(start_frame?|new_track_index?, move_linked?)    move the clip


move(items=[…], move_linked?)                       move several in one call


set_offset(left?|right?, update_linked_items?)      head/tail trim, with readback


j_l_cut(offset_frames, …)                           J-cut / L-cut: shift only the audio


delete_gaps()                                       close the gaps between clips


enabled()                                           timeline enabled state

set_offset 用于设置剪辑点的修剪量：left=n 会让剪辑从源素材的第 n 帧开始。实测一个位于 86400、源范围为 0–71 的剪辑：left=5 后，start 为 86405 / source_start 为 5 / duration 为 67；left=0 则可精确恢复——完全可逆。负值会延伸到头部余量；没有余量时会返回 False。

j_l_cut 是 J-cut / L-cut 的基本操作，也是此工具不断扩展的原因。offset_frames 为负值时，音频会比画面更早开始（J-cut——下一段声音先于画面出现）；为正值时，音频会更晚开始（L-cut——声音持续时间长于画面）。它使用 Timeline.MoveItems(..., moveLinkedItems=False)，因此画面不会移动，音画仍保持关联，且偏移量不变。实测：+24 的 L-cut 将音频从 86400 移至 86424；在有前序剪辑的片段上执行真正的 −12 J-cut 后，音频从 86496 移至 86484，Resolve 会修剪前序剪辑的音频尾部以腾出空间——这正是 NLE 中 J-cut 的效果。

它替你处理了两个容易踩的坑：使用 mediaType=1 追加的剪辑会变成仅视频，因此没有可偏移的音频（追加时不要设置 mediaType）；而 J-cut 需要前序剪辑——Resolve 拒绝将音频放到时间线的 StartFrame 之前，工具会明确说明这一点，而不是只报告失败。

Resolve 21.2.0.6 上的实测行为

以下内容均在运行中的 Studio 版本上实测，并非来自文档。tests/ 可复现这些结果——四个测试套件共 132 项断言，0 次失败。

**在 21.2.0.6 上重新实测后撤回：**此前记录 TimelineItem.SetPosition、Timeline.MoveItems 和 TimelineItem.SetLeftOffset 在 21.1.2.10 上存在故障或会破坏数据。实际上这三个调用均可正常工作，且 SetLeftOffset 可逆。此前得出破坏性结论，是因为时间线在仍包含剪辑时出现了 StartFrame == EndFrame（时长为 0）的情况——下方的 AppendToTimeline 条目才是真正的根本原因。已向上游报告为 issue #336。

可用

| 调用 | 结果 |

|---|---|

| Resolve.GetEffectsList | 36 个 Fusion + 98 个 OFX（视频），Fairlight（音频） |

| TimelineItem.AddEffect / GetEffects / DeleteEffects | 已完成端到端验证 |

| Effect.GetInfo / GetIsEnabled / SetIsEnabled / GetIndex | 已验证 |

| TimelineItem.CopyAttributes | 使用已更改的源值验证通过 |

| TimelineItem.ExportFrame | 偏移量 0..duration-1 可成功，超出范围则会被拒绝 |

| MediaPoolItem.ExportFrame | 已验证，文件已写入 |

| MediaPoolItem / Folder.GetParentFolder | 已验证 |

| Timeline.GetIsEnabled / SetIsEnabled | 已验证 |

故障或具有破坏性——请勿使用

| 调用 | 实测行为 |

|---|---| | TimelineItem.SetPosition | 在 21.2.0.6 上有效——位置为 86400 的片段移动到了 86800，GetPosition 和 GetStart 均确认了这一点；Timeline.MoveItems 也同样有效（→ 87000）。较早版本的记录显示，这两个方法对所有输入都返回 False；当时测量所用时间线报告的 StartFrame == EndFrame——请参阅 AppendToTimeline 条目。 |

| Timeline.ExportFrame | 有效——frameOffset 相对于时间线起点计算，有效范围为 0..duration-1。在 480 帧的时间线上验证：0..479 均成功，480 被拒绝。绝对帧始终会被拒绝，这看起来像是失败。较早版本将此项列为故障；那次测量有误，因为时间线元数据与其内容相矛盾。 |

| Timeline.DeleteGaps | 有效——经验证，[86400, 86600, 86800] → [86400, 86520, 86640]，间隙已闭合。若时间线包含片段却报告 StartFrame == EndFrame，则此方法不起作用；请参阅下方的 AppendToTimeline 条目。 |

| TimelineItem.SetLeftOffset | 在 21.2.0.6 上有效且可还原——它设置 HEAD 裁剪：对位置为 86400、源范围为 0–71 的片段设置 left=5 后，得到 start 86405 / source_start 5 / duration 67；设置 left=0 可精确还原。负值会延伸到片段头部的余量范围内；若没有余量，则返回 False。较早记录中“移动到 −85995，且无法还原”的结果，来自与 SetPosition 条目相同的 duration-0 时间线。 |

| MediaPool.AddToPhotoAlbum | 不会添加任何内容，并返回空列表。通过四种方式进行了测试：紧接 CreateEmptyPhotoAlbum 后调用、暂停 2 s 后调用、显式调用 SetCurrentPhotoAlbum 且经 GetCurrentPhotoAlbum 确认后调用，以及每次都新建相册——每次运行都没有照片。MediaPool.CreatePhotoAlbumFromPhotos 已验证可用（照片会添加并可读取），请使用此方法。 |

| Graph.ResetAllNodeColors | 照片相册项的图形中存在此方法，但时间线片段的图形中不存在（NoneType is not callable）。使用 SetNodeColor(i, "") 清除颜色在两者中都有效。 |

| MediaPoolItem.GetNodeGraph | 在 21.1.2.10 上不可调用（而 TimelineItem.GetNodeGraph 和 PhotoAlbumItem.GetNodeGraph 均有效）。将片段放到时间线上，并通过 item_id 对其进行操作。 |

| Project.UpdateRenderPreset | 对 GetRenderPresetList 列出的全部 37 个出厂预设均返回 False（包括 'H.264 Master'）。API 中不存在 Project.SaveRenderPreset，因此无法通过脚本创建用户预设进行测试。此功能最多只能通过 GUI 使用。 |

| Project.SetQuickExportEnabledForRenderPreset | 情况相同：对出厂预设返回 False。 |

| MediaPoolItem.SetTranscription | 对 PNG 静态图像和没有转录文本的真实视频片段均返回 False，两种起始时间码 '01:00:00:00' 和 '00:00:00:00' 均已测试。此方法会替换转录文本，因此似乎无法在没有转录文本时创建转录文本。 |

| MediaPoolItem.SetClipColor（照片项） | 对照片相册项设置 'Sky' 时返回 False，尽管文档中列出了此颜色；ClearClipColor 有效。该操作会报告拒绝结果，而非假定操作成功。 |

| Folder.AddSubFolder / Folder.MoveClips | 这两个方法都不存在。它们都属于 MediaPool（mp.AddSubFolder(parent, name)、mp.MoveClips(clips, folder)）——已验证 MoveClips 确实会移动片段并返回 True，并非虚报成功。与照片相册 API 一样，这些方法分属不同对象。 |

| TimelineItem.SetProperty("PositionX"/"PositionY") | 会被静默忽略——设置器和获取器均返回 False。请使用 Pan / Tilt（单位为像素，+x 向右，+y 向上）。这导致项目自身的网格脚本失效：缩放生效了，位置却没有变化。 | | 对位于时间线位置 0 的剪辑调用 TimelineItem.AddMarker(0) | 返回 True，但没有任何写入——tl.GetMarkers() 显示数量未变，也没有该名称的标记。**Timeline.AddMarker(0) 可以正常工作。**因此，标记应通过时间线放置，而不是通过项目放置。较早的版本曾将问题归咎于 Timeline.AddMarker；其实使用的正是上述错误配置。 |

| 使用小于 StartFrame 的 recordFrame 调用 AppendToTimeline | **会被静默接受。**在起始帧为 86400 的时间线上传入 0/200/400，会将剪辑放置在 0/200/400——位于时间线自身范围之外，而且时间线的元数据不会同步更新：虽然包含三个剪辑，却报告 StartFrame == EndFrame（时长为 0）。调用 SetProperty、关闭并重新打开后，问题依然存在。在这种时间线上，DeleteGaps 和 SetLeftOffset 都不起作用，Timeline.ExportFrame 则会拒绝所有偏移量，因此看起来像是有三个损坏的 API。请断言 recordFrame >= GetStartFrame()。 |

| 使用 startFrame == endFrame 调用 AppendToTimeline | 返回 None，且不会放置任何内容。对于单帧媒体（GetClipProperty("Frames") == "1"），自然得到的 endFrame 是 0，因此看似“正确”的 0..0 范围会静默失败。省略 endFrame 后，Resolve 会使用整个剪辑，并且可以正常工作。 |

注意事项

• 在 21.1.2 中，TimelineItem.GetProperty("Position") 返回的是 bool，而不是

  坐标。位置信息存储在 Pan / Tilt（以像素表示的 x/y）中。

  RotationAngle 的单位是度，Opacity 的范围是 0–100，裁剪值的范围是 0–1，ZoomX/Y

  表示倍率。这些属性都可写入——请通过回读确认。

• 将时间线的 SetIsEnabled(False) 设为禁用状态后，GetCurrentTimeline() 会返回

  None，因此后续每次调用都会报告“没有当前时间线”，直到在 GUI 中重新启用该时间线。

• MediaPoolItem.GetParentFolder 只有与递归遍历媒体池结合使用时才有用：ImportMedia 会将剪辑放入当前选中的媒体箱中，因此仅查找根目录时会报告“未找到”，而剪辑实际上位于下一层目录。

测试

分为两层，因为 DaVinci Resolve 无法在 CI 中运行。

离线 — 无需 Resolve，这是 CI 的运行方式

python tests/test_offline.py

检查在没有 Resolve 的情况下 server.py 能否导入（这样执行 pip install

后再运行 resolve-ext --help 就不会失败），确认所有十五个工具都已注册，

CLI 返回正确的退出代码，并验证平台路径解析能为当前运行的操作系统生成正确路径。在

Windows、macOS 和 Linux 上运行——请参阅 .github/workflows/test.yml。

实时 — 需要正在运行的 Resolve Studio

python tests/test_e2e.py        # core tools


python tests/test_phase1.py     # photo albums + node graph


python tests/test_extras.py     # render presets, audio formats, transcription


python tests/test_camera.py     # camera layouts, labels, markers, sorting





# point at your own media if ~/Pictures has fewer than 3 PNGs


RESOLVE_EXT_TEST_MEDIA="D:/stills/*.png" python tests/test_camera.py

针对 Resolve Studio 21.1.2.10 执行 162 项断言，0 项失败

（30 项离线 + 132 项实时）。

每个测试套件都会创建自己的临时项目、测试工具，然后将项目删除——绝不会触及你的其他项目。以下两项做法是有意为之：

• 断言会检查值是否发生变化并能回读，而不仅仅是确认没有返回

  错误。写入测试若只是因为内容未变而通过，就毫无证明作用；这正是发现

  DeleteGaps 和 AddToPhotoAlbum 虽然报告成功却没有实际操作的方式。

• 对已知有问题的调用，断言其会如实失败。如果未来的 Resolve 版本修复了

  AddToPhotoAlbum，其测试就会开始失败——这正是提醒我们重新测量并更新此 README 的信号，

  而不是测试损坏了。

设计说明

• **扩展，而非分支。**这里没有重复主流 MCP 服务的功能，因此两者可以并行运行，无需让模型做出选择。

• **如实报告损坏的 API，而不加以掩饰。**当 Resolve 自身的调用给出虚假结果时

  （例如 DeleteGaps 返回 True），工具会附上测量结果予以说明，而不是给出调用方无法信任的成功信息。

• **不公开具有破坏性的 API。**无法通过 API 撤销 SetLeftOffset，因此不会将它纳入接口，而且 get 仍为只读操作。

要求

• DaVinci Resolve Studio 21.1.2+（早期版本缺少这些符号）

• 只要支持 Resolve 脚本 API，Windows / macOS / Linux 均可

• Python 3.10+ 和 MCP Python SDK。pyproject.toml 将 mcp[cli]>=1.30,<2 固定为依赖版本，但服务也可在 mcp 2.x 上运行：该 SDK 在此版本中将 FastMCP 重命名为 MCPServer，导入时会自动选择已安装的名称。15 个工具仅使用两个版本共有的接口，因此环境中意外装有 mcp 2.x 也不会造成影响。CI 会测试这两个版本。

许可证

MIT — 详见 LICENSE。