OpenHuman 核心精简迁移评审修复设计：PR 5125 的行为还原、并发收敛与验证矩阵

导读

本文解析 OpenHuman 在大型「核心精简（core-slimming）」合并请求 PR #5125 上的一整套评审反馈修复设计。它解决的不是新功能，而是迁移过程中被意外丢弃的既有行为：Companion 会话的生命周期清理与全局热键、目标延续抑制与线程面板的持久化并发、语音面板的常驻聆听开关与能力目录披露，以及测试与 E2E 场景的退役对齐。读完本文，你可以掌握一种「按评审簇小步提交、每条修复配回归测试、旧线索对照当前 HEAD 复核」的收敛式回改方法，并看到这些原则如何在 OpenHuman 的 Rust 核心、Tauri 桌面壳与 React 前端中落地为具体的安全不变量。

该设计文档位于 docs/specs/2026-07-23-pr-5125-review-fixes-design.md，是全文的主体骨架；文中所有源码佐证均来自当前仓库，可在对应路径进一步核验。

一、背景：为什么「精简」也需要回改

PR #5125 是一次已经很大的核心瘦身迁移，涉及删除或搬迁一批模块。评审过程中暴露出一类典型风险：移除与搬迁的边界被刻意保留，但迁移过程会顺带把仍然需要的行为弄丢。这份设计文档的 Objective 定义得非常克制：

• 处理 PR #5125 上每一个可执行的未解决评审线程；
• 不扩大本来已经很大的改动范围；
• 保留预期的删除与搬迁边界；
• 同时恢复迁移意外丢失的行为。

换句话说，修复的目标不是推翻这次精简，而是在精简后的形态上做「精确补偿」。仓库中确实可以找到这一类「从旧形态迁移到新边界」留下的痕迹：例如语音常驻监听模块由 always_on.rs 聚合、通过 include! 拆分进 always_on_part_01.rs 与 always_on_part_02.rs（见 src/openhuman/voice/always_on.rs）；线程面板的既有异步锁与存储入口则在 src/openhuman/threads/README.md 中有明确的序列化约定。迁移后的形状是新旧代码共存的常态，因此评审线程里讨论的往往不是「写错了」，而是「这里的行为在搬迁时丢了」。

二、整体方法：评审聚类 + 原子提交 + 对照当前 HEAD

设计采用三段式收敛节奏，避免把所有修复堆成一个巨大补丁：

1. 按评审簇工作：把反馈分成若干小簇（Companion 生命周期、持久化并发、产品表面、测试对齐）；
2. 逐簇验证后单独原子提交：每个簇在其最窄的针对性测试通过后才提交；
3. 过时线程对照当前 HEAD 复核：如果后续 commit 已经修掉了某个报告的问题，就不再重复改代码，而是用验证证据去关闭该线程。

与「盲改」不同，这种做法的关键是第二条校验回路：先检查问题是否已随 HEAD 演进而消失，再决定是否动手，杜绝了重复劳动与回归噪音。

三、第一簇：Companion 生命周期与传输收敛

3.1 清理逻辑集中化：停止 / TTL 过期走同一条路径

第一个评审簇的落点是 Companion 会话的「终点状态」。原文档要求：

• 手动停止与 TTL 过期都要取消活动中的 turn；
• 停止麦克风采集；
• 移除会话；
• 发射 Idle 状态。

其背后是「终点必须唯一」。如果手动停止与 TTL 过期各自实现一套收尾逻辑，就会出现部分清理的窗口：turn 还在跑、麦克风还在采集、会话还挂在状态表里。把终点收敛成一条清理链路，才能保证无论谁触发，最终状态一致。

这一约束在源码中并非虚构。语音服务在 src/openhuman/voice/server_part_01.rs 中维护 ServerState::Idle，并做了原子状态迁移（Stopped → Idle），目的是防止并发 run() 进入；该文件在过期与收尾路径中都会把状态设回 Idle，体现了「反复终止调用不得破坏更新会话」的同一安全意图。常驻监听侧则用静态开关管理进程级状态（ENABLED、PAUSED），并注释明确说明 mic 流保持打开到下次启动为止（见 src/openhuman/voice/always_on_part_01.rs），任何收尾逻辑都必须与这套进程级生命周期协同。

3.2 Listening → Idle：取消与空转录不得覆盖更新的采集

第二个子点是状态机的回归漏洞：被取消的 turn 与空转录的 turn，在返回 Listening → Idle 时不能覆盖一个更新的采集。

这是一个典型的「迟到完成者」竞态：旧 turn 收尾时若粗暴地把状态置为 Idle，可能踩掉在此之间已经开始的新采集。因此修复要求在收尾/回退时做版本感知——只有在没有更新的采集存在时才允许把状态归位到 Idle。这与上面的原子状态迁移（Stopped → Idle）形成配合：状态转换必须可证明自己是「当前唯一合法的转移者」，否则宁可保持不动。

3.3 全局热键的注册时机

第三点要求：当用户启动 Companion 会话时才注册配置的全局热键，而不是在进程启动时无条件注册。这一改动让热键的占用窗口与会话生命周期一致——会话结束即释放，避免常驻占键带来与其他应用的冲突。

OpenHuman 语音侧的按键能力正是围绕「热键驱动」设计的：核心进程内的热键监听器负责广播 dictation:toggle 到前端（见 src/openhuman/voice/dictation_listener.rs）；激活模式分 tap（按键切换） 与 push（按住说话） 两种（见 src/openhuman/voice/hotkey.rs 与 src/openhuman/voice/cli.rs，CLI 侧可通过 --hotkey <combo> 与 --mode <tap|push> 显式配置）。把这些事实拼起来可以推断：迁移版本需要保证热键只在「开始 Companion 会话」这一用户动作上注册，并随会话清理一并释放，避免旧实现里「常驻注册 + 手动注销」在异常退出时泄漏热键。

3.4 传输目标固定：Companion 聊天只打 OpenHuman 后端基址

最后一个传输层面的评审点最贴近安全：

Companion 聊天请求必须解析到 OpenHuman 后端基址，绝不使用用户配置、携带不同凭据的推理 URL。

理由是凭据边界：用户可能为 LLM 推理配置了第三方 endpoint，其 URL 与凭据属于推理通道；Companion 会话携带的是 OpenHuman 账户会话凭据，若请求被误路由到该第三方 URL，等于把 A 的凭据发往 B 的源。该设计与文档「Error Handling and Safety」一节呼应——会话凭据只发往规范后端源。能力目录侧亦有佐证：平台目录中出现了 mobile.push_to_talk 这类条目（见 src/openhuman/platform/about_app/catalog_part_03.rs），说明语音/Companion 能力是目录化、需显式披露的能力，其底层的传输目标必须可审计。

四、第二簇：持久化并发

4.1 目标延续抑制：走 tinyagents 原子变更通道

Companion 类多轮体验会涉及「目标延续抑制（goal continuation suppression）」逻辑——某一轮结束时如果目标是延续性的，会被标记为 continuation_suppressed，等下一次用户主动发起的 turn 再清除。该状态维护在 src/openhuman/threads/goals/continuation.rs：它显式按 continuation_suppressed 过滤可延续目标，并确保turn 期间完成或被替换的目标不得被错误抑制。

迁移过程中如果改用了「整快照写回」的方式去清除该标记，就会覆盖并发期间用户对使用次数 / 状态的更新。因此设计文档要求：清除延续抑制必须改走 tinyagents 原子变更路径，同时保留当前目标身份与并发的 usage/status 变更。tinyagents 配置模块中大量 apply_* 系列函数（apply_agent_config、apply_team_models、apply_delegate，见 src/openhuman/agent/tinyagents/config.rs）体现了这个子系统「以窄范围原子层叠代替整体覆盖」的编程范式——目标延续抑制的清除应当复用同一套原子原语，而不是自造一条写回捷径。

4.2 线程面板：每个 board 的既有异步锁串行化所有读改写

第二点要求把所有线程面板（thread-board）的 read/modify/write 变更，都用既有 per-board 异步锁串行化。这与仓库中存储层的串行化纪律一致：

• 线程的 turn 快照按线程各存一个 JSON 文件（turn_state/store.rs），采用 tempfile → fsync → persist 的整文件原子覆盖，并通过进程级 parking_lot::Mutex 串行化（见 src/openhuman/threads/README.md）；
• 同文档还专门警告：异步 handler 里绝不直接调用同步的 memory_conversations API，而应使用 memory_conversations::blocking::*，因为同步入口在持有全局 Mutex 的同时做 fsync 的 JSONL IO，一旦排队过多就会让 Tokio worker 停摆，直接把 openhuman.threads_create_new 的 30 秒 RPC 预算打穿（Sentry TAURI-REACT-10 / #5156）。

文档要求的是更细粒度的 per-board 异步锁（而不是进程级大锁），目的是在保证读改写原子性与避免全局串行化拖垮并发之间取得平衡。

4.3 启动迁移路径：先完成、不占 Tokio worker

第三个并发点是启动时序：需要验证更新后的启动迁移路径确实在运行时 writer 可用前完成，并且不阻塞任何 Tokio worker。迁移若是启动期的文件整理，其理想形态是：在核心对外暴露读写能力之前一次性做完，而不是与首个写入请求赛跑；同时这类文件 IO 不能直接挂在 worker 上执行。结合上一节「不要用同步 IO 占 worker」的教训可以推断：该迁移路径应当被验证为走阻塞池或专用的启动阶段，避免首屏 RPC 因迁移 IO 排队而超时。

五、第三簇：产品表面还原

5.1 Voice 设置面板的常驻聆听开关

精简迁移曾把「常驻聆听（always-on listening）」开关从语音设置面板弄丢，修复要求用既有 voice settings RPC 把它还原。当前前端源码证明这套 RPC 通道仍然健在：

• 读取侧 loadVoiceSettings() 通过核心 RPC openhuman.config_get_client_config 拉取 voice_providers / stt_provider / tts_provider，再合并认证资料（见 app/src/services/api/voiceSettingsApi.ts）；
• 写入侧 saveVoiceSettings 对上一次快照做 diff 后只提交变更补丁（同一文件）；
• 设置面板中 toggleAlwaysOn 调用 openhumanUpdateVoiceServerSettings({ always_on_enabled: next })，采用乐观更新 + 失败回滚，随后调用 syncNotchVisibility 同步「notch」这一常驻聆听 HUD 的可见性（见 app/src/components/settings/panels/VoicePanel.tsx）。面板内对应该开关的文案 key 为 voice.debug.alwaysOn。

Rust 侧印证了该开关的语义：常驻聆听是显式 opt-in，受 config.voice_server.always_on_enabled 控制，启动与运行时都会读取它，「运行时切换由设置项通过 config RPC 调用」（见 src/openhuman/voice/always_on.rs 与 src/openhuman/voice/always_on_part_01.rs）。因此该开关的还原不是新造 RPC，而是把 UI 重新挂回既有通道，这也正是文档强调「using the existing voice settings RPC」的原因。

5.2 能力目录：还原 Companion 数据移动披露

第二个产品表面问题是 Companion 的数据移动披露曾在能力目录（capability catalog）中消失。修复要求恢复该披露条目。能力目录在 OpenHuman 中是安全策略的一部分——安全模块的策略命令层直接引用目录条目与 launch_app 相关内容（见 src/openhuman/security/policy/policy_command_part_01.rs），平台目录亦包含语音类能力 id（如 src/openhuman/platform/about_app/catalog_part_03.rs 的 mobile.push_to_talk）。可见「能力 + 数据去向」必须在目录中可被审查；恢复 Companion 披露条目属于合规表面修复，而不是新增运行时行为。

5.3 清理陈旧的 launch-app 目录条目

第三点要求如果 launch-app 目录条目仍残留在当前 HEAD，就删除它。这体现了「恢复行为」与「维持删除」的精确区分：被刻意移除的产品表面（launch-app）不得因修复而复活，这条边界在 Error Handling and Safety 一节被重申为「removed product surfaces stay removed」。

六、第四簇：测试与 E2E 对齐

迁移删除的不只是代码，还有配套测试里引用的旧接口。该簇要求：

1. 替换或删除针对已删除 autocomplete 路由、以及被移除的 WhatsApp 核心 RPC 的测试场景；
2. 若行为仍然随桌面应用交付，就优先走受支持的 Tauri command 路径；
3. 为每一个改变行为的修复补充聚焦的回归测试。

这条原则非常实用：测试套件会忠实地记录所有接口尸体——只要场景还在引用被删路由/RPC，套件就会持续失败或产生误导性的覆盖。与其修补旧接口调用，不如把断言迁移到仍然受支持的新通道（在 Tauri 桌面应用中通常意味着走 Tauri command / JSON-RPC 的正式入口），让测试与产品边界同步收敛。

仓库中的 E2E 基础设施也支持这种「清单化核对」的做法：应用侧存在 openhuman 系列 RPC 测试与 Playwright/WebdriverIO 配置（见 app/src/tests、app/test/vitest.config.ts），设计文档要求的「E2E inventory/script checks for retired scenarios」与这类按场景清单管理的测试资产一一对应。

七、安全不变量：哪些事绝不能再次发生

Error Handling and Safety 一节把这些修复浓缩为四条不变量，值得逐条理解其工程含义：

不变量	含义	对应实现约束
清理幂等	重复的 stop / expiry / cancel 不得 panic，也不得影响更新的会话或 turn	原子状态迁移（Stopped → Idle）+ 版本/代际感知
凭据只发规范源	Companion 会话凭据只送往后端基址	传输目标固定为 OpenHuman 后端源
不复活陈旧快照写回	目标与 board 变更不得再引入整快照覆盖式写入	走 tinyagents 原子通道与 per-board 异步锁
删除边界不变	已移除的产品表面保持移除	launch-app 条目只删不增；修复仅还原仍交付的行为

这四条共同构成评审修复的验收红线：改的是迁移中丢的行为，而不是迁移本身。

八、验证矩阵：从单测到 CI 闭环

每个簇在原子提交前先跑最窄且有意义的测试；最终验证覆盖多级防线：

• Rust：cargo fmt + 针对性核心测试；被触及代码跨越编译期 feature 门时，补跑默认与禁用 feature 两种配置的核心检查；
• Tauri：针对性 Companion 测试 + Tauri 侧 cargo check；
• 前端：针对性测试、typecheck、lint、format；
• E2E：为退役场景做 inventory/脚本核对；
• 收尾：全部本地检查通过后推送分支，轮询 PR checks 与未解决评审线程，直到必需检查全部成功、无可执行反馈残留。

这套矩阵的价值在于「每个修复都有对应的验证锚点」，评审线程无法以「测试过了但没人说得清验证了什么」的方式关闭——它要求证据与被验证的行为一一对应。

九、结语：把「评审反馈」变成可执行的回改协议

PR #5125 修复设计的核心方法论可以沉淀为一条可复用的回改协议：

1. 先核对 HEAD——问题可能已被后续 commit 修掉，此时用证据关线程而非重复改代码；
2. 按簇切割——相关反馈组成小簇，每簇配最窄测试后原子提交，避免巨型补丁再次失控；
3. 修复与删除分线管理——只恢复迁移丢掉的、仍应存在的行为，被精简的删除边界绝不复活；
4. 行为变更必有回归测试——每一次改变运行行为的修复都要有聚焦回归用例，并同步退役指向已删接口的旧场景。

对大型迁移类 PR，这份设计同时提供了代码层与流程层的双重保险：代码层用幂等清理、原子状态迁移、per-board 锁与固定传输源来封住并发与安全缺口；流程层用评审簇 + 原子提交 + HEAD 复核来控制变更本身的复杂度。它可以作为 OpenHuman 后续任何「大 PR 收尾阶段」的参考范式——毕竟，精简的正确标志不是「改动量小」，而是删完之后该有的行为一个不少。