鲲鹏恒控 · 程序集使用手册
这本手册是写给谁的
写给第一次接触鲲鹏恒控后端代码的人。你可能是：
- 要接一台 PLC、把现场数据采上来的工程师
- 要给某个冷门协议写驱动的开发者
- 想把组态能力嵌进自己程序、或者用脚本自动化改工程的集成商
- 接手这套代码、想先搞明白"它内部是怎么搭起来的"的新同事
不需要你事先懂这套架构。 每个术语第一次出现时都会用大白话解释一遍，每一章都先说"这是干什么用的、什么时候你会需要它"，然后才讲怎么调用。
这套后端由什么组成
一句话：15 个 .NET 程序集，从下往上四层，上层用下层、下层不认识上层。
┌─ 宿主 / 集成层 ──────────────────────────────────────────────┐
│ Hmi.Shell(WPF 壳) Hmi.HostBridge(前后端消息路由) │
│ Hmi.Mcp.Host(给外部 AI 的 MCP 服务) │
│ Hmi.RuntimeCore.Host(运行内核进程) Hmi.Supervisor(进程监督) │
├─ 组合层 ─────────────────────────────────────────────────────┤
│ Hmi.Automation(组态+感知统一 API) Hmi.Backend(运行数据引擎) │
│ Hmi.ScriptRuntime(运行时脚本宿主) │
├─ 领域库层 ───────────────────────────────────────────────────┤
│ Hmi.Project(工程模型) Hmi.Drivers(采集框架) │
│ Hmi.Scripting(脚本引擎) Hmi.Historian(历史库) │
│ Hmi.Alarms(报警引擎) Hmi.Security(账号权限) │
├─ 内核层 ─────────────────────────────────────────────────────┤
│ Hmi.Core(实时库 + 点模型 + 变化分发) │
└──────────────────────────────────────────────────────────────┘
目标框架 net8.0(WPF 壳 Hmi.Shell 为 net8.0-windows),解决方案 FangLikong.sln,
源码在 src/,测试在 tests/。
两个"独立户":
Hmi.Security和Hmi.Supervisor不依赖任何Hmi.*,可以单独摘出来用。
六篇导航
| 篇 | 讲什么 | 建议什么时候看 |
|---|---|---|
| 1 入门 | 整套东西怎么跑起来的、术语表、按目标选路线 | 先看这篇,尤其第 01 章 |
| 2 内核层 | 数据放在哪:实时库、点/通道/设备、工程文件 | 要读实时值、要读写工程文件 |
| 3 采集层 | 数据怎么进来:驱动原理、内置协议、自己写插件 | 要接 PLC、要支持新协议 |
| 4 运行层 | 数据怎么流转:数据引擎、脚本、历史、报警 | 要让工程真正跑起来 |
| 5 集成层 | 给外部程序用:自动化 API、消息路由、MCP | 要把能力嵌进自己的程序或 AI |
| 6 安全与附录 | 账号权限、程序集速查表、常见问题 | 做权限、或者查不到东西时 |
逐章清单
第 1 篇 · 入门
| 章 | 标题 | 一句话 |
|---|---|---|
| 01 | 这套软件是怎么跑起来的 | 组态器、工程文件、运行内核、PLC 之间的关系 |
| 02 | 名词表 | 程序集、实时库、点、通道、驱动、宿主……都什么意思 |
| 03 | 我该从哪一章开始看 | 按你的目标给出四条阅读路线 |
第 2 篇 · 内核层：数据存在哪
| 章 | 标题 | 一句话 |
|---|---|---|
| 04 | 实时库：内存里的点值表 | Hmi.Core 的读写与订阅 |
| 05 | 点、通道、设备：数据从哪来 | 三个核心概念的关系与字段 |
| 06 | 工程文件与加载保存 | Hmi.Project 与磁盘上的目录结构 |
第 3 篇 · 采集层：数据怎么进来
| 章 | 标题 | 一句话 |
|---|---|---|
| 07 | 驱动是怎么工作的 | 采集循环、块读规划、重连与超时 |
| 08 | 内置协议怎么用 | 8 种内置协议的地址写法与连接参数 |
| 09 | 写一个自己的协议插件 | 从零到能加载的完整流程 |
第 4 篇 · 运行层：数据怎么流转
| 章 | 标题 | 一句话 |
|---|---|---|
| 10 | 运行数据引擎 | Hmi.Backend 把工程跑起来 |
| 11 | 脚本引擎：从代码到运行 | 脚本怎么被编译、怎么被拦住危险操作 |
| 12 | 脚本运行时与脚本形态 | 全局/画面/事件/周期脚本怎么挂、能写什么 |
| 13 | 脚本函数库速查 | 15 个函数库、185 个函数,每个干什么 |
| 14 | 历史库与报警引擎 | 什么时候记、怎么查、报警怎么流转 |
第 5 篇 · 集成层：给外部程序用
| 章 | 标题 | 一句话 |
|---|---|---|
| 15 | 自动化 API 总览 | 最省事的入口,一次拿到全部组态能力 |
| 16 | 自动化 API 方法速查 | 按功能分组的完整方法清单 |
| 17 | 宿主、进程与壳 | 消息路由、运行内核进程、进程监督、WPF 壳 |
| 18 | MCP 服务器 | 让外部 AI 连进来改工程 |
第 6 篇 · 安全与附录
| 章 | 标题 | 一句话 |
|---|---|---|
| 19 | 账号、角色与权限 | Hmi.Security 的模型与 API |
| 20 | 程序集速查表 | 一页看全 15 个程序集 |
| 21 | 常见问题与坑 | 踩过的坑集中放这里 |
三条典型集成路线
不知道从哪下手?看这三条里有没有和你像的:
路线 A —— 我只想在自己的程序里读工程、改组态,不碰运行
→ 只用 Hmi.Automation。ProjectAutomation.Open(工程目录) 拿到统一 API,组态类方法改工程、感知类方法只读查询,Save() 落盘。最省事的一条。见 第 15 章。
路线 B —— 我要把工程真正跑起来,连 PLC、出实时值
→ 用 Hmi.Backend.RuntimeHost 建实时库 + 跑采集循环;要历史、报警、脚本再叠 RuntimeDataServices.Compose(...)。见 第 10 章和第 14 章。
路线 C —— 我要给外部 AI(Claude / Cursor 之类)开一个组态入口
→ 直接跑 Hmi.Mcp.Host 这个 exe,参数指向工程目录,支持 stdio 和 http 两种传输。见 第 18 章。
一条不可逾越的边界
Hmi.Automation / MCP / HostBridge 对外只暴露两件事:
- 组态 —— 改工程文件里的 JSON,可逆,随时能撤销
- 感知 —— 只读查询,绝不产生副作用
绝不暴露运行态写值、PLC 下发、设备启停。 即便在脚本运行时,RuntimeWriteGate 也只放行内部软件变量,通道点和 PLC 点的脚本侧写入一律被拦下。
把这条边界记牢 —— 它贯穿所有上层程序集,也是这套软件敢把接口开放给外部 AI 的底气。
本手册对应源码版本见仓库
docs/更新日志.md。发现手册和代码对不上,以代码为准,并回头修手册。