@hupan56/wlkj 3.0.0 → 3.1.3

package/templates/qoder/scripts/protocol/mcp/kg_mcp_server.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
+
+"""
+Knowledge Graph MCP Server for QoderWork (pure Python, no SDK dependency).
+
+Exposes the QODER knowledge graph as MCP tools that QoderWork's AI agent
+can call directly. Uses the MCP stdio protocol (JSON-RPC 2.0 over stdin/stdout)
+implemented from scratch — no external dependencies beyond the standard library.
+
+Registered in ~/.qoderwork/mcp.json as "qoder-knowledge-graph".
+Tools surface as mcp__qoder-knowledge-graph__<tool> to the AI.
+
+v3.1 重构: 用 @tool 装饰器 + ToolRegistryMeta 元类, 消除:
+  - 手写 TOOLS 列表 (78-253 行)
+  - _execute_tool 的 17 个 if/elif 分支 (386-576 行)
+两处合一, 新增工具只需加一个 @tool 方法。
+"""
+import io
+import os
+import sys
+import json
+import subprocess
+
+# Ensure UTF-8 output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+# Locate the scripts dir
+SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # scripts/ 根
+BASE_DIR = os.path.dirname(os.path.dirname(SCRIPTS_DIR))  # repo 根
+sys.path.insert(0, SCRIPTS_DIR)
+_KG_DIR = os.path.dirname(os.path.abspath(__file__))
+if _KG_DIR not in sys.path: sys.path.insert(0, _KG_DIR)
+
+
+# ── stdout 捕获辅助 ───────────────────────────────────────────────────
+# 底层脚本 (search_index/context_pack) 用 print 输出, MCP 需要捕获为字符串返回。
+
+def _capture(func, *args, **kwargs):
+    """Run a function, capture its stdout.
+
+    v3.0: sys.stdout 在 run() 后已是 stderr (基类 _setup_streams 重定向),
+    这里捕获时临时换回 buf, finally 还原。
+    """
+    old = sys.stdout
+    buf = io.StringIO()
+    sys.stdout = buf
+    try:
+        func(*args, **kwargs)
+    except Exception as e:
+        buf.write('\n[error] %s' % str(e))
+    finally:
+        sys.stdout = old
+    return buf.getvalue().strip()
+
+
+# Lazy imports (首次调用工具时才 import, 加快启动)
+_search = None
+_context = None
+
+def _ensure_imports():
+    global _search, _context
+    if _search is None:
+        from domain.kg.search import search_index as _search
+    if _context is None:
+        from domain.kg.search import context_pack as _context
+
+
+# ── MCP Server (继承 BaseMCPServer, @tool 装饰器自动分发) ──────────────
+
+from foundation.protocol.mcp_base import BaseMCPServer, tool
+
+
+class KnowledgeGraphMCPServer(BaseMCPServer):
+    """知识图谱 MCP Server。
+
+    v3.1: 每个工具用 @tool 装饰, 元类自动收集 TOOLS + 自动 handle_tool 分发。
+    新增工具 = 加一个 @tool 方法, 无需改 TOOLS 列表或 if 链。
+    """
+
+    SERVER_NAME = "qoder-knowledge-graph"
+    SERVER_VERSION = "1.1.0"
+
+    # ── 搜索类 (转发到 search_index) ──────────────────────────────────
+
+    @tool("search_code",
+          "搜索代码: 按关键词查找代码文件在哪。例: search_code(keyword='考勤') 或 search_code(keyword='车辆', platform='web')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "搜索关键词(中文或英文)"},
+              "platform": {"type": "string", "enum": ["web", "app"], "description": "平台: web=PC管理端, app=移动端。可选"},
+          }, "required": ["keyword"]})
+    def _t_search_code(self, args):
+        _ensure_imports()
+        kw = args.get("keyword", "")
+        plat = args.get("platform") or ""
+        return _capture(_search.search_keywords, kw, plat) or "无匹配结果"
+
+    @tool("search_api",
+          "搜索API端点: 按关键词查找后端接口。例: search_api(keyword='salary')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "API关键词"},
+          }, "required": ["keyword"]})
+    def _t_search_api(self, args):
+        _ensure_imports()
+        return _capture(_search.search_api, args.get("keyword", "")) or "无匹配结果"
+
+    @tool("search_prd",
+          "搜索PRD: 查已有需求文档,防止重复造轮子。例: search_prd(keyword='考勤')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "PRD关键词"},
+          }, "required": ["keyword"]})
+    def _t_search_prd(self, args):
+        _ensure_imports()
+        return _capture(_search.search_prds, args.get("keyword", "")) or "无匹配PRD"
+
+    @tool("get_impact",
+          "影响分析: 改某接口/路径会影响哪些前端页面和按钮?评估改动风险。例: get_impact(endpoint='/asset') 或 get_impact(endpoint='export')",
+          {"type": "object", "properties": {
+              "endpoint": {"type": "string", "description": "API端点路径或关键词, 如 /asset/list 或 export"},
+          }, "required": ["endpoint"]})
+    def _t_get_impact(self, args):
+        _ensure_imports()
+        return _capture(_search.search_impact, args.get("endpoint", "")) or "未找到匹配端点"
+
+    @tool("context_360",
+          "360度视图: 查看符号(端点/函数/处理器)的全部关联信息。例: context_360(symbol='handleExport') 或 context_360(symbol='/system/role')",
+          {"type": "object", "properties": {
+              "symbol": {"type": "string", "description": "符号名: 端点/函数名/处理器名"},
+          }, "required": ["symbol"]})
+    def _t_context_360(self, args):
+        _ensure_imports()
+        return _capture(_search.search_context360, args.get("symbol", "")) or "未找到匹配符号"
+
+    @tool("context_pack",
+          "上下文打包: 一次返回关键词相关的全部上下文(代码+页面+字段+PRD+API+布局指纹)。避免来回查。例: context_pack(keyword='车辆', platform='web')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "业务关键词"},
+              "platform": {"type": "string", "enum": ["web", "app"], "description": "平台: web或app。可选"},
+              "page_type": {"type": "string", "description": "页面类型: table-page/form-page/detail-page。可选"},
+              "role": {"type": "string", "enum": ["pm", "design", "dev", "test", "admin"],
+                       "description": "角色裁剪: pm=字段+PRD+API, design=页面+布局+风格, dev=代码+API, test=代码+PRD+API。可选"},
+          }, "required": ["keyword"]})
+    def _t_context_pack(self, args):
+        _ensure_imports()
+        kw = args.get("keyword", "")
+        plat = args.get("platform", "")
+        pt = args.get("page_type", "")
+        role = args.get("role", "")
+        full = _capture(_context._compute_and_print, kw, plat, pt)
+        if not full:
+            return "无匹配上下文"
+        if role:
+            try:
+                from foundation.identity.roles import filter_by_role
+                return filter_by_role(full, role)
+            except Exception:
+                return full
+        return full
+
+    # ── 知识图谱查询类 (DuckDB 直查) ──────────────────────────────────
+
+    @tool("get_workflow",
+          "业务流程: 查看一个模块的完整操作链(query→create→audit→archive→export→delete)。数据源: DuckDB workflows 表。优先匹配英文模块名, 中文输入会返回候选模块列表。例: get_workflow(module='assets') 或 get_workflow(module='cost')",
+          {"type": "object", "properties": {
+              "module": {"type": "string", "description": "模块名(英文优先): assets/cost/hr/maintenance/operation/qualityAndSafety/veh/settings/dashboard/flow/systems/monitor/quasafe"},
+          }, "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
+        q = (args.get("module") or '').strip()
+        if not q:
+            return "请提供模块名。可选: assets/cost/hr/maintenance/operation/qualityAndSafety/veh/settings/dashboard/flow/systems/monitor/quasafe"
+        con = get_db()
+        try:
+            return workflow_query(con, q)
+        finally:
+            try: con.close()
+            except Exception: pass
+
+    @tool("multi_hop",
+          "知识图谱多跳遍历: 从一个符号出发, 沿edges递归N跳, 找出全部可达实体(页面→接口→控制器→测试)。知识图谱核心能力。支持别名解析(传中文/端点/函数名自动转entity_id)。例: multi_hop(symbol='资产管理') 或 multi_hop(symbol='/asset/list', 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
+        sym = (args.get("symbol") or '').strip()
+        if not sym:
+            return "请提供起点符号 (entity_id / 端点 / 函数名 / 中文别名)"
+        try:
+            depth = int(args.get("max_depth", 3))
+        except (TypeError, ValueError):
+            depth = 3
+        depth = max(1, min(5, depth))
+        con = get_db()
+        try:
+            return hop_query(con, sym, depth, multi_hop_fn=multi_hop)
+        finally:
+            try: con.close()
+            except Exception: pass
+
+    @tool("search_wiki",
+          "搜索Repo Wiki: 查Qoder IDE生成的模块级语义文档(架构/职责/依赖), 比读源码省token。写PRD前优先查。例: search_wiki(keyword='考勤') 或 search_wiki(keyword='权限')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "Wiki关键词(中/英文)"},
+          }, "required": ["keyword"]})
+    def _t_search_wiki(self, args):
+        from domain.kg.kg_capabilities import wiki_query
+        kw = (args.get("keyword") or '').strip()
+        if not kw:
+            return "请提供搜索关键词"
+        return wiki_query(kw)
+
+    @tool("search_field",
+          "搜索字段: 查某个字段在哪些页面用过、中文标题是什么。例: search_field(field='plateNo') 或 search_field(field='车牌号')",
+          {"type": "object", "properties": {
+              "field": {"type": "string", "description": "字段名(英文field或中文标题)"},
+          }, "required": ["field"]})
+    def _t_search_field(self, args):
+        from domain.kg.storage.kg_duckdb import get_db
+        field = (args.get("field") or '').strip()
+        con = get_db()
+        try:
+            rows = con.execute(
+                "SELECT field, title, count, sample_files FROM fields "
+                "WHERE LOWER(field) LIKE ? OR LOWER(title) LIKE ? LIMIT 20",
+                ['%' + field.lower() + '%', '%' + field.lower() + '%']
+            ).fetchall()
+        finally:
+            con.close()
+        if not rows:
+            return "未找到字段 '%s'" % field
+        lines = ["字段搜索 '%s' (%d个匹配)" % (field, len(rows))]
+        for f, t, c, s in rows:
+            lines.append("  %s -> %s (用了%d次)" % (f, t, c))
+        return '\n'.join(lines)
+
+    @tool("list_modules",
+          "模块清单: 列出项目所有业务模块及其中文名。例: list_modules() 或 list_modules(platform='web')",
+          {"type": "object", "properties": {
+              "platform": {"type": "string", "enum": ["web", "app"], "description": "平台过滤。可选"},
+          }})
+    def _t_list_modules(self, args):
+        from domain.kg.storage.kg_duckdb import get_db
+        platform = args.get("platform", "")
+        con = get_db()
+        try:
+            if platform == 'web':
+                rows = con.execute("SELECT dir, cn, project FROM modules WHERE project LIKE '%fywl%' ORDER BY dir").fetchall()
+            elif platform == 'app':
+                rows = con.execute("SELECT dir, cn, project FROM modules WHERE project LIKE '%Carmg%' OR project LIKE '%H5%' ORDER BY dir").fetchall()
+            else:
+                rows = con.execute("SELECT dir, cn, project FROM modules ORDER BY project, dir").fetchall()
+        finally:
+            con.close()
+        if not rows:
+            return "无模块数据"
+        lines = ["模块清单 (%d个)" % len(rows)]
+        cur = ""
+        for d, cn, proj in rows:
+            if proj != cur:
+                cur = proj
+                lines.append("[%s]" % proj)
+            lines.append("  %s -> %s" % (d, cn))
+        return '\n'.join(lines)
+
+    @tool("coverage_matrix",
+          "功能×测试覆盖矩阵: 哪些功能有测试覆盖, 哪些是空白? 标出回归测试盲区。例: coverage_matrix()",
+          {"type": "object", "properties": {}})
+    def _t_coverage_matrix(self, args):
+        from domain.kg.graph.graph_traverse import CodeGraph
+        from foundation.core.paths import DATA_INDEX_DIR
+        g = CodeGraph(str(DATA_INDEX_DIR))
+        return g.coverage_matrix() or "无法生成覆盖矩阵"
+
+    @tool("feature_overview",
+          "功能画像: 一个功能的完整画像(端点+按钮+测试+页面)。例: feature_overview(feature='资产管理') 或 feature_overview(feature='asset')",
+          {"type": "object", "properties": {
+              "feature": {"type": "string", "description": "功能名(中/英文都行): 资产管理/asset/hr"},
+          }, "required": ["feature"]})
+    def _t_feature_overview(self, args):
+        from domain.kg.graph.graph_traverse import CodeGraph
+        from foundation.core.paths import DATA_INDEX_DIR
+        g = CodeGraph(str(DATA_INDEX_DIR))
+        result = g.feature_overview(args.get("feature", ""))
+        if result and '不存在' not in result:
+            return result
+        # DuckDB 兜底: entity-registry.json 缺失时, 用 DuckDB 直接查
+        feat = args.get("feature", "")
+        fl = feat.lower()
+        try:
+            import duckdb as _ddb
+            con = _ddb.connect(str(DATA_INDEX_DIR / 'kg.duckdb'), read_only=True)
+            eps = con.execute(
+                "SELECT canonical FROM entities WHERE type='ENDPOINT' AND "
+                "(lower(canonical) LIKE ? OR lower(canonical) LIKE ?) LIMIT 15",
+                ['%' + fl + '%', '%' + feat + '%']).fetchall()
+            btns = con.execute(
+                "SELECT canonical FROM entities WHERE type='BUTTON' AND "
+                "lower(canonical) LIKE ? LIMIT 10", ['%' + fl + '%']).fetchall()
+            con.close()
+            lines = ['功能画像: %s (DuckDB兜底)' % feat]
+            if eps:
+                lines.append('端点(%d):' % len(eps))
+                for (e,) in eps[:10]:
+                    lines.append('  %s' % e)
+            if btns:
+                lines.append('按钮(%d):' % len(btns))
+                for (b,) in btns[:5]:
+                    lines.append('  %s' % b)
+            if not eps and not btns:
+                lines.append('  (无匹配。换关键词重试)')
+            return chr(10).join(lines)
+        except Exception as e:
+            return '未找到功能 "%s" (DuckDB兜底也失败: %s)' % (feat, str(e)[:60])
+
+    # ── 跨层影响分析 ──────────────────────────────────────────────────
+
+    @tool("table_impact",
+          "改表影响分析: 改某数据库表会影响哪些 Entity 类和接口? 跨层遍历(数据层→代码层)。例: table_impact(table='quality_case') → 找到 QualityCase 类 + 影响的 Controller/接口",
+          {"type": "object", "properties": {
+              "table": {"type": "string", "description": "数据库表名 (如 quality_case)"},
+          }, "required": ["table"]})
+    def _t_table_impact(self, args):
+        from foundation.core.paths import DATA_INDEX_DIR
+        import duckdb as _ddb
+        db_path = str(DATA_INDEX_DIR / 'kg_db.duckdb')
+        if not os.path.isfile(db_path):
+            return "数据层图谱未构建。请先跑: python .qoder/scripts/domain/kg/build/kg_build_db.py"
+        table = (args.get("table") or "").strip()
+        try:
+            con = _ddb.connect(db_path, read_only=True)
+        except Exception as e:
+            return "数据层图谱暂时不可用(可能正在重建): %s。稍后重试。" % str(e)[:60]
+        try:
+            ents = con.execute(
+                "SELECT DISTINCT entity_class FROM entity_table_map WHERE table_name = ?",
+                [table]
+            ).fetchall()
+            ent_list = [r[0] for r in ents]
+            if not ent_list:
+                return "表 '%s' 在 entity_table_map 中无映射 (可能该表无 @TableName 注解的 Entity)" % table
+            lines = ["改表影响分析: %s" % table]
+            lines.append("  对应 Entity: %s" % ', '.join(ent_list))
+            cols = con.execute(
+                "SELECT column_name, data_type, column_comment FROM db_columns "
+                "WHERE table_name = ? LIMIT 10", [table]
+            ).fetchall()
+            if cols:
+                lines.append("  表字段 (%d+):" % len(cols))
+                for cn, dt, cc in cols:
+                    lines.append("    %s (%s) %s" % (cn, dt, (cc or '')[:30]))
+            try:
+                con.execute("ATTACH '%s' AS code (READ_ONLY)" % str(DATA_INDEX_DIR / 'kg.duckdb'))
+                lines.append("  影响的接口/控制器:")
+                found = 0
+                for ec in ent_list:
+                    refs = con.execute(
+                        "SELECT type, canonical FROM code.entities "
+                        "WHERE contains(canonical, ?) AND type IN ('CONTROLLER','ENDPOINT') "
+                        "LIMIT 12", [ec]
+                    ).fetchall()
+                    for t, c in refs:
+                        lines.append("    [%s] %s" % (t, c))
+                        found += 1
+                if not found:
+                    lines.append("    (代码图谱中未找到引用 %s 的接口)" % ent_list[0])
+                con.execute("DETACH code")
+            except Exception as e:
+                lines.append("  (代码图谱查询失败: %s)" % str(e)[:60])
+            return '\n'.join(lines)
+        finally:
+            con.close()
+
+    # ── 原型/设计类 (子进程调用) ──────────────────────────────────────
+
+    @tool("fill_prototype",
+          "原型预填: 用真实代码数据(表格列/表单字段/布局参数)自动填模板,输出80%完成的HTML草稿+数据清单。AI只需微调20%。出原型前必须调。例: fill_prototype(keyword='营业外合同', platform='web')",
+          {"type": "object", "properties": {
+              "keyword": {"type": "string", "description": "业务关键词"},
+              "platform": {"type": "string", "enum": ["web", "app"], "description": "平台: web或app。默认web"},
+          }, "required": ["keyword"]})
+    def _t_fill_prototype(self, args):
+        from foundation.core.paths import find_script
+        kw = args.get("keyword", "")
+        plat = args.get("platform", "web")
+        script = find_script('fill_prototype.py')
+        if script is None:
+            return "fill_prototype.py 未找到 (脚本迁移后路径未更新)"
+        try:
+            r = subprocess.run([sys.executable, str(script), kw, '--platform', plat],
+                               capture_output=True, text=True, encoding='utf-8',
+                               errors='replace', timeout=30, cwd=str(script.parent))
+            return r.stdout or "fill_prototype 无输出 (可能索引缺失)"
+        except Exception as e:
+            return "[error] fill_prototype: %s" % str(e)
+
+    @tool("get_design_system",
+          "设计系统查询: 返回项目完整设计规范(布局指纹/颜色token/页面模式/组件表/图标规则/behaviors)。出任何原型前必须先调。例: get_design_system() 或 get_design_system(platform='web')",
+          {"type": "object", "properties": {
+              "platform": {"type": "string", "enum": ["web", "app"], "description": "平台: 只返回指定平台的指纹。不传则返回全部"},
+          }})
+    def _t_get_design_system(self, args):
+        from foundation.core.paths import find_script
+        design_md = os.path.join(BASE_DIR, 'data', 'design', 'DESIGN.md')
+        if not os.path.isfile(design_md):
+            gen_script = find_script('gen_design_doc.py')
+            if gen_script is not None:
+                subprocess.run([sys.executable, str(gen_script)], capture_output=True, timeout=30)
+        if os.path.isfile(design_md):
+            content = open(design_md, encoding='utf-8').read()
+            plat = args.get("platform")
+            if plat:
+                lines = content.split('\n')
+                result = []
+                in_section = False
+                for line in lines:
+                    if line.startswith('### ') and plat.lower() in line.lower():
+                        in_section = True
+                    elif line.startswith('### ') and in_section:
+                        break
+                    if in_section:
+                        result.append(line)
+                return '\n'.join(result) if result else content
+            return content
+        return "DESIGN.md 不存在且生成失败。请手动跑: python .qoder/scripts/design/gen_design_doc.py"
+
+    @tool("semantic_search",
+          "语义搜索(概念检索): 用自然语言找代码/API/功能,不依赖精确关键词。查'报销'能命中 expense/reimburse。需先构建embedding(管理员跑 kg_semantic.py build-embeddings)。例: semantic_search(query='报销流程') 或 semantic_search(query='车辆调度')",
+          {"type": "object", "properties": {
+              "query": {"type": "string", "description": "自然语言查询(中/英文均可)"},
+              "top_k": {"type": "integer", "default": 10, "description": "返回前N条, 默认10"},
+          }, "required": ["query"]})
+    def _t_semantic_search(self, args):
+        from domain.kg.graph.kg_semantic import semantic_search, embedding_status
+        query = (args.get("query") or '').strip()
+        if not query:
+            return "请提供查询关键词"
+        try:
+            top_k = int(args.get("top_k", 10))
+        except (TypeError, ValueError):
+            top_k = 10
+        results = semantic_search(query, top_k=top_k)
+        if results is None:
+            st = embedding_status()
+            if not st['available']:
+                return ("语义检索未启用: sentence-transformers 未安装。\n"
+                        "启用方法: pip install sentence-transformers\n"
+                        "(95MB 模型首次自动下载, 之后完全离线)")
+            elif st['embeddings_count'] == 0:
+                return ("语义检索未构建向量。请管理员运行:\n"
+                        "  python .qoder/scripts/domain/kg/graph/kg_semantic.py build-embeddings")
+            return None
+        lines = ["语义搜索: '%s' (top %d)" % (query, len(results))]
+        for eid, text, score in results:
+            lines.append("  %.3f  %s" % (score, text[:70]))
+        return '\n'.join(lines)
+
+
+if __name__ == "__main__":
+    KnowledgeGraphMCPServer().run()

package/templates/qoder/scripts/{mcp → protocol/mcp}/lanhu_stdio_wrapper.py

@@ -2,9 +2,15 @@
 # -*- coding: utf-8 -*-
 # v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
 import os as _o, sys as _s
-_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
 if _cp not in _s.path: _s.path.insert(0, _cp)
 from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
 
 """
 lanhu_stdio_wrapper.py - 蓝湖 MCP STDIO 启动包装（角色隔离 + QoderWork 自动开关）
@@ -16,7 +22,7 @@ lanhu_stdio_wrapper.py - 蓝湖 MCP STDIO 启动包装（角色隔离 + QoderWor
 做什么:
   1. 定位仓库根
   2. 读 .qoder/.developer → 当前角色 (UI设计师/PM/开发...)
-  3. 读 workspace/members/{角色}/.secrets/lanhu.env → 该角色的蓝湖 cookie
+  3. 读 workspace/members/{角色}/.private/secrets/lanhu.env → 该角色的蓝湖 cookie
   4. 注入环境变量 (LANHU_COOKIE + MCP_TRANSPORT=stdio + LANHU_USER_NAME)
   5. os.execv() 拉起 lanhu_mcp_server.py (用 venv 的 3.10+ python)
 
@@ -24,7 +30,7 @@ lanhu_stdio_wrapper.py - 蓝湖 MCP STDIO 启动包装（角色隔离 + QoderWor
   蓝湖权限按角色分 (UI 能改稿, PM/开发只读)。
   cookie 必须按角色隔离, 换 .developer 时跟着换。
   wrapper 每次启动读当前角色 → 用对应 cookie → 权限正确。
-  cookie 不进 mcp.json (那是机器级全局, 不按人), 仍按角色存 .secrets/。
+  cookie 不进 mcp.json (那是机器级全局, 不按人), 仍按角色存 .private/secrets/。
 
 为什么用 os.execv 而非 subprocess:
   execv 让 lanhu server 直接替换 wrapper 进程。
@@ -45,7 +51,7 @@ except (AttributeError, TypeError, OSError):
 
 # 定位仓库根: 本文件在 <repo>/.qoder/scripts/ → 上三级
 SCRIPT_DIR = Path(__file__).resolve().parent
-BASE = SCRIPT_DIR.parent.parent  # repo root
+BASE = get_repo_root()
 
 
 def _find_repo_root():
@@ -83,7 +89,7 @@ def main():
     dev = _current_developer()
     if not dev:
         sys.stderr.write('[lanhu-wrapper] 未初始化开发者 (.qoder/.developer 不存在)。\n')
-        sys.stderr.write('  跑 /wl-init 或 python .qoder/scripts/setup.py 初始化。\n')
+        sys.stderr.write('  跑 /wl-init 或 npx @hupan56/wlkj init <你的名字> 初始化。\n')
         sys.exit(1)
 
     # 2. 该角色的 cookie

package/templates/qoder/scripts/{mcp → protocol/mcp}/mcp_doctor.py

@@ -11,7 +11,12 @@ v3.0 合并自: check_mcp(启动条件) + check_mcp_launch(实际启动)。
 """
 # v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
 import os as _o, sys as _s
-_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
 if _cp not in _s.path: _s.path.insert(0, _cp)
 from bootstrap import setup; setup()
 
@@ -55,7 +60,7 @@ if sys.platform == 'win32':
         pass
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from common.paths import get_repo_root
+from foundation.core.paths import get_repo_root
 
 BASE = get_repo_root()
 HOME = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
@@ -190,7 +195,7 @@ def check_launcher_file(fix=False):
 def check_kg():
     """4. kg MCP: duckdb + kg_mcp_server.py。"""
     print('\n--- 4. 知识图谱 MCP (kg) ---')
-    server = BASE / '.qoder' / 'scripts' / 'kg_mcp_server.py'
+    server = BASE / '.qoder' / 'scripts' / 'protocol' / 'mcp' / 'kg_mcp_server.py'
     if not server.is_file():
         problem('kg_mcp_server.py 不存在', '引擎不完整, 重跑 npx wlkj update')
         return
@@ -205,7 +210,7 @@ def check_kg():
 def check_mysql():
     """5. mysql MCP: pymysql + config.yaml mysql 段。"""
     print('\n--- 5. MySQL MCP ---')
-    server = BASE / '.qoder' / 'scripts' / 'mysql_mcp_server.py'
+    server = BASE / '.qoder' / 'scripts' / 'protocol' / 'mcp' / 'mysql_mcp_server.py'
     if not server.is_file():
         problem('mysql_mcp_server.py 不存在')
         return
@@ -229,9 +234,36 @@ def check_mysql():
         say(WARN_TAG, 'mysql 依赖就绪, 但 config.yaml 无 mysql 段 (按需配)')
 
 
+def check_zentao():
+    """6. zentao MCP: requests + zentao_mcp_server.py + 个人凭据。"""
+    print('\n--- 6. 禅道 MCP (zentao) ---')
+    server = BASE / '.qoder' / 'scripts' / 'protocol' / 'mcp' / 'zentao_mcp_server.py'
+    if not server.is_file():
+        problem('zentao_mcp_server.py 不存在')
+        return
+    py = _find_python_with('requests')
+    if not py:
+        problem('找不到装了 requests 的 Python', 'pip install requests')
+        return
+    # 个人凭据 (每人一个禅道账号, 从 .private/secrets/zentao.env 读)
+    try:
+        from foundation.core.paths import get_developer, get_secrets_dir
+        dev = get_developer(BASE)
+    except Exception:
+        dev = None
+    if not dev:
+        say(WARN_TAG, 'zentao 依赖就绪, 但未初始化开发者 (跑 /wl-init)')
+        return
+    env_file = Path(get_secrets_dir(dev)) / 'zentao.env'
+    if env_file.is_file():
+        say(OK_TAG, 'zentao 就绪 (角色=%s, 凭据已配)' % dev)
+    else:
+        say(WARN_TAG, 'zentao 依赖就绪, 但角色 %s 的凭据未配 (%s)' % (dev, env_file))
+
+
 def check_lanhu():
-    """6. lanhu MCP: venv + cookie。三态 (就绪/未装/未配)。"""
-    print('\n--- 6. 蓝湖 MCP (lanhu, 可选) ---')
+    """7. lanhu MCP: venv + cookie。三态 (就绪/未装/未配)。"""
+    print('\n--- 7. 蓝湖 MCP (lanhu, 可选) ---')
     venv = BASE / 'external' / 'lanhu-mcp' / '.venv'
     server = BASE / 'external' / 'lanhu-mcp' / 'lanhu_mcp_server.py'
     if not venv.is_dir() or not server.is_file():
@@ -244,7 +276,7 @@ def check_lanhu():
         return
     # 当前角色 cookie
     try:
-        from common.paths import get_developer
+        from foundation.core.paths import get_developer
         dev = get_developer(BASE)
     except Exception:
         dev = None
@@ -259,8 +291,8 @@ def check_lanhu():
 
 
 def check_playwright():
-    """7. playwright MCP: node + cli.js/npx。"""
-    print('\n--- 7. Playwright MCP (浏览器测试) ---')
+    """8. playwright MCP: node + cli.js/npx。"""
+    print('\n--- 8. Playwright MCP (浏览器测试) ---')
     import shutil
     node = shutil.which('node')
     if not node:
@@ -295,6 +327,7 @@ def main_conditions():
     check_launcher_file(fix)
     check_kg()
     check_mysql()
+    check_zentao()
     check_lanhu()
     check_playwright()
 
@@ -314,14 +347,14 @@ def main_conditions():
 
 
 
-# ==================== 来自 check_mcp_launch.py (实际启动诊断) ====================
+# ==================== 实际启动诊断 (原 check_mcp_launch.py 合并而来) ====================
 """
-check_mcp_launch.py - 诊断 MCP 为什么黄色
+mcp_doctor.py - 诊断 MCP 为什么黄色
 
 逐个模拟 mcp_launcher.py 启动每个 MCP, 发送 initialize 请求,
 看哪个 MCP 启动失败/崩溃/不响应。输出明确的诊断结论。
 
-用法: python .qoder/scripts/check_mcp_launch.py
+用法: python .qoder/scripts/protocol/mcp/mcp_doctor.py
 """
 import json
 import os
@@ -329,8 +362,8 @@ import subprocess
 import sys
 from pathlib import Path
 
-SCRIPTS_DIR = Path(__file__).resolve().parent
-BASE = SCRIPTS_DIR.parent.parent  # repo root
+SCRIPTS_DIR = get_repo_root()
+BASE = get_repo_root()  # repo root (统一用 foundation 定位, 不手算 parent)
 
 MCP_NAMES = ['kg', 'mysql', 'zentao', 'lanhu']