# AppGrid与交互容器

生成日期：2026-07-09

## 当前状态

- 主题说明：AppGrid与交互容器 相关会话的长期二级汇编；原始会话记录仍是证据源。
- 来源记录数：10
- 时间范围：2026-06-08 至 2026-08-28
- 最新记录：[`26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md`](26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md)

## 最近结论摘录

- AppGrid 备注气泡输入框 placeholder 可读性修复：从系统默认 `placeholderString` 改为显式 `placeholderAttributedString`。
- 设计决策：placeholder 使用 `white alpha 0.48`，可接受范围 `0.46-0.52`；正文颜色、输入框背景、文案和尺寸均不改。
- 本地化边界：placeholder 仍使用 `tr("appNote.placeholder")`，不写死中文。
- QA 门禁：`Scripts/app_note_bubble_input_qa.sh` 增加 placeholder 可读性防回归，并保留 IME marked text、提交 / 取消和备注长度上限检查。
- 交付快照：补建 `8.3.7 (20260822.2207)` ad-hoc signed 本地测试 DMG；不是 ASC 上传包，也未做公证。
- Owner 体验验收：2026-08-28 用户已安装验证 `8.3.7 (20260822.2207)` 本地测试 DMG，并确认 placeholder 字色效果 OK。
- 范围边界：Owner 验收只覆盖本地体验包和 AppGrid 备注气泡 placeholder 字色优化，不等同 ASC 上传包、公开发布放行或其它新需求验收。

## 核心事实补录

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动修复.md

```text
# Taglauncher 会话记录 - 2026-06-08 AppGrid抖动修复
## 用户目标
用户确认采用低风险方案：hover 只保留高亮/填色，不再自动滚动；点击 tag 仍滚动到对应分组。
## 已完成事项
- 将任务登记到 `/Users/ar/Projects/Taglauncher/src/TODO.md` 的 `In Progress`。
- 修改 `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`：
  - 移除 `AppGridInteractionState` 中只服务于 hover 自动滚动的 `tagNavigationLastHoverScrollID` 与 `tagNavigationLastHoverScrollAt`。
```

```text
## 用户目标
用户确认采用低风险方案：hover 只保留高亮/填色，不再自动滚动；点击 tag 仍滚动到对应分组。
## 已完成事项
- 将任务登记到 `/Users/ar/Projects/Taglauncher/src/TODO.md` 的 `In Progress`。
- 修改 `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`：
  - 移除 `AppGridInteractionState` 中只服务于 hover 自动滚动的 `tagNavigationLastHoverScrollID` 与 `tagNavigationLastHoverScrollAt`。
  - 移除 `tagNavigationHoverScrollInterval`。
  - 从 `handleTagNavigationHover()` 中移除 `scrollToTagFromHover(id)` 调用。
  - 删除 `scrollToTagFromHover(_:)` 函数。
```

```text
## 已完成事项
- 将任务登记到 `/Users/ar/Projects/Taglauncher/src/TODO.md` 的 `In Progress`。
- 修改 `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`：
  - 移除 `AppGridInteractionState` 中只服务于 hover 自动滚动的 `tagNavigationLastHoverScrollID` 与 `tagNavigationLastHoverScrollAt`。
  - 移除 `tagNavigationHoverScrollInterval`。
  - 从 `handleTagNavigationHover()` 中移除 `scrollToTagFromHover(id)` 调用。
  - 删除 `scrollToTagFromHover(_:)` 函数。
- 保留 `activateTagNavigation(_:)` 中的 `scrollTo(id)`，因此点击 tag 仍会滚动到对应分组。
## 验证结果
```

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动排查.md

```text
# Taglauncher 会话记录 - 2026-06-08 AppGrid抖动排查
## 用户目标
用户提供 `/Users/ar/Desktop/奇怪的抖动问题.mp4`，要求先判断奇怪交互抖动的成因，并评估修复风险。
## 已完成事项
- 读取并遵守 `~/.codex/rules/qa-workflow.md` 与 `~/.codex/rules/delivery-gate.md`。
- 使用 `ffprobe` 检查视频：8.88 秒，1920x1080，约 19.49 fps。
- 使用 `ffmpeg` 抽取 contact sheet：
```

```text
- 使用 `ffmpeg` 抽取 contact sheet：
  - `/private/tmp/taglauncher-jitter-frames/contact.jpg`
  - `/private/tmp/taglauncher-jitter-frames/contact-4fps.jpg`
- 读取并分析相关源码：
  - `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/AppGridCollectionView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/TagNavigationView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/AppGridSupport.swift`
## 初步判断
```

```text
- `/private/tmp/taglauncher-jitter-frames/contact.jpg`
  - `/private/tmp/taglauncher-jitter-frames/contact-4fps.jpg`
- 读取并分析相关源码：
  - `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/AppGridCollectionView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/TagNavigationView.swift`
  - `/Users/ar/Projects/Taglauncher/src/Apptag/AppGridSupport.swift`
## 初步判断
- 视频中的抖动主要表现为 AppGrid 内容在不同分组位置之间跳动，而不是单个图标 hover 的局部放大。
```

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动验收.md

```text
# Taglauncher 会话记录 - 2026-06-08 AppGrid抖动验收
## 用户目标
用户使用新版后反馈：与修复前相比变化不大，仍有一点小抖，但当前效果可以接受。
## 已完成事项
- 将 `/Users/ar/Projects/Taglauncher/src/TODO.md` 中 App Grid 顶部 tag hover 抖动修复任务从 `In Progress` 移动到 `Done`。
- 在 Done 记录中补充用户真实体验验收结论：仍有轻微小抖，但可接受，本轮不继续扩大修复范围。
```

```text
## 已完成事项
- 将 `/Users/ar/Projects/Taglauncher/src/TODO.md` 中 App Grid 顶部 tag hover 抖动修复任务从 `In Progress` 移动到 `Done`。
- 在 Done 记录中补充用户真实体验验收结论：仍有轻微小抖，但可接受，本轮不继续扩大修复范围。
## 关键决策
- 当前不再继续扩大到 AppGrid 布局算法、hover bubble 或窗口层级的更大改动。
- 保留本轮低风险改动：hover 不触发自动滚动，点击 tag 仍滚动。
## 文件变更
- `/Users/ar/Projects/Taglauncher/src/TODO.md`
```

```text
- 当前不再继续扩大到 AppGrid 布局算法、hover bubble 或窗口层级的更大改动。
- 保留本轮低风险改动：hover 不触发自动滚动，点击 tag 仍滚动。
## 文件变更
- `/Users/ar/Projects/Taglauncher/src/TODO.md`
## 未决问题
- 残余轻微小抖仍存在，后续如需要继续优化，可单独复盘 AppGrid layout bounds invalidation、hover bubble 命中区域和 tag navigation 高亮/填色重绘。
## 后续建议
```

### 2026-07-01 2026-07-01-标签额度PRD.md

```text
- 新增 PRD：
  - `/Users/ar/Projects/Taglauncher/src/Docs/Requirements/2026-07-01-pro-custom-container-quota-prd.md`
- 新增长期备忘：
  - `/Users/ar/Projects/Taglauncher/src/Docs/Requirements/free-vs-pro-feature-memo.md`
## 核心事实 / 变更快照
### 变更对象
TagLauncher 免费版 / Pro 版标签维护权限边界。
```

```text
- 新增长期备忘：
  - `/Users/ar/Projects/Taglauncher/src/Docs/Requirements/free-vs-pro-feature-memo.md`
## 核心事实 / 变更快照
### 变更对象
TagLauncher 免费版 / Pro 版标签维护权限边界。
### 事实来源
```

```text
## 核心事实 / 变更快照
### 变更对象
TagLauncher 免费版 / Pro 版标签维护权限边界。
### 事实来源
- 本轮用户讨论。
```

### 2026-07-01 2026-07-01-标签额度刷新审查.md

```text
作为代码审核员 C / QA，只读审查 TagLauncher 8.3.0 新问题的验收方案：免费用户编辑或维护标签后，Settings Tags 顶部自定义容器额度文案没有实时刷新，仍显示 0/6。用户要求不要改代码，并回答静态 QA 断言、应跑的现有 QA 命令，以及不截图 / 不真实点击时自动化证据与人工验收边界。
## 已完成事项
- 已读取 `qa-workflow` skill、`CODE_GOVERNANCE.md`、全局 QA 规则、研发前置讨论规则、`CODEGRAPH.md`。
- 已只读检查当前工作区状态：当前分支 `codex/pro-custom-hotkeys-8.2.0`，工作区已有多处未提交改动，本轮不修改。
- 已定位相关源码：
  - `src/Apptag/TagEditorView.swift`
  - `src/Apptag/PreferencesView.swift`
```

```text
- 已定位相关源码：
  - `src/Apptag/TagEditorView.swift`
  - `src/Apptag/PreferencesView.swift`
  - `src/Apptag/ContentView.swift`
  - `src/Apptag/ProEntitlement.swift`
  - `src/Apptag/DataLayer.swift`
  - `src/Scripts/pro_custom_container_quota_qa.sh`
## 关键判断
```

```text
- `src/Apptag/TagEditorView.swift`
  - `src/Apptag/PreferencesView.swift`
  - `src/Apptag/ContentView.swift`
  - `src/Apptag/ProEntitlement.swift`
  - `src/Apptag/DataLayer.swift`
  - `src/Scripts/pro_custom_container_quota_qa.sh`
## 关键判断
- 现有 `pro_custom_container_quota_qa.sh` 主要覆盖额度模型、门禁、文案和数据层规则，不足以覆盖“成功维护标签后顶部额度文案触发 SwiftUI 重新渲染”。
```

### 2026-07-01 2026-07-01-额度状态审查.md

```text
作为 TagLauncher 崩溃 / 新问题代码审核员 A，只读审查 8.3.0 新问题的最小修复方案，不修改源码。
问题：免费用户编辑 / 维护 4 个标签后，标签页顶部“免费用户可以使用6个自定义标签（容器）：已使用 0 / 6”没有实时变化。
关注文件：
- `/Users/ar/Projects/Taglauncher/src/Apptag/TagEditorView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/PreferencesView.swift`
```

```text
- `/Users/ar/Projects/Taglauncher/src/Apptag/TagEditorView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/PreferencesView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/ProEntitlement.swift`
- `/Users/ar/Projects/Taglauncher/src/Scripts/pro_custom_container_quota_qa.sh`
## 已完成事项
- 只读检查当前工作区、分支和 worktree。
```

```text
- `/Users/ar/Projects/Taglauncher/src/Apptag/TagEditorView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/PreferencesView.swift`
- `/Users/ar/Projects/Taglauncher/src/Apptag/ProEntitlement.swift`
- `/Users/ar/Projects/Taglauncher/src/Scripts/pro_custom_container_quota_qa.sh`
## 已完成事项
- 只读检查当前工作区、分支和 worktree。
- 只读审查自定义标签容器额度状态流、TagEditorView mutation 回调、ContentView / PreferencesView 顶部 accessory、ProEntitlement quota policy 和现有 QA 脚本。
```

### 2026-07-01 26.0701-Taglauncher.Coder3-标签额度文案补修.md

```text
# 26.0701-Taglauncher.Coder3-标签额度文案补修
## 用户目标
根据用户直接提供的截图 `/Users/ar/Desktop/Screencapture/SCR-20260701-phds.png`，修正 8.3.0 标签额度相关 UI 文案：
- Pro 对比表“可维护标签数量”的 Pro 列“没有限制”前漏了一个 `✅`。
- 标签页顶部额度行文案改为“免费用户可以使用6个自定义标签（容器）：”。
```

```text
- 更新 29 个本地化 JSON：
  - `settings.proStatus.unlimitedTags` 全部加上前置 `✅`。
  - `pro.customContainers.quotaShort` 改为“免费用户 / free users 可使用 6 个自定义标签（容器）”语义，并保留 `%used%`、`%limit%` 占位符。
- 更新自动化 QA：
  - `Scripts/pro_localization_qa.sh` 增加英文、简体中文和全语言 `unlimitedTags` 前置 `✅` 检查。
  - `Scripts/pro_custom_container_quota_qa.sh` 增加简体中文额度文案和 `✅没有限制` 检查。
## 核心事实 / 变更快照
- 变更对象：Pro 对比表第一行 Pro 列状态、标签页自定义容器额度行。
```

```text
- 更新自动化 QA：
  - `Scripts/pro_localization_qa.sh` 增加英文、简体中文和全语言 `unlimitedTags` 前置 `✅` 检查。
  - `Scripts/pro_custom_container_quota_qa.sh` 增加简体中文额度文案和 `✅没有限制` 检查。
## 核心事实 / 变更快照
- 变更对象：Pro 对比表第一行 Pro 列状态、标签页自定义容器额度行。
- 变更前：
  - 简体中文 Pro 列第一行显示 `没有限制`。
  - 简体中文标签页额度行显示 `自定义容器：已使用 %used% / %limit%`。
```

### 2026-07-01 26.0701-Taglauncher.发布修复-编辑标签崩溃和额度刷新.md

```text
# Taglauncher 8.3.0 编辑标签崩溃和额度刷新
## 用户目标
- 修复 8.3.0 中“试图编辑标签时系统卡死 / 崩溃”的阻塞问题。
- 用户人工验证后确认：现在可以编辑标签，不会在编辑标签时卡死。
- 同轮补修免费用户自定义标签额度顶部文案不实时刷新：用户已编辑 4 个标签，但仍显示 `0 / 6`。
- 生成新的 8.3.0 DMG 供最终人工验收。
```

```text
- 代码仓库：`/Users/ar/Projects/Taglauncher`
- 源码根目录：`/Users/ar/Projects/Taglauncher/src`
- 用户提供 hang 日志：`/Users/ar/Desktop/26.0701crashlog`
- 用户明确要求：排查崩溃时拉一位架构师和三位代码审核员共同看原因；后续额度刷新方案也拉架构师和代码审核员看。
## 关键决策
- 编辑标签卡死根因判断：`NSTextField.mouseDown(with: event)` 被同一个 `NSEvent` 手动转发，可能进入 AppKit 控件追踪递归。
- 修复策略：不再手动把原始 `mouseDown` 事件转发给 `NSTextField`，改为语义聚焦 / 首次选中，后续点击让原生文本框处理光标。
```

```text
- 代码仓库：`/Users/ar/Projects/Taglauncher`
- 源码根目录：`/Users/ar/Projects/Taglauncher/src`
- 用户提供 hang 日志：`/Users/ar/Desktop/26.0701crashlog`
- 用户明确要求：排查崩溃时拉一位架构师和三位代码审核员共同看原因；后续额度刷新方案也拉架构师和代码审核员看。
## 关键决策
- 编辑标签卡死根因判断：`NSTextField.mouseDown(with: event)` 被同一个 `NSEvent` 手动转发，可能进入 AppKit 控件追踪递归。
- 修复策略：不再手动把原始 `mouseDown` 事件转发给 `NSTextField`，改为语义聚焦 / 首次选中，后续点击让原生文本框处理光标。
- 额度刷新根因判断：顶部 `customContainerQuotaAccessory` 直接读数据库派生值，但缺少明确 SwiftUI 状态驱动，保存后父视图不稳定重算。
```

### 2026-08-22 26.0822-Taglauncher.AppGrid备注气泡-placeholder字色.md

```text
# 2026-08-22｜TagLauncher｜AppGrid 备注气泡｜placeholder 字色
## 用户目标
用户在截图中指出 AppGrid 图标备注气泡的输入框提示文字“APP 用途备注”太暗，几乎看不见；但该文字只是 placeholder，不应过分抢眼。
## 关键决策
- 本轮只改 placeholder 字色，不改文案、不改输入框尺寸、不改输入框背景、不改正文颜色。
- placeholder 仍使用 `tr("appNote.placeholder")`，不写死中文；多语言继续显示各自翻译。
- 本轮生成的是 ad-hoc signed 本地安装测试 DMG，不是 App Store Connect 上传 `.pkg`，也不做公证 / ASC 发布。
## 核心事实 / 变更快照
- 变更对象：AppGrid 备注气泡输入框 placeholder 视觉层级。
- 事实来源：
  - `/Users/ar/Projects/Taglauncher/03-O/C1.source/Apptag/AppGridSupport.swift`
  - `/Users/ar/Projects/Taglauncher/03-O/C1.source/Scripts/app_note_bubble_input_qa.sh`
  - `/Users/ar/Projects/Taglauncher/03-O/CODEGRAPH.md`
- 变更前：`NSTextField` 使用 `field.placeholderString = placeholder`，系统默认 placeholder 色在 `Color.black.opacity(0.92)` bubble 和 `Color.white.opacity(0.12)` 输入框背景上过暗。
- 变更后：`placeholderAttributedString` 使用 `NSColor.white.withAlphaComponent(0.48)`。
- 源码变更 commit：`1ec08b1dedff313e385767edb0c2b815b6dd56f3`。
- 测试包归档 commit：`eab3bec`。
- 本地测试 DMG：`/Users/ar/Projects/Taglauncher/03-O/C2.builds/LocalTest-8.3.7-20260822.2207/Archive/TagLauncher-8.3.7-build20260822.2207-localtest.dmg`。
- SHA256：`4fef51bfa26eb1d73fbb5de4e3a336d5a2a5ed02aa658995126012ace6e04c9f`。
## 验证
已通过 `Scripts/app_note_bubble_input_qa.sh`、`Scripts/macos14_availability_typecheck_qa.sh`、构建、codesign、metadata QA、DMG verify 和只读挂载检查。
```

### 2026-08-28 26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md

```text
# 2026-08-28｜TagLauncher｜AppGrid 备注气泡｜placeholder 验收
## 用户目标
用户反馈已安装 `8.3.7 (20260822.2207)` 本地测试包并验证视觉效果，结论为“效果 OK”。
## 核心事实 / 变更快照
- 对应本地测试包：`/Users/ar/Projects/Taglauncher/03-O/C2.builds/LocalTest-8.3.7-20260822.2207/Archive/TagLauncher-8.3.7-build20260822.2207-localtest.dmg`。
- 源码变更 commit：`1ec08b1dedff313e385767edb0c2b815b6dd56f3`。
- 测试包归档 commit：`eab3bec`。
- DMG SHA256：`4fef51bfa26eb1d73fbb5de4e3a336d5a2a5ed02aa658995126012ace6e04c9f`。
- 变更后：Owner 已确认安装验证通过，placeholder 字色效果 OK。
- 范围边界：本结论只覆盖 AppGrid 备注气泡 placeholder 字色优化和上述本地体验包；不代表 ASC 上传包、公开发布放行、其它 UI 问题或后续新需求已验收。
```

## 来源索引

- 2026-06-08 [`legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动修复.md`](legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动修复.md)
- 2026-06-08 [`legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动排查.md`](legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动排查.md)
- 2026-06-08 [`legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动验收.md`](legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动验收.md)
- 2026-07-01 [`2026-07-01-标签额度PRD.md`](2026-07-01-标签额度PRD.md)
- 2026-07-01 [`2026-07-01-标签额度刷新审查.md`](2026-07-01-标签额度刷新审查.md)
- 2026-07-01 [`2026-07-01-额度状态审查.md`](2026-07-01-额度状态审查.md)
- 2026-07-01 [`26.0701-Taglauncher.Coder3-标签额度文案补修.md`](26.0701-Taglauncher.Coder3-标签额度文案补修.md)
- 2026-07-01 [`26.0701-Taglauncher.发布修复-编辑标签崩溃和额度刷新.md`](26.0701-Taglauncher.发布修复-编辑标签崩溃和额度刷新.md)
- 2026-08-22 [`26.0822-Taglauncher.AppGrid备注气泡-placeholder字色.md`](26.0822-Taglauncher.AppGrid备注气泡-placeholder字色.md)
- 2026-08-28 [`26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md`](26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md)

## 时间线

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动修复.md

- 原始标题：Taglauncher 会话记录 - 2026-06-08 AppGrid抖动修复
- 将任务登记到 `/Users/ar/Projects/Taglauncher/src/TODO.md` 的 `In Progress`。
- 修改 `/Users/ar/Projects/Taglauncher/src/Apptag/ContentView.swift`：
- 移除 `AppGridInteractionState` 中只服务于 hover 自动滚动的 `tagNavigationLastHoverScrollID` 与 `tagNavigationLastHoverScrollAt`。
- 移除 `tagNavigationHoverScrollInterval`。
- 从 `handleTagNavigationHover()` 中移除 `scrollToTagFromHover(id)` 调用。

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动排查.md

- 原始标题：Taglauncher 会话记录 - 2026-06-08 AppGrid抖动排查
- 读取并遵守 `~/.codex/rules/qa-workflow.md` 与 `~/.codex/rules/delivery-gate.md`。
- 使用 `ffprobe` 检查视频：8.88 秒，1920x1080，约 19.49 fps。
- 使用 `ffmpeg` 抽取 contact sheet：
- `/private/tmp/taglauncher-jitter-frames/contact.jpg`
- `/private/tmp/taglauncher-jitter-frames/contact-4fps.jpg`

### 2026-06-08 legacy/codex-20260610/session-history/2026-06-08-AppGrid抖动验收.md

- 原始标题：Taglauncher 会话记录 - 2026-06-08 AppGrid抖动验收
- 将 `/Users/ar/Projects/Taglauncher/src/TODO.md` 中 App Grid 顶部 tag hover 抖动修复任务从 `In Progress` 移动到 `Done`。
- 在 Done 记录中补充用户真实体验验收结论：仍有轻微小抖，但可接受，本轮不继续扩大修复范围。
- 当前不再继续扩大到 AppGrid 布局算法、hover bubble 或窗口层级的更大改动。
- 保留本轮低风险改动：hover 不触发自动滚动，点击 tag 仍滚动。
- `/Users/ar/Projects/Taglauncher/src/TODO.md`

### 2026-07-01 2026-07-01-标签额度PRD.md

- 原始标题：2026-07-01 标签额度 PRD
- 组织市场专家、架构师、运营专家参与讨论。
- 形成一致结论：不采用“维护次数”限制，采用“自定义维护容器数量”限制。
- 新增 PRD：
- `/Users/ar/Projects/Taglauncher/src/Docs/Requirements/2026-07-01-pro-custom-container-quota-prd.md`
- 新增长期备忘：

### 2026-07-01 2026-07-01-标签额度刷新审查.md

- 原始标题：2026-07-01 标签额度刷新审查
- 已读取 `qa-workflow` skill、`CODE_GOVERNANCE.md`、全局 QA 规则、研发前置讨论规则、`CODEGRAPH.md`。
- 已只读检查当前工作区状态：当前分支 `codex/pro-custom-hotkeys-8.2.0`，工作区已有多处未提交改动，本轮不修改。
- 已定位相关源码：
- `src/Apptag/TagEditorView.swift`
- `src/Apptag/PreferencesView.swift`

### 2026-07-01 2026-07-01-额度状态审查.md

- 原始标题：2026-07-01 额度状态审查
- 只读检查当前工作区、分支和 worktree。
- 只读审查自定义标签容器额度状态流、TagEditorView mutation 回调、ContentView / PreferencesView 顶部 accessory、ProEntitlement quota policy 和现有 QA 脚本。
- 运行现有 QA：`bash src/Scripts/pro_custom_container_quota_qa.sh`，结果 PASS。
- 最可能漏掉的状态驱动不是数据层计数，而是 UI 层缺少一个可观察的 `customContainerQuotaStatus` 或等价 refresh token。
- 当前 `customContainerQuotaAccessory` 在 `ContentView` 和 `PreferencesView` 的 computed view 中直接调用 `ProEntitlementPolicy.customContainerQuotaStatus()`，SwiftUI 不会自动订阅数据库文件或 `TagDef.isCustomMaintained` 派生计数变化。

### 2026-07-01 26.0701-Taglauncher.Coder3-标签额度文案补修.md

- 原始标题：26.0701-Taglauncher.Coder3-标签额度文案补修
- 更新 29 个本地化 JSON：
- `settings.proStatus.unlimitedTags` 全部加上前置 `✅`。
- `pro.customContainers.quotaShort` 改为“免费用户 / free users 可使用 6 个自定义标签（容器）”语义，并保留 `%used%`、`%limit%` 占位符。
- 更新自动化 QA：
- `Scripts/pro_localization_qa.sh` 增加英文、简体中文和全语言 `unlimitedTags` 前置 `✅` 检查。

### 2026-07-01 26.0701-Taglauncher.发布修复-编辑标签崩溃和额度刷新.md

- 原始标题：Taglauncher 8.3.0 编辑标签崩溃和额度刷新
- 编辑标签卡死根因判断：`NSTextField.mouseDown(with: event)` 被同一个 `NSEvent` 手动转发，可能进入 AppKit 控件追踪递归。
- 修复策略：不再手动把原始 `mouseDown` 事件转发给 `NSTextField`，改为语义聚焦 / 首次选中，后续点击让原生文本框处理光标。
- 额度刷新根因判断：顶部 `customContainerQuotaAccessory` 直接读数据库派生值，但缺少明确 SwiftUI 状态驱动，保存后父视图不稳定重算。
- 额度刷新修复策略：`ContentView` 和 `PreferencesView` 分别持有 quota `@State`；`TagEditorView` 在成功保存或被 quota 拦截时回传最新 `ProCustomContainerQuotaStatus`。
- 不做范围：不做新的视觉改版；不重新做真实 GUI 截图验证，因为用户正在使用电脑并明确要求不要截图；真实视觉刷新留给用户人工验收。

### 2026-08-22 26.0822-Taglauncher.AppGrid备注气泡-placeholder字色.md

- 原始标题：2026-08-22｜TagLauncher｜AppGrid 备注气泡｜placeholder 字色
- 用户指出 AppGrid 图标备注气泡的输入框提示文字“APP 用途备注”太暗；要求先由设计总监给方案，确认后落地。
- 设计方案：placeholder 使用 `white alpha 0.48`，可接受范围 `0.46-0.52`；正文、输入框背景、文案和尺寸不动。
- 源码落地：`AppBubbleNoteTextField` 从系统默认 `placeholderString` 改为显式 `placeholderAttributedString`，并继续使用 `tr("appNote.placeholder")`。
- QA 门禁：`Scripts/app_note_bubble_input_qa.sh` 增加 placeholder 可读性防回归，同时保留 IME、提交 / 取消和长度上限检查。
- 交付快照：源码变更 commit `1ec08b1dedff313e385767edb0c2b815b6dd56f3`；测试包归档 commit `eab3bec`；本地测试 DMG 为 `8.3.7 (20260822.2207)`，SHA256 `4fef51bfa26eb1d73fbb5de4e3a336d5a2a5ed02aa658995126012ace6e04c9f`。
- 范围边界：本轮没有做真实运行截图 smoke；DMG 是 ad-hoc signed 本地安装测试包，不是 ASC 上传包，也未做公证。

### 2026-08-28 26.0828-Taglauncher.AppGrid备注气泡-placeholder验收.md

- 原始标题：2026-08-28｜TagLauncher｜AppGrid 备注气泡｜placeholder 验收
- 用户反馈已安装 `8.3.7 (20260822.2207)` 本地测试包并验证视觉效果，结论为“效果 OK”。
- PMO 台账和事件日志已记录 Owner 体验验收通过。
- 范围边界：该验收只覆盖本地体验包和 AppGrid 备注气泡 placeholder 字色优化，不代表 ASC 上传包、公开发布放行或其它新需求验收。