@hupan56/wlkj 2.7.11 → 3.0.0

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

@@ -1,393 +1,420 @@
-# -*- coding: utf-8 -*-
-"""
-Incremental UPSERT builder for the DuckDB knowledge graph.
-
-Instead of full rebuild (build_style_index.py → kg_duckdb.py bulk_import),
-this takes a list of changed files (from git diff) and only updates the
-entities + edges that belong to those files.
-
-Performance: ~0.2s per file vs 60s full rebuild.
-For 500 changed files: ~2 minutes incremental vs 5+ minutes full rebuild.
-
-Usage:
-  python kg_incremental.py                  # auto-detect changes via git diff
-  python kg_incremental.py file1.vue file2.ts  # explicit file list
-"""
-import json
-import os
-import re
-import sys
-
-SCRIPTS = os.path.join(os.path.dirname(os.path.abspath(__file__)))
-sys.path.insert(0, SCRIPTS)
-
-from common.paths import DATA_INDEX_DIR, PROJECT_ROOT
-from kg_duckdb import get_db, init_schema, upsert_entity, upsert_alias, upsert_edge, delete_edges_from
-from common.ts_extract import ts_build_api_fn_table, ts_trace_clicks
-from common.extract import build_api_fn_table
-from common.test_extract import extract_test_assertions
-
-CODE_DIR = str(PROJECT_ROOT / 'data' / 'code')
-INDEX_DIR = str(DATA_INDEX_DIR)
-
-
-def get_changed_files():
-    """Auto-detect ALL changed files since last kg_build via stored commit hash.
-
-    Records the last-built commit per project in build_meta table.
-    Next run diffs from that commit to HEAD, capturing ALL changes (not just last 2 commits).
-    """
-    changed = []
-    if not os.path.isdir(CODE_DIR):
-        return changed
-    import subprocess
-
-    # Read last-built commits from DuckDB build_meta
-    last_commits = {}
-    try:
-        con = get_db()
-        rows = con.execute("SELECT key, value FROM build_meta WHERE key LIKE 'last_commit_%'").fetchall()
-        con.close()
-        for k, v in rows:
-            last_commits[k.replace('last_commit_', '')] = v
-    except Exception:
-        pass
-
-    current_commits = {}
-    for proj in os.listdir(CODE_DIR):
-        proj_path = os.path.join(CODE_DIR, proj)
-        if not os.path.isdir(os.path.join(proj_path, '.git')):
-            continue
-        try:
-            # Get current HEAD
-            r = subprocess.run(['git', 'rev-parse', 'HEAD'],
-                               cwd=proj_path, capture_output=True, text=True, encoding='utf-8')
-            if r.returncode != 0:
-                continue
-            current_head = r.stdout.strip()
-            current_commits[proj] = current_head
-
-            # Determine diff range: from last-built commit to HEAD
-            last_built = last_commits.get(proj)
-            if last_built and last_built != current_head:
-                # Diff from last build to now — captures ALL changes since last build
-                diff_args = ['git', 'diff', '--name-only', last_built, current_head]
-            elif not last_built:
-                # First run — get last 7 days of changes (or all if repo is new)
-                r3 = subprocess.run(['git', 'log', '--since=7 days ago', '--oneline'],
-                                    cwd=proj_path, capture_output=True, text=True, encoding='utf-8')
-                log_lines = [l for l in r3.stdout.strip().split('\n') if l.strip()]
-                if len(log_lines) >= 2:
-                    old_commit = log_lines[-1].split()[0]
-                    diff_args = ['git', 'diff', '--name-only', old_commit, current_head]
-                else:
-                    continue  # No changes or single commit
-            else:
-                continue  # Already up to date, no diff needed
-
-            r2 = subprocess.run(diff_args,
-                                cwd=proj_path, capture_output=True, text=True, encoding='utf-8')
-            for f in r2.stdout.strip().split('\n'):
-                f = f.strip()
-                if f:
-                    changed.append(os.path.join(proj_path, f.replace('/', os.sep)))
-        except Exception:
-            pass
-
-    # Save current commits as last-built
-    try:
-        con = get_db()
-        for proj, commit in current_commits.items():
-            con.execute(
-                "INSERT OR REPLACE INTO build_meta VALUES (?, ?)",
-                ['last_commit_%s' % proj, commit]
-            )
-        con.close()
-    except Exception:
-        pass
-
-    return changed
-
-
-def incremental_update(changed_files):
-    """Update DuckDB incrementally for a list of changed files.
-
-    For each file:
-      - .vue: re-extract trace_clicks, UPSERT button entities + click edges
-      - .ts (api): re-extract api functions, UPSERT endpoint entities
-      - .java (test): re-extract test assertions, UPSERT test entities
-    """
-    con = get_db()
-    init_schema(con)
-
-    stats = {'vue': 0, 'ts': 0, 'java_test': 0, 'edges_updated': 0, 'entities_upserted': 0}
-
-    # 判断是否有 api 文件变更 — 决定是否需要重建 api_table
-    has_api_changes = any(
-        f.replace('\\', '/').endswith('.ts') and '/api/' in f.replace('\\', '/')
-        for f in changed_files if os.path.isfile(f)
-    )
-
-    api_dir = _find_api_dir()
-
-    if has_api_changes:
-        # api 文件变了 — 必须重建完整 api_table
-        api_table = ts_build_api_fn_table(api_dir) if api_dir else {}
-        # 缓存到文件, 供下次增量复用
-        if api_table and api_dir:
-            _save_api_cache(api_table, api_dir)
-    else:
-        # api 文件没变 — 从缓存加载 (毫秒级, 不扫文件系统)
-        api_table = _load_api_cache(api_dir)
-        if not api_table:
-            # 缓存不存在 (首次运行) — 重建并缓存
-            api_table = ts_build_api_fn_table(api_dir) if api_dir else {}
-            if api_table and api_dir:
-                _save_api_cache(api_table, api_dir)
-
-    for filepath in changed_files:
-        if not os.path.isfile(filepath):
-            # File was deleted — clean up its entities
-            _cleanup_deleted_file(con, filepath)
-            continue
-
-        rel_path = filepath.replace('\\', '/')
-
-        if filepath.endswith('.vue'):
-            stats['vue'] += 1
-            _update_vue_file(con, filepath, api_table, stats)
-
-        elif filepath.endswith('.ts') and '/api/' in rel_path:
-            stats['ts'] += 1
-            _update_api_file(con, filepath, stats)
-
-        elif filepath.endswith('Test.java'):
-            stats['java_test'] += 1
-            _update_test_file(con, filepath, stats)
-
-    # After file updates, refresh PRD + Wiki from git_sync's JSON output
-    _refresh_prds_and_wiki(con, stats)
-
-    con.close()
-    return stats
-
-
-def _refresh_prds_and_wiki(con, stats):
-    """Import PRD index + Wiki from git_sync's JSON output into DuckDB.
-
-    git_sync.py writes these as JSON; kg_incremental reads them and UPSERTs
-    into DuckDB so MCP tools can query them.
-    """
-    INDEX = str(DATA_INDEX_DIR)
-    import json as _json
-
-    # PRD
-    prd_path = os.path.join(INDEX, '_build_cache', 'prd-index.json')
-    if not os.path.isfile(prd_path):
-        prd_path = os.path.join(INDEX, 'prd-index.json')
-    if os.path.isfile(prd_path):
-        try:
-            prds = _json.load(open(prd_path, encoding='utf-8'))
-            con.execute("DELETE FROM prds")
-            rows = [(f, info.get('title', ''),
-                     _json.dumps(info.get('keywords', []), ensure_ascii=False),
-                     _json.dumps(info.get('features', []), ensure_ascii=False),
-                     _json.dumps(info.get('cn_terms', []), ensure_ascii=False))
-                    for f, info in prds.items()]
-            if rows:
-                _batch_insert(con, 'prds', rows, ignore=True)
-                stats['prds_refreshed'] = len(rows)
-        except Exception:
-            pass
-
-    # Wiki
-    wiki_path = os.path.join(INDEX, 'wiki-index.json')
-    if os.path.isfile(wiki_path):
-        try:
-            wiki = _json.load(open(wiki_path, encoding='utf-8'))
-            con.execute("DELETE FROM wiki")
-            wiki_rows = []
-            for kw, entries in (wiki.get('index', {}) if isinstance(wiki, dict) else {}).items():
-                for e in (entries if isinstance(entries, list) else []):
-                    wiki_rows.append((kw, e.get('project', ''), e.get('title', ''),
-                                      e.get('md_path', ''), e.get('description', '')))
-            if wiki_rows:
-                _batch_insert(con, 'wiki', wiki_rows)
-                stats['wiki_refreshed'] = len(wiki_rows)
-        except Exception:
-            pass
-
-
-def _find_api_dir():
-    """Find the fywl-ui api directory."""
-    apps = os.path.join(CODE_DIR, 'fywl-ui', 'apps')
-    if os.path.isdir(apps):
-        for app in os.listdir(apps):
-            candidate = os.path.join(apps, app, 'src', 'api')
-            if os.path.isdir(candidate):
-                return candidate
-    return None
-
-
-def _load_api_table_from_duckdb(con):
-    """从 DuckDB 加载 api_table (api 函数名→端点), 避免重建。"""
-    table = {}
-    try:
-        rows = con.execute("SELECT id, props FROM entities WHERE type = 'ENDPOINT'").fetchall()
-        for eid, props_json in rows:
-            url = eid.replace('E:', '')
-            props = json.loads(props_json) if props_json else {}
-            fn_name = props.get('api_fn', '')
-            if fn_name:
-                table[fn_name] = {'url': url, 'verb': props.get('verb', '?'),
-                                  'file': props.get('source_file', '')}
-    except Exception:
-        pass
-    return table
-
-
-_API_CACHE_PATH = os.path.join(INDEX_DIR, '.api-table-cache.json')
-
-
-def _save_api_cache(api_table, api_dir):
-    """保存 api_table 到缓存文件 (含 api_dir 的 mtime 作为失效依据)。"""
-    import time
-    cache = {
-        'api_dir_mtime': os.path.getmtime(api_dir) if os.path.isdir(api_dir) else 0,
-        'saved_at': time.time(),
-        'table': api_table,
-    }
-    with open(_API_CACHE_PATH, 'w', encoding='utf-8') as f:
-        json.dump(cache, f, ensure_ascii=False)
-
-
-def _load_api_cache(api_dir):
-    """从缓存文件加载 api_table。如果缓存不存在或过期返回 {}。"""
-    if not os.path.isfile(_API_CACHE_PATH):
-        return {}
-    try:
-        cache = json.load(open(_API_CACHE_PATH, encoding='utf-8'))
-        # 检查 api_dir 的 mtime 是否变了
-        current_mtime = os.path.getmtime(api_dir) if api_dir and os.path.isdir(api_dir) else 0
-        if cache.get('api_dir_mtime') == current_mtime:
-            return cache.get('table', {})
-    except Exception:
-        pass
-    return {}
-
-
-def _update_vue_file(con, filepath, api_table, stats):
-    """Re-extract traces from one Vue file and UPSERT its button entities + edges."""
-    try:
-        content = open(filepath, 'rb').read().decode('utf-8', errors='replace')
-    except Exception:
-        return
-    if '@click' not in content:
-        return
-
-    traces = ts_trace_clicks(filepath, content, api_table)
-    vue_norm = filepath.replace('\\', '/')
-    # Normalize vue_short — MUST match kg_build.py's format exactly
-    if '/views/' in vue_norm:
-        vue_short = vue_norm.split('/views/')[-1]
-    elif '/pages/' in vue_norm:
-        vue_short = vue_norm.split('/pages/')[-1]
-    else:
-        vue_short = os.path.basename(filepath)
-
-    for t in traces:
-        handler = t.get('handler', '')
-        eid = 'B:%s:%s' % (vue_short, handler)
-        # UPSERT entity (INSERT OR REPLACE, no duplicates)
-        upsert_entity(con, eid, 'BUTTON', handler, '',
-                      {'button_text': t.get('button', ''),
-                       'vue_file': vue_norm,
-                       'confidence': t.get('confidence', '')})
-        upsert_alias(con, handler.lower(), eid)
-        stats['entities_upserted'] += 1
-
-        # Delete ALL old edges from this button first, then insert fresh
-        delete_edges_from(con, eid)
-        ep = t.get('endpoint')
-        if ep and ep != 'None':
-            to_eid = 'E:%s' % ep
-            upsert_edge(con, eid, to_eid, 'clicks', props={
-                'button': t.get('button', ''),
-                'confidence': t.get('confidence', ''),
-            })
-            stats['edges_updated'] += 1
-
-
-def _update_api_file(con, filepath, stats):
-    """Re-extract API functions from one .ts file and UPSERT endpoint entities."""
-    # Re-use the bulk api_table extraction on this single file's directory
-    api_dir = os.path.dirname(filepath)
-    file_table = build_api_fn_table(api_dir)
-    for fn_name, info in file_table.items():
-        # Only update functions defined in THIS file
-        if info.get('file', '').replace('\\', '/') != filepath.replace('\\', '/'):
-            continue
-        eid = 'E:%s' % info['url']
-        upsert_entity(con, eid, 'ENDPOINT', info['url'], '',
-                      {'verb': info.get('verb', '?'),
-                       'api_fn': fn_name,
-                       'source_file': filepath.replace('\\', '/')})
-        upsert_alias(con, fn_name.lower(), eid)
-        stats['entities_upserted'] += 1
-
-
-def _update_test_file(con, filepath, stats):
-    """Re-extract test assertions from one Test.java and UPSERT test entities."""
-    tests = extract_test_assertions(os.path.dirname(filepath))
-    # Filter to only this file
-    file_norm = filepath.replace('\\', '/')
-    for t in tests:
-        if t.get('file', '').replace('\\', '/') != file_norm:
-            continue
-        name = '%s.%s' % (t['class'], t['method'])
-        eid = 'T:%s' % name
-        upsert_entity(con, eid, 'TEST', name, '',
-                      {'display': t.get('display_name', ''),
-                       'deps': t.get('injected_deps', []),
-                       'assertions': t.get('assertions', []),
-                       'package': t.get('package', '')})
-        upsert_alias(con, name.lower(), eid)
-        stats['entities_upserted'] += 1
-
-
-def _cleanup_deleted_file(con, filepath):
-    """Remove entities belonging to a deleted file."""
-    rel = filepath.replace('\\', '/')
-    # Delete buttons from this vue file
-    if '.vue' in rel:
-        vue_short = rel.split('/views/')[-1] if '/views/' in rel else os.path.basename(rel)
-        con.execute("DELETE FROM entities WHERE id LIKE 'B:%s:%%'" % vue_short.replace("'", "''"))
-        con.execute("DELETE FROM edges WHERE from_id LIKE 'B:%s:%%'" % vue_short.replace("'", "''"))
-
-
-if __name__ == '__main__':
-    if len(sys.argv) > 1:
-        changed = sys.argv[1:]
-    else:
-        print('Auto-detecting changes via git diff...')
-        changed = get_changed_files()
-
-    if not changed:
-        print('No changes detected.')
-        sys.exit(0)
-
-    # Filter to relevant file types
-    relevant = [f for f in changed if f.endswith(('.vue', '.ts', '.java'))]
-    print('Changed files: %d total, %d relevant' % (len(changed), len(relevant)))
-
-    if relevant:
-        import time
-        t0 = time.time()
-        stats = incremental_update(relevant)
-        elapsed = time.time() - t0
-        print('Incremental update done in %.1fs' % elapsed)
-        print('  Vue: %d, TS: %d, Java: %d' % (stats['vue'], stats['ts'], stats['java_test']))
-        print('  Entities UPSERTed: %d' % stats['entities_upserted'])
-        print('  Edges updated: %d' % stats['edges_updated'])
-    else:
-        print('No relevant files to update.')
+# -*- coding: utf-8 -*-
+# 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()
+
+"""
+Incremental UPSERT builder for the DuckDB knowledge graph.
+
+Instead of full rebuild (build_style_index.py → kg_duckdb.py bulk_import),
+this takes a list of changed files (from git diff) and only updates the
+entities + edges that belong to those files.
+
+Performance: ~0.2s per file vs 60s full rebuild.
+For 500 changed files: ~2 minutes incremental vs 5+ minutes full rebuild.
+
+Usage:
+  python kg_incremental.py                  # auto-detect changes via git diff
+  python kg_incremental.py file1.vue file2.ts  # explicit file list
+"""
+import json
+import os
+import re
+import sys
+
+SCRIPTS = os.path.join(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, SCRIPTS)
+
+from common.paths import DATA_INDEX_DIR, PROJECT_ROOT
+from kg_duckdb import get_db, init_schema, upsert_entity, upsert_alias, upsert_edge, delete_edges_from
+from common.ts_extract import ts_build_api_fn_table, ts_trace_clicks
+from common.extract import build_api_fn_table
+from common.test_extract import extract_test_assertions
+
+CODE_DIR = str(PROJECT_ROOT / 'data' / 'code')
+INDEX_DIR = str(DATA_INDEX_DIR)
+
+
+def _git(*args, cwd=None, timeout=None):
+    """git 命令包装(与 git_sync._git 一致)。网络操作必传 timeout; 本地操作可不传。
+
+    返回 rc=124 表示超时, rc=127 表示 git 未安装, 不让进程崩溃或挂死。
+    """
+    import subprocess
+    try:
+        kw = dict(cwd=cwd, capture_output=True, text=True, encoding='utf-8', errors='replace')
+        if timeout:
+            kw['timeout'] = timeout
+        return subprocess.run(['git'] + list(args), **kw)
+    except FileNotFoundError:
+        import types
+        return types.SimpleNamespace(returncode=127, stdout='', stderr='git not installed')
+    except subprocess.TimeoutExpired:
+        import types
+        return types.SimpleNamespace(returncode=124, stdout='', stderr='git {} timed out'.format(' '.join(args[:3])))
+
+
+def get_changed_files():
+    """Auto-detect ALL changed files since last kg_build via stored commit hash.
+
+    Records the last-built commit per project in build_meta table.
+    Next run diffs from that commit to HEAD, capturing ALL changes (not just last 2 commits).
+    """
+    changed = []
+    if not os.path.isdir(CODE_DIR):
+        return changed
+    import subprocess
+
+    # Read last-built commits from DuckDB build_meta
+    last_commits = {}
+    try:
+        con = get_db()
+        rows = con.execute("SELECT key, value FROM build_meta WHERE key LIKE 'last_commit_%'").fetchall()
+        con.close()
+        for k, v in rows:
+            last_commits[k.replace('last_commit_', '')] = v
+    except Exception:
+        pass
+
+    current_commits = {}
+    for proj in os.listdir(CODE_DIR):
+        proj_path = os.path.join(CODE_DIR, proj)
+        if not os.path.isdir(os.path.join(proj_path, '.git')):
+            continue
+        try:
+            # Get current HEAD (本地操作, 快速)
+            r = _git('rev-parse', 'HEAD', cwd=proj_path)
+            if r.returncode != 0:
+                continue
+            current_head = r.stdout.strip()
+            current_commits[proj] = current_head
+
+            # Determine diff range: from last-built commit to HEAD
+            last_built = last_commits.get(proj)
+            if last_built and last_built != current_head:
+                # Diff from last build to now — captures ALL changes since last build
+                diff_rev_range = ['diff', '--name-only', last_built, current_head]
+            elif not last_built:
+                # First run — get last 7 days of changes (or all if repo is new)
+                r3 = _git('log', '--since=7 days ago', '--oneline', cwd=proj_path)
+                log_lines = [l for l in r3.stdout.strip().split('\n') if l.strip()]
+                if len(log_lines) >= 2:
+                    old_commit = log_lines[-1].split()[0]
+                    diff_rev_range = ['diff', '--name-only', old_commit, current_head]
+                else:
+                    continue  # No changes or single commit
+            else:
+                continue  # Already up to date, no diff needed
+
+            r2 = _git(*diff_rev_range, cwd=proj_path)
+            # P2-11: 必须判 returncode。若 diff 失败 (如 last_built commit 被 git gc
+            # 掉、对象库损坏), r2.stdout 可能是错误信息, 把它当文件名加入 changed
+            # 会让后续 _cleanup_deleted_file 误删真实文件。
+            if r2.returncode != 0:
+                continue
+            for f in r2.stdout.strip().split('\n'):
+                f = f.strip()
+                if f:
+                    changed.append(os.path.join(proj_path, f.replace('/', os.sep)))
+        except Exception:
+            pass
+
+    # Save current commits as last-built
+    try:
+        con = get_db()
+        for proj, commit in current_commits.items():
+            con.execute(
+                "INSERT OR REPLACE INTO build_meta VALUES (?, ?)",
+                ['last_commit_%s' % proj, commit]
+            )
+        con.close()
+    except Exception:
+        pass
+
+    return changed
+
+
+def incremental_update(changed_files):
+    """Update DuckDB incrementally for a list of changed files.
+
+    For each file:
+      - .vue: re-extract trace_clicks, UPSERT button entities + click edges
+      - .ts (api): re-extract api functions, UPSERT endpoint entities
+      - .java (test): re-extract test assertions, UPSERT test entities
+    """
+    con = get_db()
+    init_schema(con)
+
+    stats = {'vue': 0, 'ts': 0, 'java_test': 0, 'edges_updated': 0, 'entities_upserted': 0}
+
+    # 判断是否有 api 文件变更 — 决定是否需要重建 api_table
+    has_api_changes = any(
+        f.replace('\\', '/').endswith('.ts') and '/api/' in f.replace('\\', '/')
+        for f in changed_files if os.path.isfile(f)
+    )
+
+    api_dir = _find_api_dir()
+
+    if has_api_changes:
+        # api 文件变了 — 必须重建完整 api_table
+        api_table = ts_build_api_fn_table(api_dir) if api_dir else {}
+        # 缓存到文件, 供下次增量复用
+        if api_table and api_dir:
+            _save_api_cache(api_table, api_dir)
+    else:
+        # api 文件没变 — 从缓存加载 (毫秒级, 不扫文件系统)
+        api_table = _load_api_cache(api_dir)
+        if not api_table:
+            # 缓存不存在 (首次运行) — 重建并缓存
+            api_table = ts_build_api_fn_table(api_dir) if api_dir else {}
+            if api_table and api_dir:
+                _save_api_cache(api_table, api_dir)
+
+    for filepath in changed_files:
+        if not os.path.isfile(filepath):
+            # File was deleted — clean up its entities
+            _cleanup_deleted_file(con, filepath)
+            continue
+
+        rel_path = filepath.replace('\\', '/')
+
+        if filepath.endswith('.vue'):
+            stats['vue'] += 1
+            _update_vue_file(con, filepath, api_table, stats)
+
+        elif filepath.endswith('.ts') and '/api/' in rel_path:
+            stats['ts'] += 1
+            _update_api_file(con, filepath, stats)
+
+        elif filepath.endswith('Test.java'):
+            stats['java_test'] += 1
+            _update_test_file(con, filepath, stats)
+
+    # After file updates, refresh PRD + Wiki from git_sync's JSON output
+    _refresh_prds_and_wiki(con, stats)
+
+    con.close()
+    return stats
+
+
+def _refresh_prds_and_wiki(con, stats):
+    """Import PRD index + Wiki from git_sync's JSON output into DuckDB.
+
+    git_sync.py writes these as JSON; kg_incremental reads them and UPSERTs
+    into DuckDB so MCP tools can query them.
+    """
+    INDEX = str(DATA_INDEX_DIR)
+    import json as _json
+
+    # PRD
+    prd_path = os.path.join(INDEX, '_build_cache', 'prd-index.json')
+    if not os.path.isfile(prd_path):
+        prd_path = os.path.join(INDEX, 'prd-index.json')
+    if os.path.isfile(prd_path):
+        try:
+            prds = _json.load(open(prd_path, encoding='utf-8'))
+            con.execute("DELETE FROM prds")
+            rows = [(f, info.get('title', ''),
+                     _json.dumps(info.get('keywords', []), ensure_ascii=False),
+                     _json.dumps(info.get('features', []), ensure_ascii=False),
+                     _json.dumps(info.get('cn_terms', []), ensure_ascii=False))
+                    for f, info in prds.items()]
+            if rows:
+                _batch_insert(con, 'prds', rows, ignore=True)
+                stats['prds_refreshed'] = len(rows)
+        except Exception:
+            pass
+
+    # Wiki
+    wiki_path = os.path.join(INDEX, 'wiki-index.json')
+    if os.path.isfile(wiki_path):
+        try:
+            wiki = _json.load(open(wiki_path, encoding='utf-8'))
+            con.execute("DELETE FROM wiki")
+            wiki_rows = []
+            for kw, entries in (wiki.get('index', {}) if isinstance(wiki, dict) else {}).items():
+                for e in (entries if isinstance(entries, list) else []):
+                    wiki_rows.append((kw, e.get('project', ''), e.get('title', ''),
+                                      e.get('md_path', ''), e.get('description', '')))
+            if wiki_rows:
+                _batch_insert(con, 'wiki', wiki_rows)
+                stats['wiki_refreshed'] = len(wiki_rows)
+        except Exception:
+            pass
+
+
+def _find_api_dir():
+    """Find the fywl-ui api directory."""
+    apps = os.path.join(CODE_DIR, 'fywl-ui', 'apps')
+    if os.path.isdir(apps):
+        for app in os.listdir(apps):
+            candidate = os.path.join(apps, app, 'src', 'api')
+            if os.path.isdir(candidate):
+                return candidate
+    return None
+
+
+def _load_api_table_from_duckdb(con):
+    """从 DuckDB 加载 api_table (api 函数名→端点), 避免重建。"""
+    table = {}
+    try:
+        rows = con.execute("SELECT id, props FROM entities WHERE type = 'ENDPOINT'").fetchall()
+        for eid, props_json in rows:
+            url = eid.replace('E:', '')
+            props = json.loads(props_json) if props_json else {}
+            fn_name = props.get('api_fn', '')
+            if fn_name:
+                table[fn_name] = {'url': url, 'verb': props.get('verb', '?'),
+                                  'file': props.get('source_file', '')}
+    except Exception:
+        pass
+    return table
+
+
+_API_CACHE_PATH = os.path.join(INDEX_DIR, '.api-table-cache.json')
+
+
+def _save_api_cache(api_table, api_dir):
+    """保存 api_table 到缓存文件 (含 api_dir 的 mtime 作为失效依据)。"""
+    import time
+    cache = {
+        'api_dir_mtime': os.path.getmtime(api_dir) if os.path.isdir(api_dir) else 0,
+        'saved_at': time.time(),
+        'table': api_table,
+    }
+    with open(_API_CACHE_PATH, 'w', encoding='utf-8') as f:
+        json.dump(cache, f, ensure_ascii=False)
+
+
+def _load_api_cache(api_dir):
+    """从缓存文件加载 api_table。如果缓存不存在或过期返回 {}。"""
+    if not os.path.isfile(_API_CACHE_PATH):
+        return {}
+    try:
+        cache = json.load(open(_API_CACHE_PATH, encoding='utf-8'))
+        # 检查 api_dir 的 mtime 是否变了
+        current_mtime = os.path.getmtime(api_dir) if api_dir and os.path.isdir(api_dir) else 0
+        if cache.get('api_dir_mtime') == current_mtime:
+            return cache.get('table', {})
+    except Exception:
+        pass
+    return {}
+
+
+def _update_vue_file(con, filepath, api_table, stats):
+    """Re-extract traces from one Vue file and UPSERT its button entities + edges."""
+    try:
+        content = open(filepath, 'rb').read().decode('utf-8', errors='replace')
+    except Exception:
+        return
+    if '@click' not in content:
+        return
+
+    traces = ts_trace_clicks(filepath, content, api_table)
+    vue_norm = filepath.replace('\\', '/')
+    # Normalize vue_short — MUST match kg_build.py's format exactly
+    if '/views/' in vue_norm:
+        vue_short = vue_norm.split('/views/')[-1]
+    elif '/pages/' in vue_norm:
+        vue_short = vue_norm.split('/pages/')[-1]
+    else:
+        vue_short = os.path.basename(filepath)
+
+    for t in traces:
+        handler = t.get('handler', '')
+        eid = 'B:%s:%s' % (vue_short, handler)
+        # UPSERT entity (INSERT OR REPLACE, no duplicates)
+        upsert_entity(con, eid, 'BUTTON', handler, '',
+                      {'button_text': t.get('button', ''),
+                       'vue_file': vue_norm,
+                       'confidence': t.get('confidence', '')})
+        upsert_alias(con, handler.lower(), eid)
+        stats['entities_upserted'] += 1
+
+        # Delete ALL old edges from this button first, then insert fresh
+        delete_edges_from(con, eid)
+        ep = t.get('endpoint')
+        if ep and ep != 'None':
+            to_eid = 'E:%s' % ep
+            upsert_edge(con, eid, to_eid, 'clicks', props={
+                'button': t.get('button', ''),
+                'confidence': t.get('confidence', ''),
+            })
+            stats['edges_updated'] += 1
+
+
+def _update_api_file(con, filepath, stats):
+    """Re-extract API functions from one .ts file and UPSERT endpoint entities."""
+    # Re-use the bulk api_table extraction on this single file's directory
+    api_dir = os.path.dirname(filepath)
+    file_table = build_api_fn_table(api_dir)
+    for fn_name, info in file_table.items():
+        # Only update functions defined in THIS file
+        if info.get('file', '').replace('\\', '/') != filepath.replace('\\', '/'):
+            continue
+        eid = 'E:%s' % info['url']
+        upsert_entity(con, eid, 'ENDPOINT', info['url'], '',
+                      {'verb': info.get('verb', '?'),
+                       'api_fn': fn_name,
+                       'source_file': filepath.replace('\\', '/')})
+        upsert_alias(con, fn_name.lower(), eid)
+        stats['entities_upserted'] += 1
+
+
+def _update_test_file(con, filepath, stats):
+    """Re-extract test assertions from one Test.java and UPSERT test entities."""
+    tests = extract_test_assertions(os.path.dirname(filepath))
+    # Filter to only this file
+    file_norm = filepath.replace('\\', '/')
+    for t in tests:
+        if t.get('file', '').replace('\\', '/') != file_norm:
+            continue
+        name = '%s.%s' % (t['class'], t['method'])
+        eid = 'T:%s' % name
+        upsert_entity(con, eid, 'TEST', name, '',
+                      {'display': t.get('display_name', ''),
+                       'deps': t.get('injected_deps', []),
+                       'assertions': t.get('assertions', []),
+                       'package': t.get('package', '')})
+        upsert_alias(con, name.lower(), eid)
+        stats['entities_upserted'] += 1
+
+
+def _cleanup_deleted_file(con, filepath):
+    """Remove entities belonging to a deleted file."""
+    rel = filepath.replace('\\', '/')
+    # Delete buttons from this vue file
+    if '.vue' in rel:
+        vue_short = rel.split('/views/')[-1] if '/views/' in rel else os.path.basename(rel)
+        con.execute("DELETE FROM entities WHERE id LIKE 'B:%s:%%'" % vue_short.replace("'", "''"))
+        con.execute("DELETE FROM edges WHERE from_id LIKE 'B:%s:%%'" % vue_short.replace("'", "''"))
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1:
+        changed = sys.argv[1:]
+    else:
+        print('Auto-detecting changes via git diff...')
+        changed = get_changed_files()
+
+    if not changed:
+        print('No changes detected.')
+        sys.exit(0)
+
+    # Filter to relevant file types
+    relevant = [f for f in changed if f.endswith(('.vue', '.ts', '.java'))]
+    print('Changed files: %d total, %d relevant' % (len(changed), len(relevant)))
+
+    if relevant:
+        import time
+        t0 = time.time()
+        stats = incremental_update(relevant)
+        elapsed = time.time() - t0
+        print('Incremental update done in %.1fs' % elapsed)
+        print('  Vue: %d, TS: %d, Java: %d' % (stats['vue'], stats['ts'], stats['java_test']))
+        print('  Entities UPSERTed: %d' % stats['entities_upserted'])
+        print('  Edges updated: %d' % stats['edges_updated'])
+    else:
+        print('No relevant files to update.')