列出本 server 支持的工业协议及其能力。

返回每个协议的端口提示、地址模型、数据类型和品牌线索, Agent 可据此推断 "这个设备该用什么协议" 而无需问用户。 不确定协议名时先调用本工具。 不确定协议/端口时先调用 detect_device。

测试能否连上 PLC 并通信, 失败时给出层级归因。

reachable = 传输层可达 (TCP 已建立; 设备回异常响应也算在线)。 failure_class 取:

• connection_refused: 端口没人监听/网络不可达 (查网络与端口)

• timeout: 连接超时 (查网络路由/防火墙)

• connected_but_no_reply: TCP 通了但设备不回话 (查协议配置)

• exception_response: 设备回异常码 (查 unit/寄存器配置, 带 exception_code) 典型用法: 设备"读不到数据"时先调本工具分层定位, 再决定下一步。

从 PLC 读取数据区并按数据类型解释。

address/count 为通用地址与数量, 语义由协议决定:

• Modbus: address 为 0 基寄存器地址, count 为寄存器个数

• FINS: address 为字地址, count 为字数

• MELSEC: address 为起始编号, count 为点数 (位软元件按 16 点/字)

• S7: address 为字节地址, count 为字节数 (count=4 + uint16 → 2 个值)

datatype 取 uint16/int16/float32, None 返回原始 16 位值 + 所有常见数据类型的多解释 (interpretations 字段), 便于 Agent 识别正确的数据类型。 byteorder 仅影响 float32 寄存器对顺序 (big=ABCD, little=DCBA)。

options: 协议特有参数, 由各协议 adapter 自行定义与校验。 用 list_protocols 查看每个协议的 read_options 说明。

综合观测给出结构化的故障候选结论 (确定性规则, 不编故事)。

三种证据可任意组合 (至少给一种):

• frame_hex: 一帧报文 hex (解析 + 校验 + 规则匹配)

• log_snippet: 通信日志文本, 自动提取其中的 hex 帧逐帧解析

• host + port: 连上设备做一次探测, 把探测归因纳入推理 返回 DiagnosticReport: candidates 按 confidence 降序, 每条含 symptom/root_cause/evidence(证据链)/suggested_action/next_tools; evidence 与 observations 保留原始观测供复核。空 candidates = 知识库未覆盖, 不硬凑结论。

把一帧报文 hex 逐字段结构化解析 (不需要连接设备)。

每个字段带 byte_offset 与 raw_hex 证据; 支持正常请求/响应与异常 响应帧; 畸形帧不抛错, 而是尽量解析并在 errors 里说明哪里坏 —— "解析失败的方式"本身是诊断证据。 direction: "auto" 按帧结构判别, 也可显式传 "req" / "resp"。 frame_format (仅 melsec): "3e_binary" / "3e_ascii" / "4e_binary" / "4e_ascii"。

• modbus: 异常帧/非 12 字节按响应, 12 字节按请求 (fc05/06 的响应 与请求逐字节相同, 任一解释一致)

• fins: TCP 命令 0x00 按请求 / 0x01、0x02 按响应; 0x04 按 FINS ICF bit6 判别 (响应置位)

• melsec: 副头部 50 00/54 00 按请求, D0 00/D4 00 按响应 (ASCII 帧 "5000"/"5400"/"D000"/"D400" 同理)

• s7: rosctr=0x01 (Job) 按请求, 0x03 (Ack_Data) 按响应; 显式传 direction 时按传入值

对一帧报文跑规范校验清单, 逐项 pass/fail (不需要连接设备)。

Modbus TCP: MBAP 长度一致性、协议号、功能码、unit 范围、PDU 自洽、数量/地址边界、异常码 (Modbus TCP 无 CRC, RTU 才有)。 FINS/TCP: magic、TCP 长度自洽、TCP 命令合法、error 字段、 FINS 端结码、载荷完整性。 MELSEC 3E: 副头部、数据长度自洽、命令/软元件代码、结束代码。 direction 取 req 或 resp。

解析 Wireshark 导出 pcap: 按 TCP 流聚合载荷 -> 按协议切帧 -> 逐帧 parse_auto。

每个流返回完整帧序列 (带结构化解析) 与尾部半帧 (partial, 截断也是 诊断信息)。protocol 缺省时按"完整帧数最多的协议"自动判别。 需要可选依赖 scapy (uv sync --extra eval)。大批量帧场景比逐条 frame_hex 高效得多。

起钓鱼模式监听: 待测设备只能当 client 时, 立假 server 钓出它的帧行为。

mode 三档: record_only=只收帧不回复 (纯被动) / respond_normal=对读类 请求回最小"正常响应" (数据恒 0, 目的只是让设备继续吐帧, 非通用模拟器) / inject_errors=正常回帧但按 faults 列表轮转注入确定性故障 (评测语料 生产 + 诊断引擎回归)。 faults (仅 inject_errors): modbus 可选 exception/bad_length/truncate, fins/melsec 可选 end_code/bad_length, 全协议通用 garbage。 收下的帧用 get_listener_frames 取, 再喂 parse_frame/diagnose。 port=0 由系统分配, 返回实际端口。建议收满样本后 stop_listener, 并提醒用户恢复设备原配置 (BUILD.md Skill 节)。

停掉指定端口的监听, 返回收/发帧统计。

取监听收下的帧 (direction/peer/frame_hex), 供 parse_frame/diagnose 分析。

起透明代理: 上位机 → 代理 → 真实 PLC, 透传同时按协议分帧录制双向帧。

现场联调时把上位机目标地址改成本代理, 无需 Wireshark 即可拿到全部 交互帧 (get_proxy_frames), 再喂 parse_frame/diagnose 做在线分析。 protocol 当前支持 modbus/fins/melsec (S7 TPKT 分帧暂不支持); listen_port=0 由系统分配。代理是诊断设施: 只透传与录制, 不改写帧。

停掉指定端口的代理, 返回录制统计 (c2s/s2c 帧数)。

取代理录制的双向透传帧 (direction: c2s=上位机→PLC, s2c=PLC→上位机)。

设备自动识别: 给定 host 自动扫端口并判定协议 (v0.4, 全程只读)。

流程: 并发扫描候选端口 (缺省 102/502/2000/44818/5007/6000/9600/9601, 单端口连接预算 0.5s) -> 开放端口并发跑四协议 probe 指纹 (单协议 预算 timeout_ms/1000, 缺省 0.8s) -> high 候选按协议做一次最小读 验证 (deep=True 缺省; 成功升级 verified, 失败留痕保持 high; deep=False 跳过验证读)。 只读保证: 全程只发握手帧 + 最小读帧, 不写任何数据; 且识别 ≠ 可访问 —— 例如 S7 PUT/GET 被关闭时识别照样成功, 读 DB 仍可能失败。 返回 DetectResult: candidates 按置信度降序 (同级先验匹配端口优先, next_step 可直接作为 plc_read 调用), unknown_services 为开放但 四协议都不认识的端口 (可用 start_listener 钓帧分析)。