# CutFlow 1.1.4 验证记录

检查日期：2026-09-23。版本：1.1.4（build 16）。当前状态：build 16 修正菜单期间的窗口焦点校验、菜单项异步出现与多 Finder 窗口匹配，并补全深浅色遮罩；用户随后确认最终验证没有问题，同意发布。用户确认未附带逐场景测试记录，不能据此声称所有视图、外观及环境组合都完成了独立实测。

## 已复现的故障与修复

1. 1.1.3 安装版在权限可用时能收到真实 Command-X，诊断记录为“已将 ⌘X 转为复制”，但 Finder 不更新剪贴板，1.5 秒后超时；因为没有获取待剪切文件，淡化也不会启动。
2. 使用 AppKit 创建的内存按键事件复现：旧处理函数把键码改为 C，但转换回 NSEvent 后，characters 和 charactersIgnoringModifiers 仍为 x。新增回归测试在旧实现上出现两项失败。
3. build 9 使用新 CGEvent 并通过了上述字符回归测试，但真实键盘测试仍出现 Finder 复制超时，用户未看到淡化。不能将这个候选版记为修复成功。
4. build 10 真实测试仍失败。被动转发诊断证实替代事件已进入后续阶段、字符一致，但 Finder 仍未更新剪贴板。用户确认不淡化，主界面返回等待剪切。
5. build 11 改为按键回调结束后通过 AXPress 调用 Finder 自身的复制/移动菜单项，按快捷键属性匹配，不依赖中英文标题。执行前检查同一进程、窗口、文字焦点、有效剪贴板和取消令牌。菜单接受复制也必须等实际文件剪贴板产生后才建立待移动状态。
6. 原生菜单路径抑制对应按下、重复和抬起；文字保护、提前粘贴保护及文件剪贴板身份核对保留。失败原因现在显示在主状态中，不再仅回到“等待剪切”。
7. build 11 用户确认图标视图剪切和淡化有效，分栏/画廊剪切有效；PID 16924 的日志确认复制、捕获 1 个文件和移动命令均成功。用户随后澄清列表视图的目标行为：希望选中文件夹后直接粘贴进去，无需先双击进入；因此尚不能据此认定列表视图的剪切监听存在故障。
8. build 12 根据实际 AX 结构扩展 ListView、ColumnView、GalleryView，列表/分栏只匹配真实文件 URL；增加所选目标文件夹识别、原生打开、目录核对及异步移动。仅选中文件夹时的路径栏不能作为已进入目录的证据。

9. 用户确认 build 12 的所选文件夹粘贴有效，但会进入目标目录。build 13 改用文件项快捷菜单中的 `cmdMoveItemsHere:`，没有 Open/Back 导航路径。已在独立测试目录通过真实 Finder UI 验证：文件项右键或 Control-Return 菜单会移入目标并保留列表视图和选中状态；源消失，目标 SHA-256 保持一致。工具栏“操作”菜单同名命令仍针对当前目录，不能用于此功能。
10. 原地菜单只从文件视图内寻找，排除工具栏、全局菜单、服务和插件项；窗口、剪贴板、所选目录、取消代次在执行前再次验证。菜单未出现或不可用时停止，不执行替代移动。该原生 UI 证据尚不能替代 CutFlow 的完整键盘链路。
11. build 13 的失败诊断显示菜单弹出后焦点或 AX 选中行暂时不可读，旧代码把这当作目标变化并取消。build 15 在打开菜单之前核实目标；打开后继续核实剪贴板、剪切会话、前台应用和原 Finder 窗口，不再依赖菜单期间不稳定的焦点与选中行。还会等待物理 ⌘ 键松开才打开菜单，避免 Finder 按仍按住的修饰键构建不完整菜单。
12. 展开的列表视图会在祖先目录窗口展示子目录中的文件。淡化现在允许 AX 文件 URL 精确匹配子文件；若文件名文本没有 URL，会从同一文件行或其图标获取，排除展开的后代行。仍不按同名文件猜测身份。
13. build 15 的只读预览：隔离测试文件在简短列表中报告“已淡化 1 个可见项目”；用户此前的文件预览报告“无法唯一确认来源窗口”。Finder 同时存在多个大小相近窗口时，旧代码要求几何匹配恰好只有一个 Window Server 窗口，因而保守隐藏淡化。build 16 优先用真实窗口标题区分；标题不可用时使用最前面的几何匹配窗口，并在显示前再次核对层级。已选中文件行优先扫描，避免大型展开列表遍历超时。
14. 菜单闪现可能发生在 Finder 已打开菜单、但 `AXFocusedWindow` 暂时转给菜单或菜单项尚未填充时。build 16 在菜单打开后仅核对剪贴板、前台应用、剪切会话与取消令牌，且在 2 秒界限内等待可用的 `cmdMoveItemsHere:`，失效或超时仍不执行文件移动。深色 Finder 用深色遮罩，浅色 Finder 用浅色遮罩；系统外观变化时重绘。

## 本次已通过

| 范围 | 证据与边界 |
| --- | --- |
| Release 自动化回归 | build 16 的 121 项通过，包含菜单期间焦点/选中行暂不可读、菜单期间剪贴板变化、展开列表目录的 URL 匹配、相同尺寸 Finder 窗口的标题/前后顺序及深浅色遮罩回归；测试使用隔离剪贴板和内存事件 |
| AppKit 回归 | 旧版本失败的复制字符测试在修复后通过；移动事件在 AppKit 中保留 Option 修饰键，按下和抬起均验证 |
| 测试隔离 | 使用独立命名剪贴板和内存事件，不安装全局监听、不发送按键；不能替代物理键盘的完整链路验收 |
| 诊断 | 区分复制超时、文字保护、切换应用取消和文件捕获；历史限制为最近 8 条，不记录输入文本及剪贴板内容 |
| 打包 | Swift 6.4、macOS 27 上完成 arm64 / x86_64 Release 构建，合成通用二进制，部署目标 macOS 13.0；本地临时签名校验通过 |
| 安装和授权 | build 16 已安装到 `/Applications/CutFlow.app`，签名和可执行文件哈希与构建产物一致；用户报告最终验证无问题，但没有提供各视图逐项记录 |
| 系统设置窗口 | 修复对延迟创建 AppModel 的观察；重新启动后“CutFlow设置”窗口实际显示完整设置和就绪状态，不再为空白 |

已实测失败的 build 10 可执行文件 SHA-256（供复现）：

```
a94dd308ce42c1ade3ee8f05acd0eefe76df5ed3b73be23a4147427128396a64
```

## 仍待完成

- 重复操作下偶发菜单闪现失败率、同名冲突及撤销的完整 build 16 数据核对。
- 列表、分栏、画廊、图标视图与深浅色模式的逐项视觉证据；用户已确认整体验证无问题，但未提供逐场景记录。
- ForkLift、登录启动、Intel 真机、旧版 macOS、跨磁盘或网络盘、只读目录、大量文件及长时间运行。

## 历史验证（不能代替本版完整链路）

1.1.3 阶段，用 Finder 原生 Command-C / Option-Command-V 验证过多文件及文件夹移动、普通撤销、同名冲突停止和保留两者，检查了源路径和目标内容哈希。当时没有完成真实 Command-X 全局监听链路，之后用户复现了上述故障。“保留两者”后的撤销未确认通过。

## 分发与复现

按用户选择使用 ad-hoc 临时签名，未经 Apple 公证；首次打开和更新签名后的授权可能需要用户手动批准。GitHub Release 标签不代表 Apple 分发认证。Finder 负责文件移动、冲突及撤销，CutFlow 不直接改写、移动或删除文件。

```sh
swift test -c release
bash scripts/build.sh
```

事件测试需要当前 macOS 用户会话的 Pasteboard 服务。若隔离沙箱阻止此服务，应在正常本机会话中运行测试。构建脚本会查询 SwiftPM 的实际产物路径，适配不同构建引擎。