@hupan56/wlkj 3.1.32 → 3.3.0

package/templates/qoder/scripts/domain/kg/extract/java/class_extractor.py

@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+"""类级注解提取器: Spring + Dubbo + Sa-Token + MyBatis-Plus。
+
+一次遍历类节点 → 识别 4 类后端组件 + 注入关系。
+"""
+from __future__ import annotations
+from . import _parser as P
+
+
+def extract(root, repo_id: str, filepath: str):
+    """提取类级实体 + 边。
+
+    返回 (entities: list[dict], edges: list[dict])。
+    实体类型: CONTROLLER / SERVICE / MAPPER / ENTITY / CONFIG
+    边类型:   implements / injects
+    """
+    entities, edges = [], []
+    if root is None:
+        return entities, edges
+
+    for cls in P.get_class_decls(root):
+        name = P.get_class_name(cls)
+        if not name:
+            continue
+        anns = P.get_annotations(cls)
+        implements = P.get_super_interfaces(cls)
+        superclass = P.get_superclass(cls)
+
+        # 按注解判定类型
+        etype = _classify(name, anns)
+        if not etype:
+            continue
+
+        # ===== 实体 =====
+        props = {
+            'annotations': sorted(anns.keys()),
+            'file': filepath,
+        }
+        if implements:
+            props['implements'] = implements
+        if superclass:
+            props['extends'] = superclass
+        # @TableName → 把表名塞 props
+        if 'TableName' in anns and anns['TableName']:
+            props['table_name'] = anns['TableName'].strip('"')
+        # @RequestMapping 类级 → 基础路径
+        if 'RequestMapping' in anns and anns['RequestMapping']:
+            props['base_path'] = anns['RequestMapping'].strip('"')
+
+        entities.append({
+            'id': P.entity_id(repo_id, _etype_prefix(etype), name),
+            'repo_id': repo_id,
+            'type': etype,
+            'canonical': name,
+            'cn': '',
+            'props': props,
+        })
+
+        # ===== implements 边 (ServiceImpl → 接口) =====
+        for iface in implements:
+            edges.append({
+                'from_id': P.entity_id(repo_id, _etype_prefix(etype), name),
+                'to_id': '%s:%s:%s' % (_etype_prefix(etype), repo_id, iface),
+                'edge_type': 'implements',
+                'from_repo': repo_id, 'to_repo': repo_id,
+                'confidence': 1.0, 'source': 'explicit',
+            })
+
+        # ===== extends 边 =====
+        if superclass and superclass != 'Object':
+            edges.append({
+                'from_id': P.entity_id(repo_id, _etype_prefix(etype), name),
+                'to_id': '%s:%s:%s' % (_etype_prefix(etype), repo_id, superclass),
+                'edge_type': 'extends',
+                'from_repo': repo_id, 'to_repo': repo_id,
+                'confidence': 1.0, 'source': 'explicit',
+            })
+
+        # ===== 注入边: @Autowired / @Resource / @DubboReference + final 字段 =====
+        has_required_args = 'RequiredArgsConstructor' in anns
+        for f in P.get_fields(cls):
+            fan = f['annotations']
+            is_inject = ('Autowired' in fan or 'Resource' in fan
+                         or 'DubboReference' in fan
+                         or (has_required_args and f['is_final']))
+            if is_inject and f['type']:
+                edge_type = 'dubbo_injects' if 'DubboReference' in fan else 'injects'
+                edges.append({
+                    'from_id': P.entity_id(repo_id, _etype_prefix(etype), name),
+                    'to_id': '%s:%s:%s' % (_etype_prefix(_guess_dep_type(f['type'])), repo_id, f['type']),
+                    'edge_type': edge_type,
+                    'from_repo': repo_id, 'to_repo': repo_id,
+                    'confidence': 1.0, 'source': 'explicit',
+                    'props': {'field': f['name'], 'dep_type': f['type'],
+                              'via_dubbo': 'DubboReference' in fan},
+                })
+
+    return entities, edges
+
+
+def _classify(name: str, anns: dict) -> str | None:
+    """按注解 + 命名规则判定实体类型。"""
+    if 'RestController' in anns or 'Controller' in anns:
+        return 'CONTROLLER'
+    if 'DubboService' in anns or 'Service' in anns:
+        return 'SERVICE'
+    if 'Mapper' in anns or (name.endswith('Mapper') and 'Repository' in anns):
+        return 'MAPPER'
+    if 'TableName' in anns:
+        return 'ENTITY'
+    # 命名兜底 (没注解但命名特征明显的)
+    if name.endswith('Mapper') and 'interface' not in str(anns):
+        return 'MAPPER'
+    if name.endswith('Controller'):
+        return 'CONTROLLER'
+    if name.endswith('ServiceImpl'):
+        return 'SERVICE'
+    if 'Configuration' in anns:
+        return 'CONFIG'
+    return None
+
+
+def _etype_prefix(etype: str) -> str:
+    """entity_id 前缀（区分 Java 后端各层）。
+    SVC=Service, MAP=Mapper, ENT=Entity, CTRL=Controller, CFG=Config
+    """
+    return {
+        'CONTROLLER': 'CTRL', 'SERVICE': 'SVC', 'MAPPER': 'MAP',
+        'ENTITY': 'ENT', 'CONFIG': 'CFG',
+    }.get(etype, 'J')
+
+
+def _guess_dep_type(simple_type: str) -> str:
+    """根据字段类型名猜它属于哪层（用于注入边的 to_id 前缀）。"""
+    if simple_type.endswith('Mapper'):
+        return 'MAPPER'
+    if simple_type.endswith('ServiceImpl') or simple_type.endswith('Service'):
+        return 'SERVICE'
+    if simple_type.endswith('Controller'):
+        return 'CONTROLLER'
+    return 'SVC'  # 默认当 Service

package/templates/qoder/scripts/domain/kg/extract/java/domain_extractor.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+"""领域对象提取器: Entity/BO/VO/Form → DTO/ENTITY + 字段→列映射 + 校验规则。
+
+处理 class_extractor 没识别为后端组件的类（DTO、BO、VO、Form）。
+关键:
+  - @TableName 的类 → ENTITY + 建 TABLE 实体 + maps_to 边
+  - 字段的 @TableField("user_id") → COLUMN 实体 + 列名映射
+  - 字段的 @NotNull/@Size → VALIDATION 实体 + validates 边
+  - 字段 javadoc /** 用户ID */ → cn (字段中文含义, 喂给 query_schema)
+"""
+from __future__ import annotations
+from . import _parser as P
+
+_VALIDATION = {'NotNull', 'NotBlank', 'NotEmpty', 'Size', 'Min', 'Max',
+               'Email', 'Pattern', 'Positive', 'Negative', 'Digits'}
+
+
+def extract(root, repo_id: str, filepath: str):
+    """提取领域对象 + 字段映射 + 校验规则。
+
+    Returns: (entities, edges)
+    """
+    entities, edges = [], []
+    if root is None:
+        return entities, edges
+
+    for cls in P.get_class_decls(root):
+        name = P.get_class_name(cls)
+        if not name:
+            continue
+        anns = P.get_annotations(cls)
+        fields = P.get_fields(cls)
+        # enum 的常量也算"字段" (枚举值)
+        is_enum = cls.type == 'enum_declaration'
+        if is_enum:
+            enum_consts = P.find_all(cls, 'enum_constant')
+            for ec in enum_consts:
+                ec_name = P._text(P.find_first(ec, 'identifier') or ec)
+                if ec_name:
+                    fields.append({'name': ec_name, 'type': name, 'annotations': {},
+                                   'is_final': True, 'is_static': True, 'comment': ''})
+        # 路径判定 (放宽: domain/dto/vo 目录下的类即使无字段也算领域对象)
+        fp_norm = filepath.replace('\\', '/').lower()
+        in_domain = '/domain/' in fp_norm
+        in_dto_dir = any('/'+d+'/' in fp_norm for d in ['vo','bo','dto','form','qry','param','query'])
+        if not fields and not (in_domain or in_dto_dir or is_enum):
+            continue  # 非领域目录且无字段 → 跳过
+
+        # @TableName → ENTITY + TABLE 实体 + maps_to
+        table_name = ''
+        if 'TableName' in anns and anns['TableName']:
+            table_name = anns['TableName'].strip('"').strip("'")
+
+        # 判定是否领域对象 (有 @TableName 或 命名特征 或 在 domain/dto 目录下)
+        is_entity = bool(table_name)
+        is_dto = (name.endswith('Vo') or name.endswith('BO') or name.endswith('Bo')
+                  or name.endswith('Form') or name.endswith('DTO') or name.endswith('Dto')
+                  or name.endswith('Body') or name.endswith('Request')
+                  or name.endswith('Response') or name.endswith('Result'))
+        # 放宽: domain/ 或 dto 子目录下的类/枚举默认归 DTO
+        if not is_entity and not is_dto and (in_domain or in_dto_dir or is_enum):
+            is_dto = True
+
+        if not is_entity and not is_dto:
+            continue
+
+        dto_type = 'ENTITY' if is_entity else 'DTO'
+        dto_id = ('ENT:%s:%s' if is_entity else 'DTO:%s:%s') % (repo_id, name)
+        field_infos = []
+        for f in fields:
+            field_infos.append({
+                'name': f['name'], 'type': f['type'],
+                'comment': f.get('comment', ''),
+                'column': _field_column(f, table_name),
+            })
+        entities.append({
+            'id': dto_id, 'repo_id': repo_id, 'type': dto_type,
+            'canonical': name, 'cn': '',
+            'props': {'fields': field_infos, 'table': table_name,
+                      'file': filepath},
+        })
+
+        # ENTITY → TABLE 实体 + maps_to 边
+        if is_entity and table_name:
+            tbl_id = 'TBL:%s:%s' % (repo_id, table_name)
+            entities.append({
+                'id': tbl_id, 'repo_id': repo_id, 'type': 'TABLE',
+                'canonical': table_name, 'cn': '',
+                'props': {'from_entity': name},
+            })
+            edges.append({
+                'from_id': dto_id, 'to_id': tbl_id,
+                'edge_type': 'maps_to',
+                'from_repo': repo_id, 'to_repo': repo_id,
+                'confidence': 1.0, 'source': 'explicit',
+            })
+
+            # 字段 → COLUMN + VALIDATION
+            for f in fields:
+                col_name = _field_column(f, table_name)
+                if not col_name:
+                    continue
+                col_id = 'COL:%s:%s.%s' % (repo_id, table_name, col_name)
+                entities.append({
+                    'id': col_id, 'repo_id': repo_id, 'type': 'COLUMN',
+                    'canonical': col_name, 'cn': f.get('comment', ''),
+                    'props': {'table': table_name, 'field': f['name'],
+                              'java_type': f['type']},
+                })
+                # 校验
+                for v in _VALIDATION:
+                    if v in f['annotations']:
+                        val_id = 'VAL:%s:%s.%s.%s' % (repo_id, table_name, col_name, v)
+                        entities.append({
+                            'id': val_id, 'repo_id': repo_id, 'type': 'VALIDATION',
+                            'canonical': '%s.%s.%s' % (table_name, col_name, v), 'cn': '',
+                            'props': {'rule': v, 'arg': f['annotations'][v],
+                                      'table': table_name, 'column': col_name},
+                        })
+                        edges.append({
+                            'from_id': val_id, 'to_id': col_id,
+                            'edge_type': 'validates',
+                            'from_repo': repo_id, 'to_repo': repo_id,
+                            'confidence': 1.0, 'source': 'explicit',
+                        })
+
+    return entities, edges
+
+
+def _field_column(field: dict, table_name: str) -> str:
+    """从字段提取数据库列名。
+    @TableField("user_id") → 'user_id'
+    @TableId → 'id' (或 value)
+    无注解 → 驼峰转下划线 (userId → user_id)
+    """
+    fan = field['annotations']
+    if 'TableField' in fan and fan['TableField']:
+        return fan['TableField'].strip('"').strip("'").split('.')[0]
+    if 'TableId' in fan:
+        return fan['TableId'].strip('"').strip("'") or 'id'
+    # 驼峰转下划线
+    name = field['name']
+    out = []
+    for i, c in enumerate(name):
+        if c.isupper() and i > 0:
+            out.append('_')
+        out.append(c.lower())
+    return ''.join(out)

package/templates/qoder/scripts/domain/kg/extract/java/dubbo_extractor.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""Dubbo RPC 提取器（@DubboService/@DubboReference）。
+
+职责: 识别 Dubbo 服务暴露/消费关系（跨进程 RPC 边）。
+本项目用 Dubbo 不是纯 Spring Autowired, DubboReference 字段是关键注入来源。
+共享 class_extractor 的提取逻辑, 这里按 Dubbo 关注点导出。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import class_extractor as _ce
+
+DUBBO_EXPOSE = {'DubboService'}
+DUBBO_CONSUME = {'DubboReference'}
+
+
+def is_dubbo_component(annotations: dict) -> bool:
+    """类是否 @DubboService 暴露。"""
+    return bool(set(annotations.keys()) & DUBBO_EXPOSE)
+
+
+def has_dubbo_reference(class_annotations: dict, fields: list) -> bool:
+    """类或字段是否有 @DubboReference 消费。"""
+    if set(class_annotations.keys()) & DUBBO_CONSUME:
+        return True
+    for f in fields:
+        if set(f.get('annotations', {}).keys()) & DUBBO_CONSUME:
+            return True
+    return False
+
+
+def extract(root, repo_id: str, filepath: str):
+    """Dubbo 类级提取（转发到 class_extractor, 行为一致）。"""
+    return _ce.extract(root, repo_id, filepath)

package/templates/qoder/scripts/domain/kg/extract/java/endpoint_extractor.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""HTTP 端点提取器（@GetMapping/@PostMapping/@PutMapping/@DeleteMapping）。
+
+职责: 从方法注解提取 HTTP 端点 → ENDPOINT 实体 + handled_by 边。
+共享 member_extractor 的方法遍历逻辑。
+"""
+from __future__ import annotations
+from . import _parser as P
+from . import member_extractor as _me
+
+# 端点注解 → HTTP 动词
+ENDPOINT_ANN_TO_VERB = {
+    'GetMapping': 'GET', 'PostMapping': 'POST',
+    'PutMapping': 'PUT', 'DeleteMapping': 'DELETE',
+    'PatchMapping': 'PATCH', 'RequestMapping': 'ANY',
+}
+
+
+def is_endpoint(annotations: dict) -> bool:
+    """方法是否是 HTTP 端点。"""
+    return bool(set(annotations.keys()) & set(ENDPOINT_ANN_TO_VERB.keys()))
+
+
+def extract_path(method_annotations: dict, class_annotations: dict) -> str:
+    """提取端点路径（类级 @RequestMapping + 方法级 @GetMapping）。"""
+    return _me._extract_endpoint_path(method_annotations, class_annotations)
+
+
+def extract_verb(ann_names: list) -> str:
+    """提取 HTTP 动词。"""
+    return _me._extract_http_verb(ann_names)
+
+
+def extract(root, repo_id: str, filepath: str, owner_classes: list = None):
+    """端点提取（转发到 member_extractor, ENDPOINT 实体在那里产出）。"""
+    return _me.extract(root, repo_id, filepath, owner_classes or [])

package/templates/qoder/scripts/domain/kg/extract/java/javadoc_extractor.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""D1-② 提取 Java 类级 Javadoc → 填 entities.cn。
+
+读 Java 文件的 /** 类注释 */ 第一句, 匹配到 entities 表的 SERVICE/CONTROLLER/MAPPER/ENTITY/DTO 实体。
+免 LLM, 纯文本解析 (tree-sitter 提注释 + 正则取首句)。
+"""
+from __future__ import annotations
+import os
+import sys
+import re
+import glob
+import time
+
+_THIS = os.path.dirname(os.path.abspath(__file__))
+for _i in range(8):
+    _p = os.path.dirname(_THIS)
+    if os.path.isfile(os.path.join(_p, 'foundation', 'bootstrap.py')):
+        sys.path.insert(0, _p); break
+    _THIS = _p
+
+# 类级 Javadoc 正则: /** ... */ 紧跟 class/interface/enum
+_RE_JAVADOC = re.compile(
+    r'/\*\*\s*\n((?:\s*\*.*\n)+?)\s*\*/\s*\n\s*((?:public|private|abstract|final|\s)*)'
+    r'(?:class|interface|enum)\s+(\w+)',
+    re.MULTILINE
+)
+
+
+def extract_javadoc_first_line(content: str) -> dict:
+    """从 Java 文件提取 {类名: javadoc首句}。
+
+    只取类级 /** */ (紧跟 class/interface/enum 的), 不取方法级。
+    首句 = 去掉 * 前缀后的第一行非空文本。
+    """
+    out = {}
+    for m in _RE_JAVADOC.finditer(content):
+        cls_name = m.group(3)
+        javadoc_body = m.group(1)
+        # 清理 * 前缀 + @author/@param 等标签
+        lines = []
+        for line in javadoc_body.split('\n'):
+            line = line.strip().lstrip('*').strip()
+            if not line or line.startswith('@'):
+                continue
+            lines.append(line)
+        if lines:
+            out[cls_name] = lines[0][:80]  # 首句, 截断80字
+    return out
+
+
+def sync_javadoc_to_cn(repo_dir: str, repo_id: str, logger=print):
+    """扫 repo 下所有 Java 文件 → 提 Javadoc → 填 entities.cn。
+
+    只填 cn 为空的实体 (不覆盖已有)。
+    """
+    from domain.kg.extract.java import pg_upsert
+    from sqlalchemy import text
+
+    t0 = time.time()
+    java_files = glob.glob(os.path.join(repo_dir, '**', '*.java'), recursive=True)
+    java_files = [f for f in java_files if '/test/' not in f.replace('\\', '/').lower()
+                  and not f.endswith('Test.java')]
+    logger('  [javadoc] 扫描 %d 个 .java (repo=%s)' % (len(java_files), repo_id))
+
+    # 提取所有类的 Javadoc
+    class_javadoc = {}  # {ClassName: javadoc首句}
+    for jf in java_files:
+        try:
+            content = open(jf, encoding='utf-8', errors='replace').read()
+            class_javadoc.update(extract_javadoc_first_line(content))
+        except Exception:
+            pass
+    logger('  [javadoc] 提取到 %d 个类的 Javadoc' % len(class_javadoc))
+
+    if not class_javadoc:
+        return {'javadoc_extracted': 0, 'cn_filled': 0}
+
+    # 填 entities.cn (只填空的)
+    engine, _ = pg_upsert._get_pg_engine()
+    if engine is None:
+        return {'error': 'PG 不可用'}
+    ok = 0
+    with engine.begin() as conn:
+        for cls_name, javadoc in class_javadoc.items():
+            # 匹配 entities.canonical = cls_name (各种类型)
+            r = conn.execute(text("""
+                UPDATE entities SET cn = :cn
+                WHERE canonical = :name AND (cn IS NULL OR cn = '')
+                  AND type IN ('SERVICE','CONTROLLER','MAPPER','ENTITY','DTO','CONFIG')
+            """), {'cn': javadoc, 'name': cls_name})
+            ok += r.rowcount or 0
+    dt = time.time() - t0
+    logger('  [javadoc] 填充 %d 条 cn / %.1fs' % (ok, dt))
+    return {'javadoc_extracted': len(class_javadoc), 'cn_filled': ok, 'seconds': round(dt, 1)}
+
+
+if __name__ == '__main__':
+    import argparse, json
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--repo-dir', required=True)
+    ap.add_argument('--repo-id', default='')
+    args = ap.parse_args()
+    try:
+        from dotenv import load_dotenv
+        for p in ['wlinkj-workspace/backend/.env', '.env']:
+            if os.path.isfile(p): load_dotenv(p); break
+    except: pass
+    rid = args.repo_id or os.path.basename(args.repo_dir.rstrip('/\\'))
+    r = sync_javadoc_to_cn(args.repo_dir, rid)
+    print(json.dumps(r, ensure_ascii=False, indent=2))

package/templates/qoder/scripts/domain/kg/extract/java/llm_cn_filler.py

@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""D1-③ LLM 批量补 cn: 对没有 Javadoc 的实体用 qwen-plus 推断中文含义。
+
+批量 10 个/次, 并发 4 线程。
+"""
+from __future__ import annotations
+import os
+import sys
+import json
+import time
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+_THIS = os.path.dirname(os.path.abspath(__file__))
+for _i in range(8):
+    _p = os.path.dirname(_THIS)
+    if os.path.isfile(os.path.join(_p, 'foundation', 'bootstrap.py')):
+        sys.path.insert(0, _p); break
+    _THIS = _p
+
+_CN_PROMPT = """你是 Java 业务架构师。根据类名推断中文业务含义。
+对每个类, 返回一行 "类名|中文含义" (含义不超过20字, 描述这个类做什么)。
+只返回结果, 不要解释。
+
+示例:
+AssetController|资产管理控制器,提供资产CRUD接口
+QrCodeLoginServiceImpl|二维码登录服务实现
+EmployeeOnline|员工在线信息实体
+
+类列表:
+%s"""
+
+
+def _call_qwen(prompt: str, timeout: int = 30) -> str:
+    key = os.environ.get('DASHSCOPE_API_KEY', '')
+    base = os.environ.get('ALI_CHAT_BASE', '').rstrip('/')
+    model = os.environ.get('ALI_CHAT_MODEL', 'qwen-plus')
+    if not key or not base:
+        return ''
+    req = urllib.request.Request(
+        base + '/chat/completions',
+        data=json.dumps({'model': model, 'messages': [{'role': 'user', 'content': prompt}],
+                         'max_tokens': 800, 'temperature': 0.1}).encode('utf-8'),
+        headers={'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json'},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())['choices'][0]['message']['content']
+    except Exception:
+        return ''
+
+
+def _parse_cn_response(text: str) -> dict:
+    """解析 "类名|中文" 格式 → {类名: 中文}"""
+    out = {}
+    for line in (text or '').split('\n'):
+        line = line.strip()
+        if '|' not in line:
+            continue
+        parts = line.split('|', 1)
+        if len(parts) == 2:
+            cls = parts[0].strip()
+            cn = parts[1].strip()[:80]
+            if cls and cn:
+                out[cls] = cn
+    return out
+
+
+def llm_fill_cn(batch_size: int = 10, limit: int = 3000, logger=print):
+    """批量 LLM 补 cn。
+
+    Args:
+        batch_size: 每次 API 传几个类 (10)
+        limit: 总上限 (避免全量 5000+ 调太久)
+    """
+    from domain.kg.extract.java import pg_upsert
+    from sqlalchemy import text
+
+    engine, _ = pg_upsert._get_pg_engine()
+    if engine is None:
+        return {'error': 'PG 不可用'}
+
+    # 取 cn 为空的后端实体
+    with engine.connect() as conn:
+        rows = conn.execute(text("""
+            SELECT id, canonical, type FROM entities
+            WHERE type IN ('SERVICE','CONTROLLER','MAPPER','ENTITY','DTO','TABLE')
+              AND (cn IS NULL OR cn = '')
+            LIMIT :lim
+        """), {'lim': limit}).all()
+    logger('  [llm-cn] %d 个实体待补 cn' % len(rows))
+    if not rows:
+        return {'filled': 0}
+
+    # 分批
+    batches = [rows[i:i+batch_size] for i in range(0, len(rows), batch_size)]
+
+    def process_batch(batch):
+        """处理一批: 构造prompt → 调LLM → 解析 → 返回 [(id, cn)]"""
+        names = [r[1] for r in batch]
+        prompt = _CN_PROMPT % '\n'.join(names)
+        resp = _call_qwen(prompt)
+        cn_map = _parse_cn_response(resp)
+        results = []
+        for eid, canonical, etype in batch:
+            cn = cn_map.get(canonical)
+            if cn:
+                results.append((eid, cn))
+        return results
+
+    # 并发 4 线程
+    t0 = time.time()
+    all_updates = []
+    with ThreadPoolExecutor(max_workers=4) as ex:
+        futures = [ex.submit(process_batch, b) for b in batches]
+        for i, fut in enumerate(futures):
+            try:
+                all_updates += fut.result()
+            except Exception:
+                pass
+            if (i+1) % 10 == 0:
+                logger('  [llm-cn] %d/%d 批 (cn=%d)' % (i+1, len(batches), len(all_updates)))
+
+    # 批量写 PG
+    ok = 0
+    with engine.begin() as conn:
+        for eid, cn in all_updates:
+            try:
+                conn.execute(text("UPDATE entities SET cn=:cn WHERE id=:id AND (cn IS NULL OR cn='')"),
+                             {'cn': cn, 'id': eid})
+                ok += 1
+            except Exception:
+                pass
+    dt = time.time() - t0
+    logger('  [llm-cn] 填充 %d 条 cn / %.1fs' % (ok, dt))
+    return {'filled': ok, 'seconds': round(dt, 1)}
+
+
+if __name__ == '__main__':
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--limit', type=int, default=3000)
+    args = ap.parse_args()
+    try:
+        from dotenv import load_dotenv
+        for p in ['wlinkj-workspace/backend/.env', '.env']:
+            if os.path.isfile(p): load_dotenv(p); break
+    except: pass
+    r = llm_fill_cn(limit=args.limit)
+    print(json.dumps(r, ensure_ascii=False, indent=2))