instrumentControl

给 AI/Agent 用的仪器控制 MCP：把实验室仪器（示波器 ×3 / 信号源 ×2 / 万用表 / 电源 / 校准器） 统一封装为 VISA-SCPI 驱动库，再由 mcp_instruments/ 暴露成 MCP 工具， 让 AI 能安全地发现设备、查询状态、自动定标、测量、截屏、上下电。

设计前提：AI 会看手册、会截图，也会犯错。所以本项目把"命令不许猜、状态要回读、 危险动作要装门"做成代码里的硬约束，而不是文档里的建议。

AI 客户端（DSH / Codex / Claude / opencode …，经 MCP stdio）
        │
        ▼
mcp_instruments/server.py ─── 68 工具（64 设备专用 + 3 通用护栏 + 1 故障兜底），无状态连接+全局锁串行化
        │
        ├─▶ sds_control       Siglent SDS800X HD 示波器（波形/截图/测量/触发诊断/auto_scale）
        ├─▶ sdg_control       Siglent SDG2000X 信号源（BSWV 键值对）
        ├─▶ keysight_3446x    Keysight 34465A 万用表（CONF/MEAS/NPLC）
        ├─▶ dho_control       RIGOL DHO800/900 示波器
        ├─▶ rigol_scope       共享内核：DHO800/900 与 MHO900 命令集 97% 重合，一份实现
        ├─▶ mho_control       RIGOL MHO900 系列示波器（MHO934/954/984；截图走原生 PNG）
        ├─▶ dg832_control     RIGOL DG800 系列信号源（DG832 基准；保护联锁 + DC 快照 + 扫频）
        ├─▶ dh1766_control    DH1766 三路可编程电源（唯一 pip 可安装，自带手册/经验文档）
        └─▶ emoe_control      Emoe 校准器（骨架：仅发现 + `*IDN?`）
                 ▲
        common/ ─┴─ 统一发现 find_device（resource → hosts → VISA 列表 → CIDR 扫描）+ VisaClient

三条设计主线

1. 命令零猜测：每条 SCPI 都对照手册提取版落码；新增命令必过 TEST_SCRIPTS/common/audit_all_commands.py 审计。写操作固定三步 ——写入 → 查 SYST:ERR? → 回读比对（含容差比较与短格式/单位后缀兼容）。

2. 安全门写进代码（不只是文档约定）：

   • 复位/存储覆写类命令零暴露（MCP 通用写黑名单拦截 *RST/*SAV/*RCL/:SYST:RES|FACT|PRES）；

   • 远程锁定类命令禁止（SYST:REM/SYST:RWL/SYST:LOCK）——面板要留给现场操作；

   • 输出类操作必须声明当前拓扑/负载并通过校验： sdg_output(..., expect_load)、psu_output(..., expect_mode)、psu_power_cycle(..., confirm)；

   • 电源切换输出模式前强制"输出全关"（继电器联动，库内无条件拦截）；

   • 新设备零代码接入：instr_query / instr_write 通用护栏（写前 drain、写后查错、 自动回读、审计落盘、离线资源硬超时看门狗）。

3. 实测留痕与可回溯：所有实测输出落 TEST_DATA/<device>/（时间戳命名）， 测试脚本放 TEST_SCRIPTS/<device>/，注入/回归/审计均有留痕文件。

Related MCP server: scpi-mcp

快速开始

pip install -r requirements.txt          # pyvisa（+ 运行 MCP 服务器需 mcp 包）
pip install -e ./dh1766_control          # 电源库走 src 布局，可独立安装
python mcp_instruments/server.py         # 启动 MCP 服务器（stdio）

MCP 注册（示例，路径按需替换）：

// DSH: ~/.dsh/cordis.patch.yml 的 insert 列表；zcode: ~/.zcode/cli/config.json
{ "serverName": "instruments", "transport": "stdio",
  "command": "C:/Users/<you>/AppData/Local/Programs/Python/Python311/python.exe",
  "args": ["D:/MyProjects/AI/instrumentControl/mcp_instruments/server.py"] }

Windows 下必须用 python 全路径（WindowsApps 别名的 python 在部分客户端 spawn 时失败）。 AI 侧的使用指引见 skill instrument-mcp（工具选择决策树/参数语义/安全门/工作流）。

目录结构

设备与发现入口

地址不是固定资产：仪器 IP 随 DHCP/换网段变化、USB 换口会换资源串、串口 ASRL 编号会漂移。 所以这里只列"怎么找到它"，不列地址——地址由解析层在运行时确定，任何环节都不写死。

MCP 专用工具的 resource 参数默认省略：server 端按 显式入参 > 环境变量 INSTRUMENT_<KIND>_RES > 本机配置 devices.json > 上次成功缓存 > 自动发现 解析（实现见 common/resolver.py）。

配置本机默认地址

这套仪器在你机器上的地址可以写进配置文件（本机专用，不入库： %LOCALAPPDATA%\instrumentControl\devices.json）；不配也能用（自动发现 + 缓存）。

值的形态：一律是「完整 VISA 资源串」——TCPIP / USB / 串口 / GPIB 都一样， 不用区分传输方式，也不要自己拼 IP:端口：

TCPIP0::<host>::inst0::INSTR        # VXI-11（SDS/SDG/34465A）
TCPIP0::<host>::5555::SOCKET        # RIGOL raw（DHO）
TCPIP0::<host>::5025::SOCKET        # 大华 raw（DH1766）
USB0::0x0957::0xA007::<serial>::INSTR   # USB TMC（DH1766 也可走这条）
ASRL5::INSTR                        # 串口（编号会漂移）

为什么不允许手拼：协议/端口/参数因设备而异（DH1766 只认 raw 5025、DHO 只认 5555、 SDS/SDG/DMM 走 inst0、USB 还需 vid/pid/serial，另有 visa://<gw>/… 别名与 mDNS 名）， 拼错一个字段就是"对未知设备发 SCPI"。拼接只发生在两处：发现时的候选生成、 以及下面这个"裸 host 规范化"入口——两处都必须经 *IDN? 校验才落库。

python mcp_instruments/config_cli.py show                 # 看当前解析链与来源（不连设备）
python mcp_instruments/config_cli.py set sds "TCPIP0::<host>::inst0::INSTR"   # 完整串：直接写
python mcp_instruments/config_cli.py set sds 192.168.31.220                   # 裸 host：自动探测协议+校验身份后写入规范串
python mcp_instruments/config_cli.py autofill             # 把 instr_discover 的发现结果固化成配置
python mcp_instruments/config_cli.py clear sds            # 删条目 → 回落自动发现

换网段/换 USB 口后：先跑一次 instr_discover（发现结果会自动回写缓存）； 若地址已被 DHCP 分给别的设备，工具会在连接后核对 *IDN? 并拒绝操作（不会误发 SCPI）。

安全摘要（完整红线见 AGENTS.md）

• 输出/信号类操作（sdg_output/psu_output/psu_power_cycle）开与关都需 confirm=True： 它代表"已获得关断授权"（用户本轮明确要求，或明确声明独占使用），不是"我知道要关"。

• 操作电源前先查模式（psu_status/psu_mode）：TRAC 下 CH2 跟随 CH1 输出负压是正常现象。

• 禁止远程锁定与复位：SYST:REM/SYST:RWL/SYST:LOCK、*RST/:SYST:RES/:SYST:FACT 一律不可用。

• 测试脚本必须 try/finally 恢复被改设定并关闭输出。

• 示波器读数超屏会被钳制 → "有无波形/是否削顶"用截图判断，不要迷信设备测量值。

扩展新设备

1. instr_discover 定位资源 → 2. instr_query（只读）跑通手册里的查询 → 3. instr_write(confirm=True, readback_cmd=...) 验证写命令 → 4. 命令有了出处后 再落库（commands.py 常量 + 库方法 + 可选 MCP 工具），最后跑命令审计器防回归。

文档导航