@hupan56/wlkj 2.0.0

package/templates/qoder/scripts/git_sync.py

@@ -0,0 +1,1087 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Weekly Knowledge Graph Update
+
+Usage:
+  python git_sync.py              # Full update: git + PRD + index
+  python git_sync.py --sync-only  # Git pull only
+  python git_sync.py --index-only # Re-index only (no git pull)
+  python git_sync.py --prd-only   # Collect + parse PRDs only
+  python git_sync.py --project fywl-ics  # Sync single project
+
+What it does (Friday Update):
+  1. Git pull latest code for each project
+  2. Collect PRDs from all user workspaces
+  3. Parse PRDs to extract business rules and features
+  4. Build incremental indexes (only changed files)
+  5. Build PRD ↔ Code mapping
+
+Config: .qoder/config.yaml -> git_sync section
+"""
+
+import os
+import sys
+import json
+import hashlib
+import subprocess
+import re
+import shutil
+from datetime import datetime
+
+# UTF-8 stdio (防御性: stdout 被捕获时不崩溃)
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except (AttributeError, TypeError, OSError, IOError):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from common.terms import BUSINESS_PATH_MAP, CN_TO_EN, PRD_STOP_WORDS
+
+BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+DATA_DIR = os.path.join(BASE, 'data')
+CODE_DIR = os.path.join(DATA_DIR, 'code')
+INDEX_DIR = os.path.join(DATA_DIR, 'index')
+PRD_DIR = os.path.join(DATA_DIR, 'docs', 'prd')
+WORKSPACE = os.path.join(BASE, 'workspace', 'members')
+CONFIG_PATH = os.path.join(BASE, '.qoder', 'config.yaml')
+
+# Simple lock to avoid two concurrent index writers (cron + manual run)
+LOCK_FILE = os.path.join(INDEX_DIR, '.sync-lock')
+LOCK_STALE_SECONDS = 2 * 60 * 60
+
+# Collected at runtime; non-empty => exit code 1 so cron/bat can detect failure
+FAILURES = []
+
+
+def fail(msg):
+    FAILURES.append(msg)
+    print('ERROR: ' + msg)
+
+
+def acquire_lock():
+    os.makedirs(INDEX_DIR, exist_ok=True)
+    if os.path.isfile(LOCK_FILE):
+        age = datetime.now().timestamp() - os.path.getmtime(LOCK_FILE)
+        if age < LOCK_STALE_SECONDS:
+            print('Another sync appears to be running (lock age {:.0f}s).'.format(age))
+            print('If you are sure it is not, delete: ' + LOCK_FILE)
+            return False
+        print('Removing stale lock ({:.0f}s old)'.format(age))
+        os.remove(LOCK_FILE)
+    with open(LOCK_FILE, 'w', encoding='utf-8') as f:
+        f.write('{} pid={}\n'.format(datetime.now().isoformat(), os.getpid()))
+    return True
+
+
+def release_lock():
+    try:
+        os.remove(LOCK_FILE)
+    except OSError:
+        pass
+
+
+def load_json(path, default=None, required=False):
+    """Load JSON file. A corrupt file is a hard error when required=True:
+    silently continuing would let an empty dict overwrite the real index."""
+    if os.path.isfile(path):
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            backup = path + '.corrupt'
+            try:
+                shutil.copy2(path, backup)
+            except OSError:
+                backup = '(backup failed)'
+            fail('corrupt JSON {}: {} (backed up to {})'.format(
+                os.path.basename(path), e, backup))
+            if required:
+                print('Aborting: refusing to rebuild on top of a corrupt index.')
+                print('Fix or delete the file, then run: python git_sync.py --full')
+                release_lock()
+                sys.exit(1)
+    return default if default is not None else {}
+
+
+def save_json(path, data):
+    """Atomic, deterministic JSON write (temp file + replace, sorted keys)."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + '.tmp'
+    with open(tmp, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2, ensure_ascii=False, sort_keys=True)
+    os.replace(tmp, path)
+
+
+def file_md5(path):
+    h = hashlib.md5()
+    with open(path, 'rb') as f:
+        for chunk in iter(lambda: f.read(65536), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def load_config():
+    """Load config from config.yaml"""
+    if not os.path.exists(CONFIG_PATH):
+        return {}
+    try:
+        import yaml
+        with open(CONFIG_PATH, 'r', encoding='utf-8') as f:
+            return yaml.safe_load(f) or {}
+    except:
+        return {}
+
+
+# ============================================================
+# Part 1: Git Sync (Code Pull)
+# ============================================================
+
+def git_pull_project(project_name, branch=None):
+    """Git pull a single project on its configured branch.
+
+    Returns: list of changed files ([] = no change), or None on failure.
+    """
+    project_dir = os.path.join(CODE_DIR, project_name)
+    if not os.path.isdir(os.path.join(project_dir, '.git')):
+        print(f'  {project_name}: Not a git repo, skipping')
+        return []
+
+    def git(*args):
+        return subprocess.run(['git'] + list(args), cwd=project_dir,
+                              capture_output=True, text=True, encoding='utf-8',
+                              errors='replace')
+
+    # Verify we are on the configured branch (config.yaml git_sync.projects)
+    result = git('rev-parse', '--abbrev-ref', 'HEAD')
+    current_branch = result.stdout.strip() if result.returncode == 0 else ''
+    if branch and current_branch != branch:
+        fail(f'{project_name}: on branch "{current_branch}", expected "{branch}". '
+             f'Checkout the right branch manually, then re-run.')
+        return None
+
+    # Get current commit before pull
+    result = git('rev-parse', 'HEAD')
+    if result.returncode != 0:
+        fail(f'{project_name}: rev-parse failed - {result.stderr.strip()[:120]}')
+        return None
+    old_commit = result.stdout.strip()[:8]
+
+    print(f'  {project_name}: Fetching...')
+    result = git('fetch', 'origin')
+    if result.returncode != 0:
+        fail(f'{project_name}: fetch failed - {result.stderr.strip()[:120]}')
+        return None
+
+    print(f'  {project_name}: Pulling...')
+    pull_args = ['pull', 'origin'] + ([branch] if branch else [])
+    result = git(*pull_args)
+    if result.returncode != 0:
+        fail(f'{project_name}: pull failed - {result.stderr.strip()[:120]}')
+        return None
+
+    result = git('rev-parse', 'HEAD')
+    new_commit = result.stdout.strip()[:8] if result.returncode == 0 else ''
+
+    if old_commit == new_commit:
+        print(f'  {project_name}: Already up to date ({new_commit})')
+        return []
+
+    # Get changed files
+    result = git('diff', '--name-only', old_commit, new_commit)
+    if result.returncode != 0:
+        fail(f'{project_name}: diff failed - run git_sync.py --full to reindex')
+        return None
+    changed = [f.strip() for f in result.stdout.strip().split('\n') if f.strip()]
+    print(f'  {project_name}: {old_commit} -> {new_commit}, {len(changed)} files changed')
+    return changed
+
+
+def git_sync_all(project_filter=None, config=None):
+    """Sync all projects"""
+    print('\n=== Git Sync ===')
+    print(f'Time: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+
+    if not os.path.exists(CODE_DIR):
+        fail('data/code/ not found')
+        return {}
+
+    branch_cfg = {}
+    if config:
+        for name, proj in (config.get('git_sync', {}).get('projects', {}) or {}).items():
+            if isinstance(proj, dict) and proj.get('branch'):
+                branch_cfg[name] = proj['branch']
+
+    changed_map = {}
+
+    for project_name in sorted(os.listdir(CODE_DIR)):
+        if not os.path.isdir(os.path.join(CODE_DIR, project_name)):
+            continue
+        if project_filter and project_name != project_filter:
+            continue
+
+        changed = git_pull_project(project_name, branch_cfg.get(project_name))
+        if changed:
+            changed_map[project_name] = changed
+
+    if not changed_map:
+        print('\nNo projects had changes.')
+    else:
+        total = sum(len(fs) for fs in changed_map.values())
+        print(f'\nChanged: {total} files in {len(changed_map)} projects')
+
+    return changed_map
+
+
+# ============================================================
+# Part 2: PRD Collection
+# ============================================================
+
+def collect_prds():
+    """Collect PRDs from all user workspaces.
+
+    Uses content hash (not mtime) to decide updates - mtime is not preserved
+    by git, so a fresh clone would otherwise re-collect everything.
+    Same filename from two different users is a collision and is skipped
+    with a warning instead of silently overwriting.
+    """
+    print('\n=== Collecting PRDs ===\n')
+
+    if not os.path.isdir(WORKSPACE):
+        print('Workspace not found')
+        return 0
+
+    os.makedirs(PRD_DIR, exist_ok=True)
+    track_file = os.path.join(INDEX_DIR, '.prd-collected.json')
+    collected = load_json(track_file)
+
+    total_new = 0
+    total_updated = 0
+
+    for user_name in sorted(os.listdir(WORKSPACE)):
+        user_dir = os.path.join(WORKSPACE, user_name)
+        if not os.path.isdir(user_dir):
+            continue
+
+        drafts_dir = os.path.join(user_dir, 'drafts')
+        if not os.path.isdir(drafts_dir):
+            continue
+
+        for f in sorted(os.listdir(drafts_dir)):
+            if not ((f.startswith('REQ-') or f.startswith('PRD-') or f.startswith('prd-')) and f.endswith('.md')):
+                continue
+            filepath = os.path.join(drafts_dir, f)
+            digest = file_md5(filepath)
+
+            prev = collected.get(f)
+            if prev and prev.get('user') and prev['user'] != user_name:
+                fail(f'PRD filename collision: {f} exists from "{prev["user"]}" '
+                     f'and "{user_name}". Rename one of them (REQ numbers must be unique).')
+                continue
+
+            is_new = prev is None
+            is_updated = (not is_new) and prev.get('md5') != digest
+            if not (is_new or is_updated):
+                continue
+
+            shutil.copy2(filepath, os.path.join(PRD_DIR, f))
+            collected[f] = {
+                'user': user_name,
+                'md5': digest,
+                'collected_at': datetime.now().strftime('%Y-%m-%d %H:%M')
+            }
+            print(f'  {"NEW" if is_new else "UPDATED"}: {f} (by {user_name})')
+            if is_new:
+                total_new += 1
+            else:
+                total_updated += 1
+
+    save_json(track_file, collected)
+
+    print(f'\nCollected: {total_new} new, {total_updated} updated')
+    print(f'Total in prd/: {len(os.listdir(PRD_DIR)) if os.path.isdir(PRD_DIR) else 0}')
+    return total_new + total_updated
+
+
+# ============================================================
+# Part 3: PRD Parsing
+# ============================================================
+
+def extract_chinese_terms(text):
+    """Extract meaningful business terms (stop words come from common.terms)"""
+    raw = re.findall(r'[一-鿿]{2,4}', text)
+    return list(set([t for t in raw if t not in PRD_STOP_WORDS and len(t) >= 2]))[:30]
+
+
+def parse_prd_file(filepath):
+    """Parse a single PRD file"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        text = f.read()
+
+    filename = os.path.basename(filepath)
+
+    # Extract title
+    title_match = re.search(r'^#\s+(.+)', text, re.MULTILINE)
+    title = title_match.group(1).strip() if title_match else filename.replace('.md', '')
+
+    # Extract sections
+    sections = re.findall(r'^#{1,3}\s+(.+)', text, re.MULTILINE)
+
+    # Extract features (numbered items)
+    features = re.findall(r'(?:^|\n)\s*\d+\.\s+\**(.+?)\**', text)
+    features = [f.strip()[:100] for f in features if len(f.strip()) > 3][:20]
+
+    # Extract business rules
+    rules = []
+    rule_patterns = [
+        r'规则[:：]\s*(.+)',
+        r'(?:必须|不能|不允许|需要|应当|默认).{5,}',
+        r'当.{2,20}时[，,].{5,}',
+    ]
+    for p in rule_patterns:
+        rules.extend(re.findall(p, text))
+    rules = [r.strip()[:200] for r in rules][:15]
+
+    # Extract keywords (CN -> EN mapping from common.terms)
+    cn_terms = extract_chinese_terms(text)
+
+    keywords = set()
+    for term in cn_terms:
+        keywords.add(term)
+        if term in CN_TO_EN:
+            keywords.add(CN_TO_EN[term])
+
+    return {
+        'file': filename,
+        'title': title,
+        'sections': sections[:20],
+        'features': features,
+        'rules': rules,
+        'keywords': list(keywords)[:50],
+        'cn_terms': cn_terms[:30],
+        'mtime': os.path.getmtime(filepath),
+    }
+
+
+def build_prd_index(keyword_index=None):
+    """Build PRD index from all PRD files.
+
+    Args:
+        keyword_index: 可选预加载的 keyword-index (性能优化 A3: 避免重复加载 4.5MB JSON)。
+                       None 则自行加载。
+    """
+    print('\n=== Building PRD Index ===\n')
+
+    if not os.path.isdir(PRD_DIR):
+        print('PRD directory not found')
+        return {}
+
+    # Load keyword index for code matching (复用传入的, 避免重复加载)
+    if keyword_index is None:
+        ki_path = os.path.join(INDEX_DIR, 'keyword-index.json')
+        keyword_index = load_json(ki_path)
+
+    prd_index = {}
+
+    for f in sorted(os.listdir(PRD_DIR)):
+        if not f.endswith('.md'):
+            continue
+
+        filepath = os.path.join(PRD_DIR, f)
+        try:
+            prd = parse_prd_file(filepath)
+
+            # Find related code
+            related = {}
+            for kw in prd['keywords']:
+                if kw in keyword_index:
+                    for cf in keyword_index[kw][:3]:
+                        proj = cf.split('/')[0] if '/' in cf else cf.split('\\')[0]
+                        related.setdefault(proj, set()).add(cf)
+            prd['related_code'] = {p: list(fs) for p, fs in related.items()}
+
+            prd_index[f] = prd
+
+            print(f'  {f}')
+            print(f'    Title: {prd["title"][:50]}')
+            print(f'    Features: {len(prd["features"])}, Rules: {len(prd["rules"])}')
+            if prd['related_code']:
+                for proj, files in prd['related_code'].items():
+                    print(f'    -> {proj}: {len(files)} files')
+
+        except Exception as e:
+            print(f'  {f}: Error - {str(e)[:80]}')
+
+    # Save index
+    save_json(os.path.join(INDEX_DIR, 'prd-index.json'), prd_index)
+
+    print(f'\nPRD Index: {len(prd_index)} PRDs indexed')
+    return prd_index
+
+
+# ============================================================
+# Part 4: Incremental Code Index Update
+# ============================================================
+
+def parse_java_file(filepath):
+    """Extract entities from a Java file"""
+    entities = []
+    try:
+        with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+
+        class_match = re.search(r'(?:public\s+)?(?:abstract\s+)?(?:class|interface|enum)\s+(\w+)', content)
+        class_name = class_match.group(1) if class_match else None
+
+        apis = re.findall(
+            r'@(?:GetMapping|PostMapping|PutMapping|DeleteMapping|RequestMapping)\s*\(?["\']([^"\']+)["\']',
+            content
+        )
+
+        methods = re.findall(r'(?:public|private|protected)\s+\w+\s+(\w+)\s*\(', content)
+
+        rel = os.path.relpath(filepath, CODE_DIR).replace(os.sep, '/')
+
+        entity = {
+            'file': rel,
+            'class': class_name,
+            'apis': apis,
+            'methods': methods[:20],
+            'keywords': re.findall('[A-Z]?[a-z]+', class_name or '') if class_name else []
+        }
+        entities.append(entity)
+    except:
+        pass
+    return entities
+
+
+def parse_frontend_file(filepath):
+    """Extract entities from frontend file"""
+    entities = []
+    try:
+        with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+
+        rel = os.path.relpath(filepath, CODE_DIR).replace(os.sep, '/')
+
+        name_match = re.search(r'name:\s*["\'](\w+)["\']', content)
+        component_name = name_match.group(1) if name_match else os.path.basename(filepath).split('.')[0]
+
+        api_calls = re.findall(r'(?:axios|request|fetch|http)\.\w+\s*\(?["\']([^"\']+)["\']', content)
+        routes = re.findall(r'path:\s*["\']([^"\']+)["\']', content)
+
+        entity = {
+            'file': rel,
+            'component': component_name,
+            'api_calls': api_calls,
+            'routes': routes,
+            'type': 'vue' if filepath.endswith('.vue') else 'js/ts'
+        }
+        entities.append(entity)
+    except:
+        pass
+    return entities
+
+
+def build_file_keys_map(keyword_index):
+    """构建反向索引 {file: set(keywords)} (性能优化 A5)。
+
+    用于 remove_file_from_indexes 的 O(1) 查找, 替代 O(all_keys) 全扫描。
+    每次全量/增量构建后调用一次, 持久化到 .file-keys.json。
+    """
+    fkm = {}
+    for kw, files in keyword_index.items():
+        for f in files:
+            fkm.setdefault(f, set()).add(kw)
+    return fkm
+
+
+def remove_file_from_indexes(filepath, keyword_index, api_index, file_keys_map=None):
+    """Remove a file's entries from keyword/api indexes.
+
+    module-map.json stores per-project COUNTS (not file lists) and is
+    recomputed by rebuild_module_summary() after each update.
+
+    Args:
+        file_keys_map: 可选反向索引 {file: set(keywords)} (A5)。
+                       有则 O(1) 查找涉及的 keys; None 则回退到 O(all_keys) 全扫描。
+    """
+    rel = filepath.replace(os.sep, '/')
+
+    # 性能优化 A5: 优先用反向索引 O(1) 查找, 避免遍历全部 keys
+    if file_keys_map is not None:
+        involved_keys = file_keys_map.pop(rel, set())
+        to_remove = []
+        for kw in involved_keys:
+            files = keyword_index.get(kw)
+            if files and rel in files:
+                files.remove(rel)
+                if not files:
+                    to_remove.append(kw)
+        for kw in to_remove:
+            del keyword_index[kw]
+    else:
+        # 回退路径: 全扫描 (旧逻辑, 兼容)
+        to_remove = []
+        for kw, files in keyword_index.items():
+            if rel in files:
+                files.remove(rel)
+                if not files:
+                    to_remove.append(kw)
+        for kw in to_remove:
+            del keyword_index[kw]
+
+    # Remove from api_index
+    to_remove_api = [api for api, f in api_index.items() if f == rel]
+    for api in to_remove_api:
+        del api_index[api]
+
+
+INDEXED_EXTS_JAVA = ('.java',)
+INDEXED_EXTS_FRONTEND = ('.vue', '.js', '.ts', '.jsx', '.tsx')
+INDEXED_EXTS_CONFIG = ('.xml', '.yml', '.yaml', '.properties')
+SKIP_DIRS = ['node_modules', 'target', 'build', 'dist', '__pycache__']
+
+
+def rebuild_module_summary(api_index, file_stats=None):
+    """Recompute module-map.json counts.
+
+    Schema (counts only, matching what's committed):
+      {project: {files: int, classes: int, apis: int, components: int}}
+
+    Args:
+        api_index: endpoint→file map.
+        file_stats: 可选的预统计 {project: {files, classes, components}},
+                    避免二次全盘 walk (性能优化 A3)。None 则回退到 walk。
+    """
+    if file_stats:
+        # 快速路径: 复用 build_full_indexes 已有的统计, 不再 walk
+        module_map = {}
+        for project_name, st in file_stats.items():
+            prefix = project_name + '/'
+            module_map[project_name] = {
+                'files': st.get('files', 0),
+                'classes': st.get('classes', 0),
+                'components': st.get('components', 0),
+                'apis': sum(1 for f in api_index.values() if f.startswith(prefix)),
+            }
+        return module_map
+
+    # 回退路径: walk 统计 (旧逻辑, 兼容)
+    module_map = {}
+    if not os.path.isdir(CODE_DIR):
+        return module_map
+    for project_name in sorted(os.listdir(CODE_DIR)):
+        project_dir = os.path.join(CODE_DIR, project_name)
+        if not os.path.isdir(project_dir):
+            continue
+        total = java = fe = 0
+        for root, dirs, files in os.walk(project_dir):
+            dirs[:] = [d for d in dirs if not d.startswith('.') and d not in SKIP_DIRS]
+            for f in files:
+                ext = os.path.splitext(f)[1]
+                if ext in INDEXED_EXTS_JAVA:
+                    java += 1
+                    total += 1
+                elif ext in INDEXED_EXTS_FRONTEND:
+                    fe += 1
+                    total += 1
+                elif ext in INDEXED_EXTS_CONFIG:
+                    total += 1
+        prefix = project_name + '/'
+        module_map[project_name] = {
+            'files': total,
+            'classes': java,
+            'components': fe,
+            'apis': sum(1 for f in api_index.values() if f.startswith(prefix)),
+        }
+    return module_map
+
+
+def normalize_keyword_index(keyword_index):
+    """Dedupe and sort file lists so output is deterministic (diff-friendly)."""
+    for kw in keyword_index:
+        keyword_index[kw] = sorted(set(keyword_index[kw]))
+
+
+def index_one_file(filepath, rel, ext, keyword_index, api_index):
+    """Parse a single source file into the keyword/api indexes.
+
+    Shared by incremental and full build so both produce identical entries.
+    Returns True if the file was indexed.
+    """
+    if ext in INDEXED_EXTS_JAVA:
+        for e in parse_java_file(filepath):
+            for api in e.get('apis', []):
+                api_index[api] = rel
+            for kw in e.get('keywords', []):
+                kl = kw.lower()
+                if len(kl) >= 2:
+                    keyword_index.setdefault(kl, [])
+                    if rel not in keyword_index[kl]:
+                        keyword_index[kl].append(rel)
+        return True
+    if ext in INDEXED_EXTS_FRONTEND:
+        for e in parse_frontend_file(filepath):
+            for api in e.get('api_calls', []):
+                key = 'api:' + api
+                keyword_index.setdefault(key, [])
+                if rel not in keyword_index[key]:
+                    keyword_index[key].append(rel)
+            comp = e.get('component', '')
+            if comp:
+                cl = comp.lower()
+                keyword_index.setdefault(cl, [])
+                if rel not in keyword_index[cl]:
+                    keyword_index[cl].append(rel)
+        return True
+    return False
+
+
+def update_indexes_incremental(changed_projects):
+    """Update indexes incrementally for changed projects only"""
+    print('\n=== Incremental Index Update ===\n')
+
+    os.makedirs(INDEX_DIR, exist_ok=True)
+
+    # required=True: refusing to "rebuild" on top of a corrupt/empty base
+    keyword_index = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'), required=True)
+    api_index = load_json(os.path.join(INDEX_DIR, 'api-index.json'), required=True)
+
+    # 性能优化 A5: 加载反向索引 (若存在) 加速 remove_file_from_indexes
+    fkm_path = os.path.join(INDEX_DIR, '.file-keys.json')
+    file_keys_map = load_json(fkm_path) if os.path.isfile(fkm_path) else None
+    if file_keys_map:
+        # 转 set 形式 (内存里操作用 set, 持久化时转 list)
+        file_keys_map = {f: set(ks) for f, ks in file_keys_map.items()}
+
+    total_files = 0
+
+    for project_name, changed_files in changed_projects.items():
+        project_dir = os.path.join(CODE_DIR, project_name)
+        if not os.path.isdir(project_dir):
+            continue
+
+        print(f'  [{project_name}] Updating {len(changed_files)} files...')
+
+        for changed_file in changed_files:
+            filepath = os.path.join(project_dir, changed_file)
+            rel = (project_name + '/' + changed_file).replace(os.sep, '/')
+
+            # Remove old entries (用反向索引 O(1), 若不可用回退全扫描)
+            remove_file_from_indexes(rel, keyword_index, api_index, file_keys_map=file_keys_map)
+
+            # Skip if file deleted
+            if not os.path.isfile(filepath):
+                continue
+
+            ext = os.path.splitext(changed_file)[1]
+            if index_one_file(filepath, rel, ext, keyword_index, api_index):
+                total_files += 1
+                # 同步更新反向索引
+                if file_keys_map is not None:
+                    file_keys_map.setdefault(rel, set())
+
+    normalize_keyword_index(keyword_index)
+
+    # 重建反向索引 (增量后 keys 关系变了, 重建最可靠)
+    fkm_new = build_file_keys_map(keyword_index)
+    module_map = rebuild_module_summary(api_index)
+
+    save_json(os.path.join(INDEX_DIR, 'module-map.json'), module_map)
+    save_json(os.path.join(INDEX_DIR, 'keyword-index.json'), keyword_index)
+    save_json(os.path.join(INDEX_DIR, 'api-index.json'), api_index)
+    save_json(os.path.join(INDEX_DIR, '.file-keys.json'),
+              {f: sorted(ks) for f, ks in fkm_new.items()})
+
+    print(f'\n  Updated: {total_files} files indexed')
+    print(f'  Keywords: {len(keyword_index)}')
+    print(f'  APIs: {len(api_index)}')
+
+    return total_files
+
+
+def _index_project(project_name, project_dir, skip_dirs):
+    """索引单个项目的所有文件 (并行 worker 函数, A4)。
+
+    在子进程里运行: walk + parse, 返回该项目的 (keyword_dict, api_dict, stats)。
+    保持与串行版完全一致的解析逻辑 (复用 index_one_file 的核心)。
+    """
+    local_ki = {}
+    local_api = {}
+    proj_count = proj_java = proj_fe = 0
+
+    for root, dirs, files in os.walk(project_dir):
+        dirs[:] = [d for d in dirs if not d.startswith('.') and d not in skip_dirs]
+        for f in sorted(files):
+            ext = os.path.splitext(f)[1]
+            filepath = os.path.join(root, f)
+            rel = os.path.relpath(filepath, os.path.dirname(project_dir)).replace(os.sep, '/')
+            if ext in INDEXED_EXTS_JAVA:
+                for e in parse_java_file(filepath):
+                    for api in e.get('apis', []):
+                        local_api[api] = rel
+                    for kw in e.get('keywords', []):
+                        kl = kw.lower()
+                        if len(kl) >= 2:
+                            local_ki.setdefault(kl, [])
+                            if rel not in local_ki[kl]:
+                                local_ki[kl].append(rel)
+                proj_count += 1
+                proj_java += 1
+            elif ext in INDEXED_EXTS_FRONTEND:
+                for e in parse_frontend_file(filepath):
+                    for api in e.get('api_calls', []):
+                        key = 'api:' + api
+                        local_ki.setdefault(key, [])
+                        if rel not in local_ki[key]:
+                            local_ki[key].append(rel)
+                    comp = e.get('component', '')
+                    if comp:
+                        cl = comp.lower()
+                        local_ki.setdefault(cl, [])
+                        if rel not in local_ki[cl]:
+                            local_ki[cl].append(rel)
+                proj_count += 1
+                proj_fe += 1
+            elif ext in INDEXED_EXTS_CONFIG:
+                proj_count += 1
+
+    stats = {'files': proj_count, 'classes': proj_java, 'components': proj_fe}
+    return project_name, local_ki, local_api, stats
+
+
+def build_full_indexes():
+    """Build full indexes from scratch"""
+    print('\n=== Full Index Build ===\n')
+
+    if not os.path.isdir(CODE_DIR):
+        fail('data/code/ not found - cannot build indexes')
+        return 0
+
+    os.makedirs(INDEX_DIR, exist_ok=True)
+
+    # 收集要处理的项目
+    projects = []
+    for project_name in sorted(os.listdir(CODE_DIR)):
+        project_dir = os.path.join(CODE_DIR, project_name)
+        if os.path.isdir(project_dir):
+            projects.append((project_name, project_dir))
+
+    keyword_index = {}
+    api_index = {}
+    total_files = 0
+    file_stats = {}
+
+    # 性能优化 A4: 按 project 并行索引 (项目间独立, 适合 ProcessPool)
+    # 项目数少 (3个), 序列化开销可接受; 单项目内仍串行 (避免 12k 文件的小任务开销)
+    use_parallel = len(projects) >= 2
+    if use_parallel:
+        try:
+            from concurrent.futures import ProcessPoolExecutor
+            import multiprocessing as mp
+            workers = min(len(projects), mp.cpu_count())
+            print(f'  Parallel indexing with {workers} workers...')
+            with ProcessPoolExecutor(max_workers=workers) as pool:
+                futures = []
+                for pname, pdir in projects:
+                    futures.append(pool.submit(_index_project, pname, pdir, SKIP_DIRS))
+                for fut in futures:
+                    pname, local_ki, local_api, stats = fut.result()
+                    # 合并到全局 index
+                    for kw, files in local_ki.items():
+                        keyword_index.setdefault(kw, []).extend(files)
+                    api_index.update(local_api)
+                    file_stats[pname] = stats
+                    total_files += stats['files']
+                    print(f'    [{pname}] Files: {stats["files"]}')
+        except Exception as e:
+            # 并行失败回退串行 (鲁棒性)
+            print(f'  Parallel failed ({e}), falling back to serial...')
+            use_parallel = False
+
+    if not use_parallel:
+        # 串行回退 (或单项目)
+        for project_name, project_dir in projects:
+            print(f'  [{project_name}] Scanning...')
+            pname, local_ki, local_api, stats = _index_project(project_name, project_dir, SKIP_DIRS)
+            for kw, files in local_ki.items():
+                keyword_index.setdefault(kw, []).extend(files)
+            api_index.update(local_api)
+            file_stats[pname] = stats
+            total_files += stats['files']
+            print(f'    Files: {stats["files"]}')
+
+    normalize_keyword_index(keyword_index)
+    # 复用 file_stats, 不再二次 walk (A3)
+    module_map = rebuild_module_summary(api_index, file_stats=file_stats)
+
+    save_json(os.path.join(INDEX_DIR, 'module-map.json'), module_map)
+    save_json(os.path.join(INDEX_DIR, 'keyword-index.json'), keyword_index)
+    save_json(os.path.join(INDEX_DIR, 'api-index.json'), api_index)
+
+    # 性能优化 A5: 持久化反向索引 {file: [keywords]} 供增量更新 O(1) 查找
+    fkm = build_file_keys_map(keyword_index)
+    save_json(os.path.join(INDEX_DIR, '.file-keys.json'),
+              {f: sorted(ks) for f, ks in fkm.items()})
+
+    print(f'\n  Total: {total_files} files, {len(keyword_index)} keywords, {len(api_index)} APIs')
+    return total_files
+
+
+# ============================================================
+# Part 5: PRD ↔ Code Mapping
+# ============================================================
+# Business term -> code path mapping comes from common.terms (BUSINESS_PATH_MAP)
+# so that index building and searching share the same semantics.
+
+# Below this length, only exact matches count (substring matching on short
+# keywords like "in"/"sa" pollutes the mapping)
+MIN_PATTERN_FUZZY_LEN = 4
+
+
+def build_prd_code_mapping(keyword_index=None):
+    """Build bidirectional PRD to Code mapping with business term awareness.
+
+    Args:
+        keyword_index: 可选预加载 (A3: 避免重复加载)。
+    """
+    print('\n=== Building PRD to Code Mapping ===\n')
+
+    prd_index = load_json(os.path.join(INDEX_DIR, 'prd-index.json'))
+    if keyword_index is None:
+        keyword_index = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
+
+    mapping = {'prd_to_code': {}, 'code_to_prd': {}}
+
+    for prd_file, prd in prd_index.items():
+        related_files = set()
+        title = prd.get('title', '')
+        cn_terms = prd.get('cn_terms', [])
+        keywords = prd.get('keywords', [])
+
+        # Strategy 1: Business term to path pattern matching
+        all_text = title + ' ' + ' '.join(cn_terms) + ' ' + ' '.join(keywords)
+        for cn_term, en_patterns in BUSINESS_PATH_MAP.items():
+            if cn_term not in all_text:
+                continue
+            for pattern in en_patterns:
+                pat_lower = pattern.strip('/-').lower()
+                if not pat_lower:
+                    continue
+                for kw, files in keyword_index.items():
+                    kw_lower = kw.lower()
+                    if kw_lower == pat_lower or (
+                        len(kw_lower) >= MIN_PATTERN_FUZZY_LEN and kw_lower in pat_lower
+                    ) or (
+                        len(pat_lower) >= MIN_PATTERN_FUZZY_LEN and pat_lower in kw_lower
+                    ):
+                        related_files.update(files[:5])
+
+        # Strategy 2: Direct keyword matching
+        for kw in keywords[:20]:
+            kw_lower = kw.lower()
+            if kw_lower in keyword_index:
+                related_files.update(keyword_index[kw_lower][:3])
+
+        # Strategy 3: CN to EN translation (shared map)
+        for term in cn_terms:
+            if term in CN_TO_EN:
+                en = CN_TO_EN[term].lower()
+                if en in keyword_index:
+                    related_files.update(keyword_index[en][:5])
+
+        # Deduplicate, sort for determinism, and limit
+        related_files = sorted(related_files)[:30]
+
+        mapping['prd_to_code'][prd_file] = {
+            'title': title,
+            'files': related_files,
+            'features': prd.get('features', [])[:10]
+        }
+
+        # Reverse mapping
+        for f in related_files:
+            mapping['code_to_prd'].setdefault(f, [])
+            if prd_file not in mapping['code_to_prd'][f]:
+                mapping['code_to_prd'][f].append(prd_file)
+
+    save_json(os.path.join(INDEX_DIR, 'prd-code-map.json'), mapping)
+
+    print(f'  PRD -> Code: {len(mapping["prd_to_code"])} PRDs mapped')
+    print(f'  Code -> PRD: {len(mapping["code_to_prd"])} files with PRD links')
+
+    for prd_file, info in list(mapping['prd_to_code'].items())[:3]:
+        print(f'\n  {prd_file}:')
+        print(f'    {info["title"][:50]}')
+        print(f'    -> {len(info["files"])} related files')
+
+    return mapping
+
+
+# ============================================================
+# Part 6: Index Verification (准确性校验)
+# ============================================================
+
+# 条目数比上次下降超过这个比例视为异常 (防止静默清空/构建残废)
+MAX_SHRINK_RATIO = 0.3
+# 抽样检查的文件数下限命中率
+MIN_SAMPLE_HIT = 0.8
+
+
+def verify_indexes(config):
+    """Post-build sanity checks. Returns dict written into .index-meta.json.
+
+    1. 每个配置的项目都在 module-map 里且 files > 0
+    2. keyword/api 条目数与上次相比未暴跌 (>30% 下降 = 异常)
+    3. 抽样 20 个索引条目, 验证文件真实存在于磁盘
+    """
+    print('\n=== Verifying Indexes ===\n')
+    result = {'checked_at': datetime.now().strftime('%Y-%m-%d %H:%M'), 'checks': {}}
+
+    module_map = load_json(os.path.join(INDEX_DIR, 'module-map.json'))
+    keyword_index = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
+    api_index = load_json(os.path.join(INDEX_DIR, 'api-index.json'))
+
+    # Check 1: 配置的项目全部被索引
+    configured = list(((config.get('git_sync', {}) or {}).get('projects', {}) or {}).keys())
+    for proj in configured:
+        info = module_map.get(proj)
+        files = info.get('files', 0) if isinstance(info, dict) else 0
+        if not files:
+            fail(f'verify: 项目 {proj} 不在索引中或 files=0')
+        else:
+            print(f'  [OK] {proj}: {files} files indexed')
+    result['checks']['projects'] = {p: (module_map.get(p) or {}).get('files', 0) for p in configured}
+
+    # Check 2: 条目数突变检测 (与上次 meta 对比)
+    prev_meta = load_json(os.path.join(INDEX_DIR, '.index-meta.json'))
+    prev_counts = prev_meta.get('counts', {})
+    counts = {'keywords': len(keyword_index), 'apis': len(api_index)}
+    for name, now in counts.items():
+        prev = prev_counts.get(name, 0)
+        if prev > 50 and now < prev * (1 - MAX_SHRINK_RATIO):
+            fail(f'verify: {name} 条目数从 {prev} 暴跌到 {now} (>30%), 索引可能损坏')
+        else:
+            print(f'  [OK] {name}: {now} (prev {prev})')
+    result['checks']['counts'] = counts
+
+    # Check 3: 抽样验证索引指向的文件真实存在
+    sample, step = [], max(1, len(keyword_index) // 20)
+    for i, (kw, files) in enumerate(sorted(keyword_index.items())):
+        if i % step == 0 and files:
+            sample.append(files[0])
+        if len(sample) >= 20:
+            break
+    if sample:
+        hits = sum(1 for f in sample if os.path.isfile(os.path.join(CODE_DIR, f)))
+        ratio = hits / len(sample)
+        if ratio < MIN_SAMPLE_HIT:
+            fail(f'verify: 抽样 {len(sample)} 条仅 {hits} 条文件存在 ({ratio:.0%}), 索引与磁盘脱节')
+        else:
+            print(f'  [OK] 抽样 {len(sample)} 条, {hits} 条文件存在 ({ratio:.0%})')
+        result['checks']['sample_hit_ratio'] = round(ratio, 2)
+
+    return result
+
+
+def main():
+    config = load_config()
+
+    sync_only = '--sync-only' in sys.argv
+    index_only = '--index-only' in sys.argv
+    prd_only = '--prd-only' in sys.argv
+    full_build = '--full' in sys.argv
+
+    project_filter = None
+    for i, arg in enumerate(sys.argv[1:], 1):
+        if arg == '--project' and i + 1 < len(sys.argv):
+            project_filter = sys.argv[i + 1]
+
+    print('=' * 50)
+    print('QODER Knowledge Graph Update')
+    print(f'Time: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')
+    print('=' * 50)
+
+    if not acquire_lock():
+        sys.exit(2)
+
+    try:
+        changed_projects = {}
+
+        # 性能优化 A3: 共享 keyword_index 加载 (避免 build_prd_index 和
+        # build_prd_code_mapping 各自重复加载 4.5MB JSON)
+        shared_ki = None  # 懒加载: 首次需要时加载, 后续复用
+
+        # Step 1: Git sync
+        if not (index_only or prd_only):
+            changed_projects = git_sync_all(project_filter, config)
+
+        # Step 2: Collect PRDs
+        if not (sync_only or index_only):
+            collect_prds()
+
+        # Step 3: Parse PRDs and build PRD index (共享 keyword_index)
+        if not sync_only:
+            if shared_ki is None and os.path.isfile(os.path.join(INDEX_DIR, 'keyword-index.json')):
+                shared_ki = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
+            build_prd_index(keyword_index=shared_ki)
+
+        # Step 4: Update code indexes
+        if not (sync_only or prd_only):
+            if full_build or index_only:
+                build_full_indexes()
+                # full build 重写了 keyword-index, 失效旧缓存
+                shared_ki = None
+            elif changed_projects:
+                update_indexes_incremental(changed_projects)
+                shared_ki = None  # 增量也改了, 失效
+            else:
+                print('\nNo code changes to index.')
+
+        # Step 5: Build PRD ↔ Code mapping (共享 keyword_index, 重新加载若失效)
+        if not sync_only:
+            if shared_ki is None and os.path.isfile(os.path.join(INDEX_DIR, 'keyword-index.json')):
+                shared_ki = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
+            build_prd_code_mapping(keyword_index=shared_ki)
+
+        # Step 5.5: Verify index accuracy (跨项目泛化的保证)
+        verify_result = None
+        if not (sync_only or prd_only):
+            verify_result = verify_indexes(config)
+
+        # Step 6: Write meta (读 module-map 拿真实 project 数; counts 用已加载的 ki)
+        module_map = load_json(os.path.join(INDEX_DIR, 'module-map.json'))
+        if shared_ki is None:
+            shared_ki = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
+        api_idx = load_json(os.path.join(INDEX_DIR, 'api-index.json'))
+        meta = {
+            'last_sync': datetime.now().strftime('%Y-%m-%d %H:%M'),
+            'projects': {p: info.get('files', 0) for p, info in module_map.items()},
+            'counts': {
+                'keywords': len(shared_ki),
+                'apis': len(api_idx),
+            },
+            'verify': verify_result,
+            'failures': FAILURES,
+        }
+        save_json(os.path.join(INDEX_DIR, '.index-meta.json'), meta)
+    finally:
+        release_lock()
+
+    print('\n' + '=' * 50)
+    if FAILURES:
+        print(f'Update finished with {len(FAILURES)} ERROR(S):')
+        for msg in FAILURES:
+            print('  - ' + msg)
+        print('=' * 50)
+        sys.exit(1)
+    print('Update complete!')
+    print('=' * 50)
+
+
+if __name__ == '__main__':
+    main()