v0.4.0 增量质检报告

• 项目：jyk/voice-ime
• 分支：v0.4.0
• 增量区间：c83ebfc0e086ae0363756bacf7a3284b29037ae2 → 34cce9f1140e2bbd2ce0efe209383996f46fc2f0
• 数据来源：codescan.git_diff / codescan.issues_diff（修复 66 条、新增 99 条）+ 源码人工复核

---

一、变更概览

本区间是一次“识别链路 + 隐私落盘”的集中迭代，主题可归为 6 条线：

日志/文档同步：AGENTS.md、README.md、docs/09,10,17,19,25,26 与新增 docs/27。

新增/重构的关键文件：

• 新增：internal/history/history.go(+_test.go)、docs/27-历史记录与失败语音.md、internal/session/{history,asr_failure,hud_tick}_test.go
• 删除：cmd/voiceimed/lexicon.go(+_test.go)
• 大改：internal/session/session.go、cmd/voiceimed/{main,ipc,tray}.go、cmd/voiceime-app/{frontend/app.js,frontend/index.html,service.go,purge.go}

---

二、修复的问题（base 有 → head 无，共 66 条）

⚠️ 重要甄别提醒：本区间删除了整包文件、且 session.go 等大文件被大幅改动，导致行号漂移。以下若干条目与「新增的问题」是同一处代码因换行被同时计入两边（例：internal/session/session.go 的「上帝类」在修复侧是 :279、新增侧是 :305；「函数过长」在两侧分别以不同行号出现）。统计的 66/99 不能直接当作“净修复/净新增”，需按代码位置人工去重。

按文件归类（描述取自工具原文）：

cmd/voiceime-app/frontend/app.js（7） — 均为删除/瘦身后消失的复杂度问题

• 递归调用 :1021、:1112、:1248
• 嵌套深度过高 :1248、:1429；函数过长 :1248
• 圈复杂度过高 :1429、:1934

cmd/voiceime-app/purge.go（1）

• 缺少默认分支 :377

cmd/voiceime-app/service.go（3）

• 圈复杂度过高 :1290；集合未预分配 :1335；缺少默认分支 :1394

cmd/voiceimed/ipc.go（5）

• 循环导入 :1；圈复杂度过高 :160
• 未使用参数 :675、:686、:748；重复代码块 :775

cmd/voiceimed/lexicon_test.go（4） — 文件已随词典一起删除

• 重复代码块 :65、:127；圈复杂度过高 :189；行过长 :236

cmd/voiceimed/main.go（2）、cmd/voiceimed/tray.go（7）、cmd/voiceimed/words_test.go（1）

• main.go：过度日志 :623；缺少默认分支 :660
• tray.go：未使用参数 :335；过度日志 :335；行过长 :404；圈复杂度过高 :499；函数过长 :499；重复代码块 :811、:847
• words_test.go：行过长 :115

internal/asr/sherpa.go（1）：重复代码块 :414

internal/ipc/ipc_test.go（9）：未使用参数 :216/:224/:819/:827；圈复杂度过高 :326/:483/:744；嵌套深度过高 :326

internal/session/session.go（20）：上帝类、递归调用、圈复杂度、重复代码块、goroutine 泄漏风险、过度日志、缺少默认分支等（:279/:439/:495/:519/:577/:719/:1069/:1070/:1086/:1135/:1430/:1500/:1558/:1814/:1983/:2098/:2244/:2324）

结论：真正“被修掉”的语义问题极少，绝大多数是删除代码 / 拆分重构 / 行号漂移带来的指标下降。例如词典下线和 app.js 词典卡片删除，确实消掉了若干复杂度告警；而 session.go 一侧的“修复”多为假修复。

---

三、新增的问题（head 有 → base 无，共 99 条）

同样按文件归类。绝大多数是复杂度/耦合/重复代码类启发式告警，安全类为 0 条（关键正面信号，见第四节）。

前端 cmd/voiceime-app/frontend/app.js（12） — 历史视图新代码引入

• 高耦合：loadWords(11)、saveHistoryPrivacy(13)、loadHistory(15)、formatHistoryTime(11)
• 递归调用：renderWords、renderWordCandidates
• 圈复杂度/嵌套过高：renderWordCandidates、:1376、:2211
• 循环依赖：historyRow → retryHistoryEntry → loadHistory → renderHistory → historyRow

cmd/voiceime-app/service.go（4）：uiLog 扇入 20；集合未预分配 :1400；圈复杂度过高 :1435；缺少默认分支 :1459 cmd/voiceime-app/purge.go（2）：重复代码块 :170；缺少默认分支 :399

cmd/voiceimed/main.go（7）：main 圈复杂度 22 / 169 行 / 6 处日志 / fan-out 94；:658 过度日志；:695 缺少默认分支 cmd/voiceimed/tray.go（11）：retryLastFailed 高耦合 12；buildTrayItems 圈复杂度 12 / 84 行 / 高耦合 11；重复代码块 :237/:663/:903；goroutine 泄漏风险 :1017；过度日志 :394；未使用参数 :449；行过长 :463 cmd/voiceimed/ipc.go（3）：未使用参数 :651/:772；重复代码块 :741；另 voiceprint.go:1 报 voiceprint ↔ ipc 循环导入 测试：tray_test.go:33/:563、words_test.go:182、ipc_test.go:444/:705/:754/:762/:771

internal/history/history.go（5，新包）：重复代码块 :197/:238/:432；圈复杂度过高 :244/:428 internal/history/history_test.go（3）：:17 圈复杂度 12；:222 圈复杂度 11；:232 循环内 IO internal/session/session.go（25，本次改动最集中）：

• 上帝类 :305（Session 80 个方法）
• goroutine 泄漏风险 :424/:642/:2303/:2564（皆为 go func(){...} 启发式命中）
• deliver 函数过长 111 行 / fan-out 29 / 高耦合 29
• inject 90 行 / fan-out 21；handleRetry 高耦合 16
• startListening 105 行、filterVoiceprint 122 行、finishAndInject 87 行
• 多处重复代码块与过度日志、若干 switch 缺少默认分支 internal/session/*_test.go：history_test.go:59 圈复杂度 14 且高耦合 14、:125 高耦合 12；asr_failure_test.go:45 高耦合 12；hud_tick_test.go:50/:56 重复代码块；watchdog_test.go:42/:68

新增问题定性

• 无新增 Critical/High 安全问题。全仓 High 仅 4 条 XSS（hotkey.js、wizard.js），且在 base 即存在；本次新增的历史/词表前端代码刻意全程用 createTextNode/textContent（见 highlighted、historyRow），与仓库红线口径一致。
• internal/history 是安全敏感新包（路径穿越防护），工具未报安全项，且有 TestSafeAudioPath 覆盖非法路径。
• 需要关注的是 internal/session/session.go 的复杂度/上帝类继续膨胀：deliver(111 行, fan-out 29)、handleRetry(耦合 16) 都是本区间新引入的高耦合点。

---

四、需要重点关注的真实风险（人工复核，非工具启发式）

以下是逐行阅读新增/改动代码后确认的确定性发现，按重要性排序。

4.1 失败语音文件权限是 0644，与文档/红线的 0600 不符（中等，隐私红线）

• session.saveFailedAudio 调 audio.WriteWAV 落盘，而 WriteWAV 用 os.Create(path)（internal/audio/wav.go）→ 受 umask 影响，macOS 默认得到 0644。
• 但 docs/27 §2.2 与 AGENTS.md 明确写“文件 0600、目录 0700”；index.html 的历史页也向用户承诺“文件 0600 / 目录 0700”。
• 目录 0700 实际上挡住了跨用户访问，所以影响被目录权限兜住；但“文件本身 0600”的承诺未兑现，属于红线文档与实现不一致。
• 建议：WriteWAV 显式 OpenFile(path, O_CREATE|O_WRONLY|O_TRUNC, 0o600)，或落盘后对失败语音 Chmod(0o600)；history.jsonl 侧已正确使用 fileMode=0o600。

4.2 restartDaemonAndWait 轮询耗尽后仍报“已重启”（低-中，假成功）

• 新抽出的公共函数（app.js）：只在 call("DaemonAction","restart") 抛错时置 err；60 次（≈60s）轮询若始终 daemon_running=false，循环正常结束、err 仍为 null → 走成功分支 btn.hidden = true 并提示“已重启，…已生效”。
• 症状：守护进程实际没起来，界面却说成功。建议轮询结束时若未观察到 running 就置 err = new Error("守护进程未在 60 秒内就绪")。

4.3 history.SafeAudioPath 的布尔优先级与注释承诺不一致（低，但有安全语义）

• if filepath.IsAbs(rel) || filepath.Base(rel) != rel && filepath.Dir(rel) != AudioDirName 实际等价于 IsAbs || (Base!=rel && Dir!=AudioDirName)。
• 后果：裸文件名（如 x.wav，Base==rel 使后半为 false）会被放行并解析为 failed-audio/x.wav。它仍落在音频目录内、不构成路径穿越（TestSafeAudioPath 的危险用例都被拒），但与“只接受 failed-audio/<id>.wav 这一种形状”的注释口径不符。
• 建议加括号并显式要求 filepath.Dir(rel) == AudioDirName（即拒绝裸文件名）。

4.4 重试时状态机迁移失败不回滚（低，当前不可达但脆弱）

• handleRetry 依次 Toggle → HotkeyUp → AudioReady；入口已判 fsm.State()==Idle，且只在 Run 协程推事件，因此正常不可达失败分支。
• 但一旦中途失败（未来若允许并发推事件），会停在 Listening，而重试未走 startListening、未武装看门狗，会话将无法自愈。建议失败时补一次 fsm.Send(Reset)。

4.5 history.Store.Append 在清理失败时返回 error，但记录其实已写入（低，语义误导）

• Append 成功写行后若 pruneLocked 失败，返回 fmt.Errorf("清理历史记录（本次会话已记录）: %w")；上层 recordHistory 会打 "写历史失败（本次会话结果不受影响）" 的 warn，与实际（已写入）相反，排障时容易误判。

4.6 重试失败会再次落一份失败音频（低，行为需知悉）

• 对一条失败记录重试仍失败时，deliver 的失败分支会 saveFailedAudio 再写一份+wav 并追加一条新的 failed 记录。功能上可接受（新记录是新的“发生过一次失败”），但会更快消耗 KeepFailedAudio=20 的保留额度。建议在 docs/27 §4 注明或复用原音频。

4.7 隐私默认值调整需团队知晓（提示，非缺陷）

• history.enabled 与 audio.save_failed_audio 默认改为 true；老配置里显式的 false 不做迁移（隐私开关不替用户打开），这个取舍是正确的，但 AGENTS.md 红线口径已随之从“不落盘”改为“日志不落盘、用户数据文件可落盘”，需要在评审中明确认知，避免后续把历史/失败语音误当日志清理。

---

五、回归与验收建议

1. 红线测试：确认日志中不出现识别文本/音频内容（新增字段 audio_saved、记录 id、removed 均为元信息）；docs/27 §7 的 redaction 验收项目前仍是未勾选状态，建议补一条自动化断言。
2. 权限断言：补测失败语音文件 mode == 0600（对应 4.1），否则目录权限一旦放宽即暴露。
3. 重试链路：go test -race ./internal/session/ ./internal/history/ 覆盖“失败→重试成功/重试再失败/会话忙时拒绝”三条路径（已有 history_test.go，建议再加“看门狗切断后重试”的交叉用例）。
4. 配置迁移：TestMigrate_LegacyMaxSessionSecUpgraded 已覆盖 180→300 且保留用户自定义值；建议补“显式 false 的历史开关不被迁移”的负向用例。
5. 前端：补 restartDaemonAndWait 的超时失败用例（对应 4.2）。
6. 复杂度治理：session.Session 上帝类（80 方法）与 deliver(111 行/fan-out 29) 建议作为下一轮拆分目标——本次改动已把“正常会话”与“失败重试”合流到同一实现（这是正确方向），但可继续把“上屏/历史落盘/阶段计时”抽为独立协作者。

---

附：工具统计口径提醒

• 修复 66 / 新增 99 为行号与文件粒度的对比结果，含大量“同一问题因行号漂移重复计入”与“删文件导致的伪修复”。真正需要评审的是第四节列出的 7 项人工发现，以及 session.go/history.go/tray.go 的复杂度与重复代码新增项。