@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/common/result.py

@@ -0,0 +1,223 @@
+# -*- coding: utf-8 -*-
+"""
+result.py - 统一结果类型 + 优雅错误处理
+
+治"容错率低"的底层基建。现状各脚本错误风格极不统一:
+  - 裸 except Exception: pass 吞异常 (build_style_index / eval_prd / team_sync)
+  - exit code 含义不一致 (eval_prd 1=不达标或文件不存在; team_sync 0/1/2/3 四档)
+  - 调用方只能 parse 中文文案, 无法程序化决策
+
+本模块引入:
+  1. Result 数据类: ok / code / msg / data, 语义化 code
+  2. graceful_error 装饰器: 把 Result/异常翻译成"人类/AI 可读文本 + 一致 exit code"
+  3. 统一 exit code 表 (替代散落各处的魔法数字)
+
+设计原则 (与方案一致):
+  - 失败不崩, 输出可读诊断 + 建议下一步
+  - 调用方能据 code 程序化决策, 不靠 parse 中文
+  - eval_prd 门禁从"硬阻塞"改"软门禁" (WARN 带警告发布)
+
+Usage:
+    from common.result import Result, OK, fail, warn, graceful_error
+
+    @graceful_error
+    def main():
+        r = do_something()
+        if not r.ok:
+            return r          # 装饰器翻译成可读输出 + exit code
+        return Result.ok(data=r.data)
+
+Exit code 约定 (全脚本统一, 替代散落魔法数字):
+    0  OK           成功
+    1  GENERIC      通用失败 (未分类)
+    2  BUSY         资源占用 (如 kg_db 被占)
+    3  CONFLICT     冲突需人工 (如 team_sync SYNC_CONFLICT)
+    4  AUTHZ        身份/权限拒绝 (与 identity.EXIT_AUTHZ 对齐)
+    5  NOT_FOUND    文件/资源不存在
+    6  INDEX_MISSING 索引缺失 (需先 init/doctor)
+    7  BELOW_THRESH  门禁未达标 (eval_prd, 软门禁可带警告继续)
+    8  NETWORK      网络/外部服务不可达
+    9  DEPS_MISSING 依赖未装 (pip 包缺失)
+"""
+
+import functools
+import sys
+import traceback
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+__all__ = [
+    "Result",
+    "OK",
+    "ResultError",
+    "ok",
+    "fail",
+    "warn",
+    "graceful_error",
+    "EXIT",
+    "code_to_exit",
+    "CODE",
+]
+
+
+# ============================================================
+# 语义化 code 常量 (调用方据此程序化决策)
+# ============================================================
+
+class CODE:
+    """结果 code 常量。小写字符串, 语义化, 跨脚本一致。"""
+    OK = "ok"
+    GENERIC = "generic"            # 通用未分类
+    BUSY = "busy"                  # 资源占用 (kg_db 锁)
+    CONFLICT = "conflict"          # 冲突需人工
+    AUTHZ = "authz"                # 身份/权限
+    NOT_FOUND = "not_found"        # 文件/资源不存在
+    INDEX_MISSING = "index_missing"  # 索引缺失
+    BELOW_THRESH = "below_thresh"  # 门禁未达标
+    NETWORK = "network"            # 网络不可达
+    DEPS_MISSING = "deps_missing"  # 依赖未装
+
+
+# ============================================================
+# code → exit code 映射 (一处定义, 全脚本统一)
+# ============================================================
+
+EXIT = {
+    CODE.OK: 0,
+    CODE.GENERIC: 1,
+    CODE.BUSY: 2,
+    CODE.CONFLICT: 3,
+    CODE.AUTHZ: 4,
+    CODE.NOT_FOUND: 5,
+    CODE.INDEX_MISSING: 6,
+    CODE.BELOW_THRESH: 7,
+    CODE.NETWORK: 8,
+    CODE.DEPS_MISSING: 9,
+}
+
+
+def code_to_exit(code: str) -> int:
+    """code → exit code, 未知 code 回退 1。"""
+    return EXIT.get(code, 1)
+
+
+# ============================================================
+# Result 数据类
+# ============================================================
+
+@dataclass
+class Result:
+    """统一结果。
+
+    Attributes:
+        ok:     是否成功
+        code:   语义化 code (见 CODE 常量), 调用方据此决策
+        msg:    人类可读消息
+        data:   成功时携带的数据 (任意)
+        hint:   失败时的"下一步建议" (可选, 输出给用户/AI)
+    """
+    ok: bool
+    code: str = CODE.GENERIC
+    msg: str = ""
+    data: Any = None
+    hint: Optional[str] = None
+
+    # ---- 工厂方法 ----
+    @classmethod
+    def success(cls, data: Any = None, msg: str = "", code: str = CODE.OK) -> "Result":
+        return cls(ok=True, code=code, msg=msg, data=data)
+
+    @classmethod
+    def failure(cls, msg: str, code: str = CODE.GENERIC,
+                hint: Optional[str] = None, data: Any = None) -> "Result":
+        return cls(ok=False, code=code, msg=msg, hint=hint, data=data)
+
+    @classmethod
+    def warning(cls, msg: str, code: str = CODE.BELOW_THRESH,
+                hint: Optional[str] = None, data: Any = None) -> "Result":
+        """WARN: 软门禁/带警告继续。ok=True (可继续), 但带警告。"""
+        return cls(ok=True, code=code, msg=msg, hint=hint, data=data)
+
+    # ---- 便捷判断 ----
+    @property
+    def is_warn(self) -> bool:
+        """是否为"成功但有警告"(如门禁 WARN 档)。"""
+        return self.ok and self.code != CODE.OK
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+# 模块级便捷别名 (常见用法)
+OK = Result.success()
+ResultError = type("ResultError", (Exception,), {})  # 预留: 未来 raise Result(r)
+
+
+def ok(data: Any = None, msg: str = "") -> Result:
+    return Result.success(data=data, msg=msg)
+
+
+def fail(msg: str, code: str = CODE.GENERIC, hint: Optional[str] = None) -> Result:
+    return Result.failure(msg=msg, code=code, hint=hint)
+
+
+def warn(msg: str, code: str = CODE.BELOW_THRESH, hint: Optional[str] = None) -> Result:
+    return Result.warning(msg=msg, code=code, hint=hint)
+
+
+# ============================================================
+# graceful_error 装饰器
+# ============================================================
+
+def _emit(r: Result, *, exit_on_fail: bool = True) -> int:
+    """把 Result 翻译成可读输出 + 返回 exit code。"""
+    if r.ok and not r.is_warn:
+        if r.msg:
+            print(r.msg)
+        return 0
+    if r.is_warn:
+        # WARN: 打印警告但不当失败
+        print("[WARN] {}".format(r.msg))
+        if r.hint:
+            print("       -> {}".format(r.hint))
+        return code_to_exit(r.code) if False else 0  # WARN 视为成功 (exit 0)
+    # FAIL
+    tag = r.code.upper() if r.code != CODE.GENERIC else "ERROR"
+    print("[{}] {}".format(tag, r.msg))
+    if r.hint:
+        print("       -> {}".format(r.hint))
+    if exit_on_fail:
+        sys.exit(code_to_exit(r.code))
+    return code_to_exit(r.code)
+
+
+def graceful_error(func):
+    """装饰 main(): 统一把返回值 (Result/None/int) 翻译成可读输出 + exit code。
+
+    - 返回 Result: 按 ok/code 翻译
+    - 返回 int:    直接当 exit code
+    - 返回 None:   视为成功 (exit 0)
+    - 抛异常:      捕获, 输出诊断 + traceback (失败不崩 → 但 main 层崩溃要可见)
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            ret = func(*args, **kwargs)
+        except SystemExit:
+            raise
+        except KeyboardInterrupt:
+            print("\n[中断] 用户取消")
+            sys.exit(130)
+        except Exception as e:
+            # 未捕获异常: 输出诊断 + 简短 traceback, 不静默吞
+            print("[ERROR] 未预期异常: {}".format(e))
+            print("       -> 这是 bug, 请反馈。traceback:")
+            traceback.print_exc()
+            sys.exit(1)
+        if isinstance(ret, Result):
+            return _emit(ret)
+        if isinstance(ret, int):
+            sys.exit(ret)
+        # None / 其他: 成功
+        return 0
+    return wrapper

package/templates/qoder/scripts/common/roles.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+"""
+roles.py - 角色章节过滤 (单一真源, 消除 kg.py↔kg_mcp_server.py 逐字重复)
+
+现状: ROLE_SECTIONS 字典 + _filter_by_role 函数在 kg.py(:645-672) 和
+kg_mcp_server.py(:249-276) 逐字重复。改一处忘改另一处 → CLI 和 MCP 行为分叉。
+
+本模块作为单一真源, kg.py 和 kg_mcp_server.py 都从这里 import。
+
+过滤规则: 按角色裁剪 context_pack 输出的章节 (## 1. / ## 2. / ## 2b. 等),
+让不同角色只看到与其职责相关的段落, 减少噪音。
+
+Usage:
+    from common.roles import filter_by_role, ROLE_SECTIONS
+    text = filter_by_role(context_pack_output, role='pm')
+"""
+
+import re
+
+__all__ = ["ROLE_SECTIONS", "filter_by_role"]
+
+# 各角色可见的 context_pack 章节号
+# (与 kg.py ROLE_SECTIONS / kg_mcp_server.py ROLE_SECTIONS 对齐, 此处为唯一真源)
+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 输出的章节。
+
+    Args:
+        text: context_pack 的多段输出 (## 1. xxx / ## 2. xxx ...)
+        role: 角色名 (pm/design/dev/test/admin), 未知角色不过滤
+
+    Returns:
+        过滤后的文本 (只保留该角色可见章节)
+    """
+    visible = ROLE_SECTIONS.get((role or '').lower())
+    if not visible:
+        return text  # 未知角色不过滤
+    # 按 "## 数字." 切段 (含 2b 这种带字母的)
+    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()

package/templates/qoder/scripts/common/task_utils.py

@@ -173,16 +173,28 @@ def modify_task_json(task_dir: Path, mutator, timeout: float = 15.0):
 
     lock_path = task_dir / ".task.lock"
     lock = FileLock(str(lock_path), timeout=timeout, stale_seconds=300)
-    try:
-        lock.acquire()
-    except LockTimeoutError as e:
-        print(f"Warning: task lock busy ({task_dir.name}): {e}", file=sys.stderr)
-        # 降级: 不阻塞, 直接写 (好过完全失败)
-        data = load_task_json(task_dir)
-        if data is None:
+
+    # 锁竞争超时: 退避重试一次。绝不降级为无锁写 —— modify_task_json 存在的意义
+    # 就是防并发 read-modify-write 丢更新, 两个并发方都超时降级 = 必然丢一个的更新。
+    acquired = False
+    for attempt in range(2):
+        try:
+            lock.acquire()
+            acquired = True
+            break
+        except LockTimeoutError as e:
+            if attempt == 0:
+                # 第一次超时: 短暂退避后重试 (锁持有方通常很快释放)
+                import time as _time
+                _time.sleep(0.5)
+                continue
+            # 重试仍超时: 明确失败, 不写 (宁可这次改不了, 也不丢更新)
+            print(f"ERROR: task lock busy after retry ({task_dir.name}): {e}", file=sys.stderr)
+            print(f"  另一个进程正在修改此任务, 请稍后重试。改动未生效 (未丢数据)。", file=sys.stderr)
             return False
-        mutator(data)
-        return write_task_json(task_dir, data)
+    if not acquired:
+        return False
+
     try:
         data = load_task_json(task_dir)
         if data is None:

package/templates/qoder/scripts/common/test_extract.py

@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+"""
+Test code extractor — E1: extract structured assertions from Test.java files.
+
+These are the "second layer" of the knowledge graph: structured business
+knowledge (Given-When-Then, assertion patterns, service dependencies) that
+production code extraction can never reach. 39+ Test.java files in fywl-ics
+contain real integration tests with @Autowired services and assertion logic.
+
+JOIN keys to other layers:
+  - injected service class → code-callgraph (who this test exercises)
+  - package path → ui-modules / prd-index (which business module)
+  - @Test method name → code-keyword (searchable)
+"""
+import os
+import re
+
+# @Test annotation (Junit 5)
+RE_TEST = re.compile(r'@Test\b', re.M)
+# @DisplayName("...")
+RE_DISPLAY = re.compile(r'@DisplayName\s*\(\s*["\']([^"\']+)["\']\s*\)')
+# method signature: void methodName() or public void methodName()
+RE_METHOD = re.compile(r'(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:void|\w+(?:<[^>]*>)?)\s+(\w+)\s*\([^)]*\)\s*(?:throws\s+[\w.,\s]+)?\s*\{', re.M)
+# @Autowired / @Resource field: @Autowired private SomeService svc;
+RE_INJECT = re.compile(r'@(?:Autowired|Resource)\s+(?:private\s+|protected\s+)?(\w+(?:<[^>]*>)?)\s+(\w+)\s*;', re.M)
+# @SpringBootTest, @RunWith, @ExtendWith — marks integration tests
+RE_INTEGRATION = re.compile(r'@(?:SpringBootTest|RunWith|ExtendWith|WebMvcTest|DataJpaTest)', re.M)
+# Assertions: assertThat(x).isEqualTo(y), Assertions.assertEquals(x,y), Assert.X
+RE_ASSERT = re.compile(r'(?:assertThat|Assertions?|Assert)\.(\w+)\s*\(', re.M)
+# package declaration
+RE_PACKAGE = re.compile(r'package\s+([\w.]+)\s*;', re.M)
+
+
+def extract_test_assertions(proj_path):
+    """Scan a project for *Test.java files and extract structured test info.
+
+    Returns a list of dicts:
+      {file, class, package, method, display_name, injected_deps[],
+       assertions[], is_integration, comment}
+    """
+    results = []
+    if not proj_path or not os.path.isdir(proj_path):
+        return results
+
+    for root, dirs, files in os.walk(proj_path):
+        dirs[:] = [d for d in dirs if d not in ('node_modules', '.git', 'dist', '__pycache__')]
+        for f in files:
+            if not f.endswith('Test.java'):
+                continue
+            fpath = os.path.join(root, f)
+            try:
+                content = open(fpath, encoding='utf-8', errors='ignore').read()
+            except Exception:
+                continue
+            if '@Test' not in content:
+                continue
+
+            # Class-level info
+            pkg_m = RE_PACKAGE.search(content)
+            package = pkg_m.group(1) if pkg_m else ''
+            is_integration = bool(RE_INTEGRATION.search(content))
+
+            # Injected dependencies (services/mappers under test)
+            injected = []
+            for im in RE_INJECT.finditer(content):
+                dep_type = im.group(1).split('<')[0]  # strip generics
+                injected.append({'type': dep_type, 'name': im.group(2)})
+
+            # Class name (from filename, strip .java)
+            class_name = f[:-5]
+
+            # Extract each @Test method
+            test_positions = [m.start() for m in RE_TEST.finditer(content)]
+            display_map = {}
+            for dm in RE_DISPLAY.finditer(content):
+                # Associate @DisplayName with the nearest @Test after it
+                display_map[dm.end()] = dm.group(1)
+
+            for tp in test_positions:
+                # Find display name (nearest before this @Test, within 100 chars)
+                display = ''
+                for pos, name in display_map.items():
+                    if pos <= tp and tp - pos < 200:
+                        display = name
+
+                # Find method name after @Test
+                search_region = content[tp:tp + 300]
+                method_m = RE_METHOD.search(search_region)
+                if not method_m:
+                    continue
+                method_name = method_m.group(1)
+
+                # Extract method body for assertions
+                body_start = tp + method_m.end()
+                body = content[body_start:body_start + 600]
+                assertions = list(set(m.group(1) for m in RE_ASSERT.finditer(body)))
+
+                # Extract comment before @Test (/** ... */ or // ...)
+                before = content[max(0, tp - 200):tp]
+                comment_m = re.search(r'(?:/\*\*\s*\n\s*\*\s*([^*]+?)\s*\n)|(?://\s*(.+)$)', before, re.M)
+                comment = (comment_m.group(1) or comment_m.group(2)).strip() if comment_m else ''
+
+                results.append({
+                    'file': fpath.replace('\\', '/'),
+                    'class': class_name,
+                    'package': package,
+                    'method': method_name,
+                    'display_name': display,
+                    'comment': comment[:80],
+                    'injected_deps': [d['type'] for d in injected[:5]],
+                    'assertions': assertions[:5],
+                    'is_integration': is_integration,
+                })
+
+    return results

package/templates/qoder/scripts/kg/__init__.py

@@ -0,0 +1,11 @@
+# 子包初始化: 注入 scripts/根 + 所有子包到 sys.path
+# 让跨包 import (旧式不带前缀) 仍可用, 兼容现有代码
+import os as _os, sys as _sys
+_root = _os.path.dirname(_os.path.dirname(_os.path.abspath(__file__)))
+if _root not in _sys.path:
+    _sys.path.insert(0, _root)
+# 注入所有子包目录 (兼容旧式 import xxx)
+for _sub in ('kg', 'build', 'test', 'setup', 'io'):
+    _subdir = _os.path.join(_root, _sub)
+    if _os.path.isdir(_subdir) and _subdir not in _sys.path:
+        _sys.path.insert(0, _subdir)

package/templates/qoder/scripts/kg/build_entity_registry.py

@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""build_entity_registry.py — 从 ui-modules + code-api 构建 entity-registry.json。
+
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+产出 data/index/_build_cache/entity-registry.json, 供 kg_duckdb 导入 entities/aliases 表,
+让 kg.py feature <功能名> 能返回功能画像。
+
+结构 (与 kg_duckdb.bulk_import_from_json 契约对齐):
+  {
+    "entities": {
+      "F:<dir>": {"type":"FEATURE","canonical":"<dir>","cn":"<中文名>","aliases":[...],"properties":{...}},
+      "E:<endpoint>": {"type":"ENDPOINT","canonical":"<endpoint>","cn":"","aliases":[],"properties":{}},
+      "C:<controller>": {"type":"CONTROLLER",...}
+    },
+    "feature_adjacency": {"F:<dir>": {"endpoints": ["E:<ep>", ...]}}
+  }
+
+数据源:
+  - ui-modules.json 的 modules (每个 module → FEATURE entity, cn=中文名)
+  - code-api.json 的 endpoints (每个 → ENDPOINT entity)
+  - trace-chain.json 的 traces (推导 FEATURE → ENDPOINT 邻接)
+
+注意: 这是基础实现 (从模块结构推导)。更丰富的语义 (controller/test 关联、
+业务流程) 由 build_relations.py/build_features.py/build_workflows.py 补充,
+那些脚本未实现时不影响本脚本的 entity 基础层。
+"""
+import json
+import os
+import sys
+from datetime import datetime
+
+# 路径自适应 (和兄弟脚本一致)
+THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(THIS_DIR, '..'))
+from common.paths import DATA_INDEX_DIR, BUILD_CACHE_DIR
+
+
+def load(name):
+    """从 _build_cache 读索引 JSON (build_style_index 的产物位置)。"""
+    for d in (str(BUILD_CACHE_DIR), str(DATA_INDEX_DIR)):
+        p = os.path.join(d, name)
+        if os.path.isfile(p):
+            try:
+                return json.load(open(p, encoding='utf-8'))
+            except (json.JSONDecodeError, OSError):
+                pass
+    return {}
+
+
+def build():
+    entities = {}
+    aliases_rows = []  # (alias_lower, entity_id)
+    feature_adjacency = {}
+
+    # 1. FEATURE entities (from ui-modules.json)
+    mi = load('ui-modules.json')
+    feat_count = 0
+    for proj, mods in mi.get('projects', {}).items():
+        for m in mods:
+            if not isinstance(m, dict):
+                continue
+            mdir = m.get('dir', '').strip()
+            if not mdir:
+                continue
+            eid = 'F:%s' % mdir
+            cn = m.get('cn', '').strip()
+            # cn 为空或与 dir 相同时不算有中文名
+            if not cn or cn == mdir:
+                cn = ''
+            entities[eid] = {
+                'type': 'FEATURE',
+                'canonical': mdir,
+                'cn': cn,
+                'aliases': [mdir, mdir.lower()],
+                'properties': {'project': proj, 'path': m.get('path', '')},
+            }
+            for a in entities[eid]['aliases']:
+                aliases_rows.append((a.lower(), eid))
+            feature_adjacency[eid] = {'endpoints': [], 'buttons': []}
+            feat_count += 1
+
+    # 2. ENDPOINT entities (from code-api.json + trace-chain.json 补充)
+    # trace 的 endpoint 比 code-api 多且粒度不同, 两者都收录, 避免邻接匹配落空。
+    api = load('code-api.json')
+    tc = load('trace-chain.json')
+    ep_count = 0
+    for ep, ctrl_file in api.items():
+        eid = 'E:%s' % ep
+        entities[eid] = {
+            'type': 'ENDPOINT',
+            'canonical': ep,
+            'cn': '',
+            'aliases': [ep],
+            'properties': {'controller_file': ctrl_file},
+        }
+        aliases_rows.append((ep.lower(), eid))
+        ep_count += 1
+    # 补充 trace 里独有的 endpoint
+    for t in tc.get('traces', []):
+        ep = t.get('endpoint', '')
+        if not ep:
+            continue
+        eid = 'E:%s' % ep
+        if eid not in entities:
+            entities[eid] = {
+                'type': 'ENDPOINT',
+                'canonical': ep,
+                'cn': '',
+                'aliases': [ep],
+                'properties': {'source': 'trace', 'verb': t.get('verb', '')},
+            }
+            aliases_rows.append((ep.lower(), eid))
+            ep_count += 1
+
+    # 3. FEATURE -> ENDPOINT 邻接 (from trace-chain.json, tc 已在 step 2 加载)
+    # trace 里 button 的 vue_file 路径含 module dir, 可反推它属于哪个 FEATURE。
+    feat_canonicals = [(fid, ent['canonical']) for fid, ent in entities.items()
+                       if ent['type'] == 'FEATURE' and ent.get('canonical')]
+    trace_matched = 0
+    for t in tc.get('traces', []):
+        vue = (t.get('vue_file') or '').replace('\\', '/')
+        endpoint = t.get('endpoint', '')
+        if not vue or not endpoint:
+            continue
+        # 从 vue 路径找匹配的 module dir (最长匹配优先, 避免 cost 误匹配 costDetail)
+        matched_feat = None
+        best_len = 0
+        for fid, d in feat_canonicals:
+            if ('/%s/' % d) in vue or vue.endswith('/%s' % d) or ('/%s.' % d) in vue:
+                if len(d) > best_len:  # 最长匹配
+                    matched_feat = fid
+                    best_len = len(d)
+        if matched_feat:
+            trace_matched += 1
+            adj = feature_adjacency.setdefault(matched_feat, {})
+            adj.setdefault('endpoints', [])
+            adj.setdefault('buttons', [])
+            ep_eid = 'E:%s' % endpoint
+            if ep_eid in entities and ep_eid not in adj['endpoints']:
+                adj['endpoints'].append(ep_eid)
+            # button 邻接: vue_short:handler 归属此 feature
+            vue_short = vue.split('/views/')[-1] if '/views/' in vue else vue
+            handler = t.get('handler', '')
+            btn_eid = 'B:%s:%s' % (vue_short, handler)
+            if btn_eid not in adj['buttons']:
+                adj['buttons'].append(btn_eid)
+
+    # 4. 去重 aliases
+    seen_alias = set()
+    unique_aliases = []
+    for a, eid in aliases_rows:
+        key = (a, eid)
+        if key not in seen_alias:
+            seen_alias.add(key)
+            unique_aliases.append({'alias': a, 'entity_id': eid})
+
+    registry = {
+        'version': '1.0',
+        'updated': datetime.now().isoformat(),
+        'entities': entities,
+        'aliases': unique_aliases,
+        'feature_adjacency': feature_adjacency,
+        'stats': {
+            'features': feat_count,
+            'endpoints': ep_count,
+            'total_entities': len(entities),
+            'features_with_cn': sum(1 for e in entities.values()
+                                    if e['type'] == 'FEATURE' and e.get('cn')),
+            'trace_matched': trace_matched,
+            'features_with_endpoints': sum(1 for v in feature_adjacency.values() if v.get('endpoints')),
+        },
+    }
+    return registry
+
+
+def main():
+    print('Building entity registry...')
+    registry = build()
+    out = os.path.join(str(BUILD_CACHE_DIR), 'entity-registry.json')
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, 'w', encoding='utf-8') as f:
+        json.dump(registry, f, ensure_ascii=False, indent=2, sort_keys=True)
+    s = registry['stats']
+    print('  FEATURE entities: %d (%d 有中文名)' % (s['features'], s['features_with_cn']))
+    print('  ENDPOINT entities: %d' % s['endpoints'])
+    print('  aliases: %d' % len(registry['aliases']))
+    print('  Saved to: %s' % out)
+
+
+if __name__ == '__main__':
+    main()