plctap 0.1.0__tar.gz

plctap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --extra eval
+      - run: uv run pytest -q

plctap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+# 打 v* 标签即触发: git tag v0.1.0 && git push origin v0.1.0
+# 用 PyPI Trusted Publishing (OIDC), GitHub Actions 内不需要任何 token/密码;
+# 前置一次性设置: PyPI 项目设置里启用 trusted publishing (见 docs/PUBLISH.md)
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write  # OIDC 签发发布凭证
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

plctap-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# 运行时产物
+*.jsonl
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# 本地调试杂物
+.tmp/
+hangdiag.log
+issue-evidence/
+
+# eval 生成物 (可再生)
+eval/prompts.jsonl
+eval/results_baseline.json

plctap-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# plctap — Agent-PLC MCP Server 架构设计（ARCHITECTURE.md）
+
+> 配合 PLAN.md v2 与 BUILD.md 使用｜2026-09-03
+
+## 1. 分层架构总览
+
+```
+MCP 客户端 (Claude Desktop / Codex / Cursor)
+        │ MCP stdio
+MCP Server (FastMCP)
+  ├─ 工具注册表（按配置条件注册，写工具默认缺席）
+  ├─ 安全闸门 + 审计日志(JSONL)
+  ├─ 连接管理器（连接池/空闲回收/目标级锁）
+  ├─ 协议适配器（插件式: Modbus / FINS / MELSEC）
+  ├─ Codec 纯函数层 (parse / validate / build)
+  └─ 诊断引擎（规则引擎 + YAML 知识库, 纯确定性输出）
+        │ TCP
+真实 PLC / ProtoForge 模拟器
+评测 harness（离线独立进程, 直连 codec, 不走 MCP）
+```
+
+## 2. 六个关键架构决策（ADR 摘要，2026-09-03 已全部确认）
+
+### D1 会话模型：无状态参数 + 内部透明连接池
+- 工具每次携带 host/port，不暴露 connect()/session_id
+- 连接池 key = (protocol, host, port, unit)；空闲 30s 回收；池上限可配
+- FINS/TCP 节点号握手等细节封装在适配器内部
+- 每目标地址互斥锁，防并发写竞争
+- 理由：LLM 管理 session id 极易出错（遗忘/编造/过期）
+
+### D2 Codec 纯函数化（可测试性根基）
+- parse(hex)->ParseResult、validate(frame)->CheckList、build(params)->hex 均为纯函数
+- 适配器只做网络 I/O；评测/单测/故障注入只测纯函数，CI 毫秒级
+- ParseResult 每字段带 byte offset 与原始 hex 片段，供 diagnose 引用证据
+
+### D3 异步 I/O：纯 asyncio
+- 适配器用 asyncio.open_connection + asyncio.wait_for 超时
+- 不依赖同步协议库（pymodbus 等仅作行为对齐参考）
+- 与 MCP 工具超时语义天然对齐；支持并发探测多设备
+
+### D4 诊断引擎纯确定性
+- 规则引擎 + kb.yaml，输出结构化候选: {symptom, evidence[], confidence, suggested_action}
+- 不生成自然语言；叙述由 Agent + Skill 层完成
+- 输出可被 Agent 用于继续调用 probe_device 验证 → 诊断→探测→确认工具链
+
+### D5 安全闸门：注册层控制 + 全量审计（方案C，已确认）
+- allow_write=false 时写类工具根本不注册（Agent 不可见）
+- 开启后每次写/发送写 JSONL 审计: {ts, tool, target, frame_hex, caller}
+- 配套 MCP 审批弹窗（config.toml: default_tools_approval_mode / per-tool approval_mode）
+
+## 3. 目录结构
+
+```
+plctap/
+├── pyproject.toml              # 入口: plctap (console script)
+├── src/plctap/
+│   ├── server.py               # FastMCP app + 条件注册
+│   ├── config.py               # allow_write / 池大小 / 超时
+│   ├── safety.py               # 闸门 + 审计日志
+│   ├── conn/
+│   │   └── manager.py          # 连接池 + 目标级锁
+│   ├── protocols/
+│   │   ├── base.py             # ProtocolAdapter ABC + 注册表
+│   │   ├── modbus/{adapter.py, codec.py}
+│   │   ├── fins/{adapter.py, codec.py}
+│   │   └── melsec/{adapter.py, codec.py}
+│   ├── diag/
+│   │   ├── rules.py            # 确定性规则引擎
+│   │   ├── kb.yaml             # 50+ 故障知识库
+│   │   └── report.py           # 结构化诊断报告模型
+│   └── models.py               # ParseResult / ReadResult / DiagnosticReport
+├── skill/SKILL.md              # 方法论指令层
+├── eval/
+│   ├── corpus/                 # 分层评测集 (yaml)
+│   └── benchmark.py            # vs 裸模型对比
+├── tests/                      # 纯函数单测 + MCP 冒烟测试
+└── README.md
+```
+
+## 4. 核心数据模型（Pydantic）
+
+```python
+class ParseResult(BaseModel):
+    protocol: str
+    direction: "req" | "resp"
+    fields: list[Field]          # name, value, raw_hex, byte_offset, note
+    valid: bool
+
+class ReadResult(BaseModel):
+    target: Target               # protocol/host/port/unit
+    request_frame: str           # hex, 便于调试
+    raw_registers: list[int]
+    interpreted: Any             # 按 datatype/byteorder 解释
+    elapsed_ms: int
+
+class ProbeResult(BaseModel):
+    reachable: bool
+    failure_class: "connection_refused" | "timeout" | \
+                   "connected_but_no_reply" | "exception_response" | None
+    exception_code: int | None
+    layer_hint: "connectivity" | "protocol" | "application"
+
+class DiagnosticReport(BaseModel):
+    candidates: list[Candidate]  # symptom/evidence/confidence/suggested_action
+    next_tools: list[str]        # 建议Agent接下来调用的工具
+```
+
+## 5. 数据流走查
+
+### 场景 A: "读 40001 开始 10 个寄存器"
+plc_read(modbus, host, 502, addr=0, count=10, datatype=float32)
+→ 连接池取/建 TCP → codec.build 请求帧 → 发送 → codec.parse 响应
+→ 字节序解释 → ReadResult。一次工具调用完成。
+
+### 场景 B: "192.168.1.10 读不到数据"
+probe_device → timeout → (Skill 指引) 查网络层
+端口通 → plc_read → 异常码 0x02 → diagnose 匹配 KB
+→ "地址越界, 建议先确认寄存器区范围" → Agent 转述。
+三层分类（连接/协议/应用）对应三条工具路径。
+
+## 6. 协议适配器接口
+
+```python
+class ProtocolAdapter(ABC):
+    async def probe(self, target) -> ProbeResult
+    async def read(self, target, address, count, datatype) -> ReadResult
+    async def write(self, target, address, values) -> WriteResult   # 闸门后注册
+    async def send_raw(self, target, frame_hex) -> RawExchange
+    # codec 纯函数: adapter.codec.parse / validate / build
+```
+新协议 = 新目录 + 注册表登记，server.py 不改（插件式扩展点）。
+
+## 7. 配置与部署
+
+```toml
+# ~/.codex/config.toml 或 claude_desktop_config.json
+[plctap]
+allow_write = false          # 默认
+pool_max_per_target = 2
+idle_timeout_sec = 30
+default_timeout_ms = 2000
+audit_log = "~/.plctap/audit.jsonl"
+```
+分发: pipx/uvx 安装；Claude Desktop / Codex 各给一段配置样例；后续可加 streamable_http 远程模式。
+
+### D6 评测设计：分层难度 + 同模型双跑（已确认）
+- 五档难度: 单帧ModbusTCP / RTU CRC / FINS / 批量日志 / 主动探测
+- 同一批帧: 裸模型问答 vs 挂MCP工具, 同一模型消融, 分层报准确率
+- 不做竞品准确率对比; README 放功能覆盖对比表即可
+
+### D7 I/O 模型: 纯 asyncio（已确认, 随技术栈D3=Python+FastMCP）
+
+## 8. 演进路线
+- v0.1 (M1): Modbus TCP probe+read+parse/validate, ProtoForge 实测
+- v0.2 (M2): +FINS/MELSEC + 诊断引擎 + 分层评测对比表
+- v0.3 (M3): +写闸门 + parse_pcap + Skill → 发布 v1.0
+- v2.0: S7(snap7) / 数据类型自动推断 / HTTP 远程部署
+## 9. 工业协议层角色定位（2026-09-03 补充）
+
+两个"server"概念区分：
+- MCP 协议层: 永远是 Server（向 Claude/Codex 暴露工具）
+- 工业协议层: v1 只做 Client/主站（主动连 PLC）
+
+"被连接"能力的演进（不做通用模拟器, 那是 ProtoForge 的地盘, 用集成代替重写）:
+- v1   : 仅 Client/主站
+- v1.1 : 服务端诊断套件(共享监听基础设施, codec.parse/build 反向复用):
+           start_proxy  诊断代理: 上位机→代理→真实PLC 透明转发+录制
+                        → 排查"上位机说没回 / PLC 说没发"扯皮场景
+           start_listener 钓鱼模式(实习真实痛点背书):
+                        待测设备只能当client时, 立可编程假server钓出其帧行为
+                        mode: record_only / respond_normal / respond_scripted / inject_errors
+                        → 捕获畸形握手/错误字节序/重发风暴; 可按请求写入数控(CNC)
+                        → 知识库新增 client 侧故障模式类; 面试零硬件双向演示
+- 永不做: 独立完整从站模拟器；ProtoForge 作为开发/测试依赖引入
+
+
+
+

plctap-0.1.0/BUILD.md

@@ -0,0 +1,121 @@
+> **注意（2026-09-03）**：项目 plctap 已重新定位为「Agent-PLC 连接器」（见 PLAN.md v2）。工具优先级调整为：M1 先做 `probe_device` + `plc_read`（Modbus TCP 读写闭环），诊断层工具顺延到 M2；BUILD.md 第 2 节的解析/诊断工具设计仍有效，连接层工具设计以 PLAN.md 第 3 节为准。
+# 工业协议诊断 MCP 实施指南（BUILD.md）
+
+> 配合 PLAN.md 使用｜形态已定：MCP Server 为核心 + 薄 Skill 指令层｜测试台架：ProtoForge
+
+## 0. 形态决策（为什么）
+
+- `parse_frame` / `validate_frame` 是确定性字节级操作 → 必须是代码工具 → **MCP Server**
+- 诊断方法论（抓包→比对→排除）是流程知识 → **Skill（纯指令，SKILL.md）**
+- 评测卖点 = 工具化解析 vs 模型口算的准确率差 → 没有工具层就没有这个对比
+
+## 1. 仓库结构（建议）
+
+```
+proto-diag-mcp/
+├── pyproject.toml              # 依赖: fastmcp, pymodbus(参考), pytest
+├── src/proto_diag/
+│   ├── server.py               # FastMCP 入口, 注册 tools/resources/prompts
+│   ├── protocols/
+│   │   ├── modbus/             # parser.py, rules.py, spec.md
+│   │   ├── fins/               # parser.py, rules.py, spec.md
+│   │   └── melsec/             # parser.py, rules.py, spec.md
+│   ├── diagnose/
+│   │   ├── rules.py            # 规则引擎(确定性检查)
+│   │   └── kb.yaml             # 50+ 故障知识库(症状→根因→修复)
+│   └── models.py               # ParseResult / DiagnosticReport Pydantic 模型
+├── skill/                      # 薄 Skill 层
+│   └── SKILL.md                # 诊断方法论, 指令 only
+├── eval/
+│   ├── corpus/                 # 评测集: hex + 期望标签 (yaml)
+│   └── benchmark.py            # 工具诊断 vs 裸模型问答 对比
+├── tests/
+└── README.md
+```
+
+## 2. MCP 工具设计
+
+### Tools（都返回结构化 JSON）
+- `parse_frame(protocol: "modbus"|"fins"|"melsec", hex: str)` → 逐字段拆解（事务号/单元号/功能码/地址/数量/数据/CRC 等），每个字段带 byte offset 和原始 hex 片段
+- `validate_frame(protocol, hex)` → 校验清单逐项 pass/fail：CRC/LRC、MBAP 长度一致性、功能码合法、寄存器地址边界、FINS 目标节点、MC 帧尾代码
+- `diagnose(protocol, hex | log_snippet, context?)` → parse+validate 结果 → 规则引擎匹配知识库 → 输出结构化报告：`{severity, symptom, root_cause, evidence, fix_suggestion, next_steps}`
+- `list_protocols()` → 能力自述（Agent 自发现用）
+
+### Resources
+- `spec://modbus`、`spec://fins`、`spec://melsec` 脱敏协议速查（提炼，不整抄手册）
+
+### Prompts
+- `diagnostic_playbook`：抓包→比对→排除法完整流程
+
+## 3. 解析器实现要点（M1）
+
+- **纯手写解析，不依赖协议库做解析**（库只做行为对齐参考）。原因：库是客户端视角，你要的是无状态帧解析，且求职需要展示"从协议规范手写解析器"
+- Modbus TCP：MBAP 头 7B + PDU；注意异常响应帧（功能码 |0x80 + 异常码）单独处理
+- FINS TCP：FINS/TCP 握手帧(0x46494E53) 与 FINS 帧(TC/RS 头)区分；命令码 0101/0102/0103…
+- MELSEC 3E：副头部 + 网络号/PC 号 + 监视定时器 + 结束代码；注意二进制 vs ASCII 模式先只做二进制
+- 字节序：Modbus 大端，FINS 大端，MC 二进制小端——这些差异本身就是诊断知识库素材
+- 每个协议:先写固定样例的单元测试(pytest + 参数化)，再接 FastMCP
+
+## 4. 用 ProtoForge 生产评测集（M2 核心技巧）
+
+1. `git clone` ProtoForge，跑起 modbus/fins/mc 模拟器（MIT 协议，实现可学习参考）
+2. 正常流量：客户端轮询读写 → 录制基线报文
+3. **故障注入清单**（评测集来源，每类 ≥5 条）：
+   - CRC 篡改 1 bit
+   - MBAP/副头部长度字段与实际不符
+   - 事务号乱序 / 复用
+   - 寄存器地址越界（读 4x 段用 0x 前缀地址）
+   - 字节序调换（大端↔小端）
+   - 异常响应帧（Illegal Address / Illegal Function / Gateway Target Failed）
+   - 连接竞态：半包、粘包、TCP RST 中断
+   - FINS:节点号重复、TC 帧超时
+   - MC:结束代码非 0（映射到具体含义）
+3.5 **client 侧故障类（钓鱼模式产出，源自实习场景）**：设备连假 server 后钓出的——畸形握手帧、错误字节序请求、超时重发风暴、非法功能码请求、半包粘包的 client 拆帧错误
+4. 每条样本标注：`{hex, protocol, expected_symptom, expected_root_cause}` → eval/corpus/*.yaml
+5. benchmark.py 双跑：本 MCP 工具诊断 vs 同一批帧直接喂裸模型问答 → 出对比表(README 核心卖点)
+
+## 5. Skill 写法（M3，薄）
+
+```
+skill/SKILL.md
+---
+name: proto-diag
+description: 工业协议(Modbus/FINS/MELSEC)报文诊断。当用户给出 hex 报文、
+  抓包片段、PLC 通信异常日志，或要求排查上位机/网关通信故障时触发。
+---
+诊断流程(严格按序):
+1. 判断协议，无法判断时问用户或用 parse_frame 各试一次看哪个结构成立
+2. parse_frame → 读结构化字段
+3. validate_frame → 逐项看 fail 项
+4. 结合上下文(设备型号/网络拓扑)读 diagnose 报告
+5. 给出修复建议后，提醒用户复测并回报新报文，进入闭环
+
+钓鱼模式(设备只能当 client 时):
+- start_listener(protocol, port, mode) 起假 server → 让用户把设备指向该端口
+- 优先 record_only: 收满样本后 parse_frame+diagnose 逐帧分析
+- 需要观察设备容错时才用 respond_normal/respond_scripted, 一次只改一个变量
+- 结束必须提醒用户恢复设备原配置
+注意事项: 字节序陷阱、半包重组成完整帧再解析、不要跳过 validate 直接下结论
+```
+
+- 只在 SKILL.md 里写方法论与工具调用顺序，不含脚本
+- description 是触发关键：写清"何时触发/何时不触发"
+
+## 6. 接入与发布清单（M3）
+
+- [ ] Claude Desktop: `claude_desktop_config.json` 注册 stdio server，截图
+- [ ] Codex: `config.toml` `[mcp_servers.proto-diag]` 注册，截图
+- [ ] README: 架构图 + 评测对比表 + GIF 演示（终端录 asciinema）
+- [ ] 提交 glama.ai / mcp.so / Pulse 收录
+- [ ] 可选薄 Web demo: FastAPI 单页，粘贴 hex → 展示解析+诊断
+- [ ] 加 MIT License、CI(pytest)
+
+## 7. 安全红线（坚持 PLAN.md 的要求）
+
+- 报文样例全部脱敏/改写；知识库用例来自实习排查经历但改写为通用场景
+- 不含公司设备 IP、型号组合、业务寄存器语义
+- 评测集用 ProtoForge 注入生成 + 手工构造，不依赖真实抓包原文
+
+
+
+

plctap-0.1.0/HANDOFF.md

@@ -0,0 +1,135 @@
+# plctap 开发交接文档（HANDOFF.md）
+
+> 交接对象：负责编码实现的 agent｜交接日期：2026-09-03
+> 本文档是唯一入口。按顺序读完第 1 节列出的文档后再动手写代码。
+
+## 1. 必读文档（按序）
+
+| 顺序 | 文档 | 内容 |
+|---|---|---|
+| 1 | PLAN.md | 定位、用户、能力地图、里程碑（已定案，不要重新讨论定位） |
+| 2 | ARCHITECTURE.md | 七个已确认 ADR、数据模型、适配器接口、服务端套件 |
+| 3 | BUILD.md | 仓库结构、三协议解析要点、ProtoForge 故障注入清单、SKILL.md 模板 |
+
+## 2. 已锁定的决策（直接执行，勿重议）
+
+1. **名称**: `plctap`（GitHub 仓库 / PyPI 包 / Python 包名统一）
+2. **技术栈**: Python 3.11+ / FastMCP / 纯 asyncio（不用同步协议库做 I/O；pymodbus、pymcprotocol 仅作帧格式对齐参考）
+3. **会话模型**: 工具无状态（每次带 host/port），server 内部连接池 key=(protocol,host,port,unit)，空闲30s回收，目标级互斥锁
+4. **Codec 纯函数化**: parse/validate/build 不碰 socket；全部单测覆盖
+5. **诊断引擎**: 纯确定性（规则引擎+kb.yaml），只输出结构化候选，不生成自然语言，不调 LLM
+6. **安全**: `allow_write=false` 时写类工具不注册；所有写/发送写 JSONL 审计日志(~/.plctap/audit.jsonl)
+7. **协议角色**: v1 只做 Client/主站；钓鱼模式 listener 基础两档(record_only/respond_normal)属 M3
+8. **评测**: 五档难度×同模型双跑；corpus 用 YAML；不做竞品准确率对比
+9. **三协议**: Modbus TCP / Omron FINS(TCP) / Mitsubishi MC(3E 二进制)
+
+## 3. 实施顺序（M1 任务分解，含验收标准）
+
+### T1 项目骨架（半天）
+- `uv init`，pyproject：`[project.scripts] plctap = "plctap.server:main"`
+- 依赖: fastmcp, pydantic, pyyaml, pytest, pytest-asyncio, scapy(评测用, 可选)
+- 建 ARCHITECTURE.md 第 3 节的目录树（包名 plctap）
+- CI: GitHub Actions 跑 pytest
+- **验收**: `uv run plctap` 能启动，MCP 工具列表里出现空实现工具
+
+### T2 Modbus codec 纯函数（1 天）
+- `protocols/modbus/codec.py`: build_read_request / parse_response / parse_request / validate_frame
+- 覆盖: FC01-04 请求/响应、FC05-06、异常响应(FC|0x80+异常码)、MBAP 长度校验
+- ParseResult 每字段带 byte_offset 和 raw_hex
+- **验收**: 参数化单测 ≥30 条全绿，含异常帧和畸形帧
+
+### T3 连接管理器 + probe（1 天）
+- `conn/manager.py`: 异步连接池 + wait_for 超时 + 目标级锁
+- `probe_device`: 分类 connection_refused / timeout / connected_but_no_reply / exception_response，输出 layer_hint
+- **验收**: 对本地 ProtoForge 模拟器 probe 成功；对不存在端口返回 refused；对静默端口返回 timeout
+
+### T4 plc_read（1 天）
+- 读 FC03/FC04，支持 datatype: uint16/int16/float32(大小端选项)
+- 返回 ReadResult（含 request_frame hex、elapsed_ms）
+- **验收**: 对话式完成"探测→读取→解释数值"，Claude Desktop + Codex 双端接入截图
+
+### T5 parse_frame / validate_frame 工具化（半天）
+- **验收**: 粘贴 hex 得到结构化字段与校验清单
+
+### M1 DoD（全绿才算完成）
+- [ ] ProtoForge 起本地 Modbus 从站，全流程演示 GIF 录制
+- [ ] pytest 通过率 100%，CI 绿
+- [ ] Claude Desktop / Codex 接入文档 + 截图
+
+### M2/M3 按 PLAN.md 里程碑执行，注意：
+- M2 评测 corpus 先做 Modbus 层（单帧/CRC/批量日志三档），FINS/MELSEC 层后补
+- M2 FINS 注意 TCP 握手(0x46494E53 节点分配)藏在 adapter 内；MC 只做 3E 二进制帧
+- M3 listener 用 asyncio.start_server，respond_normal 直接用 codec.build 回包
+
+## 4. 实现要点与坑（务必看 BUILD.md 第 3、4 节）
+
+- Modbus TCP 无 CRC（RTU 才有）；字节序三协议各不同（Modbus 大端/FINS 大端/MC 小端）——这些差异是知识库素材
+- 解析器对齐参考: pymodbus（Modbus）、pymcprotocol（MC 3E/4E）、sukmatechid/fins-driver（FINS）
+- ProtoForge 用法: clone 后按 protocols/{modbus,fins,mc}/server.py 起模拟器；故障注入=篡改响应字节再发（见 BUILD.md 第 4 节清单）
+- asyncio: 所有 socket 操作 asyncio.wait_for 包裹；连接池回收用后台 task
+- Windows 本地开发: 日志/路径用 pathlib；审计日志目录不存在要自动创建
+
+## 5. 红线（违反即返工）
+
+1. 报文样例/知识库全部脱敏改写——不含公司设备 IP、型号组合、业务寄存器语义
+2. 写工具默认不注册；审计日志不可关
+3. 不引入 LLM 调用进 server；不做自然语言解析
+4. 不重写通用模拟器（ProtoForge 是依赖不是竞品，MIT 协议可放心参考其 FINS/MC 实现）
+5. 不做超范围的协议（S7/OPC-UA 是 v2 的事）
+
+## 5.5 M1 联测记录（2026-09-04 完成）
+
+- ProtoForge Modbus TCP 从站 (127.0.0.1:15020) 实测: probe / fc06 写×3 / fc03 读回精确匹配 / float32 解释 3.1415927 / fc05 线圈 0xFF00 / 越界 ILLEGAL_DATA_ADDRESS(0x02) —— 全部通过
+- 本 Windows 关端口表现为 timeout（SYN 被丢弃），refused 分支由 monkeypatch 确定性覆盖
+- 联测脚本: scripts/integration_protoforge.py
+- 发现上游 bug: ProtoForge 设备写回路径在 pymodbus 3.15 下失效 (ModbusServerContext.async_setValues 对 legacy context 恒返回 DEVICE_BUSY) —— M2 做故障注入时需绕过该路径或给上游提 issue
+- **ProtoForge 测试台架必须 pin pymodbus==3.12.1** (`pip install protoforge "pymodbus<3.13"`): pymodbus 3.13+ 下配置的点位值会全部读回 0 (写回路径静默失效), 不 pin 会在"点位值全变 0"上浪费半天排查
+- P2 已修复: plc_write 实装 (fc05/06) + 审计记录真实帧 (on_frame 发送前回调) + list_protocols 与实际注册对齐
+
+## 5.6 演示资产（2026-09-04 完成）
+
+- docs/demo.gif: 聊天式演示动画, 由 scripts/make_demo_gif.py 用真实工具调用数据渲染 (内嵌状态化从站, 可随时重跑)
+- README 已含 Claude Desktop / Codex 接入样例 (含本地开发路径变体与 env 段)
+- 修复连接池清扫任务并发 bug (sweep 迭代快照化, 含回归测试) —— 演示脚本压测发现
+- 待用户环境: 双端接入截图 (配置样例已备好), 推送 GitHub
+
+## 5.7 M2 完成记录（2026-09-04）
+
+- **codec + 适配器**: FINS/TCP 两层协议 (TCP 头 16B + FINS 10B 头, 全大端) 与 MELSEC 3E 二进制 (副头部 0x5000, 全小端, 位软元件字数=ceil(count/16)) 的 build/parse/validate/interpret 全套; 两协议适配器接入 probe/read/send_raw, server 工具三协议分发 (plc_read 增 area/device 参数)
+- **方向判别统一**: `protocols/auto.py` 的 parse_auto 供 server 与诊断引擎共用 (Modbus 按 fc|0x80 与 12B 规则、FINS 按 TCP 命令与 ICF bit6、MELSEC 按命令字回显)
+- **诊断引擎 (D4)**: `diagnose` 工具 + 确定性规则引擎 + kb.yaml (60 条 entries + 3 条字节序 references); req→resp 帧配对启用交叉校验 (tid/sid/节点回显, 抓串包/网关错路由); Modbus TCP/RTU 双轨三档判别 (TCP 合法→单轨 TCP / RTU 完整可解释→单轨 RTU / 双败→合并但按"形似 RTU"门控抑制噪声候选)
+- **评测**: eval/benchmark.py (tool 模式打分 + `--export-prompts` 导出裸模型 JSONL) + corpus/modbus_m2.yaml 18 条三档语料 (single_frame_tcp 8 / integrity_crc 5 / batch_log 5), 全部合成帧, **18/18 通过**; tests/test_eval.py 自检防基线回退
+- **测试**: 248 全绿 (新增 codec FINS/MELSEC 48 + 适配器 14 + 诊断 81 + eval 自检 2)
+- 关键坑 (已修, 详见代码注释): ① asyncio fake server 对 EOF (IncompleteReadError) continue 会形成无挂起自旋、饿死整个事件循环 —— EOF 必须 return; ② FINS 请求的 DA1 必须定向到握手确认的 server_node, 否则多节点网络交叉校验误报; ③ 合法 RTU 帧按 TCP 硬解会产出 MBAP 类伪候选 (双轨判别的动机)
+- 红线遵守: 全部帧样本/KB 文案脱敏合成; server 内无 LLM 调用; 未写通用模拟器 (ProtoForge 为依赖)
+
+## 5.8 P3 语义修正 + 基线方法学（2026-09-04）
+
+- reachable 语义定死: 传输层可达 (TCP 已建立)。exception_response 时 reachable=True
+  (设备在线且回规范异常帧) —— models/server docstring、modbus/fins/melsec 适配器、测试同步
+- eval/baseline.py: 裸模型基线 runner (stdlib 调 Responses API, 离线 --answers 模式,
+  确定性判分与工具模式同源) + eval/README.md 方法学 (同模型双跑/分层/对比表纪律)
+- 自检: 判分器对关键词命中/空数组/错答三种情况验证正确
+- 真跑基线需 OPENAI_API_KEY (用户环境); README 对比表 = 工具模式 18/18 vs 基线 X/18
+
+## 5.9 M3 完成记录（2026-09-04）
+
+- **send_frame** (闸门): 发送原始帧 + 等待一帧响应, 与 plc_write 同受 allow_write 控制, 发送前完整帧落审计; list_protocols 的 send_raw 与闸门对齐
+- **parse_pcap**: scapy (可选依赖 eval extra) 读 pcap → 按五元组流聚合载荷 → 按协议切帧 → 逐帧 parse_auto; 尾部半帧标 partial 不静默丢弃; protocol 缺省按"完整帧数最多"自动判别; 未装 scapy 给出安装提示
+- **钓鱼监听** (record_only / respond_normal 两档): streams.py 三协议流分帧纯函数 (listener 与 pcap 共用); respond_normal 只回读类请求 (modbus fc1-6 / fins 握手+0101 / melsec 0401), 数据恒 0, 未覆盖请求记帧不回复; EOF/IncompleteReadError/空闲超时一律 return (M2 事件循环饿死教训), 帧存内存环形缓冲 (上限 1000), port=0 支持系统分配
+- **skill/SKILL.md** (proto-diag): BUILD.md 模板, 诊断流程 + 三种报文证据 + 钓鱼模式用法 + 字节序/半包注意事项
+- **LICENSE**: MIT; README 补工具表与状态更新
+- **测试**: 276 全绿 (新增 streams 12 + listener 13 + pcap 6 + smoke 扩展 2 + send_frame 端到端)
+- 红线遵守: 帧样本全部合成 (scapy 生成 pcap); respond_normal 是诊断设施非通用模拟器 (HANDOFF 红线 4)
+- 待用户环境: 五档评测对比表 (裸模型基线跑分需 OPENAI_API_KEY), 三端接入截图, GitHub/PyPI 发布, MCP 收录站提交
+
+## 6. 交付物清单
+
+- [x] eval/benchmark.py + corpus/ (M2 18/18; 裸模型基线跑分待用户 KEY)
+- [x] skill/SKILL.md
+- [x] LICENSE (MIT)
+- [ ] GitHub 仓库 plctap（CI 已有, 待推送 + 双端接入截图）
+- [ ] PyPI 可安装（uvx/pipx 一行跑起来）
+- [ ] README: 五档评测对比表 + 三端接入截图（待用户环境）
+- [ ] 提交 glama.ai / mcp.so / Pulse 收录
+

plctap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plctap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plctap-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: plctap
+Version: 0.1.0
+Summary: Agent-PLC MCP Server: connect, read and diagnose Modbus / FINS / MELSEC PLCs
+Project-URL: Homepage, https://github.com/ymxc152/plctap
+Project-URL: Repository, https://github.com/ymxc152/plctap
+Project-URL: Issues, https://github.com/ymxc152/plctap/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fins,industrial,mcp,melsec,modbus,plc,scada
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: eval
+Requires-Dist: scapy>=2.5; extra == 'eval'
+Description-Content-Type: text/markdown
+
+# plctap
+
+> Agent 的 PLC 驱动层 — 让 Claude / Codex / Cursor 直接连接、读写、诊断
+> Modbus TCP / FINS / MELSEC PLC 的 MCP Server。
+
+![demo](docs/demo.gif)
+
+**状态: 开发中 (M3: 三协议 + 诊断引擎 + 钓鱼监听)。** 本 README 将随里程碑补全:
+五档评测对比表 (工具模式 vs 裸模型)、三端接入截图 (待用户环境)。
+
+## 工具
+
+| 层 | 工具 | 说明 |
+|---|---|---|
+| 连接 | `probe_device` | 连通性探测 + 四类失败分层归因 |
+| 连接 | `plc_read` | 读数据区并按 datatype/字节序解释 (三协议) |
+| 诊断 | `parse_frame` / `validate_frame` | 单帧结构化解析 / 规范校验清单 |
+| 诊断 | `diagnose` | 规则引擎 + 故障知识库 → 结构化候选报告 |
+| 诊断 | `parse_pcap` | 解析 Wireshark 导出 pcap, 逐流逐帧 (需 `uv sync --extra eval`) |
+| 监听 | `start_listener` / `stop_listener` / `get_listener_frames` | 钓鱼模式: 设备只能当 client 时立假 server 收帧分析 |
+| 执行 | `plc_write` / `send_frame` | **默认不注册**, `PLCTAP_ALLOW_WRITE=true` 才启用 (闸门) |
+
+## 快速开始
+
+```bash
+uvx plctap          # 或 pipx install plctap
+```
+
+### Claude Desktop 接入 (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "plctap": {
+      "command": "uvx",
+      "args": ["plctap"],
+      "env": { "PLCTAP_ALLOW_WRITE": "false" }
+    }
+  }
+}
+```
+
+本地开发 (仓库检出路径):
+
+```json
+{
+  "mcpServers": {
+    "plctap": {
+      "command": "uv",
+      "args": ["--directory", "C:/path/to/plctap", "run", "plctap"]
+    }
+  }
+}
+```
+
+### Codex 接入 (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.plctap]
+command = "uvx"
+args = ["plctap"]
+
+[mcp_servers.plctap.env]
+PLCTAP_ALLOW_WRITE = "false"   # 写闸门默认关闭
+PLCTAP_DEFAULT_TIMEOUT_MS = "2000"
+```
+
+### 配置 (环境变量, 均有默认值)
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `PLCTAP_ALLOW_WRITE` | `false` | **写类工具默认不注册** (安全闸门) |
+| `PLCTAP_POOL_MAX_PER_TARGET` | `2` | 每目标连接池上限 |
+| `PLCTAP_IDLE_TIMEOUT_SEC` | `30` | 空闲连接回收秒数 |
+| `PLCTAP_DEFAULT_TIMEOUT_MS` | `2000` | 网络超时 |
+
+## 安全
+
+- 写操作默认**完全不注册**; 显式 `PLCTAP_ALLOW_WRITE=true` 才启用。
+- 所有写/发送动作逐条写入 JSONL 审计日志 (`~/.plctap/audit.jsonl`, 不可关)。
+- 发送类调用请配合客户端审批弹窗使用 (用户可见目标 IP 与完整帧)。
+- 审计日志样例:
+  `{"ts":"2026-09-04T01:20:33+0800","tool":"plc_write","target":"modbus://127.0.0.1:15020 unit=1","frame_hex":"0002000000060106000104d2","caller":"mcp"}`
+
+## 开发
+
+```bash
+uv sync
+uv run pytest -q   # codec 纯函数单测 (毫秒级) + MCP 冒烟测试
+uv run plctap      # 本地启动 stdio server
+```
+
+## License
+
+MIT