企业官网建设流程全解析

openharness 是面向 coding agents 的统一指挥台（command center），它的开源配件Harness device是一个摆在桌面的圆形小圆盘：USB 一连，所有 Agent 的实时状态尽收眼底。本文带你完整拆解它的 PCB 设计、外壳结构、物料清单与 ESP32-S3 固件，从零理解这套开放硬件是怎么把"多 Agent 并行工作"变成一眼可见的桌面体验。

它到底是什么：一个桌面 Agent 状态显示器

Harness device 是一块 1.75 英寸 466×466 圆形 AMOLED 触摸显示屏，内置双麦克风和扬声器，核心是ESP32-S3。它通过USB 数据线连接运行 Harness daemon 的电脑：

• 屏幕上直接显示每个 Agent 在干什么、谁做完了、谁在等你回答；
• Agent 提问时，圆盘弹出问题，点按屏幕或语音直接作答；
• 按住侧边按钮说话，即可不切窗口下发新任务（语音由主机侧转写，设备本身不存任何云端凭据）。

没有 Wi-Fi、没有账号、没有配对码——插上线即连上，这正是它的设计哲学。

硬件拆解：PCB 设计与 Gerber 文件

整块 PCB 设计在 EasyEDA Pro 中完成，仓库里提供了从原理图到打板文件的全套资料，位于 devices/harness-device/hardware/pcb/：

正面（Rev 2.0）是显示 FPC 连接器、双麦克风、USB-C 与音频编解码 IC；背面则是带印刷天线走线的 ESP32-S3-WROOM 模组，以及扬声器座（SPK）和扩展 FPC（EXP）。

尺寸上非常克制：直径约 52.5 mm、高 24.11 mm，加激光切割的 3 mm 钢板配重底座后宽 53.89 mm，稳稳坐在键盘旁边。

外壳与结构：STEP + STL 双格式 3D 文件

机械部分位于 devices/harness-device/hardware/3d/，每个零件都提供STEP（参数化 CAD 源文件，可导入 FreeCAD / SolidWorks / Fusion 360 编辑）和STL（可直接切片打印）两种格式：

3D 打印外壳带有安装柱、螺丝孔和 USB-C 开孔；PCB 落位后，底部的 USB 夹把端口 PCB 固定在 V / -D / +D / G 四个焊盘上。

完整物料清单（BOM）

一份整机 BOM 列在 devices/harness-device/hardware/BOM.csv，做一台只需 11 项：

小提示：显示屏模组的丝印标的是 CST9217 触摸控制器，但实际采购批次可能是同封装的CST816S。固件会自动探测两种型号并选择对应驱动，无需单独编译。

固件解析：ESP32-S3 + ESP-IDF，USB 即协议

固件源码在 devices/harness-device/firmware/，基于 ESP-IDF 构建。核心目录结构一目了然：

• main/board/ —— 板级引脚、I²C、触摸/电源管理探测（引脚定义见 board_pins.h）
• main/ui/habitat/ —— 圆形屏幕 UI：滚动、触控、终端文本渲染、宠物动画
• main/cable_client.c —— 与 daemon 的"线缆协议"（见 cable_client.h）
• main/audio_client.c / ptt.c —— 麦克风采集与按键说话
• main/fw_update.c —— 固件经 USB 更新

固件会自动在 I²C 总线上探测两种硬件变体（CST9217 + AXP2101 电源管理，或 CST816S 无 AXP2101），并据此选择驱动和重置引脚（GPIO 39/40 或 1/2）——一套镜像适配两种板子。

构建与烧录（需 ESP-IDF 5.5+，完整指南见 devices/harness-device/firmware/README.md）：

cd devices/harness-device/firmware idf.py set-target esp32s3 idf.py build idf.py -p PORT flash monitor

没有真机也能跑主机侧测试：make device-test（协议、UI、渲染都有大量 C/Python 测试，见 firmware/test/）。

线缆协议：hello / welcome 握手，JSON 帧流

圆盘和 daemon 之间跑的是"带帧的 JSON 线缆协议"，逻辑在 cable_client.h 中注释得非常直白：

1. 设备上电后发送hello，daemon 回复welcome，之后才开始拉取 Agent 列表——welcome到达前屏幕显示 "Not connected"；
2. daemon 主动推送 Agent 花名册（当前 tab 最多 16 个）、swarms（多 Agent 分组）、turn.started/activity/done（回合状态）、question（提问）等帧；
3. 圆盘可回发：提交新任务、停止回合、回答提问、报告滚轮滑动、发起语音流（PCM 1024 字节分帧），以及接收 USB 固件更新；
4. 容错是设计原则：读不懂的帧只计数、不断链、不重启——因为线路上随时可能有 bootloader 噪音和更新版的 daemon。

语音链路尤其优雅：圆盘只负责采集，daemon 负责转写，转写结果自动路由到指定 Agent 发起新回合。UI 交互流程（启动状态机、项目主页、语音 PTT、STOP 中断、问答流程）完整记录在 devices/harness-device/firmware/docs/UI_FLOWS.md。

文件总导航与进阶

另外，仓库里还有一台更大的方形设备Harness Pro（ESP32-P4 + 720×720 触摸屏，Pod 界面），固件与协议契约文档在 devices/harness-pro/（含 docs/cable.md 能力协商机制），是同一套 daemon 的另一块"客户端"，适合想扩展硬件的同学参考。

从 Gerber 到 STL，从 BOM 到可编译的 ESP-IDF 固件，openharness 把这台桌面圆盘做成了真正意义上的开放硬件——改引脚、换屏幕、加功能，全在你自己的手里。