instrument-devtool（硬件调试框架）

路径：packages/instrument-devtool
包名：instrument-devtool

瘦 Electron 调试壳，直连本地 device-agent，不依赖 @xichen-full-stack/admin、业务后端登录与权限。

与 Desktop 的分工：

包	定位
desktop	硬件操作 产品 框架（业务 UI、登录、RBAC）
instrument-devtool	硬件操作 调试 框架（命令联调、工作流、Agent 日志）
device-agent	本机设备服务（两边共用）
@xichen-full-stack/instrument	HTTP 客户端（两边共用）

架构

instrument-devtool (Electron)
  ├── main：自动 build/拉起/复用 device-agent，转发进程日志
  └── renderer：DeviceDebugger → @xichen-full-stack/instrument
                    ↓ HTTP
              device-agent (:19721)

开发

需要 .NET 8 SDK。

pnpm instrument-devtool:dev
# 或
pnpm --filter instrument-devtool dev

启动后会：

1. 增量 dotnet build DeviceAgent.Host（Debug）
2. 若 http://127.0.0.1:19721 已健康则复用，否则拉起子进程
3. 打开调试窗口（开发模式自动开 DevTools）

也可先手动起 Agent：

pnpm device-agent:dev
pnpm instrument-devtool:dev

开发端口：5175。

联调要点

1. 设备下拉里选对驱动：sample-flow-1（阅片机协议）或 stage-1（台架运动）
2. 先 连接（连接串留空则用 Agent appsettings 默认，如 SampleFlow 的 COM3）
3. 再发 start-normal / home 等命令；操作日志会显示 deviceId ← command → OK/FAIL

SampleFlow 命令发到非 sample-flow 设备会返回「未知命令」。

打包

安装包内嵌已 publish 的 device-agent（extraResources）。

pnpm instrument-devtool:build          # NSIS 安装包
pnpm instrument-devtool:build:unpack   # win-unpacked，方便本机试跑

等价：

pnpm device-agent:build
pnpm --filter instrument-devtool build

产物：packages/instrument-devtool/release/<version>/。

环境变量

变量	说明
VITE_DEVICE_AGENT_URL	覆盖默认 http://127.0.0.1:19721

能力摘要

• 设备列表 / 连接 / 状态 / 诊断
• Stage 运动与采集
• SampleFlow 常用命令 + 自定义 command/params
• 整机复位 POST /api/v1/workflows/instrument-reset
• Job 创建与控制（SSE）
• Agent 进程日志、一键重启

相关文档

• device-agent
• instrument 客户端
• Desktop（产品框架）