docs: add code quality cleanup roadmap (fixes #699)

[zsxh1990]

User description

Summary

Document the code quality cleanup items from the 1-app audit (2026-06-17).

Changes

• Add docs/CODE_QUALITY_CLEANUP.md with detailed roadmap
• Covers all 3 items from Code quality cleanup (polish.rs duplication, blanket allow, mobile_stubs naming) #699 with execution order

Items Documented

1. [windows] 启动首屏被麦克风权限探测阻塞 #27: Remove blanket allow — Lowest risk, immediate value
2. [infra/devex] Windows 真机回归缺少真实凭据和物理热键门禁 #32: Rename misleading stub — Quick win, improves clarity
3. chore(release): rustfmt 后端 + 更新 CLAUDE.md #24: Extract shared builder — Most complex, do last

Next Steps

• Install Rust toolchain for compilation verification
• Execute cleanup in documented order
• Each step includes verification checklist

Closes #699

/claim #699

---

PR Type

Enhancement, Bug fix, Tests, Documentation

---

Description

• 主窗 UI 大改：聊天面板统一尺寸、macOS 非激活 NSPanel

• Apple Speech ASR 改进：locale 支持、on-device、取消等待、流式简繁

• 活动热力图与 Less Computer 缓冲同步

• 按键事件配对修复（macOS 侧修饰键）及 Linux 拒绝

• 持久化：样式偏好保留、活动计数写入

---

Diagram Walkthrough

flowchart LR
  lib["lib.rs 窗口管理重构"] --> panel["聊天面板统一尺寸 & 非激活 NSPanel"]
  lib --> hideAnim["退场动画 (epoch)"]
  lib --> capsule["胶囊尺寸统一 & 光效舞台"]
  apple["AppleSpeechAsr 改进"] --> locale["locale 支持"]
  apple --> onDevice["On-Device 识别"]
  apple --> cancelFlag["取消标志 + 轮询等待"]
  dict["dictation.rs"] --> buff["事件缓冲 (less_computer_sync)"]
  dict --> warming["乐观胶囊显示 (warming)"]
  dict --> streamingT2S["流式 t2s 转换"]
  volc["Volcengine ASR"] --> retry["连接重试 & 限流分类"]
  volc --> speaker["声纹过滤 (主说话人)"]
  combo["side_aware_combo"] --> pairFix["事件配对自愈"]
  combo --> linuxReject["Linux 拒绝"]
  settings["settings.rs"] --> preserveStyle["持久化时保留样式偏好"]
  coord["coordinator.rs"] --> activity["ActivityStore 热力图"]
  pref["preferences.rs"] --> preserveStyle

Loading

File Walkthrough

	Relevant files
Enhancement	17 files lib.rs 聊天面板窗口重构（尺寸、NSPanel、退场动画）                                                                +156/-146 apple_speech_provider.rs Apple Speech ASR 改进（locale、on-device、取消等待）                              +311/-32 dictation.rs Less Computer 缓冲、乐观胶囊、流式简繁转换                                                          +173/-26 volcengine.rs 连接重试、限流分类、声纹过滤                                                                                      +215/-33 coordinator.rs 添加 ActivityStore 与文本提交命令                                                                  +49/-17  preferences.rs 添加 set_preserving_current_style_preferences                            +53/-1    activity.rs 每日活动计数存储                                                                                                  +69/-0    SiriGL.tsx 语音光效舞台组件                                                                                                  +471/-0  Heatmap.tsx 活动热力图组件                                                                                                    +222/-0  avatars.tsx 聊天头像组件                                                                                                      +148/-0  input-group.tsx 聊天输入组样式更新                                                                                                +155/-0  bubble.tsx 聊天气泡样式更新                                                                                                  +128/-0  orbFeed.ts 语音光效动画逻辑                                                                                                  +129/-0  Tooltip.tsx 工具提示组件                                                                                                      +135/-0  message-scroller.tsx 消息滚动组件                                                                                                      +128/-0  button.tsx 聊天按钮组件                                                                                                      +62/-0    card.tsx 聊天卡片组件                                                                                                      +100/-0
Bug fix	2 files side_aware_combo.rs 按键事件配对修复、Linux 拒绝                                                                                +248/-7  settings.rs 持久化时保留样式偏好                                                                                              +141/-10
Documentation	1 files CODE_QUALITY_CLEANUP.md 代码质量清理路线图文档                                                                                            +98/-0
Additional files	80 files README.md +16/-1    README.zh.md +16/-1    package.json +20/-4    Cargo.toml +4/-3      bailian.rs +27/-0    mod.rs +1/-1      stream.rs +23/-0    history.rs +12/-0    mod.rs +2/-1      providers.rs +15/-1    qa.rs +73/-9    asr_wiring.rs +11/-3    capsule_focus.rs +33/-3    hotkey_loops.rs +0/-1      qa.rs +0/-5      qa_session.rs +4/-0      insertion.rs +11/-3    credentials.rs +54/-5    mod.rs +2/-0      types.rs +33/-0    unicode_keystroke.rs +90/-40  windows_ime_profile.rs +83/-8    tauri.conf.json +4/-4      App.tsx +17/-11  AutoUpdate.tsx +1/-1      Capsule.tsx +223/-326 FloatingShell.tsx +197/-132 Kbd.tsx +45/-0    MarketplaceModal.tsx +0/-125  SettingsModal.tsx +9/-8      ShortcutRecorder.tsx +4/-4      ThinkingDots.tsx +75/-0    chat.css +341/-0  index.ts +64/-0    utils.ts +7/-0      lifecycle.ts +51/-0    markdown.tsx +40/-0    empty.tsx +105/-0  input.tsx +20/-0    marker.tsx +71/-0    message.tsx +92/-0    spinner.tsx +18/-0    textarea.tsx +18/-0    Modal.tsx +9/-2      en.ts +33/-4    ja.ts +33/-4    ko.ts +33/-4    zh-CN.ts +35/-6    zh-TW.ts +35/-6    audioCue.test.ts +36/-0    audioCue.ts +82/-25  capsuleLayout.test.ts +25/-23  capsuleLayout.ts +18/-22  hotkey.ts +9/-2      chat-panel.ts +13/-0    history.ts +7/-2      index.ts +7/-5      less-computer.ts +11/-4    mock-data.ts +20/-0    qa.ts +0/-4      stylePrefs.test.ts +1/-0      types.ts +23/-2    LessComputerGlow.tsx +169/-96 LessComputerPanel.tsx +559/-469 Marketplace.tsx +28/-5    Overview.tsx +66/-2    QaPanel.tsx +368/-831 Style.tsx +9/-24    LocalModelSection.tsx +1/-1      PermissionsSection.tsx +8/-2      ProvidersSection.tsx +3/-2      RemoteInputSection.tsx +1/-1      ThemeSection.tsx +12/-1    tabs.tsx +34/-14  useAppState.ts +1/-0      global.css +79/-0    tokens.css +113/-119 vite.config.ts +4/-1      ipc_client.cpp +109/-40 ipc_client.h +12/-4

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 699 - Partially compliant Compliant requirements: None of the three requirements are fulfilled by the changes shown in the diff. Non-compliant requirements: Blanket allow removal not addressed. Stub rename not addressed. Shared builder extraction not addressed. Requires further human verification: The PR description claims to close Code quality cleanup (polish.rs duplication, blanket allow, mobile_stubs naming) #699 and adds docs/CODE_QUALITY_CLEANUP.md, but this is not included in the diff (truncated). It is unclear whether the actual cleanup steps will be executed in separate PRs or if this PR is mislabeled. 27 - Partially compliant Compliant requirements: None of the Windows startup changes are present in this diff. Non-compliant requirements: Windows startup behavior unchanged. Microphone permission gate still blocks main UI. Requires further human verification: The PR description mentions unrelated UI changes but the actual diff includes macOS panel improvements and Apple Speech ASR changes. If this PR was intended to address [windows] 启动首屏被麦克风权限探测阻塞 #27, it does not. 32 - Partially compliant Compliant requirements: None of these items appear in the diff. Non-compliant requirements: No credentials requirement checks added. No regression script provided. Requires further human verification:

⏱️ Estimated effort to review: 5 🔵🔵🔵🔵🔵

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Incorrect NSPanel Style Mask and Level The nonactivating NSPanel conversion uses 1 << 7 (128) as the style mask. Apple's NSNonactivatingPanelMask is defined as 1 << 8 (256). Using the wrong bit may cause the panel to still activate the app, defeating the purpose. Additionally, panel.set_level(3) is used, but NSFloatingWindowLevel is 5, not 3. Level 3 (NSTornOffMenuWindowLevel) sits below floating windows, which could cause the chat panel to be hidden behind other floating windows in practice. This affects both make_chat_window_panel_macos and make_chat_window_draggable_macos usage. fn make_chat_window_panel_macos<R: tauri::Runtime>(window: &tauri::WebviewWindow<R>, tag: &str) { use tauri_nspanel::cocoa::appkit::NSWindowCollectionBehavior; use tauri_nspanel::WebviewWindowExt; match window.to_panel() { Ok(panel) => { const NS_NONACTIVATING_PANEL_MASK: i32 = 1 << 7; panel.set_style_mask(NS_NONACTIVATING_PANEL_MASK); // 浮层级别（NSFloatingWindowLevel）：盖普通窗口，不盖菜单栏/胶囊(25)。 panel.set_level(3); panel.set_collection_behaviour( NSWindowCollectionBehavior::NSWindowCollectionBehaviorFullScreenAuxiliary | NSWindowCollectionBehavior::NSWindowCollectionBehaviorCanJoinAllSpaces, ); log::info!("[{tag}] converted to nonactivating NSPanel"); } Err(e) => log::warn!("[{tag}] to_panel failed: {e:?}"), } Missing NSException catch in ObjC msg_send! for setMovable The make_chat_window_draggable_macos function wraps the msg_send! calls in an objc2::exception::catch block, which is good. However, there is a potential issue: if ns_window is retrieved successfully but setMovableByWindowBackground: raises an exception, the catch block captures it. But the setMovable: call is also inside the same catch. If the first call succeeds but the second fails, the exception is caught and logged. This is acceptable, but the safety comment claims that the closure has no Rust values needing drop. This is correct, but the comment could be clearer that the catch does not prevent all memory unsafety if an exception is raised (e.g., if a Rust value with a destructor were present). For now, it's safe. /// 解法是把 NSWindow 的 `movableByWindowBackground` 打开——这条路径不依赖窗口是否成为 /// key window，跟 Spotlight / Raycast 的浮窗是同一手法。设一次就够，整个生命周期保持。 #[cfg(target_os = "macos")] fn make_chat_window_draggable_macos<R: tauri::Runtime>(window: &tauri::WebviewWindow<R>, tag: &str) { use objc2::msg_send; use objc2::runtime::{AnyObject, Bool}; let Ok(handle) = window.ns_window() else { log::warn!("[{tag}] ns_window unavailable; drag fix skipped"); return; }; let ns_window = handle as *mut AnyObject; if ns_window.is_null() { log::warn!("[{tag}] ns_window null; drag fix skipped"); return; } // 异常兜底：AppKit 在 drag margins 状态不一致时会从 setMovable 内部 raise // NSException；不捕获的话异常穿过 Rust 边界直接 abort 整个 app。捕获后降级为 // 日志（拖动失效但 app 活着），日志会指认具体异常便于追根因。 // SAFETY: 闭包内只有两个无返回值的 ObjC 消息发送，没有需要运行析构的 Rust 值， // 异常展开跳过闭包帧不会破坏内存安全。 let result = unsafe { objc2::exception::catch(std::panic::AssertUnwindSafe(|| { let _: () = msg_send![ns_window, setMovableByWindowBackground: Bool::YES]; let _: () = msg_send![ns_window, setMovable: Bool::YES]; })) }; match result { Ok(()) => log::info!("[{tag}] NSWindow movableByWindowBackground=YES"), Err(e) => { log::error!("[{tag}] drag setup raised ObjC exception (caught, drag disabled): {e:?}") } } Potential Data Race on Global Event Log LESS_COMPUTER_EVENT_LOG is a global OnceLock<Mutex<LessComputerEventLog>>. The log_less_computer_event function holds the mutex lock while pushing to the VecDeque. However, the emit_less_computer function only locks when the log is available; if the lock is poisoned (e.g., panic while holding the lock), every subsequent call will skip the log and fall back to emitting without seq, which is a degraded behavior. This is an acceptable trade-off but could lead to silent data loss if the poison persists, and unwrap_or_default() in less_computer_event_backlog() swallows the error. Consider using std::sync::PoisonError::into_inner to recover or at least log the poisoning. static LESS_COMPUTER_EVENT_LOG: std::sync::OnceLock<std::sync::Mutex<LessComputerEventLog>> = std::sync::OnceLock::new(); fn less_computer_event_log() -> &'static std::sync::Mutex<LessComputerEventLog> { LESS_COMPUTER_EVENT_LOG.get_or_init(|| { std::sync::Mutex::new(LessComputerEventLog { next_seq: 0, events: std::collections::VecDeque::new(), }) }) } /// 纯逻辑：给 payload 编 seq 并写入缓冲（fresh user 先清空，超限丢最旧）。 fn log_less_computer_event(log: &mut LessComputerEventLog, payload: &mut serde_json::Value) { let fresh_user = payload.get("kind").and_then(|k| k.as_str()) == Some("user") && payload.get("fresh").and_then(|f| f.as_bool()) == Some(true); if fresh_user { log.events.clear(); } log.next_seq += 1; payload["seq"] = serde_json::json!(log.next_seq); log.events.push_back(payload.clone()); while log.events.len() > LESS_COMPUTER_EVENT_LOG_CAP { log.events.pop_front(); } } /// `less_computer_sync` 命令的数据源：当前会话已发生的事件（seq 升序）。 pub(crate) fn less_computer_event_backlog() -> Vec<serde_json::Value> { less_computer_event_log() .lock() .map(|log| log.events.iter().cloned().collect()) .unwrap_or_default() }