简体中文 · English

面向 AI 编程与桌面工作流的开放硬件入口

官方硬件 · 桌面客户端 · BLE 协议 · 社区扩展

AhaKey 采用 “开源软件 + 开放协议 + 社区共创 + 受控硬件资料” 的分层开放机制。

我们默认开放官方桌面客户端源码、BLE 协议文档、客户端开发示例和社区项目展示入口，鼓励用户基于公开协议开发自己的客户端、脚本、工具和 AI workflow。

固件源码、硬件设计文件、PCB、BOM 和生产资料不默认公开。如确有学习、调试、研究或共创需要，可以通过 AhaKey 硬件源码访问计划 提交说明，我们会尽量支持真实的学习、开发和社区共创需求。

AhaKey 尊重用户对自己设备的本地控制权。
我们不会故意通过远程认证、云端锁定或固件更新，破坏已公开协议下的合理本地开发和第三方客户端使用。

这些文件不是新的用户入口，而是 AhaKey 社区的基础维护规则。
普通用户不需要一开始全部阅读；当你准备提 Issue、PR、报告安全问题或参与社区协作时，再查看对应文档即可。

简单理解：

想贡献 → CONTRIBUTING
遇到问题 → SUPPORT
安全问题 → SECURITY
社区行为规范 → CODE_OF_CONDUCT

进入 Releases
→ 下载最新版本
→ 安装桌面客户端
→ 连接 AhaKey
→ 开始使用

适合：

• 只想使用 AhaKey
• 不改代码
• 不做开发
• 需要下载安装包

入口：desktop/releases

进入 desktop
→ 阅读 README
→ Fork 仓库
→ 修改代码
→ 本地测试
→ 提交 Pull Request

适合：

• 修 bug
• 改 UI
• 优化安装体验
• 增加 macOS / Windows 适配
• 改进官方默认体验

入口：desktop

进入 protocol
→ 阅读 BLE 协议
→ 参考 examples
→ 创建自己的 repo
→ 做出 demo
→ 提交到 awesome-ahakey

适合：

• 自己写 macOS / Windows 客户端
• 做 Cursor / Claude / Codex 工作流工具
• 做快捷键脚本
• 做 OLED / RGB / 配置工具
• 做自动化集成

入口：protocol

进入 awesome-ahakey
→ 找到感兴趣的项目
→ 查看 README / Demo
→ Fork 或参考实现
→ 做自己的改造

适合：

• 看别人怎么玩 AhaKey
• 找现成工具和教程
• Fork 社区项目继续改
• 学习第三方客户端或 workflow 的实现方式

入口：awesome-ahakey

进入 awesome-ahakey
→ 按模板提交项目
→ 社区收录
→ 优秀功能可进一步评估是否进入官方 desktop

适合：

• 第三方客户端
• 工具脚本
• 使用教程
• 工作流 preset
• 桌面 setup 展示
• 视频 / 图文教程

入口：awesome-ahakey

进入对应仓库的 Issues
→ 描述问题
→ 提供复现步骤
→ 补充系统环境、日志或截图
→ 等待维护者确认

适合用 Issue 的情况：

• 官方客户端无法启动
• BLE 连接异常
• 某个功能稳定复现错误
• 文档有明显错误
• 构建 / 安装流程失败
• 协议文档中某个字段不清楚

常用入口：

• 官方客户端问题：desktop/issues
• 协议问题：protocol/issues

进入 Discussions
→ 描述你的想法 / 玩法 / 场景
→ 和社区一起讨论
→ 成熟后再决定是否开 Issue 或 PR

适合用 Discussion 的情况：

• 你还不确定这是不是 bug
• 你有一个新功能想法
• 你想讨论某种 AhaKey 玩法
• 你想展示正在做的 DIY
• 你想发起一个高关注度的共创话题
• 你想问“这个功能该不该做、怎么做”

入口：GitHub Discussions

简单理解：

不确定 → 先 Discussion
明确问题 → 提 Issue
已经改好 → 提 Pull Request
做了独立作品 → 提到 awesome-ahakey

你可以贡献：

• bug report
• 文档修正
• 安装教程
• macOS / Windows 客户端改进
• BLE 协议反馈
• 第三方客户端
• workflow / preset / 脚本
• 使用视频、截图、教程

建议尽量保持：

• 小步提交
• 说明清楚
• 有截图 / 日志 / demo 更好
• 不提交密钥、token、私人文件
• 大功能先 Discussion，再 PR

如果公开协议、客户端示例和社区文档已经不能满足你的开发需求，例如你正在做固件级调试、底层行为研究、教程共创或希望参与更深层的硬件 / 固件贡献，可以通过下面的入口提交说明：

AhaKey 硬件源码访问计划

这个计划面向真实的学习、研究、调试和社区共创需求。
固件源码、硬件设计文件、PCB、BOM 和生产资料不默认公开，未经授权不得用于自行打板、仿制、量产、销售或开发竞争性硬件产品。

如果你想了解 AhaKey、下载软件、购买设备、加入讨论或联系官方，可以从下面这些入口开始。

扫码加入中文社群 / 联系客服

微信公众号	微信讨论群	QQ 讨论群
关注公众号	加入微信讨论群	加入 QQ 讨论群
小红书群	企业微信客服	更多入口
加入小红书群	联系专人客服	ahakey.com 官网与下载入口

↑ Back to top

An open hardware entry point for AI coding and desktop workflows

Official Hardware · Desktop Client · BLE Protocol · Community Extensions

AhaKey follows a layered openness model: open-source software + open protocol + community collaboration + controlled hardware materials.

We open the official desktop client source code, BLE protocol documentation, client development examples, and community project showcase entry points by default. We encourage developers to build their own clients, scripts, tools, and AI workflows based on the public protocol.

Firmware source code, hardware design files, PCB files, BOM, and production materials are not public by default. If you need them for learning, debugging, research, or collaboration, you can submit a request through the AhaKey Hardware Source Access Program.

AhaKey respects users' local control over their own devices.
We will not intentionally use remote authentication, cloud lock-in, or firmware updates to break reasonable local development or third-party clients built on published protocols.

These files are not extra entry points for new users.
They are the basic rules and support files that help keep the AhaKey community maintainable.

You do not need to read all of them at the beginning.
Check the relevant file when you are ready to submit an Issue, open a Pull Request, report a security issue, or participate in community collaboration.

Simple rule:

Want to contribute → CONTRIBUTING
Need help → SUPPORT
Security issue → SECURITY
Community behavior → CODE_OF_CONDUCT

Go to Releases
→ Download the latest version
→ Install the desktop client
→ Connect AhaKey
→ Start using it

Best for:

• users who only want to use AhaKey
• no code changes
• no development work
• downloading installers

Entry: desktop/releases

Go to desktop
→ Read the README
→ Fork the repository
→ Modify the code
→ Test locally
→ Submit a Pull Request

Best for:

• bug fixes
• UI improvements
• installation experience improvements
• macOS / Windows support improvements
• improvements to the official default experience

Entry: desktop

Go to protocol
→ Read the BLE protocol
→ Check examples
→ Create your own repo
→ Build a demo
→ Submit it to awesome-ahakey

Best for:

• your own macOS / Windows client
• Cursor / Claude / Codex workflow tools
• shortcut scripts
• OLED / RGB / config tools
• automation integrations

Entry: protocol

Go to awesome-ahakey
→ Find an interesting project
→ Read its README / Demo
→ Fork it or learn from it
→ Build your own remix

Best for:

• seeing how others use AhaKey
• finding existing tools and tutorials
• forking community projects
• learning from third-party clients or workflow implementations

Entry: awesome-ahakey

Go to awesome-ahakey
→ Submit your project with the template
→ Get listed by the community
→ High-value features may later be evaluated for the official desktop

Best for:

• third-party clients
• utility scripts
• tutorials
• workflow presets
• desktop setup showcases
• video / article tutorials

Entry: awesome-ahakey

Go to Issues
→ Describe the problem
→ Provide reproduction steps
→ Add environment info, logs, or screenshots
→ Wait for maintainer confirmation

Use Issues for:

• official client startup failures
• BLE connection problems
• reproducible feature bugs
• documentation errors
• build / installation failures
• unclear protocol fields

Common entries:

• Desktop issues: desktop/issues
• Protocol issues: protocol/issues

Go to Discussions
→ Describe your idea / use case / workflow
→ Discuss with the community
→ Open an Issue or PR later if it becomes clear

Use Discussions for:

• uncertain questions
• new feature ideas
• AhaKey workflow discussions
• DIY build logs
• high-attention collaboration topics
• questions like “should this be built?” or “how should this be built?”

Entry: GitHub Discussions

Simple rule:

Not sure → Discussion
Clear problem → Issue
Already changed something → Pull Request
Built an independent project → awesome-ahakey

You can contribute:

• bug reports
• documentation improvements
• installation guides
• macOS / Windows client improvements
• BLE protocol feedback
• third-party clients
• workflows / presets / scripts
• videos, screenshots, and tutorials

Please try to keep contributions:

• small and reviewable
• clearly explained
• accompanied by screenshots / logs / demos when helpful
• free of secrets, tokens, or personal files
• discussed first if the feature is large

If the public protocol, client examples, and community documentation are not enough for your project, for example if you are doing firmware-level debugging, low-level behavior research, tutorial co-creation, or deeper hardware / firmware contributions, you can submit a short request here:

AhaKey Hardware Source Access Program

This program is intended for real learning, research, debugging, and community collaboration needs.
Firmware source code, hardware design files, PCB files, BOM, and production materials are not public by default. Without authorization, controlled materials may not be used for board reproduction, cloning, manufacturing, resale, or development of competing hardware products.

If you want to learn about AhaKey, download software, buy the device, join discussions, or contact the team, start here.

Chinese community QR codes / support contact

WeChat Official Account	WeChat Group	QQ Group
Follow us	Join WeChat group	Join QQ group
Xiaohongshu Group	WeCom Support	More
Join Xiaohongshu group	Contact support	ahakey.com Website and downloads

↑ Back to top