refactor: coordinator.rs/commands.rs 单一职责拆分 + 重复函数合并（机械式·零回归）

[appergb]

User description

这是什么

把 Less Computer 语音 Agent 落地后膨胀的两个超大文件按单一职责拆分，并合并若干重复函数。纯机械式、行为保持——无逻辑改动，全程 cargo check / cargo test --lib / npm run build 绿，417 个单测零回归。

本 PR 基于 #597（base = feat/fast-agent），stacked on #597：请先合 #597，再合本 PR（届时 GitHub 自动收敛 diff）。

改了什么

1. coordinator.rs 拆分（5985 → 1145 行）

Coordinator/Inner/ActiveAsr/impl Coordinator 留在父模块；其余按职责抽到 coordinator/ 子模块。靠 glob 重导出契约（pub(crate) use <new>::*）保住既有 use super::* 裸名引用，零调用点改写：

子模块	行	职责
hotkey_supervisors.rs	920	各 supervisor/bridge 热键监督循环
qa_session.rs	690	QA 问答会话主流程
llm_pipeline.rs	660	polish/translate/provider/凭证
ime_insertion.rs	598	Win IME / 焦点 / capsule 原生 glue
asr_setup.rs	506	ASR 引擎构建 + 生命周期
capsule.rs	358	emit_capsule + 布局 + 显示策略
voice_agent_hotkeys.rs	350	less-computer + 快取用热键
tests.rs	846	外移的 #[cfg(test)] mod tests

并发敏感代码（音频回调 ~30Hz 的 emit_capsule、各 bridge loop 的 P0 #468/#475 序列化、#118 主线程注册、DeferredAsrBridge、跨 await 持锁的 end_qa_session）逐字搬运，未动锁作用域 / block_on / spawn。

2. commands.rs 拆分（4857 → commands/ 17 文件）

转成 commands/mod.rs + pub use <domain>::* glob 重导出 → tauri::generate_handler! 与 lib.rs 零改动。127 个 #[tauri::command] 命令面逐一 parity 核对，无增删。16 个域模块（settings/credentials/providers/history/dictionary/dictation/style_packs/permissions/qa/hotkeys/local_asr/foundry_asr/sherpa_asr/marketplace/github_oauth/misc）均 <800 行。

3. 重复函数合并

• pcm_duration_ms：4 处（foundry/sherpa×2/whisper）→ 共享 asr/pcm.rs，消除魔数。
• take_*_on_main_thread：3 处近重复 → 共享 helper。
• less_computer 两个 bridge loop（仅事件枚举不同）→ 合并。
• 前端 formatTime/formatDuration/formatBytes/clamp → src/lib/format.ts。

跨端弹窗一致性核查（任务附带）

重构后 capsule 路径契约测试 macos-capsule-spaces / hotkey-injection 全过。一致性矩阵：capsule(mac ✅ / Win ⚠️#470 定位脆弱 / Linux 改用 fcitx5 aux)、qa(mac 不抢焦点 / Win 抢一帧 #466)、less-computer + glow(设计仅 mac)。

Windows capsule #470 定位修复（四边 clamp + 句柄重试）不在本 PR——仓库已有 chore/issue-470-capsule-diagnostics-v2 专门分支处理，避免重复/冲突。

不在范围

• dictation.rs（2766 行）：拆分前就大，属既有，可另行拆分。
• 去重 C2（supervisor loop 泛化）/ C5（音频热路径 drain）：中风险，暂缓。

测试

• cargo check：0 error（55 warning = 拆前基线，无新增）
• cargo test --lib：417 passed / 0 failed
• npm run build：成功
• 契约测试：macos-capsule-spaces ✅ / hotkey-injection ✅
• 本机仅 macOS target；Windows/Linux 的 cfg 分支靠本 CI（mac/win/linux）兜底。

---

PR Type

Other

---

Description

• Split 4800-line coordinator.rs and 5985-line commands.rs into focused modules

• Merged duplicate functions (pcm_duration_ms, open_path_in_file_manager)

• Mechanical, behavior-preserving with glob re-exports

• Zero regression: all 417 tests pass, cargo check and tsc clean

---

Diagram Walkthrough

flowchart LR
coord["coordinator.rs"] --> hs["hotkey_supervisors.rs"]
coord --> qa["qa_session.rs"]
coord --> llm["llm_pipeline.rs"]
coord --> ime["ime_insertion.rs"]
coord --> asr["asr_setup.rs"]
coord --> cap["capsule.rs"]
coord --> tests["tests.rs"]
cmd["commands.rs"] --> set["settings.rs"]
cmd --> cred["credentials.rs"]
cmd --> prov["providers.rs"]
cmd --> hot["hotkeys.rs"]
cmd --> dict["dictation.rs"]
cmd --> misc["misc.rs"]
cmd --> hist["history.rs"]
cmd --> sty["style_packs.rs"]
cmd --> fnd["foundry_asr.rs"]
cmd --> shr["sherpa_asr.rs"]
cmd --> lcl["local_asr.rs"]
cmd --> qa_cmd["qa.rs"]
cmd --> mkt["marketplace.rs"]
cmd --> gh["github_oauth.rs"]
cmd --> perm["permissions_cmds.rs"]
cmd --> dict2["dictionary.rs"]

Loading

File Walkthrough

	Relevant files
Refactoring	19 files mod.rs New module with glob re-exports of 16 domain submodules +1364/-0 hotkey_supervisors.rs Supervisor and bridge loops for dictation, QA, combo, translation, action hotkeys +925/-0 ime_insertion.rs Windows IME session, TSF insertion, focus capture, capsule window management +598/-0 dictation.rs Extracted dictation Tauri commands (start, stop, cancel, repolish) +49/-0 sherpa_runtime.rs Replaced inline pcm_duration_ms with centralized crate::asr::pcm version +1/-1 qa_session.rs Extracted QA session flow module +690/-0 llm_pipeline.rs Extracted polish, translate, provider management module +660/-0 asr_setup.rs Extracted ASR engine construction and lifecycle +506/-0 capsule.rs Extracted capsule HUD display, layout, emit logic +358/-0 settings.rs Extracted settings persistence commands +412/-0 credentials.rs Extracted credentials and ASR/LLM configuration commands +227/-0 providers.rs Extracted provider model fetch and validation +496/-0 hotkeys.rs Extracted hotkey binding commands +408/-0 local_asr.rs Extracted local ASR commands (Qwen) +309/-0 foundry_asr.rs Extracted Foundry ASR commands +190/-0 sherpa_asr.rs Extracted Sherpa ONNX ASR commands +192/-0 misc.rs Extracted miscellaneous Tauri commands +123/-0 permissions_cmds.rs Extracted permissions-related commands +100/-0 history.rs Extracted history and recording commands +50/-0
Tests	1 files tests.rs Moved #[cfg(test)] mod tests from coordinator.rs +846/-0
Additional files	22 files macos-capsule-spaces-contract.test.mjs +4/-2 foundry_provider.rs +1/-1 sherpa_provider.rs +2/-2 mimo.rs +1/-1 mod.rs +1/-0 pcm.rs +41/-0 whisper.rs +1/-1 commands.rs +0/-4857 dictionary.rs +79/-0 github_oauth.rs +154/-0 marketplace.rs +404/-0 qa.rs +67/-0 style_packs.rs +287/-0 coordinator.rs +44/-4884 voice_agent_hotkeys.rs +356/-0 AutoUpdate.tsx +3/-4 format.ts +71/-0 History.tsx +3/-14 LocalAsr.tsx +3/-4 Overview.tsx +3/-14 DataStorageSection.tsx +1/-3 DebugToolsSection.tsx +1/-2

---

[appergb]

@claude 复审这个纯机械式重构 PR。它把 Less Computer 落地后膨胀的两个超大文件按单一职责拆分 + 合并重复函数，声称零逻辑改动、行为保持。请重点验证「机械式」这一点是否成立：

请核验

1. 行为保持：拆分是否纯剪切+可见性提升？有没有任何函数体被无意改动（锁作用域、block_on/spawn、await 点、cfg 分支）？特别是并发敏感区——emit_capsule（音频回调）、各 bridge/supervisor loop（[windows] 启动时静默运行功能在 Win11 失效 #468/[ui] 悬窗透明遮罩异常透出底层内容 #475 序列化、[feature] 划词语音问答（Selection + Voice Q&A） #118 主线程注册）、DeferredAsrBridge、end_qa_session 跨 await 持锁。
2. glob 重导出契约：coordinator.rs 的 pub(crate) use <sub>::* 和 commands/mod.rs 的 pub use <domain>::* 是否完整覆盖、无遗漏导致的 super:: 裸名失配？commands::<name> 路径是否真全部不变（lib.rs 零改）？
3. 命令面 parity：127 个 #[tauri::command] 是否无增删？generate_handler! 仍能解析全部？
4. 去重正确性：pcm_duration_ms/take_*_on_main_thread/less_computer bridge loop 合并后语义是否等价？前端 formatBytes 统一后两个调用点的显示是否与原先逐字一致（AutoUpdate 封顶 MB+guard vs LocalAsr 到 GB）？
5. cfg 完整性：foundry/sherpa/ime 等大量 #[cfg(windows)]/#[cfg(target_os)] 是否都跟函数原样搬走（本机仅能 check macOS，Windows/Linux 靠 CI 兜底）？

已验证

cargo check 0 error（55 warning = 拆前基线无新增）、cargo test --lib 419 passed、npm run build 绿、契约测试 macos-capsule-spaces/hotkey-injection 通过。

请判断是否可以合并（注意本 PR base 是 feat/fast-agent，stacked on #597）。

[claude]

Claude finished @appergb's task in 5m 21s —— View job

---

PR #615 机械式重构复审

任务清单

• 读取 diff（git diff origin/feat/fast-agent...HEAD）
• 核验 1：行为保持（并发敏感区逐字比对）
• 核验 2：glob 重导出契约完整性
• 核验 3：#[tauri::command] 命令面 parity
• 核验 4：去重正确性（pcm_duration_ms / take_* / bridge loop / formatBytes）
• 核验 5：cfg 平台分支完整性

---

结论：✅ 机械式声明成立，可以合并

5 个核验点逐一通过，未发现任何语义变动。以下是详细复审报告。

---

核验 1：行为保持（并发敏感区）

emit_capsule（音频回调 ~30Hz，coordinator/capsule.rs）

• run_on_main_thread marshaling 路径逐字保留（SIGTRAP 规避，audit 3.2.2）
• app.emit_to("capsule", ...) + app.emit_to("main", ...) 调用顺序不变
• 先写 last_capsule_state、再取 app、再 run_on_main_thread 的顺序保持 ✅

hotkey_bridge_loop（P0 #468/#475 序列化，coordinator/hotkey_supervisors.rs:737）

• HotkeyEvent::Pressed/Released 的 block_on 顺序执行语义保留
• QaShortcutPressed 仍走 spawn（不阻塞 bridge 线程，正确）
• 与原版逐字一致，无 spawn/block_on 替换 ✅

DeferredAsrBridge（coordinator/asr_setup.rs:442）

• attach 函数中 attaching flag + loop-flush 交错协议保留
• consume_pcm_chunk 的 attaching 判断路径保留
• 模块 docstring 明确标注"并发敏感，只搬不改" ✅

end_qa_session 跨 await 持锁（coordinator/qa_session.rs）

• 模块 docstring 明确: "end_qa_session 跨 await 持/放 qa_state 锁……是全文件最并发敏感的函数，只搬不改" ✅

#118 主线程注册

• qa_hotkey_supervisor_loop 的 run_on_main_thread + init_rx.recv_timeout 回执模式保留 ✅

---

核验 2：glob 重导出契约

来源	子模块	重导出方式	状态
coordinator.rs	asr_setup / capsule / hotkey_supervisors / ime_insertion / llm_pipeline / qa_session / voice_agent_hotkeys	pub(crate) use <sub>::*	✅ 7 个全覆盖
coordinator.rs	dictation / qa / resources	显式命名导入（非 glob）	✅ 设计正确
commands/mod.rs	credentials / dictation / dictionary / foundry_asr / github_oauth / history / hotkeys / local_asr / marketplace / misc / permissions_cmds / providers / qa / settings / sherpa_asr / style_packs	pub use <domain>::*	✅ 16 个全覆盖

lib.rs diff = 0 行，cargo check 0 error 双重确认路径解析正确 ✅

---

核验 3：命令面 parity

原 commands.rs (origin/feat/fast-agent): 127 个 #[tauri::command]
新 commands/ 模块（函数级精确计数）: 127 个

初始 grep 计数 129 是因为 mod.rs:4 和 mod.rs:8 的注释文字里有 #[tauri::command] 字符串（不是属性）。函数级过滤后精确匹配 127。

generate_handler! 清单（lib.rs 零改）仍完整有效 ✅

⚠️轻微问题：commands/mod.rs:4 注释写"89 个 #[tauri::command]"，实际是 127 个——是早期开发时的遗留注释。不影响功能，建议下一次顺手修正。

---

核验 4：去重正确性

pcm_duration_ms（asr/pcm.rs）

模块	原始公式
foundry_provider	(pcm.len() as u64 / 2) * 1000 / 16_000
sherpa_provider	(bytes / 2) * 1000 / 16_000
sherpa_runtime	(pcm.len() as u64 / 2) * 1000 / 16_000
mimo	(pcm.len() / PCM_BYTES_PER_SAMPLE as u64) * 1000 / PCM_SAMPLE_RATE_HZ（同常量）

新共享实现：(bytes / PCM_BYTES_PER_SAMPLE) * 1000 / PCM_SAMPLE_RATE_HZ，展开后完全等价。各模块保留薄包装函数（保证测试中 super::pcm_duration_ms 调用不变）✅

take_combo_monitor_on_main_thread（hotkey_supervisors.rs:602）

• 泛型 slot: impl Fn(&Arc<Inner>) -> &Mutex<Option<ComboHotkeyMonitor>> + Send + 'static 正确
• run_on_main_thread 闭包内的 slot(&inner).lock().take() 与原三处逐字一致
• take_action_hotkey_on_main_thread 单独实现（字段类型相同但 action 走不同 slot 函数）保持正确 ✅

less_computer 两个 bridge loop

• LessComputerEdge 枚举中间层正确归一：HotkeyEvent::Pressed/Released/Cancelled ↔ ComboHotkeyEvent::Pressed/Released
• block_on 语义在泛型循环体内保留 ✅

前端 formatBytes（src/lib/format.ts）

调用方	参数	等价原始行为
AutoUpdate.tsx	{ maxUnit: 'MB', guard: true }	guard 检查 + 封顶 MB + toFixed(1) ✅
LocalAsr.tsx	{ maxUnit: 'GB', mbDigits: 0 }	MB 用 toFixed(0) + 升 GB ✅

两个调用点行为与各自原始实现精确等价 ✅

---

核验 5：cfg 完整性

• coordinator/ime_insertion.rs：#[cfg(target_os = "windows")] 大量 Windows IME 胶水代码搬入独立文件，编译单元隔离正确
• coordinator/asr_setup.rs：#[cfg(not(target_os = "macos"))] / #[cfg(target_os = "windows")] 分支保留
• commands/sherpa_asr.rs：#[allow(unused_imports)] 标注正确处理非 Windows 的 glob 引入无使用问题
• macOS 本地 cargo check + CI mac/win/linux 矩阵提供 3 平台 cfg 分支覆盖 ✅

---

额外观察

空节段标题残留：coordinator.rs:1103-1107 有两个空的 // ─── hotkey bridging ─── / // ─── session lifecycle ─── 注释，原来的实现搬走后成了空标题。纯外观，可趁机清理。

代码组织：16 个 commands 域模块命名清晰，各文件 <800 行目标达到。coordinator/ 结构也让曾经的 5985 行变成可维护的 9 个专注文件。

---

综合判断：可以合并 ✅

本 PR 的「机械式、行为保持」声明经核验成立。所有并发敏感路径（emit_capsule、block_on 序列化、DeferredAsrBridge、end_qa_session、#118 主线程注册）均逐字原样搬运，无锁作用域更改、无 await 点插入/删除、无 spawn/block_on 替换。glob 重导出契约完整，命令面 127 个全部保留，去重语义等价。

唯一建议（可选，不影响合并）：修正 commands/mod.rs:4 注释中"89 个"的过时计数。

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit bdd26fb)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 475 - Partially compliant Compliant requirements: (empty - this PR is a mechanical refactoring, not addressing the bug) Non-compliant requirements: Windows 下打开 OpenLess 悬窗后，主体内容区不再异常透出底层应用内容。 默认提示页、录音中状态和结果展示状态的背景透明度符合设计预期，正文内容清晰可读。 悬窗圆角、边框、阴影和底部状态栏在截图复现场景中没有异常透明层叠。 Requires further human verification: (empty) 597 - Partially compliant Compliant requirements: (empty - this PR is a refactoring, not implementing the feature) Non-compliant requirements: 专用键（macOS，coding_agent_voice_hotkey） 动作模式（放行+护栏） 连续对话 流式聊天弹框（less-computer） 全屏彩虹描边（less-computer-glow） 设置：模型下拉、Cloud 控制台默认折叠、胶囊处理态文案 agent 单次超时 300s / 预算 $2 Requires further human verification: (empty) 470 - Partially compliant Compliant requirements: (empty - this PR is a mechanical refactoring, not addressing the bug) Non-compliant requirements: 语音输入时显示录音胶囊 Requires further human verification: (empty)

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ No major issues detected

[github-actions]

Persistent review updated to latest commit bdd26fb

[appergb]

@claude 合并前最终复审。本 PR = coordinator.rs(5985→1145, 8 子模块) / commands.rs(→17 域模块, lib.rs 零改) 单一职责拆分 + 5 簇重复函数合并，声明机械式·零回归。最新 bdd26fb。栈整体已过一轮 4 维度自审：127 个 #[tauri::command] 数一致、glob 重导出契约完好、合并函数逐字等价、cargo test 475 passed。请确认无行为改变、可合并。

[claude]

Claude finished @appergb's task in 2m 3s —— View job

---

PR #615 合并前最终复审

任务清单

• 读取最新 diff（bdd26fb，基于 origin/feat/fast-agent，15 commits / 42 files）
• 核验并发敏感区（emit_capsule / bridge loop / DeferredAsrBridge / end_qa_session）
• 核验 glob 重导出完整性 + 命令面 parity（127 个）
• 核验合并函数语义等价（pcm_duration_ms / formatBytes）
• 最终合并判断

---

结论：✅ 可以合并

本轮复审对所有并发敏感路径、重导出契约、命令面计数、合并函数做了独立核验，"机械式、行为保持"声明成立。

---

最新 commit bdd26fb

仅修正 commands/mod.rs 注释中"89 个"→"127 个"——正是上轮复审唯一建议的可选修正，已落实。功能零改动。

---

核验 1：并发敏感区（逐点）

emit_capsule（capsule.rs:104-223）

• *inner.last_capsule_state.lock() = Some(state)先写（:104）
• 再取 inner.app.lock().clone()（:105）
• 再 app.run_on_main_thread(…)（:223）
• 顺序与原版一致，SIGTRAP 规避路径保留 ✅

hotkey bridge loop（hotkey_supervisors.rs:744-777）

• HotkeyEvent::Pressed/Released → async_runtime::block_on（P0 [windows] 启动时静默运行功能在 Win11 失效 #468/[ui] 悬窗透明遮罩异常透出底层内容 #475 串行语义保留）
• HotkeyEvent::QaShortcutPressed → async_runtime::spawn（不阻塞 bridge 线程，正确）
• 注释完整保留了序列化原因说明 ✅

DeferredAsrBridge（asr_setup.rs:442-503）

• attaching flag + loop-flush 交错协议逐字搬运（:449/:467/:475/:490/:503）
• consume_pcm_chunk 中 attaching 判断路径保留 ✅

end_qa_session（qa_session.rs:232-）

• qa_state.lock() 合并写的注释保留（":81 合并两次 lock"），持锁期间调用安全分析完整 ✅

---

核验 2：glob 重导出契约

模块	重导出数	方式
coordinator.rs	7 个子模块	pub(crate) use *
coordinator.rs	dictation / qa / resources	显式命名（设计正确）
commands/mod.rs	16 个域模块	pub use *

lib.rs diff = 空（零改），cargo check 0 error 双重确认路径解析正确 ✅

---

核验 3：命令面 parity

grep -rn "^#\[tauri::command\]" commands/ | wc -l → 127

与 PR 声明完全一致，generate_handler! 清单有效 ✅

---

核验 4：合并函数语义等价

pcm_duration_ms（asr/pcm.rs）

// 公式：(bytes / 2) * 1000 / 16_000pubfnpcm_duration_ms(pcm:&[u8]) -> u64{(pcm.len()asu64 / PCM_BYTES_PER_SAMPLE)*1000 / PCM_SAMPLE_RATE_HZ}

带 2 个回归测试（1 秒 PCM = 1000ms；末尾奇数字节向下取整），等价历史实现 ✅

formatBytes（src/lib/format.ts）

调用方	参数	等价原始行为
AutoUpdate	{ maxUnit: 'MB', guard: true }	封顶 MB + guard 保护 ✅
LocalAsr	{ maxUnit: 'GB', mbDigits: 0 }	MB 0 位小数 + 升 GB ✅

两处均通过本地薄封装函数委托，参数精确对应原始独立实现 ✅

---

综合判断

所有 5 个核验维度通过，上轮复审唯一的可选建议（注释计数过时）已在 bdd26fb 修正。机械式重构声明经独立复核成立——并发敏感路径（emit_capsule 顺序、block_on 串行化、DeferredAsrBridge attach 协议、end_qa_session 锁作用域）均逐字原样搬运，无锁顺序变更、无 await 点增删、无 spawn/block_on 互换。