一个面向 Waveshare MK10 的开源 Codex 状态桥接：Mac 负责读取会话和控制，MK10 负责显示、按键与音效。
本项目是非官方社区项目，与 OpenAI、Waveshare 无隶属或背书关系；相关商标归各自所有。
感谢 LINUX DO 社区。
当前项目版本：0.29
- 完整链路已在一台原厂 MK10 V2.29（ARMv7/T113）上验证。
- 设备侧使用 USB CDC 串口，Codex 控制通过 ChatGPT Desktop 本地 IPC，不需要刷固件。
- Fast、Plan、Compact、Stop、Effort 通过 ChatGPT Desktop 的本地私有 IPC 控制。
- framebuffer 映射和 Codex IPC 都与版本相关；其他设备必须重新验证。
会话状态会在 MK10 本地渲染，Thinking、Input 和 Error 状态持续呼吸：
下排展示 Plan、Fast、Effort，以及 Stop 的运行和双击确认状态：
任务完成时会播放通知音，并从对应会话键扩散完成涟漪：
下面是运行项目版本 0.29 的 Waveshare MK10 实拍图：
完整的首装、升级、恢复、校准和故障排查流程见 安装指南。下面是最短可复现路径。
依赖：macOS、Xcode Command Line Tools、Go 1.25+、Python 3，以及已登录的 ChatGPT Desktop/Codex。
git clone https://github.com/Rladmsrl/codex-mk10-bridge.git codex-mk10-bridge
cd codex-mk10-bridge
go test ./...
scripts/install-macos.sh --no-start安装器会构建 mk10-bridge 和 mk10ctl，合并 Hook（保留其他配置），并生成用户级 LaunchAgent。默认不启动，避免设备尚未准备好时反复重启。
先关闭 ScreenKey，给原厂设备上电并查找串口：
go run ./cmd/mk10ctl ports
PORT=/dev/cu.usbmodemXXXX
go run ./cmd/mk10ctl probe --port "$PORT" --protocol legacy --timeout 10s确认返回的是 V2.29 风格 MK10 后再写入设备。首装脚本会重新构建 ARMv7
二进制、再次探测并按“二进制先、lunch.sh 后”的顺序写入四个文件：
scripts/init-device.sh --port "$PORT"如果原厂服务不可用，可让脚本预检一个明确的读卡器挂载点并安全弹出：
scripts/init-device.sh --card "/Volumes/REPLACE_WITH_CARD_LABEL" --eject原厂 legacy 服务不提供远端剩余空间查询；SD 空间接近上限时请使用读卡器模式， 脚本会在写入前拒绝不足的介质。
SD 只用于首装种子；不要刷 MK10_V1.0.img，也不要运行 PhoenixCard。
给 MK10 断电重启，然后验证自定义服务：
go run ./cmd/mk10ctl direct-info --port "$PORT" --timeout 8s
go run ./cmd/mk10ctl direct-version --port "$PORT" --timeout 8s确认 direct-info、direct-version 和 SHA 校验成功后启动：
scripts/install-macos.sh --start --port "$PORT"
scripts/update-device.sh
tail -f ~/.local/state/mk10-bridge.log首次启动会使用 /data/mk10-recovery；update-device.sh 会完成空间预检、恢复副本和正常副本的 SHA 校验，以及监督重启。
保持 ChatGPT Desktop 开启并登录。桥接启动时会先静音 MK10 键盘自身的 QMK 键码，然后推送语义状态。
桥接会在连接设备时记录设备二进制版本；桥接运行期间可直接查看：
~/.local/bin/mk10ctl bridge-status
~/.local/bin/mk10ctl bridge-status --json
~/.local/bin/mk10ctl storage-info --json该命令优先通过桥接的本机控制通道实时查询，失败时读取状态快照，不会抢占 USB 串口。
设备运行期间的版本、显示、音频、文件和重启等管理操作也统一通过这个本机通道执行， 不会再打开第二个 USB 串口；只有首装时的 legacy 探测和引导上传需要桥接尚未运行。
日常升级通过运行中的桥接更新 /data/mk10-recovery 和
/data/mk10-device，不写入空间很小的 SD 分区，也不需要停止桥接：
scripts/update-device.sh脚本会读取 /data 可用空间，为两次原子暂存各留出空间并额外保留 1 MiB，
逐份写入并回读 SHA，最后慢速确认新版本已经运行。脚本会串行化并发升级；需要保留上一版恢复副本时可加
--skip-recovery，否则脚本会在验证正常服务后同步恢复副本。
首装是一次性的种子部署，不是无操作重复执行；升级支持中断后重试并收敛， 但每次都会生成新的时间戳二进制并重启服务，脚本会串行化并发升级。
deploy-service 会执行原子上传、SHA-256 回读、一次监督重启和慢速版本校验。不要在重启期间高频重连串口。
如果自定义服务仍可访问，把 device/lunch-restore.sh 写成下一次启动的 lunch.sh 后重启；如果 USB 不可用，用读卡器复制为 lunch.sh 再上电。完整步骤见 安装指南。
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/mk10ctl
scripts/build-device.sh /tmp/mk10-device
go run ./cmd/mk10ctl preview-ui --out /tmp/mk10-preview.jpg- 桥接只从本机读取 Codex 认证、会话和设置文件；需要配额时会使用现有 OAuth 令牌访问 ChatGPT 服务。
- OAuth 令牌不会写入设备或桥接日志；任务标题、生命周期状态和控制请求会通过 USB 发送到 MK10。
- 设备不保存网络管理凭据，也不提供网络管理接口；USB 直连协议只应连接可信主机。
- 项目不包含遥测服务；请在提交问题或日志前移除本地路径、会话内容和网络信息。