Skip to content

系统架构 ​

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%\ZoneDeckInstalled
便携版,程序目录可写程序目录Portable
便携版,程序目录写不进去%APPDATA%\ZoneDeckPortableFallback

便携版把数据留在程序目录,拷走整个文件夹就带走了全部设置;安装版则不能这么做——安装包可以装进 Program Files,那里普通权限进程不可写,配置程序每次保存都会得到 os error 5。

怎么分辨是哪一种 ​

看程序目录里有没有安装痕迹(paths::is_installed):

  1. 安装包放的标记文件 installed.marker([Files] 里装,卸载时随之移除);
  2. 卸载程序 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。

稳定性设计(崩溃自愈三层防线) ​

  1. 崩溃日志:关键事件与 panic 写入数据目录下的 logs/ZoneDeck-YYYY-MM-DD.log(按天切割,按 log_retention_days 保留,0 表示关闭日志;按 log_level 过滤,默认只记 WARN 及以上,详见日志分级与脱敏)。
  2. 崩溃恢复:隐藏动作执行前先把"将要隐藏 / 冻结 / 静音什么"写入 recovery.json(tmp + rename 原子替换)。异常退出后重启走 adopt_from:逐条核对句柄、PID、映像名与可见性,对得上的继续保持隐藏(上一轮是核心被终止,用户的隐藏意图没变),对不上的只丢记录并按 notifications.on_recovery_mismatch 通知用户;一个窗口都没接管成功时才解冻 / 取消静音 / 撤销效率模式。快照带开机时刻与进程创建时刻,跨重启的过期快照直接丢弃。
  3. 看门狗:计划任务 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.rsMsg 枚举 + 三语 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,采用无边框自绘窗口、亮暗主题、配置自动保存等设计。详见 前端与配置界面。