@hupan56/wlkj 3.1.9 → 3.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "3.1.9",
+  "version": "3.1.11",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"

package/templates/qoder/agents/qoder-spec-gen.toml

@@ -16,22 +16,24 @@ developer_instructions = """
 如果没有，扫描 `workspace/specs/` 目录找到最新的未生成 Spec 的 PRD。
 
 ### Step 2: 读取上下文
-必须读取以下文件：
-1. PRD 文件 — 需求来源
-2. `.qoder/rules/spec-template.md` — Spec 结构模板
-3. `.qoder/rules/code-style.md` — 命名规范
-4. `.qoder/context/architecture.md` — 项目架构
-5. `.qoder/context/data-dictionary.md` — 数据字典（如存在）
+必须读取以下文件（**注意：这些是真实存在的路径，旧版引用的 rules/spec-template.md 等 4 个文件已不存在**）：
+1. PRD 文件 — 需求来源（drafts 里的 `REQ-*.md` 或 `data/docs/prd/REQ-*.md`）
+2. `.qoder/skills/spec-generator/SKILL.md` — Spec 结构模板与生成流程（权威源）
+3. `.qoder/contracts/spec.md` — Spec 模块契约（字段/格式/贯穿检索要求）
+4. `data/docs/architecture/` 下的架构文档（如 `kg-layers.md`）— 项目架构
+5. `data/docs/constitution/eva-metrics.md` — 质量度量（Spec 要对齐验收标准）
 
 ### Step 3: 生成 Spec
-按 spec-template.md 的结构，从 PRD 提取：
+按 SKILL.md + spec.md 契约的结构，从 PRD 提取：
 - 每个用户故事 → API 接口
 - 验收标准 → 接口输入/输出/异常
 - 数据需求 → 数据库表设计
 - 非功能需求 → 约束章节
 
 ### Step 4: 输出
-写入 `workspace/specs/REQ-{ID}-{模块名}.md`
+写入 `workspace/specs/REQ-{ID}-{module}.spec.md`（**文件名必须带 `.spec.md` 后缀**，
+与 `.qoder/contracts/spec.md` 契约一致 —— 旧版写成 `REQ-{ID}-{模块名}.md` 会导致
+spec→code→test 贯穿检索断链）。
 完成后汇报：文件列表、与 PRD 的映射关系、需要开发关注的点。
 
 ## 规则

package/templates/qoder/agents/spec-generator.md

@@ -10,12 +10,12 @@ You are the spec-generator. Do NOT spawn another spec-generator.
 Generate technical Spec from PRD + Design.
 
 ## Workflow
-1. Read PRD from workspace/specs/prd/ or task dir
-2. Read design artifacts from workspace/tasks/{id}/design/
-3. Read team rules from workspace/constitution/
-4. Generate spec.md covering:
+1. Read PRD — 先找 `workspace/members/{dev}/drafts/REQ-*.md`，再找 `data/docs/prd/REQ-*.md`，最后 `workspace/specs/prd/`
+2. Read design artifacts from `workspace/tasks/{id}/design/` (若存在)
+3. Read team rules from `.qoder/skills/spec-generator/SKILL.md` + `.qoder/contracts/spec.md` (权威源)；`workspace/constitution/` 有则参考
+4. Generate spec covering:
    - Architecture changes
    - Data model changes
    - API changes
    - Implementation plan
-5. Save to workspace/specs/ or workspace/tasks/{id}/spec.md
+5. Save to `workspace/specs/REQ-{ID}-{module}.spec.md` (文件名带 `.spec.md` 后缀，与 contracts/spec.md 契约一致，保证 spec→code→test 贯穿检索)

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

@@ -1,271 +1,295 @@
-# -*- 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
+# -*- 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"
+
+    @staticmethod
+    def _repo_root():
+        """定位仓库根。
+
+        ⚠ 不能用 Path(__file__).parent^4! qw.py 在 scripts/capability/adapters/ 下
+        (scripts 下 3 级), 4 次 parent 解析到 .qoder/ 目录本身 (非仓库根),
+        再拼 CRON_DIR('.qoder/data/cron') → .qoder/.qoder/data/cron/ (双重 .qoder)。
+        用 foundation.core.paths.get_repo_root() 才对。失败回退向上找 .qoder/scripts。
+        """
+        try:
+            from foundation.core.paths import get_repo_root
+            return get_repo_root()
+        except Exception:
+            from pathlib import Path
+            here = Path(__file__).resolve()
+            for _ in range(10):
+                if (here / '.qoder' / 'scripts').is_dir():
+                    return here
+                parent = here.parent
+                if parent == here:
+                    break
+                here = parent
+            return Path(__file__).resolve().parent.parent.parent
+
+    def __init__(self):
+        self._env = is_qoderwork()
+
+    @property
+    def available(self) -> bool:
+        """文件系统可写即可用。"""
+        try:
+            from pathlib import Path
+            repo_root = self._repo_root()
+            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 = self._repo_root()
+            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 = self._repo_root()
+            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 = self._repo_root()
+            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 = self._repo_root()
+            # 找当前 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/protocol/mcp/kg_mcp_server.py

@@ -198,7 +198,7 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
           }, "required": ["module"]})
     def _t_get_workflow(self, args):
         from domain.kg.kg_capabilities import workflow_query
-        from domain.kg.storage.kg_duckdb import get_db
+        from domain.kg.storage.kg_duckdb import get_db_readonly
         q = (args.get("module") or '').strip()
         if not q:
             return "请提供模块名。可选: assets/cost/hr/maintenance/operation/qualityAndSafety/veh/settings/dashboard/flow/systems/monitor/quasafe"
@@ -207,7 +207,9 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
         _hint = _require_kgdb()
         if _hint:
             return _hint
-        con = get_db()
+        con = get_db_readonly()
+        if con is None:
+            return "知识图谱暂不可用 (kg.duckdb 连接失败), 稍后重试或联系管理员。"
         try:
             return workflow_query(con, q)
         finally:
@@ -215,14 +217,14 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
             except Exception: pass
 
     @tool("multi_hop",
-          "知识图谱多跳遍历: 从一个符号出发, 沿edges递归N跳, 找出全部可达实体(页面→接口→控制器→测试)。知识图谱核心能力。支持别名解析(传中文/端点/函数名自动转entity_id)。例: multi_hop(symbol='资产管理') 或 multi_hop(symbol='/asset/list', max_depth=3)",
+          "知识图谱多跳遍历: 从一个符号出发, 沿edges递归N跳, 找出全部可达实体(页面→接口→控制器→测试)。知识图谱核心能力。支持别名解析(传中文/端点/函数名自动转entity_id)。例: multi_hop(symbol='资产管理') 或 multi_hop(symbol='handleExport', max_depth=3)",
           {"type": "object", "properties": {
               "symbol": {"type": "string", "description": "起点符号: 可传entity_id、别名(资产管理)、端点(/asset/list)或函数名"},
               "max_depth": {"type": "integer", "default": 3, "description": "最大跳数(1-5), 默认3。越大越全但越慢"},
           }, "required": ["symbol"]})
     def _t_multi_hop(self, args):
         from domain.kg.kg_capabilities import hop_query
-        from domain.kg.storage.kg_duckdb import get_db, multi_hop
+        from domain.kg.storage.kg_duckdb import get_db_readonly, multi_hop
         sym = (args.get("symbol") or '').strip()
         if not sym:
             return "请提供起点符号 (entity_id / 端点 / 函数名 / 中文别名)"
@@ -234,7 +236,9 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
         _hint = _require_kgdb()
         if _hint:
             return _hint
-        con = get_db()
+        con = get_db_readonly()
+        if con is None:
+            return "知识图谱暂不可用 (kg.duckdb 连接失败), 稍后重试或联系管理员。"
         try:
             return hop_query(con, sym, depth, multi_hop_fn=multi_hop)
         finally:
@@ -259,12 +263,14 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
               "field": {"type": "string", "description": "字段名(英文field或中文标题)"},
           }, "required": ["field"]})
     def _t_search_field(self, args):
-        from domain.kg.storage.kg_duckdb import get_db
+        from domain.kg.storage.kg_duckdb import get_db_readonly
         field = (args.get("field") or '').strip()
         _hint = _require_kgdb()
         if _hint:
             return _hint
-        con = get_db()
+        con = get_db_readonly()
+        if con is None:
+            return "知识图谱暂不可用 (kg.duckdb 连接失败), 稍后重试或联系管理员。"
         try:
             rows = con.execute(
                 "SELECT field, title, count, sample_files FROM fields "
@@ -286,12 +292,14 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
               "platform": {"type": "string", "enum": ["web", "app"], "description": "平台过滤。可选"},
           }})
     def _t_list_modules(self, args):
-        from domain.kg.storage.kg_duckdb import get_db
+        from domain.kg.storage.kg_duckdb import get_db_readonly
         platform = args.get("platform", "")
         _hint = _require_kgdb()
         if _hint:
             return _hint
-        con = get_db()
+        con = get_db_readonly()
+        if con is None:
+            return "知识图谱暂不可用 (kg.duckdb 连接失败), 稍后重试或联系管理员。"
         try:
             if platform == 'web':
                 rows = con.execute("SELECT dir, cn, project FROM modules WHERE project LIKE '%fywl%' ORDER BY dir").fetchall()