@motionharness/bridge-davinci 0.0.0-stage → 0.0.22

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Hotion Harness DaVinci Resolve Bridge (@motionharness/bridge-davinci)
+Copyright 2026 MH contributors
+
+This product includes software developed by MH contributors.
+The bridge implementation moved into this optional monorepo package retains
+its existing Apache License, Version 2.0 notices and previously granted rights.
+
+This distribution bundles third-party JavaScript dependencies. Their copyright
+and license notices are included in THIRD_PARTY_NOTICES.md; those dependencies
+are not relicensed by the Apache License.
+
+The native bridge is built against OpenFX 1.4 headers. Their original copyright
+and BSD license are included in OPENFX_LICENSE.

package/OPENFX_LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2003-2015, The Open Effects Association Ltd. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name The Open Effects Association Ltd, nor the names of its
+      contributors may be used to endorse or promote products derived from this
+      software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# Hotion Harness · DaVinci Resolve 可选组件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+时间线承载完整的普通视频，动效源码仍在 Hotion Harness 中编辑。主 CLI 提供 `mh bridge davinci`，Agent 同时使用达芬奇官方 MCP 处理实拍剪辑、音轨和原生变速。组件不启动另一套 MCP 服务。安装组件时一并安装固定菜单、简洁小窗和侧栏 OFX；给时间线片段自动附加 OFX 尚未提供。
+
+## 支持范围
+
+Studio 可发送和更新普通视频，支持透明合成；更新时核对源规格、片段状态与内容版本。Resolve 使用渲染完成的视频文件，不依赖 Studio 会话持续运行。
+
+当前 macOS 安装包包含桥接、固定菜单、简洁状态窗口和侧栏 OFX。侧栏读取效果自身的源视频路径，并核对当前工程的素材池身份及关联元数据，不依赖时间线选择。更新采用每个关联独立的固定视频路径；历史版本独立保存。旧关联首次更新会迁移到固定路径，旧效果若仍缓存旧路径会停止操作：保存并重新打开工程，或重新附加效果后再试，也可继续使用固定菜单。
+
+## 安装与恢复
+
+```sh
+mh bridge davinci install
+mh bridge davinci doctor
+mh bridge davinci status
+mh bridge davinci uninstall
+```
+
+组件与 SDK、CLI 使用相同版本号，由同一个正式 tag 发布。开发版本先运行组件的 `package` 命令，再执行 `mh bridge davinci install --package <输出的 packageDirectory>`。默认安装仅在明确请求后下载固定版本组件，主 CLI 不携带该依赖。安装会核对清单、CLI 版本和全部文件摘要，然后激活新版本。修复复用同一个命令；固定版本的本地安装包完整且兼容时直接复用，无需下载。非本组件文件或用户修改会保留并报冲突。卸载保留源工程、关联和不可变产物，也保留用户修改过的入口文件。运行中的任务会阻止卸载。
+
+修复或升级时，未重新指定工作目录便继续使用原目录。入口文件先完整暂存，再与组件激活记录一同登记；中断后重新安装会核对并恢复，外部修改保留且明确报错。损坏的组件版本会保留到组件目录内的 `quarantine`，再从已核对的安装包重建；不会删除源工程、关联记录或用户修改。
+
+组件需 Node.js 22.18+、Resolve Studio 的本机外部脚本访问，以及 FFmpeg/ffprobe；透明 ProRes 导出需要 FFmpeg 7 或更新版本。可用 `MH_FFMPEG`、`MH_FFPROBE` 指定已有可执行文件。安装和 `doctor` 不把依赖存在等同于实机验收通过。
+
+安装器只保存已解析的 Node、pnpm、FFmpeg、ffprobe 位置，供达芬奇菜单与后台进程启动时使用；不会复制终端中的凭据或完整环境。移动这些工具后重新运行安装命令修复。缺少 FFmpeg/ffprobe 时应先安装并运行 `doctor` 检查。
+
+后台任务会持续保护当前组件安装，使用其他工作目录的任务也在保护范围内。运行中尝试修复或卸载会立即返回 `TASK_BUSY`，查询和取消仍可使用。启动失败会保留原任务；`recover check` 只核对，修复原因后通过 `recover resume` 明确继续原任务。
+
+主 CLI 自动升级会先运行目标版本的只读兼容检查；已装组件不兼容或无法验证时停止升级并保留当前版本。组件清单可声明有上下界的 CLI 版本范围；旧清单继续要求版本完全匹配。
+
+后台任务的进程监督目前支持 macOS。Windows 暂无对应的进程监督实现，会在入队前返回 `WORKER_LEASE_REQUIRED`，不启动后台修改。
+
+工作目录默认为用户应用数据目录内的 `mh/bridge/davinci/workspace`。CLI 的 JSON 请求可明确指定 `workspace`；Studio 只操作本机宿主固定的目录。`MH_BRIDGE_DIR` 可用于隔离测试或管理指定的组件目录。
+
+## 侧栏入口
+
+运行 `mh bridge davinci install` 会一并安装菜单、小窗和 OFX。OFX 默认安装到 `/Library/OFX/Plugins`；系统目录需要权限时会请求 macOS 管理员授权，取消或失败会报告未完成，不能当作完整安装成功。安装后保存工程并重启 Resolve，给普通视频附加 Hotion Harness 滤镜。侧栏提供“编辑 Hotion Harness 工程”“更新此素材”“查看状态”和“更多…”。更新直接核对并固定目标，复用已有更新流程，影响该素材在当前工程中的全部引用。立即显示状态提示，重复点击复用正在进行的请求；不需要先打开管理窗口。效果中保存的 ID 和当前时间线选择都不能替代源路径、素材池身份及元数据的交叉核对，无法唯一确定时停止。
+
+自动附加、自动恢复被移除的效果和“不可单独删除”不在当前范围；用户按图文步骤自行添加侧栏，缺少视觉入口时仍可从固定菜单编辑、更新片段。新旧入口协议在升级期间并存，旧二进制仍可能给出过期路径提示，需重新启动 Resolve 才会加载新的原生入口。
+
+## Studio 流程
+
+日常操作直接使用侧栏的编辑、更新和状态按钮。没有添加侧栏 OFX 时，选中普通视频后仍可从「工作区 → 脚本 → Utility → Hotion Harness」使用“编辑工程”和“更新到达芬奇”。独立的“管理所选片段”菜单已移除；升级仅清理未被用户修改的自有旧菜单。
+
+组件安装后，Studio 导出面板并列显示“发送到达芬奇”。未安装时隐藏该按钮，旁边的说明提供安装命令。先打开目标 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 丢失时只允许继续核对，不盲目重发。重开导出面板会核对当前源内容、已应用版本和原生关联；该轻量核对不扫描时间线或切换达芬奇页面，完整引用检查仅在明确准备更新时进行。其他素材、多目标或纯渲染任务可继续观察，面板不会把它们当成当前素材已经更新。
+
+## Agent 从 Resolve 开始
+
+1. 用达芬奇官方 MCP 读取明确的工程和时间线，完成实拍剪辑，并取得插入目标。
+2. 用主 CLI 创建或修改可编辑 Hotion 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` 的结果是只读确认资料，不创建任务，也不渲染视频。
+
+显式管理接口还有 `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` 可按选中片段的稳定关联打开源工程。
+
+侧栏“更多…”按效果自身的源路径固定素材身份，后来切换选择不会把操作转给另一段素材。窗口直接提供该关联确实应用过的历史版本、指定时间线实例的独立副本（多处引用时先明确选择具体片段）、重新定位源目录和丢失元数据时的关联修复；目录面板只在明确点击相应操作后出现。恢复版本前显示会影响的引用数量，独立副本则明确只改变一个时间线实例。结果不明时先核对原任务，再明确选择继续原任务；原任务可能包含多个目标，不会被管理窗口缩成当前一段。
+
+默认构建和安装包同时包含菜单、小窗和图像透传 OFX。插件仅提供源工程入口和更新状态，不承载动效渲染。普通视频不会自动附加 OFX，`entry restore` 当前返回能力不可用；缺少或删除视觉入口不影响源关联，可以继续通过固定菜单和 CLI 管理。安装 OFX 与自动附加 OFX 是两个独立能力。
+
+安装器默认使用官方目录 `/Library/OFX/Plugins`；`MH_DAVINCI_OFX_DIR` 可指定受支持的位置。目录权限不足时通过随包权限准备程序请求系统授权，安装结果分别报告 OFX、菜单和小窗状态。升级或修复只处理已核对的自有文件；无法完成 OFX 安装时明确报错。原生窗口作为小型 AppKit 应用随包提供，不包含浏览器、Studio 或渲染引擎。
+
+`restore` 接受 `bindingId`、`artifactId`、`expectedRevision`、`idempotencyKey`，将同规格的历史视频复制到该关联的固定视频路径，核对目标后原子替换并刷新原素材，不覆盖动效源。当前源与旧版视频不同会如实显示过期。只丢失原生关联元数据时，可传 `associationOnly:true`、`bindingId`、`expectedRevision`、`expectedMediaFingerprint`、`idempotencyKey`：组件核对记录中的原生素材 ID、固定路径和完整文件摘要后只恢复元数据，已有其他身份时拒绝覆盖。`relink` 在源移动后核对源内容再更新位置。关联记录和目录都丢失时，需要从备份恢复或明确重新关联，不能仅凭同名文件猜测。
+
+`migrate --json '{"legacyWorkspace":"<旧目录>"}'` 只检查旧版记录，并返回可否迁移、阻止原因和 `legacyFingerprint`。旧目录有活动任务、结果不明的任务或正在使用的协作锁时，必须先处理原任务。加 `"apply":true` 才复制到空的新工作目录；可同时传入预览的 `expectedLegacyFingerprint`。复制后再次核对旧清单和目标清单，发生并发修改时保留已有记录并停止登记。完全相同的迁移可重复执行，会返回原回执，不覆盖导入后的新编辑。备份保留旧清单的全部任务历史，工作目录搬移后仍按相对位置定位。旧任务不会自动继续，旧生成器不会原地改造成普通视频。
+
+迁移回执同时登记旧入口的工作目录身份。较早的回执可在原迁移请求中显式增加 `registerLegacyEntry:true` 补登记，普通重复请求仍不修改记录。`legacy entry` 只读核对迁移备份、关联和当前选中片段，返回固定目标；它本身不安装旧共享启动器转发，也不打开工程。旧入口转发安装和专用 MCP 配置退役需分别显式执行，普通安装不会接管旧入口。
+
+`legacy retire entries --json '{"legacyWorkspace":"<旧目录>"}'` 只读预览共享 Lua 入口；确认后使用同一请求加 `apply:true`，并将预览的 `fingerprint` 填入 `expectedFingerprint`。仅接管能够按旧版模板逐字节复原、且已有完整迁移登记的入口。它转发点击时的片段身份到主 CLI 状态窗口；数据清单与原工程保留。旧任务、旧目录锁或预览后的文件变化会阻止接管。原 Lua 私有备份按路径与内容分别保留；之后修复沿用已登记的目标目录，卸载先核对并恢复原字节和权限，再移除新 helper。用户改动转发器或备份时停止自动修复、卸载。真实旧 Inspector 点击仍需宿主验收。
+
+`legacy retire mcp --json '{"legacyWorkspace":"<旧目录>","serverName":"mh-bridge"}'` 预览已迁移旧桥接的 Codex 用户级配置。确认后仅提交 `apply:true`、`previewId` 和 `expectedPreviewFingerprint`。组件通过 Codex 官方 `mcp get` 核对有效配置，再用 `mcp remove` 移除这一项，随后读回；不自行重写 TOML。仅支持已识别的直接 Node 启动结构，项目覆盖、未知启动包装及其他客户端会保留。私有回执只备份目标配置节，供核对和手动恢复；不备份其他 MCP 的凭据。结果不明时使用原预览回执再次查询，不重复执行移除，也不覆盖后来修改的配置。已完成回执的重放只返回历史结果。客户端可能仍缓存会话，移除配置不等于已停止旧 MCP 进程。
+
+迁入旧记录后，`legacy preview` 接受明确的 `scope`、`timelineId` 和可选 `itemIds`，逐项列出可转换对象、保留原因、整条时间线的复制限制和预览指纹。若任何 Fusion 片段不能完整转换或未在本次范围内，包括缺少旧关联记录、未知曲线、动态缩放或其他效果，则保留原时间线，不创建转换副本。时间线含非零视频淡入淡出时也会提前拒绝：当前宿主的 `SetFades` 保存重开行为尚不能保证保留。预览列出具体片段、轨道和原因，不自动补写属性或放宽识别条件。
+
+仅当整条时间线通过检查时，`legacy convert` 才接受预览返回的 `previewId`、`expectedPreviewFingerprint` 与新 `idempotencyKey`，复制时间线并在副本中把完全识别的自有生成器转换为普通视频；为它们复制视频字节并建立新媒体、新关联。执行前再次检查最终转换范围，未通过时不调用 `DuplicateTimeline` 或 `ImportMedia`。原时间线、原关联和旧产物保持。转换后先对照画面再使用新时间线；恢复方式是选择保留的原时间线，不覆盖用户在副本中的后续修改。中断时使用原 taskId 查询或 `recover`，不会为同一任务再创建一个副本。旧任务已发生的原生结果仍按原记录核对，新的保护不会把部分副本误报为已回滚。
+
+半途转换不能安全继续时，可明确执行 `recover --json '{"taskId":"...","action":"keep-original"}'`。组件只读核对原时间线仍保持后取消剩余步骤，结果列出保留的部分副本和已导入媒体；已有副本修改不会被叫作“已回滚”，也不会自动删除。
+
+独立副本若在依赖安装时失败，会保留源目录并说明达芬奇步骤尚未开始。此时 `recover check` 不会再次启动依赖安装；修复依赖后，`recover resume` 必须验证副本与原公开工程包的完整内容指纹一致，才继续同一任务，不重新解包或覆盖目录。若决定结束，`keep-original` 只在源副本未登记、没有新产物或原生事务记录，且原关联和时间线仍匹配时取消剩余步骤，返回 `partial-source-retained`。一旦已经进入原生实例事务，不能用此方式绕过事务恢复检查。
+
+旧生成器转换为实验性功能，仅支持完整识别、原速、同帧率、整数帧裁切且整条时间线可安全复制的对象。不保证任意旧 Fusion 工程均可无损迁移。不能完整转换的 Fusion 片段、非零视频淡入淡出及其他不支持项会阻止自动转换。组件不使用 DRT 导入绕过这些限制，也不自动重配旧合成。转换后的素材沿用原产物的核验状态，未核验的旧视频不会因复制而变成已核验。
+
+## 开发
+
+```sh
+pnpm --filter @motionharness/bridge-davinci build
+pnpm --filter @motionharness/bridge-davinci test
+```
+
+用 `pnpm --filter @motionharness/bridge-davinci package` 在根目录 `.tmp/` 制作独立安装包，不发布。构建生成自包含的 `dist/runner.mjs` 和文件摘要清单。公开包只带 runner、受支持的 Resolve 脚本和入口资源，不包含验证日志、机器路径、编辑器或另一套渲染器。临时验收文件统一放在仓库根 `.tmp/`；自动测试与真实 Resolve 验收分别记录。
+
+macOS 原生构建使用 `node packages/bridge/davinci/native/build.mjs`，生成通用 arm64/x86_64 的 `HotionHarnessStatus.app`、`HotionHarness.ofx.bundle` 和权限准备程序 `HotionHarnessInstall`。需要 Apple 命令行构建工具和 Resolve OpenFX 开发 SDK；`HOTION_OFX_SDK` 可指定 SDK 目录。二进制只输出到 `.tmp/`，不写入源码目录。
+
+默认 `package` 自动构建这些原生资源，也可设置 `MH_BRIDGE_NATIVE_BUILD=<完整构建目录>` 复用构建。缺少任一原生组件会停止打包。旧 `--experimental-ofx` 参数兼容保留，但不再改变包内容。开发机需要 SDK 和编译工具，用户安装发布包无需这些构建依赖。
+
+### 固定视频与更新恢复
+
+每个关联使用 `artifacts/media/<bindingId>/<文件名>` 作为播放文件，`artifacts/<artifactId>/` 保存独立的历史版本。渲染和完整视频校验成功后，先记录任务的目标、旧版本和新版本，再由原生脚本核对素材身份与剪辑状态，在同一目录原子替换播放文件，并通过 `RelinkClips` 刷新。不会覆盖历史文件或使用硬链接。渲染失败保留旧画面；发布后结果不明时保留原任务，不自动重新提交。通过管理窗口或 `recover` 核对已应用版本，只有原目标仍匹配才允许继续。
+
+固定路径不保证所有未知宿主版本和代理组合的行为。组件沿用已验证宿主范围，已关联代理、无法核对的媒体或不支持的时间线结构仍拒绝更新。普通视频暂停时可能保留旧帧，播放或移动播放头后才显示新画面；定格画面也可能保留旧版本。定格不因此阻止更新。状态小窗及管理窗口以一行次要文字提示“预览未刷新请播放；定格可能保留旧画面。”任务完成代表视频文件与关联已更新，不保证宿主预览已经重绘。管理窗口保留恢复版本、重新定位、修复关联等低频功能。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,196 @@
+# Bundled third-party notices
+
+The following installed packages contribute code to the self-contained runner. Their original license notices follow in full.
+
+## fflate@0.8.3
+
+License: MIT.
+
+### LICENSE
+
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## graceful-fs@4.2.11
+
+License: ISC.
+
+### LICENSE
+
+The ISC License
+
+Copyright (c) 2011-2022 Isaac Z. Schlueter, Ben Noordhuis, and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+## proper-lockfile@4.1.2
+
+License: MIT.
+
+### LICENSE
+
+The MIT License (MIT)
+
+Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+## retry@0.12.0
+
+License: MIT.
+
+### License
+
+Copyright (c) 2011:
+Tim Koschützki (tim@debuggable.com)
+Felix Geisendörfer (felix@debuggable.com)
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+
+
+## signal-exit@3.0.7
+
+License: ISC.
+
+### LICENSE.txt
+
+The ISC License
+
+Copyright (c) 2015, Contributors
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyright notice and this permission notice
+appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE
+LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+## smol-toml@1.9.1
+
+License: BSD-3-Clause.
+
+### LICENSE
+
+Copyright (c) Squirrel Chat et al., All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+## zod@4.3.6
+
+License: MIT.
+
+### LICENSE
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.