plctap 0.1.0__py3-none-any.whl

plctap/__init__.py

@@ -0,0 +1,6 @@
+"""plctap — Agent-PLC MCP Server。
+
+让 Claude / Codex / Cursor 直接连接、读写、诊断 Modbus TCP / FINS / MELSEC PLC。
+"""
+
+__version__ = "0.1.0"

plctap/config.py

@@ -0,0 +1,44 @@
+"""运行配置 (ARCHITECTURE.md 第 7 节)。
+
+配置来源: 环境变量 (PLCTAP_*)。
+理由: MCP stdio server 由客户端拉起 (claude_desktop_config.json 的 env 段 /
+Codex config.toml 的 [mcp_servers.plctap].env), 环境变量是两个客户端都原生
+支持的配置通道; 独立 TOML 文件还需约定查找路径与优先级, M1 阶段不引入。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+_TRUE = {"1", "true", "yes", "on"}
+
+_DEFAULT_AUDIT_LOG = Path.home() / ".plctap" / "audit.jsonl"
+
+
+@dataclass(frozen=True)
+class PlctapConfig:
+    """server 运行参数, 与 ARCHITECTURE.md 第 7 节的配置样例一一对应。"""
+
+    # 安全闸门 (D5): False 时写类工具根本不注册
+    allow_write: bool = False
+    # 连接池: 每目标 (protocol,host,port,unit) 同时持有的连接上限 (D1)
+    pool_max_per_target: int = 2
+    # 空闲连接回收阈值 (D1: 空闲 30s 回收)
+    idle_timeout_sec: float = 30.0
+    # 默认网络超时 (连接/收发各自独立计时)
+    default_timeout_ms: int = 2000
+    # JSONL 审计日志路径; 审计不可关 (HANDOFF 红线 2)
+    audit_log: Path = _DEFAULT_AUDIT_LOG
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "PlctapConfig":
+        env = os.environ if env is None else env
+        return cls(
+            allow_write=env.get("PLCTAP_ALLOW_WRITE", "").strip().lower() in _TRUE,
+            pool_max_per_target=int(env.get("PLCTAP_POOL_MAX_PER_TARGET", "2")),
+            idle_timeout_sec=float(env.get("PLCTAP_IDLE_TIMEOUT_SEC", "30")),
+            default_timeout_ms=int(env.get("PLCTAP_DEFAULT_TIMEOUT_MS", "2000")),
+            audit_log=Path(env.get("PLCTAP_AUDIT_LOG", str(_DEFAULT_AUDIT_LOG))),
+        )

plctap/conn/__init__.py

@@ -0,0 +1 @@
+"""连接管理子包 (D1: 无状态工具 + 内部透明连接池)。"""

plctap/conn/manager.py

@@ -0,0 +1,165 @@
+"""连接池 + 目标级互斥锁 (ARCHITECTURE.md D1)。
+
+设计要点:
+- 工具无状态, 每次携带 host/port; 池 key = (protocol, host, port, unit)。
+  unit 进入 key 是因为同一 IP:PORT 上不同 unit id 的会话语义不同
+  (Modbus 网关场景), 复用连接可能串话。
+- 空闲 idle_timeout_sec 的连接由后台清扫任务关闭; 任务在首次 acquire
+  时惰性启动, 进程退出由事件循环一并回收 (stdio server 生命周期即进程)。
+- 每目标互斥锁: 一次请求-响应配对期间独占连接, 防止并发调用串包。
+- 池上限: 活跃+空闲连接达到 max_per_target 后, 新连接标记为 ephemeral,
+  用完即弃不入池 (限流而非阻塞)。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import NamedTuple
+
+
+class ConnectionKey(NamedTuple):
+    """连接池 key (D1): (protocol, host, port, unit)。"""
+
+    protocol: str
+    host: str
+    port: int
+    unit: int
+
+    @property
+    def target(self) -> str:
+        """人可读的目标标识, 用于审计与错误信息。"""
+        return f"{self.protocol}://{self.host}:{self.port} unit={self.unit}"
+
+
+class PooledConnection:
+    """池中一条 TCP 连接。ephemeral=True 的连接用完即关, 不回池。"""
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        key: ConnectionKey,
+        ephemeral: bool = False,
+    ) -> None:
+        self.reader = reader
+        self.writer = writer
+        self.key = key
+        self.ephemeral = ephemeral
+        self.last_used = time.monotonic()
+        # 协议适配器的每连接会话状态 (如 FINS/TCP 已完成的节点握手);
+        # 连接复用时状态随连接保留, 连接销毁即作废
+        self.metadata: dict[str, object] = {}
+
+    @property
+    def closed(self) -> bool:
+        return self.writer.is_closing()
+
+    def close(self) -> None:
+        if not self.writer.is_closing():
+            self.writer.close()
+
+
+class ConnectionPool:
+    def __init__(
+        self,
+        idle_timeout_sec: float = 30.0,
+        max_per_target: int = 2,
+        sweep_interval_sec: float = 5.0,
+    ) -> None:
+        self.idle_timeout_sec = idle_timeout_sec
+        self.max_per_target = max(1, max_per_target)
+        self.sweep_interval_sec = sweep_interval_sec
+        self._idle: dict[ConnectionKey, list[PooledConnection]] = {}
+        self._active: dict[ConnectionKey, int] = {}
+        self._locks: dict[ConnectionKey, asyncio.Lock] = {}
+        self._sweeper: asyncio.Task[None] | None = None
+
+    def lock_for(self, key: ConnectionKey) -> asyncio.Lock:
+        """目标级互斥锁 (D1): 覆盖整个请求-响应配对, 防并发串包。"""
+        lock = self._locks.get(key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._locks[key] = lock
+        return lock
+
+    async def acquire(
+        self,
+        key: ConnectionKey,
+        connect_timeout: float,
+    ) -> PooledConnection:
+        """取一条可用连接: 优先复用空闲连接, 否则新建。新建失败向上抛
+        ConnectionRefusedError / TimeoutError 等, 由适配器做失败分类。"""
+        # 1) 复用空闲连接 (跳过已被对端关闭的)
+        idle = self._idle.get(key)
+        while idle:
+            conn = idle.pop()
+            if not conn.closed:
+                self._active[key] = self._active.get(key, 0) + 1
+                conn.last_used = time.monotonic()
+                return conn
+            conn.close()  # 确保 socket 资源释放
+
+        # 2) 新建; 达到池上限则建 ephemeral 连接 (用完即弃)
+        ephemeral = self._active.get(key, 0) >= self.max_per_target
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(key.host, key.port), connect_timeout
+        )
+        conn = PooledConnection(reader, writer, key, ephemeral=ephemeral)
+        self._active[key] = self._active.get(key, 0) + 1
+        self._ensure_sweeper()
+        return conn
+
+    def release(self, conn: PooledConnection, *, healthy: bool = True) -> None:
+        """归还连接。healthy=False (协议层出错/流可能失步) 时直接丢弃。"""
+        self._active[conn.key] = max(0, self._active.get(conn.key, 1) - 1)
+        if not healthy or conn.ephemeral or conn.closed:
+            conn.close()
+            return
+        conn.last_used = time.monotonic()
+        self._idle.setdefault(conn.key, []).append(conn)
+
+    def discard(self, conn: PooledConnection) -> None:
+        """异常路径丢弃连接 (release 的别名, 语义化使用)。"""
+        self.release(conn, healthy=False)
+
+    async def close_all(self) -> None:
+        """关闭全部空闲连接并停掉清扫任务 (测试收尾用)。"""
+        if self._sweeper is not None:
+            self._sweeper.cancel()
+            try:
+                await self._sweeper
+            except asyncio.CancelledError:
+                pass
+            self._sweeper = None
+        for idle in self._idle.values():
+            for conn in idle:
+                conn.close()
+        self._idle.clear()
+
+    def _ensure_sweeper(self) -> None:
+        """清扫任务惰性启动: 首次成功建连时才创建, 之后常驻。"""
+        if self._sweeper is not None and not self._sweeper.done():
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        self._sweeper = loop.create_task(self._sweep_loop())
+
+    async def _sweep_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self.sweep_interval_sec)
+            now = time.monotonic()
+            for key, idle in list(self._idle.items()):  # 快照迭代: release() 可能并发改字典
+                keep: list[PooledConnection] = []
+                for conn in idle:
+                    if now - conn.last_used > self.idle_timeout_sec or conn.closed:
+                        conn.close()
+                    else:
+                        keep.append(conn)
+                if keep:
+                    self._idle[key] = keep
+                else:
+                    self._idle.pop(key, None)
+

plctap/diag/__init__.py

@@ -0,0 +1 @@
+"""诊断引擎子包 (M2: 确定性规则引擎 + kb.yaml, D4)。占位。"""

plctap/diag/engine.py

@@ -0,0 +1,265 @@
+"""诊断引擎 (D4): 确定性规则匹配 + kb.yaml, 不做任何自然语言生成。
+
+输入是结构化观测 (probe 结果 / 帧解析结果 / 日志片段), 输出按置信度
+排序的候选结论。规则全部来自 kb.yaml (与本模块同目录打包):
+- entries: 匹配条件 -> 预审定的静态文案 (symptom/root_cause/action)
+- references: 命中含数值数据的帧时附加的字节序提示 (不是候选结论)
+
+匹配语义 (kb.yaml 头注): 单条目所有给出的条件都满足才命中;
+frame 级条件 (解析报错/检查项/字段) 按帧求值, 任一帧命中即算;
+probe 级条件 (failure_class) 对探测结果求值。
+
+日志模式: 从文本里提取连续 hex 串 (>=16 hex 字符即 >= 8 字节, 覆盖
+RTU 最短帧) 逐帧解析。纯数字长串 (时间戳) 可能误入, 解析只会产出
+结构化错误并归入 observations, 不影响结论 (事实先行, 噪声留痕)。
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from plctap.models import Candidate, DiagnosticReport, ParseResult, ProbeResult
+from plctap.protocols.auto import parse_auto
+
+_KB_PATH = Path(__file__).with_name("kb.yaml")
+
+# 连续 hex 串 (偶长): >= 16 个 hex 字符 = 8 字节 (Modbus RTU 最短帧)
+_HEX_TOKEN = re.compile(r"(?<![0-9a-fA-F])[0-9a-fA-F]{16,}(?![0-9a-fA-F])")
+
+# 双轨合并时 RTU 侧的 "形似 RTU" 门控: 这些检查全过才把尾字节当 CRC 校验
+_RTU_GATE = frozenset({
+    "exception_payload_shape", "request_payload_shape", "response_payload_shape",
+})
+
+
+@lru_cache(maxsize=1)
+def _load_kb() -> dict[str, Any]:
+    with _KB_PATH.open("r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def kb_entries() -> list[dict[str, Any]]:
+    """知识库条目 (评测与测试用)。"""
+    return _load_kb().get("entries", [])
+
+
+def kb_entry_ids() -> set[str]:
+    return {e["id"] for e in kb_entries()}
+
+
+# ---------------------------------------------------------------- 观测收集
+
+
+class _FrameFacts:
+    """单帧的观测事实: 方向 + 解析报错 + 校验失败项 + 字段值。"""
+
+    __slots__ = ("direction", "parse_errors", "failed_checks", "fields")
+
+    def __init__(self, parsed: ParseResult, failed_checks: list[str]) -> None:
+        self.direction = parsed.direction
+        self.parse_errors = parsed.errors
+        self.failed_checks = failed_checks
+        self.fields = {f.name: f.value for f in parsed.fields}
+
+
+def _collect_frame(protocol: str, frame: bytes, pending_request: bytes | None) -> tuple[_FrameFacts, bytes | None]:
+    """解析一帧并收集事实。返回 (帧事实, 本帧若为请求则带回以供配对)。
+
+    Modbus TCP/RTU 双轨判别 (三档, 决定校验清单与事实来源):
+    - TCP 结构合法: 单轨 TCP。合法 TCP 帧的尾字节不是 RTU CRC, 不跑 RTU 轨。
+    - TCP 硬解失败但 RTU 能完整解释 (parse_rtu 合法): 单轨 RTU —— 合法
+      RTU 帧不该产出 "MBAP 长度不符" 这类按 TCP 硬解的伪结论。
+    - 两者都解释不通: 双轨合并。RTU 侧仅在帧 "形似 RTU" (功能码已知且
+      payload 形状自洽, 见 validate_rtu) 时纳入, 否则 12 字节 TCP 帧的
+      尾字节会被当 CRC 算出 "RTU 校验和错" 噪声, 压过真正的 TCP 结论。
+
+    配对规则: 响应帧紧跟在同一协议的 TCP 请求帧之后时, 用 codec 的
+    request 参数重解析, 交叉校验错误 (tid/sid/节点回显) 才能出现 ——
+    这正是串包/网关错路由类故障的观测来源。RTU 帧无事务号, 不参与
+    配对 (串口侧按地址/功能码回显核对, 不在本引擎范围)。
+    """
+    from plctap.protocols import codec_for
+
+    codec = codec_for(protocol)
+    parsed = parse_auto(protocol, frame)
+    track = "tcp"
+    if parsed.valid:
+        failed = [c.name for c in codec.validate_frame(frame, parsed.direction) if not c.passed]
+        facts = _FrameFacts(parsed, failed)
+    else:
+        rtu = codec.parse_rtu(frame) if protocol == "modbus" else None
+        if rtu is not None and rtu.valid:
+            track = "rtu"
+            failed = [c.name for c in codec.validate_rtu(frame, rtu.direction) if not c.passed]
+            facts = _FrameFacts(rtu, failed)
+        else:
+            failed = [c.name for c in codec.validate_frame(frame, parsed.direction) if not c.passed]
+            rtu_checks = codec.validate_rtu(frame) if rtu is not None else []
+            gate = _RTU_GATE | {"function_code_known"}
+            if all(c.passed for c in rtu_checks if c.name in gate):
+                failed.extend(c.name for c in rtu_checks if not c.passed)
+            facts = _FrameFacts(parsed, failed)
+    if facts.direction == "req" and track == "tcp":
+        return facts, frame
+    if pending_request is not None:
+        reparsed = codec.parse_response(frame, request=pending_request)
+        return _FrameFacts(reparsed, facts.failed_checks), None
+    return facts, None
+
+
+# ---------------------------------------------------------------- 规则匹配
+
+
+def _match_frame(entry: dict[str, Any], frame: _FrameFacts) -> bool:
+    m = entry.get("match", {})
+    if "exception_code" in m:
+        # Modbus 异常码在 exception_code 字段; FINS/MELSEC 在 end_code 字段,
+        # 但 KB 用 exception_code 统一表达"设备回的错误码" —— 两个来源都看
+        codes = {v for v in (_frame_code(frame, "exception_code"), _frame_code(frame, "end_code")) if v is not None}
+        if not codes & set(m["exception_code"]):
+            return False
+    if "end_code" in m:
+        if _frame_code(frame, "end_code") not in m["end_code"]:
+            return False
+    if "parse_error_contains" in m:
+        joined = " | ".join(frame.parse_errors).casefold()
+        if not any(s.casefold() in joined for s in m["parse_error_contains"]):
+            return False
+    if "check_failed" in m:
+        if not any(name in frame.failed_checks for name in m["check_failed"]):
+            return False
+    if "field" in m:
+        for name, values in m["field"].items():
+            if frame.fields.get(name) not in values:
+                return False
+    if "direction" in m and frame.direction != m["direction"]:
+        return False
+    return True
+
+
+def _frame_code(frame: _FrameFacts, name: str) -> int | None:
+    v = frame.fields.get(name)
+    return v if isinstance(v, int) else None
+
+
+def _match_probe(entry: dict[str, Any], probe: ProbeResult | None) -> bool:
+    if "failure_class" not in entry.get("match", {}):
+        return True  # 条目不约束探测结果
+    if probe is None or not probe.failure_class:
+        return False
+    return probe.failure_class in entry["match"]["failure_class"]
+
+
+def _evidence(entry_id: str, frames: list[tuple[int, _FrameFacts]], probe: ProbeResult | None) -> list[str]:
+    ev: list[str] = []
+    for idx, f in frames:
+        ev.append(f"frame[{idx}] direction={f.direction}")
+        ev.extend(f"frame[{idx}] parse_error: {e}" for e in f.parse_errors)
+        ev.extend(f"frame[{idx}] check_failed: {c}" for c in f.failed_checks)
+    if probe is not None and probe.failure_class:
+        ev.append(f"probe failure_class={probe.failure_class}")
+        if probe.exception_code is not None:
+            ev.append(f"probe exception_code={probe.exception_code:#x}")
+    return ev or [f"matched kb entry {entry_id} (no extra evidence)"]
+
+
+# ---------------------------------------------------------------- 主入口
+
+
+def diagnose(
+    protocol: str,
+    frames_hex: list[str] | None = None,
+    log_snippet: str | None = None,
+    probe_result: ProbeResult | None = None,
+) -> DiagnosticReport:
+    """从观测推导候选结论。三种输入可任意组合, 全缺则返回空报告
+    (知识库未覆盖时如实为空, 不硬凑结论)。"""
+    observations: list[str] = []
+    frames: list[tuple[int, _FrameFacts]] = []
+    saw_values = False
+    pending_request: bytes | None = None
+
+    for hexstr in frames_hex or []:
+        frame = _coerce_frame(hexstr, observations)
+        if frame is None:
+            continue
+        facts, pending_request = _collect_frame(protocol, frame, pending_request)
+        frames.append((len(frames), facts))
+        if "word_values" in facts.fields:
+            saw_values = True
+        observations.append(f"frame[{frames[-1][0]}] {len(frame)}B parsed (direction={facts.direction})")
+
+    if log_snippet:
+        tokens = _HEX_TOKEN.findall(log_snippet)
+        observations.append(f"log_snippet: extracted {len(tokens)} hex token(s)")
+        for tok in tokens:
+            frame = _coerce_frame(tok, observations)
+            if frame is None:
+                continue
+            facts, pending_request = _collect_frame(protocol, frame, pending_request)
+            frames.append((len(frames), facts))
+            if "word_values" in facts.fields:
+                saw_values = True
+
+    candidates: list[Candidate] = []
+    for entry in kb_entries():
+        if not _match_probe(entry, probe_result):
+            continue
+        matched = [
+            (idx, f) for idx, f in frames if _match_frame(entry, f)
+        ]
+        if not matched and _needs_frame(entry):
+            continue
+        c = entry["candidate"]
+        candidates.append(
+            Candidate(
+                symptom=c["symptom"],
+                root_cause=c["root_cause"],
+                evidence=_evidence(entry["id"], matched, probe_result),
+                confidence=float(c["confidence"]),
+                suggested_action=c["suggested_action"],
+                next_tools=c.get("next_tools", []),
+            )
+        )
+
+    candidates.sort(key=lambda c: c.confidence, reverse=True)
+
+    next_tools: list[str] = []
+    for c in candidates:
+        for t in c.next_tools:
+            if t not in next_tools:
+                next_tools.append(t)
+
+    if saw_values:
+        observations.extend(_reference_notes(protocol))
+
+    if not candidates and not observations:
+        observations.append("no observation provided; give frame_hex / log_snippet / probe inputs")
+    if not candidates and observations:
+        observations.append("no kb entry matched; knowledge base does not cover this pattern")
+
+    return DiagnosticReport(candidates=candidates, next_tools=next_tools, observations=observations)
+
+
+def _needs_frame(entry: dict[str, Any]) -> bool:
+    """条目含任一帧级条件就必须有帧命中; 仅 probe 条目的条目无需帧。"""
+    m = entry.get("match", {})
+    return any(k in m for k in ("exception_code", "end_code", "parse_error_contains", "check_failed", "field", "direction"))
+
+
+def _coerce_frame(hexstr: str, observations: list[str]) -> bytes | None:
+    try:
+        return bytes.fromhex(hexstr)
+    except ValueError:
+        observations.append(f"skipped non-hex token: {hexstr[:16]}...")
+        return None
+
+
+def _reference_notes(protocol: str) -> list[str]:
+    notes = [r["note"] for r in _load_kb().get("references", []) if r.get("protocol") == protocol]
+    return ["reference: " + " ".join(n.split()) for n in notes]