Ganter Lab
登录 下载

工具，按范围列出

代理能调用的每一个工具都做什么，按声明它的那个能力开关分组。

以 Markdown 查看

工具名称是稳定的 snake_case 标识符。错误是结构化的、能照着办的：一次失败的调用会返回哪里出了错，外加一句提示，点名哪个工具或哪一步能把它修好，这样代理会自己纠正，而不是靠猜。“备份（管理）”这个范围开着的时候，服务器还会指示代理在改动配置之前先做一次配置备份。代理实际看得到下面哪几份清单，由每个范围开放什么决定。

Connector：读取

工具 作用
connector_browse 列出已配置的那棵树以及实时健康状态：Modbus RTU 按驱动、串行线路、设备、点位；其余每个驱动按驱动、设备、点位，每台设备的文件夹标在旁边。它会亮出那些点位别名（Driver.Folders….Device.Tag），也就是 tag_read、tag_write 和 Logic 表达式所用的那些。内置服务器停着的时候，别名是 null。
tag_read 按别名读一个点位的实时数值：设备层的原始值、走完转换链之后的工程值、质量，以及两个时间戳。

Connector：配置

工具 作用
driver_capabilities 列出应用能服务的每一个驱动，连同一台设备所需的连接字段、点位寻址模型（自由文本地址和/或定型字段）、是否支持设备发现及其参数、时序取值范围和支持的数值类型。这是代理在 device_upsert 或 tag_upsert 之前要读的那张地图。
serial_line_list 列出每一条已保存的 Modbus RTU 串行线路，已禁用的和空的也在内，带它稳定的 id 以及配置的、自动的和实际生效的时序值。
serial_line_upsert 创建一条 Modbus RTU 线路，或者按稳定 id 更新一条。名称和启用状态任何时候都能改；最小事务间隔在线路启用时也能改；串口、波特率、串行格式和响应超时只能在已保存的那条线路禁用着的时候改。
serial_line_delete 按稳定 id 删除一条线路。里面还有设备的线路会被拒绝，除非这次调用明确授权把每一台子设备和它们的点位一起删掉。
device_upsert 按“驱动 + 名称”创建或更新一台设备（驱动在创建之后不可变）。只有传进来的参数会变；连接字段随驱动而异；把一台设备移进文件夹会改写指向它旧点位地址的每一处引用。这次改动会立刻被调和进正在跑的服务器。
device_delete 删除一台设备和它的全部点位；立刻被调和进正在跑的服务器。
tag_upsert 在一台设备上创建或更新一个点位。寻址随驱动而异（自由文本地址和/或定型字段）；应答里会回显拼好的总线地址，以及给 tag_read 用的那个别名。数值点位还包含那些无效读数环节（NaN 处理方式和读取失败时的呈现方式）。
tag_delete 删除一个点位；立刻被调和。

Logic：读取

工具 作用
logic_browse 浏览带根的 Logic 地址空间，也就是每一条表达式所读的那棵点号树：System、Server、Connector、Variables、Alarms、Process 和 Assets。操作员建的文件夹是真正的地址层级；子点位带着它们的实时数值和质量。
logic_read 按点号地址读一个点位（例如 Variables.Setpoint），返回实时数值和质量。

Logic：配置

upsert 是部分更新的（没传的参数保持原值），而每一份合并之后的草稿都要过 Logic 编辑器所用的那同一套校验；无效的草稿会被驳回，什么都不会做一半。

工具 作用
variable_upsert 创建或更新一个变量：表达式（一条在地址空间之上书写的只读 JavaScript 表达式）或者内部存储值（一个可写、可选掉电保持的值）。名称是键，规整之后也是地址；folder 参数把它归档，并改写指向旧地址的每一处引用。
variable_delete 按路径删除一个变量，它保留下来的值也一起删。绑在它上面的通道会失去信号源。
action_upsert 创建或更新一个动作：一段 JavaScript 语句块，恰好有两种写入写法，内部存储值变量赋值和工程值点位写入。只做静态校验，保存时绝不执行。
action_delete 按名称删除一个动作。绑在它上面的触发器会空转。
trigger_upsert 创建或更新一个定时间隔触发器：每 intervalMs（最小 100）在逻辑队列上发出绑定的那个动作；上一次运行还没了结时到点的节拍会被跳过。动作绑定是松散的，按名称绑。
trigger_delete 删除一个触发器；绑定的那个动作不受影响。
alarm_upsert 创建或更新一条报警：一个 Bool 条件表达式、优先级（严重/高/中/低）、上升和下降延时、要不要确认，以及宣示方式。保存改动过的条件或时序会把正在跑的状态机重置。
alarm_delete 按路径删除一条报警；正在进行的宣示会先被清掉。
logic_folder_upsert 在某一节（Variables、Alarms、Actions、Triggers；最多三层）里创建、重命名或者重新归档一个用于组织的文件夹。对 Variables 和 Alarms 来说文件夹路径是地址的一部分，所以重命名和搬动会改写它下面的每一条表达式、每一段脚本、每一个条件和每一个仪表画面绑定。
logic_folder_delete 删除一个文件夹。它装着的东西一样都不会被毁掉：里面的项和子文件夹重新归到上一层，引用被改写；在去处撞名时这次删除被拒绝。

Logic：操作

这些全都搭那唯一一条逻辑队列，并以来源 MCP 记进日志。

工具 作用
variable_write 往一个内部存储值变量里写一个值（强制转换成它的输出类型，掉电保持时会被保留）。表达式变量是算出来的，拒绝写入。
tag_write 往一个可写点位里写一个工程值：倒着走完这个点位的转换链，强制转换成设备的类型，再写到设备上。只读的点位和只读的驱动会被拒绝，并说明原因。
action_run 在逻辑队列上跑一个动作，返回它的结果和用时。已禁用的动作根本不跑就失败。
alarm_ack 确认一条报警，也就是那次操作员响应；没有待处理项时它什么都不做。
alarm_ack_all 把每一条在等确认的报警都确认掉，作为一个逻辑队列项，每一次状态变化都记进日志。

服务器：读取

工具 作用
server_status 报告内置 OPC UA 服务器的健康状况：运行状态、运行时长、端点 URL、已连接的客户端会话，以及已配置地址空间的规模。

服务器：操作

工具 作用
server_start 启动内置 OPC UA 服务器，把当前配置落地。已经在跑时它什么都不做。
server_stop 优雅地停掉服务器。设备通信、点位读取和实时的 Logic 地址空间都会停下，直到它重新启动。
server_restart 先停再起，把配置重新落地一遍；一批改动之后的完整重载。
connector_refresh 把正在跑的服务器和已配置的那些设备增量调和（新增、移除、重建），不必整个重启；这是应用改动更轻的那条路。
device_discover 跑一个驱动的设备发现扫描，返回候选项及其点位，什么都不存下来。只有协议支持真扫描的驱动才参与；已经存在的候选项会被标出来。

日志：读取

工具 作用
logs_read 读程序范围内的实时日志流（就是事件控制台上的那一条），可按最低严重程度（调试/信息/警告/错误，默认“信息”）、区域（App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing）、组件和一段上下文子串筛选；返回最新的那些匹配项（默认 100 条，最多 500 条）。代理的动作记在 Agent 区域下面。
event_history_read 读那份能挺过重启的常驻运行事件时间线：报警状态变化、事件条目状态变化和联锁状态变化。可按种类（Alarm/Occurrence/Interlock）、一段闭区间的 UTC 时段和一个级别（报警优先级、事件条目严重程度或联锁状态变化）筛选；最新的在前，默认 100 条，最多 500 条。严格只读：什么都清不掉、也删不掉任何一条日志条目。

Process：读取

工具 作用
process_models 完整列出那些 Process 模型：通道、共享分组、带解析好的接线和运行状态的单元、流程、操作面板、配方、判定、事件条目，外加全局的报告模板库。这是代理在启动任何东西之前要读的那张地图。
process_runs 列出那些运行记录，最新的在前：id、名称、状态、结论、跑的是什么、谁启动的（Station/User/Automation/Agent）、时间和循环进度。可以只要活动中的运行，也可以限量（默认 50 条）。
process_run 按 id 读一次运行完整的冻结档案：快照、元数据、带采样计数的已判判据、事件条目的发生记录和事件、实际执行的配方写入、备注，以及冻结下来的报告和标签存档件及其打印尝试。可选地算出数据记录的行数和时间范围。
unit_status 报告一个单元的实时状态：它在不在运行（连同那次活动的运行），以及每个通道背后当前的工程值，只读不记录。

Process：配置

工具 作用
process_view_configure 恰好配置一个模型的一块操作面板：画在它旁边的图标，以及它出不出现在 View 页面上。Process 这个聚合里别的东西都不能通过 MCP 写；其余部分在 Process 页面上编辑。

Process：操作

由代理启动、结束或加备注的那些运行，把代理记为执行者，绝不会记成碰巧在试验台上登录着的那位操作员。

工具 作用
process_snapshot 在流程之外，对一个单元采一行数据记录。每一次调用都在历史里造出一次新的、已经完成的即时运行，不带判定（结论为 None）。
process_evaluate 采一行数据记录，并用一个判定去判它；造出一次已完成的即时运行，并返回它的结论。
process_recipe_apply 通过 Process 的写入出口和信号源锁，把一份即时配方对一个单元应用一次。它给设备下命令；不造出运行记录（那些写入会记进日志）。时序配方会被拒绝。
process_start 在一个单元上启动一次流程运行，用一个 JSON 对象填这个流程的元数据字段。必填元数据缺失或无效、单元已经在运行，或者共享通道的锁冲突，都会拒绝这次启动。返回新的运行 id。
process_stop 停掉一次正在跑的运行：收尾段、冻结的历史快照、算出来的结论。
process_hold 把一次运行的时序曲线暂停在最后一个设定值上；数据记录继续记。
process_resume 让一次已暂停运行的时序曲线继续。
process_abort 把一次运行从“运行中”或“已暂停”中止掉：收尾段照跑，快照照写，状态变成“已中止”，结论为不合格。
process_comment 往一次运行的文件里加一条带时间戳的备注：运行还活动时是一条时间线记录，结束之后是一条事后记录。
process_report 为一次已结束的运行生成（或重新生成）PDF 报告，并返回它的文件路径。从全局库里点名一份模板会盖过这个流程配置的那一份；两者都没有时，采用全章节的默认版式。运行还活动时被拒绝。
process_run_delete 永久删除一条已记录的运行：它在历史索引里的指针和那个按运行分的数据库文件。运行还活动时被拒绝；配置不受影响。

仪表画面：配置

工具 作用
dashboard_list 列出那些仪表画面（或者点名一个模型时，列出那个模型的画面）：网格尺寸、文件夹、图标、启动标志、按角色的可见性，以及每一个组件连同它的位置、层次和属性 JSON，外加每一张已保存的连线网络。它还返回组件种类的目录，带每一种的默认尺寸和默认属性包。
dashboard_upsert 按名称创建或更新一张仪表画面：网格尺寸（会让某个组件无处安放的缩小会被驳回）、可视化列表里的文件夹和图标、启动标志、全屏时状态栏的可见性，以及按角色的可见性。点名一个模型时，改的就是那个模型的画面。打开着的仪表画面页面会实时反映这次改动。
dashboard_delete 按名称删除一张仪表画面和它的组件；点名一个模型时，删的是那个模型的画面。
component_upsert 按种类添加一个组件（除非另有说明，放在第一个空闲格上，用这个种类的默认尺寸），或者按 id 更新一个。摆放必须落在网格里面；允许重叠，由 z 层次决定绘制顺序；属性 JSON 就是这个种类那个带类型的属性包。点名一个模型时，改的是那个模型的画面，所以在那里造出来的画面可以在这里排版。
component_delete 按 id 移除一个组件；点名一个模型时，改的是那个模型的画面。
connection_upsert 用一张带类型的连线网络把两个图元连接点连起来，从图元目录里解析出类型、角色和方向，和画布编辑器做的一模一样。两端解析出来的类型不同时会失败，除非明确允许一条未定义类型的连线；一个已经带着连线的锚点会被驳回。点名一个模型时，改的是那个模型的画面。
connection_delete 按 id 和期望的修订号移除一张连线网络，这样一次过期的删除会被驳回，而不是把一次更新的编辑盖掉；点名一个模型时，改的是那个模型的画面。

界面：自动操作

这些工具驾驭的是真正的应用窗口；它们的存在，是为了让代理能核实面向操作员的那个界面，而不是核实它的一个仿制品。交互是下发给活着的那个外壳的，所以正确的做法是每做一个手势就跟一次 ui_screenshot 去看效果，而含糊的匹配会以候选列表的形式返回，不会猜着点下去。

工具 作用
ui_state 报告外壳的状态：当前页面、可用的页面、主题、窗口尺寸和可见性，以及这个实例对外提供界面所用的那个本地回环地址。这是做别的事情之前那次定位调用。
ui_navigate 按页面的稳定名称激活外壳的某个页面，这个名称在每台工作站上都是英文：View、Process、Logic、Connector、Users、Validation、Events、Agent、Settings、Account。导航栏在工作站语言中显示的标签也同样接受。
ui_screenshot 把窗口按屏幕上显示的样子抓成一个 PNG 文件，并返回它的绝对路径；窗口收在托盘里时先把它还原。它也可以只抓一个具名的画面区域（一个唯一且可见的 data-doc-region 区域），而一个缺失、隐藏或含糊的区域会失败并列出可见的那些区域，不会悄悄退回去抓整个窗口。
ui_scroll 把当前页面的主滚动区滚到顶、滚到底或者按视口翻页，并返回偏移量，这样一个长页面能被扫一遍。
ui_set_theme 应用主题（跟随系统、浅色或深色）。它和标题栏的主题菜单一样会被保存下来，所以规矩的代理做完之后会把原来的值恢复回去。
ui_resize 按设备无关单位调整还原状态下窗口的大小，会被夹到窗口的最小值；用来审视紧凑布局很有用。
ui_click 点击文字匹配得上的那个可见按钮、超链接、勾选框或开关；勾选框和开关按它们的字段标签找到，结果会报告落在什么状态。含糊时返回那些候选项，而不是随便挑一个。
ui_set_text 往一个按字段标签认出来的文本框里写一个值，并像打字那样把绑定提交掉。
ui_select 按可见文字选中一项：用斜杠分隔的一条路径会走一棵树，沿途展开；单独一段也能匹配当前页面上的列表项、标签页、下拉框条目和表格行。

备份：管理

工具 作用
backup_create 在线给配置数据库拍一份快照到备份文件夹里，可以附一条说明。已记录的运行住在配置之外，备份和恢复都碰不到它们。
backup_list 列出那些配置备份（文件名、创建时间、大小、说明），外加任何已经排定的恢复。

这里刻意没有删除备份的工具：保留多久只由操作员在备份页面上说了算。

备份：恢复

工具 作用
backup_restore 排定一份备份，在下一次应用启动时替换掉当前配置。正在跑的应用里什么都不变，这个工具也绝不会去重启它；被替换掉的那份配置会先自动拍一份快照，而在重启之前操作员随时可以从“设置”里取消这次待执行的恢复。有记录正在进行时被拒绝。

设置：管理

工具 作用
settings_read 读工作站的显示和生命周期偏好：日期/时间/数字格式、小数位数、主题、关闭时收进托盘和崩溃报告这两个标志。
localization_set 更新那些显示偏好（部分更新：没传的参数保持原值）。只影响显示：存储、驱动 I/O 和记录始终使用固定区域性格式。
asset_list 列出那些用户素材（图像、图标、颜色），带 id、值和路径。
asset_import 从一个本地文件路径把一张 PNG/JPG 导入应用自有的素材库，并返回新的素材 id。字节是复制过去的，所以源文件之后可以移走。
symbol_validate 校验内联的图元内容（原始 SVG 或者一个 v2 包），什么都不存下来：把那次导入原样空跑一遍，返回错误、净化器的警告，以及认出了哪些东西的摘要。这个工具的说明里带着完整的可移植图元契约。
symbol_import 把内联的图元内容作为一个新的用户图元素材导入，并返回它的 id 和 user:<guid> 引用。它总是造一个新素材；撞名时自动加后缀。