AhakeyAI · ShawnyinsGit · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026
diff --git a/.gitignore b/.gitignore
@@ -64,6 +64,7 @@ logs/
 **/config_client.json
 **/settings.json.bak.*
 **/hooks.json.bak.*
+scripts/build.local.env
 
 # Local backups / temp
 *.bak
@@ -72,3 +73,19 @@ logs/
 # Local model / runtime payloads
 internal/
 .gstack/
+
+# Java / Maven build output
+target/
+*.class
+
+# Swift build artifacts
+.build/
+.swiftpm/
+DerivedData/
+*.xcuserstate
+
+# Packaged outputs
+dist/
+
+# Local env (signing creds etc.)
+scripts/build.local.env
diff --git a/.idea/.gitignore b/.idea/.gitignore
diff --git a/...cp_bridge_for_vibe_code-master/App.config → BLE_tcp_bridge/App.config b/...cp_bridge_for_vibe_code-master/App.config → BLE_tcp_bridge/App.config
diff --git a/..._bridge_for_vibe_code-master/AppConfig.cs → BLE_tcp_bridge/AppConfig.cs b/..._bridge_for_vibe_code-master/AppConfig.cs → BLE_tcp_bridge/AppConfig.cs
diff --git a/...or_vibe_code-master/BLE_tcp_driver.csproj → BLE_tcp_bridge/BLE_tcp_driver.csproj b/...or_vibe_code-master/BLE_tcp_driver.csproj → BLE_tcp_bridge/BLE_tcp_driver.csproj
diff --git a/...e_for_vibe_code-master/BLE_tcp_driver.sln → BLE_tcp_bridge/BLE_tcp_driver.sln b/...e_for_vibe_code-master/BLE_tcp_driver.sln → BLE_tcp_bridge/BLE_tcp_driver.sln
diff --git a/...ge_for_vibe_code-master/Form1.Designer.cs → BLE_tcp_bridge/Form1.Designer.cs b/...ge_for_vibe_code-master/Form1.Designer.cs → BLE_tcp_bridge/Form1.Designer.cs
diff --git a/..._tcp_bridge_for_vibe_code-master/Form1.cs → BLE_tcp_bridge/Form1.cs b/..._tcp_bridge_for_vibe_code-master/Form1.cs → BLE_tcp_bridge/Form1.cs
diff --git a/...cp_bridge_for_vibe_code-master/Form1.resx → BLE_tcp_bridge/Form1.resx b/...cp_bridge_for_vibe_code-master/Form1.resx → BLE_tcp_bridge/Form1.resx
diff --git a/...cp_bridge_for_vibe_code-master/Program.cs → BLE_tcp_bridge/Program.cs b/...cp_bridge_for_vibe_code-master/Program.cs → BLE_tcp_bridge/Program.cs
diff --git a/...be_code-master/Properties/AssemblyInfo.cs → BLE_tcp_bridge/Properties/AssemblyInfo.cs b/...be_code-master/Properties/AssemblyInfo.cs → BLE_tcp_bridge/Properties/AssemblyInfo.cs
diff --git a/...e-master/Properties/Resources.Designer.cs → ...p_bridge/Properties/Resources.Designer.cs b/...e-master/Properties/Resources.Designer.cs → ...p_bridge/Properties/Resources.Designer.cs
diff --git a/...ibe_code-master/Properties/Resources.resx → BLE_tcp_bridge/Properties/Resources.resx b/...ibe_code-master/Properties/Resources.resx → BLE_tcp_bridge/Properties/Resources.resx
diff --git a/...de-master/Properties/Settings.Designer.cs → ...cp_bridge/Properties/Settings.Designer.cs b/...de-master/Properties/Settings.Designer.cs → ...cp_bridge/Properties/Settings.Designer.cs
diff --git a/..._code-master/Properties/Settings.settings → BLE_tcp_bridge/Properties/Settings.settings b/..._code-master/Properties/Settings.settings → BLE_tcp_bridge/Properties/Settings.settings
diff --git a/...p_bridge_for_vibe_code-master/Protocol.cs → BLE_tcp_bridge/Protocol.cs b/...p_bridge_for_vibe_code-master/Protocol.cs → BLE_tcp_bridge/Protocol.cs
diff --git a/..._bridge_for_vibe_code-master/TcpServer.cs → BLE_tcp_bridge/TcpServer.cs b/..._bridge_for_vibe_code-master/TcpServer.cs → BLE_tcp_bridge/TcpServer.cs
diff --git a/...tcp_bridge_for_vibe_code-master/readme.md → BLE_tcp_bridge/readme.md b/...tcp_bridge_for_vibe_code-master/readme.md → BLE_tcp_bridge/readme.md
diff --git a/platforms/macos/Makefile → Makefile b/platforms/macos/Makefile → Makefile
diff --git a/platforms/macos/Package.swift → Package.swift b/platforms/macos/Package.swift → Package.swift
diff --git a/...ing/AhaKeyConfig-EmbeddedInfo-Debug.plist → ...ing/AhaKeyConfig-EmbeddedInfo-Debug.plist b/...ing/AhaKeyConfig-EmbeddedInfo-Debug.plist → ...ing/AhaKeyConfig-EmbeddedInfo-Debug.plist
diff --git a/...Packaging/AhaKeyConfig-EmbeddedInfo.plist → Packaging/AhaKeyConfig-EmbeddedInfo.plist b/...Packaging/AhaKeyConfig-EmbeddedInfo.plist → Packaging/AhaKeyConfig-EmbeddedInfo.plist
diff --git a/README-sharing.md b/README-sharing.md
@@ -0,0 +1,169 @@
+# AhaKeyConfig — AhaKey-X1 原生 macOS 配置工具
+
+## 项目简介
+
+这是一个用 Swift + SwiftUI 写的 macOS 原生应用，直接通过 CoreBluetooth 连接 AhaKey-X1（Vibecoding Keyboard），**不需要 TCP 桥接层**。
+
+原厂工具的架构是 Python (PySide6) → .NET TCP Bridge → Swift BLE Helper，三层转接。这个项目把整个链路压缩成一个 Swift 应用，直连 BLE。
+
+### 功能
+
+- BLE 自动扫描/连接/重连 AhaKey-X1 设备
+- 设备状态查询（电量、固件版本、工作模式、灯光、拨杆）
+- 4 键 × 3 模式的键位映射（快捷键 + LCD 描述文字）
+- IDE 状态同步 → LED 变色（Claude Code hooks 集成）
+- LCD 图片/GIF 管理界面（协议已实现，上传功能 TODO）
+- 后台守护进程维持 BLE 连接（LaunchAgent）
+
+### 协议实现完整度
+
+BLE 协议已从原厂工具反编译完整还原，包括：
+- 帧格式（AA BB ... CC DD）
+- 全部 DeviceCmd（0x00-0x90）
+- 按键配置（快捷键/宏/描述 三种子类型）
+- 大数据写入流程（ LCD 图片）
+- IDE 状态同步（0x90）
+
+详见 `docs/ble-protocol.md`。
+
+---
+
+## 构建说明
+
+### 环境要求
+
+- macOS 15.0+
+- Xcode 15+（或等效 Swift toolchain）
+- Swift 5.9+
+- Apple Silicon（arm64）
+
+### 编译
+
+```bash
+# 仅编译
+swift build -c release --arch arm64 --product AhaKeyConfig
+
+# 编译 + 打包 .app bundle（含图标生成、代码签名）
+bash scripts/build.sh
+
+# 编译 + 安装到 /Applications
+INSTALL_TO_APPLICATIONS=1 bash scripts/build.sh
+
+# 编译 + 安装 + 启动
+INSTALL_TO_APPLICATIONS=1 LAUNCH_AFTER_INSTALL=1 bash scripts/build.sh
+```
+
+也可以用 Makefile：
+
+```bash
+make build    # 等同 bash scripts/build.sh
+make install  # 等同 INSTALL_TO_APPLICATIONS=1 LAUNCH_AFTER_INSTALL=1 bash scripts/build.sh
+```
+
+### 代码签名
+
+`scripts/build.sh` 会自动查找本机的 Developer ID Application 或 Apple Development 证书。如需指定：
+
+```bash
+SIGNING_IDENTITY="你的签名身份" bash scripts/build.sh
+```
+
+**重要**：当前 bundle ID 是 `lab.jawa.ahakeyconfig`，你们需要改成自己的（搜索替换即可，出现在 `Package.swift` 的 product name 不需要改，主要改 `scripts/build.sh` 里的 `APP_IDENTIFIER` 和源码里的 Logger subsystem）。
+
+### 蓝牙权限
+
+App 需要 Bluetooth entitlement 才能使用 CoreBluetooth：
+
+```xml
+<key>com.apple.security.device.bluetooth</key>
+<true/>
+```
+
+`scripts/build.sh` 会自动生成 entitlements 文件并签名。如果用 Xcode 打开项目，需要在 Signing & Capabilities 里手动添加 Bluetooth。
+
+---
+
+## 项目结构
+
+```
+ahakeyconfig/
+├── Package.swift                          # SPM 包定义，两个 target
+├── Makefile                               # 快捷构建命令
+├── scripts/
+│   ├── build.sh                           # 完整构建脚本（编译+打包+签名+安装）
+│   ├── ahakey-state.sh                    # Claude hooks 用的 LED 状态同步脚本
+│   └── generate_icons.swift               # 程序化生成 app icon
+├── Sources/
+│   ├── AhaKeyConfigApp.swift              # App 入口，单实例控制
+│   ├── BLE/
+│   │   ├── AhaKeyProtocol.swift           # ★ 协议编解码（帧格式、命令、HID 键码表）
+│   │   └── AhaKeyBLEManager.swift         # ★ CoreBluetooth 通信管理器
+│   ├── Views/
+│   │   ├── ContentView.swift              # Tab 容器
+│   │   ├── DeviceInfoView.swift           # 设备信息 + LED 测试 + BLE 日志
+│   │   ├── KeyMappingView.swift           # 键位映射配置 + 预设方案
+│   │   └──  LCDManagerView.swift          # LCD 图片/GIF 管理
+│   ├── Utilities/
+│   │   └── AgentManager.swift             # LaunchAgent 守护进程管理 + Claude hooks 安装
+│   └── Agent/
+│       ├── AhaKeyAgent.swift              # 轻量 BLE 守护进程（Unix socket 接收状态命令）
+│       └── main.swift                     # Agent 入口
+├── docs/
+│   └── ble-protocol.md                    # ★ 完整 BLE 协议文档
+└── .gitignore
+```
+
+### 重点文件
+
+| 文件 | 说明 |
+|------|------|
+| `Sources/BLE/AhaKeyProtocol.swift` | 你们的协议完整实现——帧编解码、所有 DeviceCmd、HID 键码表、响应解析 |
+| `Sources/BLE/AhaKeyBLEManager.swift` | 直接 CoreBluetooth 通信，自动扫描/连接/重连，写入队列防过载 |
+| `docs/ble-protocol.md` | 协议完整文档（从原厂工具反编译 + 抓包验证） |
+| `Sources/Agent/AhaKeyAgent.swift` | 后台守护进程，通过 Unix socket 接收 LED 状态命令 |
+| `Sources/Utilities/AgentManager.swift` | Claude Code hooks 自动安装/卸载（追加模式，不覆盖已有 hooks） |
+
+---
+
+## 架构说明
+
+### 与原厂工具的对比
+
+```
+原厂:  Python (PySide6) ←TCP→ .NET (BleTcpBridge) ←stdin/stdout→ Swift (ble_helper)
+本项目: Swift (SwiftUI + CoreBluetooth) ──BLE──> 键盘
+```
+
+省掉了 TCP 桥接层，连接更稳定，延迟更低，部署更简单（单个 .app）。
+
+### 双进程架构
+
+1. **AhaKeyConfig**（主进程）：SwiftUI GUI，键位配置、设备管理、LCD 管理
+2. **ahakeyconfig-agent**（守护进程）：无 UI，LaunchAgent 管理，维持 BLE 连接 + 接收 Unix socket 命令
+
+守护进程的存在是为了在 GUI 关闭后仍能接收 Claude Code hooks 的 LED 状态推送。
+
+### LED 状态同步流程
+
+```
+Claude Code hook → ahakey-state.sh → Unix socket → ahakeyconfig-agent → BLE 0x90 → 键盘 LED
+```
+
+---
+
+## 已知限制 / TODO
+
+1. ** LCD 图片上传**：协议已文档化（见 `ble-protocol.md` 第 8 节），UI 已有，但分包上传逻辑未实现
+2. **宏录入 UI**：协议支持宏（sub_type 0x74），但 UI 只做了快捷键映射
+3. **多模式切换**：代码支持 3 种工作模式（mode 0/1/2），但 UI 目前只操作 mode 0
+4. **拨杆联动**：原厂的拨杆→自动授权功能未移植（需要在 PermissionRequest hook 中查询 SwitchState）
+
+---
+
+## 许可说明
+
+本项目无偿共享，欢迎自由使用、修改、集成到你们的官方工具中。无需署名，无附加条件。
+
+协议文档 (`docs/ble-protocol.md`) 基于原厂工具反编译整理，版权归原始作者所有。
+
+如有问题欢迎随时沟通。
diff --git a/Resources/AppIcon/AhaKeyStudioIcon.png b/Resources/AppIcon/AhaKeyStudioIcon.png
diff --git a/.../macos/Resources/DefaultOLED/claude_0.gif → Resources/DefaultOLED/claude_0.gif b/.../macos/Resources/DefaultOLED/claude_0.gif → Resources/DefaultOLED/claude_0.gif
diff --git a/Resources/DefaultOLED/codex.gif b/Resources/DefaultOLED/codex.gif
diff --git a/Resources/DefaultOLED/cursor.gif b/Resources/DefaultOLED/cursor.gif
diff --git a/Resources/Help/AhaKeyStudioHelp.html b/Resources/Help/AhaKeyStudioHelp.html
@@ -0,0 +1,162 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>AhaKey Studio 帮助中心</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC", sans-serif;
+      line-height: 1.65;
+      color: CanvasText;
+      background: Canvas;
+    }
+    body {
+      margin: 0;
+      padding: 44px 28px 72px;
+    }
+    main {
+      max-width: 920px;
+      margin: 0 auto;
+    }
+    h1 {
+      font-size: 34px;
+      line-height: 1.18;
+      margin: 0 0 10px;
+    }
+    h2 {
+      font-size: 22px;
+      margin: 34px 0 12px;
+      padding-top: 8px;
+      border-top: 1px solid color-mix(in srgb, CanvasText 14%, transparent);
+    }
+    h3 {
+      font-size: 17px;
+      margin: 22px 0 8px;
+    }
+    p, li {
+      font-size: 15px;
+    }
+    p {
+      margin: 8px 0;
+    }
+    ul, ol {
+      padding-left: 24px;
+    }
+    .lead {
+      color: color-mix(in srgb, CanvasText 70%, transparent);
+      font-size: 16px;
+      margin-bottom: 24px;
+    }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+      gap: 12px;
+      margin: 18px 0;
+    }
+    .card {
+      border: 1px solid color-mix(in srgb, CanvasText 14%, transparent);
+      border-radius: 8px;
+      padding: 16px;
+      background: color-mix(in srgb, Canvas 92%, CanvasText 4%);
+    }
+    .card strong {
+      display: block;
+      margin-bottom: 6px;
+      font-size: 15px;
+    }
+    code {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 0.92em;
+      padding: 2px 5px;
+      border-radius: 5px;
+      background: color-mix(in srgb, CanvasText 10%, transparent);
+    }
+    .note {
+      border-left: 3px solid #0a84ff;
+      padding: 10px 14px;
+      background: color-mix(in srgb, #0a84ff 10%, Canvas);
+      border-radius: 6px;
+      margin: 16px 0;
+    }
+  </style>
+</head>
+<body>
+<main>
+  <h1>AhaKey Studio 帮助中心</h1>
+  <p class="lead">这份本地说明对应当前客户端界面和代码逻辑，适用于首次设置、权限排查、AhaType 云端整理和键盘配置。</p>
+
+  <h2>首次启动流程</h2>
+  <p>首次打开 AhaKey Studio 会进入新手引导。引导顶部按步骤显示，底部使用“上一步”和“下一步”推进。</p>
+  <div class="grid">
+    <div class="card">
+      <strong>欢迎</strong>
+      介绍连接键盘、后台语音键接管、macOS 原生语音和体验输入。
+    </div>
+    <div class="card">
+      <strong>系统授权</strong>
+      检查蓝牙、输入监控和辅助功能。蓝牙用于发现和连接键盘，输入监控与辅助功能用于后台接管实体语音键。
+    </div>
+    <div class="card">
+      <strong>语音授权</strong>
+      检查麦克风、语音转写、Siri 与听写。默认 macOS 原生语音需要这些能力都可用。
+    </div>
+    <div class="card">
+      <strong>开始体验</strong>
+      使用客户端内同一套语音链路试说一句话，确认识别和写入链路正常。
+    </div>
+  </div>
+
+  <h2>需要开启的系统权限</h2>
+  <ol>
+    <li><strong>蓝牙：</strong>在“隐私与安全性 > 蓝牙”允许 AhaKey Studio，并确保系统蓝牙已打开。</li>
+    <li><strong>输入监控：</strong>在“隐私与安全性 > 输入监控”允许 AhaKey Studio，用于后台监听实体语音键。</li>
+    <li><strong>辅助功能：</strong>在“隐私与安全性 > 辅助功能”允许 AhaKey Studio，用于把语音键转换成 macOS 原生转写或 Fn/Globe 行为。</li>
+    <li><strong>麦克风：</strong>在“隐私与安全性 > 麦克风”允许 AhaKey Studio，用于苹果原生语音采集。</li>
+    <li><strong>语音转写：</strong>在“隐私与安全性 > 语音识别”允许 AhaKey Studio，用于系统语音识别。</li>
+    <li><strong>Siri：</strong>在“系统设置 > Siri 与聚焦”开启 Siri。</li>
+    <li><strong>听写：</strong>在“系统设置 > 键盘 > 听写”开启听写。</li>
+  </ol>
+  <div class="note">如果系统设置里已经打开权限，但客户端仍显示未开启，请完全退出 AhaKey Studio 后重新打开。输入监控和辅助功能常按进程生效，重启后状态会与系统设置一致。</div>
+
+  <h2>主界面区域</h2>
+  <h3>顶部状态栏</h3>
+  <p>顶部显示设备连接状态、电量、拨杆状态、AhaType 开关和键盘控制状态。“更多”菜单提供重新连接设备、清空 LCD 预览、设备信息、云端账号和退出等入口。</p>
+
+  <h3>Keyboard Mode</h3>
+  <p>Mode 标签对应键盘不同工作模式。Claude Code、Cursor、Codex 三个预设会影响实体按键写入内容和语音键路由。</p>
+
+  <h3>配置区</h3>
+  <p>点击灯条、屏幕、四个按键或拨杆可以进入对应配置。修改会先保存到本地，连接设备并进入编辑配置后再同步到键盘。</p>
+
+  <h3>右侧检查面板</h3>
+  <p>“后台监听中”展示输入监控和辅助功能状态；“苹果原生转写”展示麦克风、语音转写、Siri 与听写状态；“AhaType 云端整理”展示云端整理开关、账号状态和额度信息。</p>
+
+  <h2>AhaType 云端整理</h2>
+  <p>开启 AhaType 后，语音识别结果会先发送到云端整理，再写入当前光标。若未登录、登录过期或额度不足，客户端会退回写入原始转写文本。</p>
+  <p>可在“更多 > 云端账号 · AhaType”登录、注册、刷新额度、兑换或购买额度。</p>
+
+  <h2>语音键体验</h2>
+  <ol>
+    <li>保持 AhaKey Studio 在后台运行。</li>
+    <li>确认权限检查里输入监控、辅助功能、麦克风、语音转写、Siri 与听写均已开启。</li>
+    <li>确认设备当前在 Mode 0，或在目标 Mode 中已配置语音键。</li>
+    <li>按一次实体语音键开始录音，再按一次结束并写入当前光标。</li>
+  </ol>
+
+  <h2>底部状态栏</h2>
+  <p>底部会显示当前选中的部件和模式、未同步改动数量、同步提示和最近同步时间。右下角的“新手引导”可重新进入分步引导，“帮助中心”会打开本文件。</p>
+
+  <h2>常见问题</h2>
+  <h3>为什么麦克风已打开仍提示未开启？</h3>
+  <p>请完全退出并重新打开 AhaKey Studio。若应用路径或签名发生变化，macOS 可能把新版本视为另一个应用，需要对当前正式包重新授权。</p>
+
+  <h3>为什么系统设置没有自动跳到准确页面？</h3>
+  <p>不同 macOS 版本的系统设置 URL 支持不完全一致。客户端会优先打开最接近的权限页；如果没有定位到目标项，请在“隐私与安全性”中手动选择对应权限。</p>
+
+  <h3>为什么连接状态显示由 Agent 控制？</h3>
+  <p>日常使用由后台 Agent 持有蓝牙连接；需要改键、LCD、同步或本机灯效测试时，点击“编辑配置”由 AhaKey Studio 临时接管蓝牙。</p>
+</main>
+</body>
+</html>