@hupan56/wlkj 2.7.12 → 3.1.2

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()