@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/domain/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/domain/kg/build/build_entity_registry.py

@@ -0,0 +1,201 @@
+# -*- 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
+_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()
+
+产出 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 foundation.core.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()

package/templates/qoder/scripts/domain/kg/build/build_relations.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""build_relations.py — 从 trace-chain + code-api 推导关系边, 生成 relations.json。
+
+# 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()
+
+产出 data/index/_build_cache/relations.json, 供 kg_duckdb 导入 edges 表,
+让 kg.py feature 的端点/按钮数据非零, kg.py hop 多跳遍历有边可走。
+
+结构 (与 kg_duckdb.bulk_import_from_json 的 edges_data 契约对齐):
+  {
+    "edges": {
+      "click_to_api": [
+        {"vue_file":..., "button":..., "handler":..., "endpoint":..., "confidence":...}
+      ],
+      "api_to_controller": {"<endpoint>": "<controller_file>"},
+      "controller_to_tests": {"<controller>": [{"test":..., "dep":..., "assertions":[...]}]}
+    }
+  }
+
+数据源:
+  - trace-chain.json: traces (vue_file→button→handler→api_fn→endpoint→verb→confidence)
+                      api_functions (fnName→{url,verb,file})
+  - code-api.json: {endpoint: controller_file} (api_to_controller 直接用)
+  - test-assertions.json: tests (controller_to_tests 推导)
+"""
+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 foundation.core.paths import DATA_INDEX_DIR, BUILD_CACHE_DIR
+
+
+def load(name):
+    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():
+    tc = load('trace-chain.json')
+    api = load('code-api.json')
+
+    # 1. click_to_api: 直接从 traces 转 (字段名对齐 kg_duckdb 期望)
+    click_to_api = []
+    for t in tc.get('traces', []):
+        if not t.get('endpoint'):
+            continue
+        click_to_api.append({
+            'vue_file': t.get('vue_file', ''),
+            'button': t.get('button', ''),
+            'handler': t.get('handler', ''),
+            'api_fn': t.get('api_fn', ''),
+            'endpoint': t.get('endpoint', ''),
+            'verb': t.get('verb', ''),
+            'confidence': t.get('confidence', ''),
+        })
+
+    # 2. api_to_controller: code-api.json 已经是 {endpoint: controller_file}
+    # 过滤掉空值
+    api_to_controller = {ep: f for ep, f in api.items() if ep and f}
+
+    # 3. controller_to_tests: 从 test-assertions.json 推导
+    # test 有 package/class 信息, controller 名从 controller_file 提取, 反向匹配 test
+    ta = load('test-assertions.json')
+    controller_to_tests = {}
+    # 建 controller 名 → test 的映射 (test 的 package 含 controller 关键字则关联)
+    ctrl_names = set()
+    for ctrl_file in api_to_controller.values():
+        cname = ctrl_file.split('/')[-1].replace('.java', '')
+        if cname:
+            ctrl_names.add(cname)
+    for t in ta.get('tests', []):
+        test_loc = (t.get('package', '') + '.' + t.get('class', '')).lower()
+        for cname in ctrl_names:
+            if cname.lower() in test_loc:
+                controller_to_tests.setdefault(cname, []).append({
+                    'test': t.get('display_name') or (t.get('class', '') + '.' + t.get('method', '')),
+                    'dep': '',
+                    'assertions': t.get('assertions', []),
+                })
+                break  # 一个 test 只关联一个 controller
+
+    relations = {
+        'version': '1.0',
+        'updated': datetime.now().isoformat(),
+        'edges': {
+            'click_to_api': click_to_api,
+            'api_to_controller': api_to_controller,
+            'controller_to_tests': controller_to_tests,
+        },
+        'stats': {
+            'click_edges': len(click_to_api),
+            'api_to_ctrl': len(api_to_controller),
+            'ctrl_to_test': len(controller_to_tests),
+        },
+    }
+    return relations
+
+
+def main():
+    print('Building relations...')
+    rel = build()
+    out = os.path.join(str(BUILD_CACHE_DIR), 'relations.json')
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, 'w', encoding='utf-8') as f:
+        json.dump(rel, f, ensure_ascii=False, indent=2, sort_keys=True)
+    s = rel['stats']
+    print('  click_to_api edges: %d' % s['click_edges'])
+    print('  api_to_controller: %d' % s['api_to_ctrl'])
+    print('  controller_to_tests: %d' % s['ctrl_to_test'])
+    print('  Saved to: %s' % out)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -1,5 +1,17 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 # -*- 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
+
 """
 Build style index from Vue/HTML files.
 Extracts UI patterns: tables, forms, layouts, colors, components.
@@ -8,7 +20,7 @@ Usage:
   python build_style_index.py
 """
 import os, json, re, sys
-from common.paths import BUILD_CACHE_DIR
+from foundation.core.paths import BUILD_CACHE_DIR
 from datetime import datetime
 
 # UTF-8 stdio (防御性: stdout 被捕获时不崩溃)
@@ -20,7 +32,7 @@ except (AttributeError, TypeError, OSError, IOError):
     except Exception:
         pass
 
-BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+BASE = get_repo_root()
 DATA_CODE = os.path.join(BASE, 'data', 'code')
 INDEX_DIR = os.path.join(BASE, 'data', 'index')
 STYLE_INDEX_PATH = os.path.join(BUILD_CACHE_DIR, 'ui-style.json')
@@ -33,13 +45,20 @@ TEST_ASSERTIONS_PATH = os.path.join(BUILD_CACHE_DIR, 'test-assertions.json')
 # E2: prefer tree-sitter extraction (31%->70%+ coverage); fallback to regex
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 try:
-    from common.ts_extract import ts_build_api_fn_table as build_api_fn_table
-    from common.ts_extract import ts_trace_clicks as trace_clicks
+    from domain.kg.extract.ts_extract import ts_build_api_fn_table as build_api_fn_table
+    from domain.kg.extract.ts_extract import ts_trace_clicks as trace_clicks
     _EXTRACT_ENGINE = 'tree-sitter'
 except Exception:
-    from common.extract import build_api_fn_table, trace_clicks
+    from domain.kg.extract.extract import build_api_fn_table, trace_clicks
     _EXTRACT_ENGINE = 'regex (tree-sitter not installed)'
-from common.test_extract import extract_test_assertions  # noqa: E402
+# test_extract 是可选增强层 (test-assertions 索引), 模块可能未提供。
+# 用 lazy import + 降级: 没有就跳过 test-assertions, 不阻断 ui-style 主线构建。
+try:
+    from domain.kg.extract.test_extract import extract_test_assertions  # noqa: E402
+    _HAS_TEST_EXTRACT = True
+except ImportError:
+    extract_test_assertions = None
+    _HAS_TEST_EXTRACT = False
 
 
 def extract_vue_patterns(filepath, content):
@@ -377,7 +396,12 @@ def scan_project(proj_name, proj_path):
 
         for f in files:
             filepath = os.path.join(root, f)
-            rel_path = os.path.relpath(filepath, proj_path).replace('\\', '/')
+            # relpath 在 Windows 上对特殊路径 (\\.\nul 等设备/跨盘符) 会抛 ValueError。
+            # 这些根本不是源码, 跳过即可, 不让一个异常文件炸掉整个扫描。
+            try:
+                rel_path = os.path.relpath(filepath, proj_path).replace('\\', '/')
+            except ValueError:
+                continue
 
             if f.endswith('.vue'):
                 vue_count += 1
@@ -415,7 +439,7 @@ def scan_project(proj_name, proj_path):
                         comp_m = re.findall(r"component:\s*['\"]([^'\"]+)['\"]", content)
                         for comp in comp_m:
                             form_components[comp] = form_components.get(comp, 0) + 1
-                except:
+                except Exception:
                     pass
 
     return {
@@ -662,13 +686,20 @@ def main():
 
     # test-assertions.json — E1: 测试代码提取 (Given-When-Then + 断言 + 注入依赖)
     # 第二层知识: 生产代码提取不到的业务预期和断言标准, 补上'怎么算对'天花板
-    print('Building test assertions index...')
+    # 依赖 common.test_extract (可选模块); 缺失则跳过, 不阻断 ui-style 等主线。
     all_tests = []
-    for proj in sorted(os.listdir(DATA_CODE)):
-        proj_path = os.path.join(DATA_CODE, proj)
-        if os.path.isdir(proj_path):
-            tests = extract_test_assertions(proj_path)
-            all_tests.extend(tests)
+    if not _HAS_TEST_EXTRACT:
+        print('Skipping test assertions index (common.test_extract not available - optional)')
+    else:
+        print('Building test assertions index...')
+        for proj in sorted(os.listdir(DATA_CODE)):
+            proj_path = os.path.join(DATA_CODE, proj)
+            if os.path.isdir(proj_path):
+                try:
+                    tests = extract_test_assertions(proj_path)
+                    all_tests.extend(tests)
+                except Exception as e:
+                    print('  WARN: test_extract failed for {}: {}'.format(proj, str(e)[:80]))
     test_index = {
         'version': '1.0', 'updated': datetime.now().isoformat(),
         'tests': all_tests,
@@ -679,6 +710,8 @@ def main():
         json.dump(test_index, f, ensure_ascii=False, indent=2, sort_keys=True)
 
     # ── 知识图谱层: relations + features + entity-registry + DuckDB ──
+    # build_entity_registry 已实现 (FEATURE/ENDPOINT entity 基础层)。
+    # build_relations/features/workflows 是增强层, 未实现时 entities 表仍有基础数据。
     print('Building knowledge graph layers...')
     import subprocess
     for script in ['build_relations.py', 'build_features.py',
@@ -690,6 +723,8 @@ def main():
                 print('  %s OK' % script)
             except Exception as e:
                 print('  %s SKIP: %s' % (script, str(e)[:60]))
+        elif script != 'kg_duckdb.py':
+            print('  %s N/A (语义层脚本未实现, entities/workflows 表将空)' % script)
 
     print()
     print('=== Done ===')

package/templates/qoder/scripts/domain/kg/build/build_workflows.py

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+"""build_workflows.py — 从 traces + endpoints 推导业务流程链, 生成 workflow-index.json。
+
+# 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()
+
+产出 data/index/_build_cache/workflow-index.json, 供 kg_duckdb 导入 workflows 表,
+让 kg.py workflow <模块> 能返回该模块的状态流转链 (query→create→audit→...)。
+
+workflows 表结构: module, state, seq, button, endpoint
+
+推导逻辑 (基于 verb + 路径关键词的启发式状态推断):
+  - GET/read/list/page/export → "query" (查询)
+  - POST/add/create/save/submit/apply → "create" (新增/提交)
+  - PUT/update/edit/audit/approve/reject → "audit" (审核/修改)
+  - DELETE/remove/cancel/delete/del → "cancel" (取消/删除)
+
+数据源: trace-chain.json (vue_file→button→endpoint→verb) + entity-registry.json
+(module→endpoint 邻接, 用于把 endpoint 归到 module)。
+"""
+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 foundation.core.paths import DATA_INDEX_DIR, BUILD_CACHE_DIR
+
+
+def load(name):
+    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 {}
+
+
+# 状态推断规则 (按优先级, 先匹配先用)
+STATE_RULES = [
+    ('query', ['get', 'read', 'list', 'page', 'export', 'detail', 'info', 'count']),
+    ('create', ['post', 'add', 'create', 'save', 'submit', 'apply', 'import', 'write']),
+    ('audit', ['put', 'update', 'edit', 'audit', 'approve', 'reject', 'review', 'confirm', 'send']),
+    ('cancel', ['delete', 'remove', 'cancel', 'del', 'revoke', 'close']),
+]
+# 状态排序 (业务流程顺序)
+STATE_ORDER = {'query': 1, 'create': 2, 'audit': 3, 'cancel': 4}
+
+
+def infer_state(verb, endpoint):
+    """从 HTTP verb + endpoint 路径推断业务状态。"""
+    key = ((verb or '') + ' ' + (endpoint or '')).lower()
+    for state, patterns in STATE_RULES:
+        for p in patterns:
+            if p in key:
+                return state
+    return 'other'
+
+
+def build():
+    er = load('entity-registry.json')
+    tc = load('trace-chain.json')
+
+    # module → [(state, button, endpoint)] 从 feature_adjacency + traces 推导
+    # feature_adjacency 已有 endpoints + buttons, 配合 trace 的 verb 推断 state
+    fa = er.get('feature_adjacency', {})
+    entities = er.get('entities', {})
+
+    # 建 endpoint → (verb, button) 映射 (从 traces)
+    ep_info = {}  # endpoint -> {verb, buttons:set}
+    for t in tc.get('traces', []):
+        ep = t.get('endpoint', '')
+        if not ep:
+            continue
+        info = ep_info.setdefault(ep, {'verb': '', 'buttons': set()})
+        if t.get('verb') and not info['verb']:
+            info['verb'] = t.get('verb', '')
+        if t.get('button'):
+            info['buttons'].add(t.get('button'))
+
+    # 按 kg_duckdb.import_workflow_layer 期望的结构组装:
+    # {module: {chain: [{state, operations: [{button, endpoint}]}]}}
+    workflows = {}
+    module_states = {}
+    total_steps = 0
+    for feat_eid, adj in fa.items():
+        if not isinstance(adj, dict):
+            continue
+        ent = entities.get(feat_eid, {})
+        module = ent.get('canonical', feat_eid.replace('F:', ''))
+        eps = adj.get('endpoints', [])
+        if not eps:
+            continue
+        # 按 state 分组端点
+        state_ops = {}  # state -> [{button, endpoint}]
+        for ep_eid in eps:
+            ep = ep_eid.replace('E:', '', 1)
+            info = ep_info.get(ep, {'verb': '', 'buttons': set()})
+            state = infer_state(info['verb'], ep)
+            btn = next(iter(info['buttons']), '') if info['buttons'] else ''
+            state_ops.setdefault(state, []).append({'button': btn, 'endpoint': ep})
+        # 按 STATE_ORDER 排序成 chain
+        chain = []
+        for state in sorted(state_ops.keys(), key=lambda s: STATE_ORDER.get(s, 5)):
+            chain.append({'state': state, 'operations': state_ops[state]})
+            total_steps += len(state_ops[state])
+        if chain:
+            workflows[module] = {'chain': chain}
+            module_states[module] = len(state_ops)
+
+    result = {
+        'version': '1.0',
+        'updated': datetime.now().isoformat(),
+        'workflows': workflows,
+        'stats': {
+            'modules': len(module_states),
+            'flow_steps': total_steps,
+            'modules_with_multi_state': sum(1 for n in module_states.values() if n > 1),
+        },
+    }
+    return result
+
+
+def main():
+    print('Building workflows...')
+    wf = build()
+    out = os.path.join(str(BUILD_CACHE_DIR), 'workflow-index.json')
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, 'w', encoding='utf-8') as f:
+        json.dump(wf, f, ensure_ascii=False, indent=2, sort_keys=True)
+    s = wf['stats']
+    print('  modules: %d (%d 有多状态流转)' % (s['modules'], s['modules_with_multi_state']))
+    print('  flow steps: %d' % s['flow_steps'])
+    print('  Saved to: %s' % out)
+
+
+if __name__ == '__main__':
+    main()