@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/{kg.py → kg/kg.py}

@@ -1,708 +1,638 @@
-# -*- 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())
+# -*- 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')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""
+kg.py — QODER 知识图谱统一 CLI 入口（全系列通用）
+
+把原本只在 QoderWork MCP (kg_mcp_server.py) 里的知识图谱能力，
+统一成一套命令行子命令。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.dirname(os.path.abspath(__file__)))  # 子包→scripts/根
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(SCRIPTS_DIR)))  # 多一层: 子包→scripts→repo  # repo root
+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)  # 同包import
+
+
+# ── 路径与索引新鲜度（与底层一致）──────────────────────────────────────
+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_prefetch(args):
+    """需求上下文预测 + 批量预取: 输入一句需求描述, 一次返回多词合并的上下文。
+
+    治"串行试探式搜索"(查一个词不命中 → 换词再查 6+ 次)的轮次爆炸。
+    支持 --platform。
+    """
+    if not args:
+        return ("用法: kg.py prefetch \"<需求描述>\" [--platform web|app]\n"
+                "例: kg.py prefetch \"保险单OCR识别标注对比图\" --platform web")
+    rest = list(args)
+    plat = ''
+    rest2 = []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == '--platform' and i + 1 < len(rest):
+            plat = rest[i + 1]; i += 2; continue
+        rest2.append(a); i += 1
+    query = ' '.join(rest2) if rest2 else ''
+    if not query:
+        return "请提供需求描述（一句话）"
+    import prefetch as P
+    primary_cn, en_words = P.predict_words(query)
+    if not en_words:
+        # 降级: 预测不出词 → 单词 context_pack
+        import context_pack as C
+        return _capture(C._compute_and_print, query, plat, '') or "无匹配上下文"
+    targets = []
+    if plat and plat.lower() not in ('both', '两端'):
+        targets = [P.PLATFORM_MAP.get(plat.lower(), plat)]
+    elif plat:
+        targets = sorted(set(P.PLATFORM_MAP.values()))
+    collected = P._collect(targets, en_words)
+    return _capture(P._print_merged, query, plat, primary_cn, en_words, collected) or "无匹配上下文"
+
+
+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()
+        if not feats:
+            # entities 表为空 — 语义层未构建 (需要 build_entity_registry 等脚本, 非数据缺失)
+            total = con.execute("SELECT COUNT(*) FROM entities").fetchone()[0]
+            if total == 0:
+                return ("未找到功能 '%s'。知识图谱语义层 (entities) 为空 — "
+                        "需要管理员构建: npx @hupan56/wlkj run build_style_index.py "
+                        "(生成 entity-registry 后由 kg_duckdb 导入)。" % q)
+        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 表查询 — v3.0 f3: 转发到 common.kg_capabilities (单一真源, CLI/MCP共用)。"""
+    from common.kg_capabilities import workflow_query
+    return workflow_query(con, 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:
+        # v3.0 f3: 核心查询转发到 common.kg_capabilities.hop_query (CLI/MCP共用)
+        from common.kg_capabilities import hop_query
+        return hop_query(con, symbol, depth, multi_hop_fn=K.multi_hop)
+    finally:
+        try: con.close()
+        except Exception: pass
+
+
+def cmd_wiki(args):
+    """Repo Wiki 搜索 — v3.0 f3: 转发到 common.kg_capabilities.wiki_query (CLI/MCP共用)。"""
+    if not args:
+        return "用法: kg.py wiki <关键词>"
+    from common.kg_capabilities import wiki_query
+    result = wiki_query(args[0])
+    # CLI 额外提示
+    if 'matching' in result:
+        result += '\n\n  提示: 读 wiki 文档（带行号引用）比读源码更省 token'
+    return result
+
+
+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
+# v3.0: 单一真源移到 common/roles.py, 消除与 kg_mcp_server.py 的逐字重复
+try:
+    from common.roles import ROLE_SECTIONS, filter_by_role as _filter_by_role_imported
+    _filter_by_role = _filter_by_role_imported  # 保持旧调用名 _filter_by_role 兼容
+except Exception:
+    # 回退: 内联定义 (common 不可用时, 与 common/roles.py 保持一致)
+    ROLE_SECTIONS = {
+        'pm':     {'1', '2', '2b', '3', '4', '5', '7'},
+        'design': {'2', '2b', '3', '6'},
+        'dev':    {'1', '3', '5', '7'},
+        'test':   {'1', '4', '5'},
+        'admin':  {'4', '5'},
+    }
+
+    def _filter_by_role(text, role):
+        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 角色裁剪）'),
+    ('prefetch',       cmd_prefetch,       '需求上下文预测+批量预取（一句需求→多词合并，治串行搜索）'),
+    ('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 <子命令> [参数]',
+        '',
+        '14 个子命令:',
+    ]
+    for name, _, desc in COMMANDS:
+        lines.append('  %-16s %s' % (name, desc))
+    lines += [
+        '',
+        '示例:',
+        '  kg.py search 考勤 --platform web',
+        '  kg.py prefetch "保险单OCR识别" --platform web  # 写PRD前先批量预取',
+        '  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())