tommybobb/crabdeck

# crabdeck [](https://github.com/tommybobb/crabdeck/actions/workflows/test.yml) [](https://github.com/tommybobb/crabdeck/releases) [](LICENSE) 将 Ajazz/Mirabox/Mars-Gaming AKP03 系列 stream deck 上的 LCD 按键转换为 Claude Code 使用情况的实时显示——包括 5 小时会话百分比、每周百分比、实时 会话数、运行中的 subagent 以及消耗速率 ETA。  该项目最初是一个单一设备的逆向工程计划（完整的协议分析请参阅 `docs/NOTES.md`），后来扩展到了下方的整个设备系列，因为它们在不同的 USB ID 下 共享同一套命令词汇表。 **仅限 Windows。** 使用 `ctypes.windll` 进行前台窗口检测并 使用 `.bat` 启动脚本；目前没有 Mac/Linux 移植版本 （欢迎提交 PR——HID 协议层本身，即 `deck.py`/`devices.py`，并不是 Windows 专属的）。 ## 环境要求 - Windows 10/11 - Python 3.9+ - 已安装 [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) 并 配置在 `PATH` 中（crabdeck 会通过 shell 调用 `claude -p /usage`） - 下方列出的[支持的设备](#supported-devices)之一 ## 隐私 crabdeck 会读取 Claude Code 的本地会话文件（`~/.claude/sessions/*.json`） 和记录（`~/.claude/projects/**/*.jsonl`），以驱动 LIVE/AGENTS 磁贴。它仅提取会话状态和工具调用 ID——绝不包含消息 内容——且仅从你本人机器上已有的文件中读取。除了那一次 `claude -p /usage` 调用本身之外，不会向任何地方发送任何内容，该调用会与你 已配置的 Claude 账户进行通信，就像在正常会话中运行 `/usage` 一样。 ## 安装 ``` git clone https://github.com/tommybobb/crabdeck.git cd crabdeck pip install -r requirements.txt ``` 然后运行 `start.bat`。首次运行会自动检测你的设备并将其保存到 `config.json`；后续运行将直接使用该配置。如果插入了多个受支持的设备， 它会询问你选择哪一个。（如果你在此 文件夹中安装了 `.venv`，`start.bat` 会自动使用它；否则它将回退到 `PATH` 中的 `python`。） ## 支持的设备 9 个按键（6 个带有 LCD 显示屏）+ 3 个旋钮，60x60 JPEG 磁贴： | VID:PID | 名称 | 状态 | |---|---|---| | `0B00:1001` | Mars Gaming MSD-TWO | 已在硬件上验证 | | `0300:1001` | Ajazz AKP03 | 未测试 | | `0300:1002` | Ajazz AKP03E | 未测试 | | `0300:1003` | Ajazz AKP03R | 未测试 | | `0300:3002` | Ajazz AKP03E (rev. 2) | 未测试 | | `0300:3003` | Ajazz AKP03R (rev. 2) | 未测试 | | `6602:1002` | Mirabox N3 | 未测试 | | `6603:1002` | Mirabox N3CN (rev. 3) | 未测试 | | `6603:1003` | Mirabox N3EN | 未测试 | | `1500:3001` | Soomfon Stream Controller SE | 未测试 | | `5548:1001` | TreasLin N3 | 未测试 | | `0200:2000` | Redragon Skyrider SS-551 | 未测试 | “未测试”表示 USB ID 和协议版本来源于上游 （参见鸣谢），但尚无人使用此代码在该确切设备上进行过验证。 如果你拥有该设备并且它能够工作（或不能工作），请提交 issue/PR——我们有 专门针对此情况的 issue 模板。 **不支持**：18 键/0 旋钮的 AKP153 系列（例如 Mars Gaming MSD-ONE）—— 其几何结构和数据包布局完全不同，需要建立自己的设备 表。欢迎提交 PR。 ### 添加设备 如果你的 deck 未被列出，但共享了 `CRT`/`BAT`/`STP`/`CLE`/`LIG` 命令 词汇表，请在 `devices.py` 的 `DEVICES` 中添加一行： ``` (0xVVVV, 0xPPPP): ("Your Device Name", protocol_version, False), ``` 对于旧版固件（1024 字节数据包，无旋转），`protocol_version` 为 2； 对于较新的固件（1024 字节数据包，图像顺时针旋转 90°），则为 3——以 `0x3` 开头的 PID 通常是 pv3。在信任它之前，请运行 `tools/probe_input.py` 并确认打印出的输入代码与 `deck.INPUT_CODES` 匹配。 ## 独立使用协议层 `deck.py` + `devices.py` 不依赖于 Claude 用量相关的代码： ``` import deck dev = deck.open() # auto-detect/config/prompt, opens interface 0 dev.send_image(1, jpeg_bytes) # jpeg_bytes sized/rotated for dev.profile dev.clear_key(1) dev.close() ``` ## 开发 `tests/test_devices.py` 是唯一不需要硬件的测试（使用 `pytest`，或者 直接运行 `python tests/test_devices.py`）。`claude_state.py` 和 `usage.py` 在 `if __name__ == "__main__":` 下也有内置的自检功能。 `tools/` 包含手动硬件探测脚本（`probe_input.py`、`probe_size.py`、 `probe_orient.py`、`probe_clear_key.py`、`probe_clear_all.py`）——这些脚本会向 真实连接的设备写入数据，且不会被 CI 运行。 ## 更多细节 `docs/NOTES.md` 包含了完整的逆向工程日志：USB 捕获方法、 固件特性、供应商应用程序的场景切换行为，以及过程中犯过的错误。

标签：Claude Code, Python, 安全规则引擎, 无后门, 桌面外设, 状态监控, 硬件控制, 逆向工具