From edfb74b171f51d4beaa9926e27d2d80791fbf43c Mon Sep 17 00:00:00 2001 From: mac Date: Sun, 1 Nov 2026 21:26:08 +0800 Subject: [PATCH] docs: hand off mask tracking and repeatable tool instances from verified 1.3.1 baseline --- README.md | 4 + RECOVERY.md | 4 + research/MaskTrackingAndToolStack.md | 95 ++++++++++++++++++++ 大鱼调色FxPlug4交接.md | 128 +++++++++++++++++---------- 4 files changed, 186 insertions(+), 45 deletions(-) create mode 100644 research/MaskTrackingAndToolStack.md diff --git a/README.md b/README.md index 27959a8..a76bf00 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,10 @@ LUT 缩略图浏览器使用宿主的独立可调整窗口:拖动标题栏移 五套主题跨实例记忆。风格 LUT 网格打开缩略图浏览库;用户库为 `~/Movies/大鱼调色LUT/look LUTs`。后台扫描、导入、解析、预览、取消和最后一次选择生效的机制保留;支持既有 UTF-8/16/32 与旧编码 Cube 兼容。用户文件不进入源码或安装包。 +## 下一阶段 + +用户计划增加每工具蒙版、蒙版跟踪和可重复添加工具,例如第二个独立 HSL。这些功能尚未在当前版本实现;接手入口为 [最新交接](大鱼调色FxPlug4交接.md) 与 [续作方案](research/MaskTrackingAndToolStack.md)。 + ## 验证与恢复 - [本轮交接](大鱼调色FxPlug4交接.md) diff --git a/RECOVERY.md b/RECOVERY.md index d67f0ca..546538d 100644 --- a/RECOVERY.md +++ b/RECOVERY.md @@ -200,3 +200,7 @@ python3 Packaging/build_pkg.py --pkg-forge-repo /实际/PKG工坊源码目录 -- 正式包 `../发行包/大鱼调色-1.3.1.pkg`,14,073,683 字节,SHA-256 `954b10c581f31d23a8c417a6f37b24fae19939786dce8733b4d6f09c7ed3adae`。PKG 公证 `85cad776-c3d7-4037-9643-24041b269002`,Accepted;Installer 团队 B3W25FX5H5、可信时间戳、票据、Gatekeeper 和 20 项真实展开验包通过。包内 APP 与已验收的正式安装一致,APP 实际编译 `dbb7ca4a995ef832178a32f35939aed7d3a85012`;未重复执行系统安装。 正式 Release 已发布并完整下载校验:[1.3.1 Release](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.3.1-browser-recents-20261101),Release ID 366、附件 ID 12;标签提交 `281721bda11484c23f294b4f0d9e0b30ef829288`,APP 编译 `dbb7ca4a995ef832178a32f35939aed7d3a85012`。附件 14,073,683 字节,SHA-256 `954b10c581f31d23a8c417a6f37b24fae19939786dce8733b4d6f09c7ed3adae`。草稿经已登录会话完整下载校验后发布,正式链接再次完整下载校验;只上传一次并复用同一附件。临时下载副本已核实清理,正式发行包保留。交付标签远端独立恢复 184 文件与 full/strict fsck 通过,见 verification/BrowserReleaseRecovery.json。 + +## 蒙版、跟踪与可重复工具的文档交接(2026-11-01) + +文档整理前 main 为 `bbdd47d1d74e241f1f144bb2c245204e86973b3f`。交接标签 `handoff-mask-tracking-tools-20261101` 保存最新 `大鱼调色FxPlug4交接.md` 及 `research/MaskTrackingAndToolStack.md`,区分正式 1.3.1(19)与尚未实现的多个独立 HSL、每实例蒙版和跟踪。本文档提交未重新构建、安装或发布 APP/PKG,不移动原发行标签;父级“大鱼调色盘”只读参考。接续时保护用户当前窗口、布局、LUT 选择和工程。 diff --git a/research/MaskTrackingAndToolStack.md b/research/MaskTrackingAndToolStack.md new file mode 100644 index 0000000..7b13a35 --- /dev/null +++ b/research/MaskTrackingAndToolStack.md @@ -0,0 +1,95 @@ +# 续作方案:工具实例、蒙版与跟踪 + +2026-11-01。**这是下一阶段方案,尚未实现。** 用户明确要增加蒙版、跟踪和可添加工具,并举例“一层 HSL 不够,再加一个 HSL”。本文的具体类型、按钮和实施顺序为建议,不把参考库现有全部功能自动扩为新产品的承诺。 + +## 一、先解决多个 HSL 的身份和执行问题 + +当前固定 HSL 在 `DYModel.mm` 注册,使用 `DYUniforms` 的一组 `hsl*` 字段,`DYColorTables.mm` 构造一份 24 参数 HSL 查表。`DYGrade.metal` 调用融合的 `dy_grade`,蜘蛛盘随后执行。CST 位于原有显示域调色链之前。 + +推荐为可添加工具建立统一实例模型;先开放 HSL,一旦成立再扩展支持的类型。一个实例至少保存稳定 UUID、工具类型及版本、名称、启用状态、混合强度、独立参数和其蒙版引用;作者文档保存有序实例列表。显示名称和列表位置都不能代替身份。 + +界面最小闭环:添加工具 → HSL → 出现第二张独立 HSL 卡片 → 调整各自参数 → 单独启停/折叠 → 保存重开仍互不覆盖。复制、删除、重命名、排序是适合此模型的后续操作建议;若本阶段提供,均须使用同一作者状态和单次宿主撤销。 + +折叠只写 `folds[nodeID]` 一类界面状态,眼睛写实例启用;不能共用现有 `folds["hsl"]`。所有控件回调、异步加载、选中目标和 Undo 都绑定 nodeID + 参数键,不能绑定可能因插入/删除变化的数组下标。 + +### 渲染与旧参数的适配 + +先写清工具顺序和每个阶段的颜色域。保持 CST 输入/一级/输出的现有全局前段;新增 HSL 不应再执行一次 CST 或其它全局调整。当前固定链有融合内核,**不能为每个工具直接重复调用整个 `renderSource`**,否则会重复曝光、LUT、统计或空间处理。 + +原固定 HSL 可用稳定的兼容实例映射到原参数 ID,以保留旧工程和已有宿主动画;新增 HSL 必须有自己的参数存储与缓存。若需要将原链拆成可重排阶段,先做旧路径与拆分路径数值回归,再让新文档使用新计划。若先采用附加工具段,也必须在界面和文档明确其实际执行位置,不能让 UI 顺序与渲染顺序不同。 + +无新增状态的旧工程必须沿用原路径;显式迁移后记录格式版本,避免同一 HSL 同时从旧融合链和新实例链执行两次。旧参数 ID、枚举值、944 字节 ABI 前缀不能重排。新工具使用中性参数时应直通;关闭工具、混合为零或空新增列表应恢复原结果。 + +每个实例的查表/中间纹理缓存至少按 device、类型、完整有效参数和相关域信息隔离。第一层调值不能污染第二层。建立完整帧/分块、半透明、负值/HDR、重排以及连续多实例的检查,不把“面板能多开”当成多工具渲染已完成。 + +## 二、作者状态、动画和预设先定合同 + +本项目现有 `DYAssetState` 在参数 9001,标志含 `NOT_ANIMATABLE`。可以保留它存 LUT/蜘蛛盘资源;若新增工具参数需要宿主关键帧,须另行选择可动画的参数方案或明确时间化作者状态,不能直接塞入 9001 后默认为支持关键帧。 + +需区分:宿主可动画参数、工具/蒙版作者数据、逐帧求值后的不可变渲染计划,以及可丢弃缓存。轨迹作者数据随工程保存,运行计划按给定 CMTime 求值,不能由 UI 当前播放头或可变全局选择决定渲染。 + +所有新增类型应覆盖 NSSecureCoding 白名单、copy、isEqual、hash、验证、资源路径、预设、宿主归档和渲染状态。当前 InspectorToken schema 2、预设 JSON v3、临时 render-state schema 1 分属不同格式。不要用一次任意“schema++”代替各格式的明确迁移。 + +对新数据设置数量/大小/嵌套上限,验证有限数值、合法工具类型、UUID 唯一和引用完整性。失败加载保持旧作者文档;不加载任意类。必要时为当前插件增加明确文档格式,而不是依赖不可版本化的 UI 对象。 + +## 三、把蒙版绑定到工具实例 + +建议先移植矩形、椭圆和闭合钢笔;羽化、反转、强度和组合规则应有明确数学定义。其它 HSL/亮度键、人物或外部蒙版只作为父库的后续候选,未获本轮逐项指定。 + +每个工具保存自己的蒙版列表和当前蒙版 ID。首阶段优先正常混合:`output = mix(toolInput, toolResult, clamp(maskCoverage * toolOpacity, 0, 1))`。多蒙版的加/减/交集顺序、无蒙版的覆盖语义、空路径和禁用蒙版的含义须先确定并测试。不要用一个全局蒙版同时影响所有 HSL。 + +CPU、Metal、预览和 OSC 共用坐标合同:源图/目的图范围、宿主 tile bounds、top/bottom origin、非方形像素、缩放/旋转及视图变换都要处理。计算蒙版不能依赖检查器或浏览器尺寸。保留 alpha,明确直通 RGB 与预乘 RGB 的转换和混合边界。 + +画面控件通过宿主的 OSC 机制绘制,使用当前效果实例和稳定工具/蒙版 ID 隔离。点击效果标题、开关显示控件、关闭工具窗口后是否保留轮廓等行为在正式 FCP 中验证。不要自建一张静帧预览来冒充宿主当前画面的编辑和跟踪。 + +## 四、跟踪移植的范围与易错点 + +父库正式68采用 Metal 图像金字塔/正反光流与确定性 RANSAC,输出位置、旋转和独立横纵缩放。其输出合同不包括透视/剪切。建议复用前向、后向、同参考帧双向和前后单帧;连续范围、单帧参考区间、取消行为均按精确帧长定义,不猜帧率。 + +从宿主分析接口取得实际源帧。当前 `lookLUTPreview` 只是 320×180 预览,不足以替代最终跟踪输入;也不能靠拖动播放头或缓存最后一帧伪造完整分析。需要检查、实现并验证 FxAnalyzer / FxAnalysisAPI 生命周期和真实帧调度。 + +分析开始时冻结效果实例、文档/工具/蒙版 ID、形状 revision、参考 CMTime、范围和帧长。每次结果发布验证目标仍匹配;切片段、切实例、删除工具、编辑蒙版或新一轮分析后,过时回调不得写回当前文档。 + +将手工键和自动轨迹分开保存;手工修正优先,合并只替换指定区间的可替换自动结果,保留区间外轨迹、羽化和强度动画。取消保留可信段;空结果不制造作者编辑。低置信度/丢失要有明确提示,不能静默填成功或持续外推。 + +**先读父库 `research/tracking-host-lifecycle.md`。** 它记录过提前返回后不收尾、跨 action 分组无效、预览刷新吃掉 Undo/Redo、旧实例在切片段后持续刷新等实际问题。当前可复用方案在准备好结果后,单个有效 action 内完成命名 Undo 起止和完整作者状态写入,然后 endAction;分析收尾保证一次,迟到/重复收尾不再编辑。别恢复早期58–67的已知问题流程。 + +## 五、参考库导航(只读) + +本次核对:`/Volumes/备份/大鱼调色/大鱼调色盘`,HEAD `f8950384e514685c8809fe8e8ee2dd5f16ad0bd7`;正式68源码 `d05994d5f4547687511bef524efe8c881e8a5c9c`。接手时先检查差异,若参考更新则固定并记录新节点。 + +| 参考入口 | 复用方向 | +| --- | --- | +| `HANDOFF.md`、`verification/release-2.0.0-build68.json` | 正式68的真实完成范围与宿主证据 | +| `Sources/DYSettings.h/.mm` | 作者文档、图层、每层蒙版与归档 | +| `Sources/DYPanelLayers.inc` | 图层/工具列表操作与编辑目标 | +| `Sources/DYMaskState.h/.mm` | 精确 CMTime、手动/自动键、形状与变换求值 | +| `Core/DYMask.h`、`DYMaskOperator.h`、`DYLayerPlan.h` | 蒙版数学、组合/源阶段、渲染计划 | +| `Sources/DYPanelMasks.inc`、`DYInspectorMaskControls.inc` | 蒙版编辑器、宿主检查器入口 | +| `Core/DYTracker.hpp`、`Sources/DYMetalTracker.h/.mm` | 光流后端、RANSAC、结果/区间合并 | +| `Sources/DYPlugin.mm` | FxAnalyzer、目标冻结、取消/收尾、预览归属、Undo 提交 | +| `Sources/DYRenderer.mm`、`Shaders/DYColor.metal` | 计划执行、纹理与蒙版合成,需适配本项目 | +| `research/tracking-host-lifecycle.md` | 宿主生命周期、单 action 撤销和旧实例刷新防护 | +| `Tools/test_tracking.py`、`Tools/test_mask_refinement.py` | 参考测试和合成运动素材思路,不能替代本产品验收 | + +父库有独立 Bundle ID、参数表、1032 字节 DYGrade、作者格式和更大的产品范围。本项目为 1104 字节 DYUniforms。按功能适配源码,保留本产品颜色链和品牌/安装身份;不整仓覆盖、不盲抄 PID/结构体,不把父库已验收数量记成本项目通过。移入源码时记录来源节点、文件摘要与必要资源,构建不得依赖兄弟 APP 或另一目录运行时存在。 + +## 六、建议里程碑与验收 + +| 阶段 | 可交付行为 | 最低验收重点 | +| --- | --- | --- | +| A:两个 HSL | 独立添加、调值、眼睛和折叠;实例保存 | 不共用参数/缓存;旧工程画面不变;删除/插入不串目标;单次 Undo/Redo;重开与预设 | +| B:每实例蒙版 | 两个 HSL 分别影响不同区域 | 蒙版/羽化/反转/透明度 CPU–GPU 对照;原点、tile、4K与非方形画面;关闭精确旁路 | +| C:宿主控件 | 在 FCP 检视器画与改蒙版 | 当前实例隔离、真实拖动/绘制、工具窗口关闭后的行为、一次手势一次撤销 | +| D:跟踪 | 实际运动帧驱动对应蒙版 | 前后/双向/单帧;取消可信段;低置信度;手工键优先;精确 CMTime;切片段/旧回调隔离 | +| E:正式回归 | 保存、导出、性能与发行 | 冷重开轨迹完整一致;一次 Undo/Redo 的作者文档核对;旧预设/工程、CST/蜘蛛盘/LUT 回归;正式交付 | + +用本产品独立合成源验证平移、旋转、独立轴缩放、边界/透明、局部遮挡或目标离画;量化中心和尺寸误差,并区分算法样本与实机结果。对任意遮挡不能作无证据保证。导出后检查完整运动序列,不能只看静态首帧轮廓。 + +新增无蒙版、无逐帧依赖的逐像素 HSL 可表达为 LUT;空间蒙版和跟踪不能完整写入普通 3D Cube。到实现时应明确选择阻止完整导出、或让用户明确导出全局部分,并在 UI 说明;不得静默丢掉局部调色后仍称完整一致。 + +## 七、工作与交付边界 + +本轮只交接,不实现这些功能、不改变正式 1.3.1(19)。下一轮遵循 `/Users/mac/.codex/AGENTS.md`:先保护当前工作,保存并推送阶段检查点;构建/CLI 测试在固定缓存,用户可见测试走已签名公证的唯一正式安装。新增功能后递增版本/构建号,刷新模型模板,完整签名、公证、安装、FCP 验收、清理、PKG、Release 完整下载与远端恢复。 + +用户正在使用浏览器时,不为额外测试重启或复位其工程。优先用新合成测试库,完整保留其 LUT、预设、最近使用和现有轨迹。此任务不需要 NAS 后端部署,不新增生产服务。 diff --git a/大鱼调色FxPlug4交接.md b/大鱼调色FxPlug4交接.md index 28af2db..98459ac 100644 --- a/大鱼调色FxPlug4交接.md +++ b/大鱼调色FxPlug4交接.md @@ -1,76 +1,114 @@ -# 大鱼调色 FxPlug4:色轮复位、浏览器与最近使用交接 +# 大鱼调色:蒙版、跟踪与可重复工具交接 -更新时间:2026-11-01,Asia/Shanghai。 +更新日期:2026-11-01,Asia/Shanghai。本次只整理文档,未编译、替换或重新安装应用,也未操作用户正在使用的 FCP 窗口。 -## 当前 1.3.1(19):色轮复位、可调整浏览器与最近使用 +## 1. 下一阶段目标与当前边界 -实际编译 `dbb7ca4a995ef832178a32f35939aed7d3a85012`,APP 公证 `9e93dc7f-04a3-44f9-a1e4-792bd7b31533`,Accepted;票据、Gatekeeper、唯一正式安装与 FCP 12.4 加载通过。发行标签 `v1.3.1-browser-recents-20261101`,包目标 `../发行包/大鱼调色-1.3.1.pkg`。本版本发布结果见 verification/Package.json 和 verification/Release.json。 +用户最新需求:继续增加**蒙版、跟踪,以及自行添加工具的能力**。明确例子是:一层 HSL 不够时,可以再添加一个 HSL,分别调整。 -新实例及全部还原的输入默认为 Sony S-Log3(数学 ID 28)与 Sony S-Gamut3.Cine(27);输出 Gamma 2.4 / Rec.709、工作 DI/DWG 不变。一级白平衡的可见复位按钮只写方向和强度为零,保持双击复位与一次撤销。 +这里的核心是“同类工具可有多个独立实例”。新增 HSL 不能只是另一张面板共用原 HSL 的参数。蒙版应能绑定到具体工具实例,跟踪结果应驱动对应蒙版。 -浏览器在 CustomParameterAction scope 中取得并立即请求 FxRemoteWindowAPI_v2 的最小/最大尺寸窗口;首个子视图在 reply 返回前同步附着。当前 FCP 实测独立浮动窗口生效。支持网格/列表、缩略图大小、可拖动分隔条和按库保存的窗口/布局偏好;旧宿主保留可分离弹出框回退。窗口尺寸受宿主 80% 上限及屏幕约束。 +**上述功能尚未在“大鱼调色”实现。** 当前 1.3.1 是固定模块调色器;“大鱼调色盘”的图层、蒙版和跟踪代码只是下一阶段参考,不能把父库已完成的功能写成当前产品已完成。 -最近使用保存在当前 XPC 的 NSUserDefaults,key 以库的规范路径隔离;只记录成功且最新的宿主应用确认,失败、取消、过时回调不写。最多 40 个,去重最新优先,最近分类第一位,全部/文件夹也最近优先。首次打开可从已有当前 LUT 初始化;不能补造旧版本未记录的所有历史。LUT 文件不改动,历史偏好不进 Git/PKG。 +建议开发次序:工具实例和第二个 HSL → 每实例蒙版 → 宿主画面控件 → 蒙版跟踪 → 持久化、撤销和正式交付。设计、源码入口、迁移风险及验收清单见 [蒙版跟踪与工具栈续作方案](research/MaskTrackingAndToolStack.md)。其中标为“建议”的内容是接手方案,不代表用户已经逐项指定所有类型和操作。 -verification/BrowserNative.json 为正式路径 201 项;BrowserCustomization.json 为 23 项真实离屏 AppKit 窗口/布局/历史检查;BrowserRegression.json 含 3,025 项虚拟化、取消和应用确认回归。FCP 的 Sony 默认、可见复位、浮动窗口及系统缩放、两种布局、最近排序和关闭重开见 HostBrowserAndReset.json。自由标题栏/边缘拖动未由自动化独立确认;用户开始操作后保留当前状态,未再重启 FCP。Motion、Intel、旧系统未验收。 +## 2. 实际项目与可恢复节点 -远端独立恢复编译提交 178 文件、full/strict fsck 及 Metal 重建与正式库一致,见 verification/BrowserRecovery.json。恢复历史版本时仍使用其各自标签和验证记录,不把当前 Sony 默认替代历史中明确保存的设置。 +| 项目 | 当前值 | +| --- | --- | +| 主源码目录 | `/Volumes/备份/大鱼调色/大鱼调色` | +| 远程 / 分支 | `https://dayu.media/git/dayu/dayu-color.git` / `main` | +| 文档整理前 main | `bbdd47d1d74e241f1f144bb2c245204e86973b3f` | +| 本次交接标签 | `handoff-mask-tracking-tools-20261101`;最终提交可通过此标签解析 | +| 当前正式版本 | **1.3.1(19)** | +| APP 实际编译源码 | `dbb7ca4a995ef832178a32f35939aed7d3a85012` | +| 正式版本标签 | `v1.3.1-browser-recents-20261101` | +| 正式版本标签提交 | `281721bda11484c23f294b4f0d9e0b30ef829288` | +| 主 ID / 插件 ID | `com.dayu.color` / `com.dayu.color.XPC` | +| 唯一正式 APP | `/Library/Plug-Ins/FxPlug/大鱼调色.app` | +| 唯一 FCP 模板 | `/Users/mac/Movies/Motion Templates.localized/Effects.localized/大鱼调色/大鱼调色/大鱼调色.moef` | +| 固定构建缓存 | `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color` | +| 工程 / Scheme | `大鱼调色.xcodeproj` / `Wrapper Application`,Release | -历史 1.3.0 APP **1.3.0(18)**;实际编译源码 `c2818cbb1157093f80efd2a85cea0cf1509f565e`,Apple 公证 `5de714ac-dd28-4d2b-926f-6c0f424d0e5d`,Accepted,票据和 Gatekeeper 通过。后续文档和安装包提交不改变 APP 编译来源。 +工作目录、APP 编译提交、发行标签提交与后续文档提交是不同概念。恢复正式程序源码取编译提交;恢复含包记录的发行节点取版本标签;继续下一阶段从最新 main 或本次交接标签开始。已有历史版本、标签和安装包保留。 -## 项目身份 +## 3. 已交付行为,后续须保留 -- 源码:`/Volumes/备份/大鱼调色/大鱼调色`;远程 `https://dayu.media/git/dayu/dayu-color.git`,main。 -- 主 ID `com.dayu.color`,XPC `com.dayu.color.XPC`。 -- 唯一正式 APP `/Library/Plug-Ins/FxPlug/大鱼调色.app`。 -- 固定缓存 `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color`;Xcode scheme `Wrapper Application`,Release。 +- 一级调色将输入转换、工作空间、一级参数和输出转换放在一张卡片中。使用大鱼 CST 的固定源码数学取代新实例的输入还原 LUT;四个可见旁路选项已移除,一级眼睛统一启停。旧输入 LUT、旧参数 ID 和兼容解释仍保留。 +- 新实例及全部还原:输入 **Sony S-Log3(28)/ S-Gamut3.Cine(27)**;工作 **DaVinci Intermediate(10)/ DaVinci Wide Gamut(16)**;输出 **Gamma 2.4(1002)/ Rec.709(22)**;自动色调映射关闭。不要根据曲线名称覆盖用户手选色域。 +- 一级白平衡采用原 CST 色轮,保留原图、+104° 方位、/5 精细拖动、双击复位和方向键微调。底部可见“复位”只将该色轮方向、强度置零。原 BASIS 强度平方×4 的数学不变。 +- 蜘蛛盘来自“大鱼调色盘”,默认联动 6×6、31 节点;两轴可分别选择 6/8/12/16/24。固定、多选、同列自由点联动、整环/整列、复位、归档和 Cube 导出已接入。中性盘精确直通。 +- 新实例默认展开**一级调色、蜘蛛盘校色仪、基础调整**,其他模块折叠,全部眼睛打开。标题仅折叠,眼睛仅启停;状态独立保存。黑白混合默认 0%。 +- 风格 LUT 最多五层。库路径 `/Users/mac/Movies/大鱼调色LUT/look LUTs`。后台导入、取消、最后一次选择生效和 UTF-8/16/32 等编码兼容均保留。 +- LUT 浏览器在 FCP 中使用独立宿主浮动窗口。网格/列表、缩略图大小、可调整侧栏、窗口/布局偏好按库保存。最近使用分类第一位,成功应用后去重、最新优先,最多 40 个;全部及文件夹也优先显示最近项。旧版未记录的所有历史不能凭空补造;首次打开可从已有当前 LUT 初始化。 +- 33³ Cube 导出包含开启的 CST、一级白平衡、蜘蛛盘及其它逐像素色彩操作,遵循眼睛开关,折叠不影响导出;不含纹理、清晰度、去朦胧和逐画面统计。将来出现空间蒙版/跟踪后必须重新定义并明确提示导出边界。 -## 用户要求与实现 +## 4. 当前实现结构与兼容约束 -1. 大鱼 CST 输入转换 → 工作空间一级 → 输出转换已取代新实例的还原 LUT;三个阶段合并为一个一级调色卡片,曲线与色域独立选择。移除四个旁路选项,由一级眼睛统一启停。 -2. 一级白平衡改为原 CST 色轮,保留原图、+104° 方位、/5 精细拖动、圆形限幅、双击归零和 BASIS 强度平方×4,增加方向键微调。隐藏两根旧滑块;角度范围修正为 0–360°,旧值保持原解释。 -3. 直接移植父级“大鱼调色盘”的可变蜘蛛盘与 CPU/Metal 数学、固定、多选、同列联动、整环/整列及复位;点数 6/8/12/16/24,两轴可独立。中性盘精确直通,眼睛/混合独立,Cube 导出包含蜘蛛盘。 -4. 新实例与全部还原默认展开一级调色、蜘蛛盘校色仪、基础调整,其余折叠,所有眼睛开启。标题只折叠,小眼睛只启停,分别保存。用户“沉默展开”按“默认展开”实现。 -5. 蜘蛛盘完整网格、固定点、密度和联动状态随现有 DYAssetState 保存;预设 schema 3 写 JSON 网格,旧预设可读。旧阶段/旁路参数保留注册,仅打开旧工程不改变原画面;明确编辑 CST 或复位才清理旧旁路。 +| 文件 / 位置 | 接手用途 | +| --- | --- | +| `大鱼调色/Plugin/DYModel.h/.mm` | 234 个固定 float 参数、参数 ID、默认值、资产与界面归档 | +| `大鱼调色/Plugin/DYUniforms.h` | 当前 CPU/Metal 缓冲 1104 字节;原 944 字节前缀保持;CST 在偏移 944 追加 | +| `大鱼调色/Plugin/DYInspector.mm` | 固定卡片、标题/眼睛、预设 v3、LUT 提交与浏览器宿主 API | +| `大鱼调色/Plugin/DYNewPanels.inc.h` | 一级白平衡色轮、可见复位、蜘蛛盘面板 | +| `大鱼调色/Plugin/DYColorTables.mm` | HSL、白平衡、颜色分级等 LUT 构建与缓存 | +| `大鱼调色/Plugin/DYRenderer.mm` | CST 前段、固定调色链、蜘蛛盘、Metal 资源、预览、Cube 导出 | +| `大鱼调色/Plugin/DYGrade.metal`、`tools/kernels/*.ll` | Metal 边界和已版本化运算内核;当前固定调色链有融合执行,尚非工具栈 | +| `大鱼调色/Plugin/DYPlugIn.mm` | FxTileableEffect、按宿主时间生成渲染状态、归档白名单及导出 | +| `大鱼调色/Plugin/DYLUTBrowser.mm`、`DYLUTLibrary.mm` | 窗口/布局、异步确认、最近使用;不要混入工具作者数据 | -## 实现与来源 +当前两项 custom 参数:`9000 DYInspectorToken`(schema 2,folds 字典),`9001 DYAssetState`(LUT paths、spiderMesh、spiderLinked)。**9001 注册为 NOT_ANIMATABLE**,不能简单把动态工具塞进去就宣称支持宿主参数关键帧。预设 JSON 版本是 **3**;插件临时渲染状态的 schema 是 **1**;它们是不同格式的版本号。 -`DYNewPanels.inc.h` 是色轮/蜘蛛盘界面适配;`DYSpiderDisc.inc.h` 复用原盘交互,`SpiderCore` 复用原数学,`DYSpiderState.h` 管理归档与 JSON 验证。原 944 字节调色前缀和新增 CST 布局保持,控制尾部追加一级 master、蜘蛛 eye 和 mix。生产 shader 通过当前仓库内源码及已版本化 LLVM 重建。 +当前 HSL 只有一组 `hsl*` 固定字段和一份 HSL 查表。重复工具需要独立身份、参数、缓存和撤销目标。父库 `DYGrade` 是 1032 字节,与本项目 `DYUniforms` 不同;不能直接复制其参数号、POD、Bundle ID 或整个插件入口覆盖当前产品。 -参考仓库只读:大鱼 CST `973766b51dbcab3ab5092f1955d753575cd32d89`,大鱼调色盘 `f8950384e514685c8809fe8e8ee2dd5f16ad0bd7`。完整 SHA 摘要见 research/SpiderAndBalanceSources.json;边界见 research/SpiderAndBalanceIntegration.md。兄弟仓库和用户资料未改动。 +归档、预设、复制、相等性、hash、允许解码类和渲染状态都必须一起演进。旧字段与数学 ID 不重排;旧工程无新增状态时保留原画面。UI 折叠键在多工具场景下应按实例 ID 隔离,不能全部共用 `hsl`。 -## 验证 +## 5. 可复用参考:父级“大鱼调色盘” -- verification/SpiderAndBalance.json:正式安装路径 198 项,含真实离屏 AppKit 鼠标事件、撤销配对、归档/preset、9 组原 CPU/生产 Metal 蜘蛛盘像素误差 0、Cube 和 21 组独立 CST 对照。 -- verification/SpiderMath.json:25 种网格、204,683 项,CPU/Metal 最大相对误差约 1.79e-6。 -- verification/InstalledSelfTest.json:正式版常规 155 项。 -- verification/HostSpiderAndBalance.json:FCP 12.4 实际面板、默认、键盘调整、菜单撤销/重做、联动及 12×8 密度、固定和整环、眼睛/折叠、保存重开通过,最后恢复默认。坐标注入未激活远程控件,宿主拖动/双击未确认;不能拿离屏事件冒充该项已验收。 -- verification/SpiderRecovery.json:实际编译节点远端独立克隆 168 文件,full/strict fsck,重建 Metal 摘要与正式库一致;临时 clone 已清理。 +只读目录 `/Volumes/备份/大鱼调色/大鱼调色盘`;远程 `https://dayu.media/git/dayu/dayu-colorplate.git`。本次核对干净 HEAD `f8950384e514685c8809fe8e8ee2dd5f16ad0bd7`。其正式 2.0.0(68)编译源码为 `d05994d5f4547687511bef524efe8c881e8a5c9c`,标签 `v2.0.0-build68`。 -Motion、Intel、旧系统和宿主逐像素导出一致性未验收。 +先读父库 `HANDOFF.md`、`research/tracking-host-lifecycle.md` 及 `verification/release-2.0.0-build68.json`。该库记录了矩形/椭圆/闭合钢笔区域、前后/双向/单帧、位置/旋转/独立横纵缩放、取消保留可信段和一次撤销等实现与宿主证据。它输出仿射分解后的这些变换,不能宣传为透视/剪切跟踪或任意遮挡均可靠。 -## 交付和恢复 +下一阶段按具体功能复用其作者状态、蒙版数学、OSC 和 FxAnalyzer 生命周期适配,源文件导航见续作方案。父库现有交接另有胶片/CMS等任务,**不属于本次“大鱼调色”新增范围**。不改动兄弟仓库、不替换兄弟 APP、不恢复或覆盖其用户调色文件。 -版本标签 `v1.3.0-spider-balance-20261101`,正式包 `../发行包/大鱼调色-1.3.0.pkg`。本版本 PKG 公证与 Release 下载校验以 verification/Package.json 和 verification/Release.json 为准。历史版本标签和附件保持。 +## 6. 验证现状与用户工作保护 -源码检查点:`python3 tools/checkpoint.py '<说明>' <路径...>`;APP:`python3 tools/deliver.py`;PKG:`python3 Packaging/build_pkg.py --pkg-forge-repo /Users/mac/Documents/dayu-git/repositories/pkg-forge`;Release:`python3 Packaging/publish_release.py --tag v1.3.0-spider-balance-20261101 --notes Packaging/Release-1.3.0.md`。入口自带适用锁,勿外层嵌套获取同锁。 +| 证据 | 本版本实际覆盖 | +| --- | --- | +| `verification/InstalledSelfTest.json` | 正式路径常规 158 项原生检查 | +| `verification/BrowserNative.json` | 正式路径 201 项,含独立 CST 像素参照、色轮/蜘蛛盘、归档与渲染 | +| `verification/BrowserCustomization.json` | 23 项离屏浏览器、几何/布局/历史检查 | +| `verification/BrowserRegression.json` | 67 项回归,含 3,025 项目录虚拟化、取消及应用确认 | +| `verification/SpiderMath.json` | 25 种网格、204,683 项数学检查 | +| `verification/HostBrowserAndReset.json` | FCP 12.4 的 Sony 默认、可见复位、独立窗口及系统缩放、两种布局、最近排序、浏览器关闭重开 | +| `verification/BrowserRecovery.json` | 编译节点远端恢复 178 文件、fsck、Metal 重建与正式库一致 | +| `verification/BrowserReleaseRecovery.json` | 发行节点远端恢复 184 文件、fsck | -用户 LUT `~/Movies/大鱼调色LUT/look LUTs` 不导入、不删除、不打包。验收采用 tools/create_spider_host_fixture.py 生成的独立合成色卡和 1.12 DTD 校验,用户媒体和原有项目未编辑。完整恢复见 RECOVERY.md;凭据与签名私钥独立恢复。 +自由标题栏/窗口边缘拖动未由自动化独立确认。用户开始操作浏览器后,保留其当时的网格布局、约 197.97 缩略图大小、窗口位置和 LUT 选择,**未再次重启 FCP 或全部还原**。这些是当时观察,不是要求下一轮强制恢复的偏好;接手以用户最新操作为准。浏览器关闭重开已测,不写成此次已重新冷启动宿主。Motion、Intel、旧系统未验收。 -## 1.2.0 正式 PKG +测试库位于 `/Users/mac/Library/Caches/CodexBuilds/com.dayu.color/fcp-qa/大鱼调色_验收.fcpbundle`;本轮独立项目 `大鱼调色_1.3.1_浏览器与复位`。只读/引用现有 LUT,未导入或删除用户 LUT。新功能用独立合成运动素材验收,不修改用户正在工作的调色、跟踪或媒体。 -正式包 `../发行包/大鱼调色-1.2.0.pkg`,13,818,397 字节,SHA-256 `9fba4f0c1a313a6da8374b683f7e6b41af70388d7a7a180e26b9e236a9ba64a1`。PKG 公证 `c7b97b0f-57c8-45d3-a4d7-7db8e8694487`,Accepted;Installer 团队 B3W25FX5H5、票据、Gatekeeper 及 20 项展开验包通过。包内 APP 与已验收正式安装一致,未重复运行安装器。 +## 7. 正式交付与发布记录 -正式 Release 已发布并完整下载校验:[1.2.0 Release](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.2.0-cst-fold-20261101),Release ID 363,附件 ID 10。关联标签完整提交 `8074444259fbacc758ec003aa91a6331b6224a85`,APP 实际编译 `48b00c85799b0226ba32aba3f2e5397aa0e509ed`;附件 13,818,397 字节,SHA-256 `9fba4f0c1a313a6da8374b683f7e6b41af70388d7a7a180e26b9e236a9ba64a1`。草稿下载验证后才发布,发布后再次用上传器完整下载并回读核对;仅一次附件上传,未覆盖历史附件或移动标签。浏览器临时下载副本已按大小、摘要和来源核实清理,本地正式发行包保留。 +- APP 公证:`9e93dc7f-04a3-44f9-a1e4-792bd7b31533`,Accepted。 +- PKG 公证:`85cad776-c3d7-4037-9643-24041b269002`,Accepted。 +- 正式包:`/Volumes/备份/大鱼调色/发行包/大鱼调色-1.3.1.pkg`;14,073,683 字节。 +- SHA-256:`954b10c581f31d23a8c417a6f37b24fae19939786dce8733b4d6f09c7ed3adae`。 +- [1.3.1 Release](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.3.1-browser-recents-20261101),Release ID 366,附件 ID 12;附件下载链接见 `verification/Release.json`。 +- APP/PKG 的 Developer ID、票据、Gatekeeper、20 项展开验包通过。草稿与正式链接均完整下载校验,只上传一次。正式 APP 已安装,本轮未重复执行 PKG 安装器。 -## 1.3.0 正式 PKG +详细恢复与历史仍在 [RECOVERY.md](RECOVERY.md)。本次整理不修改上述正式发行标签、附件或程序版本。 -正式包 `../发行包/大鱼调色-1.3.0.pkg`,14,066,399 字节,SHA-256 `36c251722d3c9e4aaed8d5a09bf5afd3bf84039e9d1161c63635ab9d8224f506`。PKG 公证 `f6b25757-1e6b-4260-9667-5baecce8b3d4`,Accepted;Installer 团队 B3W25FX5H5、可信时间戳、票据、Gatekeeper 和 20 项真实展开验包通过。包内 APP 与已验收正式安装一致,未重复运行安装器。APP 编译源码 `c2818cbb1157093f80efd2a85cea0cf1509f565e`。正式包保留,临时展开副本由打包入口清理。 +## 8. 下一位接手的操作入口 -正式 Release 已发布并完成草稿、正式链接两次完整下载校验:[1.3.0 Release](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.3.0-spider-balance-20261101),Release ID 365,附件 ID 11,关联标签提交 `6528f888affe0acdd4292bc0c5ae0dac3a89b5a5`,实际 APP 编译 `c2818cbb1157093f80efd2a85cea0cf1509f565e`。附件 14,066,399 字节,SHA-256 `36c251722d3c9e4aaed8d5a09bf5afd3bf84039e9d1161c63635ab9d8224f506`;只上传一次,未覆盖历史附件或移动标签。草稿浏览器下载副本已按来源、创建时间、字节数和摘要确认后清理,正式发行包保留。标签远端恢复 172 文件、full/strict fsck 通过,见 verification/SpiderReleaseRecovery.json。 +1. 读取本文件、续作方案和本机 `/Users/mac/.codex/AGENTS.md`;核对 main、本地未提交改动、远端及同产品任务,保留用户正在操作的 FCP 状态。 +2. 先完成工具实例/参数/顺序/迁移合同,以“两个独立 HSL”形成可验收的第一阶段;避免先给所有模块套一个全局蒙版而日后重做。 +3. 再按续作方案接蒙版、OSC、精确时间分析、取消和单次 Undo/Redo。每阶段提交并立即推送;只暂存本任务文件。 +4. 模型修改后刷新模板:`python3 tools/build_template.py --refresh-model --overwrite`。 +5. 编译和 CLI 检查可在固定缓存执行;用户可见验收必须从正式安装的已公证版本进行。正式交付使用 `python3 tools/deliver.py`,它持有产品锁并等待宿主验收输入 `complete`。 +6. PKG 入口:`python3 Packaging/build_pkg.py --pkg-forge-repo /Users/mac/Documents/dayu-git/repositories/pkg-forge`。发布入口:`python3 Packaging/publish_release.py --tag <新标签> --notes <对应说明>`。不要复用本次版本号、覆盖旧包或移动旧标签。 +7. 产品身份、正式路径、逐层签名、公证、票据、PluginKit 唯一登记、生成副本清理、Release 完整下载及远端恢复都继续按全局约定执行。证书/profile/权限在下次发布时重新复核,凭据不进文档或源码。 -## 1.3.1 正式 PKG +可直接用于下一聊的任务描述: -正式包 `../发行包/大鱼调色-1.3.1.pkg`,14,073,683 字节,SHA-256 `954b10c581f31d23a8c417a6f37b24fae19939786dce8733b4d6f09c7ed3adae`。PKG 公证 `85cad776-c3d7-4037-9643-24041b269002`,Accepted;Installer 团队 B3W25FX5H5、可信时间戳、票据、Gatekeeper 和 20 项真实展开验包通过。包内 APP 与已验收的正式安装一致,APP 实际编译 `dbb7ca4a995ef832178a32f35939aed7d3a85012`;未重复执行系统安装。 - -正式 Release 已发布并完整下载校验:[1.3.1 Release](https://dayu.media/git/dayu/dayu-color/releases/tag/v1.3.1-browser-recents-20261101),Release ID 366、附件 ID 12;标签提交 `281721bda11484c23f294b4f0d9e0b30ef829288`,APP 编译 `dbb7ca4a995ef832178a32f35939aed7d3a85012`。附件 14,073,683 字节,SHA-256 `954b10c581f31d23a8c417a6f37b24fae19939786dce8733b4d6f09c7ed3adae`。草稿经已登录会话完整下载校验后发布,正式链接再次完整下载校验;只上传一次并复用同一附件。临时下载副本已核实清理,正式发行包保留。交付标签远端独立恢复 184 文件与 full/strict fsck 通过,见 verification/BrowserReleaseRecovery.json。 +> 先读“大鱼调色FxPlug4交接.md”和 research/MaskTrackingAndToolStack.md,从当前 1.3.1(19)继续。我要能添加多个独立工具,例如第二个 HSL,并给具体工具添加蒙版及蒙版跟踪。参考父级“大鱼调色盘”,保留当前 CST、折叠/眼睛、蜘蛛盘、LUT 浏览器和最近使用行为,保护已有工程和当前用户操作,分阶段验证并完成正式交付。