@hupan56/wlkj 3.3.12 → 3.3.14

package/templates/qoder/scripts/capability/adapters/mcp.py

@@ -1,322 +1,314 @@
-# -*- coding: utf-8 -*-
-"""
-adapters.mcp —— L1 MCP 能力统一入口（已接通 transport 层）。
-
-设计模式: Adapter + Facade
-
-职责：
-    把 McpRegistry（tool→server→transport 路由）适配成 McpCap 的
-    has_tool/call/list_tools 接口，供 Nexus Facade 统一暴露。
-
-L1 能力定位：禅道/知识图谱/MySQL/蓝湖/playwright 已 MCP 化，
-    通过本入口跨宿主统一调用，复用已有 MCP 资产，绝不重写它们。
-
-跨宿主行为：
-    - QoderWork / 任意宿主：通过 mcp_launcher spawn 本地 MCP server（stdio transport）
-    - 未来服务器：改 McpRegistry.SERVERS 配置 kind=http + url，工作流零改动
-    - 无可用 server：available=False，has_tool 返回 False（静默回退）
-
-McpMemoryProvider：memory 职责链的 MCP provider，接通 kg.duckdb learning_events 表。
-    当 mem0/Zep MCP server 更成熟时可替换为 MCP 版本，接口不变。
-"""
-from __future__ import annotations
-
-import json
-from typing import Any, Optional
-
-from ..registry_mcp import McpRegistry, _load_servers
-from protocol.transports import ToolResult
-
-
-# 单例 Registry（同一进程复用进程池，避免重复 spawn）
-_REGISTRY: Optional[McpRegistry] = None
-
-
-def _get_registry() -> McpRegistry:
-    global _REGISTRY
-    if _REGISTRY is None:
-        _REGISTRY = McpRegistry()
-    return _REGISTRY
-
-
-class McpCap:
-    """L1 MCP 能力统一入口 —— 复用已有 MCP server（禅道/知识图谱/MySQL/蓝湖）。
-
-    工作流调用：
-        cap = resolve()
-        result = cap.mcp.call("search_code", {"keyword": "保险"})
-        # 自动路由：MCP 可用走 MCP，不可用走 wlkj.py（CLI 降级）
-    """
-
-    def __init__(self, mcp_servers=None):
-        # ★ 空 mcp_servers (= [] 或 None) 视为"不限制 = 用全部本地 server"。
-        # 原版: mcp_servers=[] (空列表, is not None) → filtered 成空 → _servers={} → 0 工具,
-        # 整个 cap.mcp 自废武功。但本地 stdio transport (StdioTransport) 通过 mcp_launcher
-        # spawn 子进程, 不依赖宿主是否原生支持 MCP —— CLI / Codex / Claude 同样能起 server。
-        # 故: 宿主未声明 mcp_servers 或声明为空 = "没有宿主原生限制, 用全部本地可起的"。
-        if mcp_servers:  # 非空列表才过滤
-            # 用 _load_servers() 而非硬编码 SERVERS —— 这样 mcp_config.json 改配置才生效
-            all_servers = _load_servers()
-            filtered = {k: v for k, v in all_servers.items() if k in mcp_servers}
-            self._registry = McpRegistry(servers=filtered)
-        else:
-            self._registry = _get_registry()
-
-    @property
-    def available(self) -> bool:
-        """是否有任一 MCP server 可用。"""
-        try:
-            return self._registry.available()
-        except Exception:
-            return False
-
-    # ------------------------------------------------------------------
-    # McpCap 接口
-    # ------------------------------------------------------------------
-
-    def has_tool(self, name: str) -> bool:
-        """某 MCP 工具是否可用（跨所有已配置 server 查找）。"""
-        try:
-            return self._registry.has_tool(name)
-        except Exception:
-            return False
-
-    def call(self, name: str, args: Optional[dict] = None,
-             server: Optional[str] = None) -> ToolResult:
-        """调用 MCP 工具（自动 CLI 降级）。
-
-        优先走 MCP；MCP 不可用时自动降级到 wlkj.py CLI 脚本。
-        工作流永远写 cap.mcp.call("tool_name", args)，零宿主感知。
-        """
-        # 1. MCP 可用 → 走 MCP
-        result = self._registry.call(name, args, server=server)
-        if not result.is_error:
-            return result
-        # 2. CLI 降级（MCP 不可用或调用失败）
-        cli_text = self._cli_fallback(name, args or {})
-        if cli_text is not None:
-            return ToolResult(text=cli_text)
-        return result  # 无降级映射，返回原始错误
-
-    # ------------------------------------------------------------------
-    # CLI 降级（MCP 不可用时走 wlkj.py）
-    # ------------------------------------------------------------------
-
-    # MCP 工具名 → (wlkj 命令, 基础参数) 映射
-    # 只映射有 wlkj.py 对应的知识图谱/任务工具。
-    # MySQL/禅道/蓝湖等 MCP 专属工具不映射（MCP 不可用时返回错误提示）。
-    _TOOL_TO_WLKJ = {
-        "search_code":       ("kg", ["search"]),
-        "search_api":        ("kg", ["api"]),
-        "search_prd":        ("kg", ["prd"]),
-        "context_pack":      ("kg", ["context"]),
-        "get_impact":        ("kg", ["impact"]),
-        "context_360":       ("kg", ["context360"]),
-        "coverage_matrix":   ("kg", ["coverage"]),
-        "feature_overview":  ("kg", ["feature"]),
-        "get_workflow":      ("kg", ["workflow"]),
-        "multi_hop":         ("kg", ["hop"]),
-        "search_wiki":       ("kg", ["wiki"]),
-        "fill_prototype":    ("kg", ["fill-prototype"]),
-        "get_design_system": ("kg", ["design-system"]),
-        # RAG/GraphRAG 降级映射（MCP 挂时走本地 wlkj.py kg search，语义降级为关键词）
-        "rag_search":        ("kg", ["search"]),
-        "ask_corpus":        ("kg", ["search"]),
-        # 学习工具降级（MCP 挂时本地无 learning 表，返回提示）
-        "learn":             ("noop", []),
-        "get_learnings":     ("noop", []),
-        "list_tasks":        ("task", ["list"]),
-        "create_task":       ("task", ["create"]),
-        "start_task":        ("task", ["start"]),
-        "finish_task":       ("task", ["finish"]),
-    }
-
-    def _cli_fallback(self, tool_name: str, args: dict) -> Optional[str]:
-        """MCP 工具名 → wlkj.py 执行。无映射返回 None。"""
-        # ★ 递归守卫：search_code→kg search→search_index→call_remote→call→_cli_fallback 会无限套娃。
-        # 已在降级子进程内（_run_wlkj 设了 _WLKJ_IN_CLI_FALLBACK=1）则直接放弃降级，返回原始错误。
-        import os as _os
-        if _os.environ.get("_WLKJ_IN_CLI_FALLBACK"):
-            return None
-        entry = self._TOOL_TO_WLKJ.get(tool_name)
-        if entry is None:
-            return None
-        cmd, base_args = entry
-        # noop 类工具（learn/get_learnings 等）：本地无等价 CLI，返回提示不崩
-        if cmd == "noop":
-            return json.dumps({"degraded": True, "message": "MCP不可用，该工具(learning)降级跳过"}, ensure_ascii=False)
-        cli_args = list(base_args)
-        # 从 MCP args 构建命令行参数。
-        # 参数名对齐: 平台 MCP search 工具入参是 query, 引擎命令文档用 keyword。
-        # 这里两边都取值, 确保无论上游传哪个都能落到 CLI 查询词上。
-        kw = args.get("keyword") or args.get("query")
-        if kw is not None:
-            cli_args.append(str(kw))
-        if "platform" in args and args["platform"]:
-            cli_args.extend(["--platform", str(args["platform"])])
-        if "role" in args and args["role"]:
-            cli_args.extend(["--role", str(args["role"])])
-        if "endpoint" in args:
-            cli_args.append(str(args["endpoint"]))
-        if "symbol" in args:
-            cli_args.append(str(args["symbol"]))
-        if "depth" in args:
-            cli_args.extend(["--depth", str(args["depth"])])
-        if "feature" in args:
-            cli_args.append(str(args["feature"]))
-        if "module" in args:
-            cli_args.append(str(args["module"]))
-        if "title" in args:
-            cli_args.append(str(args["title"]))
-        if "table" in args:
-            cli_args.append(str(args["table"]))
-        if "column" in args:
-            cli_args.append(str(args["column"]))
-        if "db" in args and args["db"]:
-            cli_args.extend(["--db", str(args["db"])])
-        if "env" in args and args["env"]:
-            cli_args.extend(["--env", str(args["env"])])
-        return self._run_wlkj(cmd, cli_args)
-
-    @staticmethod
-    def _run_wlkj(cmd: str, args: list) -> str:
-        """调 wlkj.py 执行，返回 stdout。"""
-        import subprocess, sys, os
-        try:
-            from foundation.core.paths import get_repo_root
-            repo = str(get_repo_root())
-        except Exception:
-            repo = os.getcwd()
-        wlkj = os.path.join(repo, ".qoder", "scripts", "orchestration", "wlkj.py")
-        try:
-            # 递归守卫：子进程内 _WLKJ_IN_CLI_FALLBACK=1，其 McpCap 不再降级（否则套娃）
-            env = dict(os.environ, _WLKJ_IN_CLI_FALLBACK="1")
-            r = subprocess.run(
-                [sys.executable, wlkj, cmd] + args,
-                capture_output=True, text=True, timeout=60,
-                encoding="utf-8", errors="replace", env=env,
-            )
-            if r.returncode == 0:
-                return r.stdout.strip()
-            return "[cli-fallback error] %s" % (r.stderr or r.stdout)[:200]
-        except subprocess.TimeoutExpired:
-            return "[cli-fallback error] timeout (60s)"
-        except Exception as e:
-            return "[cli-fallback error] %s" % str(e)[:100]
-
-    def list_tools(self, keyword: str = "") -> list[dict]:
-        """枚举可用 MCP 工具（可选按 keyword 过滤）。"""
-        try:
-            self._registry._ensure_index()
-            tools = []
-            for server_name in self._registry._servers:
-                t = self._registry._pool.get(server_name)
-                if t is None:
-                    continue
-                for tool in (t._tools_cache or []):
-                    if keyword and keyword not in tool.get("name", ""):
-                        continue
-                    tool_copy = dict(tool)
-                    tool_copy["_server"] = server_name
-                    tools.append(tool_copy)
-            return tools
-        except Exception:
-            return []
-
-    def describe(self) -> dict:
-        """诊断：各 server 状态。"""
-        try:
-            return self._registry.describe()
-        except Exception as e:
-            return {"error": str(e)[:120]}
-
-
-class McpMemoryProvider:
-    """memory 职责链的 MCP provider —— 接通平台 PG.learning_patterns。
-
-    设计模式: Adapter（把平台 MCP get_learnings/learn 适配成 MemoryCap 契约）
-
-    职责链位置: 链头优先。平台 MCP 可用（has_tool get_learnings）时抢占，
-    复用项目级学习表（PG.learning_patterns，按 token 解析 pid 隔离，跨会话积累）。
-
-    数据源: 平台 MCP 工具 get_learnings / learn（后端 services.knowledge.learn）。
-    """
-
-    def __init__(self):
-        self._registry = None  # 懒取 MCP 单例（避免 import 时即连后端）
-
-    def _reg(self):
-        """复用 McpCap 同款模块级单例（_get_registry），零重复 spawn。"""
-        if self._registry is None:
-            self._registry = _get_registry()
-        return self._registry
-
-    @property
-    def available(self) -> bool:
-        """平台 MCP 可用且 get_learnings 工具在索引中即为可用。
-        全迁 PG 后记忆走平台 get_learnings（PG.learning_patterns，按项目隔离）。
-        """
-        try:
-            return self._reg().has_tool("get_learnings")
-        except Exception:
-            return False
-
-    def recall(self, query: str) -> list[dict]:
-        """检索记忆: 取平台学习记录，按 query 模糊过滤 pattern/category。"""
-        if not self.available:
-            return []
-        try:
-            import json as _json
-            result = self._reg().call("get_learnings", {"limit": 50})
-            text = getattr(result, "text", "") or ""
-            data = _json.loads(text) if text else {}
-            items = data.get("items", []) if isinstance(data, dict) else []
-            q = (query or "").lower()
-            out = []
-            for it in items:
-                hay = "%s %s" % (it.get("category", ""), it.get("pattern", ""))
-                if not q or q in hay.lower():
-                    out.append({
-                        "event": it.get("category", ""),
-                        "data": it.get("pattern", ""),
-                        "ts": it.get("last_seen", ""),
-                        "dev": ",".join(it.get("source_devs", []) or []),
-                    })
-            return out[:20]
-        except Exception:
-            return []
-
-    def remember(self, key: str, content: str) -> None:
-        """写入一条记忆: 调平台 learn（PG.learning_patterns 累加）。"""
-        if not self.available:
-            return
-        try:
-            self._reg().call("learn", {
-                "category": "rule",
-                "pattern": "%s: %s" % (key, content[:500]),
-                "source": "engine/memory",
-            })
-        except Exception:
-            pass  # 写入失败不阻塞
-
-    def get_fact(self, key: str) -> str | None:
-        """按 key 取一条事实，无则 None。"""
-        results = self.recall(key)
-        return results[0].get("data") if results else None
-
-    def list_recent(self, limit: int = 10) -> list[dict]:
-        """最近 N 条记忆（平台按 frequency 倒序返回）。"""
-        if not self.available:
-            return []
-        try:
-            import json as _json
-            result = self._reg().call("get_learnings", {"limit": limit})
-            text = getattr(result, "text", "") or ""
-            data = _json.loads(text) if text else {}
-            items = data.get("items", []) if isinstance(data, dict) else []
-            return [{"event": it.get("category", ""), "data": it.get("pattern", ""),
-                     "ts": it.get("last_seen", ""), "dev": ",".join(it.get("source_devs", []) or [])}
-                    for it in items[:limit]]
-        except Exception:
-            return []
-
+# -*- coding: utf-8 -*-
+"""
+adapters.mcp —— L1 MCP 能力统一入口（已接通 transport 层）。
+
+设计模式: Adapter + Facade
+
+职责：
+    把 McpRegistry（tool→server→transport 路由）适配成 McpCap 的
+    has_tool/call/list_tools 接口，供 Nexus Facade 统一暴露。
+
+L1 能力定位：禅道/知识图谱/MySQL/蓝湖/playwright 已 MCP 化，
+    通过本入口跨宿主统一调用，复用已有 MCP 资产，绝不重写它们。
+
+跨宿主行为：
+    - QoderWork / 任意宿主：通过 mcp_launcher spawn 本地 MCP server（stdio transport）
+    - 未来服务器：改 McpRegistry.SERVERS 配置 kind=http + url，工作流零改动
+    - 无可用 server：available=False，has_tool 返回 False（静默回退）
+
+McpMemoryProvider：memory 职责链的 MCP provider，接通 kg.duckdb learning_events 表。
+    当 mem0/Zep MCP server 更成熟时可替换为 MCP 版本，接口不变。
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..registry_mcp import McpRegistry, _load_servers
+from protocol.transports import ToolResult
+
+
+# 单例 Registry（同一进程复用进程池，避免重复 spawn）
+_REGISTRY: Optional[McpRegistry] = None
+
+
+def _get_registry() -> McpRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = McpRegistry()
+    return _REGISTRY
+
+
+class McpCap:
+    """L1 MCP 能力统一入口 —— 复用已有 MCP server（禅道/知识图谱/MySQL/蓝湖）。
+
+    工作流调用：
+        cap = resolve()
+        result = cap.mcp.call("search_code", {"keyword": "保险"})
+        # 自动路由：MCP 可用走 MCP，不可用走 wlkj.py（CLI 降级）
+    """
+
+    def __init__(self, mcp_servers=None):
+        # ★ 空 mcp_servers (= [] 或 None) 视为"不限制 = 用全部本地 server"。
+        # 原版: mcp_servers=[] (空列表, is not None) → filtered 成空 → _servers={} → 0 工具,
+        # 整个 cap.mcp 自废武功。但本地 stdio transport (StdioTransport) 通过 mcp_launcher
+        # spawn 子进程, 不依赖宿主是否原生支持 MCP —— CLI / Codex / Claude 同样能起 server。
+        # 故: 宿主未声明 mcp_servers 或声明为空 = "没有宿主原生限制, 用全部本地可起的"。
+        if mcp_servers:  # 非空列表才过滤
+            # 用 _load_servers() 而非硬编码 SERVERS —— 这样 mcp_config.json 改配置才生效
+            all_servers = _load_servers()
+            filtered = {k: v for k, v in all_servers.items() if k in mcp_servers}
+            self._registry = McpRegistry(servers=filtered)
+        else:
+            self._registry = _get_registry()
+
+    @property
+    def available(self) -> bool:
+        """是否有任一 MCP server 可用。"""
+        try:
+            return self._registry.available()
+        except Exception:
+            return False
+
+    # ------------------------------------------------------------------
+    # McpCap 接口
+    # ------------------------------------------------------------------
+
+    def has_tool(self, name: str) -> bool:
+        """某 MCP 工具是否可用（跨所有已配置 server 查找）。"""
+        try:
+            return self._registry.has_tool(name)
+        except Exception:
+            return False
+
+    def call(self, name: str, args: Optional[dict] = None,
+             server: Optional[str] = None) -> ToolResult:
+        """调用 MCP 工具（自动 CLI 降级）。
+
+        优先走 MCP；MCP 不可用时自动降级到 wlkj.py CLI 脚本。
+        工作流永远写 cap.mcp.call("tool_name", args)，零宿主感知。
+        """
+        # 1. MCP 可用 → 走 MCP
+        result = self._registry.call(name, args, server=server)
+        if not result.is_error:
+            return result
+        # 2. CLI 降级（MCP 不可用或调用失败）
+        cli_text = self._cli_fallback(name, args or {})
+        if cli_text is not None:
+            return ToolResult(text=cli_text)
+        return result  # 无降级映射，返回原始错误
+
+    # ------------------------------------------------------------------
+    # CLI 降级（MCP 不可用时走 wlkj.py）
+    # ------------------------------------------------------------------
+
+    # MCP 工具名 → (wlkj 命令, 基础参数) 映射
+    # 只映射有 wlkj.py 对应的知识图谱/任务工具。
+    # MySQL/禅道/蓝湖等 MCP 专属工具不映射（MCP 不可用时返回错误提示）。
+    _TOOL_TO_WLKJ = {
+        "search_code":       ("kg", ["search"]),
+        "search_api":        ("kg", ["api"]),
+        "search_prd":        ("kg", ["prd"]),
+        "context_pack":      ("kg", ["context"]),
+        "get_impact":        ("kg", ["impact"]),
+        "context_360":       ("kg", ["context360"]),
+        "coverage_matrix":   ("kg", ["coverage"]),
+        "feature_overview":  ("kg", ["feature"]),
+        "get_workflow":      ("kg", ["workflow"]),
+        "multi_hop":         ("kg", ["hop"]),
+        "search_wiki":       ("kg", ["wiki"]),
+        "fill_prototype":    ("kg", ["fill-prototype"]),
+        "get_design_system": ("kg", ["design-system"]),
+        # RAG/GraphRAG 降级映射（MCP 挂时走本地 wlkj.py kg search，语义降级为关键词）
+        "rag_search":        ("kg", ["search"]),
+        "ask_corpus":        ("kg", ["search"]),
+        # 学习工具降级（MCP 挂时本地无 learning 表，返回提示）
+        "learn":             ("noop", []),
+        "get_learnings":     ("noop", []),
+        "list_tasks":        ("task", ["list"]),
+        "create_task":       ("task", ["create"]),
+        "start_task":        ("task", ["start"]),
+        "finish_task":       ("task", ["finish"]),
+    }
+
+    def _cli_fallback(self, tool_name: str, args: dict) -> Optional[str]:
+        """MCP 工具名 → wlkj.py 执行。无映射返回 None。"""
+        entry = self._TOOL_TO_WLKJ.get(tool_name)
+        if entry is None:
+            return None
+        cmd, base_args = entry
+        # noop 类工具（learn/get_learnings 等）：本地无等价 CLI，返回提示不崩
+        if cmd == "noop":
+            return json.dumps({"degraded": True, "message": "MCP不可用，该工具(learning)降级跳过"}, ensure_ascii=False)
+        cli_args = list(base_args)
+        # 从 MCP args 构建命令行参数。
+        # 参数名对齐: 平台 MCP search 工具入参是 query, 引擎命令文档用 keyword。
+        # 这里两边都取值, 确保无论上游传哪个都能落到 CLI 查询词上。
+        kw = args.get("keyword") or args.get("query")
+        if kw is not None:
+            cli_args.append(str(kw))
+        if "platform" in args and args["platform"]:
+            cli_args.extend(["--platform", str(args["platform"])])
+        if "role" in args and args["role"]:
+            cli_args.extend(["--role", str(args["role"])])
+        if "endpoint" in args:
+            cli_args.append(str(args["endpoint"]))
+        if "symbol" in args:
+            cli_args.append(str(args["symbol"]))
+        if "depth" in args:
+            cli_args.extend(["--depth", str(args["depth"])])
+        if "feature" in args:
+            cli_args.append(str(args["feature"]))
+        if "module" in args:
+            cli_args.append(str(args["module"]))
+        if "title" in args:
+            cli_args.append(str(args["title"]))
+        if "table" in args:
+            cli_args.append(str(args["table"]))
+        if "column" in args:
+            cli_args.append(str(args["column"]))
+        if "db" in args and args["db"]:
+            cli_args.extend(["--db", str(args["db"])])
+        if "env" in args and args["env"]:
+            cli_args.extend(["--env", str(args["env"])])
+        return self._run_wlkj(cmd, cli_args)
+
+    @staticmethod
+    def _run_wlkj(cmd: str, args: list) -> str:
+        """调 wlkj.py 执行，返回 stdout。"""
+        import subprocess, sys, os
+        try:
+            from foundation.core.paths import get_repo_root
+            repo = str(get_repo_root())
+        except Exception:
+            repo = os.getcwd()
+        wlkj = os.path.join(repo, ".qoder", "scripts", "orchestration", "wlkj.py")
+        try:
+            r = subprocess.run(
+                [sys.executable, wlkj, cmd] + args,
+                capture_output=True, text=True, timeout=60,
+                encoding="utf-8", errors="replace",
+            )
+            if r.returncode == 0:
+                return r.stdout.strip()
+            return "[cli-fallback error] %s" % (r.stderr or r.stdout)[:200]
+        except subprocess.TimeoutExpired:
+            return "[cli-fallback error] timeout (60s)"
+        except Exception as e:
+            return "[cli-fallback error] %s" % str(e)[:100]
+
+    def list_tools(self, keyword: str = "") -> list[dict]:
+        """枚举可用 MCP 工具（可选按 keyword 过滤）。"""
+        try:
+            self._registry._ensure_index()
+            tools = []
+            for server_name in self._registry._servers:
+                t = self._registry._pool.get(server_name)
+                if t is None:
+                    continue
+                for tool in (t._tools_cache or []):
+                    if keyword and keyword not in tool.get("name", ""):
+                        continue
+                    tool_copy = dict(tool)
+                    tool_copy["_server"] = server_name
+                    tools.append(tool_copy)
+            return tools
+        except Exception:
+            return []
+
+    def describe(self) -> dict:
+        """诊断：各 server 状态。"""
+        try:
+            return self._registry.describe()
+        except Exception as e:
+            return {"error": str(e)[:120]}
+
+
+class McpMemoryProvider:
+    """memory 职责链的 MCP provider —— 接通平台 PG.learning_patterns。
+
+    设计模式: Adapter（把平台 MCP get_learnings/learn 适配成 MemoryCap 契约）
+
+    职责链位置: 链头优先。平台 MCP 可用（has_tool get_learnings）时抢占，
+    复用项目级学习表（PG.learning_patterns，按 token 解析 pid 隔离，跨会话积累）。
+
+    数据源: 平台 MCP 工具 get_learnings / learn（后端 services.knowledge.learn）。
+    """
+
+    def __init__(self):
+        self._registry = None  # 懒取 MCP 单例（避免 import 时即连后端）
+
+    def _reg(self):
+        """复用 McpCap 同款模块级单例（_get_registry），零重复 spawn。"""
+        if self._registry is None:
+            self._registry = _get_registry()
+        return self._registry
+
+    @property
+    def available(self) -> bool:
+        """平台 MCP 可用且 get_learnings 工具在索引中即为可用。
+        全迁 PG 后记忆走平台 get_learnings（PG.learning_patterns，按项目隔离）。
+        """
+        try:
+            return self._reg().has_tool("get_learnings")
+        except Exception:
+            return False
+
+    def recall(self, query: str) -> list[dict]:
+        """检索记忆: 取平台学习记录，按 query 模糊过滤 pattern/category。"""
+        if not self.available:
+            return []
+        try:
+            import json as _json
+            result = self._reg().call("get_learnings", {"limit": 50})
+            text = getattr(result, "text", "") or ""
+            data = _json.loads(text) if text else {}
+            items = data.get("items", []) if isinstance(data, dict) else []
+            q = (query or "").lower()
+            out = []
+            for it in items:
+                hay = "%s %s" % (it.get("category", ""), it.get("pattern", ""))
+                if not q or q in hay.lower():
+                    out.append({
+                        "event": it.get("category", ""),
+                        "data": it.get("pattern", ""),
+                        "ts": it.get("last_seen", ""),
+                        "dev": ",".join(it.get("source_devs", []) or []),
+                    })
+            return out[:20]
+        except Exception:
+            return []
+
+    def remember(self, key: str, content: str) -> None:
+        """写入一条记忆: 调平台 learn（PG.learning_patterns 累加）。"""
+        if not self.available:
+            return
+        try:
+            self._reg().call("learn", {
+                "category": "rule",
+                "pattern": "%s: %s" % (key, content[:500]),
+                "source": "engine/memory",
+            })
+        except Exception:
+            pass  # 写入失败不阻塞
+
+    def get_fact(self, key: str) -> str | None:
+        """按 key 取一条事实，无则 None。"""
+        results = self.recall(key)
+        return results[0].get("data") if results else None
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        """最近 N 条记忆（平台按 frequency 倒序返回）。"""
+        if not self.available:
+            return []
+        try:
+            import json as _json
+            result = self._reg().call("get_learnings", {"limit": limit})
+            text = getattr(result, "text", "") or ""
+            data = _json.loads(text) if text else {}
+            items = data.get("items", []) if isinstance(data, dict) else []
+            return [{"event": it.get("category", ""), "data": it.get("pattern", ""),
+                     "ts": it.get("last_seen", ""), "dev": ",".join(it.get("source_devs", []) or [])}
+                    for it in items[:limit]]
+        except Exception:
+            return []
+