前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，会话是否在跑、有没有待审批、Token 和上下文大概用到哪，通常只能盯着电脑上的 Web 或 Desktop 界面。需要授权时还要切回会话卡片点选。若你已经在用或打算做一块 ESP32-S3 小屏（Buddy 固件），更自然的做法是：状态在设备上可见，触摸即可 Allow Once 或 Deny，并与 Harness 官方审批卡片双向同步。
ESP Buddy（npm 包名 dsh-esp-buddy）是 WayAero 维护的 DSH Cordis 客户端类插件：经蓝牙低功耗（BLE）把汇总会话、Token 与上下文信息推到设备，并处理触摸审批、电脑校时和角色包传输。硬件烧录与接线见配套 ESP32-S3 Buddy 固件仓库；插件侧面向 DeepSeek Harness 0.2.0-rc.2、Cordis ~4.0.4，要求 Node.js >=22（资料中 npm 包版本为 0.5.1）。
这是什么¶
插件运行在运行 Harness 的那台电脑上：Desktop 与 Web 都通过主机蓝牙连设备；在其他设备上打开 Web 页面不会用到浏览器所在机器的蓝牙。Windows x64 包内置蓝牙辅助程序，日常使用无需单独装 Python；Linux x64 与 macOS arm64 需按仓库开发文档自行部署辅助程序路径。
设备须运行配套固件并广播 Nordic UART Service（NUS）。插件按 NUS 服务 UUID 发现设备，不按名称前缀筛选；默认蓝牙名常为 DeepSeek-XXXX，也可为 Claude-XXXX 或自定义名，但其他产品也可能使用 NUS，需核对 BLE 地址。
核心功能¶
| 能力 | 说明 |
|---|---|
| 工作状态 | 显示会话总数、运行数、待审批数与会话摘要；变化时推送，默认每 3 秒补发 |
| Token 与上下文 | 汇总会话 Token；上下文为最近更新会话的估算，取决于 Harness 数据是否可用 |
| 触摸审批 | 设备选 Allow Once / Deny；官方卡片保留完整信息与入口，任一端决定后另一端同步结束 |
| 电脑校时 | 连接与重连后发时间，持续连接每 10 分钟同步，系统时间或时区变化时补发 |
| 角色包 | 在插件详情页选目录，经 Folder Push V2 装到设备，无需重烧固件 |
| 连接管理 | 自动连接、断线重连、指定 deviceAddress、查看状态与复制诊断信息 |
审批请求在设备与 Harness 卡片同时出现；设备离线、辅助程序失败、超时或插件停用时不自动拒绝，未决请求交给 Harness 后续应答链。BLE 会发送审批摘要与状态到设备屏幕，旁人可见；插件不转发完整命令参数。
安装与启用¶
DSH 生态里插件由 Harness 管理；社区目录页 dsh-esp-buddy 与 GitHub 仓库 WayAero/dsh-esp-buddy 为独立信息源，与 DeepSeek / 幻方无官方从属关系。安装前请自行查看源码与 MIT 许可；插件以当前 dsh 进程权限运行。
方式一：Harness 插件页¶
- 打开 Harness 插件（Plugins）→ 添加插件。
- 输入
dsh-esp-buddy安装 npm 发布版；指定版本时用dsh-esp-buddy@版本号。 - 启用 ESP Buddy 组合包及其中的
esp-buddy行，在详情页配置设备。
方式二：终端（推荐命令来自 README）¶
桌面端与 Web 各自 profile，请装到实际使用的 profile：
# 桌面端
dsh plugin --profile desktop add dsh-esp-buddy
# Web；自定义 profile 时替换 web
dsh plugin --profile web add dsh-esp-buddy
升级可在插件页卸载后安装目标版本，再刷新 Web 或重启 Desktop。
首次连接与日常设置¶
下面按 README 的可复现顺序操作。
- 按 固件 README 准备硬件、烧录并启动；默认蓝牙名
DeepSeek-XXXX。 - 在 Windows 设置 → 蓝牙和设备 → 添加设备 → 蓝牙 中配对 Buddy，按屏幕提示完成；首次 MITM 配对由系统完成。
- 在 Harness 启用 ESP Buddy 并打开详情页；默认
autoConnect，一次扫描约 10 秒。 - 多台 NUS 候选时，在「最近错误」查看名称与地址，将目标写入 BLE 设备地址（配置键
deviceAddress）并保存。 - 连接后启动 Harness 会话，设备随活动更新；校时以设备显示为准（消息无专用 ACK）。
详情页常用配置（保存后生效；改地址或心跳间隔会重启蓝牙辅助程序）：
| 配置键 | 默认值 | 用途 |
|---|---|---|
enabled |
true |
启用插件 |
autoConnect |
true |
自动连接 |
deviceAddress |
空 | 唯一候选自动选；填写则固定地址 |
approvalTimeoutMs |
300000 |
设备端审批等待（毫秒） |
heartbeatIntervalMs |
3000 |
状态补发间隔（1000–29000） |
rolePackWriteDelayMs |
0 |
角色包 JSONL 写完后等待（0–4） |
只读或远程 memory 模式无法保存时，请在运行 Harness 的主机本地 Web 或 Desktop 中改配置。
角色包示例¶
目录不能含子目录。最小 GIF 角色包结构如下：
my-buddy/
├── manifest.json
├── idle.gif 必需
├── busy.gif 可选
├── attention.gif 可选
├── sleep.gif 可选
└── NOTICE.txt
{ "name": "my-buddy", "mode": "gif" }
资料建议单 GIF 约 84×84、最多 80 帧、约 8 FPS、最多 210 KiB、最多 64 色；需固件支持 Folder Push V2。npm 包与仓库附带示例 dsh-pet-maid，素材条款见包内 NOTICE.txt（允许开源使用、禁止商用）。
适用场景与注意¶
适合：已在 Windows 11 x64（推荐）上跑 Harness 0.2.0-rc.2 系、具备可用蓝牙，并持有 ESP32-S3 Buddy 固件设备的开发者；希望桌面物理屏看会话/Token、触摸批审批、偶尔换 GIF 角色而不重烧固件。
注意：
- 与 Claude Code 共用设备时，须先停用本插件，设备改蓝牙名为
Claude开头并改用 cc-buddy-bridge；切回 Harness 前退出桥接 daemon。设备一次只连一个 BLE 客户端。 - Token 为插件汇总会话数据，非账户账单；上下文为估算值。
- 找不到设备时：确认固件广播 NUS、系统已配对、未被其他 profile 或桥接占用。
故障排查表与 Issue 提交字段见 GitHub README。
结尾¶
dsh-esp-buddy 把 Harness 的会话聚合、Token 视图与审批流接到 ESP32-S3 Buddy：主机 BLE 推送状态，触摸与官方卡片同步决策，并可校时与推送角色包。目录页：https://www.skillhub.cn/plugins/WayAero/dsh-esp-buddy；源码与完整说明：https://github.com/WayAero/dsh-esp-buddy。
