@hupan56/wlkj 2.6.0 → 2.7.1

package/templates/qoder/scripts/kg.py

@@ -0,0 +1,708 @@
+# -*- coding: utf-8 -*-
+"""
+kg.py — QODER 知识图谱统一 CLI 入口（全系列通用）
+
+把原本只在 QoderWork MCP (kg_mcp_server.py) 里的 13 个知识图谱能力，
+统一成一套命令行子命令。Qoder IDE / Quest / CLI 直接跑；QoderWork 仍可
+用 MCP，本脚本是新增的并列通道（功能等价）。
+
+设计原则：
+  1. 不复制逻辑 — 调底层: search_index / context_pack / graph_traverse /
+     kg_duckdb / repowiki / fill_prototype / gen_design_doc
+  2. 全容错 — DuckDB/索引缺失优雅降级，给修复提示，绝不抛栈给用户
+  3. 参数统一 — 13 个子命令风格一致，对标 MCP 工具名
+  4. 纯文本输出 — UTF-8，无日志噪音，AI 直接读
+
+用法:
+  python .qoder/scripts/kg.py <子命令> [参数]
+
+  python .qoder/scripts/kg.py search 考勤 --platform web
+  python .qoder/scripts/kg.py impact /asset
+  python .qoder/scripts/kg.py coverage
+  python .qoder/scripts/kg.py feature 资产管理
+  python .qoder/scripts/kg.py workflow assets
+  python .qoder/scripts/kg.py hop 资产管理 --depth 3
+"""
+import io
+import os
+import re
+import sys
+
+# UTF-8 输出（Windows 终端默认 GBK 会乱码）
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
+BASE_DIR = os.path.dirname(os.path.dirname(SCRIPTS_DIR))  # repo root
+sys.path.insert(0, SCRIPTS_DIR)
+
+
+# ── 路径与索引新鲜度（与底层一致）──────────────────────────────────────
+def _index_dir():
+    """获取 data/index 目录（延迟导入，避免顶层崩）。"""
+    try:
+        from common.paths import DATA_INDEX_DIR
+        return str(DATA_INDEX_DIR)
+    except Exception:
+        # 兜底: 常规布局
+        return os.path.join(BASE_DIR, 'data', 'index')
+
+
+def _kg_db_path():
+    return os.path.join(_index_dir(), 'kg.duckdb')
+
+
+def _has_duckdb():
+    """知识图谱 DuckDB 是否已构建。"""
+    return os.path.isfile(_kg_db_path())
+
+
+def _hint_rebuild(action_cn='知识图谱'):
+    """DuckDB/索引缺失时的统一修复提示。"""
+    return (
+        "⚠️ %s未构建或缺失。\n"
+        "修复方法（任选其一）:\n"
+        "  1. 对 AI 说「初始化」(/wl-init) — 自动刷新索引\n"
+        "  2. 手动构建: python .qoder/scripts/kg_build.py\n"
+        "  3. 自检修复: python .qoder/scripts/init_doctor.py --fix\n"
+        "本次查询无法继续，但其他子命令（不依赖图谱的）仍可用。"
+        % action_cn
+    )
+
+
+# ── 子命令实现 ────────────────────────────────────────────────────────
+
+def cmd_search(args):
+    """搜代码: 按关键词找代码文件。"""
+    if not args:
+        return "用法: kg.py search <关键词> [--platform web|app]"
+    kw, plat = _split_kw_platform(args)
+    if not kw:
+        return "请提供搜索关键词"
+    import search_index as S
+    # search_keywords(query, platform=None) 自带中文扩展，不需外层 expand
+    return _capture(S.search_keywords, kw, plat) or "无匹配结果"
+
+
+def cmd_api(args):
+    """搜 API 端点。"""
+    if not args:
+        return "用法: kg.py api <关键词>"
+    import search_index as S
+    return _capture(S.search_api, args[0]) or "无匹配 API"
+
+
+def cmd_prd(args):
+    """搜 PRD（防重复造轮子）。"""
+    if not args:
+        return "用法: kg.py prd <关键词>"
+    import search_index as S
+    return _capture(S.search_prds, args[0]) or "无匹配 PRD"
+
+
+def cmd_impact(args):
+    """影响分析: 改某接口影响哪些前端页面/按钮。"""
+    if not args:
+        return "用法: kg.py impact <端点或关键词>  例: /asset 或 export"
+    import search_index as S
+    return _capture(S.search_impact, args[0]) or "未找到匹配端点"
+
+
+def cmd_context360(args):
+    """符号 360 度视图: 端点/函数/处理器的全部关联。"""
+    if not args:
+        return "用法: kg.py context360 <符号>  例: handleExport 或 /system/role"
+    import search_index as S
+    return _capture(S.search_context360, args[0]) or "未找到匹配符号"
+
+
+def cmd_context(args):
+    """上下文打包: 一次返回关键词相关的全部上下文。支持 --role 角色裁剪。"""
+    if not args:
+        return ("用法: kg.py context <关键词> [--platform web|app] "
+                "[--role pm|design|dev|test|admin]")
+    rest = list(args)
+    role = ''
+    plat = ''
+    # 解析 --role / --platform
+    rest2 = []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == '--role' and i + 1 < len(rest):
+            role = rest[i + 1]; i += 2; continue
+        if a == '--platform' and i + 1 < len(rest):
+            plat = rest[i + 1]; i += 2; continue
+        rest2.append(a); i += 1
+    kw = rest2[0] if rest2 else ''
+    if not kw:
+        return "请提供业务关键词"
+    import context_pack as C
+    full = _capture(C._compute_and_print, kw, plat, '')
+    if not full:
+        return "无匹配上下文"
+    if role:
+        return _filter_by_role(full, role)
+    return full
+
+
+def cmd_coverage(args):
+    """功能×测试覆盖矩阵: 哪些功能有测试，哪些是盲区。"""
+    from common.graph_traverse import CodeGraph
+    g = CodeGraph(_index_dir())
+    return g.coverage_matrix() or "无法生成覆盖矩阵（索引可能为空）"
+
+
+def cmd_feature(args):
+    """功能画像: 一个功能的完整画像（端点+按钮+测试）。
+
+    DuckDB 优先（DuckDB 数据最全）；DuckDB 缺失时回退到 CodeGraph 的 JSON 路径。
+    """
+    if not args:
+        return "用法: kg.py feature <功能名>  例: 资产管理 或 asset 或 system"
+    feat = args[0]
+    # DuckDB 优先（数据最全，coverage 已验证可用）
+    if _has_duckdb():
+        try:
+            import duckdb
+        except ImportError:
+            return "未安装 duckdb。请运行: pip install duckdb"
+        con = duckdb.connect(_kg_db_path(), read_only=True)
+        try:
+            result = _feature_duckdb(con, feat)
+            if result:
+                return result
+        finally:
+            try: con.close()
+            except Exception: pass
+    # 回退: CodeGraph 的 JSON 实现（entity-registry.json 通常不存在）
+    from common.graph_traverse import CodeGraph
+    g = CodeGraph(_index_dir())
+    return g.feature_overview(feat) or "未找到功能 '%s'" % feat
+
+
+def _feature_duckdb(con, query):
+    """从 DuckDB 查功能画像（feature → endpoints/buttons/tests）。
+
+    别名解析: aliases 精确 → canonical/cn 模糊 → entity_id 含关键词。
+    """
+    q = (query or '').strip()
+    # 1) 解析为 FEATURE entity_id
+    target = None
+    resolved = con.execute(
+        "SELECT entity_id FROM aliases WHERE alias = ? "
+        "AND entity_id IN (SELECT id FROM entities WHERE type='FEATURE')",
+        [q.lower()]
+    ).fetchone()
+    if resolved:
+        target = resolved[0]
+    else:
+        # canonical / cn 模糊
+        row = con.execute(
+            "SELECT id FROM entities WHERE type='FEATURE' "
+            "AND (LOWER(canonical)=? OR cn=? OR LOWER(canonical) LIKE '%'||?||'%' OR cn LIKE '%'||?||'%') "
+            "LIMIT 1",
+            [q.lower(), q, q.lower(), q]
+        ).fetchone()
+        if row:
+            target = row[0]
+    if not target:
+        # 列出可用 feature 帮用户选
+        feats = con.execute(
+            "SELECT canonical, cn FROM entities WHERE type='FEATURE' AND cn<>'' ORDER BY cn LIMIT 30"
+        ).fetchall()
+        cands = ', '.join('%s(%s)' % (c, cn) if cn and cn != c else c for c, cn in feats)
+        return "未找到功能 '%s'。可用功能: %s" % (q, cands)
+
+    # 2) 取 feature 基本信息
+    info = con.execute(
+        "SELECT canonical, cn FROM entities WHERE id=?", [target]
+    ).fetchone()
+    canon, cn = info if info else (target, target)
+
+    # 3) 统计端点 / 按钮
+    endpoints = con.execute(
+        "SELECT to_id FROM edges WHERE from_id=? AND edge_type='has_endpoint'", [target]
+    ).fetchall()
+    buttons = con.execute(
+        "SELECT to_id FROM edges WHERE from_id=? AND edge_type='has_button'", [target]
+    ).fetchall()
+
+    # 4) 关联测试: feature 的端点 -(handled_by)-> controller -(tested_by)-> test
+    try:
+        tests = con.execute("""
+            SELECT DISTINCT tb.to_id FROM edges he
+            JOIN edges tb ON tb.from_id = he.to_id AND tb.edge_type='tested_by'
+            WHERE he.from_id=? AND he.edge_type='handled_by'
+        """, [target]).fetchall()
+    except Exception:
+        tests = []
+
+    ep_ids = [e[0] for e in endpoints]
+    btn_ids = [b[0] for b in buttons]
+    test_ids = [t[0] for t in tests]
+
+    # 5) 组装画像
+    out = ['## 功能画像: %s (%s)' % (cn, canon)]
+    out.append('  端点 %d 个 | 按钮操作 %d 个 | 关联测试 %d 个' % (
+        len(ep_ids), len(btn_ids), len(test_ids)))
+    out.append('')
+
+    out.append('### 端点 (%d)' % len(ep_ids))
+    for eid in ep_ids[:10]:
+        out.append('  %s' % eid)
+    if len(ep_ids) > 10:
+        out.append('  ... 还有 %d 个' % (len(ep_ids) - 10))
+    out.append('')
+
+    out.append('### 按钮操作 (%d)' % len(btn_ids))
+    # 提取按钮的操作动词(handleAdd/handleDel 等)
+    verbs = {}
+    for bid in btn_ids:
+        # bid 形如 B:path/to/file.vue:handleAdd
+        if ':' in bid:
+            handler = bid.rsplit(':', 1)[-1]
+        else:
+            handler = bid
+        verbs[handler] = verbs.get(handler, 0) + 1
+    top_verbs = sorted(verbs.items(), key=lambda x: -x[1])[:15]
+    out.append('  操作分布: %s' % ', '.join('%s×%d' % (v, n) for v, n in top_verbs))
+    out.append('')
+
+    out.append('### 关联测试 (%d)' % len(test_ids))
+    shown = 0
+    for tid in test_ids:
+        if shown >= 6:
+            out.append('  ... 还有 %d 个' % (len(test_ids) - 6))
+            break
+        # tid 形如 T:ClassName.method，查 tests 表拿断言
+        if tid.startswith('T:'):
+            ref = tid[2:]
+            cls = method = ''
+            if '.' in ref:
+                cls, method = ref.rsplit('.', 1)
+            trow = con.execute(
+                "SELECT display_name, assertions FROM tests WHERE class=? AND method=? LIMIT 1",
+                [cls, method]
+            ).fetchone()
+            if trow:
+                dn, asserts = trow
+                import json as _json
+                try:
+                    a_list = _json.loads(asserts) if isinstance(asserts, str) else asserts
+                    a_str = ', '.join(a_list[:3]) if a_list else ''
+                except Exception:
+                    a_str = ''
+                out.append('  %s — %s%s' % (ref, dn or '', (' [断言: %s]' % a_str) if a_str else ''))
+            else:
+                out.append('  %s' % ref)
+        else:
+            out.append('  %s' % tid)
+        shown += 1
+
+    if len(test_ids) == 0:
+        out.append('  ⚠️ 该功能无关联测试，是回归测试盲区')
+
+    return '\n'.join(out)
+
+
+def cmd_workflow(args):
+    """业务流程链: 一个模块的完整操作链（query→create→audit→...）。
+
+    优先匹配英文模块名（assets/cost/hr/...），中文输入返回候选。
+    数据源: DuckDB workflows 表。
+    """
+    if not args:
+        return ("用法: kg.py workflow <模块名>  例: assets / cost / hr\n"
+                "可选模块: assets/cost/hr/maintenance/operation/"
+                "qualityAndSafety/veh/settings/dashboard/flow/systems/monitor/quasafe")
+    module = args[0]
+    if not _has_duckdb():
+        return _hint_rebuild('业务流程数据（DuckDB）')
+    try:
+        import duckdb
+    except ImportError:
+        return ("未安装 duckdb。请运行: pip install duckdb")
+    con = duckdb.connect(_kg_db_path(), read_only=True)
+    try:
+        return _workflow_query(con, module)
+    finally:
+        try: con.close()
+        except Exception: pass
+
+
+def _workflow_query(con, q):
+    """workflows 表查询 + 脏数据清洗 + 中文兜底（从 kg_mcp_server 平移）。"""
+    q = (q or '').strip()
+    # 1) 精确 + 模糊匹配 workflows.module（英文）
+    hits = con.execute(
+        "SELECT DISTINCT module FROM workflows WHERE module = ? OR module LIKE '%' || ? || '%' ORDER BY module",
+        [q.lower(), q.lower()]
+    ).fetchall()
+    if not hits:
+        # 2) 中文兜底: 查 entities.cn 返回英文候选
+        cn_hits = con.execute(
+            "SELECT canonical, cn FROM entities WHERE type IN ('FEATURE','MODULE') AND cn <> '' AND (cn LIKE '%' || ? OR cn LIKE '%' || ? || '%')",
+            [q, q]
+        ).fetchall()
+        if cn_hits:
+            cands = ', '.join('%s(%s)' % (c[0], c[1]) for c in cn_hits[:8])
+            return "未在 workflows 表找到模块 '%s'。但 entities 表有相近中文名，可换这些英文模块名重试:\n  %s" % (q, cands)
+        all_mods = [r[0] for r in con.execute("SELECT DISTINCT module FROM workflows ORDER BY module").fetchall()]
+        return "未找到模块 '%s'。现有模块: %s" % (q, ', '.join(all_mods))
+
+    out = []
+    for (mod,) in hits:
+        # 清洗: 过滤空端点和模板泄漏按钮
+        rows = con.execute("""
+            SELECT state, seq, button, endpoint FROM workflows
+            WHERE module = ?
+              AND endpoint <> 'None' AND endpoint <> ''
+              AND button NOT LIKE '{{%'
+            ORDER BY seq, state
+        """, [mod]).fetchall()
+        if not rows:
+            continue
+        out.append('=== %s (%d 步, 已清洗脏数据) ===' % (mod, len(rows)))
+        cur_seq = -1
+        for st, sq, btn, ep in rows:
+            if sq != cur_seq:
+                out.append('  [%d] %s' % (sq, st))
+                cur_seq = sq
+            out.append('        %-16s -> %s' % (btn, ep))
+        out.append('')
+    return '\n'.join(out).strip() or "模块 '%s' 清洗后无有效操作链" % q
+
+
+def cmd_hop(args):
+    """多跳遍历: 从一个符号出发，递归 N 跳找全部可达实体。
+
+    知识图谱核心能力。支持别名解析（传中文/端点/函数名自动转 entity_id）。
+    """
+    if not args:
+        return "用法: kg.py hop <符号> [--depth 1-5]  例: 资产管理 或 /asset/list"
+    symbol, depth = _split_symbol_depth(args)
+    if not _has_duckdb():
+        return _hint_rebuild('知识图谱（DuckDB）')
+    try:
+        import duckdb
+    except ImportError:
+        return "未安装 duckdb。请运行: pip install duckdb"
+    import kg_duckdb as K
+    con = duckdb.connect(_kg_db_path(), read_only=True)
+    try:
+        # 1) 别名解析（三级兜底）
+        start_id = symbol
+        resolved = con.execute(
+            "SELECT entity_id FROM aliases WHERE alias = ?", [symbol.lower()]
+        ).fetchone()
+        if resolved:
+            start_id = resolved[0]
+        else:
+            fuzzy = con.execute(
+                "SELECT id FROM entities WHERE id = ? OR id LIKE '%' || ? || '%' LIMIT 1",
+                [symbol, symbol]
+            ).fetchone()
+            if fuzzy:
+                start_id = fuzzy[0]
+            else:
+                edge_hit = con.execute(
+                    "SELECT from_id FROM edges WHERE from_id LIKE '%' || ? || '%' LIMIT 1",
+                    [symbol]
+                ).fetchone()
+                if edge_hit:
+                    start_id = edge_hit[0]
+
+        # 2) 递归 CTE 遍历
+        try:
+            hops = K.multi_hop(con, start_id, max_depth=depth)
+        except Exception as e:
+            return "遍历出错 (起点=%s): %s" % (start_id, str(e))
+
+        if not hops or (len(hops) == 1 and hops[0][1] == 0):
+            return "从 '%s' (解析为 %s) 出发无可达节点。可能该符号不在图谱中，或无出边。" % (symbol, start_id)
+
+        # 3) 按 depth 分组展示
+        from collections import defaultdict
+        by_depth = defaultdict(list)
+        for eid, d in hops:
+            by_depth[d].append(eid)
+
+        out = ['=== 多跳遍历: %s (解析为 %s) ===' % (symbol, start_id)]
+        out.append('可达 %d 个实体, 最大 %d 跳:' % (len(hops), max(by_depth.keys())))
+        out.append('')
+        for d in sorted(by_depth.keys()):
+            eids = by_depth[d]
+            out.append('[第 %d 跳] %d 个实体:' % (d, len(eids)))
+            shown = 0
+            for eid in eids:
+                if shown >= 12:
+                    out.append('  ... 还有 %d 个' % (len(eids) - 12))
+                    break
+                info = con.execute(
+                    "SELECT type, canonical, cn FROM entities WHERE id = ?", [eid]
+                ).fetchone()
+                if info:
+                    t, c, cn = info
+                    label = '%s / %s' % (c, cn) if cn and cn != c else c
+                    out.append('  %-14s %-12s %s' % ('[%s]' % t, eid[:40], label))
+                else:
+                    out.append('  %-14s %s' % ('[edge]', eid[:60]))
+                shown += 1
+            out.append('')
+        return '\n'.join(out).strip()
+    finally:
+        try: con.close()
+        except Exception: pass
+
+
+def cmd_wiki(args):
+    """Repo Wiki 搜索: 查模块级语义文档（比读源码省 token）。
+
+    只读 wiki-index.json，不触发自动构建（慢操作）。
+    """
+    if not args:
+        return "用法: kg.py wiki <关键词>"
+    kw = args[0]
+    from common.paths import DATA_INDEX_DIR as _idx, PROJECT_ROOT as _base
+    wiki_path = os.path.join(str(_idx), 'wiki-index.json')
+    if not os.path.isfile(wiki_path):
+        return ("wiki-index.json 不存在。请在终端手动构建（一次性）:\n"
+                "  python .qoder/scripts/search_index.py wiki\n"
+                "（需要先在 Qoder IDE 对项目生成 Repo Wiki）")
+    try:
+        from common.repowiki import search_wiki
+        from common.terms import get_cn_map_with_auto
+    except ImportError as e:
+        return "Wiki 搜索模块缺失: %s" % str(e)
+    code_dir = os.path.join(_base, 'data', 'code')
+    try:
+        cn_map = get_cn_map_with_auto()
+        results = search_wiki(kw, str(_idx), code_dir, cn_map)
+    except Exception as e:
+        return "Wiki 搜索出错: %s" % str(e)
+    if not results:
+        return "No wiki pages match: %s" % kw
+    out = ['Wiki pages matching: %s (%d found)' % (kw, len(results)), '']
+    for i, r in enumerate(results, 1):
+        out.append('  %d. [%s] %s' % (i, r.get('project', '?'), r.get('title', '')))
+        deps = r.get('dependent_files') or []
+        if deps:
+            out.append('     依赖: %s%s' % (', '.join(deps[:2]),
+                      (' (共 %d 个文件)' % len(deps)) if len(deps) > 2 else ''))
+        if r.get('md_path'):
+            try:
+                rel = os.path.relpath(r['md_path'], _base)
+            except ValueError:
+                rel = r['md_path']
+            out.append('     文档: %s' % rel)
+    out.append('')
+    out.append('  提示: 读 wiki 文档（带行号引用）比读源码更省 token')
+    return '\n'.join(out)
+
+
+def cmd_fill_prototype(args):
+    """原型预填: 用真实代码数据自动填模板，输出 80% 完成的 HTML 草稿。"""
+    if not args:
+        return "用法: kg.py fill-prototype <关键词> [--platform web|app]"
+    kw, plat = _split_kw_platform(args)
+    plat = plat or 'web'
+    import subprocess as _sp
+    script = os.path.join(SCRIPTS_DIR, 'fill_prototype.py')
+    if not os.path.isfile(script):
+        return "fill_prototype.py 不存在"
+    try:
+        r = _sp.run([sys.executable, script, kw, '--platform', plat],
+                    capture_output=True, text=True, encoding='utf-8',
+                    errors='replace', timeout=30, cwd=SCRIPTS_DIR)
+        return r.stdout or "fill_prototype 无输出（可能索引缺失）"
+    except Exception as e:
+        return "[error] fill_prototype: %s" % str(e)
+
+
+def cmd_design_system(args):
+    """设计系统查询: 返回项目完整设计规范（布局指纹/颜色token/组件表/图标）。"""
+    plat = ''
+    if args and args[0] in ('--platform', '-p') and len(args) > 1:
+        plat = args[1]
+    import subprocess as _sp
+    design_md = os.path.join(BASE_DIR, 'data', 'design', 'DESIGN.md')
+    if not os.path.isfile(design_md):
+        gen_script = os.path.join(SCRIPTS_DIR, 'gen_design_doc.py')
+        if os.path.isfile(gen_script):
+            _sp.run([sys.executable, gen_script], capture_output=True, timeout=30)
+    if os.path.isfile(design_md):
+        content = open(design_md, encoding='utf-8').read()
+        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/gen_design_doc.py"
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────
+
+def _capture(func, *args, **kwargs):
+    """运行函数，捕获其 stdout 输出（底层脚本用 print 输出）。"""
+    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()
+
+
+def _split_kw_platform(args):
+    """从参数里拆出 keyword 和 --platform 值。"""
+    rest = list(args)
+    plat = ''
+    out = []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == '--platform' and i + 1 < len(rest):
+            plat = rest[i + 1]; i += 2; continue
+        out.append(a); i += 1
+    kw = out[0] if out else ''
+    return kw, plat
+
+
+def _split_symbol_depth(args):
+    """从参数里拆出 symbol 和 --depth 值（默认 3）。"""
+    rest = list(args)
+    depth = 3
+    out = []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == '--depth' and i + 1 < len(rest):
+            try: depth = int(rest[i + 1])
+            except (ValueError, TypeError): depth = 3
+            i += 2; continue
+        out.append(a); i += 1
+    return (out[0] if out else ''), max(1, min(5, depth))
+
+
+# Role-based section filtering for context_pack output（与 MCP 一致）
+ROLE_SECTIONS = {
+    'pm':     {'1', '2', '2b', '3', '4', '5', '7'},  # PM: 字段+PRD+API，无代码噪音
+    'design': {'2', '2b', '3', '6'},                  # 设计: 页面+布局+字段+风格
+    'dev':    {'1', '3', '5', '7'},                   # 开发: 代码+字段+API+wiki
+    'test':   {'1', '4', '5'},                        # 测试: 代码+PRD+API
+    'admin':  {'4', '5'},                             # 管理: PRD+API 概览
+}
+
+
+def _filter_by_role(text, role):
+    """按角色过滤 context_pack 输出的章节。"""
+    visible = ROLE_SECTIONS.get((role or '').lower())
+    if not visible:
+        return text  # 未知角色不过滤
+    sections = re.split(r'(\n## \d+[ab]?\.)', text)
+    result = sections[0]
+    i = 1
+    while i < len(sections):
+        header = sections[i]
+        num_m = re.match(r'\n## (\d+[ab]?)\.', header)
+        if num_m and num_m.group(1) in visible:
+            result += header
+            if i + 1 < len(sections):
+                result += sections[i + 1]
+            i += 2
+        else:
+            i += 2
+    return result.strip()
+
+
+# ── 子命令注册表 ──────────────────────────────────────────────────────
+# (子命令名, 处理函数, 中文说明)
+COMMANDS = [
+    ('search',         cmd_search,         '搜代码: 按关键词找代码文件'),
+    ('api',            cmd_api,            '搜 API 端点'),
+    ('prd',            cmd_prd,             '搜 PRD（防重复造轮子）'),
+    ('impact',         cmd_impact,         '影响分析: 改某接口影响哪些页面/按钮'),
+    ('context360',     cmd_context360,     '符号 360 度视图（端点/函数/处理器）'),
+    ('context',        cmd_context,        '上下文打包（代码+页面+字段+PRD+API，可 --role 角色裁剪）'),
+    ('coverage',       cmd_coverage,       '功能×测试覆盖矩阵（标出回归盲区）'),
+    ('feature',        cmd_feature,        '功能画像（端点+按钮+测试+页面）'),
+    ('workflow',       cmd_workflow,       '业务流程链（query→create→audit→...）'),
+    ('hop',            cmd_hop,            '多跳遍历（知识图谱核心，从一符号递归 N 跳）'),
+    ('wiki',           cmd_wiki,           'Repo Wiki 搜索（模块语义文档）'),
+    ('fill-prototype', cmd_fill_prototype, '原型预填（真实数据填模板，输出 80% HTML）'),
+    ('design-system',  cmd_design_system,  '设计系统查询（布局指纹/颜色token/组件表）'),
+]
+
+
+def _usage():
+    """打印用法清单。"""
+    lines = [
+        'kg.py — QODER 知识图谱统一 CLI（全系列通用）',
+        '',
+        '用法: python .qoder/scripts/kg.py <子命令> [参数]',
+        '',
+        '13 个子命令:',
+    ]
+    for name, _, desc in COMMANDS:
+        lines.append('  %-16s %s' % (name, desc))
+    lines += [
+        '',
+        '示例:',
+        '  kg.py search 考勤 --platform web',
+        '  kg.py impact /asset               # 改 /asset 影响谁',
+        '  kg.py coverage                    # 哪些功能没测试',
+        '  kg.py feature 资产管理            # 资产管理功能画像',
+        '  kg.py workflow assets             # 资产模块业务流程',
+        '  kg.py hop 资产管理 --depth 3      # 从资产管理出发 3 跳遍历',
+        '  kg.py context 车辆 --role pm      # PM 视角的上下文打包',
+        '',
+        'QoderWork 环境: AI 也会直接调 MCP 工具（mcp__qoder-knowledge-graph__*），功能等价。',
+    ]
+    return '\n'.join(lines)
+
+
+def main(argv=None):
+    argv = argv if argv is not None else sys.argv[1:]
+    if not argv or argv[0] in ('-h', '--help', 'help'):
+        print(_usage())
+        return 0
+    cmd = argv[0]
+    rest = argv[1:]
+    # 查找子命令
+    handler = None
+    for name, fn, _ in COMMANDS:
+        if name == cmd:
+            handler = fn
+            break
+    if handler is None:
+        print("未知子命令: %s" % cmd)
+        print(_usage())
+        return 1
+    # 执行（全容错，绝不抛栈）
+    try:
+        result = handler(rest)
+        if result:
+            print(result)
+    except Exception as e:
+        print("[error] %s 执行失败: %s" % (cmd, str(e)))
+        print("如果是索引/图谱问题，尝试: python .qoder/scripts/init_doctor.py --fix")
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())