@motionharness/bridge-davinci 0.0.22 → 0.0.23

package/NOTICE

@@ -1,4 +1,4 @@
-Hotion Harness DaVinci Resolve Bridge (@motionharness/bridge-davinci)
+Motion Harness Bridge Component for DaVinci Resolve (@motionharness/bridge-davinci)
 Copyright 2026 MH contributors
 
 This product includes software developed by MH contributors.

package/README.md

@@ -1,6 +1,6 @@
-# Hotion Harness · DaVinci Resolve 可选组件
+# Motion Harness 桥接组件（Motion Harness Bridge Component）
 
-时间线承载完整的普通视频，动效源码仍在 Hotion Harness 中编辑。主 CLI 提供 `mh bridge davinci`，Agent 同时使用达芬奇官方 MCP 处理实拍剪辑、音轨和原生变速。组件不启动另一套 MCP 服务。安装组件时一并安装固定菜单、简洁小窗和侧栏 OFX；给时间线片段自动附加 OFX 尚未提供。
+素材池原素材（`MediaPoolItem`）通过 `sourceId + mediaPoolItemId` 关联 Motion Harness 工程。时间线片段只是操作入口：菜单从所选片段取得原素材，侧栏从实际输入视频核对已有素材关联。同一原素材的复制、裁切及多轨道引用打开同一工程、一起更新。时间线承载普通视频，动效源码仍在 Motion Harness 中编辑。主 CLI 提供 `mh bridge davinci`，Agent 同时使用达芬奇官方 MCP 处理实拍剪辑、音轨和原生变速。组件不启动另一套 MCP 服务。安装组件时一并安装固定菜单、简洁小窗和侧栏 OFX；给时间线片段自动附加 OFX 尚未提供。
 
 ## 支持范围
 
@@ -35,41 +35,41 @@ mh bridge davinci uninstall
 
 ## 侧栏入口
 
-运行 `mh bridge davinci install` 会一并安装菜单、小窗和 OFX。OFX 默认安装到 `/Library/OFX/Plugins`；系统目录需要权限时会请求 macOS 管理员授权，取消或失败会报告未完成，不能当作完整安装成功。安装后保存工程并重启 Resolve，给普通视频附加 Hotion Harness 滤镜。侧栏提供“编辑 Hotion Harness 工程”“更新此素材”“查看状态”和“更多…”。更新直接核对并固定目标，复用已有更新流程，影响该素材在当前工程中的全部引用。立即显示状态提示，重复点击复用正在进行的请求；不需要先打开管理窗口。效果中保存的 ID 和当前时间线选择都不能替代源路径、素材池身份及元数据的交叉核对，无法唯一确定时停止。
+运行 `mh bridge davinci install` 会一并安装菜单、小窗和 OFX。OFX 默认安装到 `/Library/OFX/Plugins`；系统目录需要权限时会请求 macOS 管理员授权，取消或失败会报告未完成，不能当作完整安装成功。安装后保存工程并重启 Resolve，给普通视频附加 Motion Harness 桥接组件。侧栏提供“编辑 Motion Harness 工程”“更新此素材”“查看状态”和“更多…”。更新直接核对并固定目标，复用已有更新流程，影响该素材在当前工程中的全部引用。立即显示状态提示，重复点击复用正在进行的请求；不需要先打开管理窗口。效果中保存的 ID 和当前时间线选择都不能替代源路径、素材池身份及元数据的交叉核对，无法唯一确定时停止。
 
 自动附加、自动恢复被移除的效果和“不可单独删除”不在当前范围；用户按图文步骤自行添加侧栏，缺少视觉入口时仍可从固定菜单编辑、更新片段。新旧入口协议在升级期间并存，旧二进制仍可能给出过期路径提示，需重新启动 Resolve 才会加载新的原生入口。
 
 ## Studio 流程
 
-日常操作直接使用侧栏的编辑、更新和状态按钮。没有添加侧栏 OFX 时，选中普通视频后仍可从「工作区 → 脚本 → Utility → Hotion Harness」使用“编辑工程”和“更新到达芬奇”。独立的“管理所选片段”菜单已移除；升级仅清理未被用户修改的自有旧菜单。
+日常操作直接使用侧栏的编辑、更新和状态按钮。没有添加侧栏 OFX 时，选中普通视频后仍可从「工作区 → 脚本 → Utility → Motion Harness 桥接组件」使用“编辑工程”和“更新到达芬奇”。独立的“管理所选片段”菜单已移除；升级仅清理未被用户修改的自有旧菜单。
 
 组件安装后，Studio 导出面板并列显示“发送到达芬奇”。未安装时隐藏该按钮，旁边的说明提供安装命令。先打开目标 Resolve 时间线，再选择导出格式发送。已关联的源在同一位置提供“更新到达芬奇”。发送前先显示工程、时间线、空闲视频轨和播放头位置；更新前显示实际目标与本次核对的引用数量。确认后按该目标在后台完成渲染、完整解码验证和导入；动效内容或目标剪辑改变会报冲突，不覆盖用户操作。
 
-发送成功后提供可关闭的侧栏入口提示，图文步骤包含特效库搜索、拖入片段的真实界面截图，快捷键作为补充。选择“不再提示”后，仍可从导出区的桥接说明或侧栏“更多…”窗口底部打开图文步骤。CLI 完成发送的任务结果包含可选的 `sidebarHint`，供 Agent 在交付时说明；`mh bridge davinci sidebar-guide` 返回本机图文页位置。帮助页不修改 Resolve，也不意味着侧栏已自动附加。
+发送成功后提供可关闭的侧栏入口提示，图文步骤包含特效库搜索、拖入片段的布局示意图，快捷键作为补充。选择“不再提示”后，仍可从导出区的桥接说明或侧栏“更多…”窗口底部打开图文步骤。CLI 完成发送的任务结果包含可选的 `sidebarHint`，供 Agent 在交付时说明；`mh bridge davinci sidebar-guide` 返回本机图文页位置。帮助页不修改 Resolve，也不意味着侧栏已自动附加。
 
 MP4/H.264 用于不透明视频。MOV/ProRes 4444 或 4444 XQ 支持 straight alpha。源中的音轨当前仍由桥接明确拒绝，请让 Agent 在 Resolve 中管理音轨，避免静默丢声。
 
-确认并提交后返回任务 ID；真实阶段为 queued、preparing、rendering、validating、applying，再到 completed、failed、cancelled 或 outcome-unknown。重复提交同一幂等键返回原任务。网络丢失回执时，当前 Studio 页会保留已确认请求，重新打开导出面板或刷新页面只按原键查询，不自动重发。暂时查不到任务也不会改用新键；“重试原请求”明确使用原目标、版本条件和幂等键。已知任务 ID 丢失时只允许继续核对，不盲目重发。重开导出面板会核对当前源内容、已应用版本和原生关联；该轻量核对不扫描时间线或切换达芬奇页面，完整引用检查仅在明确准备更新时进行。其他素材、多目标或纯渲染任务可继续观察，面板不会把它们当成当前素材已经更新。
+确认并提交后返回任务 ID；真实阶段为 queued、preparing、rendering、validating、applying，再到 completed、failed、cancelled 或 outcome-unknown。重复提交同一幂等键返回原任务。网络丢失回执时，当前 Studio 页会保留已确认请求，重新打开导出面板或刷新页面只按原键查询，不自动重发。暂时查不到任务也不会改用新键；“重试原请求”明确使用原目标、版本条件和幂等键。已知任务 ID 丢失时只允许继续核对，不盲目重发。重开导出面板只核对原素材身份、工程目录是否存在和已记录关联；不启动源工程内容检查、不计算整段视频摘要，也不扫描时间线或切换达芬奇页面。更新确认只说明影响全部引用，不为统计引用数量扫描工程。其他素材、多目标或纯渲染任务可继续观察，面板不会把它们当成当前素材已经更新。
 
 ## Agent 从 Resolve 开始
 
 1. 用达芬奇官方 MCP 读取明确的工程和时间线，完成实拍剪辑，并取得插入目标。
-2. 用主 CLI 创建或修改可编辑 Hotion Harness 工程，匹配输出尺寸、帧率和时长。
+2. 用主 CLI 创建或修改可编辑 Motion Harness 工程，匹配输出尺寸、帧率和时长。
 3. 可先调用 `mh bridge davinci action prepare --project <源目录> --json '{"operation":"send","idempotencyKey":"..."}'` 获取固定目标及版本条件，将返回的 `request` 原样交给 `send`，并保留同一 `--project`。无需人工确认的 Agent 流程也可直接调用 `mh bridge davinci send --project <源目录> --json '<请求>'`。请求至少包含 `idempotencyKey`，可包含 `export`（与 `mh render` 相同的格式/编码/透明度等选项）以及 `scope`、`timelineId`、`track`、`recordFrame`。
 4. 用 `mh bridge davinci task --json '{"taskId":"..."}'` 查询完成结果。也可传 `idempotencyKey` 恢复丢失的任务 ID。
 5. 用 Resolve MCP 对普通视频做原生剪辑。修改动效源后，调用 `update`，指定 `bindingId`、可选 `expectedRevision` 和新的 `idempotencyKey`。
 
-`inspect --json '{"bindingId":"...","mode":"status"}'` 只核对当前源版本与素材身份，不读取全部剪辑；默认 `inspect` 仍执行完整引用检查。`action prepare` 的结果是只读确认资料，不创建任务，也不渲染视频。
+`inspect --json '{"bindingId":"...","mode":"status"}'` 只核对目标原素材与已记录关联；默认 `inspect` 采用相同的轻量检查。返回的源观察是缓存资料，`contentChecked:false` 表示本次未重新检查源内容。打开只要求源工程存在。源版本和文件完整性在实际更新、恢复或导出前检查。`action prepare` 的结果是只读确认资料，不创建任务，也不渲染视频。
 
-显式管理接口还有 `bind`、`render`、`adopt`、`insert`、`apply`、`sync`、`duplicate`、`inspect`、`timeline`、`selection`、`cancel` 和 `recover`。每个动作使用 `--json`、`--file` 或 `--stdin`。用 `mh bridge davinci describe --json '{"operation":"insert"}'` 查看已安装适配器的完整请求结构。修改动作需要幂等键；支持范围以 `doctor` 和实际任务结果为准。规格变化不会自动重剪已有时间线，应发送为新素材。固定播放文件通过原生 RelinkClips 刷新，并逐次核对全部引用，不要求关闭默认全局设置。恒定变速、倒放和定格的剪辑状态会保留，但刷新结果存在以下预览限制。已关联代理和未知时间映射继续明确阻止自动更新。
+显式管理接口还有 `bind`、`render`、`adopt`、`insert`、`apply`、`sync`、`duplicate`、`inspect`、`timeline`、`selection`、`cancel` 和 `recover`。每个动作使用 `--json`、`--file` 或 `--stdin`。用 `mh bridge davinci describe --json '{"operation":"insert"}'` 查看已安装适配器的完整请求结构。修改动作需要幂等键；支持范围以 `doctor` 和实际任务结果为准。规格变化不会自动重剪已有时间线，应发送为新素材。固定播放文件通过原生 RelinkClips 刷新，只操作绑定的原素材，不重建、修改或逐一检查时间线片段，不要求关闭默认全局设置。位置、裁切、变速、倒放、定格和特效由达芬奇保留，但刷新结果存在以下预览限制。已关联代理的原素材仍阻止自动更新；时间线实例的编辑差异不作为关联失效条件。
 
 `duplicate` 可仅复制编辑源，也可明确指定 `bindingId`、`itemId`、`timelineId` 及当前媒体/时间线指纹，复制编辑源与不可变视频后让这一个时间线实例使用新关联；其他实例继续引用原素材。当前原生独立实例流程限定源与时间线均为 30 fps、无已有 Take Selector、无关联音轨和曲线变速，临时归一化不可超出源时长。原生步骤写入恢复记录；发生外部改动时停止，不能凭旧状态盲目回滚。
 
 ## 入口与历史版本
 
-macOS 原生包安装“编辑工程”和“更新到达芬奇”两个菜单脚本，入口为 Resolve「工作区 → 脚本 → Utility → Hotion Harness」。主 CLI `edit` 可按选中片段的稳定关联打开源工程。
+macOS 原生包安装“编辑工程”和“更新到达芬奇”两个菜单脚本，入口为 Resolve「工作区 → 脚本 → Utility → Motion Harness 桥接组件」。主 CLI `edit` 可按选中片段的稳定关联打开源工程。
 
-侧栏“更多…”按效果自身的源路径固定素材身份，后来切换选择不会把操作转给另一段素材。窗口直接提供该关联确实应用过的历史版本、指定时间线实例的独立副本（多处引用时先明确选择具体片段）、重新定位源目录和丢失元数据时的关联修复；目录面板只在明确点击相应操作后出现。恢复版本前显示会影响的引用数量，独立副本则明确只改变一个时间线实例。结果不明时先核对原任务，再明确选择继续原任务；原任务可能包含多个目标，不会被管理窗口缩成当前一段。
+侧栏“更多…”按效果自身的源路径固定素材身份，后来切换选择不会把操作转给另一段素材。窗口直接提供该关联确实应用过的历史版本、重新定位源目录和丢失元数据时的关联修复。点击“创建独立副本…”后才扫描引用并选择具体片段；日常打开管理窗口不列举全部时间线实例。目录面板只在明确点击相应操作后出现。恢复版本前说明影响该素材的全部引用，独立副本则明确只改变一个时间线实例。结果不明时先核对原任务，再明确选择继续原任务；原任务可能包含多个目标，不会被管理窗口缩成当前一段。
 
 默认构建和安装包同时包含菜单、小窗和图像透传 OFX。插件仅提供源工程入口和更新状态，不承载动效渲染。普通视频不会自动附加 OFX，`entry restore` 当前返回能力不可用；缺少或删除视觉入口不影响源关联，可以继续通过固定菜单和 CLI 管理。安装 OFX 与自动附加 OFX 是两个独立能力。
 
@@ -110,6 +110,14 @@ macOS 原生构建使用 `node packages/bridge/davinci/native/build.mjs`，生
 
 ### 固定视频与更新恢复
 
-每个关联使用 `artifacts/media/<bindingId>/<文件名>` 作为播放文件，`artifacts/<artifactId>/` 保存独立的历史版本。渲染和完整视频校验成功后，先记录任务的目标、旧版本和新版本，再由原生脚本核对素材身份与剪辑状态，在同一目录原子替换播放文件，并通过 `RelinkClips` 刷新。不会覆盖历史文件或使用硬链接。渲染失败保留旧画面；发布后结果不明时保留原任务，不自动重新提交。通过管理窗口或 `recover` 核对已应用版本，只有原目标仍匹配才允许继续。
+每个关联使用 `artifacts/media/<bindingId>/<文件名>` 作为播放文件，`artifacts/<artifactId>/` 保存独立的历史版本。渲染和完整视频校验成功后，先记录任务的目标、旧版本和新版本，再由原生脚本核对绑定的原素材身份、关联和媒体规格，在同一目录原子替换播放文件，并通过 `RelinkClips` 刷新。不会覆盖历史文件或使用硬链接。渲染失败保留旧画面；发布后结果不明时保留原任务，不自动重新提交。通过管理窗口或 `recover` 核对已应用版本，只有原目标仍匹配才允许继续。
 
-固定路径不保证所有未知宿主版本和代理组合的行为。组件沿用已验证宿主范围，已关联代理、无法核对的媒体或不支持的时间线结构仍拒绝更新。普通视频暂停时可能保留旧帧，播放或移动播放头后才显示新画面；定格画面也可能保留旧版本。定格不因此阻止更新。状态小窗及管理窗口以一行次要文字提示“预览未刷新请播放；定格可能保留旧画面。”任务完成代表视频文件与关联已更新，不保证宿主预览已经重绘。管理窗口保留恢复版本、重新定位、修复关联等低频功能。
+固定路径不保证所有未知宿主版本和代理组合的行为。组件沿用已验证宿主范围，已关联代理或无法核对身份、版本及文件完整性的原素材仍拒绝更新。时间线结构检查只用于插入、独立实例副本和最终导出等操作。普通视频暂停时可能保留旧帧，播放或移动播放头后才显示新画面；定格画面也可能保留旧版本。定格不因此阻止更新。状态小窗及管理窗口以一行次要文字提示“预览未刷新请播放；定格可能保留旧画面。”任务完成代表视频文件与关联已更新，不保证宿主预览已经重绘。管理窗口保留恢复版本、重新定位、修复关联等低频功能。
+
+### 名称与语言兼容
+
+侧栏显示本地连接状态，缺少 CLI、配置或状态窗口时会在首次点击立即提示。通过 npm 安装时保存固定 CLI 启动入口，每次操作自动定位当前原生程序，CLI 升级或平台包位置变化后无需重装 OFX。点击“修复连接”可刷新已有启动配置并检查达芬奇连接，不重装 OFX、不重启达芬奇，也不改素材关联。组件文件缺失或配置被用户修改时，提示运行 `mh bridge davinci install` 修复。
+
+组件在中文界面显示为 **Motion Harness 桥接组件**，英文显示为 **Motion Harness Bridge Component**。原生侧栏与小窗口跟随 macOS 首选中英文，固定菜单在安装或修复时使用同一语言；Studio 的图文帮助跟随 Studio 当前语言。`MH_UI_LOCALE=zh-CN` 或 `MH_UI_LOCALE=en` 可显式指定原生入口语言。更改系统语言后，重新安装组件并重启 Resolve 即可刷新菜单及侧栏名称。
+
+旧版本误拼写对应的 OFX 插件 ID、参数键、二进制文件名、通知标识和 `Application Support/Hotion Harness` 配置路径继续保留，以兼容已有工程、入口和安装记录。`legacy-inspector-v1.lua` 是旧入口逐字节识别所需的原始模板，不用于生成新的界面。升级只移除已登记且未修改的旧菜单，保留用户定制内容。

package/bridge-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "name": "@motionharness/bridge-davinci",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "protocol": 1,
-  "cliVersion": "0.0.22",
+  "cliVersion": "0.0.23",
   "files": [
     {
       "path": "dist/inspector_runtime.py",
@@ -19,15 +19,15 @@
     },
     {
       "path": "dist/legacy_conversion.py",
-      "sha256": "0581d63ac5c67a489e10887fba4fae0abdaf89f1640f9c450b7e1b911251769b"
+      "sha256": "3c595b7f5a34611d20f59bdd8181414b5191aadd27fee02667dfdd6c59f6d464"
     },
     {
       "path": "dist/resolve_rpc.py",
-      "sha256": "cfb622ec26f3d33dc961fb498b7774330eaa9bd3455752b4a582af78ba92852a"
+      "sha256": "f10440c19783605f0aec00b206a6520d7a3dafd6f28ddf307cae6b7e08802691"
     },
     {
       "path": "dist/runner.mjs",
-      "sha256": "e1c08679917fff1acc6d88af1671783b398045ee987393d4b580c5e5f304bf3b"
+      "sha256": "8a7c2c89b465ed32ce0e3e275edf8e4e8b0b2c5cd61b01dbf7690daaf2e235d5"
     },
     {
       "path": "dist/runtime_io.py",
@@ -39,7 +39,7 @@
     },
     {
       "path": "NOTICE",
-      "sha256": "dbd3fd6e2ae4bed6332946051cfced0b9f3b559ec72f9f27d1ea9d4959d51d65"
+      "sha256": "08da1a97f3e888dc31f14a8489f4ddbc2a8471a588831c6c1a784c57b55d2d88"
     },
     {
       "path": "OPENFX_LICENSE",
@@ -47,16 +47,16 @@
     },
     {
       "path": "README.md",
-      "sha256": "bfded59d2028d419e7d34961971bb69b0ebc161f9ec5ba4284463c7c9a91687f"
+      "sha256": "a60beff9902034f0d59739ae714659feb00c7e4e2bb747c8b36d1ed25bec6451"
     },
     {
       "path": "resources/HotionHarness.ofx.bundle/Contents/Info.plist",
-      "sha256": "8e856f10d851400c6a0d192724d4a01bfe5a3c9920f5c1044dfcb1fc1c0a1a25",
+      "sha256": "a5316a00995683460edc87123ad958425cd1be36a2dc64edd26b1063b6acefed",
       "executable": false
     },
     {
       "path": "resources/HotionHarness.ofx.bundle/Contents/MacOS/HotionHarness.ofx",
-      "sha256": "825783410ce6bd1b00cf0dbf3ee1e2a82d13bf5ad7bd5b628f99ba3ee729ba69",
+      "sha256": "750369116eac4aec476a903685690bb488088f881f82d7b3ec0596e9b38a1aa2",
       "executable": true
     },
     {
@@ -66,17 +66,27 @@
     },
     {
       "path": "resources/HotionHarnessStatus.app/Contents/Info.plist",
-      "sha256": "a56fa4c4bbc618f9e0a362474637afa4e2463046677bd8396f5c5b7043c3dc71",
+      "sha256": "ec9e19f3f74cbc09c076382a1fe49c2553a8592887680449d8645ed4adca3fd9",
       "executable": false
     },
     {
       "path": "resources/HotionHarnessStatus.app/Contents/MacOS/HotionHarnessStatus",
-      "sha256": "dda084047882a6de416d572a3a1f5df855d6bf3de14e4197cbd6b403cfc1429e",
+      "sha256": "8894fd5809549ab4281adc525d447d0c847c8720dd5705e4df4be40098cacd08",
       "executable": true
     },
+    {
+      "path": "resources/HotionHarnessStatus.app/Contents/Resources/en.lproj/InfoPlist.strings",
+      "sha256": "a2ace2734255bc9751b7ea734d7cf19b1d1386604b8cb838f0e529839846f419",
+      "executable": false
+    },
+    {
+      "path": "resources/HotionHarnessStatus.app/Contents/Resources/zh-Hans.lproj/InfoPlist.strings",
+      "sha256": "834876e910caa01c120735fc3cb927db473014cc336e4977aae8d390591e1be2",
+      "executable": false
+    },
     {
       "path": "resources/legacy-forwarder.lua",
-      "sha256": "778edbabdd56947743f6028ac7f6ec212c8685f04a55244b18672bdb7f32e861",
+      "sha256": "342b396ac9fd68dbb9e8cd166c2e99b8d0740c7dc01cac3a5064d6fd092b8900",
       "executable": false
     },
     {
@@ -86,17 +96,17 @@
     },
     {
       "path": "resources/menu-entry.py",
-      "sha256": "08b4cb619d39735a4bdb468e6b8c00feb454c6c11ece14905c043b564d26398d",
+      "sha256": "15f8dafb4d3c4a8020007b20764d4e3c1700f9585be107769efefd8ba4877e94",
       "executable": false
     },
     {
-      "path": "resources/sidebar-help/index.html",
-      "sha256": "4c6e51cd63b5310816af724877f4ef42d7f6293a41a97fbcb89a966b84f73db7",
+      "path": "resources/sidebar-help/en.html",
+      "sha256": "838c7af75c332e6427d78c97a67d4cd44f142633e97dc5200c2a079145d0d4cd",
       "executable": false
     },
     {
-      "path": "resources/sidebar-help/resolve-sidebar.png",
-      "sha256": "78a18d0047315a59217a897bf4958e9c4cd2445b7ea66039491c0b3721608985",
+      "path": "resources/sidebar-help/index.html",
+      "sha256": "ad201ec81af3728ec4a3d0219ca55b5d00fdba2bacb694dcaf47652d368eb8a4",
       "executable": false
     },
     {

package/dist/legacy_conversion.py

@@ -276,7 +276,7 @@ def _plan(resolve, project, scope, params, api):
             continue
         reasons = []
         if not entry:
-            reasons.append(("legacy-identity-unrecognized", "不是完整识别的 Hotion Harness 旧生成器，保持原结构。"))
+            reasons.append(("legacy-identity-unrecognized", "不是完整识别的 Motion Harness 旧生成器，保持原结构。"))
         candidate = {"itemId": item["id"], "name": item["name"], "track": item["track"], "startFrame": item["startFrame"], "endFrame": item["endFrame"]}
         if entry:
             identity = entry["identity"]
@@ -415,7 +415,7 @@ def convert(resolve, project, scope, params, api):
     if name:
         require(name not in names, "TARGET_OCCUPIED", "隔离副本名称已经存在，请选择新名称；未调用 DuplicateTimeline。")
     else:
-        base = plan["name"] + " · Hotion Harness 转换"
+        base = plan["name"] + " · Motion Harness 转换"
         name, suffix = base, 2
         while name in names:
             name = base + " " + str(suffix)

package/dist/resolve_rpc.py

@@ -2,8 +2,8 @@
 """One JSON request over stdin. Only documented Resolve scripting APIs are used.
 
 Only explicit targets and owned render IDs can be modified. Resolve's database
-is never edited directly. Unsupported effects exposed by public readback block
-automated replacement; Edit-page OFX omitted from OTIO cannot be fully enumerated.
+is never edited directly. Updating a bound media-pool item leaves its timeline
+instances and effects under Resolve ownership.
 """
 import hashlib
 import importlib
@@ -127,91 +127,36 @@ def media_for(project, media_id):
 
 
 def ofx_source_target(resolve, params):
-    """Prove an OFX host source maps to one media item, without UI selection.
+    """Match the actual input file to its registered media-pool identity.
 
-    Two complete pool reads detect changes visible during discovery. This is a
-    read-only observation, not a lock; callers must revalidate before mutation.
-    File-less timeline/compound entries are excluded only when GetTimeline()
-    returns an identifiable timeline. Other unclassifiable entries fail closed.
+    Read file paths once to reject ambiguous imports. Only the target's bridge
+    metadata matters; unrelated subtitles, generators and metadata are ignored.
     """
-    def identifier(value):
-        return isinstance(value, str) and bool(value.strip()) and "\0" not in value
-
-    def canonical_path(value, code):
-        require(identifier(value) and os.path.isabs(value), code, "侧栏源路径必须是非空绝对路径。")
-        return os.path.realpath(value)
-
     requested = params.get("scope")
+    media_id, raw_path = params.get("mediaPoolItemId"), params.get("path")
+    valid = lambda value: isinstance(value, str) and bool(value.strip()) and "\0" not in value
     require(isinstance(requested, dict) and set(requested) == {"databaseId", "projectId"}
-            and all(identifier(value) for value in requested.values()),
-            "INVALID_ARGUMENT", "侧栏入口需要明确的数据库和工程作用域。")
-    media_id = params.get("mediaPoolItemId")
-    require(identifier(media_id), "INVALID_ARGUMENT", "侧栏入口需要明确的素材池对象 ID。")
-    path = canonical_path(params.get("path"), "INVALID_ARGUMENT")
-
-    def read_media(media):
-        identity = media.GetUniqueId()
-        require(identifier(identity), "CAPABILITY_UNAVAILABLE", "素材池对象缺少可验证的 ID。")
-        properties = media.GetClipProperty()
-        require(isinstance(properties, dict) and "File Path" in properties,
-                "CAPABILITY_UNAVAILABLE", "无法完整读取素材池文件路径，不能证明侧栏源唯一。")
-        raw_path = properties["File Path"]
-        if raw_path == "":
-            timeline = media.GetTimeline()
-            timeline_id = timeline.GetUniqueId() if timeline else None
-            require(identifier(timeline_id), "CAPABILITY_UNAVAILABLE",
-                    "素材池包含无法识别来源的无文件素材，不能证明侧栏源唯一。")
-            return identity, {"timelineId": timeline_id}
-        source_path = canonical_path(raw_path, "CAPABILITY_UNAVAILABLE")
-        metadata = media.GetThirdPartyMetadata()
-        require(isinstance(metadata, dict) and all(isinstance(key, str) and isinstance(value, str)
-                for key, value in metadata.items()), "CAPABILITY_UNAVAILABLE", "无法完整读取素材关联元数据。")
-        # Copy values so a host response or test double cannot mutate our proof.
-        return identity, {"path": source_path, "metadata": dict(metadata)}
-
-    def scan(project):
-        pool = project.GetMediaPool()
-        root = pool.GetRootFolder() if pool else None
-        require(root is not None, "CAPABILITY_UNAVAILABLE", "无法读取素材池根目录。")
-        folders, media_states, objects = {}, {}, {}
-        pending = [root]
-        while pending:
-            folder = pending.pop()
-            folder_id = folder.GetUniqueId()
-            require(identifier(folder_id) and folder_id not in folders,
-                    "CAPABILITY_UNAVAILABLE", "素材池目录 ID 缺失、重复或存在循环。")
-            clips, children = folder.GetClipList(), folder.GetSubFolderList()
-            require(isinstance(clips, list) and isinstance(children, list),
-                    "CAPABILITY_UNAVAILABLE", "素材池目录读取不完整，不能证明侧栏源唯一。")
-            folders[folder_id] = []
-            for media in clips:
-                identity, state = read_media(media)
-                require(identity not in media_states, "CAPABILITY_UNAVAILABLE", "素材池对象 ID 重复，不能证明侧栏源唯一。")
-                media_states[identity], objects[identity] = state, media
-                folders[folder_id].append(identity)
-            folders[folder_id].sort()
-            pending.extend(children)
-        matches = [identity for identity, state in media_states.items() if state.get("path") == path]
-        require(len(matches) == 1 and matches[0] == media_id, "VERSION_CONFLICT",
-                "侧栏源路径没有对应唯一且匹配的素材池对象；请从固定菜单管理片段。")
-        return {"folders": folders, "media": media_states}, objects[media_id]
-
-    try:
-        project, scope = project_for(resolve, requested)
-        first, _ = scan(project)
-        project_for(resolve, requested)
-        second, target = scan(project)
-        require(first == second, "VERSION_CONFLICT", "素材池在侧栏身份核对期间发生变化。")
-        identity, final_state = read_media(target)
-        require(identity == media_id and final_state == second["media"][media_id],
-                "VERSION_CONFLICT", "素材路径或关联元数据在侧栏身份核对期间发生变化。")
-        project_for(resolve, requested)
-        return {"scope": scope, "mediaPoolItemId": media_id, "path": path,
-                "metadata": final_state["metadata"], "unique": True}
-    except BridgeFailure:
-        raise
-    except Exception as error:
-        raise BridgeFailure("CAPABILITY_UNAVAILABLE", "无法完整核对侧栏素材身份。", diagnostic=str(error))
+            and all(valid(value) for value in requested.values()) and valid(media_id),
+            "INVALID_ARGUMENT", "侧栏入口需要明确的数据库、工程和素材池对象 ID。")
+    require(valid(raw_path) and os.path.isabs(raw_path), "INVALID_ARGUMENT", "侧栏源路径必须是非空绝对路径。")
+    path = os.path.realpath(raw_path)
+    project, scope = project_for(resolve, requested)
+    matches = []
+    for media in all_media(project.GetMediaPool().GetRootFolder()):
+        try:
+            properties = media.GetClipProperty() or {}
+            source_path = properties.get("File Path")
+        except Exception:
+            require(media.GetUniqueId() != media_id, "CAPABILITY_UNAVAILABLE", "无法读取目标素材的文件路径。")
+            continue
+        if valid(source_path) and os.path.isabs(source_path) and os.path.realpath(source_path) == path:
+            matches.append(media)
+    require(len(matches) == 1 and matches[0].GetUniqueId() == media_id,
+            "VERSION_CONFLICT", "侧栏源路径没有对应唯一且匹配的素材池对象；请从固定菜单管理片段。")
+    result = media_identity(project, scope, matches[0])
+    require(os.path.realpath(result["path"]) == path, "VERSION_CONFLICT", "目标素材已被重新链接。")
+    project_for(resolve, requested)
+    return {**result, "path": path, "unique": True}
 
 
 def fps_value(value):
@@ -685,8 +630,28 @@ def publish_playback(path, publication, before_path):
             os.unlink(pending)
 
 
+def media_identity(project, scope, media):
+    """The original media owns the binding, independently of its timeline uses."""
+    try:
+        properties = media.GetClipProperty() or {}
+        metadata = media.GetThirdPartyMetadata() or {}
+    except Exception as error:
+        raise BridgeFailure("CAPABILITY_UNAVAILABLE", "无法读取目标原素材的身份或关联。", diagnostic=str(error))
+    require(isinstance(properties, dict) and isinstance(metadata, dict)
+            and all(isinstance(key, str) and isinstance(value, str) for key, value in metadata.items()),
+            "CAPABILITY_UNAVAILABLE", "无法读取目标素材的身份或关联。")
+    data = {"scope": scope, "projectName": project.GetName(), "mediaPoolItemId": media.GetUniqueId(),
+            "path": properties.get("File Path", ""), "metadata": metadata,
+            "uses": [], "usageScanComplete": False,
+            "clipProperties": {key: properties.get(key) for key in ("FPS", "Frames", "Resolution", "Audio Ch", "Proxy Media Path", "Input Color Space", "Input Gamma", "Data Level", "Alpha mode", "PAR", "Field Dominance", "Clip Name")}}
+    data["fingerprint"] = fingerprint({"scope": scope, "mediaPoolItemId": data["mediaPoolItemId"], "path": data["path"],
+        "bridgeMetadata": metadata.get("motionharness.bridge"),
+        "properties": {key: value for key, value in data["clipProperties"].items() if key != "Clip Name"}})
+    return data
+
+
 def media_snapshot(project, scope, media, resolve=None):
-    properties = media.GetClipProperty() or {}
+    data = media_identity(project, scope, media)
     media_id = media.GetUniqueId()
     uses = []
     complete = True
@@ -700,11 +665,8 @@ def media_snapshot(project, scope, media, resolve=None):
         if any(any(reason in i["unsupported"] for reason in ("nested-or-compound-timeline", "no-plain-media-source", "nested-or-unknown-otio-item", "nested-media-reference", "otio-inspection-unavailable", "otio-item-coverage-mismatch", "host-build-and-frame-conventions-unverified")) for i in items):
             complete = False
     settings = project.GetSettings() if resolve and validated_host(resolve) else {}
-    data = {"scope": scope, "projectName": project.GetName(), "mediaPoolItemId": media_id, "path": properties.get("File Path", ""),
-            "metadata": media.GetThirdPartyMetadata() or {}, "uses": uses, "usageScanComplete": complete,
-            "clipProperties": {key: properties.get(key) for key in ("FPS", "Frames", "Resolution", "Audio Ch", "Proxy Media Path", "Input Color Space", "Input Gamma", "Data Level", "Alpha mode", "PAR", "Field Dominance", "Clip Name")},
-            "playbackPolicy": {key: settings.get(key) for key in ("perfProxyMediaMode", "perfOptimisedMediaOn", "perfRenderCacheMode")}}
-    data["fingerprint"] = fingerprint({"properties": properties, **data})
+    data.update({"uses": uses, "usageScanComplete": complete,
+                 "playbackPolicy": {key: settings.get(key) for key in ("perfProxyMediaMode", "perfOptimisedMediaOn", "perfRenderCacheMode")}})
     return data
 
 
@@ -885,7 +847,7 @@ def playback_policy(project):
 
 
 def render_preset_evidence(resolve, project):
-    name = "Hotion Harness Bridge delivery check " + str(uuid.uuid4())
+    name = "Motion Harness Bridge delivery check " + str(uuid.uuid4())
     require(project.SaveAsNewRenderPreset(name), "CAPABILITY_UNAVAILABLE", "无法核对导出预设的缓存策略。")
     try:
         with tempfile.TemporaryDirectory(prefix="mh-bridge-preset-") as directory:
@@ -910,7 +872,7 @@ def create_render(resolve, project, scope, params):
     previous = project.GetCurrentTimeline()
     before_jobs = project.GetRenderJobList() or []
     require(not any(os.path.realpath(job.get("TargetDir", "")) == os.path.realpath(os.path.dirname(path)) and job.get("OutputFilename") == os.path.basename(path) for job in before_jobs), "TARGET_OCCUPIED", "输出位置已被其他队列项占用。")
-    backup = "Hotion Harness Bridge restore " + str(uuid.uuid4())
+    backup = "Motion Harness Bridge restore " + str(uuid.uuid4())
     require(project.SaveAsNewRenderPreset(backup), "CAPABILITY_UNAVAILABLE", "无法保存原有导出配置，未修改设置。")
     job_id = None
     try:
@@ -1131,8 +1093,7 @@ def entry_target(resolve, project, scope, params):
         source = ofx_source_target(resolve, {"scope": scope, "mediaPoolItemId": selection.get("mediaPoolItemId"), "path": selection["path"]})
     if not selection.get("timelineId") and not selection.get("itemId"):
         require(source is not None, "INVALID_REQUEST", "素材级入口需要源视频路径。")
-        media = media_for(project, selection.get("mediaPoolItemId"))
-        return {**source, "projectName": project.GetName(), "name": media.GetName()}
+        return {**source, "name": source["clipProperties"].get("Clip Name") or ""}
     timeline = timeline_for(project, selection.get("timelineId"))
     found = [item for track in range(1, timeline.GetTrackCount("video") + 1)
              for item in timeline.GetItemListInTrack("video", track) or []
@@ -1162,7 +1123,7 @@ def inspector_operation(resolve, params):
     # A composition imported through the API is not an Edit-page Fusion effect.
     # Keep the graph experiment separate from the product's Inspector entry.
     require(params.get("remove") or params.get("compositionOnly") is True, "CAPABILITY_UNAVAILABLE",
-            "ImportFusionComp 不能创建 Edit 检查器效果，请通过原生特效库应用 Hotion Harness Bridge 模板。")
+            "ImportFusionComp 不能创建 Edit 检查器效果，请通过原生特效库应用 Motion Harness Bridge 模板。")
     identity = params["identity"]
     require(identity.get("schemaVersion") == 1, "INVALID_REQUEST", "检查器入口身份版本无效。")
     selected = selection_snapshot(resolve)
@@ -1197,7 +1158,7 @@ def inspector_operation(resolve, params):
     before = timeline_snapshot(project, scope, timeline, resolve)
     targets = [value for value in before["items"] if value["id"] == item.GetUniqueId()]
     require(len(targets) == 1 and not targets[0]["unsupported"] and not targets[0].get("trackLocked"),
-            "UNSUPPORTED_TIMELINE_ITEM", "实验入口只接受完整读回通过、未锁定的普通 Hotion Harness 片段。")
+            "UNSUPPORTED_TIMELINE_ITEM", "实验入口只接受完整读回通过、未锁定的普通 Motion Harness 片段。")
     with open(params["compositionPath"], "rb") as stream:
         data = stream.read()
     require(hashlib.sha256(data).hexdigest() == params["compositionSha256"] and data.startswith(b"-- MH Resolve Bridge inspector v1\n"),
@@ -1272,7 +1233,7 @@ def dispatch(resolve, operation, params):
                 "scope": scope_for(manager, project) if project else None,
                 "timelines": [{"id": t.GetUniqueId(), "name": t.GetName()} for t in timelines(project)] if project else [],
                 "adapter": "documented-python-scripting", "officialMcp": "not-tested-by-scripting",
-                "replacement": "stable-playback-file-with-native-speed-and-otio-check" if validated_host(resolve) else "host-build-unverified",
+                "replacement": "stable-playback-file-with-media-identity" if validated_host(resolve) else "host-build-unverified",
                 "frameConvention": "half-open" if validated_host(resolve) else "unverified",
                 "profile": {"platform": sys.platform, "architecture": platform.machine(), "basicBridgeValidated": validated_host(resolve)},
                 "timelineReadback": "top-level-video; native speed/properties/fades and conservative OTIO structure check"}
@@ -1344,25 +1305,19 @@ def dispatch(resolve, operation, params):
         return status
     if operation == "media_identity":
         media = media_for(project, params["mediaPoolItemId"])
-        properties = media.GetClipProperty() or {}
-        result = {"scope": scope, "projectName": project.GetName(), "mediaPoolItemId": media.GetUniqueId(),
-                  "path": properties.get("File Path", ""), "metadata": media.GetThirdPartyMetadata() or {},
-                  "clipProperties": {key: properties.get(key) for key in ("Proxy Media Path", "Clip Name")},
-                  "validatedHost": validated_host(resolve)}
+        result = media_identity(project, scope, media)
         require_active_project(resolve, project)
         return result
     if operation in ("media", "bind", "replace"):
         media = media_for(project, params["mediaPoolItemId"])
-        before = media_snapshot(project, scope, media, resolve)
         if operation == "media":
-            return before
+            return media_snapshot(project, scope, media, resolve)
+        before = media_identity(project, scope, media)
         require(not project.IsRenderingInProgress(), "RESOLVE_BUSY", "Resolve 正在导出，桥接没有修改媒体。")
         require(validated_host(resolve), "CAPABILITY_UNAVAILABLE", "该 Resolve 平台与构建尚未验证自动修改的帧边界。")
-        require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "Resolve 媒体或使用位置已变化。")
+        require(before["fingerprint"] == params["expectedFingerprint"], "VERSION_CONFLICT", "Resolve 原素材的身份、关联或媒体规格已变化。")
         if operation == "replace":
             repair = params.get("offlineRepair")
-            allowed = {"offline-media-reference"} if repair else set()
-            require(before["usageScanComplete"] and not any(set(i["unsupported"]) - allowed for i in before["uses"]), "UNSUPPORTED_TIMELINE_ITEM", "已剪片段包含不能完整核对的处理，未重连新版本。")
             path = os.path.realpath(params["filePath"])
             publication = params.get("publication")
             require(publication or os.path.isfile(path), "ARTIFACT_MISSING", "新产物不存在。")
@@ -1372,22 +1327,21 @@ def dispatch(resolve, operation, params):
                         "RECOVERY_CONFLICT", "离线搬迁修复只允许原绑定、原产物身份和已记录的旧路径。")
                 require(file_digest(publication["sourcePath"] if publication else path) == repair["sha256"],
                         "ARTIFACT_CHANGED", "搬迁媒体与记录摘要不同。")
-            policy = before["playbackPolicy"]
-            require(str(policy.get("perfProxyMediaMode")) in ("0", "1", "2") and str(policy.get("perfOptimisedMediaOn")) in ("0", "1")
-                    and policy.get("perfRenderCacheMode") in ("none", "smart", "user"),
-                    "PLAYBACK_POLICY_UNVERIFIED", "原生代理、优化媒体或缓存设置无法完整读回，未修改工程设置。", policy=policy)
             require(not before["clipProperties"].get("Proxy Media Path"), "PROXY_UNSUPPORTED", "当前替换路径尚未验证已关联代理。")
             require(os.path.basename(path) == os.path.basename(before["path"]), "BASENAME_CONFLICT", "安全重连要求版本目录中的文件名保持一致；未修改现有素材。")
             if publication:
                 require_active_project(resolve, project)
+                require(media_identity(project, scope, media)["fingerprint"] == before["fingerprint"],
+                        "VERSION_CONFLICT", "发布前原素材的身份或关联已改变。")
                 # Require the still-current metadata; no selection or effect-stored ID is consulted.
                 old_link = json.loads(before["metadata"].get("motionharness.bridge") or "{}")
                 new_link = json.loads(params["metadata"].get("motionharness.bridge") or "{}")
                 require(not old_link or all(old_link.get(k) == new_link.get(k) for k in ("schemaVersion", "bindingId", "sourceId")),
                         "BINDING_CONFLICT", "素材的关联身份已经改变。")
-                if old_link and os.path.realpath(before["path"]) == path:
-                    ofx_source_target(resolve, {"scope": scope, "mediaPoolItemId": media.GetUniqueId(), "path": path})
                 publish_playback(path, publication, before["path"])
+            require_active_project(resolve, project)
+            require(media_identity(project, scope, media)["fingerprint"] == before["fingerprint"],
+                    "APPLY_OUTCOME_UNKNOWN" if publication else "VERSION_CONFLICT", "重连前原素材的身份或关联已改变。")
             require(project.GetMediaPool().RelinkClips([media], os.path.dirname(path)), "APPLY_OUTCOME_UNKNOWN", "Resolve 未确认重连版本目录，需读回核对后处理。")
             # Clip interpretation belongs to the existing cut. Relinking may
             # re-read container defaults; preserve the user's native settings.
@@ -1400,21 +1354,10 @@ def dispatch(resolve, operation, params):
             require(all(readback.get(key) == before["clipProperties"].get(key) for key in ("Alpha mode", "Input Color Space", "Input Gamma", "Data Level", "PAR", "Field Dominance", "Clip Name") if key in before["clipProperties"]),
                     "APPLY_OUTCOME_UNKNOWN", "媒体解释读回与替换前不同，需核对原生状态。")
         set_metadata(media, {**before["metadata"], **params["metadata"]})
-        if operation == 'replace':
-            for use in before['uses']:
-                if not use.get('intrinsicEntry'):
-                    continue
-                target = timeline_for(project, use['timelineId'])
-                with timeline_context(resolve, target):
-                    matches = [i for i in target.GetItemListInTrack('video', use['track']) or [] if i.GetUniqueId() == use['id']]
-                    require(len(matches) == 1 and intrinsic.read_entry(matches[0], {media.GetUniqueId(): media}),
-                            'APPLY_OUTCOME_UNKNOWN', '素材已替换，但原生入口或画面引用在更新期间发生变化。')
-                    intrinsic.refresh_media(matches[0], media)
-        after = media_snapshot(project, scope, media, resolve)
+        after = media_identity(project, scope, media)
+        require_active_project(resolve, project)
         if operation == "replace":
-            def edits(uses):
-                return [{**item, "unsupported": [reason for reason in item["unsupported"] if not repair or reason != "offline-media-reference"]} for item in uses]
-            require(os.path.realpath(after["path"]) == path and edits(before["uses"]) == edits(after["uses"]), "APPLY_OUTCOME_UNKNOWN", "替换后的路径或剪辑使用位置读回不一致。")
+            require(os.path.realpath(after["path"]) == path, "APPLY_OUTCOME_UNKNOWN", "替换后的原素材路径读回不一致。")
             for key in ("FPS", "Frames", "Resolution", "Audio Ch", "Input Color Space", "Input Gamma", "Data Level"):
                 require(before["clipProperties"].get(key) == after["clipProperties"].get(key), "APPLY_OUTCOME_UNKNOWN", "替换后媒体规格或颜色解释改变。", property=key)
         return after