@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/domain/kg/graph/kg_semantic.py

@@ -0,0 +1,683 @@
+# -*- 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()
+
+"""
+LLM semantic labeling layer for the knowledge graph.
+
+After kg_build.py extracts structural data (AST-level), this module:
+  1. Finds entities that lack semantic labels (cn == dir, no business_domain)
+  2. Outputs a labeling prompt for the AI (QoderWork) to fill in
+  3. Provides a write-back function to store labels in DuckDB
+
+The AI (QoderWork's LLM) sees the prompt during session-start or when
+kg_build reports new modules, and labels them — zero human trigger.
+
+Usage (called by AI automatically):
+  python kg_semantic.py --check       # check what needs labeling
+  python kg_semantic.py --label '{"assets": {"cn": "资产管理", "domain": "固定资产"}}'
+"""
+import json
+import os
+import re
+import sys
+
+SCRIPTS = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # 子包→scripts/根
+sys.path.insert(0, SCRIPTS)
+from foundation.core.paths import DATA_INDEX_DIR
+from domain.kg.storage.kg_duckdb import get_db, get_db_readonly
+
+DB_PATH = str(DATA_INDEX_DIR / 'kg.duckdb')
+
+
+def check_unlabeled():
+    """Find modules that need semantic labeling (cn == dir or cn is empty)."""
+    con = get_db()
+    # Find FEATURE entities where cn == dir (unlabeled) or cn is empty
+    rows = con.execute("""
+        SELECT id, canonical, cn FROM entities
+        WHERE type = 'FEATURE'
+          AND (cn = canonical OR cn = '' OR cn IS NULL)
+        ORDER BY canonical
+    """).fetchall()
+
+    if not rows:
+        return None
+
+    # Build labeling prompt
+    modules = []
+    for eid, dirname, cn in rows:
+        # Gather context: what endpoints/pages does this module have?
+        ep_count = con.execute(
+            "SELECT COUNT(*) FROM edges WHERE from_id = ? AND edge_type = 'has_endpoint'",
+            [eid]
+        ).fetchone()[0]
+        btn_count = con.execute(
+            "SELECT COUNT(*) FROM edges WHERE from_id = ? AND edge_type = 'has_button'",
+            [eid]
+        ).fetchone()[0]
+        # Sample endpoints for context
+        sample_eps = con.execute("""
+            SELECT e.to_id FROM edges e
+            WHERE e.from_id = ? AND e.edge_type = 'has_endpoint' LIMIT 5
+        """, [eid]).fetchall()
+
+        modules.append({
+            'dir': dirname,
+            'endpoints': ep_count,
+            'buttons': btn_count,
+            'sample_apis': [r[0].replace('E:', '') for r in sample_eps],
+        })
+
+    con.close()
+
+    prompt = {
+        'action': 'semantic_labeling_needed',
+        'description': '以下模块需要语义标注（中文名+业务领域）。请根据目录名和API端点推断。',
+        'modules': modules,
+        'instructions': (
+            '对每个模块返回: {"目录名": {"cn": "中文名", "domain": "业务领域"}}\n'
+            '示例: {"assets": {"cn": "资产管理", "domain": "固定资产管理"}}\n'
+            '然后用 kg_semantic.py --label 写回'
+        ),
+    }
+    return prompt
+
+
+def apply_labels(labels_json):
+    """Write semantic labels back to DuckDB.
+
+    labels_json: {"assets": {"cn": "资产管理", "domain": "固定资产"}, ...}
+    """
+    labels = json.loads(labels_json) if isinstance(labels_json, str) else labels_json
+    con = get_db()
+    updated = 0
+
+    for dirname, info in labels.items():
+        cn = info.get('cn', dirname)
+        domain = info.get('domain', '')
+
+        # Find the FEATURE entity by canonical name (dir)
+        rows = con.execute(
+            "SELECT id FROM entities WHERE type='FEATURE' AND canonical = ?",
+            [dirname]
+        ).fetchall()
+
+        for row in rows:
+            eid = row[0]
+            # Update cn
+            con.execute(
+                "UPDATE entities SET cn = ? WHERE id = ?",
+                [cn, eid]
+            )
+            # Update props with domain
+            props_row = con.execute(
+                "SELECT props FROM entities WHERE id = ?", [eid]
+            ).fetchone()
+            if props_row:
+                try:
+                    props = json.loads(props_row[0]) if props_row[0] else {}
+                except Exception:
+                    props = {}
+                props['business_domain'] = domain
+                props['labeled'] = True
+                con.execute(
+                    "UPDATE entities SET props = ? WHERE id = ?",
+                    [json.dumps(props, ensure_ascii=False), eid]
+                )
+            # Update alias
+            con.execute(
+                "INSERT OR REPLACE INTO aliases VALUES (?, ?)",
+                [cn.lower(), eid]
+            )
+            updated += 1
+
+    con.close()
+    return updated
+
+
+# ============================================================
+# 语义检索 (v3.1: bge-small-zh embedding)
+# ============================================================
+# 解决关键词精确匹配的漏召问题: 查"报销"能命中叫 expense/reimburse 的代码。
+# 用 sentence-transformers + BAAI/bge-small-zh-v1.5 (95MB, 512维, 完全离线)。
+#
+# 设计:
+#   - build_embeddings(): 遍历 entities 的 canonical+cn 文本, 批量生成向量写入 DuckDB
+#   - semantic_search(): query→向量→余弦相似度→top_k
+#   - 模型懒加载 + 进程内单例 (避免重复加载 95MB)
+#   - 模型未装时优雅降级: 不报错, 返回提示安装
+
+_MODEL_NAME = 'BAAI/bge-small-zh-v1.5'
+_MODEL = None  # 进程内单例
+
+
+def _load_model():
+    """懒加载 sentence-transformers 模型 (进程内单例)。
+
+    临时移除 common/ 等 scripts 子目录的 sys.path, 避免 common/filelock.py
+    遮蔽 pip 的 filelock 包 (huggingface_hub 需要 filelock.BaseFileLock)。
+    加载完恢复 sys.path。
+
+    Returns:
+        model 实例, 或 None (未安装 sentence-transformers / 加载失败)
+    """
+    global _MODEL
+    if _MODEL is not None:
+        return _MODEL
+    # 隔离: 临时移除所有含本地模块的 scripts 子目录, 防止遮蔽第三方包。
+    # 关键: common/filelock.py 会遮蔽 pip 的 filelock (huggingface_hub 需要
+    # filelock.BaseFileLock)。仅清 sys.path 不够 —— 若 filelock 已被 import 过
+    # (本进程早先走过 bootstrap), sys.modules 里缓存的是错的, 要一并清掉。
+    saved_paths = [p for p in sys.path]
+    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    sys.path[:] = [p for p in sys.path
+                   if not (p and p.lower().startswith(scripts_root.lower()))
+                   and os.path.basename(p) not in ('foundation', 'kg', 'mcp', 'report', 'test', 'setup')]
+    # 清掉被本地模块污染的 sys.modules 缓存 (filelock 等), 让第三方重新 import 干净版
+    _purged = {}
+    for mod_name in list(sys.modules):
+        if mod_name == 'filelock' or mod_name.startswith('filelock.'):
+            _purged[mod_name] = sys.modules.pop(mod_name)
+    try:
+        from sentence_transformers import SentenceTransformer
+        _MODEL = SentenceTransformer(_MODEL_NAME)
+        return _MODEL
+    except ImportError:
+        return None
+    except Exception:
+        return None
+    finally:
+        sys.path[:] = saved_paths  # 恢复 sys.path
+
+
+def embedding_status():
+    """检查 embedding 能力是否可用 + 已构建多少。"""
+    available = _load_model() is not None
+    con = get_db()
+    try:
+        count = con.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0]
+    except Exception:
+        count = 0
+    finally:
+        con.close()
+    return {
+        'model': _MODEL_NAME if available else None,
+        'available': available,
+        'installed_hint': 'pip install sentence-transformers' if not available else None,
+        'embeddings_count': count,
+    }
+
+
+def build_embeddings(batch_size=64):
+    """为 entities 表构建 embedding 向量并写入 DuckDB。
+
+    只 embed 有业务语义的实体类型 (FEATURE/MODULE/ENDPOINT/BUTTON),
+    跳过纯文件路径实体。文本 = canonical + cn (中英拼接, 提升检索召回)。
+
+    模型未装时直接返回 0, 不报错 (调用方自行提示)。
+    """
+    model = _load_model()
+    if model is None:
+        print('[semantic] sentence-transformers 未安装, 跳过 embedding 构建')
+        print('           安装: pip install sentence-transformers')
+        return 0
+
+    con = get_db()
+    try:
+        # 确保表存在 (旧 kg.duckdb 可能没有 embeddings 表)
+        from domain.kg.storage.kg_duckdb import init_schema
+        init_schema(con)
+        # 取需要 embed 的实体 (有业务语义的)
+        rows = con.execute(
+            "SELECT id, canonical, COALESCE(cn, '') FROM entities "
+            "WHERE type IN ('FEATURE', 'MODULE', 'ENDPOINT', 'BUTTON') "
+            "AND canonical IS NOT NULL AND canonical != ''"
+        ).fetchall()
+        if not rows:
+            return 0
+
+        # 清空旧 embedding
+        con.execute("DELETE FROM embeddings")
+
+        total = 0
+        texts = []
+        ids = []
+        for eid, canonical, cn in rows:
+            # 拼接文本: 中文名 + 英文名 (中英都有时检索效果最好)
+            text = (cn + ' ' + canonical).strip() if cn else canonical
+            texts.append(text)
+            ids.append(eid)
+
+        # 批量 encode
+        for i in range(0, len(texts), batch_size):
+            batch_texts = texts[i:i + batch_size]
+            batch_ids = ids[i:i + batch_size]
+            vecs = model.encode(batch_texts, normalize_embeddings=True)
+            for eid, text, vec in zip(batch_ids, batch_texts, vecs):
+                vec_list = [float(x) for x in vec]
+                con.execute(
+                    "INSERT INTO embeddings (entity_id, text, vec, model) VALUES (?, ?, ?, ?)",
+                    [eid, text, vec_list, _MODEL_NAME]
+                )
+            total += len(batch_texts)
+            if (i // batch_size) % 10 == 0:
+                print('  [semantic] %d/%d...' % (total, len(texts)))
+        return total
+    finally:
+        con.close()
+
+
+def semantic_search(query, top_k=10):
+    """语义搜索: query→向量→余弦相似度→top_k 实体。
+
+    Args:
+        query: 自然语言查询 (中文/英文均可), 如 "报销流程" "车辆调度"
+        top_k: 返回前 N 条
+    Returns:
+        [(entity_id, text, score), ...] 或 None (模型未装/无数据)
+    """
+    model = _load_model()
+    if model is None:
+        return None
+
+    con = get_db_readonly()
+    if con is None:
+        return None
+    try:
+        try:
+            count = con.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0]
+        except Exception:
+            return None  # embeddings 表不存在 (旧库)
+        if count == 0:
+            return None
+
+        # query 向量
+        q_vec = model.encode([query], normalize_embeddings=True)[0]
+        q_list = [float(x) for x in q_vec]
+
+        # 优先用 DuckDB 原生 list_dot_product (向量已 normalize, 点积=余弦相似度)。
+        # 比 Python 循环快 ~23x (553ms → 24ms, 5180 向量)。旧版 DuckDB 无此函数
+        # 则回退 Python 循环。
+        scored = None
+        try:
+            q_lit = '[' + ','.join('%.7f' % x for x in q_list) + ']'
+            sql_rows = con.execute(
+                "SELECT entity_id, text, list_dot_product(vec, " + q_lit + "::FLOAT[]) AS score "
+                "FROM embeddings WHERE vec IS NOT NULL ORDER BY score DESC LIMIT ?",
+                [top_k]
+            ).fetchall()
+            scored = [(eid, text, float(score)) for eid, text, score in sql_rows]
+        except Exception:
+            scored = None  # 函数不存在/SQL 失败 → 回退 Python
+
+        if scored is None:
+            # 回退: Python 端算余弦相似度 (兼容旧 DuckDB)
+            rows = con.execute("SELECT entity_id, text, vec FROM embeddings").fetchall()
+            scored = []
+            for eid, text, vec in rows:
+                if not vec:
+                    continue
+                score = sum(a * b for a, b in zip(q_list, vec))
+                scored.append((eid, text, score))
+            scored.sort(key=lambda x: -x[2])
+            scored = scored[:top_k]
+        return scored
+    finally:
+        con.close()
+
+
+def semantic_search_files(query, top_k=10, min_score=0.35):
+    """语义搜索 → 把实体解析回文件路径 (供 search_index/prefetch 接入)。
+
+    semantic_search 返回的是实体, 但用户要的是"读哪个文件"。这个函数把:
+      - ENDPOINT 实体 -> endpoints.controller_file (Java 后端)
+      - BUTTON 实体  -> eid 内嵌的 vue 文件路径 (B:{vue}:{handler})
+      - FEATURE 实体 -> modules.path (按 project+dir)
+    解析成可读文件, 附 cn(中文名) + score。
+
+    模型未装/无 embedding 时返回 None (调用方静默跳过, 不报错)。
+
+    Returns:
+        [(file_path, entity_id, cn, score), ...] 或 None
+    """
+    results = semantic_search(query, top_k=top_k * 2)  # 多取些, 解析失败会过滤掉
+    if not results:
+        return None
+
+    con = get_db_readonly()
+    if con is None:
+        # 只读连接失败 (文件不存在) → 至少返回原始实体信息 (无文件解析)
+        return [(eid, eid, text, score) for eid, text, score in results[:top_k]]
+    try:
+        out = []
+        seen_files = set()  # 去重 (同一文件多个实体只留最高分)
+        for eid, text, score in results:
+            if score < min_score:
+                continue
+            etype = eid.split(':', 1)[0] if ':' in eid else ''
+            file_path = None
+            cn = ''
+
+            if etype == 'E':
+                # ENDPOINT: 查 endpoints 表拿 controller_file
+                ep = eid[2:]
+                row = con.execute(
+                    "SELECT controller_file FROM endpoints WHERE endpoint = ?", [ep]
+                ).fetchone()
+                if row and row[0]:
+                    file_path = row[0]
+
+            elif etype == 'B':
+                # BUTTON: eid 格式 B:{vue_path}:{handler}, vue_path 含 .vue
+                parts = eid.split(':')
+                if len(parts) >= 2 and '.vue' in parts[1]:
+                    file_path = parts[1]
+                # cn 从 entities 表 (backfill 填的中文名)
+                row = con.execute("SELECT cn FROM entities WHERE id = ?", [eid]).fetchone()
+                cn = row[0] if row and row[0] else ''
+
+            elif etype == 'F':
+                # FEATURE: F:{project}:{dir} -> modules.path
+                fparts = eid.split(':')
+                if len(fparts) >= 3:
+                    proj, mod_dir = fparts[1], fparts[2]
+                    row = con.execute(
+                        "SELECT path FROM modules WHERE project = ? AND dir = ?",
+                        [proj, mod_dir]
+                    ).fetchone()
+                    if row and row[0]:
+                        file_path = '%s/%s' % (proj, row[0])
+                    row2 = con.execute("SELECT cn FROM entities WHERE id = ?", [eid]).fetchone()
+                    cn = row2[0] if row2 and row2[0] else ''
+
+            if file_path and file_path not in seen_files:
+                seen_files.add(file_path)
+                out.append((file_path, eid, cn or text, score))
+
+            if len(out) >= top_k:
+                break
+        return out if out else []
+    finally:
+        con.close()
+
+
+def filter_semantic_by_platform(results, platform, repo_base=None):
+    """把 semantic_search_files 的结果按 platform 过滤 + 补全项目前缀。
+
+    难点: BUTTON 实体的 vue 路径是相对路径 (无项目前缀, 如 hr/timeManage/...),
+    无法靠子串判项目。这里用文件实际存在性兜底, 并把相对路径补成可读全路径。
+
+    Args:
+        results: semantic_search_files 的输出 [(file_path, eid, cn, score), ...]
+        platform: 'web'/'app'/None
+        repo_base: 仓库根 (用于查文件存在性; 默认按 DATA_INDEX_DIR 推 repo 根)
+    Returns:
+        [(full_file_path, cn, score), ...] 已过滤 + 前缀补全
+    """
+    if not platform or not results:
+        # 无 platform 过滤, 只补前缀提示 (返回相对路径)
+        return [(fp.replace('\\', '/'), cn, sc) for fp, eid, cn, sc in results]
+    # platform -> 项目名 + view 根
+    _PF = {'web': 'fywl-ui', 'pc': 'fywl-ui', '管理端': 'fywl-ui',
+           'app': 'Carmg-H5', 'mobile': 'Carmg-H5', 'h5': 'Carmg-H5', '移动端': 'Carmg-H5'}
+    target = _PF.get(platform.lower(), platform)
+    if repo_base is None:
+        repo_base = str(DATA_INDEX_DIR.parent.parent)  # data/index -> data -> repo
+    view_root = None
+    if target == 'fywl-ui':
+        view_root = os.path.join(repo_base, 'data', 'code', 'fywl-ui', 'apps', 'ics', 'src', 'views')
+    elif target == 'Carmg-H5':
+        view_root = os.path.join(repo_base, 'data', 'code', 'Carmg-H5', 'src')
+
+    KNOWN_PROJ = ('fywl-ui', 'fywl-ics', 'Carmg-H5')
+    out = []
+    for fp, eid, cn, sc in results:
+        fp_norm = fp.replace('\\', '/')
+        first_seg = fp_norm.split('/')[0]
+        if first_seg in KNOWN_PROJ:
+            # 明确项目前缀 → 判项目名
+            if target.lower() in fp_norm.lower():
+                out.append((fp_norm, cn, sc))
+        elif view_root and os.path.isfile(os.path.join(view_root, fp_norm)):
+            # 相对路径 (BUTTON vue) → 存在性兜底 + 补前缀
+            if target == 'fywl-ui':
+                out.append(('fywl-ui/apps/ics/src/views/' + fp_norm, cn, sc))
+            else:
+                out.append((target + '/src/' + fp_norm, cn, sc))
+    return out
+
+
+# ============================================================
+# cn 回填 (v3.1.1: 为 BUTTON/ENDPOINT/CONTROLLER 补中文名)
+# ============================================================
+# kg_build 构建 BUTTON 时已尽量填 cn, 但存量库 / props 缺失 / ENDPOINT/CONTROLLER
+# 一直没中文。这个命令对存量实体做一次性回填:
+#   - BUTTON: 从 props.button_text 清洗 icon 字体(&#x...; / iconfont 类名) + 噪音
+#   - ENDPOINT: 从 path 末段提动词(get/add/update...) + 资源, 启发式翻译
+#   - CONTROLLER: CamelCase 拆词, 词典映射已知业务域 (Asset→资产 等)
+# 回填后需重算 embeddings (build-embeddings) 才能让语义检索命中中文。
+
+# 动词 → 中文 (覆盖常见 CRUD + 业务动作)
+_VERB_CN = {
+    'get': '查询', 'list': '列表', 'page': '分页', 'query': '查询', 'find': '查找',
+    'search': '搜索', 'detail': '详情', 'count': '统计', 'info': '信息',
+    'add': '新增', 'create': '创建', 'save': '保存', 'insert': '新增', 'new': '新增',
+    'edit': '编辑', 'update': '修改', 'modify': '修改', 'set': '设置', 'change': '变更',
+    'delete': '删除', 'remove': '移除', 'del': '删除',
+    'export': '导出', 'download': '下载', 'import': '导入', 'upload': '上传',
+    'submit': '提交', 'commit': '提交', 'apply': '申请', 'approve': '审批', 'reject': '驳回',
+    'check': '校验', 'verify': '核实', 'judge': '判定', 'validate': '校验',
+    'send': '发送', 'push': '推送', 'notify': '通知', 'mail': '邮件',
+    'start': '启动', 'begin': '开始', 'execute': '执行', 'run': '运行', 'finish': '完成', 'complete': '完成',
+    'login': '登录', 'logout': '登出', 'register': '注册', 'auth': '鉴权',
+    'bind': '绑定', 'unbind': '解绑', 'link': '关联', 'transfer': '转办',
+    'generate': '生成', 'parse': '解析', 'convert': '转换', 'sync': '同步',
+    'enable': '启用', 'disable': '停用', 'lock': '锁定', 'unlock': '解锁',
+    'reset': '重置', 'refresh': '刷新', 'copy': '复制', 'merge': '合并', 'split': '拆分',
+    'schedule': '排程', 'clock': '打卡', 'abnormal': '异常',
+}
+
+# 业务域 token → 中文 (CamelCase 拆词后逐词映射, 拼接成领域名)
+_DOMAIN_CN = {
+    'asset': '资产', 'assets': '资产', 'ledger': '台账', 'inventory': '盘点',
+    'vehicle': '车辆', 'car': '车辆', 'motor': '机车', 'model': '车型',
+    'maintain': '维护', 'maintenance': '维护', 'repair': '维修', 'fault': '故障',
+    'contract': '合同', 'supplier': '供应商', 'purchase': '采购', 'order': '订单',
+    'user': '用户', 'org': '组织', 'organization': '组织', 'dept': '部门',
+    'role': '角色', 'permission': '权限', 'auth': '权限', 'menu': '菜单',
+    'attendance': '考勤', 'clock': '打卡', 'leave': '请假', 'overtime': '加班',
+    'salary': '薪资', 'wage': '工资', 'payroll': '工资单',
+    'insurance': '保险', 'social': '社保',
+    'schedule': '排班', 'shift': '班次', 'plan': '计划', 'task': '任务',
+    'employee': '员工', 'staff': '员工', 'personnel': '人事', 'hr': '人事',
+    'mail': '邮件', 'message': '消息', 'notify': '通知', 'notice': '公告',
+    'file': '文件', 'document': '文档', 'doc': '文档', 'ocr': '识别', 'image': '图片',
+    'project': '项目', 'business': '业务', 'category': '分类', 'type': '类型',
+    'terminal': '终端', 'device': '设备', 'heartbeat': '心跳', 'redis': '缓存',
+    'log': '日志', 'report': '报表', 'export': '导出', 'import': '导入',
+    'feedback': '反馈', 'complaint': '投诉', 'evaluate': '评价',
+    'ocrasset': '资产识别', 'asssetlist': '资产列表',
+}
+
+
+def _clean_button_text(text):
+    """清洗按钮文本: 去 icon 字体编码 / iconfont 类名 / 多余空白, 保留中文。"""
+    if not text:
+        return ''
+    # 去 HTML 实体 icon 编码: &#xe600; &#x1f4e7;
+    t = re.sub(r'&#x[0-9a-fA-F]+;', '', text)
+    # 去 iconfont 类名残留 (如 :icon-plus: / iconfont-plus / icon-foo)
+    t = re.sub(r':?\s*icon[a-zA-Z0-9_-]*\s*:?', ' ', t, flags=re.IGNORECASE)
+    # 去 <i ...> 标签
+    t = re.sub(r'<[^>]+>', '', t)
+    # 去英文/数字噪音 token (handler 名混入等), 保留中文与必要符号
+    t = re.sub(r'[A-Za-z_][A-Za-z0-9_]*', '', t)
+    # 去 Vue 模板表达式残留 ({{ . }} / { var } / ${...})
+    t = re.sub(r'\{\{?\s*[^}]*\}?\}', '', t)
+    # 合并空白 + 去首尾符号/冒号
+    t = re.sub(r'\s+', ' ', t).strip(' >\t\r\n,，;；:-')
+    return t
+
+
+def _endpoint_to_cn(endpoint):
+    """从 endpoint path 启发式翻译成中文标签。
+    例: /updateOcrAssetList -> '修改 资产识别列表', /getManufactorList -> '查询 厂商列表'
+    失败时返回 '' (不强行造词, 避免污染检索)。"""
+    if not endpoint:
+        return ''
+    # 取最后一段 path (去掉 {id} 等参数段)
+    seg = endpoint.rstrip('/').split('/')[-1]
+    seg = re.sub(r'\{.*?\}', '', seg).strip()
+    if not seg or len(seg) <= 1:
+        return ''
+    # 拆成词: camelCase 切分 + 斜杠/下划线
+    parts = re.findall(r'[A-Z]?[a-z]+|[A-Z]+(?=[A-Z]|$)', seg)
+    parts = [p.lower() for p in parts if len(p) >= 2]
+    if not parts:
+        return ''
+    # 第一个动词词 → 中文动作, 其余 → 领域词
+    cn_parts = []
+    verb_done = False
+    for w in parts:
+        if not verb_done and w in _VERB_CN:
+            cn_parts.append(_VERB_CN[w])
+            verb_done = True
+        elif w in _DOMAIN_CN:
+            cn_parts.append(_DOMAIN_CN[w])
+    # 末尾 List/Page/All/Detail/By 后缀
+    if parts and parts[-1] == 'list' and '列表' not in cn_parts:
+        cn_parts.append('列表')
+    elif parts and parts[-1] == 'detail' and '详情' not in cn_parts:
+        cn_parts.append('详情')
+    return ' '.join(cn_parts) if cn_parts else ''
+
+
+def _controller_to_cn(name):
+    """从 Controller 类名翻译中文领域名。
+    例: AssetGeneralLedgerController -> '资产 台账',
+        VehicleModelAnalysisController -> '车辆 车型 分析'."""
+    if not name:
+        return ''
+    base = name.replace('Controller', '').replace('RestController', '')
+    # CamelCase 拆词
+    parts = re.findall(r'[A-Z]?[a-z]+|[A-Z]+(?=[A-Z]|$)', base)
+    parts = [p.lower() for p in parts if len(p) >= 2]
+    cn_parts = [_DOMAIN_CN[w] for w in parts if w in _DOMAIN_CN]
+    # 去重保序
+    seen = set()
+    uniq = []
+    for c in cn_parts:
+        if c not in seen:
+            seen.add(c)
+            uniq.append(c)
+    return ' '.join(uniq) if uniq else ''
+
+
+def backfill_cn():
+    """回填 BUTTON/ENDPOINT/CONTROLLER 的 cn 字段 (存量库一次性补全)。
+
+    只更新 cn 为空的实体 (不覆盖已有中文)。回填后建议重算 embeddings。
+    Returns: dict {type: updated_count}
+    """
+    con = get_db()
+    try:
+        stats = {'BUTTON': 0, 'ENDPOINT': 0, 'CONTROLLER': 0}
+
+        # BUTTON: 从 props.button_text 清洗
+        rows = con.execute(
+            "SELECT id, props FROM entities WHERE type='BUTTON' "
+            "AND (cn = '' OR cn IS NULL)"
+        ).fetchall()
+        for eid, props_json in rows:
+            try:
+                props = json.loads(props_json) if props_json else {}
+            except Exception:
+                props = {}
+            btn_text = props.get('button_text', '')
+            cn = _clean_button_text(btn_text)
+            if cn:
+                con.execute("UPDATE entities SET cn=? WHERE id=?", [cn, eid])
+                con.execute("INSERT OR REPLACE INTO aliases VALUES (?, ?)", [cn.lower(), eid])
+                stats['BUTTON'] += 1
+
+        # ENDPOINT: 启发式翻译 path
+        rows = con.execute(
+            "SELECT id, canonical FROM entities WHERE type='ENDPOINT' "
+            "AND (cn = '' OR cn IS NULL)"
+        ).fetchall()
+        for eid, canonical in rows:
+            cn = _endpoint_to_cn(canonical)
+            if cn:
+                con.execute("UPDATE entities SET cn=? WHERE id=?", [cn, eid])
+                con.execute("INSERT OR REPLACE INTO aliases VALUES (?, ?)", [cn.lower(), eid])
+                stats['ENDPOINT'] += 1
+
+        # CONTROLLER: 类名翻译
+        rows = con.execute(
+            "SELECT id, canonical FROM entities WHERE type='CONTROLLER' "
+            "AND (cn = '' OR cn IS NULL)"
+        ).fetchall()
+        for eid, canonical in rows:
+            cn = _controller_to_cn(canonical)
+            if cn:
+                con.execute("UPDATE entities SET cn=? WHERE id=?", [cn, eid])
+                con.execute("INSERT OR REPLACE INTO aliases VALUES (?, ?)", [cn.lower(), eid])
+                stats['CONTROLLER'] += 1
+
+        return stats
+    finally:
+        con.close()
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1 and sys.argv[1] == '--check':
+        result = check_unlabeled()
+        if result:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            print('{"status": "all_labeled", "message": "所有模块已有语义标注"}')
+
+    elif len(sys.argv) > 2 and sys.argv[1] == '--label':
+        count = apply_labels(sys.argv[2])
+        print('Updated %d entities with semantic labels' % count)
+
+    elif len(sys.argv) > 1 and sys.argv[1] == 'build-embeddings':
+        n = build_embeddings()
+        print('Built %d embeddings' % n)
+
+    elif len(sys.argv) > 2 and sys.argv[1] == 'search':
+        results = semantic_search(sys.argv[2])
+        if results:
+            for eid, text, score in results:
+                print('  %.3f  %s' % (score, text[:70]))
+        else:
+            print('(无结果或 embedding 未构建)')
+
+    elif len(sys.argv) > 1 and sys.argv[1] == '--status':
+        st = embedding_status()
+        print(json.dumps(st, ensure_ascii=False, indent=2))
+
+    elif len(sys.argv) > 1 and sys.argv[1] == '--backfill-cn':
+        stats = backfill_cn()
+        print('cn 回填完成:')
+        for t, c in stats.items():
+            print('  %-12s: %d' % (t, c))
+        print('(建议接着跑: python kg_semantic.py build-embeddings)')
+
+    else:
+        print('Usage:')
+        print('  python kg_semantic.py --check    # 查看待标注模块')
+        print('  python kg_semantic.py --label \'{"assets":{"cn":"资产管理","domain":"固定资产"}}\'')
+        print('  python kg_semantic.py build-embeddings  # 构建 embedding 向量')
+        print('  python kg_semantic.py search 报销       # 语义搜索')
+        print('  python kg_semantic.py --status          # embedding 状态')
+        print('  python kg_semantic.py --backfill-cn     # 回填 BUTTON/ENDPOINT/CONTROLLER 中文')