My Agents

My Agents 是一个配合 Magpie 使用的桌面状态面板和实体小屏项目。它把 Magpie 中可观察到的 Agent 活动、Token 用量和费用统计显示在 Windows 托盘应用与一块 240 × 240 的 ESP8266 屏幕上；桌面端还可以查看和筛选账号额度。

适合希望在工作时快速了解 Agent 是否正在活动、查看用量趋势，或把状态放到桌面小屏上的用户。即使没有实体屏幕，也可以先使用浏览器或 Windows 应用中的预览。

界面预览

桌面端显示设备预览和账号额度（截图中的账号信息已遮盖）：

240 × 240 屏幕预览：

功能

• Agent 活动：显示 Magpie 当前报告的活动会话，屏幕最多显示 10 个图标。它不是所有已打开 Agent 窗口的清单。
• 用量统计：按日、周、月、季度或年展示 Token、估算费用和趋势。请求历史不完整时，界面会标记统计可能不完整。
• 账号额度：读取本地及已启用的远程 Magpie 缓存额度；可按账号选择显示的周期或模型，并选择圆形或条形进度。设置弹框提供实时预览。同一账号的同名额度项合并时，优先显示已用比例最高的一项，用量相同时使用较早的重置时间。
• 屏幕控制：桌面预览支持旋转、角度校准、图标数量及四种屏幕样式；配置通过桥接服务同步给设备。
• 托盘与通知：Windows 托盘控制桥接服务，并可在 Magpie 报告会话响应结束后发送通知。通知依赖 Magpie 可见的活动，不能保证整个任务成功。
• 设备配网：首次启动时可通过设备热点配置 2.4 GHz Wi-Fi。

工作原理

flowchart LR
    M[本机 Magpie] -->|活动与用量 API| B[Node.js 桥接服务]
    B -->|Bearer Token + 局域网 HTTP| E[ESP8266 小屏]
    B -->|状态与配置| D[Windows 托盘应用]
    M -->|缓存额度| D
    R[远程 Magpie，可选] -->|缓存额度| D
    D --> P[桌面屏幕预览与账号额度]

Loading

桥接服务从本机 Magpie 的 127.0.0.1:3425 接口读取活动和用量，整理为设备可消费的精简 JSON。ESP8266 约每两秒通过 GET /api/agents 拉取状态，并使用共享 Bearer Token 鉴权。桌面预览根据相同状态绘制画面，不是从实体屏幕读取的画面。

账号额度由桌面端的桥接控制器读取本地 Magpie，以及 Magpie 配置中启用的 remote-magpie 来源。读取的是缓存额度，不会主动触发供应商额度刷新。远程 Gateway Key 留在控制器进程中，不发送到浏览器页面。

日、周、月的统计总量来自 Magpie 的汇总接口；季度和年度总量及图表数据依赖请求历史。每次刷新最多读取 4,000 条历史记录，因此较长周期可能不完整。活动图标也只反映 Magpie 能观察到的请求。

环境要求

• Windows 电脑，以及能够正常运行并提供本地接口的 Magpie。
• Node.js 18 或更高版本；构建桌面应用需要 npm。
• 实体屏幕可选：SD2 / “小电视”开发板，ESP-12S / ESP8266EX、4 MB Flash、240 × 240 ST7789 屏幕和 CH340 USB 串口。其他硬件需要自行调整引脚和显示驱动。
• 构建或刷写固件需要 PlatformIO Core、USB 数据线和可用的串口驱动。
• 电脑与设备需要处于可互通的局域网；ESP8266 连接 2.4 GHz Wi-Fi。

快速开始

以下命令在仓库根目录的 PowerShell 中执行。先启动 Magpie，并把示例地址替换成电脑在局域网内的实际 IPv4 地址。

1. 初始化桥接配置

.\bridge\Start-MagpieBridge.ps1 -SetupOnly -BindAddress <电脑的局域网IPv4地址>

此命令根据 firmware/include/secrets.example.h 生成本地 firmware/include/secrets.h，写入桥接 URL 和随机共享 Token。已有有效 Token 会保留。该文件被 Git 忽略，请勿提交或分享。

2. 启动桌面应用

cd bridge\tray-app
npm ci
npm start

应用启动后会出现在 Windows 通知区域，并在需要时启动桥接服务。点击托盘图标打开控制窗口；关闭或最小化窗口会将其隐藏到托盘。通过托盘菜单的“退出并停止桥接”结束程序和桥接服务。

在控制窗口中可查看屏幕预览和账号额度，通过“管理显示”选择账号、额度项及进度条样式；“设置”窗口用于配置桥接地址、设备显示和通知。

3. 可选：构建并刷写实体屏幕

在仓库根目录运行：

cd firmware
pio run
pio device list
pio run -t upload --upload-port COM4

将 COM4 替换为 pio device list 显示的设备端口。刷写会替换板上现有固件。首次启动时，根据屏幕显示的热点名称和密码连接设备热点，在手机浏览器打开 http://192.168.4.1，选择 2.4 GHz Wi-Fi 并输入密码。设备验证连接后会把凭据保存到 EEPROM。

设备需要访问桥接服务绑定的地址和端口。若电脑地址或端口变化，在桌面设置中更新配置后，需要重新构建并刷写固件，因为桥接 URL 编译在固件中。设备显示样式、旋转和统计周期等设置则可在支持这些功能的固件运行后同步，无需每次重新刷写。

详细的引脚、固件配置和串口调试说明见 固件文档。

开发与构建

浏览器调试

cd bridge\tray-app
npm run dev:web

打开 http://127.0.0.1:4173/。浏览器开发服务仅监听本机，使用 bridge/.web-dev-data/ 保存独立的开发配置和日志，并在需要时启动桥接服务。按 Ctrl+C 停止开发服务；桥接进程可能继续运行。浏览器模式与 Electron 模式的本地显示偏好各自保存。

测试与 Windows 打包

cd bridge\tray-app
npm test
npm run package:dir

打包后的程序位于 bridge/tray-app/dist/win-unpacked/。请保留完整目录，并将其放在项目目录内，使程序能够找到 bridge/server.mjs 和本地 firmware/include/secrets.h；当前产物不是独立安装包。运行桥接服务仍需要 Node.js。更多操作说明见 桌面端文档 和 桥接服务文档。

修改共享像素图案后，可从仓库根目录运行以下命令，重新生成固件头文件：

node firmware/scripts/generate-agent-icons.cjs

安全与隐私

• firmware/include/secrets.h、开发设置、日志、依赖和构建目录已列入 .gitignore。发布前仍应检查提交内容、截图、日志和历史记录是否包含账号信息或凭据。Git 忽略规则不会自动移除已经追踪或历史提交中的文件。
• 设备到桥接服务使用带 Bearer Token 的 HTTP，传输未加密。仅在可信局域网使用；不要把桥接端口直接暴露到公网。防火墙如需放行，应限制在可信的专用网络。
• 桥接服务对外提供活动名称、计数和汇总用量等状态，不转发提示词或回复正文。桌面端还会处理额度卡片中的账号标识和额度信息；这些信息可能出现在屏幕和截图中。
• 设备配网信息会保存在设备 EEPROM 中。转让或处理设备前，请自行清除设备上的配置和固件。

目录结构

bridge/
  server.mjs                 # Magpie 状态与用量桥接
  Start-MagpieBridge.ps1     # Windows 配置与启动脚本
  web-dev.mjs                # 本机浏览器开发服务
  tray-app/                  # Electron 托盘应用、预览与额度管理
firmware/
  src/main.cpp               # ESP8266 固件
  include/secrets.example.h  # 本地配置模板
  platformio.ini             # PlatformIO 构建和引脚配置

许可证与第三方素材

仓库目前尚未声明项目整体许可证；在项目所有者确定并添加许可证之前，请勿假定代码已获某种开源许可证授权。bridge/tray-app/assets/agent-icons/ 中保留的参考素材来自 LobeHub，来源和许可见该目录的 SOURCE.md 与 LICENSE.txt。相关品牌标识仍可能受各自权利人的商标政策约束。