@hupan56/wlkj 2.7.12 → 3.1.2

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

@@ -0,0 +1,334 @@
+# -*- 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
+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 = nexus.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:  # 非空列表才过滤
+            from ..registry_mcp import SERVERS
+            filtered = {k: v for k, v in 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"]),
+        "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
+        cli_args = list(base_args)
+        # 从 MCP args 构建命令行参数
+        if "keyword" in args:
+            cli_args.append(str(args["keyword"]))
+        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 —— 接通 kg.duckdb learning_events 表。
+
+    设计模式: Adapter（把 kg.duckdb 适配成 MemoryCap 契约）
+
+    职责链位置: 链头优先（available=True），纯 CLI 环境也能用。
+    当 mem0/Zep MCP server 更成熟时，可替换为 MCP 版本，接口不变。
+
+    数据源: kg.duckdb 的 learning_events 表（id, ts, dev, event, data）。
+    复用 learn_aggregate.py 的写入逻辑，保证 CLI 和 MCP 行为一致。
+    """
+
+    def __init__(self):
+        self._available: bool | None = None  # 懒探测
+
+    @property
+    def available(self) -> bool:
+        """kg.duckdb 存在且可读写即为可用。"""
+        if self._available is None:
+            try:
+                from foundation.protocol.duckdb_conn import get_db
+                con = get_db()
+                con.execute("""CREATE TABLE IF NOT EXISTS learning_events (
+                    id TEXT PRIMARY KEY, ts TEXT NOT NULL, dev TEXT NOT NULL,
+                    event TEXT NOT NULL, data JSON)""")
+                con.close()
+                self._available = True
+            except Exception:
+                self._available = False
+        return self._available
+
+    def recall(self, query: str) -> list[dict]:
+        """语义检索记忆: 按 event 或 data 模糊匹配。"""
+        if not self.available:
+            return []
+        try:
+            from foundation.protocol.duckdb_conn import get_db
+            con = get_db()
+            rows = con.execute(
+                """SELECT id, ts, dev, event, data FROM learning_events
+                   WHERE event LIKE '%' || ? || '%' OR data LIKE '%' || ? || '%'
+                   ORDER BY ts DESC LIMIT 20""",
+                [query, query],
+            ).fetchall()
+            con.close()
+            return [
+                {"id": r[0], "ts": r[1], "dev": r[2], "event": r[3], "data": r[4]}
+                for r in rows
+            ]
+        except Exception:
+            return []
+
+    def remember(self, key: str, content: str) -> None:
+        """写入一条记忆: 插入 learning_events 表。"""
+        if not self.available:
+            return
+        try:
+            import hashlib
+            import json
+            import time as _time
+            from foundation.protocol.duckdb_conn import get_db, init_schema
+            con = get_db()
+            init_schema(con)
+            eid = hashlib.md5(("%s:%s:%s" % (key, content, _time.time())).encode()).hexdigest()[:16]
+            ts = _time.strftime("%Y-%m-%dT%H:%M:%S")
+            data = json.dumps({"content": content}, ensure_ascii=False)
+            con.execute(
+                "INSERT OR IGNORE INTO learning_events(id, ts, dev, event, data) VALUES (?,?,?,?,?)",
+                [eid, ts, "", key, data],
+            )
+            con.close()
+        except Exception:
+            pass
+
+    def get_fact(self, key: str) -> str | None:
+        """按 event 精确查找，返回 data 字段（JSON 字符串）。"""
+        if not self.available:
+            return None
+        try:
+            from foundation.protocol.duckdb_conn import get_db
+            con = get_db()
+            row = con.execute(
+                "SELECT data FROM learning_events WHERE event = ? ORDER BY ts DESC LIMIT 1",
+                [key],
+            ).fetchone()
+            con.close()
+            if not row:
+                return None
+            data = row[0]
+            if isinstance(data, str):
+                return data
+            import json as _json
+            return _json.dumps(data, ensure_ascii=False) if data else None
+        except Exception:
+            return None
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        """最近 N 条记忆。"""
+        if not self.available:
+            return []
+        try:
+            import json as _json
+            from foundation.protocol.duckdb_conn import get_db
+            con = get_db()
+            rows = con.execute(
+                "SELECT id, ts, dev, event, data FROM learning_events ORDER BY ts DESC LIMIT ?",
+                [limit],
+            ).fetchall()
+            con.close()
+            results = []
+            for r in rows:
+                data = r[4]
+                # DuckDB JSON 列可能返回字符串，需解析
+                if isinstance(data, str):
+                    try:
+                        data = _json.loads(data)
+                    except (_json.JSONDecodeError, TypeError):
+                        data = {"raw": data}
+                results.append({"id": r[0], "ts": r[1], "dev": r[2], "event": r[3], "data": data or {}})
+            return results
+        except Exception:
+            return []

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

@@ -0,0 +1,271 @@
+# -*- coding: utf-8 -*-
+"""
+adapters.qw —— QoderWork 原生能力 Adapter。
+
+设计模式: Adapter（适配 QoderWork 原生工具到 Cap 契约）
+
+实现 QoderWork 提供的 L2 宿主原生能力。其他宿主（ZCode/Codex）不适用，
+未实现的 Cap 由 NoOp 兜底。
+
+QoderWork 提供的相关工具（参考）:
+    memory / memory_search / memory_get  → QwMemoryCap（转发到 MCP 层）
+    qoder_cron                            → QwCronCap（文件 + 系统 crontab）
+    qw_mcp_list/get/call                  → 走 McpCap（L1）
+    delegate_to_im                        → QwNotifyCap（后续补）
+    qoder_show_widget / present_files     → QwPresentCap（后续补）
+
+本模块实现 QwMemoryCap + QwCronCap，其余后续补。
+"""
+from __future__ import annotations
+
+import os
+
+
+def is_qoderwork() -> bool:
+    """探测当前是否运行在 QoderWork 宿主内。
+
+    QoderWork 注入 QODER_SESSION_ID（会话）或 QODER_MCP_AVAILABLE（MCP 网关）。
+    """
+    if os.environ.get("QODER_SESSION_ID"):
+        return True
+    return os.environ.get("QODER_MCP_AVAILABLE", "").lower() in ("1", "true", "yes")
+
+
+class QwMemoryCap:
+    """QoderWork memory 工具适配器。
+
+    设计模式: Adapter（QoderWork → MemoryCap 契约）
+
+    策略: 优先使用 QoderWork 原生 memory 工具，降级到 MCP MemoryProvider。
+    当前实现: 转发到 MCP 层的 McpMemoryProvider（接通 kg.duckdb）。
+    未来: QoderWork 原生 memory 工具可用时，优先用原生。
+    """
+
+    def __init__(self):
+        self._env = is_qoderwork()
+        self._mcp_provider = None
+
+    def _get_mcp_provider(self):
+        """延迟获取 MCP MemoryProvider（避免循环导入）。"""
+        if self._mcp_provider is None:
+            try:
+                from .mcp import McpMemoryProvider
+                self._mcp_provider = McpMemoryProvider()
+            except Exception:
+                pass
+        return self._mcp_provider
+
+    @property
+    def available(self) -> bool:
+        """QoderWork 环境下可用（降级到 MCP 层）。"""
+        if self._env:
+            return True
+        # 非 QoderWork 环境，看 MCP provider 是否可用
+        provider = self._get_mcp_provider()
+        return bool(provider and provider.available)
+
+    def recall(self, query: str) -> list[dict]:
+        """语义检索记忆：优先 QoderWork 原生，降级 MCP。"""
+        # TODO: QoderWork 原生 memory_search 工具可用时优先调用
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.recall(query)
+        return []
+
+    def remember(self, key: str, content: str) -> None:
+        """写入记忆：优先 QoderWork 原生，降级 MCP。"""
+        # TODO: QoderWork 原生 memory 工具可用时优先调用
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            provider.remember(key, content)
+
+    def get_fact(self, key: str) -> str | None:
+        """按 key 取事实：优先 QoderWork 原生，降级 MCP。"""
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.get_fact(key)
+        return None
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        """最近 N 条记忆：优先 QoderWork 原生，降级 MCP。"""
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.list_recent(limit)
+        return []
+
+
+class QwCronCap:
+    """QoderWork cron 工具适配器。
+
+    设计模式: Adapter（QoderWork → CronCap 契约）
+
+    当前实现: 使用 common.events 的 cron 注册文件（.qoder/data/cron/）。
+    未来: QoderWork 原生 qoder_cron 工具可用时优先用原生。
+    """
+
+    CRON_DIR = ".qoder" + os.sep + "data" + os.sep + "cron"
+
+    def __init__(self):
+        self._env = is_qoderwork()
+
+    @property
+    def available(self) -> bool:
+        """文件系统可写即可用。"""
+        try:
+            from pathlib import Path
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            cron_dir.mkdir(parents=True, exist_ok=True)
+            return cron_dir.is_dir()
+        except Exception:
+            return False
+
+    def add(self, cron_expr: str, command: str, label: str = "") -> str:
+        """添加定时任务，返回 job_id。"""
+        import json
+        import time
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            cron_dir.mkdir(parents=True, exist_ok=True)
+
+            job_id = "%s-%s" % (label or "job", int(time.time()))
+            job = {
+                "id": job_id,
+                "cron": cron_expr,
+                "command": command,
+                "label": label,
+                "enabled": True,
+            }
+            job_file = cron_dir / ("%s.json" % job_id)
+            with open(job_file, "w", encoding="utf-8") as f:
+                json.dump(job, f, ensure_ascii=False, indent=2)
+            return job_id
+        except Exception as e:
+            return "error: %s" % str(e)[:80]
+
+    def list(self) -> list[dict]:
+        """列出所有定时任务。"""
+        import json
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            if not cron_dir.is_dir():
+                return []
+            jobs = []
+            for f in cron_dir.glob("*.json"):
+                try:
+                    with open(f, encoding="utf-8") as fh:
+                        jobs.append(json.load(fh))
+                except Exception:
+                    continue
+            return sorted(jobs, key=lambda j: j.get("id", ""))
+        except Exception:
+            return []
+
+    def remove(self, job_id: str) -> bool:
+        """删除定时任务。"""
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            job_file = repo_root / self.CRON_DIR / ("%s.json" % job_id)
+            if job_file.is_file():
+                job_file.unlink()
+                return True
+        except Exception:
+            pass
+        return False
+
+
+class QwPresentCap:
+    """QoderWork 富展示能力适配器。
+
+    设计模式: Adapter（QoderWork qoder_show_widget → PresentCap 契约）
+
+    把"渲染交互 HTML 到对话流"从宿主原生工具适配到 PresentCap.widget()。
+    降级链: QoderWork 原生 qoder_show_widget → 落盘 HTML 文件(纯 CLI 兜底)。
+    """
+
+    def __init__(self):
+        self._env = is_qoderwork()
+
+    @property
+    def available(self) -> bool:
+        """QoderWork 环境且 qoder_show_widget 工具可达时可用。"""
+        if not self._env:
+            return False
+        # 探测宿主工具是否可达 (走 McpCap, 失败则降级)
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            return reg.has_tool("qoder_show_widget")
+        except Exception:
+            return False
+
+    def _try_host_widget(self, html: str) -> bool:
+        """尝试调宿主 qoder_show_widget 把 HTML 嵌入对话流。成功返回 True。"""
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            result = reg.call("qoder_show_widget", {"html": html})
+            return not result.is_error
+        except Exception:
+            return False
+
+    def widget(self, html: str) -> bool:
+        """展示交互 widget。优先嵌入对话流, 降级落盘 HTML 文件。"""
+        if self._try_host_widget(html):
+            return True
+        # 降级: 落盘到 journal (纯 CLI / 工具不可达时)
+        try:
+            from datetime import datetime
+            from pathlib import Path
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            # 找当前 dev
+            dev = "default"
+            dev_file = repo_root / ".qoder" / ".developer"
+            if dev_file.is_file():
+                for line in dev_file.read_text(encoding="utf-8").splitlines():
+                    if "name=" in line:
+                        dev = line.split("name=", 1)[1].strip().split()[0]
+                        break
+            out_dir = repo_root / "workspace" / "members" / dev / "journal"
+            out_dir.mkdir(parents=True, exist_ok=True)
+            out = out_dir / ("dashboard-%s.html" % datetime.now().strftime("%Y%m%d-%H%M%S"))
+            out.write_text(html, encoding="utf-8")
+            print("[PresentCap] qoder_show_widget 不可达, 看板已落盘: %s" % out)
+            return False  # 通知调用方: 未嵌入对话流(但已落盘)
+        except Exception:
+            return False
+
+    def table(self, rows: list, headers: list | None = None) -> str:
+        """渲染 markdown 表格 (兜底, 所有宿主都能看)。"""
+        if not rows:
+            return ""
+        headers = headers or (list(rows[0].keys()) if rows and isinstance(rows[0], dict) else [])
+        lines = ["| " + " | ".join(str(h) for h in headers) + " |",
+                 "| " + " | ".join("---" for _ in headers) + " |"]
+        for r in rows:
+            if isinstance(r, dict):
+                lines.append("| " + " | ".join(str(r.get(h, "")) for h in headers) + " |")
+            else:
+                lines.append("| " + " | ".join(str(x) for x in r) + " |")
+        return "\n".join(lines)
+
+    def files(self, paths: list) -> bool:
+        """以文件卡片展示。降级: 打印路径列表。"""
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            if reg.has_tool("present_files"):
+                result = reg.call("present_files", {"paths": paths})
+                return not result.is_error
+        except Exception:
+            pass
+        print("[PresentCap] present_files 不可达, 文件列表: " + ", ".join(str(p) for p in paths))
+        return False

package/templates/qoder/scripts/capability/caps/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.caps —— L2 宿主原生能力契约层。
+
+每个能力 = Protocol（契约）+ NoOp（默认空实现）。
+新增能力（扩展场景 B）= 新建一个文件定义 Protocol + NoOp，在此导出，
+                       再在 registry.Nexus 加属性、_resolve_xxx 加装配。
+"""
+from .memory import MemoryCap, NoOpMemoryCap
+from .repo import RepoCap, NoOpRepoCap
+from .identity import IdentityCap, NoOpIdentityCap
+from .context import ContextCap, NoOpContextCap
+from .cron import CronCap, NoOpCronCap
+from .notify import NotifyCap, NoOpNotifyCap
+from .present import PresentCap, NoOpPresentCap
+from .sandbox import SandboxCap, NoOpSandboxCap
+
+__all__ = [
+    "MemoryCap", "NoOpMemoryCap",
+    "RepoCap", "NoOpRepoCap",
+    "IdentityCap", "NoOpIdentityCap",
+    "ContextCap", "NoOpContextCap",
+    "CronCap", "NoOpCronCap",
+    "NotifyCap", "NoOpNotifyCap",
+    "PresentCap", "NoOpPresentCap",
+    "SandboxCap", "NoOpSandboxCap",
+]

package/templates/qoder/scripts/capability/caps/context.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+ContextCap —— 上下文/偏好能力契约。
+
+核心能力（必有降级）。读取 USER 偏好、最近学到的经验等。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ContextCap(Protocol):
+    """上下文/偏好能力。"""
+
+    available: bool
+
+    def preferences(self) -> dict:
+        """USER 偏好字典。"""
+        ...
+
+    def recent_learnings(self, limit: int = 5) -> list[dict]:
+        """最近学到的经验/事实。"""
+        ...
+
+
+class NoOpContextCap:
+    """ContextCap 空实现。"""
+
+    available = False
+
+    def preferences(self) -> dict:
+        return {}
+
+    def recent_learnings(self, limit: int = 5) -> list[dict]:
+        return []