@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/protocol/transports/__init__.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.transports —— 能力传输策略层。
+
+设计模式: Strategy + Factory
+
+三态对应部署形态：
+    - stdio: 本地 spawn MCP server（现状默认）
+    - cli:   非 MCP 宿主兜底（直接跑脚本）— P2
+    - http:  远程服务器（未来）— P3
+
+工作流只通过 McpCap 调用，McpCap 经 McpRegistry 路由到具体 Transport。
+配置驱动 transport 选择 —— 改一行配置，本地→远程切换，工作流零改动。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .base import Transport, ToolResult, NoOpTransport
+from .stdio import StdioTransport
+from .http import RemoteHttpTransport
+from .cli import CliTransport
+
+
+def get_transport(server_name: str, kind: str = "stdio",
+                  repo_root=None, **kwargs) -> Transport:
+    """传输策略工厂。
+
+    Args:
+        server_name: MCP server 名（诊断 + launcher 参数）。
+        kind: 传输方式 —— "stdio" | "cli" | "http"。
+        repo_root: 仓库根（stdio 用，定位 mcp_launcher）。
+        **kwargs: 各 transport 特定参数（http 的 url/token 等）。
+    Returns:
+        Transport 实例；未知 kind 返回 NoOpTransport（兜底不抛错）。
+    """
+    if kind == "stdio":
+        return StdioTransport(server_name, repo_root=repo_root)
+    if kind == "http":
+        return RemoteHttpTransport(
+            url=kwargs.get("url", ""),
+            token=kwargs.get("token"),
+            server_name=server_name,
+        )
+    if kind == "cli":
+        script = kwargs.get("script")
+        from pathlib import Path
+        return CliTransport(script=Path(script) if script else Path(), **{k: v for k, v in kwargs.items() if k != "script"})
+    return NoOpTransport()
+
+
+__all__ = [
+    "Transport", "ToolResult", "NoOpTransport",
+    "StdioTransport", "RemoteHttpTransport", "CliTransport",
+    "get_transport",
+]

package/templates/qoder/scripts/protocol/transports/base.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""
+transports.base —— 能力传输策略抽象。
+
+设计模式: Strategy（策略模式）
+
+一个能力（如知识图谱）的"传输方式"是可替换策略：
+    - StdioTransport  (现状: 本地 spawn MCP server, stdin/stdout 传 JSON-RPC)
+    - CliTransport    (兜底: 直接跑 kg.py 等脚本, 解析 stdout) — P2
+    - RemoteHttpTransport (未来: HTTP POST 到服务器) — P3
+
+工作流面向"能力"编程 (cap.mcp.call("table_impact"))，不感知传输细节。
+配置驱动切换 transport —— 知识图谱从本地 stdio 迁到服务器 http，
+只需改 McpRegistry 配置 + 填 url，工作流代码零改动。
+
+Transport 与具体 MCP server 解耦：Transport 是"一种传输方式"，
+McpRegistry 负责"哪个 tool 走哪个 server 的哪个 transport"。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ToolResult:
+    """工具调用结果（所有 Transport 统一返回类型）。
+
+    Attributes:
+        text: 工具返回的文本内容（MCP 的 content[0].text，或 CLI 的 stdout）。
+        is_error: 是否为错误结果（MCP 的 isError，或异常捕获）。
+        raw: 原始响应（诊断用，调用方一般不直接用）。
+    """
+    text: str = ""
+    is_error: bool = False
+    raw: Any = field(default=None)
+
+    def __str__(self) -> str:
+        return self.text
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """能力传输策略契约。
+
+    所有 transport（stdio/http/cli）必须实现此接口。
+    McpCap 只通过此接口与底层通信，不感知传输细节。
+    """
+
+    available: bool
+
+    def list_tools(self) -> list[dict]:
+        """枚举此 transport 后端提供的工具（tools/list 语义）。"""
+        ...
+
+    def has_tool(self, name: str) -> bool:
+        """某工具是否可用。"""
+        ...
+
+    def call_tool(self, name: str, args: dict | None = None) -> ToolResult:
+        """调用工具，返回 ToolResult。失败时 is_error=True 但不抛异常（让调用方决定降级）。"""
+        ...
+
+    def close(self) -> None:
+        """清理连接/子进程。"""
+        ...
+
+
+class NoOpTransport:
+    """Transport 空实现 —— Null Object。
+
+    无可用 transport 时兜底：available=False，方法静默返回空，绝不抛错。
+    """
+
+    available = False
+
+    def list_tools(self) -> list[dict]:
+        return []
+
+    def has_tool(self, name: str) -> bool:
+        return False
+
+    def call_tool(self, name: str, args: dict | None = None) -> ToolResult:
+        return ToolResult(text="", is_error=True)
+
+    def close(self) -> None:
+        pass

package/templates/qoder/scripts/protocol/transports/cli.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""
+transports.cli —— CLI 传输策略（兜底形态）。
+
+设计模式: Strategy（与 StdioTransport 同接口，可替换）
+
+定位：非 QoderWork 宿主（ZCode/Codex/纯 CLI）没有 MCP 客户端时，
+      通过直接跑 kg.py 等脚本子进程获得等价能力。
+      复用 kg_capabilities.py（kg.py 与 kg_mcp_server.py 的共享单一真源），
+      保证输出与 MCP 一致。
+
+机制：
+    command_map 映射 tool_name → (subcommand, args_adapter)：
+    - subcommand: CLI 子命令名（如 "search_code"）
+    - args_adapter: callable(dict) -> list[str] 参数翻译函数（可选）
+    CliTransport 用 subprocess.run 跑脚本 + 子命令，解析 stdout JSON。
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from .base import ToolResult
+
+# 默认超时（秒）
+_TIMEOUT = 60
+
+
+class CliTransport:
+    """CLI 传输策略（子进程跑脚本，解析 stdout）。
+
+    Args:
+        script: 脚本路径（如 .qoder/scripts/domain/kg/kg.py）。
+        command_map: tool 名 → (subcommand, args_adapter) 映射。
+            subcommand: CLI 子命令名。
+            args_adapter: callable(dict) -> list[str]（可选，None 表示无额外参数）。
+    """
+
+    def __init__(self, script: Path, command_map: Optional[dict] = None):
+        self._script = script
+        self._command_map = command_map or {}
+        self._tools_cache: Optional[list[dict]] = None
+        self._tool_index: Optional[set[str]] = None
+
+    @property
+    def available(self) -> bool:
+        return self._script.is_file()
+
+    def list_tools(self) -> list[dict]:
+        # CLI 无统一 tools/list；按 command_map 的 key 作为可用工具清单
+        if self._tools_cache is None:
+            self._tools_cache = [{"name": k} for k in self._command_map]
+            self._tool_index = set(self._command_map.keys())
+        return self._tools_cache
+
+    def has_tool(self, name: str) -> bool:
+        if self._tool_index is None:
+            self.list_tools()
+        return name in (self._tool_index or set())
+
+    def call_tool(self, name: str, args: dict | None = None) -> ToolResult:
+        if name not in self._command_map:
+            return ToolResult(text="CLI 未映射工具: %s" % name, is_error=True)
+
+        entry = self._command_map[name]
+        if isinstance(entry, tuple):
+            subcommand = entry[0]
+            adapter = entry[1] if len(entry) > 1 else None
+        else:
+            subcommand = entry
+            adapter = None
+
+        # 构建 CLI 命令: python script.py subcommand [adapted_args...]
+        cmd = [sys.executable, str(self._script), subcommand]
+        if adapter and args:
+            try:
+                cmd.extend(adapter(args))
+            except Exception as e:
+                return ToolResult(text="参数翻译失败: %s" % str(e)[:120], is_error=True)
+        elif args:
+            # 默认: key=value 格式
+            for k, v in args.items():
+                if v is not None:
+                    cmd.extend(["--%s" % k, str(v)])
+
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=_TIMEOUT,
+                encoding="utf-8",
+                errors="replace",
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(text="CLI 超时 (%ds): %s" % (_TIMEOUT, name), is_error=True)
+        except Exception as e:
+            return ToolResult(text="CLI 执行失败: %s" % str(e)[:120], is_error=True)
+
+        # 解析 stdout：优先 JSON，降级纯文本
+        stdout = (proc.stdout or "").strip()
+        stderr = (proc.stderr or "").strip()
+
+        if proc.returncode != 0 and not stdout:
+            return ToolResult(
+                text="CLI 错误 (exit=%d): %s" % (proc.returncode, stderr[:200]),
+                is_error=True,
+            )
+
+        # 尝试 JSON 解析
+        if stdout:
+            try:
+                data = json.loads(stdout)
+                # MCP server 输出格式: {"content": [{"text": "..."}]}
+                if isinstance(data, dict) and "content" in data:
+                    text = data["content"][0].get("text", "") if data["content"] else ""
+                    return ToolResult(text=text, is_error=data.get("isError", False))
+                # 纯 JSON 字符串或列表
+                if isinstance(data, str):
+                    return ToolResult(text=data)
+                return ToolResult(text=json.dumps(data, ensure_ascii=False))
+            except (json.JSONDecodeError, IndexError, KeyError):
+                pass
+
+        # 降级: 纯文本输出
+        return ToolResult(text=stdout or stderr or "(无输出)")
+
+    def close(self) -> None:
+        pass  # CLI 无状态，每次调用 spawn 子进程

package/templates/qoder/scripts/protocol/transports/http.py

@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+"""
+transports.http —— 远程 HTTP MCP 传输策略。
+
+设计模式: Strategy（与 StdioTransport 同接口，可替换）
+
+定位：满足现在的本地 stdio，留扩展给未来的服务器化。
+知识图谱/禅道等能力未来可上服务器，以 HTTP MCP (Streamable HTTP) 暴露。
+届时只需在 McpRegistry 配置把 server 的 transport 从 "stdio" 改成 "http" + 填 url，
+工作流代码 (cap.mcp.call) 零改动。
+
+机制：
+    POST {url}/mcp  发 JSON-RPC 2.0 请求，解析 JSON 响应。
+    支持 Bearer token 认证。
+    超时可配置，失败自动分类（网络/超时/协议错误）。
+
+依赖：仅 stdlib（urllib），无第三方包。
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from .base import ToolResult
+
+# 默认超时（秒）
+_TIMEOUT = 30
+# MCP 协议版本
+_PROTOCOL_VERSION = "2024-11-05"
+
+
+class RemoteHttpTransport:
+    """远程 HTTP MCP 传输策略。
+
+    Args:
+        url: 远程 MCP endpoint（如 https://kg.corp/mcp）。
+        token: 认证 token（Bearer）。可选。
+        server_name: server 名（诊断用）。
+        timeout: 请求超时秒数。
+    """
+
+    def __init__(self, url: str, token: Optional[str] = None,
+                 server_name: str = "", timeout: int = _TIMEOUT):
+        self._url = (url or "").rstrip("/")
+        self._token = token
+        self._server = server_name
+        self._timeout = timeout
+        self._tools_cache: Optional[list[dict]] = None
+        self._tool_index: Optional[set[str]] = None
+        self._req_id = 0
+        self._last_error: Optional[str] = None
+
+    @property
+    def available(self) -> bool:
+        """有 url 即视为可尝试（真实可达性在首次调用时检验）。"""
+        return bool(self._url)
+
+    def _next_id(self) -> int:
+        self._req_id += 1
+        return self._req_id
+
+    def _post_jsonrpc(self, method: str, params: dict | None = None) -> dict:
+        """发 JSON-RPC 请求，返回响应 dict。
+
+        失败抛 RuntimeError（调用方捕获转 ToolResult）。
+        """
+        rid = self._next_id()
+        body: dict = {"jsonrpc": "2.0", "id": rid, "method": method}
+        if params is not None:
+            body["params"] = params
+
+        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+        endpoint = self._url + "/mcp"
+
+        req = urllib.request.Request(
+            endpoint,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        if self._token:
+            req.add_header("Authorization", "Bearer %s" % self._token)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            raise RuntimeError("HTTP %d: %s" % (e.code, e.read().decode("utf-8", errors="replace")[:200]))
+        except urllib.error.URLError as e:
+            raise RuntimeError("连接失败: %s" % str(e.reason)[:120])
+        except TimeoutError:
+            raise RuntimeError("超时 (%ds)" % self._timeout)
+
+        try:
+            result = json.loads(raw)
+        except json.JSONDecodeError:
+            raise RuntimeError("非 JSON 响应: %s" % raw[:120])
+
+        if "error" in result:
+            msg = result["error"].get("message", "unknown")
+            raise RuntimeError("MCP error: %s" % str(msg)[:200])
+
+        return result
+
+    def list_tools(self) -> list[dict]:
+        """POST tools/list，解析工具清单。"""
+        if self._tools_cache is not None:
+            return self._tools_cache
+        try:
+            resp = self._post_jsonrpc("tools/list")
+            tools = resp.get("result", {}).get("tools", [])
+            self._tools_cache = tools
+            self._tool_index = {t.get("name", "") for t in tools}
+        except Exception as e:
+            self._last_error = str(e)[:120]
+            self._tools_cache = []
+            self._tool_index = set()
+        return self._tools_cache
+
+    def has_tool(self, name: str) -> bool:
+        if self._tool_index is None:
+            self.list_tools()
+        return name in (self._tool_index or set())
+
+    def call_tool(self, name: str, args: dict | None = None) -> ToolResult:
+        """POST tools/call，解析 content[0].text。"""
+        try:
+            resp = self._post_jsonrpc("tools/call", {"name": name, "arguments": args or {}})
+        except Exception as e:
+            return ToolResult(text="HTTP transport 错误: %s" % str(e)[:120], is_error=True)
+
+        result = resp.get("result", {})
+        content = result.get("content", [])
+        text = content[0].get("text", "") if content else ""
+        return ToolResult(text=text, is_error=result.get("isError", False), raw=resp)
+
+    def close(self) -> None:
+        # HTTP 无长连接需关（urllib 无连接池）
+        pass