# VoiceSnap TODO

## Workflow

- 每次修改前先检查本文件。
- 如果用户提出的新需求不在清单中，先新增到 `Todo` 或 `In Progress`。
- 开始做任务时，把任务移动到 `In Progress`。
- 任务完成并验证后，把任务移动到 `Done`，补一句完成结果。

## In Progress

- 无

## Todo

- 无

## Done

- [2026-05-17] 放大菜单栏图标的有效绘制区域，改善深色菜单栏里图标过小的问题。
  - `VoiceSnapGo/build/darwin/tray_icon.png` 的有效内容区域从约 `156x156` 放大到约 `220x220`。
  - build: `20260517.2306`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.2306-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
  - 已安装到 `/Applications/VoiceSnap.app`。
- [2026-05-17] 使用重新生成并已确认满意的 macOS 26 风格麦克风图标，制作透明边缘 icns 并重新打包。
  - 图标来源: `/Users/ar/.codex/generated_images/019e2f69-755a-74a2-9a61-0e390fda0463/ig_0a6e87fd2c8e3f65016a09c4c865688191ade9691cb608b2e4.png`
  - 透明 PNG: `VoiceSnapGo/build/darwin/macos26_mic_app_icon.png`
  - 当前打包图标: `VoiceSnapGo/build/darwin/icon.icns`
  - 备用 ICNS: `VoiceSnapGo/build/darwin/VoiceSnap-macos26-mic.icns`
  - build: `20260517.2142`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.2142-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
  - 已安装到 `/Applications/VoiceSnap.app`，安装后图标 `hasAlpha: yes`。
- [2026-05-17] 恢复用户指定的精致麦克风图标，并重新打包。
  - 图标来源: `VoiceSnapGo/build/darwin/app_icon_source.png`
  - PNG: `VoiceSnapGo/build/darwin/refined_mic_app_icon.png`
  - ICNS: `VoiceSnapGo/build/darwin/VoiceSnap-refined-mic.icns`
  - 当前打包图标: `VoiceSnapGo/build/darwin/icon.icns`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.2046-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 将 App 图标回退到最早源码自带的蓝底白色声波图标，并重新打包。
  - 图标来源: `/Users/ar/Downloads/VoiceSnap-2.1.1/VoiceSnapGo/build/windows/icon.ico`
  - PNG: `VoiceSnapGo/build/darwin/original_app_icon.png`
  - ICNS: `VoiceSnapGo/build/darwin/VoiceSnap-original.icns`
  - 当前打包图标: `VoiceSnapGo/build/darwin/icon.icns`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.2039-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 调整用户词库默认显示顺序，最新添加的词语显示在最上面。
  - 后端 `UserDictService.GetAll` 返回时按 `createdAt` 倒序排列，时间相同时按 `id` 倒序兜底。
  - 前端加载词库时做同样的保险排序；新增词条后直接插到列表最上方。
  - 替换规则执行顺序保持原存储顺序，不影响识别文本替换行为。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.1811-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 修复组合键检测使用残留按键状态导致右 Alt 突然失效的问题。
  - 组合键判定改为只认“热键按下之后新按下的其他键”，不再被旧的残留按键状态拦截。
  - macOS 增加 `Hotkey combination source` 日志，后续如果还被判定组合键，可以直接看到触发源。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.1631-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 修复右 Alt 被误判为组合键的问题，避免 macOS 把同组 Option 状态误报成左 Alt 后阻止录音。
  - 日志定位到右 Alt 按下后被 `Hotkey marked as combination` 拦截，原因是 macOS 侧边 Option 查询会把左 Alt 误报为按下。
  - 侧边修饰键改为只信任 event tap 记录的物理 keyCode 状态，不再用会混淆左右的即时轮询。
  - 组合键判断中跳过同一修饰键组，避免 R-Alt 被 L-Alt 假状态拦截。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.1622-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 给 App 增加 build 编号显示，并在启动日志记录版本、build、可执行文件路径和数据目录。
  - About 页版本显示改为 `2.1.1 (build 20260517.1614)`。
  - `CFBundleVersion` 改为 `20260517.1614`，安装后的 `/Applications/VoiceSnap.app` 已验证。
  - 启动日志现在记录 `version`、`build`、`executable` 和 `dataDir`。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-build20260517.1614-arm64-local.dmg`
  - 兼容输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg` 已替换为同一份新包。
- [2026-05-17] 增加热键诊断日志，记录 macOS 原始 Alt 事件、App 轮询状态和触发/忽略原因。
  - 记录 event tap 是否启动，以及 `L-Alt/R-Alt` 原始事件序号、事件类型、flags、事件状态、轮询状态。
  - 记录 App 层热键状态变化、按下接受、释放、短按/长按动作、组合键判定和被忽略原因。
  - 日志位置: `~/Library/Application Support/VoiceSnap/app.log`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 修正 macOS `flagsChanged` 修饰键状态逻辑，避免重复事件把右 Alt 状态翻转错误。
  - event tap 移到独立后台 run loop，避免主线程 run loop 状态影响键盘监听。
  - 修饰键状态改为按事件后 modifier flag 直接置 true/false，不再用 toggle。
  - 给短按增加 120ms 状态缓冲，避免 30ms 轮询错过很快的点击。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 修复 macOS 右 Alt 热键时灵时不灵的问题，改为单一 `CGEventTap` 事件源追踪键盘状态。
  - 移除 local/global 双监听导致的修饰键状态翻转不同步风险。
  - 现在由一个 listen-only HID event tap 统一记录 KeyDown/KeyUp/FlagsChanged。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 日志每行时间戳改为完整日期和几点几分几秒，方便排查问题。
  - 日志格式改为 `[2026-05-17 15:24:08] INFO ...`。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 修复上版 macOS 右 Alt 无法触发语音输入的问题，改用 `flagsChanged` 事件追踪左右修饰键状态。
  - 左右 Alt/Ctrl/Shift/Cmd 现在由 macOS 修饰键变更事件记录物理键状态，并保留系统物理按键状态查询作为辅助。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 将配置、用户词库、历史、模型缓存迁移到 macOS `Application Support/VoiceSnap`，避免更新 App 后丢失。
  - 新数据目录: `~/Library/Application Support/VoiceSnap`
  - 持久化内容: `config.json`、`userdict.json`、`history.json`、`models/sensevoice`、`app.log`
  - 首次启动会从旧 `.app/Contents/MacOS` 位置复制缺失数据到新目录，不覆盖已有新数据。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 将默认触发热键改为右侧 Alt。
  - 新配置默认值从 `R-Ctrl` 改为 `R-Alt`。
- [2026-05-17] 修复 macOS 下左右 Alt 被当成同一个键的问题：设置 `R-Alt` 时左 Alt 不能触发。
  - macOS 左右 Ctrl/Alt/Shift/Cmd 改为按物理 keyCode 检测，不再依赖不区分左右的系统 modifier flag。
- [2026-05-17] 用户词库导出默认文件名追加当前日期和时分时间戳。
  - 默认文件名形如 `userdict-20260517-1503.json`。
- [2026-05-17] 简化用户词库导出 JSON，只保留用户真正关心的 `from` 和 `to` 字段。
  - 导入功能兼容旧版完整字段和新版简化字段。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 重新迭代 App 图标，修复 Dock 深色背景上的白边问题，并打包进新版 `.app/.dmg`。
  - 图标资源: `VoiceSnapGo/build/darwin/app_icon.png`
  - ICNS: `VoiceSnapGo/build/darwin/icon.icns`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 改进用户词库导出体验：导出时让用户选择保存位置，并在成功后显示实际路径。
  - 导出按钮现在会弹出 macOS 保存文件对话框，默认文件名为 `userdict.json`。
  - 用户取消保存时不报错；保存成功后界面显示实际保存路径。
- [2026-05-17] 将用户确认的新 App 图标打包进新版 `.app/.dmg`，本次只替换图标资源，不改业务代码。
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap.app`
  - 输出: `VoiceSnapGo/build/local/arm64/VoiceSnap-2.1.1-arm64-local.dmg`
- [2026-05-17] 保存用户确认满意的新 App 图标，并生成可手动替换的 `.icns`。
  - PNG: `VoiceSnapGo/build/darwin/approved_app_icon.png`
  - ICNS: `VoiceSnapGo/build/darwin/VoiceSnap-approved.icns`
  - 用户便捷取用副本: `/Users/ar/Downloads/VoiceSnap-approved.icns`