@hupan56/wlkj 2.7.12 → 3.1.2

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

@@ -1,708 +1,871 @@
-# -*- 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
+_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
+
+"""
+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. 参数统一 — 15 个子命令风格一致，对标 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 = get_repo_root()
+BASE_DIR = get_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 foundation.core.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 "请提供搜索关键词"
+    from domain.kg.search 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 <关键词>"
+    from domain.kg.search 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 <关键词>"
+    from domain.kg.search 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"
+    from domain.kg.search 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"
+    from domain.kg.search 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 "请提供业务关键词"
+    from domain.kg.search 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 "请提供需求描述（一句话）"
+    from domain.kg.search import prefetch as P
+    primary_cn, en_words = P.predict_words(query)
+    if not en_words:
+        # 降级: 预测不出词 → 单词 context_pack
+        from domain.kg.search 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 domain.kg.graph.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 domain.kg.graph.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 domain.kg.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"
+    from domain.kg.storage 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 domain.kg.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 domain.kg.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
+    from foundation.core.paths import find_script
+    script = find_script('fill_prototype.py')
+    if script is None:
+        return "fill_prototype.py 未找到 (脚本迁移后路径未更新)"
+    try:
+        r = _sp.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)
+
+
+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):
+        from foundation.core.paths import find_script
+        gen_script = find_script('gen_design_doc.py')
+        if gen_script is not None:
+            _sp.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()
+        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"
+
+
+def cmd_semantic(args):
+    """语义搜索: 用自然语言找代码/API (概念检索, 不依赖精确关键词)。
+
+    需先构建 embedding 向量 (管理员): kg_semantic.py build-embeddings。
+    模型未装时给出安装提示, 不崩溃。
+    """
+    if not args:
+        return ("用法: kg.py semantic <自然语言查询> [--top N]\n"
+                "  语义检索: 查'报销'能命中 expense/reimburse\n"
+                "  需先构建: python .qoder/scripts/domain/kg/graph/kg_semantic.py build-embeddings")
+    query = args[0]
+    top_k = 10
+    if '--top' in args:
+        idx = args.index('--top')
+        if idx + 1 < len(args):
+            try:
+                top_k = int(args[idx + 1])
+            except ValueError:
+                pass
+    from domain.kg.graph.kg_semantic import semantic_search, embedding_status
+    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 (95MB模型首次自动下载)")
+        elif st['embeddings_count'] == 0:
+            return ("语义检索未构建向量。请管理员运行:\n"
+                    "  python .qoder/scripts/domain/kg/graph/kg_semantic.py build-embeddings")
+    if not results:
+        return "无匹配结果"
+    out = ["语义搜索: %s (top %d)" % (query, len(results))]
+    for eid, text, score in results:
+        out.append("  %.3f  %s" % (score, text[:70]))
+    return '\n'.join(out)
+
+
+# ── 中文文案/报错溯源 (grep-text): 单进程安全兜底, 替代 findstr/s 全盘扫描 ──
+# 设计动机: 用户查"车辆不存在""项目车号"这类中文文案时, kg.py 的代码标识符索引
+# 天然查不到 (索引按英文标识符建)。AI 若兜底去 findstr /s 或 os.walk 全库
+# (8973+ 文件) → Windows 卡死 + 疯狂弹 cmd 窗口。本命令是这类需求的唯一安全通道:
+# 单进程、限定 data/code、限定扩展名、有行数上限, 绝不递归弹子进程。
+_GREP_EXTS = ('.java', '.vue', '.ts', '.tsx', '.js', '.jsx', '.xml', '.html',
+              '.json', '.sql', '.properties', '.yml', '.yaml', '.ftl', '.txt')
+
+
+def cmd_grep_text(args):
+    """中文文案/报错溯源: 在 data/code 里搜中文短语 (报错文案/字段标签/业务词)。
+
+    单进程 Python, 限定扩展名, 上限 200 命中 + 30 文件。绝不弹子进程窗口。
+    用法: kg.py grep-text <中文短语> [--ext java,vue] [--limit N] [--platform web|app]
+    """
+    if not args:
+        return ("用法: kg.py grep-text <中文短语> [选项]\n"
+                "  在 data/code 里搜中文文案/报错/字段标签 (kg.py search 查不到中文时用这个)\n"
+                "  --ext java,vue    限定文件类型 (默认: java/vue/ts/xml/json...)\n"
+                "  --limit N         最多返回 N 条命中 (默认 50)\n"
+                "  --platform web|app 只搜某平台源码\n"
+                "示例: kg.py grep-text 车辆不存在")
+    import os as _os
+    # kg.py 在 .qoder/scripts/domain/kg/ 下, 往上 4 级到 repo 根
+    here = _os.path.dirname(_os.path.abspath(__file__))  # .../domain/kg/
+    base = _os.path.dirname(_os.path.dirname(_os.path.dirname(_os.path.dirname(here))))  # repo 根
+    code_root = _os.path.join(base, 'data', 'code')
+    if not _os.path.isdir(code_root):
+        return ('data/code 不存在 (源码未克隆)。跑 python .qoder/scripts/deployment/setup/init_doctor.py --fix')
+
+    query = args[0]
+    # 解析选项
+    exts = set(_GREP_EXTS)
+    limit = 50
+    user_limit = None  # 记录用户是否显式传了 --limit (决定是否启用 early_stop)
+    plat = ''
+    i = 1
+    while i < len(args):
+        a = args[i]
+        if a == '--ext' and i + 1 < len(args):
+            exts = set('.' + e.lstrip('.') for e in args[i + 1].split(',') if e.strip())
+            i += 2; continue
+        if a == '--limit' and i + 1 < len(args):
+            try:
+                limit = max(1, int(args[i + 1]))
+                user_limit = limit  # 用户显式指定了, early_stop 不再介入
+            except ValueError: pass
+            i += 2; continue
+        if a == '--platform' and i + 1 < len(args):
+            plat = args[i + 1]; i += 2; continue
+        i += 1
+
+    # 平台 → 子目录过滤
+    proj_dirs = []
+    if not plat:
+        for d in sorted(_os.listdir(code_root)):
+            if _os.path.isdir(_os.path.join(code_root, d)) and not d.startswith('.'):
+                proj_dirs.append(d)
+    elif plat in ('web', 'pc'):
+        proj_dirs = [d for d in ('fywl-ui',) if _os.path.isdir(_os.path.join(code_root, d))]
+    elif plat in ('app', 'h5'):
+        proj_dirs = [d for d in ('Carmg-H5',) if _os.path.isdir(_os.path.join(code_root, d))]
+    else:
+        proj_dirs = [d for d in sorted(_os.listdir(code_root))
+                     if _os.path.isdir(_os.path.join(code_root, d)) and not d.startswith('.')]
+
+    hits = []
+    files_hit = 0
+    scanned = 0
+    import time as _time
+    deadline = _time.monotonic() + 15  # 硬超时 15s: data/code 大目录上避免 30s+ 卡死
+    timed_out = False
+    # 够用即停阈值: 仅当用户没显式指定 --limit 时启用 (默认场景快速溯源)。
+    # 用户传了 --limit 就完全尊重它, 不被 early_stop 截断 (原 max(10,min(limit,30))
+    # 会把 --limit 50 截成 30、把 --limit 5 抬到 10, 违背用户契约)。
+    early_stop = 30 if user_limit is None else None
+    for proj in proj_dirs:
+        proj_path = _os.path.join(code_root, proj)
+        for dirpath, dirnames, filenames in _os.walk(proj_path):
+            # 跳过明显的依赖/构建目录, 加速
+            dirnames[:] = [d for d in dirnames if d not in
+                           ('node_modules', '.git', 'target', 'dist', 'build', '.idea', '__pycache__')]
+            for fn in filenames:
+                # 文件级超时检查: 避免单个大文件卡死目录内循环 (15s 硬超时在目录级
+                # 检查时形同虚设)。已找到结果才超时退出, 没找到继续扫。
+                if hits and _time.monotonic() > deadline:
+                    timed_out = True
+                    break
+                ext = _os.path.splitext(fn)[1].lower()
+                if ext not in exts:
+                    continue
+                fp = _os.path.join(dirpath, fn)
+                # 跳过大文件 (>500KB 多半是生成/压缩文件, 拖慢扫描)
+                try:
+                    if _os.path.getsize(fp) > 500_000:
+                        continue
+                except OSError:
+                    continue
+                scanned += 1
+                done = False
+                try:
+                    with open(fp, 'r', encoding='utf-8', errors='ignore') as fh:
+                        for lineno, line in enumerate(fh, 1):
+                            # 逐文件行级超时检查: 极大文件逐行读也能及时退出
+                            if lineno % 20000 == 0 and hits and _time.monotonic() > deadline:
+                                timed_out = True
+                                done = True
+                                break
+                            if query in line:
+                                rel = _os.path.relpath(fp, code_root).replace('\\', '/')
+                                snippet = line.strip()[:120]
+                                hits.append((rel, lineno, snippet))
+                                if len(hits) >= limit:
+                                    done = True
+                                    break
+                                # 够用即停 (仅默认场景): 与 limit 同级行内检查,
+                                # 避免单文件多行命中跨过 early_stop (原34>30问题)
+                                if early_stop is not None and len(hits) >= early_stop:
+                                    done = True
+                                    break
+                except (OSError, UnicodeDecodeError):
+                    pass
+                if done or len(hits) >= limit:
+                    break
+                # 够用即停 (仅默认场景; 用户显式 limit 时 early_stop=None 跳过)
+                if early_stop is not None and len(hits) >= early_stop:
+                    break
+            if timed_out or len(hits) >= limit or (early_stop is not None and len(hits) >= early_stop):
+                break
+        if timed_out or len(hits) >= limit or (early_stop is not None and len(hits) >= early_stop):
+            break
+
+    # 统计命中文件数 (去重)
+    files_hit = len(set(h[0] for h in hits))
+    if not hits:
+        return ('未找到 "%s" (扫描 %d 个文件, %s)\n'
+                '提示: 换近义词, 或用 kg.py semantic "%s" 语义检索' % (
+                    query, scanned, '/'.join(proj_dirs) or 'data/code', query))
+    out = ['grep-text: "%s" → %d 命中 / %d 文件 (扫描 %d 文件%s)' % (
+        query, len(hits), files_hit, scanned, ', ⏱15s超时已返回部分结果' if timed_out else '')]
+    last_file = ''
+    for rel, lineno, snippet in hits:
+        if rel != last_file:
+            out.append('\n■ %s' % rel)
+            last_file = rel
+        out.append('  L%d: %s' % (lineno, snippet))
+    return '\n'.join(out)
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────
+
+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 foundation.identity.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/组件表）'),
+    ('semantic',       cmd_semantic,       '语义搜索（概念检索：查"报销"命中 expense）'),
+    ('grep-text',      cmd_grep_text,      '中文文案/报错溯源（findstr 替代，单进程不弹窗）'),
+]
+
+
+def _usage():
+    """打印用法清单。"""
+    lines = [
+        'kg.py — QODER 知识图谱统一 CLI（全系列通用）',
+        '',
+        '用法: python .qoder/scripts/kg.py <子命令> [参数]',
+        '',
+        '16 个子命令:',
+    ]
+    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 视角的上下文打包',
+        '  kg.py grep-text 车辆不存在         # 中文报错文案溯源 (findstr 安全替代)',
+        '',
+        'QoderWork 环境: AI 也会直接调 MCP 工具（mcp__qoder-knowledge-graph__*），功能等价。',
+    ]
+    return '\n'.join(lines)
+
+
+def _try_daemon(cmd, rest):
+    """尝试走 daemon 热路径。命中返回 True (已输出结果), 未命中返回 False (回退冷路径)。
+
+    daemon 常驻模型+连接, semantic 26.8s→0.08s。连不上/出错则透明回退。
+    """
+    try:
+        from kgd import kgd_client, DAEMON_COMMANDS
+    except Exception:
+        return False  # kgd 模块不可用 → 回退
+    if cmd not in DAEMON_COMMANDS:
+        return False  # 该命令不走 daemon
+    res = kgd_client.call(cmd, rest)
+    if res is None:
+        return False  # daemon 不在线/出错 → 回退
+    text, _secs = res
+    print(text)
+    return True
+
+
+def main(argv=None):
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # 解析 --no-daemon: 强制冷路径 (调试用)。剥离后不影响后续参数解析。
+    use_daemon = True
+    if '--no-daemon' in argv:
+        use_daemon = False
+        argv = [a for a in argv if a != '--no-daemon']
+
+    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
+
+    # ⚡ 优先走 daemon 热路径 (模型/连接已常驻, 秒回)
+    if use_daemon and _try_daemon(cmd, rest):
+        return 0
+
+    # 冷路径: 直接执行 handler (daemon 不在线 / --no-daemon / 不支持的命令)
+    # semantic 在 daemon 不在线时给加速提示 (它单次要 ~27s)
+    if cmd == 'semantic' and use_daemon:
+        print('[提示] daemon 未运行, semantic 将冷启动 (~27s)。')
+        print('       加速: python .qoder/scripts/domain/kg/server/kgd.py start  (常驻后 semantic → 0.08s)')
+    # 执行（全容错，绝不抛栈）
+    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())