Industrial-AIOps Energy

industrial-aiops-energy — 能源版（变电站 / 公用事业）

English · 中文

Industrial-AIOps 的能源版，已拆分为独立仓库：用于变电站 / 公用事业遥控协议的只读 OT 连接器，基于 iaiops.core 构建。

• IEC 60870-5-104（c104）— RTU / 变电站遥测
• DNP3 / IEEE 1815（pydnp3）— 远动站监控
• IEC 61850 MMS（pyiec61850，仅限 Linux 的 wheel）— 变电站 IED 读取

本项目复用了基础包的共享治理（审计 / 预算 / 风险等级 / 撤销）、跨协议大脑（基于标准化 ISA-95/18.2 模型的数据流 / 告警 / OEE / 停机根因分析）以及 MCP 服务基础设施——本仓库仅新增三个能源连接器及其会话构建器和 MCP 工具。优先读取：不提供控制方向的写入操作。 当前版本：0.2.0（要求 iaiops>=0.29.0,<1.0；已针对 iaiops 0.31.0 进行测试）。在线提供：80 个工具，其中 75 个只读、0 个具有破坏性（此服务上挂载的能源连接器，以及基础包中的工具）。0.2.0 新增功能——此服务上的每次 MCP 调用都会记录审计信息，包含由哪个前端和哪个客户端发起（origin=mcp、客户端自报名称、每个连接一个 ID）；此前，此处的调用在审计记录中会显示为来源未知。升级说明： iaiops 0.29 会将这些字段纳入审计链哈希；如果旧版基础包验证由 0.29 写入的审计记录，会报告 row_hash mismatch——因此，所有共用一个 IAIOPS_HOME 的进程（此服务、iaiops-mcp、CLI、enterprise）都必须一起升级。基础包新增的 HTTP bearer-token 要求不适用于此处：此服务仅通过 stdio 通信。请参阅 CHANGELOG.md。此前在 0.1.12 中——此包现在会报告自身版本：此前连续八个版本都将 __version__ 硬编码为 0.1.3，MCP 握手也会将 SDK 的版本报告为此服务的版本；现在这两项均从已安装包的元数据中获取。此前在 0.1.11 中——三条监控路径首次全部受 CI 门禁约束，而实时测试一旦跳过，现在会导致构建失败，而不是通过。DNP3 此前是个例：pip install pydnp3 在任何当前 Linux 系统上都会失败，因此此仓库也继承了整个生态系统“无法在托管运行器上构建”的问题，tests/test_dnp3_live.py 在每次构建中都会跳过。它并非无法构建——opendnp3 可以顺利编译，2019 年的绑定层只需三项机械性修复，这些修复现已写入脚本 scripts/build_pydnp3.sh，并在真正的 GitHub 运行器上执行。此版本还继承了 iaiops 0.20.3 的两项治理修复（已提高版本固定要求）：调用失败后不再被审计为成功（此前每次失败还会因此错误地影响模式熔断器），并且失控防护现在可以检测到调用方不断重试被拒绝的操作。此前在 0.1.10 中——从基础包继承的一项安全修复：此版本镜像的三个出站工具（stream_publish、stream_publish_event、historian_push）会将凭据——NATS 身份验证令牌、TSDB 密码——以明文写入审计日志，而 audit_forward 会将该记录发送到配置的 SIEM。这些工具定义在 iaiops 中，因此此版本无法单独修复；版本固定要求提高至 iaiops>=0.20.2，并新增了一项契约测试：如果整个已注册工具接口再次包含未声明的凭据参数，构建就会失败。如果你曾向这些工具传入令牌或 historian 密码，请轮换这些凭据，并检查现有审计记录。能源连接器本身不接受任何凭据参数。此前在 0.1.9 中——每个工具都会提供 MCP ToolAnnotations 提示（readOnlyHint / destructiveHint / openWorldHint），并且这些提示由 @governed_tool 执行框架推导，而非手动编写，因此客户端无需解析 [READ]/[WRITE] 文档字符串标签，就能区分监控读取与会执行操作的工具。该版本在线提供 59 个工具，其中 55 个只读，且没有具有破坏性的工具——此版本不提供任何控制方向，该限制现在由测试强制执行，而不再只是写在文档中。这些只是提示，并非门禁：MCP 规范禁止将注解用于安全决策，执行保障仍由 @governed_tool 提供。基础包版本固定要求改为 iaiops>=0.20.1，以便从 mcp_server.hints 导入提示推导逻辑，而不再在此处重复定义。 此前 0.1.8 版——基础版中的 IAIOPS_READ_ONLY 门控已在 iaiops 0.19.0 中移除（读写授权由调用者决定——依据 Agent 判断 / 账户管理，而非 tap；每个工具均通过基础版 @governed_tool 管理框架接受治理和审计），因此此版本也将其移除。 此版本保留了 IAIOPS_NO_EGRESS=1 门控——这是数据外泄 / 隔离网环境维度的防护，会在注册时阻止数据外传工具出现在 list_tools() 中。此版本运行自己的 FastMCP 实例，因此门控接入了自己的 main()；否则，即使设置 IAIOPS_NO_EGRESS=1，从基础版脑中镜像过来的 historian_push、rca_narrate 和 stream_publish* 这一对工具仍会暴露。能源连接器本身仅用于监控，因此不受门控影响。参见 CHANGELOG.md。

此前 0.1.6 版——对三个只读连接器进行了一轮审计加固：DNP3 不再将离线的远方站报告为在线，也不会再返回不完整的完整性轮询数据库；IEC-61850 增加了有界连接 / 请求超时，并停止在失败时伪造 0.0 / 空成功结果；变电站分析器不再将单个断路器分闸称为“选择性跳闸”；测试会隔离 IAIOPS_HOME；基础版依赖下限提高至 iaiops>=0.14，以应用治理端点范围修复。参见 CHANGELOG.md §0.1.6。（0.1.5 验证了 IEC-104 监控路径——在 Linux 容器中进行了真实的 c104 客户端↔服务端往返测试，见 tests/test_iec104_live.py。） 物理 RTU / IED 仍未经过验证。 自 0.1.3 起，服务端拥有自己的 MCP 身份——iaiops-energy-mcp 运行专用的 FastMCP("iaiops-energy") 实例，附带能源专用说明（IEC-104 / DNP3 / IEC-61850、优先读取、不进行控制 / 操作），并将基础版跨协议脑工具镜像到该实例上——此外还包含一个版本专属技能（skills/iaiops-energy/SKILL.md，经过防漂移测试，与已注册工具的接口保持一致）以及协议一致性契约测试（每个工具都必须带有治理标记、[READ] 风险标签、Args: 小节，以及规范的 {error, hint} 错误格式；如果任何已注册工具缺少治理标记，服务端将拒绝启动）。

🧪 Beta 测试与共创

此软件包最需要的是变电站 RTU / IED / IEC-104 现场测试。 IEC-104、DNP3 和 IEC-61850 监控路径均已通过库级环回测试验证，现在三者都会在每次 CI 构建中运行——跳过测试会导致构建失败，而非通过。（自 2026-08-01 起：DNP3 的验证证据过去只有 2026-07-02 的一次手动运行，因为人们认为 pydnp3 无法在托管运行器上构建。这个判断有误——参见 scripts/build_pydnp3.sh。）真实 RTU / IED 硬件仍未经过验证。 如果你能在获授权的测试环境中，使用真实变电站设备运行 iaiops doctor，我们非常希望了解结果——经过验证的设备会在支持矩阵中按名称列出。请通过基础版仓库置顶议题报告结果（协议 + 设备型号 + iaiops doctor 输出）： 👉 industrial-aiops#28 — 征集现场测试合作伙伴（v0.10.0）

为什么单独建仓库

能源面向不同的客户群（公用事业 / 变电站），平台专属依赖更重（pyiec61850 是仅限 Linux 的 SWIG wheel；pydnp3 会构建原生扩展），且拥有自己的合规要求（中国《电力监控系统安全防护规定》）。拆分仓库可让基础版安装保持轻量。计划详见基础版仓库的 docs/ENERGY-SPINOUT.md。

安装

pip install iaiops-energy[energy]      # all three energy protocols
pip install iaiops-energy[iec104]      # just IEC-104

iaiops-energy 会自动引入 iaiops（共享核心）。

使用（MCP）

iaiops-energy-mcp                       # brain + energy tools over stdio

在 ~/.iaiops/config.yaml 中将目标指向你的变电站设备（protocol: iec104|dnp3|iec61850、host、port、common_address / unit_id）。

边缘部署与生态系统（原生边缘 / Margo）

与基础版软件包一样，能源版运行在经过加固、集中管理的边缘主机上，作为便携、受管控的边缘应用——映射到 Margo 的边缘互操作角色（不可变主机 · 合规编排器 · iaiops-energy = OT 领域应用），可部署为 OCI 托管容器（仅向变电站 RTU/IED 发起出站连接，不接受入站连接）。容器和 margo.org/v1-alpha1 应用描述骨架位于 deploy/margo/；完整的对齐说明及坦诚的差距分析见基础版仓库中的 docs/MARGO-ALIGNMENT.md。每次 PR 都会根据 Margo 发布的 margo.org/v1-alpha1 LinkML 架构验证描述符（CI 作业 margo-descriptor），并顺利通过——这仅代表结构有效，详见 deploy/margo/schema/PROVENANCE.md。

坦诚说明当前状态： 这是自然适配 Margo 的边缘应用，但尚未符合 Margo 标准——镜像构建、托管并签名的软件包，以及已发布的符合性结果均在路线图中，标记为 ⏳。在符合性结果发布之前，不会声称符合标准；上述架构验证也不代表正在朝此目标迈进：目前无法运行符合性测试套件，因为它尚不存在（margo 组织中还没有符合性仓库；截至 2026-01-15，首个 PR1 垂直切片仍在规划中）。

验证状态（如实说明）

与基础仓库采用相同的诚实标准。驱动程序的 codec / API surface 已通过真实库验证；使用 mock / monkeypatch 的 单元测试在 CI 中运行，无需硬件。有关协议晋级方式，请参阅基础仓库的 docs/PREVIEW-VERIFICATION.md 操作指南。

协议	状态	CI 覆盖范围	证据
DNP3 / IEEE 1815	已验证（监控路径）	✅ 每次推送都会运行 ¹	使用 pydnp3，针对运行中的 opendnp3 outstation 进行真实的主站↔outstation 往返测试：is_online() 会反映真实通道的 OnStateChange，而 integrity_poll()（Class 0/1/2/3）会按类型返回预置的二进制/模拟量/计数器数据库。参见 tests/test_dnp3_live.py（@pytest.mark.integration）。无需物理 RTU。
IEC 60870-5-104	已验证（监控路径）	✅ 每次推送都会运行	针对进程内 c104 服务进行真实的客户端↔服务端往返测试（tests/test_iec104_live.py + tests/iec104_server_harness.py，@pytest.mark.integration，可在 Linux 容器中通过）：iec104_connection_info 会发现预置站点，iec104_interrogate（总召唤 / C_IC）会返回带质量信息的预置 M_ME_NC_1 + M_SP_NA_1 点位，iec104_read_point 会读取测量值；无效 IOA 会返回 found=False，不会伪造值；服务端 ASDU 捕获证明从未发出控制 ASDU（C_SC / C_DC / C_SE）。c104 未提供 macOS wheel，因此测试在 macOS 上会跳过（在 CI / Linux 中运行）。无需物理 RTU。仅监控/读取。
IEC 61850 (MMS)	已验证（监控路径）	✅ 每次推送都会运行	使用 pyiec61850 的服务端 API 构建进程内 libiec61850 MMS 服务，并进行真实的客户端↔服务端 MMS 往返测试：iec61850_device_directory 会列出逻辑设备（并浏览其逻辑节点 / 数据对象），而 iec61850_read 会通过真实的 ISO-on-TCP 返回预置测量值（TotW.mag.f，FC MX）；无效引用会返回 MMS 数据访问错误，而不是伪造值。参见 tests/test_iec61850_live.py（@pytest.mark.integration，缺少 pyiec61850 / 其服务端 API 时会跳过）。无需物理 IED。仅读取/监控——控制 / GOOSE / SV 不在范围内。

¹ 现在，三个监控路径均由 CI 门禁控制；跳过测试会导致构建失败，而不是通过（no live protocol test may skip）。过去的说明是：“只有 IEC-104 由 CI 门禁控制；DNP3 和 IEC-61850 依赖 CI 之外的运行，而非绿色徽章。” 这曾经属实，但现在已不再如此。

DNP3 是最后完成 CI 门禁接入的协议，值得记录一下原因：这里的旧说明、CI 作业和本 README 几个月来一直重复着同一个错误结论：在任何当前版本的 Linux 上，pip install pydnp3 都会失败，因此人们认为它在托管运行器上无法构建。事实并非如此。opendnp3 本身可以顺利编译；老化的是 2019 年的绑定层。只需进行三项机械性修复，无需修改 opendnp3：

1. 必须安装 Python 头文件（python3-dev）——否则构建会因 Python.h: No such file or directory 而失败，这就是“无法构建”的表象；
2. 将 214 个随附头文件中的 #include <python2.7/Python.h> 改写为 <Python.h>；
3. 随附的 pybind11 版本早于 CPython 3.11（它会读取 3.11 已设为不透明的 PyFrameObject 内部结构），也早于 GCC 13（使用 std::uint16_t 却未包含 <cstdint>）——将其替换为 pybind11 v2.13.6。

scripts/build_pydnp3.sh 会应用这三项修复并验证导入。在双核机器上，从冷启动构建约需 3 分钟。经验教训适用于更多场景：“生态系统认为无法构建” 是需要验证的说法，而不是应该照单全收的结论。

DNP3 注意事项：仅支持只读/监控方向（不支持控制）。在长时间运行的解释器中，DNP3Manager.Shutdown() 可能会阻塞，因此连接器会限制拆卸耗时（_Pydnp3MasterAdapter.shutdown），测试则在短生命周期的子进程中执行往返操作。

许可证

MIT — © wei。属于厂商中立、受治理的 Industrial-AIOps 系列。