KeySurgeon

什么是KeySurgeon

KeySurgeon 是一个面向 Windows 的终端键盘故障诊断工具，专注于排查键盘连击、双击、死键、间歇键和粘滞键。它不满足于“按键是否注册”这一层，而是观察按键事件与按下时序。浏览器键盘测试器通常只能回答“键有没有反应”，但 chatter 开关可能仍然注册，只是重复注册两次，因此普通测试器容易漏判。KeySurgeon 安装低级 Windows 键盘钩子 WH_KEYBOARD_LL，使用 perf_counter 为每个事件打时间戳，分析按下与释放之间的间隔，以及后续是否出现异常短间隔的重复按下。它会针对已知故障签名打分，给出每个键 0-100 的置信度。

  • 结果定位：不是考试成绩，而是维修决策——HEALTHY 表示测试键看起来正常；WATCH 表示证据可疑但暂不处理；DEGRADING 表示建议清洁或隔离开关；FAILING 表示在更换键盘前先按修复阶梯处理
  • 修复阶梯：从便宜到贵——软件过滤、压缩空气吹尘、清洁触点、热插拔换轴，最后才考虑更换键盘
  • 适用人群：感觉某键偶尔双击、漏按、卡顿，但普通测试器查不出的用户
  • 运行方式：仅支持 Windows 系统，点击下方下载按钮获取安装包即可使用
  • 隐私说明：不保存输入文本，只保留键标签、时序和派生结论

因此它既适合个人排查键盘故障，也适合生成可公开分享的维修记录和问题报告。

KeySurgeon的功能介绍

KeySurgeon 的核心是低层键盘钩子与时序分析。它记录 press/release 事件，检查按键间隔和重复按下，匹配 chatter、dead key、intermittent、sticky 等故障签名。

  • 入口命令：keysurgeon 打开菜单；keysurgeon app 启动 Textual 命令中心；keysurgeon tour 演示命令循环；keysurgeon triage 进入“哪里不对”的引导流程
  • 扫描与监测：keysurgeon sweep 扫描整个键盘并生成健康报告；keysurgeon watch 监测正常打字中的双触发；watch --bg 后台隐藏运行；watch --status 查看后台状态；watch --stop 停止后台
  • 测试与报告：keysurgeon test E R T 测试指定键；keysurgeon report 查看上次结果和趋势；keysurgeon proof 生成本地证明报告；keysurgeon smoke 写硬件冒烟报告脚手架
  • 修复与分享：keysurgeon fix E 给出单键修复阶梯；keysurgeon issue 生成脱敏 GitHub issue 包；keysurgeon export 输出脱敏 Markdown；export --json 输出结构化 JSON
  • 环境与辅助：keysurgeon board 设置或确认键盘类型；keysurgeon doctor 检查支持环境；keysurgeon selftest 做逻辑自检（不需要键盘）；keysurgeon site 输出本地落地页路径
  • 典型输出：例如 CHATTER DETECTED、证据如 re-press 31ms、18 bounces in 240 presses，以及下一步 1 软件过滤、2 吹尘、3 清洁触点、4 热插拔换轴
  • 隐私保护：不存储或导出输入文本，只保留键标签、时序和结论，issue 包也经过脱敏

因此它既适合个人排查键盘故障，也适合生成可公开分享的维修记录和问题报告。

如何使用KeySurgeon

使用 KeySurgeon 可分为安装、自检、测试、解读与分享几个步骤：

  • 安装：点击下方下载按钮获得安装包，解压后运行即可使用
  • 自检：首次使用建议先运行 keysurgeon selftest，确认程序逻辑正常，不需要键盘即可完成自检
  • 进入与学习：运行 keysurgeon 进入菜单，或运行 keysurgeon tour 了解命令循环
  • 测试：怀疑某个键时用 keysurgeon test E R T 测试指定键；想边打字边监测用 keysurgeon watch，希望后台运行用 watch --bg，之后用 watch --status 和 watch --stop 管理；想系统排查用 keysurgeon triage 按引导回答，或用 keysurgeon sweep 走一遍键盘并生成健康报告
  • 解读结果：测试后运行 keysurgeon report 查看上次结果和趋势，按 HEALTHY、WATCH、DEGRADING、FAILING 解读
  • 修复阶梯：若某键被判定异常，用 keysurgeon fix E 获取修复阶梯——先软件过滤，再压缩空气吹尘，再清洁触点，再热插拔换轴，最后才换键盘
  • 分享与记录：需要提交问题时用 keysurgeon issue 写脱敏 issue 包，或用 export 输出 Markdown、export --json 输出 JSON；需要证明报告用 proof，需要本地页面用 site --open，需要硬件冒烟记录用 smoke

整个过程不需要记录私人文本，适合维修记录和公开求助。

KeySurgeon使用的注意事项

使用 KeySurgeon 时，需要注意平台、权限、环境、维修与解读等问题：

  • 平台要求：仅支持 Windows 系统；如果使用 exe，则直接运行即可
  • 权限与安全软件：安装低层键盘钩子，可能被安全软件、杀毒软件或系统权限策略拦截，遇到无法监听时先检查权限和白名单
  • 后台监测：watch 会持续监测键盘，虽然工具不保存输入文本，但键盘钩子本身敏感，公用电脑上应谨慎启用，用完及时执行 watch --stop
  • 排除干扰因素：无线键盘的电池电量、接收器干扰、蓝牙延迟、USB 集线器或 KVM 也可能造成类似连击的时序异常，测试前尽量排除这些因素
  • 硬件维修安全：机械键盘热插拔换轴前必须断电，注意静电和针脚方向；清洁触点应使用合适清洁剂，不要用导电液体，也不要过度用力；压缩空气吹尘要短促、保持距离，避免冷凝
  • 结果解读：软件过滤只能缓解连击，不能真正修复磨损开关；如果结果为 DEGRADING 或 FAILING，应按修复阶梯从低成本到高成本处理；结果应视为维修决策而非绝对诊断，WATCH 不一定故障，HEALTHY 也只代表测试期间正常

资源出处

  • 资源名称KeySurgeon
  • 资源协议MIT
  • 资源版本0.2.1
  • 资源来源