@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/capability/chain.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+ProviderChain —— 能力 Provider 职责链。
+
+设计模式:
+    - Chain of Responsibility（职责链）: 按优先级遍历，第一个 available 的命中
+    - Strategy（策略组合）: 每个 provider 是一种策略实现
+    - Decorator（装饰器）: 可选地对命中的 provider 增强（缓存/日志/统计）
+
+透明代理: ProviderChain 把方法调用转发给命中的 provider，
+          对调用方而言与直接用 Cap 无异。
+
+    chain = ProviderChain([McpMemoryProvider(), QwMemoryCap(),
+                           FileMemoryCap(), NoOpMemoryCap()])
+    chain.recall("本周执行")   # 自动代理到第一个 available 的 provider
+
+链尾永远是 NoOp，保证无能力时不抛错（Null Object 兜底）。
+
+演进（扩展场景 C: 能力 MCP 化迁移）:
+    mem0 MCP server 成熟 → 链头插入 McpMemoryProvider →
+    available=True 自动抢占 → 旧的 QwMemoryCap 沉到链尾静默退役 →
+    调用方代码零改动。这就是"未来 vs 现实"的机制化。
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class ProviderChain:
+    """能力 Provider 职责链。
+
+    Args:
+        providers: 按优先级排列的 provider 列表，链尾应为 NoOp。
+        decorators: 可选装饰器列表，每个形式 func(provider_method, provider) -> wrapped，
+                    对命中的 provider 的方法做增强（缓存/日志/降级统计），不改原 provider。
+    """
+
+    def __init__(self, providers: list, decorators: list | None = None):
+        # 用 object.__setattr__ 绕过自定义 __getattr__，避免初始化期递归
+        object.__setattr__(self, "_providers", list(providers))
+        object.__setattr__(self, "_decorators", list(decorators or []))
+        object.__setattr__(self, "_active", None)
+        object.__setattr__(self, "_probed", False)
+
+    @property
+    def available(self) -> bool:
+        """是否有任一 provider 可用。"""
+        return self._probe() is not None
+
+    def _probe(self) -> Any:
+        """返回第一个 available 的 provider，缓存结果（首次探测后不再变）。"""
+        if self._probed:
+            return self._active
+        for p in self._providers:
+            if getattr(p, "available", False):
+                object.__setattr__(self, "_active", p)
+                break
+        object.__setattr__(self, "_probed", True)
+        return self._active
+
+    def providers_status(self) -> list[dict]:
+        """诊断用：每个 provider 的 available 状态 + 是否命中。"""
+        active = self._probe()
+        return [
+            {
+                "provider": type(p).__name__,
+                "available": bool(getattr(p, "available", False)),
+                "hit": p is active,
+            }
+            for p in self._providers
+        ]
+
+    def __getattr__(self, name: str) -> Any:
+        """透明代理：把属性/方法调用转发给命中的 provider。
+
+        调用方写 chain.recall(q) 等价于 active_provider.recall(q)。
+        若无任何 provider available，用链尾（NoOp）兜底，绝不抛错。
+        """
+        if name.startswith("_"):
+            raise AttributeError(name)
+        active = self._probe()
+        if active is None:
+            # 兜底：链尾 NoOp
+            active = self._providers[-1] if self._providers else None
+        if active is None:
+            raise AttributeError(f"ProviderChain 无 provider 可解析 '{name}'")
+        attr = getattr(active, name)
+        # 应用装饰器（仅对可调用方法）
+        if callable(attr) and self._decorators:
+            for dec in self._decorators:
+                attr = dec(attr, active)
+        return attr

package/templates/qoder/scripts/capability/memory_chain.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""
+memory 能力职责链装配。
+
+设计模式: Provider Chain + Strategy
+
+独立成文件的理由: memory 是最复杂的 L2 能力（4 个 provider），
+未来加 provider（如向量库、mem0 MCP）只改本文件，不动 registry ——
+体现 Plugin/SPI：新实现接入不改核心。
+
+优先级（高→低）:
+    ① McpMemoryProvider  —— 未来 mem0/Zep MCP server（现状 available=False）
+    ② QwMemoryCap        —— QoderWork 原生（仅 qoderwork 宿主）
+    ③ FileMemoryCap      —— 文件降级（纯 CLI/任意宿主）
+    ④ NoOpMemoryCap      —— 兜底（绝不抛错）
+
+演进（扩展场景 C）: mem0 MCP 成熟 → 把 McpMemoryProvider 的 available 打开 →
+              自动抢占链头 → FileMemoryCap/QwMemoryCap 静默退役 → 调用方零改动。
+"""
+from __future__ import annotations
+
+from .chain import ProviderChain
+from .caps import NoOpMemoryCap
+
+
+def build_memory_chain(host: str) -> ProviderChain:
+    """装配 memory 职责链。
+
+    Args:
+        host: detect_host() 返回的宿主名。
+    """
+    from .adapters.mcp import McpMemoryProvider
+    from .adapters.cli import FileMemoryCap
+
+    providers: list = [McpMemoryProvider()]
+    if host == "qoderwork":
+        from .adapters.qw import QwMemoryCap
+        providers.append(QwMemoryCap())
+    providers.append(FileMemoryCap())
+    providers.append(NoOpMemoryCap())
+    return ProviderChain(providers)

package/templates/qoder/scripts/capability/registry.py

@@ -0,0 +1,246 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.registry —— 宿主发现 + Nexus Facade。
+
+设计模式:
+    - Registry（HOST_TABLE 单一事实源，泛化 common.active_task._ENV_SESSION_KEYS）
+    - Facade（resolve() 一行入口）
+    - Bridge（Cap 抽象 × 宿主实现 正交）
+
+主轴: 工作流面向能力编程，不面向宿主。
+    cap = nexus.resolve()
+    cap.memory.recall(...)   # 不管在 QoderWork 还是 CLI，同一行代码
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .caps import (
+    NoOpCronCap,
+    NoOpNotifyCap,
+    NoOpPresentCap,
+    NoOpSandboxCap,
+)
+
+
+# =============================================================================
+# HOST_TABLE —— 宿主注册表
+# -----------------------------------------------------------------------------
+# 泛化 common/active_task.py:_ENV_SESSION_KEYS 的 7 宿主表：
+#   从"只探测身份"扩展为"身份 + 能力清单"。
+#
+# 现在最小形态: Python dict。
+# 未来完整形态: manifests/*.yaml 声明式文件（每宿主一份）。
+# 迁移路径: dict → yaml，resolve() 接口不变，工作流零改动。
+# =============================================================================
+
+HOST_TABLE: dict[str, dict] = {
+    # ── Qoder 产品线（第一宿主系列）─────────────────────────────
+    "qoder-work": {
+        "detect": ("QODER_SESSION_ID",),
+        # features = 当前已实现 (非 NoOp) 的能力。notify/present/sandbox 暂无
+        # 宿主原生 Adapter，声明即误报可用，故不列。后续补齐 Adapter 再加。
+        "features": ("mcp", "memory", "cron"),
+        "mcp_servers": ["qoder-knowledge-graph", "qoder-zentao", "qoder-mysql", "lanhu"],
+        "note": "QoderWork 桌面 Agent，全能力",
+    },
+    "qoder-ide": {
+        "detect": ("QODER_IDE",),
+        "features": ("mcp", "memory"),
+        "mcp_servers": ["qoder-knowledge-graph", "qoder-zentao", "qoder-mysql"],
+        "note": "Qoder IDE (VSCode 扩展)",
+    },
+    "qoder-quest": {
+        "detect": ("QODER_QUEST",),
+        "features": ("mcp", "memory"),
+        "mcp_servers": ["qoder-knowledge-graph", "qoder-zentao"],
+        "note": "Qoder Quest，自然语言入口",
+    },
+    # ── 其他宿主（通用 AI 工具）────────────────────────────────
+    "codex": {
+        "detect": ("CODEX_SESSION_ID", "CODEX_THREAD_ID"),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+        "note": "OpenAI Codex CLI",
+    },
+    "claude": {
+        "detect": ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID"),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+        "note": "Claude Code",
+    },
+    "cursor": {
+        "detect": ("CURSOR_SESSION_ID",),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+    },
+    "opencode": {
+        "detect": ("OPENCODE_SESSION_ID", "OPENCODE_RUN_ID"),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+    },
+    "gemini": {
+        "detect": ("GEMINI_SESSION_ID",),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+    },
+    "copilot": {
+        "detect": ("COPILOT_SESSION_ID",),
+        "features": ("repo", "identity"),
+        "mcp_servers": [],
+    },
+    # ── 兜底 ──────────────────────────────────────────────────
+    "cli": {
+        "detect": (),  # 兜底：无 env 命中即为 CLI / 任意宿主
+        "features": ("repo", "identity", "context", "memory", "mcp"),
+        # 本地 stdio transport 经 mcp_launcher spawn 子进程, 不依赖宿主原生 MCP。
+        # 故 CLI 能起全部本地 server (kg/zentao/mysql/lanhu), 与 QoderWork 等价。
+        "mcp_servers": ["qoder-knowledge-graph", "qoder-zentao", "qoder-mysql", "lanhu"],
+        "note": "纯 CLI 兜底; MCP 走本地 spawn (非宿主原生), 其余走文件降级",
+    },
+}
+
+
+def detect_host() -> str:
+    """探测当前宿主名。
+
+    遍历 HOST_TABLE，第一个 env 命中的返回；无则 'cli'。
+    单一事实源 —— 替代散落在 active_task / autotest / mcp_launcher 的多处宿主探测。
+    """
+    for name, info in HOST_TABLE.items():
+        if name == "cli":
+            continue
+        for env_var in info.get("detect", ()):
+            if os.environ.get(env_var):
+                return name
+    return "cli"
+
+
+# =============================================================================
+# Nexus Facade
+# =============================================================================
+
+class Nexus:
+    """宿主能力 Facade —— 聚合所有能力，对外统一入口。
+
+    工作流永远只调 nexus.resolve() 拿到本对象，再访问 .memory/.mcp/...，
+    不直接 import 任何 adapter（Facade 模式）。
+    """
+
+    def __init__(self, host_name: str, repo, identity, context, memory,
+                 cron, notify, present, sandbox, mcp):
+        self.host_name = host_name
+        self.repo = repo
+        self.identity = identity
+        self.context = context
+        self.memory = memory
+        self.cron = cron
+        self.notify = notify
+        self.present = present
+        self.sandbox = sandbox
+        self.mcp = mcp
+
+    def describe(self) -> dict:
+        """诊断：当前宿主 + 各能力 available 状态。"""
+        return {
+            "host": self.host_name,
+            "capabilities": {
+                "repo": _avail(self.repo),
+                "identity": _avail(self.identity),
+                "context": _avail(self.context),
+                "memory": _avail(self.memory),
+                "cron": _avail(self.cron),
+                "notify": _avail(self.notify),
+                "present": _avail(self.present),
+                "sandbox": _avail(self.sandbox),
+                "mcp": _avail(self.mcp),
+            },
+        }
+
+
+def _avail(cap) -> bool:
+    return bool(getattr(cap, "available", False))
+
+
+# =============================================================================
+# 能力装配（Bridge: Cap 抽象 × 宿主实现 正交）
+# -----------------------------------------------------------------------------
+# 每个 _resolve_xxx 是一个能力的装配点。新增能力（场景 B）= 加一个 _resolve_xxx
+# + Nexus 属性。新增宿主实现 = 在对应 _resolve_xxx 里按 host 名分支。
+# =============================================================================
+
+def _resolve_repo(host: str):
+    """核心能力：所有宿主都用文件降级版（无 ~/.qoderwork 依赖）。"""
+    from .adapters.cli import FileRepoCap
+    return FileRepoCap()
+
+
+def _resolve_identity(host: str):
+    from .adapters.cli import FileIdentityCap
+    return FileIdentityCap()
+
+
+def _resolve_context(host: str):
+    from .adapters.cli import FileContextCap
+    return FileContextCap()
+
+
+def _resolve_memory(host: str):
+    """memory —— 职责链样板（见 memory_chain.py）。"""
+    from .memory_chain import build_memory_chain
+    return build_memory_chain(host)
+
+
+def _resolve_cron(host: str):
+    from .adapters.qw import QwCronCap
+    return QwCronCap()  # 文件系统 cron，不依赖宿主
+
+
+def _resolve_notify(host: str):
+    return NoOpNotifyCap()
+
+
+def _resolve_present(host: str):
+    """L2 富展示 —— QoderWork 调 qoder_show_widget 嵌入对话; 其余 NoOp 降级表格。"""
+    if host in ("qoder-work", "qoder-ide"):
+        try:
+            from .adapters.qw import QwPresentCap
+            return QwPresentCap()
+        except Exception:
+            pass
+    return NoOpPresentCap()
+
+
+def _resolve_sandbox(host: str):
+    return NoOpSandboxCap()
+
+
+def _resolve_mcp(host: str):
+    """L1 MCP 统一入口 —— 根据宿主声明的 mcp_servers 决定 spawn 哪些。"""
+    from .adapters.mcp import McpCap
+    info = HOST_TABLE.get(host, {})
+    mcp_servers = info.get("mcp_servers")
+    return McpCap(mcp_servers=mcp_servers)
+
+
+def resolve() -> Nexus:
+    """解析当前环境，返回 Nexus Facade。
+
+    一行入口: cap = nexus.resolve()
+    内部: detect_host → 按宿主装配各 Cap → 注入 NoOp 兜底。
+    工作流代码零宿主感知。
+    """
+    host = detect_host()
+    return Nexus(
+        host_name=host,
+        repo=_resolve_repo(host),
+        identity=_resolve_identity(host),
+        context=_resolve_context(host),
+        memory=_resolve_memory(host),
+        cron=_resolve_cron(host),
+        notify=_resolve_notify(host),
+        present=_resolve_present(host),
+        sandbox=_resolve_sandbox(host),
+        mcp=_resolve_mcp(host),
+    )

package/templates/qoder/scripts/capability/registry_mcp.py

@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.registry_mcp —— MCP 工具路由（tool → server → transport）。
+
+设计模式: Registry + Strategy（配合 transports 层）
+
+职责：
+    1. 声明现有 MCP server 清单及其默认 transport（配置驱动，留远程化扩展点）。
+    2. 维护 server → Transport 实例池（复用子进程/连接）。
+    3. 构建 tool 名 → server 名 的反向索引（懒加载，首次需要时遍历 tools/list）。
+    4. resolve_tool(tool_name) → 该 tool 所在 server 的 Transport。
+
+扩展点（配置驱动远程化）：
+    未来知识图谱上服务器，把 SERVERS["qoder-knowledge-graph"]["kind"] 改成 "http"
+    + 填 url，工作流 (cap.mcp.call) 零改动。
+    这是"满足现在同时留扩展给未来"的核心机制。
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from protocol.transports import get_transport, Transport, NoOpTransport, ToolResult
+
+
+# =============================================================================
+# SERVERS —— MCP server 清单 + 默认 transport 配置（单一事实源）
+# -----------------------------------------------------------------------------
+# 每个条目：
+#   kind:   传输方式 ("stdio"|"cli"|"http")
+#   launcher_arg: mcp_launcher 接受的子名（多数同 key）
+#   url:    http 时的远程 endpoint（stdio/cli 不用）
+# 未来改这里即可切换部署形态，工作流零改动。
+# =============================================================================
+
+SERVERS: dict[str, dict] = {
+    "qoder-knowledge-graph": {
+        "kind": "stdio",
+        "launcher_arg": "kg",
+        "note": "知识图谱。本地分发；未来可上服务器 → 改 kind=http + url",
+    },
+    "qoder-zentao": {
+        "kind": "stdio",
+        "launcher_arg": "zentao",
+        "note": "禅道任务/Bug/需求",
+    },
+    "qoder-mysql": {
+        "kind": "stdio",
+        "launcher_arg": "mysql",
+        "note": "只读 MySQL 结构/数据",
+    },
+    "lanhu": {
+        "kind": "stdio",
+        "launcher_arg": "lanhu",
+        "note": "蓝湖设计稿",
+    },
+}
+
+
+def _get_repo_root() -> Path:
+    """从 common.paths 获取仓库根（复用既有工具，不重复造轮子）。"""
+    try:
+        from foundation.core.paths import get_repo_root
+        return get_repo_root()
+    except Exception:
+        return Path(__file__).resolve().parent.parent.parent.parent
+
+
+class McpRegistry:
+    """MCP 工具路由 + Transport 实例池。
+
+    线程安全说明：实例池按 server 名缓存 Transport，每个 Transport 自带锁。
+    反向索引构建期间对多 server 并发（线程池），构建后只读。
+    """
+
+    def __init__(self, repo_root: Optional[Path] = None, servers: Optional[dict] = None):
+        self._repo = repo_root or _get_repo_root()
+        self._servers = servers if servers is not None else SERVERS
+        self._pool: dict[str, Transport] = {}
+        self._tool_to_server: Optional[dict[str, str]] = None  # 懒构建
+        self._index_lock_built = False
+
+    # ------------------------------------------------------------------
+    # Transport 实例池
+    # ------------------------------------------------------------------
+
+    def _get_or_create(self, server_name: str) -> Transport:
+        """按 server 名取/建 Transport 实例（复用）。"""
+        if server_name not in self._pool:
+            cfg = self._servers.get(server_name, {})
+            kind = cfg.get("kind", "stdio")
+            launcher_arg = cfg.get("launcher_arg", server_name)
+            if kind == "stdio":
+                self._pool[server_name] = get_transport(
+                    launcher_arg, kind="stdio", repo_root=self._repo,
+                )
+            elif kind == "http":
+                self._pool[server_name] = get_transport(
+                    server_name, kind="http",
+                    url=cfg.get("url", ""), token=cfg.get("token"),
+                )
+            else:
+                self._pool[server_name] = get_transport(
+                    server_name, kind=kind, repo_root=self._repo, **cfg,
+                )
+        return self._pool[server_name]
+
+    # ------------------------------------------------------------------
+    # 反向索引（tool 名 → server 名）
+    # ------------------------------------------------------------------
+
+    def _build_index(self) -> None:
+        """对所有 server 发 tools/list，建 tool→server 反向索引。
+
+        并发构建（各 server 独立 transport，互不干扰）。
+        不可用的 server 跳过（其 tool 不进索引）。
+        """
+        import concurrent.futures
+
+        index: dict[str, str] = {}
+
+        def _probe(server_name: str) -> tuple[str, list[dict]]:
+            try:
+                t = self._get_or_create(server_name)
+                tools = t.list_tools()
+                return server_name, tools
+            except Exception:
+                return server_name, []
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=len(self._servers) or 1) as ex:
+            for server_name, tools in ex.map(_probe, list(self._servers.keys())):
+                for tool in tools:
+                    tname = tool.get("name", "")
+                    if tname:
+                        index[tname] = server_name
+
+        self._tool_to_server = index
+        # ★ 修复: 全空索引不标记为"已建好"。
+        # 原版无论结果如何都设 _index_lock_built=True + 赋空 dict,
+        # 导致 _ensure_index (判 is None) 永不重建 → 一次冷启动竞态失败就永久 0 工具。
+        # 现改为: 空 = 视为未建, 下次调用会重试 (并发冷启动是间歇性的, 重试通常成功)。
+        if index:
+            self._index_lock_built = True
+        else:
+            # 保留 None, 下次 _ensure_index 会重 _build_index
+            self._tool_to_server = None
+
+    def _ensure_index(self) -> None:
+        if self._tool_to_server is None:
+            self._build_index()
+
+    # ------------------------------------------------------------------
+    # 公共 API
+    # ------------------------------------------------------------------
+
+    def resolve_tool(self, tool_name: str) -> Optional[Transport]:
+        """按 tool 名解析其所在 server 的 Transport。未知返回 None。"""
+        self._ensure_index()
+        server = (self._tool_to_server or {}).get(tool_name)
+        if not server:
+            return None
+        return self._get_or_create(server)
+
+    def has_tool(self, tool_name: str) -> bool:
+        """某 tool 是否可用（先查反向索引；未命中尝试解析）。"""
+        self._ensure_index()
+        if tool_name in (self._tool_to_server or {}):
+            return True
+        t = self.resolve_tool(tool_name)
+        if t is None:
+            return False
+        try:
+            return t.has_tool(tool_name)
+        except Exception:
+            return False
+
+    def call(self, tool_name: str, args: Optional[dict] = None,
+             server: Optional[str] = None) -> ToolResult:
+        """调用工具。
+
+        Args:
+            tool_name: 工具名（如 list_execution_tasks）。
+            args: 工具参数。
+            server: 显式指定 server 名（跳过反向索引，避免首次开销）。
+        Returns:
+            ToolResult。未知工具/不可用返回 is_error=True 的空结果，不抛异常。
+        """
+        transport: Transport
+        if server:
+            if server not in self._servers:
+                return ToolResult(text="未知 server: %s" % server, is_error=True)
+            transport = self._get_or_create(server)
+        else:
+            transport = self.resolve_tool(tool_name) or NoOpTransport()
+        if not transport.available:
+            return ToolResult(
+                text="transport 不可用 (server=%s, tool=%s)" % (server or "?", tool_name),
+                is_error=True,
+            )
+        return transport.call_tool(tool_name, args or {})
+
+    def available(self) -> bool:
+        """任一 server 可用即为 True。"""
+        self._ensure_index()
+        return bool(self._tool_to_server)
+
+    def describe(self) -> dict:
+        """诊断：各 server 的 transport 状态 + 已索引工具数 + 延迟 + PID。"""
+        import time as _time
+        self._ensure_index()
+        servers_status = {}
+        for name in self._servers:
+            t = self._pool.get(name)
+            indexed = [tn for tn, sn in (self._tool_to_server or {}).items() if sn == name]
+
+            # latency: 测量 list_tools 的首次延迟（已在 _build_index 期间完成，此处重新测）
+            latency_ms = None
+            if t and t.available:
+                try:
+                    t0 = _time.monotonic()
+                    t.list_tools()  # 有缓存，很快
+                    latency_ms = round((_time.monotonic() - t0) * 1000, 1)
+                except Exception:
+                    pass
+
+            # spawn_pid: stdio transport 的子进程 PID
+            spawn_pid = None
+            if t and hasattr(t, "_proc") and t._proc is not None:
+                spawn_pid = getattr(t._proc, "pid", None)
+
+            servers_status[name] = {
+                "kind": self._servers[name].get("kind", "stdio"),
+                "available": bool(t and t.available),
+                "tools_indexed": len(indexed),
+                "latency_ms": latency_ms,
+                "spawn_pid": spawn_pid,
+            }
+        return {"servers": servers_status, "total_tools": len(self._tool_to_server or {})}
+
+    def close_all(self) -> None:
+        """关闭所有 Transport（进程退出/连接释放）。"""
+        for t in self._pool.values():
+            try:
+                t.close()
+            except Exception:
+                pass
+        self._pool.clear()
+        self._tool_to_server = None
+        self._index_lock_built = False