wsclx/ak820pro-modder

## 为什么需要这个项目 官方的 Epomaker / Ajazz 驱动程序仅支持 Windows 且功能有限。macOS 用户什么也得不到 —— 没有灯光调节，没有按键重映射，没有宏，没有 TFT 自定义。这个项目改变了这一点，通过逆向工程对抗官方在线驱动的有线协议，并在一个干净、原生、可编写脚本的堆栈中重新实现了完整的功能集。 | | 官方 AJAZZ 工具 | **AK820 Pro Modder** | |---|---|---| | macOS 支持 | ❌ 仅限 Windows | ✅ 原生，签名构建目标 | | CLI / 脚本 | ❌ | ✅ `ak820` 无头二进制文件 | | 透明协议 | ❌ 封闭 | ✅ [`docs/PROTOCOL.md`](docs/PROTOCOL.md) —— 记录了每一个字节 | | 20 种灯光模式 | ✅ | ✅ | | 单键 RGB | ✅ | ✅ 点击绘制表面 | | 键盘映射重映射 | ✅ | ✅ 基础层 + Fn 层 + 恢复出厂设置 | | 宏录制器 | ✅ | ✅ 应用内实时捕获 | | TFT 图片上传 | ✅ | 🚧 有线格式已解码，可见性验证正在进行中 | | **AppleScript / 快捷指令 库** | ❌ | ✅ 带有 15 个入门示例的主机端运行器 | | **键盘触发的自动化** | ❌ | ✅ 通过 F13–F24 标记将 AppleScript 绑定到物理按键 | | **正在播放 阅读器（音乐 + Spotify）** | ❌ | ✅ 在系统视图中实时显示 | | **全方位预设** | ❌ | ✅ 10 个精选配置文件（游戏 / 开发 / 办公 / 创作 / 生活方式） | | 音频响应灯光 | ❌ | 🛣 计划中 | | TFT 上的正在播放 | ❌ | 🛣 计划中 | | 跨机器配置文件同步 | ❌ | 🛣 计划中 | | 开源 | ❌ | ✅ MIT | ## 状态 **版本 0.5.0-beta。** 灯光（包括单键绘制表面）、按键映射（带有恢复出厂设置）、宏、系统信息以及主机端自动化引擎 —— 包括精选的 15 个入门库和一键全方位预设 —— 均已在运行固件 1.07（**ISO-DE** 德国 QWERTZ 布局）的 AK820 Pro 上通过硬件验证。TFT 上传已完成协议对接并提供 CLI 冒烟测试；应用内 TFT UI 受阻于最后一个逆向工程步骤。有关详细信息，请参阅 [Roadmap](#roadmap) 部分。 ## 快速开始 ### 安装 (macOS, 暂时从源代码构建) ``` # 前置条件: Rust 1.82+, Node.js 20+, pnpm git clone https://github.com/wsclx/ak820pro-modder.git cd ak820pro-modder pnpm install pnpm tauri:build open src-tauri/target/release/bundle/dmg/*.dmg ``` 将 **AK820 Pro Modder.app** 拖入“应用程序”并启动。 一旦代码签名管道连接好，签名的 `.dmg` 发布版将会出现在 [Releases](https://github.com/wsclx/ak820pro-modder/releases) 页面上。 ### CLI 使用 ``` cargo build -p ak820-cli --release ./target/release/ak820 list # enumerate every HID interface ./target/release/ak820 probe # open control endpoint, sanity check ./target/release/ak820 info # firmware + battery + profile ./target/release/ak820 lighting set --mode static --color FF00AA ./target/release/ak820 rgb fill --color 00FF80 # per-key static colour ./target/release/ak820 rgb rainbow # 128-LED rainbow gradient ./target/release/ak820 macros list # dump every stored macro ./target/release/ak820 hid-descriptors # debug: report sizes per interface ``` 完整的 CLI 帮助是 `ak820 --help`。 ## 功能 ### 灯光 - 官方驱动程序中的所有 20 种效果模式（静态、呼吸、光谱、涟漪、流光 等） - 带有 HSL 预览的 RGB 选择器 - 支持该模式的模式的 双色调辅助颜色 - 亮度 + 速度 0–5 - 方向（左 / 右 / 上 / 下），在模式支持的情况下 - 实时应用并带有防抖；可切换到手动模式进行慢反馈调整 ### 键盘映射与层 - 可视化 ISO-DE 键盘表面，可通过窗口拖动调整大小（CSS `transform: scale()` 实现像素级完美的重新渲染） - 点击任意按键 → 选择新动作 → 保存会自动写入基础层和 Fn 层 - 128 个插槽，覆盖每种击键类型：HID 键盘、消费者（媒体）、鼠标、层切换、宏触发、未知类的原始透传 - 在 macOS 模式下重新映射 F 行按键时会弹出抬头警告（固件会通过物理 Mac/Win 切换键抢占这些按键作为媒体键） ### 宏 - 直接在应用中录制宏 —— 每个浏览器的 `keydown` / `keyup` 都会变成带有毫秒级延迟的连线事件 - 最多 100 个插槽 × 320 字节（每个宏约 79 个动作） - 两阶段原子提交，因此部分写入不会使键盘处于奇怪的状态 - 可从按键映射选择器中的 **Macros** 动作组分配给任意按键 ### 系统 - 固件版本 + 电池电量 + 充电状态 + 活跃的配置文件插槽 - 睡眠定时器预设（从不 / 1m / 5m / 10m / 15m / 30m） - 每次写入后实时读取设备信息，以确认键盘确实接受了我们发送的内容 - **正在播放 卡片** (macOS)：实时读取 Music.app + Spotify 桌面版，每 2 秒刷新一次。这是在解锁激活序列后将曲目流式传输到 TFT 显示器的基础。 ### 单键 RGB - 反映 ISO-DE 键盘布局的点击绘制表面 - 调色板 + 全部填充 / 全部清除 助手 - 带有 120 ms 防抖的自动应用，使绘制在硬件上感觉像实时的 - 隐藏在灯光视图的 `custom` 效果模式下（`SET_LED_EFFECT` 模式字节为 `0x80`） ### 自动化 - 主机端的 AppleScript、macOS Shortcuts 和 shell 命令库 - 开箱即用的 **15 个精选入门示例**，横跨六个类别（系统、文件、剪贴板、媒体、网页、开发）—— 无需 sudo，无外部依赖，全部安全 - 每个条目的编辑器带有类型感知的有效负载（AppleScript / shell 对应文本区域，已安装的 Shortcuts 对应选择器） - 内联运行 + stdout/stderr/退出代码 面板 - 持久化到 `~/Library/Application Support/io.github.wsclx.ak820pro-modder/automations.json` - **将任何自动化绑定到物理按键**：在按键映射视图中，从 `Automations` 动作组中选择 → 后端自动分配一个 F13–F24 标记 → 通过 Carbon `RegisterEventHotKey` 注册全局热键 → 按键触发脚本（最多 12 个同时绑定，无需辅助功能权限） ### 预设 - 捆绑了灯光 + 稀疏按键映射覆盖 + 自动化种子的全方位配置文件 - 横跨 5 个类别的 **10 个入门预设**：游戏（FPS · MMO）、开发（Linux 终端 · 氛围编码者 · 白帽子）、办公（MS365）、创作（音乐制作 · 写作专注）、生活方式（流媒体 · 旅行省电） - **叠加应用** —— 修补你当前的状态，不会清除任何内容。用户可以选择每个预设的每个组件（灯光 / 基础按键映射 / Fn 按键映射 / 自动化）。 - 显示具体更改内容的内联应用后报告 ### 接下来 有关工程轨迹，请参阅 [Roadmap](#roadmap) 部分和 [`docs/HANDOFF.md`](docs/HANDOFF.md) 文件。 ## 架构 ``` ak820pro-modder/ ├── crates/ │ ├── ak820-protocol/ Pure-Rust library — HID framing, command encoders/decoders │ │ └── src/commands/ One module per feature family (lighting, keymap, macros, …) │ └── ak820-cli/ `ak820` headless binary (scripting + RE / smoke tests) ├── src-tauri/ Tauri 2 shell — async commands marshal between UI and protocol crate ├── src/ React 19 + TypeScript + Tailwind 3 frontend │ ├── views/ One file per top-level tab (Connect, Lighting, Keymap, Macros, …) │ ├── components/ Shared UI primitives (Card, Button, Slider, …) │ └── data/ Static layout descriptors + curated action catalogues ├── docs/ │ ├── PROTOCOL.md Living byte-level wire documentation │ ├── ARCHITECTURE.md High-level design + tech stack rationale │ ├── HANDOFF.md Engineering handoff: foot-guns, decisions, debug trail │ └── reverse-engineering/ Scraped vendor bundles + USB pcap captures (gitignored) └── tests/ Hardware-in-the-loop fixtures (gitignored) ``` [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 解释了为什么选择 Tauri + Rust 而不是 Electron / PyQt / WebHID。 ## 硬件参考 | 组件 | 部件 | 备注 | |---|---|---| | 主 MCU | HFD80CP100 (Sonix SN32F299 clone) | 6 × 15 按键矩阵 | | 无线 | WCH CH582F | BLE 5.1 + 2.4 GHz，通过 I²C 连接到 MCU | | 闪存 | PY25Q128HA | 16 MB SPI —— 固件 + 配置 + GIF 帧 | | 显示器 | NFP085B-10AF, 0.85″ 128 × 128 | GC9107 控制器, SPI | | 引导加载程序 | 空格键下方的隐藏引脚 | ISP 模式 VID/PID `0x0C45 / 0x7140` | | 运行 VID/PID | `0x0C45 / 0x8009`（有线 + 2.4 GHz） | 蓝牙为 `0xFEFE`，控制在 HID 接口 2（`usage_page 0xFF68`） | | **测试过的布局** | **ISO-DE**（德国 QWERTZ） | 有线协议与布局无关；只有按键映射视图中渲染的键盘表面是特定于布局的。AK820 Pro 存在 ANSI / ISO-FR / ISO-ES / ISO-UK / JIS 变体，并已列入多布局路线图。 | 感谢 [fpb/ajazz-ak820-pro](https://github.com/fpb/ajazz-ak820-pro) 硬件文档项目提供的早期 MCU / 无线 / 闪存识别 —— 请参阅 [致谢](#acknowledgements)。 ## 路线图 | 阶段 | 状态 | 描述 | |---|---|---| | 0 — 基础 | ✅ | Tauri shell，工作区，HID 传输，探测握手 | | 1 — 灯光 | ✅ | 20 种模式 + 辅助颜色 + 亮度 / 速度 / 方向 | | 2 — 系统 | ✅ | 设备信息，电池，睡眠定时器，配置文件，游戏模式 | | 3 — 按键映射 | ✅ | 基础层 + Fn 层编辑器，可视化 ISO-DE 表面，128 插槽往返，恢复出厂设置 | | 4 — 宏 | ✅ | 录制器，编辑器，ActionCatalog 集成，硬件验证 | | 5a — 单键 RGB | ✅ | 协议 + CLI + 灯光视图中的点击绘制 UI | | 5b — TFT 显示器 | 🟡 | 协议 + CLI 上传在连线层面已验证；可见性翻转等待官方 Windows 工具的 USB 抓包 | | 6a — 正在播放 阅读器 | ✅ | macOS Music.app + Spotify 桌面版，在系统视图中展示 | | 6b — 自动化引擎 | ✅ | AppleScript / 快捷指令 / Shell 库，15 个精选入门，通过 F13–F24 标记实现键盘端触发 | | 6c — 全方位预设 | ✅ | 10 个横跨游戏 / 开发 / 办公 / 创作 / 生活方式的精选配置文件 | | 6d — 音频响应灯光 | 🛣 | ScreenCaptureKit 系统音频分接 + FFT → 色彩映射 | | 6e — TFT 上的正在播放 | 🛣 | 取决于阶段 5b —— 将正在播放阅读器的快照流式传输到键盘的显示器 | | 6f — iCloud 配置同步 | 🛣 | Plist + 宏 + 自动化通过 `~/Library/Mobile Documents` 往返，以便多台 Mac 共享一个配置 | | 7 — 跨平台 | 🛣 | 通过 GitHub Actions 进行 Windows + Linux 构建 | | 8 — 多布局 | 🛣 | ANSI, ISO-FR, ISO-ES, ISO-UK, JIS 变体。在 `src/data/layouts/` 下干净隔离并带有布局选择器 UI。有线协议已适用于所有变体；这纯粹是关于屏幕上的键盘表面。 | ## 安全 硬件控制表面本质上是具有风险的。请阅读 [`SECURITY.md`](SECURITY.md) 以了解我们的披露政策和救援程序（ISP 引导加载程序，通过 HID 出厂重置）。 ## 致谢 - [@gohv](https://github.com/gohv) — [EPOMAKER-Ajazz-AK820-Pro](https://github.com/gohv/EPOMAKER-Ajazz-AK820-Pro) 提供了最初的 Linux Rust 移植。启发了这个项目的架构；它的灯光发现在 macOS 上是错误的（官方在线驱动使用不同的有线格式），但其编码器骨架是一个有用的起点。 - [@TaxMachinehttps://github.com/TaxMachine) — [ajazz-keyboard-software-linux](https://github.com/TaxMachine/ajazz-keyboard-software-linux) 提供了 C++ pcap-parser 方法并持续进行协议逆向工程。 - [@fpb](https://github.com/fpb) — [ajazz-ak820-pro](https://github.com/fpb/ajazz-ak820-pro) 提供了硬件识别（MCU、无线芯片、闪存、显示器）。 - [SonixQMK](https://github.com/SonixQMK) 项目 —— 为 SN32F299 系列保留了通向最终 QMK 固件支持的路径。 ## 许可证 [MIT](LICENSE) © wsclx _{v0.5.0-beta · 为 macOS 机械键盘社区用 ❤️ 打造 · 在 [github.com/wsclx/ak820pro-modder](https://github.com/wsclx/ak820pro-modder) 开放问题 / PR}

标签：Ajazz, AK820 Pro, Applescript, Epomaker, macOS原生应用, RGB灯效控制, Rust, Tauri 2, TFT屏幕, USB通信, 云资产清单, 可视化界面, 外设驱动, 宏录制, 开源硬件, 数字取证, 机械键盘, 桌面工具, 硬件协议分析, 程序员极客, 系统快捷指令, 网络流量审计, 自动化脚本, 跨平台替代, 逆向工程, 通知系统, 键位映射, 键盘客制化