# QuickSearch

生成日期：2026-07-09

## 当前状态

- 主题说明：QuickSearch 相关会话的长期二级汇编；原始会话记录仍是证据源。
- 来源记录数：10
- 时间范围：2026-06-09 至 2026-08-28
- 最新记录：[`26.0830-Taglauncher.quicksearchfilter-TestFlight上传.md`](../26.0830-Taglauncher.quicksearchfilter-TestFlight上传.md)

## 最近结论摘录

- 基于前一轮排查，确认当前问题不应按中文个例打补丁，而应抽象为“用户可见显示名”和“搜索别名/内部标识”分层。
- 复查当前实现中 `AppInfo.localizedDisplayName(for:)`、`localizedNamesByLanguage`、`localizedNames`、`QuickSearchEngine.makeDocuments`、`L10n.supported` 和 Apple 默认应用目录的语言 fallback。
- 通用规律：一个 App 通常同时存在多种名称来源，包括当前语言本地化名、系统/Finder/Spotlight 显示名、Bundle 基础名、文件名、可执行名、bundle id 和 wrapper/helper 内部名。
- 产品显示名应优先使用“用户当前语种的本地化可见名称”；内部名只应作为搜索别名，不能优先显示。
- 嵌套 `.app`、helper、iOS-on-Mac wrapper 应归并到外层用户可见 App；内层标识最多参与搜索匹配，不应作为独立结果展示。
- 2026-08-28 `QSF-DEV-001` 实现 Quick Search 标签筛选 V1：搜索框下方、结果列表上方新增单行横向标签条；只显示 `全部` 与真实标签，排除未分类 / Mac 自带 / 不常用；标签筛选为运行时单选状态，不持久化；选中标签后与关键词搜索取交集，空搜索 + 标签列出该标签下 App，结果仍使用长条候选项。
- 2026-08-28 `QSF-CR-001` 独立代码审核通过，终态口令 `CR_PASS_QSF`。审核确认运行时单选、不持久化、不改 AppGrid / Pro / 数据结构；Return / Esc / 方向键、鼠标点击启动、IME composition 和焦点回到输入框契约未被破坏；后续仍需 QA 执行真实 UI / 视觉 / 鼠标 / IME 实机验收。
- 2026-08-28 `QSF-QA-001` 正式 QA 失败，终态口令 `QA_FAIL_QSF`。自动门禁通过，但真实 UI 发现 `全部` chip 不能稳定清除筛选，且含 `未分类` 等保护容器标签的数据触发 Swift fatal `Duplicate values for key: '未分类'`。QA PASS 前不得生成 8.4.0 可安装验收包。
- 2026-08-28 `QSF-QA-002` 返修复测通过，终态口令 `QA_PASS_QSF_FIX`。真实 UI 确认 `全部` chip 可稳定清除筛选，普通标签切换 / 同标签二次点击 / 标签 + 关键词交集 / 启动与关闭 / IME smoke 回归通过；保护容器 fixture 未再 duplicate-key 崩溃，保护名未进入 Quick Search 筛选条。PMO 消费后才能生成 8.4.0 可安装验收包。
- 2026-08-28 `QSF-PKG-001` 完成，终态口令 `LOCAL_TEST_READY_QSF`。`8.4.0 (20260828.1732)` 本地安装体验 DMG 已生成并通过基础验证；DMG 路径为 `/Users/ar/Projects/Taglauncher/03-O/C2.builds/LocalTest-8.4.0-20260828.1732/Archive/TagLauncher-8.4.0-build20260828.1732-localtest.dmg`，SHA256 为 `76647a1133fbb96abdb8dd0531dc83819ac58815057071671204b746b781070f`。
- 2026-08-28 用户安装体验 `8.4.0 (20260828.1732)` 后确认“没有找到问题”。PMO 随后完成正式冻结，终态状态 `ASC_UPLOAD_READY_QSF`：正式上传包为 `/Users/ar/Projects/Taglauncher/03-O/K3.运营与发布资料/Release/AppStore-8.4.0-20260828.2219/Upload/TagLauncher-8.4.0-build20260828.2219.pkg`，SHA256 为 `0d374a03b25c11a4bf9bad19238defd7c3043b72386ee70f7857e01f4f9d6318`。
- 2026-08-30 `QSF-ASC-001` 完成，终态口令 `TESTFLIGHT_INTERNAL_READY_QSF`。`8.4.0 (20260828.2219)` 已上传 App Store Connect，Delivery UUID `482c12a7-543d-4dab-afac-aa4e1b4bb6d0`，Apple 返回 `VALID` / `BETA_INTERNAL_TESTING`，下一步由 Owner 通过 TestFlight 测试几天。

## 核心事实补录

### 2026-06-09 legacy/codex-20260610/session-history/2026-06-09-helper过滤补强.md

```text
- 确认 `/Applications/TagLauncher.app` 已是 `7.8.25 (20260609.1741)`，当前运行进程也是安装后的 `/Applications/TagLauncher.app/Contents/MacOS/TagLauncher`。
- 确认用户数据库 `tags.json` 未记录 `isunclient`，因此不是本地数据旧项。
- 确认系统相关 app 路径包括：
  - `/Applications/AweSun.app`
  - `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`
  - `/Applications/贝锐向日葵被控.app`
  - `/Applications/贝锐向日葵被控.app/Wrapper/isunclient.app`
- 判断 `7.8.25` 只按 URL pathComponents 识别嵌套 `.app` 不够稳，需要把 wrapper/helper 路径识别升为通用过滤规则。
- 实现 `7.8.26`：
```

```text
- 确认 `/Applications/TagLauncher.app` 已是 `7.8.25 (20260609.1741)`，当前运行进程也是安装后的 `/Applications/TagLauncher.app/Contents/MacOS/TagLauncher`。
- 确认用户数据库 `tags.json` 未记录 `isunclient`，因此不是本地数据旧项。
- 确认系统相关 app 路径包括：
  - `/Applications/AweSun.app`
  - `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`
  - `/Applications/贝锐向日葵被控.app`
  - `/Applications/贝锐向日葵被控.app/Wrapper/isunclient.app`
- 判断 `7.8.25` 只按 URL pathComponents 识别嵌套 `.app` 不够稳，需要把 wrapper/helper 路径识别升为通用过滤规则。
- 实现 `7.8.26`：
  - 扫描层过滤 `.app/.../*.app`、`/Wrapper/`、`/Contents/Helpers/`、`/Contents/XPCServices/`。
```

```text
- QA 增加 helper path fixture。
  - 版本更新为 `7.8.26 (20260609.2004)`。
- 创建提交：`dd1c9fc Release 7.8.26 helper app filtering`。
- 生成本地验收 DMG：`/Users/ar/Projects/Taglauncher/src/build/TagLauncher-7.8.26-build20260609.2004.dmg`。
## 验证结果
- `Scripts/quick_search_app_name_qa.sh` 通过。
- `Scripts/quick_search_system_app_qa.sh` 通过。
- `APP_BUILD=20260609.2004 bash build.sh` 通过。
```

### 2026-06-09 legacy/codex-20260610/session-history/2026-06-09-向日葵显示名排查.md

```text
排查 TagLauncher 搜索“向日葵”时命中结果显示为英文 `isunclient`，而 Spotlight 显示中文名的问题，判断原因和修复风险。
## 已完成事项
- 重新读取 `/Users/ar/.codex/AGENTS.md` 与 `/Users/ar/Projects/Taglauncher/AGENTS.md`，并遵守项目要求的代码治理、实现前讨论、QA 与会话记录规则。
- 只读检查当前源码中 `AppIndexer`、`QuickSearchEngine`、`AppLibraryController` 和现有 `quick_search_app_name_qa.sh`。
- 确认系统中存在：
  - `/Applications/AweSun.app`
  - `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`
```

```text
- 重新读取 `/Users/ar/.codex/AGENTS.md` 与 `/Users/ar/Projects/Taglauncher/AGENTS.md`，并遵守项目要求的代码治理、实现前讨论、QA 与会话记录规则。
- 只读检查当前源码中 `AppIndexer`、`QuickSearchEngine`、`AppLibraryController` 和现有 `quick_search_app_name_qa.sh`。
- 确认系统中存在：
  - `/Applications/AweSun.app`
  - `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`
  - `/Applications/贝锐向日葵被控.app`
  - `/Applications/贝锐向日葵被控.app/Wrapper/isunclient.app`
- 确认用户数据 `tags.json` 记录的是外层 `/Applications/贝锐向日葵被控.app`，不是内层 `isunclient.app`。
- 临时运行当前扫描逻辑复现实验，当前源码只输出外层 `/Applications/贝锐向日葵被控.app`，可读到中文显示名，不输出内层 `Wrapper/isunclient.app`。
```

```text
- `/Applications/贝锐向日葵被控.app/Wrapper/isunclient.app`
- 确认用户数据 `tags.json` 记录的是外层 `/Applications/贝锐向日葵被控.app`，不是内层 `isunclient.app`。
- 临时运行当前扫描逻辑复现实验，当前源码只输出外层 `/Applications/贝锐向日葵被控.app`，可读到中文显示名，不输出内层 `Wrapper/isunclient.app`。
- 发现本机 `/Applications/TagLauncher.app` 仍为 `7.8.22 (20260608.2346)`，不是已冻结的 `7.8.24 (20260609.1221)`。
- 运行现有 QA 脚本通过，但该脚本没有覆盖最终 QuickSearch 文档是否含有 `isunclient`，存在回归测试盲区。
## 关键判断
- 直接原因：向日葵“被控”包结构特殊，外层 `.app` 是包装器，真实 bundle 在 `Wrapper/isunclient.app`。旧扫描结果或旧构建若把内层 bundle 当成独立 App 收入 QuickSearch，就会显示内部文件名 `isunclient`。
- 当前源码侧扫描器已能过滤这个内层 helper，截图现象更可能来自旧安装版或旧内存扫描数据。
```

## 来源索引

- 2026-06-09 [`legacy/codex-20260610/session-history/2026-06-09-helper过滤补强.md`](legacy/codex-20260610/session-history/2026-06-09-helper过滤补强.md)
- 2026-06-09 [`legacy/codex-20260610/session-history/2026-06-09-向日葵显示名排查.md`](legacy/codex-20260610/session-history/2026-06-09-向日葵显示名排查.md)
- 2026-06-09 [`legacy/codex-20260610/session-history/2026-06-09-多语种显示名策略.md`](legacy/codex-20260610/session-history/2026-06-09-多语种显示名策略.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-开发实现.md`](../26.0828-Taglauncher.quicksearchfilter-开发实现.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-代码审核.md`](../26.0828-Taglauncher.quicksearchfilter-代码审核.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-QA失败.md`](../26.0828-Taglauncher.quicksearchfilter-QA失败.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-QA返修复测.md`](../26.0828-Taglauncher.quicksearchfilter-QA返修复测.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-8.4.0本地包.md`](../26.0828-Taglauncher.quicksearchfilter-8.4.0本地包.md)
- 2026-08-28 [`26.0828-Taglauncher.quicksearchfilter-8.4.0正式冻结.md`](../26.0828-Taglauncher.quicksearchfilter-8.4.0正式冻结.md)
- 2026-08-30 [`26.0830-Taglauncher.quicksearchfilter-TestFlight上传.md`](../26.0830-Taglauncher.quicksearchfilter-TestFlight上传.md)

## 时间线

### 2026-06-09 legacy/codex-20260610/session-history/2026-06-09-helper过滤补强.md

- 原始标题：2026-06-09 helper过滤补强
- 确认 `/Applications/TagLauncher.app` 已是 `7.8.25 (20260609.1741)`，当前运行进程也是安装后的 `/Applications/TagLauncher.app/Contents/MacOS/TagLauncher`。
- 确认用户数据库 `tags.json` 未记录 `isunclient`，因此不是本地数据旧项。
- 确认系统相关 app 路径包括：
- `/Applications/AweSun.app`
- `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`

### 2026-06-09 legacy/codex-20260610/session-history/2026-06-09-向日葵显示名排查.md

- 原始标题：2026-06-09 向日葵显示名排查
- 重新读取 `/Users/ar/.codex/AGENTS.md` 与 `/Users/ar/Projects/Taglauncher/AGENTS.md`，并遵守项目要求的代码治理、实现前讨论、QA 与会话记录规则。
- 只读检查当前源码中 `AppIndexer`、`QuickSearchEngine`、`AppLibraryController` 和现有 `quick_search_app_name_qa.sh`。
- 确认系统中存在：
- `/Applications/AweSun.app`
- `/Applications/AweSun.app/Contents/Helpers/AweSun_Desktop.app`

### 2026-06-09 legacy/codex-20260610/session-history/2026-06-09-多语种显示名策略.md

- 原始标题：2026-06-09 多语种显示名策略
- 基于前一轮排查，确认当前问题不应按中文个例打补丁，而应抽象为“用户可见显示名”和“搜索别名/内部标识”分层。
- 复查当前实现中 `AppInfo.localizedDisplayName(for:)`、`localizedNamesByLanguage`、`localizedNames`、`QuickSearchEngine.makeDocuments`、`L10n.supported` 和 Apple 默认应用目录的语言 fallback。
- 通用规律：一个 App 通常同时存在多种名称来源，包括当前语言本地化名、系统/Finder/Spotlight 显示名、Bundle 基础名、文件名、可执行名、bundle id 和 wrapper/helper 内部名。
- 产品显示名应优先使用“用户当前语种的本地化可见名称”；内部名只应作为搜索别名，不能优先显示。
- 嵌套 `.app`、helper、iOS-on-Mac wrapper 应归并到外层用户可见 App；内层标识最多参与搜索匹配，不应作为独立结果展示。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-开发实现.md

- 原始标题：Taglauncher quicksearchfilter 开发实现。
- `QSF-DEV-001` 终态口令为 `DEV_READY_QSF`，证据见 `02-P/Round01-QuickSearchTagFilter/04-开发自测与回报-8.4.0.md`。
- `QuickSearchEngine.search` 增加 `selectedTagName`，先按真实标签精确收窄文档，再和关键词 token 匹配。
- `ContentView` 维护 `quickSearchSelectedTagName` 运行时状态，从当前索引与 `tagDefinitions` 生成可用标签，排除未分类、Mac 自带、不常用等保护容器名。
- 新增 `QuickSearchTagFilterBar` / `QuickSearchTagFilterChip`，保持结果区使用原有长条候选项。
- 自测通过 `quick_search_tag_filter_qa.sh`、`quick_search_launch_contract_qa.sh`、`windowserver_event_safety_qa.sh`、`quick_search_system_app_qa.sh`、`macos14_availability_typecheck_qa.sh` 和 `git diff --check`。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-代码审核.md

- 原始标题：Taglauncher quicksearchfilter 代码审核。
- `QSF-CR-001` 终态口令为 `CR_PASS_QSF`，证据见 `02-P/Round01-QuickSearchTagFilter/05-代码审核报告-8.4.0.md`。
- 代码审核未发现需要开发返修的阻断问题。
- 审核确认 Quick Search 标签筛选只做运行时单选，不持久化，不改 AppGrid / Pro / 数据结构。
- 审核确认标签条不替换结果长条列表，不破坏 Return / Esc / 方向键、鼠标点击启动、IME composition 和焦点回到输入框契约。
- 已复跑并通过标签筛选专项、启动契约、WindowServer 事件安全、系统应用索引、macOS 14 可用性 typecheck 和 scoped `git diff --check`。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-QA失败.md

- 原始标题：Taglauncher quicksearchfilter QA失败。
- `QSF-QA-001` 终态口令为 `QA_FAIL_QSF`，证据见 `02-P/Round01-QuickSearchTagFilter/06-QA执行报告-8.4.0.md`。
- 本轮真实 UI 对象确认为 `/Users/ar/Projects/Taglauncher/03-O/C1.source/build/TagLauncher.app`，旧 `/Applications/TagLauncher.app` 未计入 QA 证据。
- 自动门禁全部通过，但真实 UI 发现两个阻断项：`全部` chip 不能稳定清除筛选；含 `未分类` 等保护容器标签的数据触发 Swift fatal `Duplicate values for key: '未分类'`。
- QA PASS 前不得生成 8.4.0 可安装验收包，应先派回开发做最小返修。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-QA返修复测.md

- 原始标题：Taglauncher quicksearchfilter QA返修复测。
- `QSF-QA-002` 终态口令为 `QA_PASS_QSF_FIX`，证据见 `02-P/Round01-QuickSearchTagFilter/09-QA复测报告-8.4.0.md` 和 `QA-Retest-Evidence-8.4.0-20260828-QSF-QA-002/`。
- 真实 UI 对象确认为 `/Users/ar/Projects/Taglauncher/03-O/C1.source/build/TagLauncher.app`，旧 `/Applications/TagLauncher.app` 未计入复测证据。
- F1 复测通过：点击 `全部` chip 可清除已选标签筛选并保持 Quick Search 面板稳定；普通标签切换、同标签二次点击清除、标签 + 关键词交集、鼠标结果行启动、Return 启动、方向键、Esc、外部点击和中文 IME smoke 回归通过。
- F2 复测通过：隔离 fixture 覆盖 `未分类`、`Mac自带`、`不常用`、`__system.uncommon`，未再触发 `Duplicate values for key` 崩溃，保护名未进入 Quick Search 筛选条。
- 本 QA worker 未生成 DMG/pkg、未提交、未推远端、未改生产代码或版本 / 签名 / 发布链路；PMO 消费后才可生成 8.4.0 可安装验收包。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-8.4.0本地包.md

- 原始标题：Taglauncher quicksearchfilter 8.4.0 本地包。
- PMO 消费 `QA_PASS_QSF_FIX` 后执行 `QSF-PKG-001`，终态口令为 `LOCAL_TEST_READY_QSF`。
- 版本收口为 `8.4.0 (20260828.1732)`，源码冻结提交 `c5bdc7f1eb3ff4287beeeebb17d4f02f376a8d38`，归档提交 `c8f827e`。
- 本地安装体验包：`/Users/ar/Projects/Taglauncher/03-O/C2.builds/LocalTest-8.4.0-20260828.1732/Archive/TagLauncher-8.4.0-build20260828.1732-localtest.dmg`。
- SHA256：`76647a1133fbb96abdb8dd0531dc83819ac58815057071671204b746b781070f`。
- 验证通过专项 QA、构建、签名、macOS 14 build metadata、DMG 校验、只读挂载内容/权限检查和隔离启动 smoke。
- 本包是 ad-hoc signed 本地安装体验包，不是 ASC/TestFlight 上传包，也不是 Developer ID 公证包；等待用户安装体验确认。

### 2026-08-28 26.0828-Taglauncher.quicksearchfilter-8.4.0正式冻结.md

- 原始标题：Taglauncher quicksearchfilter 8.4.0 正式冻结。
- 用户安装体验 `8.4.0 (20260828.1732)` 后确认“没有找到问题”，PMO 登记 Owner 验收并继续正式冻结。
- 正式 App Store 上传版本为 `8.4.0 (20260828.2219)`。
- 源码冻结提交：`7a94f69bb0dc5206a2e68d82486fd5959d16e664`。
- Release archive 提交：`e0b616c988e25d6db6e232c12056fb943c04e03e`。
- Release tag：`v8.4.0-build20260828.2219`。
- App Store 上传包：`/Users/ar/Projects/Taglauncher/03-O/K3.运营与发布资料/Release/AppStore-8.4.0-20260828.2219/Upload/TagLauncher-8.4.0-build20260828.2219.pkg`。
- 上传包 SHA256：`0d374a03b25c11a4bf9bad19238defd7c3043b72386ee70f7857e01f4f9d6318`。
- 状态：`ASC_UPLOAD_READY_QSF`，等待 Transporter / App Store Connect 上传和 Apple 后台处理反馈。

### 2026-08-30 26.0830-Taglauncher.quicksearchfilter-TestFlight上传.md

- 原始标题：Taglauncher quicksearchfilter 8.4.0 TestFlight 上传。
- 用户要求上传到市场并走 TestFlight，以便再测试几天。
- 上传版本：`8.4.0 (20260828.2219)`。
- Delivery UUID：`482c12a7-543d-4dab-afac-aa4e1b4bb6d0`。
- Apple 返回：`import-status=VALID`、`processingState=VALID`、`build-status=BETA_INTERNAL_TESTING`、`buildAudienceType=APP_STORE_ELIGIBLE`。
- 状态：`TESTFLIGHT_INTERNAL_READY_QSF`；未提交 App Review，下一步是 Owner 通过 TestFlight 体验。