前言¶
在 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。
