项目定位

这是一个个人制作的硬件 Demo（概念验证），用来展示“AI Agent 状态副屏”这一玩法。它适合学习、复现、改造和社区交流，目前不是一套面向量产或长期运维的完整产品。

固件会把硬件变成 Harness 专用状态屏，只保留本 Demo 所需的界面与交互。源码树仍包含开发板原工程的部分板级支持模块，以保证固件可以完整构建；运行时入口由 PRODUCT_HARNESS_ONLY=1 限制为 Harness 模式。

它能做什么

• 显示当前状态：离线、待命、思考、执行工具、等待、等待选择、完成、错误、已停止。
• 显示当前任务标题、持续时间、Todo 进度和工具类型。
• 显示 DeepSeek API 余额；任务结束后立即刷新，并在 3 秒、10 秒、30 秒补拉，另有 5 分钟兜底刷新。
• 金额过长时循环滚动显示，人民币格式为 123.45元。
• 用不同的 Q 萌慵懒鲸鱼娘动效表达不同状态。
• 普通单选题可直接在设备上用上/下/确认三键回答。
• 插件内可用 /whale 查看桥接器与硬件连接状态。
• 电脑和设备通过 BLE 连接，不要求同一 Wi-Fi，也不依赖 2.4 GHz 网络。

为什么仍然需要桥接器

需要，但用户不用手动启动它。

DeepSeek Harness 运行在电脑上，ESP32-C3 设备通过 BLE 接收数据；两端不能直接调用彼此的运行时 API。仓库中的 Python 桥接器负责把本机插件事件转换成紧凑 BLE 数据帧，并把设备按键选择送回插件。安装完成后，Harness 插件会自动启动和管理桥接器。

flowchart LR
    A[DeepSeek Harness] -->|事件| B[TypeScript 插件]
    B -->|仅本机 UDP| C[Python BLE 桥接器]
    C -->|BLE| D[ESP32-C3 状态副屏]
    D -->|单选结果| C
    C --> B
    C -.余额查询.-> E[DeepSeek API]

插件不会把 Prompt、模型回答、文件内容、工具参数或 API Key 发给设备。详见 架构说明 与 BLE 协议。

硬件要求

当前已测试配置：

这份固件包含特定开发板的屏幕、按键、电源和分区配置，并不是任意 ESP32-C3 开发板都能直接烧录。使用其他板子时，请先修改 board_config.h 和显示驱动配置，再自行构建。

电脑端要求

• Windows 10/11 64 位（当前一键安装流程的实测平台）。
• Python 3.10～3.13，安装时勾选 Add Python to PATH。
• 电脑有可用蓝牙，并已安装 DeepSeek Harness。
• 烧录固件时使用可传输数据的 USB 线。

最快安装方式

1. 下载代码与固件

先克隆仓库，或使用 GitHub 的 Code → Download ZIP 下载代码：

git clone https://github.com/1ikeMcFlurry/harness-whale-companion.git
cd harness-whale-companion

再从 Releases 下载唯一的固件文件 Harness-Whale-ESP32C3-8MB.bin，放到 installer\firmware\。校验清单已经包含在代码仓库中。

2. 安装 Harness Companion

在仓库根目录打开 PowerShell：

python installer\install_companion.py

安装器会：

1. 把插件安装到 ~/.dsh/plugins/harness-whale-companion/；
2. 把桥接器安装到 ~/.dsh/harness-whale-bridge/；
3. 创建独立 Python 虚拟环境并安装 BLE 依赖；
4. 自动更新 Harness 的 cordis.patch.yml；
5. 静默询问 DeepSeek API Key，用于余额显示。

API Key 可以直接回车跳过；跳过后其余状态功能仍可使用，设备余额显示为 --。不要把 Key 放进命令行、截图、Issue 或 Git 提交。

安装后完全退出并重新启动 Harness。输入 /whale 可以查看桥接器和设备连接状态。

3. 烧录固件

烧录会整片擦除设备上的旧固件、NVS、配置和存档，请先确认设备允许被覆盖。

python -m venv .flash-venv
.\.flash-venv\Scripts\python.exe -m pip install -r installer\requirements-flash.txt
.\.flash-venv\Scripts\python.exe installer\flash_firmware.py

脚本会自动识别串口、校验 SHA-256、擦除 Flash，并把完整镜像从 0x0 写入。烧录后 BLE 名称为 HARNESS-WHALE。

设备上的单选交互

当 Harness 请求普通单选时：

• 上键 / 下键：切换选项；
• 确认键：提交当前选项；
• 2～4 个选项：一页显示；
• 5 个及以上：每页显示 3 个实际选项和 1 个翻页项。

为了保持小屏交互简单，多选、自由文本和复杂的“其他”补充仍回到电脑完成。电脑与设备同时等待时，任意一端先回答，另一端会自动取消，避免重复提交。

自定义固件路径

若不想把 .bin 放到 installer\firmware\，请把 installer\firmware\manifest.json 复制到 .bin 同一目录，再显式指定固件：

python -m venv .flash-venv
.\.flash-venv\Scripts\python.exe -m pip install -r installer\requirements-flash.txt
.\.flash-venv\Scripts\python.exe installer\flash_firmware.py --firmware D:\path\to\Harness-Whale-ESP32C3-8MB.bin

从源码构建固件

安装 ESP-IDF 5.5，并进入已激活 ESP-IDF 环境：

cd device-firmware
idf.py set-target esp32c3
idf.py build
python scripts\release.py

主要入口：

• 专用运行时：device-firmware/components/app/src/app.c
• Harness UI：device-firmware/components/ui/presentation/src/ui_harness.c
• 状态协议解析：device-firmware/components/core/services/src/harness_status.c
• BLE GATT：device-firmware/components/platform/platform_esp32/src/ble_config.c
• 板级引脚：device-firmware/components/platform/platform_esp32/include/platform/board_config.h

交给豆包或其他 AI 自动部署

仓库根目录的 AGENTS.md 和 docs/AI_DEPLOYMENT.md 是机器可读的确定性操作说明。可以把下面这段话直接交给能够操作本机终端的 AI：

请先完整阅读 AGENTS.md 和 docs/AI_DEPLOYMENT.md，然后从这个代码仓库部署 Harness Whale Companion，并从 Release 下载唯一的 .bin 固件。先做只读环境检查，再运行源码安装器；API Key 必须由我在终端中静默输入，禁止输出、记录或写入脚本。烧录前必须确认串口和整片擦除范围，只烧录目标 ESP32-C3，不要修改其他 Harness 插件。

项目目录

常见问题

更多检查步骤见 排障手册。

Release 文件

Release 只放 .bin。Harness 插件、桥接器、安装器、固件源码、manifest、AI 部署说明和测试全部在代码仓库中，便于直接审阅与更新。

安全与隐私

• UDP 只监听 127.0.0.1，不会开放局域网端口。
• BLE 只发送状态、工具分类、计时、Todo、标题和余额，不发送 Prompt 或模型输出。
• API Key 只由本机桥接器读取并直接请求余额接口，不进入 UDP/BLE 数据帧。
• Windows 安装器把 Key 保存到当前用户环境变量；仓库、配置文件和设备中都不保存 Key。

当前限制

• 这是个人 Demo，安装和硬件兼容范围仍比较窄。
• 一键安装目前只验证了 Windows 10/11 64 位。
• 预编译固件只适用于上述已测试板级配置。
• 仓库当前未声明统一许可证；第三方组件仍遵循其各自目录中的许可文件。

欢迎把它当作 Agent 硬件交互的起点继续改造。