系统架构
ZoneDeck v3 采用 核心 + 配置分离 的双进程架构,两者通过命名管道通信。本章介绍整体设计与工程结构。
双进程总览
┌────────────────────────────────────────────────────────────────┐
│ 用户交互会话(Session 1+) │
│ │
│ ┌──────────────────────────┐ ┌────────────────────────┐ │
│ │ ZoneDeck.exe(常驻) │ │ config.exe │ │
│ │ 纯 Rust 原生,~350KB │◀─IPC──▶│ Tauri(Rust + WebView)│ │
│ │ 隐藏的消息窗口 + wndproc │ 命名 │ 按需打开,关闭即退出 │ │
│ │ │ 管道 │ │ │
│ │ • RegisterHotKey 全局热键 │ │ • 窗口绑定 / 热键录制 │ │
│ │ • WH_MOUSE_LL 鼠标/四角 │ │ • 选项 / 关于 / 检查更新│ │
│ │ • GetLastInputInfo 空闲 │ │ • 管理员重启 / 窗口恢复 │ │
│ │ • 枚举/隐藏/显示窗口 │ └────────────┬───────────┘ │
│ │ • Core Audio 静音 │ │ 读写 │
│ │ • NtSuspend 进程冻结 │ ┌────────────▼───────────┐ │
│ │ • 托盘图标 / 气泡通知 │ │ config.json(数据目录) │
│ │ • 开机自启(计划任务/注册表) │ 核心收到 reload 后热重载 │ │
│ └──────────────────────────┘ └────────────────────────┘ │
│ ▲ 随登录自启 │
└─────────┼────────────────────────────────────────────────────────┘
│ 计划任务(登录触发,最高权限) / 注册表 Run 回退关键设计决策
核心必须运行在用户交互会话
核心不能做成 Session 0 的 Windows 服务,否则无法枚举 / 隐藏用户窗口、无法安装钩子。因此核心以随登录自启的普通程序形式运行在用户会话中。
进程间通信(IPC)
- 使用命名管道
\\.\pipe\zonedeck,一行一条 JSON(Command/Response)。 - 配置保存后,配置界面发送
reload_config,核心热重载并重新注册热键 / 钩子 / 定时器,无需重启核心。 - 协议细节见 IPC 协议。
全部用户态监听,不使用内核驱动
| 能力 | 使用的 API | 说明 |
|---|---|---|
| 全局热键 | RegisterHotKey | 最规范、完善的触发方式 |
| 热键走钩子 | WH_KEYBOARD_LL | 仅在有热键开启「低级键盘钩子」、或用了纯修饰键 / 多主键组合时才安装 |
| 鼠标 / 四角 | WH_MOUSE_LL | 仅在启用鼠标 / 四角时才安装 |
| 空闲检测 | GetLastInputInfo | 无需常驻监听键盘 |
不依赖任何内核驱动,降低误报与安全风险。
权限模型
核心默认 asInvoker,不强制 UAC。仅以下两项需要管理员,通过配置界面的"以管理员身份重启核心"按需提权:
- 增强冻结(
pssuspend64.exe); - 计划任务最高权限自启。
工程结构(Cargo workspace)
ZoneDeck/
├── Cargo.toml workspace(含 release profile 调优)
├── crates/
│ ├── common/ 共享库(无平台依赖,可跨平台编译)
│ │ └── src/{model,config,matching,ipc,i18n,paths}.rs
│ │ model WindowInfo / WindowRule / ProcessRule(serde 兼容旧 config.json,PID 大写)
│ │ config Config/Setting/Hotkey(兼容读取旧配置 + 迁移;保存走 tmp + rename 原子替换)
│ │ matching 窗口匹配逻辑
│ │ paths 数据目录定位(安装版走 %APPDATA%,便携版就地,见下)
│ │ ipc Command/Response 协议 + PipeClient 客户端
│ │ i18n 界面语言标签(Lang)与语言偏好解析,核心与配置程序共用
│ └── core/ 常驻核心(lib + bin)
│ └── src/
│ platform/win32.rs 窗口枚举/隐藏/显示(WindowManager trait)
│ agent.rs 消息循环,聚合热键/托盘/IPC/鼠标/定时器
│ hotkey.rs 热键字符串 → RegisterHotKey 解析
│ hide.rs 隐藏选择逻辑 + HideController(plan/commit 两段式编排,
│ 含死句柄剪枝与恢复前的窗口/进程身份校验)
│ effects.rs Effects trait(静音/冻结/暂停媒体,可注入 mock)
│ effects_worker.rs 副作用专职线程(FIFO 队列;消息循环只做 SW_HIDE)
│ audio.rs Core Audio 会话静音(会话级记账)+ 目标出声判定
│ media.rs SMTC 媒体会话(按应用精确暂停,超时回退全局媒体键)
│ freeze.rs NtSuspend/Resume + pssuspend64 增强冻结
│ input_hooks.rs 输入钩子专职线程(承载两个低级钩子,优先级 above normal)
│ mouse_hook.rs WH_MOUSE_LL(中键/侧键/四角)
│ keyboard_hook.rs WH_KEYBOARD_LL(走钩子的热键:可选吞键、纯修饰键、多主键)
│ idle.rs GetLastInputInfo 空闲 + 自动隐藏判定
│ win_event.rs SetWinEventHook 窗口事件追踪(销毁/显示/改标题 → 实时维护记录)
│ tray.rs Shell_NotifyIcon 托盘 + 气泡
│ ipc_server.rs 命名管道服务端(创建失败退避重试,不退出)
│ autostart.rs 开机自启(计划任务 XML 含失败自动重启 + 注册表回退)
│ elevation.rs 管理员检测 + UAC 提权重启
│ i18n.rs 核心用户可见文案 catalog(托盘菜单 / 气泡 / IPC 错误;日志不走它)
│ logging.rs 分级文件日志(按天切割 + 等级过滤 + 脱敏 + panic 钩子)
│ recovery.rs 崩溃恢复(意图先行落盘 + 原子写;快照带开机时刻与
│ 进程创建时刻,跨重启的快照会被丢弃)
│ stats.rs 能效统计(冻结/效率模式/释放内存的累计量,节流落盘 stats.json)
│ icon.rs 进程图标提取(HICON → 手写 PNG/base64 编码)
│ single_instance.rs 命名互斥单实例
└── apps/config/ 配置界面(Tauri 2 + Svelte 5)
├── src-tauri/ Rust 后端命令 + tauri.conf.json + capabilities
│ └── src/verhub.rs Verhub 客户端(版本/公告/反馈/日志/项目链接,基于 verhub-sdk;
│ 反馈可选转为 GitHub Issue,由 Verhub 机器人创建,此时须填 GitHub 账号;
│ 版本说明 / 公告 / 项目信息按界面语言取译文,缺译文时回落默认内容;
│ 项目链接带缓存:内存 + 数据目录下的 verhub_cache.json,有效期一天,换语言即失效)
│ └── src/analytics.rs 匿名使用统计(启动时报一份功能采用快照 + 设置改动事件,
│ 事件名与属性都有白名单,规则与白名单只报条数;
│ 未获授权前一字节不采不写,授权状态存在 config 的 verhub.analytics)
├── ui/ 前端源码(Vite + Svelte 5)
│ └── src/ lib/(纯逻辑 + vitest 测试)+ components/(Svelte 组件)
│ + locales/(三语文案 catalog,以 zh-CN.js 为基准)
└── dist/ 前端构建产物(gitignore;由 ui/ 经 vite build 生成)common 为什么无平台依赖
crates/common 刻意不依赖 Windows API,因此可以跨平台编译,其纯逻辑(配置解析、匹配、协议)也更易做单元测试。平台相关代码集中在 crates/core。
数据目录
配置 config.json、日志 logs/、恢复文件 recovery.json、统计 stats.json、缓存 verhub_cache.json 共处一个数据目录,由 crates/common/src/paths.rs 定位。安装版与便携版分开对待:
| 情形 | 数据目录 | DataDirKind |
|---|---|---|
| 安装版 | %APPDATA%\ZoneDeck | Installed |
| 便携版,程序目录可写 | 程序目录 | Portable |
| 便携版,程序目录写不进去 | %APPDATA%\ZoneDeck | PortableFallback |
便携版把数据留在程序目录,拷走整个文件夹就带走了全部设置;安装版则不能这么做——安装包可以装进 Program Files,那里普通权限进程不可写,配置程序每次保存都会得到 os error 5。
怎么分辨是哪一种
看程序目录里有没有安装痕迹(paths::is_installed):
- 安装包放的标记文件
installed.marker([Files]里装,卸载时随之移除); - 卸载程序
unins*.exe—— 兜底,标记文件被误删时仍认得出是安装版,不至于把数据写回Program Files。序号随重复安装递增,故按前缀匹配。
判据必须是文件,不能是进程权限
核心可能以管理员身份运行、配置程序不会:核心在 Program Files 下写得进去,配置程序写不进去。若两边各按自己能否写入来选目录,就会各读一份配置,用户改了设置却不生效。看文件则两边必然一致。也因此,安装版根本不做可写性探测——结果一样是用户目录。
回退与迁移
便携版探测到程序目录不可写时退回用户目录,kind 记为 PortableFallback。核心把它写进日志,配置程序通过 data_location 命令读到后弹出提示,说明这是权限问题以及怎么改(见 DataNoticeModal.svelte)。程序功能不受影响。
用到用户目录时,程序目录里的 config.json 会搬过来:先复制,再尽力删掉原文件。目标已有配置就不动它——那是当前在用的一份,旧文件不得覆盖,也不去删。删不掉(没有写权限、文件被占用)就留在原处,反正不会再被读到。
品牌改名(Boss Key → ZoneDeck)留下的旧数据同样自动迁移:每次定位数据目录时,%APPDATA%\BossKey 若还在而 %APPDATA%\ZoneDeck 尚不存在,就整体重命名过去;旧目录被占用重命名失败时退回只复制 config.json 与 recovery.json,残余交给卸载程序或 cleanup.ps1。旧日志前缀 BossKey- 仍被保留天数清理与会话回溯识别(同日期时新前缀排前)。旧名称注册的开机自启(BossKeyAutostart 计划任务、Boss Key Application 注册表值)由核心启动时迁移:先按原权限偏好在新名称下注册成功,再清理旧残留;安装版升级时安装器须先删掉旧看门狗任务才能替换文件,删除前会写一个迁移标记(HKCU\Software\ZoneDeck\MigrateAutostart)供核心首启接力。核心启动前还会探测旧互斥体 BossKey_SingleInstance_Mutex:旧版核心仍在运行时弹窗提示并退出,避免双实例以及从运行中的旧核心脚下搬走数据目录。
配置界面的浏览器数据另有一处
Tauri 按 tauri.conf.json 里的 identifier 把 WebView2 用户数据放在 %LOCALAPPDATA%\cn.hanloth.zonedeck.config,不在数据目录里,也不由 paths.rs 管。安装包的卸载程序与便携版随包的 scripts/cleanup.ps1 都会清理它。
每次启动的实际数据目录与判定结果会写进日志的 [START] 标记,排查读写失败先看它(路径中的用户目录已脱敏为 %USERPROFILE%)。
核心内部:Agent 消息循环
agent.rs 是核心的中枢:它创建一个隐藏的消息窗口并运行 Windows 消息循环,聚合以下事件源:
- 全局热键(
WM_HOTKEY); - 鼠标钩子(中键 / 侧键 / 四角);
- 命名管道服务端(来自配置界面的命令);
- 定时器(空闲检测、状态维护等);
- 窗口事件(
SetWinEventHook:顶层窗口销毁 / 显示 / 改标题); - 托盘图标交互。
消息循环状态由 RefCell 承载:托盘 / 悬浮窗菜单的模态循环(TrackPopupMenu)会重入 wndproc,重入期间的事件借用失败即被安全丢弃,避免出现两个可变引用的别名。IPC 线程创建命名管道失败时按退避(1s → 5s → 30s)重试,不会退出。
低级输入钩子不与消息循环同线程
WH_MOUSE_LL / WH_KEYBOARD_LL 的回调由安装线程的消息泵派发,且系统的输入线程要等钩子链返回才继续投递事件。若与 agent 同线程,枚举窗口、写恢复文件、处理全系统窗口事件这类操作会直接拖慢全局鼠标与键盘输入,单次超过 LowLevelHooksTimeout(默认 300ms)时系统还会丢弃该事件。
故 input_hooks.rs 单起一条只跑消息泵的线程承载这两个钩子,线程优先级提到 above normal,回调里只做纯内存判定与 PostMessageW(鼠标移动这条最热的路径上不加锁,采样存在原子里)。agent 线程通过一个仅消息窗口向它同步下发装卸请求,并据返回值决定是否回退(键盘钩子装不上时,走钩子的热键退化为 RegisterHotKey,RegisterHotKey 表达不了的组合则本次不生效)。
agent 线程本身不提优先级:它干的是枚举 / 冻结 / 落盘这类重活,抬高只会从前台程序手里抢 CPU。
窗口事件驱动隐藏记录的实时维护:被隐藏的窗口自行销毁或被外部恢复显示时,记录即刻移除并落盘;标题变化同步进隐藏记录与精确窗口规则(仅内存,随下次正常落盘写出),使「标题 + 进程路径」的追溯与找回始终基于最新信息。恢复时若句柄已失效,还会按「进程路径 + 标题」在当前不可见窗口中尝试重新找回。
当触发隐藏 / 显示时,交由 HideController 编排,流程为「意图先行」两段式:plan_hide 算出执行计划(剪掉失效记录、补齐 PID)→ 把计划后的快照写入 recovery.json(先落盘再动手,隐藏中途崩溃不丢记录)→ commit_hide 同步隐藏窗口(SW_HIDE),并把静音 / 冻结 / 暂停媒体交给副作用专职线程(effects_worker.rs)按 FIFO 异步执行——消息循环不被慢操作(音频枚举、pssuspend 等待)阻塞,热键与界面保持响应。
队列内的先后有讲究:暂停媒体→静音→静置→冻结。冻结让进程彻底停止响应消息,隐藏若还没在屏幕上画完就冻结,被冻结的窗口会留下残影;暂停命令同样要有时间被目标程序处理掉。故冻结前统一静置一次(FREEZE_SETTLE_DELAY,整批只等一次,没有要冻结的进程就不等)。静音不排在这道等待之后——它走音频会话,与目标进程是否在跑无关。
暂停媒体分两条路径:先经 SMTC(media.rs)逐个会话下发明确的暂停命令,只动被隐藏进程自己的、且确实在播放的会话;匹配不上的目标(没注册 SMTC 会话,或 AUMID 与映像路径对不上)才回退全局媒体键,且仍要先确认这些目标在出声——那个键是播放 / 暂停切换键,目标没在播时发过去反而会把它切成播放。SMTC 的等待是无限阻塞的,故整个调用扔进临时线程限时等待,超时按「一个都没暂停」处理,免得连累队列后面排队的解冻。
恢复(显示)时逐条校验记录的有效性:句柄须仍存在且仍属于当初的进程(IsWindow + PID 比对),冻结 / 效率模式记录须匹配进程创建时刻——句柄与 PID 都会被系统回收复用,校验不过的记录跳过并如实计入日志。
静音是例外,不做存活校验:它波及的是同映像的全部会话,目标进程即使已经退出,同 exe 的其他会话仍得解除,故按记录里的映像路径找回。误伤由 audio.rs 的会话级记账挡着——只有本程序真正从「非静音」改成「静音」的会话才会被解除,用户自己在音量合成器里设的静音原样留着。效率模式同理记下原貌:进程原本就被显式设过 EcoQoS 的,撤销时那份留着不动。恢复时不发任何暂停 / 播放命令,本程序不替用户决定要不要重新播放。
可测试性设计
Effects 被抽象为 trait,测试时可注入 mock,从而在不真正静音 / 冻结系统的情况下验证隐藏编排逻辑。同理 WindowManager 也是 trait。
稳定性设计(崩溃自愈三层防线)
- 崩溃日志:关键事件与 panic 写入数据目录下的
logs/ZoneDeck-YYYY-MM-DD.log(按天切割,按log_retention_days保留,0 表示关闭日志;按log_level过滤,默认只记 WARN 及以上,详见日志分级与脱敏)。 - 崩溃恢复:隐藏动作执行前先把"将要隐藏 / 冻结 / 静音什么"写入
recovery.json(tmp + rename 原子替换)。异常退出后重启走adopt_from:逐条核对句柄、PID、映像名与可见性,对得上的继续保持隐藏(上一轮是核心被终止,用户的隐藏意图没变),对不上的只丢记录并按notifications.on_recovery_mismatch通知用户;一个窗口都没接管成功时才解冻 / 取消静音 / 撤销效率模式。快照带开机时刻与进程创建时刻,跨重启的过期快照直接丢弃。 - 看门狗:计划任务
RestartOnFailure(崩溃后 1 分钟内重启,最多 3 次)。release 构建panic = "abort",panic 钩子写完日志后以非零码退出,正好触发计划任务重启。
用户视角的说明见 窗口恢复与崩溃自愈。
日志分级与脱敏
crates/core/src/logging.rs 提供 debug / info / warn / error 四级与两条会话标记,写入前统一脱敏。用户在配置界面选择的 log_level 是记录门槛:低于它的日志直接丢弃,默认 warn 即只留警告与错误。等级在 reload_config 时即时生效,无需重启核心。
新增日志时按下表归类:
| 级别 | 收什么 | 例子 |
|---|---|---|
error | 功能已不可用或数据有丢失风险,用户需要知道 | 代理窗口创建失败、配置解析失败回退默认、恢复文件写入失败 |
warn | 降级但仍能用,或出现了用户会察觉的异常 | 热键注册失败、钩子安装失败、规则未匹配到窗口、检测到上次异常退出 |
info | 每次运行至多一两条的里程碑 | 更新后首次启动并拉起配置程序 |
debug | 逐次动作的流水与自愈过程,仅排查时才需要 | 每次隐藏 / 恢复的明细、热键注册成功、托盘图标补挂 |
两条会话标记不受等级过滤,每次运行各一条:[START] 记录版本、配置 schema、生效等级与数据目录,[EXIT] 记录正常退出及其来由(关闭热键 / 托盘菜单 / 配置程序下发 / 冒烟计时)。日志末尾没有 [EXIT] 即上次是崩溃或被强杀;只有 [START] 能让一段上传上来的日志说清楚它出自哪个版本。
隐藏与恢复的记录带上触发来源(Trigger:热键、鼠标按键、四角、空闲、托盘、悬浮窗、配置程序)。用户反馈「窗口莫名其妙被隐藏」时,第一步就是分清是谁触发的。
上报只取本次运行
logging::latest_session 从最近一个 [START] 起截到当前,跨零点时向前回溯一个日志文件;配置程序的 current_session_log 命令即取这一段。不按固定末尾若干行取,是因为那样既会混进上几次运行的内容,又会漏掉本次运行开头的版本与数据目录。超出上报预算([verhub::LOG_EXCERPT_MAX])时保留首行与末尾,中间注明省略了多少行——首行是版本信息,末尾是出错现场,两头都不能丢。
日志可能被用户上传
配置界面的反馈功能会把日志发往 Verhub,因此日志里不得出现窗口标题(可能是文件名、聊天对象、网页标题),窗口一律以「进程名 + 句柄 + PID」指代,窗口规则以「序号 + 进程名」指代。用户目录由 logging.rs 统一替换为 %USERPROFILE%,无须各调用点自行处理。
error 信息
- 对象:出问题的路径、PID、热键、管道名等,路径直接
display()(脱敏由日志层负责)。 - 原因:系统 API 用
util::win_err(消息 + 十六进制错误码),IO 与子进程错误直接带{e}。 - 后果:哪个功能因此不可用、数据是否可能丢失,而不是只说「失败」。
- 位置:用
log_error!/log_warn!宏,自动附上文件:行号。
例:重新加载配置失败,本次改动未生效,核心仍在用上一次加载的配置: <路径> — <原因> (agent.rs:123)。
界面语言
核心与配置程序共用 crates/common 的 Lang(zh-CN / en / zh-TW)与语言偏好解析,文案则各自维护:
| 位置 | 文案载体 | 说明 |
|---|---|---|
crates/core/src/i18n.rs | Msg 枚举 + 三语 match | 托盘菜单、气泡通知、IPC 错误;tf() 负责 {名字} 占位符替换 |
apps/config/ui/src/locales/*.js | 扁平键值表 | 配置界面全部文案;t(key, params) 查表并替换占位符 |
- 生效语言由
setting.language决定:auto时按系统显示语言推断(核心用GetUserDefaultLocaleName,前端用navigator.language),推断不出回落到简体中文。 - 配置界面保存配置后会发
reload_config,核心据此同步语言,因此切换语言无需重启任一进程。 - 日志不参与 i18n,一律使用简体中文,以便跨语言排查问题。
NO_TITLE("无标题窗口")是跨进程、写进config.json的哨兵值,不随语言变化,仅在展示时翻译。
前端架构
配置界面前端使用 Svelte 5 + Vite,采用无边框自绘窗口、亮暗主题、配置自动保存等设计。详见 前端与配置界面。