# 2026-06-29 QuickSearch 修复

## 用户目标

- 修复重大回归：Quick Search 列出的应用点击或按 Return 都打不开。
- 不把未验证成果交给用户测试；需要 QA 自己实际按快捷键 / 操作验证。

## 当前起点

- 工作区已有 Pro 自定义快捷键、Pro UI、标签颜色、备注额度等多处未完成/未提交改动。
- 本轮只处理 Quick Search 启动阻断回归，不回退无关改动。
- 参考源码入口：`src/Apptag/ApptagApp.swift`、`src/Apptag/QuickSearch.swift`、`src/Apptag/ContentView.swift`。

## 根因与修复

- 点击路径：Quick Search 打开时，本地 mouse monitor 对 `overlayWindow` 内部鼠标事件发 dismiss 并 `return nil`，会吞掉结果行点击，导致行内 `mouseDown -> onLaunch` 不可靠。
  - 修复：`installQuickSearchLocalMouseMonitor()` 对 `event.window === overlayWindow` 直接 `return event`，让事件继续传给 Quick Search 行视图。
- Return 路径：Quick Search 面板原先是 `.nonactivatingPanel`，并且只依赖 field editor/keyDown/delegate 路径，某些场景 Return 不可靠。
  - 修复：Quick Search 面板去掉 `.nonactivatingPanel`，展示时先 `NSApp.activate(ignoringOtherApps: true)` 再 `makeKeyAndOrderFront`。
  - 修复：`QuickSearchTextField` 增加 `NSControl.target/action`，`submitAction` 兜底发出 `.submit`。

## 文件变更

- `src/Apptag/ApptagApp.swift`
  - 本地 Quick Search mouse monitor 不再吞 overlay 内事件。
- `src/Apptag/QuickSearch.swift`
  - Quick Search panel 改为可激活 key panel。
  - 文本框增加 Return submit target/action fallback。
- `src/Scripts/quick_search_launch_contract_qa.sh`
  - 新增静态 contract QA，防止点击/Return 启动链再次断开。
- `CODEGRAPH.md`
  - 补充 Quick Search 启动路径保护边界和新增 QA 入口。

## QA 证据

- 真实 GUI 验证：
  - 使用 build 版 `src/build/TagLauncher.app`。
  - 当前测试环境的 Quick Search effective hotkey 为 `Option+Space`。
  - 打开 Quick Search，点击输入框，粘贴 `Grapher`，按 Return；验证 `Grapher` 进程启动：通过。
  - 重新打开 Quick Search，粘贴 `Grapher`，点击第一条结果；验证 `Grapher` 进程启动：通过。
- 脚本验证：
  - `bash src/Scripts/quick_search_launch_contract_qa.sh`：通过。
  - `bash src/Scripts/quick_search_system_app_qa.sh`：通过。
  - `bash src/Scripts/quick_search_app_name_qa.sh`：本机未安装 `/Applications/贝锐向日葵被控.app`，脚本按预期跳过。
  - `bash build.sh`：通过，产物 `/Users/ar/Projects/Taglauncher/src/build/TagLauncher.app`。
  - `git diff --check -- src/Apptag/ApptagApp.swift src/Apptag/QuickSearch.swift src/Scripts/quick_search_launch_contract_qa.sh CODEGRAPH.md`：通过。

## 清理

- 已退出测试打开的 TagLauncher 和 Grapher 进程。
- 已删除临时 QA App：`~/Applications/TagLauncherQuickSearchQATarget.app`。
- 已删除 `/tmp/taglauncher-quicksearch-qa-marker`。
- 已删除调试期间写入的 `diagnosticLoggingEnabled` defaults key，恢复未设置状态。

## DMG 验收候选包

- 用户追问后补充生成 DMG：`/Users/ar/Projects/Taglauncher/src/build/TagLauncher.dmg`。
- 包类型：验收候选临时 DMG；当前工作区仍有未提交源码/文档改动，所以不能称为正式可回滚发布包。
- DMG 内容验证：
  - `hdiutil verify /Users/ar/Projects/Taglauncher/src/build/TagLauncher.dmg`：通过。
  - 挂载后检查包含 `TagLauncher.app` 和 `Applications` symlink：通过。
  - `codesign --verify --deep --strict` 挂载卷内 `TagLauncher.app`：通过。
  - 版本：`8.2.2`。
  - Build：`20260629.1338`。
  - DMG 大小：`6.0M`。
  - SHA256：`114cd9dc4109c6e980cc32e75cd7966d77b4b8db06541a021870cc99eef1bba4`。

## 未覆盖风险

- 旧 `window_logic_qa.sh` 仍偏窗口层级检查，不是完整 launch 端到端断言；本轮新增了静态 contract QA，并用真实 GUI 测试补充 launch 证据。
- 本轮没有改动无关 Pro 功能/UI 工作区改动，也没有回退当前工作区中已有的大量文档/Release 删除状态。