@hupan56/wlkj 2.2.5 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"

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

@@ -0,0 +1,243 @@
+# -*- coding: utf-8 -*-
+"""
+repowiki.py - 读取 Qoder IDE 生成的 Repo Wiki, 转成搜索可用的索引。
+
+Repo Wiki 是 Qoder IDE 用 LLM 对整个仓库生成的语义级知识图谱:
+  - wiki_catalogs: 模块/功能文档 (含 dependent_files 源文件映射)
+  - wiki_items: 文档标题/描述
+  - knowledge_relations: 模块间父子/依赖关系
+  - content/*.md: 带行号引用的人类可读文档
+
+位置: data/code/{project}/.qoder/repowiki/{lang}/meta/repowiki-metadata.json
+      data/code/{project}/.qoder/repowiki/{lang}/content/{分类}/{页面}.md
+
+本模块把这些转成:
+  - wiki-index.json: {关键词: [{project, title, catalog_id, md_path, dependent_files}]}
+  - 供 search_index --wiki 和 context_pack 使用
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+def find_repowiki_dirs(code_dir: str) -> List[tuple]:
+    """扫描 data/code/{project}/.qoder/repowiki/, 返回 [(project, wiki_root), ...]。"""
+    results = []
+    if not os.path.isdir(code_dir):
+        return results
+    for proj in os.listdir(code_dir):
+        # 找 repowiki 目录 (可能是 zh/ 或 en/)
+        wiki_base = os.path.join(code_dir, proj, '.qoder', 'repowiki')
+        if not os.path.isdir(wiki_base):
+            continue
+        for lang in os.listdir(wiki_base):
+            lang_dir = os.path.join(wiki_base, lang)
+            meta = os.path.join(lang_dir, 'meta', 'repowiki-metadata.json')
+            if os.path.isfile(meta):
+                results.append((proj, lang_dir))
+                break  # 每个项目只取一个语言版本
+    return results
+
+
+def load_wiki_metadata(wiki_root: str) -> Optional[dict]:
+    """加载 repowiki-metadata.json。"""
+    meta_path = os.path.join(wiki_root, 'meta', 'repowiki-metadata.json')
+    try:
+        with open(meta_path, encoding='utf-8') as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _extract_keywords(text: str) -> List[str]:
+    """从标题/描述提取搜索关键词 (中文分词 + 英文小写)。"""
+    if not text:
+        return []
+    words = set()
+    # 英文: 按非字母数字分割, 保留长度>=3的
+    for tok in re.split(r'[^a-zA-Z0-9]+', text):
+        tok = tok.strip().lower()
+        if len(tok) >= 3:
+            words.add(tok)
+    # 中文: 整段作为关键词 (让 CN_MAP 在搜索时做分词扩展)
+    # 提取连续中文片段
+    for m in re.finditer(r'[\u4e00-\u9fff]{2,}', text):
+        words.add(m.group())
+    return list(words)
+
+
+def build_wiki_index(code_dir: str, output_path: str) -> dict:
+    """扫描所有项目的 Repo Wiki, 构建 wiki-index.json。
+
+    Returns:
+        构建的索引 dict: {keyword: [{project, title, catalog_id, md_path, dependent_files, description}]}
+    """
+    wiki_dirs = find_repowiki_dirs(code_dir)
+    if not wiki_dirs:
+        return {}
+
+    index = {}  # keyword -> [entry, ...]
+    stats = {'projects': 0, 'pages': 0, 'keywords': 0}
+
+    for project, wiki_root in wiki_dirs:
+        meta = load_wiki_metadata(wiki_root)
+        if not meta:
+            continue
+        stats['projects'] += 1
+
+        catalogs = meta.get('wiki_catalogs', [])
+        items = meta.get('wiki_items', [])
+        # catalog_id -> title 映射
+        id_to_title = {it.get('catalog_id'): it.get('title', '') for it in items}
+
+        for cat in catalogs:
+            cat_id = cat.get('id', '')
+            name = cat.get('name', '')
+            desc = cat.get('description', '')
+            dep_files = cat.get('dependent_files', '')
+            title = id_to_title.get(cat_id, name)
+
+            # 找对应的 markdown 文档
+            md_path = _find_md_for_catalog(wiki_root, cat_id, name)
+            if not md_path:
+                continue
+
+            stats['pages'] += 1
+
+            # 提取关键词 (标题 + 描述 + 依赖文件名)
+            kw_text = ' '.join([title, name, desc])
+            # 依赖文件也作为关键词 (异常.java → 搜"异常"能命中)
+            if dep_files:
+                kw_text += ' ' + dep_files.replace(',', ' ').replace('/', ' ')
+            keywords = _extract_keywords(kw_text)
+
+            entry = {
+                'project': project,
+                'title': title or name,
+                'catalog_id': cat_id,
+                'md_path': md_path,
+                'dependent_files': [f.strip() for f in dep_files.split(',') if f.strip()] if dep_files else [],
+                'description': desc,
+            }
+
+            for kw in keywords:
+                index.setdefault(kw, [])
+                if entry not in index[kw]:
+                    index[kw].append(entry)
+
+    stats['keywords'] = len(index)
+
+    # 写入
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    with open(output_path, 'w', encoding='utf-8') as f:
+        json.dump({'index': index, 'stats': stats}, f, ensure_ascii=False, indent=2)
+
+    return {'index': index, 'stats': stats}
+
+
+def _find_md_for_catalog(wiki_root: str, catalog_id: str, name: str) -> Optional[str]:
+    """在 content/ 目录下找对应的 markdown 文件。
+
+    文件名通常等于 catalog name (.md), 在某个子分类目录下。
+    """
+    content_dir = os.path.join(wiki_root, 'content')
+    if not os.path.isdir(content_dir):
+        return None
+    target = name + '.md'
+    for root, dirs, files in os.walk(content_dir):
+        if target in files:
+            return os.path.join(root, target)
+    # 模糊匹配: name 的第一段
+    short = name.split('-')[0].split('（')[0].strip()
+    if short and short != name:
+        target2 = short + '.md'
+        for root, dirs, files in os.walk(content_dir):
+            for fn in files:
+                if fn == target2 or short in fn:
+                    return os.path.join(root, fn)
+    return None
+
+
+def load_wiki_index(index_dir: str) -> dict:
+    """加载已构建的 wiki-index.json。返回 {} 表示不存在。"""
+    path = os.path.join(index_dir, 'wiki-index.json')
+    try:
+        with open(path, encoding='utf-8') as f:
+            data = json.load(f)
+        return data.get('index', {}) if isinstance(data, dict) else data
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def search_wiki(query: str, index_dir: str, code_dir: str,
+                cn_map: Optional[dict] = None) -> List[dict]:
+    """在 Repo Wiki 索引里搜索。
+
+    自动扩展中文查询 (用 cn_map), 返回匹配的 wiki 条目列表。
+    如果 wiki-index.json 不存在, 自动构建。
+    """
+    wiki_idx = load_wiki_index(index_dir)
+    if not wiki_idx:
+        # 自动构建
+        out = os.path.join(index_dir, 'wiki-index.json')
+        result = build_wiki_index(code_dir, out)
+        if isinstance(result, dict):
+            wiki_idx = result.get('index', {})
+        else:
+            wiki_idx = result
+
+    if not wiki_idx:
+        return []
+
+    # 扩展查询词 (复用 search_index 的 CN_MAP 分词逻辑)
+    words = set()
+    q_lower = query.lower()
+    words.add(q_lower)
+    # 中文分词: 用 cn_map 拆
+    if cn_map:
+        remaining = query
+        for cn in sorted(cn_map.keys(), key=len, reverse=True):
+            if cn in remaining:
+                for en in cn_map[cn].split():
+                    words.add(en.lower())
+                remaining = remaining.replace(cn, ' ')
+        # 剩余英文片段
+        for frag in remaining.split():
+            if frag and frag.isascii():
+                words.add(frag.lower())
+    # 中文整段也加
+    for m in re.finditer(r'[\u4e00-\u9fff]{2,}', query):
+        words.add(m.group())
+
+    # 搜索: 子串匹配, 标题命中优先 (TF 排序)
+    scored = []  # (score, entry)
+    seen_titles = set()
+    for kw, entries in wiki_idx.items():
+        kw_lower = kw.lower()
+        for word in words:
+            if word in kw_lower or kw_lower in word:
+                for entry in entries:
+                    key = (entry.get('project'), entry.get('title'))
+                    if key in seen_titles:
+                        continue
+                    # 打分: 标题命中 = 10分, 描述命中 = 5分, 依赖文件命中 = 1分
+                    title = (entry.get('title') or '').lower()
+                    desc = (entry.get('description') or '').lower()
+                    score = 0
+                    if word in title or title in word:
+                        score = 10
+                    elif word in desc:
+                        score = 5
+                    else:
+                        score = 1  # 依赖文件命中
+                    if score > 0:
+                        seen_titles.add(key)
+                        scored.append((score, entry))
+                break
+
+    # 按分数降序
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return [entry for _, entry in scored[:15]]

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

@@ -64,6 +64,37 @@ CN_MAP = {
     '分类': 'category classify', '类型': 'type',
     '地区': 'region area', '区域': 'zone region',
     '时间': 'time date', '日期': 'date',
+    # 异常/品质/合规 (高频但之前缺失, 导致"异常记录"搜不到)
+    '异常': 'abnormal anomaly exception', '故障': 'fault error failure',
+    '报警': 'alarm alert warning', '违规': 'violation breach',
+    '合规': 'compliance', '风险': 'risk hazard',
+    '处理': 'handle process deal', '反馈': 'feedback',
+    # 筛选/查询 (PRD 高频, "新增筛选条件"类需求)
+    '筛选': 'filter search', '过滤': 'filter',
+    '搜索': 'search query', '查询': 'query search find',
+    '条件': 'condition filter criteria',
+    '排序': 'sort order', '分组': 'group',
+    # 页面/交互
+    '列表': 'list table', '详情': 'detail info',
+    '弹窗': 'modal dialog popup', '抽屉': 'drawer',
+    '表单': 'form', '表格': 'table grid',
+    '看板': 'dashboard board panel', '大屏': 'screen monitor dashboard',
+    '图表': 'chart graph', '柱状图': 'bar chart',
+    '饼图': 'pie chart', '折线图': 'line chart',
+    # 项目类型/业务对象 (本次需求触发)
+    '项目类型': 'projectType project type',
+    '业务对象': 'business object entity',
+    # 导入导出增强
+    '上传': 'upload import', '下载': 'download export',
+    '打印': 'print', '预览': 'preview',
+    # 人员/身份增强
+    '人员': 'person personnel staff user',
+    '负责人': 'owner manager charge',
+    '驾驶员': 'driver',
+    # 地图/位置
+    '地图': 'map gis',
+    '位置': 'location position gps',
+    '轨迹': 'track trajectory gps',
 }
 
 # Chinese business term -> code path/identifier patterns.
@@ -120,6 +151,15 @@ BUSINESS_PATH_MAP = {
     '消息': ['message', 'Message', 'notify', 'Notify'],
     '配置': ['config', 'Config', 'setting', 'Setting'],
     '字典': ['dict', 'Dict', 'dictionary', 'Dictionary'],
+    # 异常/品质/合规 (新增, 解决"异常记录"搜不到)
+    '异常': ['abnormal', 'Abnormal', 'anomaly', 'Anomaly', 'exception', 'Exception'],
+    '故障': ['fault', 'Fault', 'error', 'Error', 'failure', 'Failure'],
+    '合规': ['compliance', 'Compliance'],
+    '看板': ['dashboard', 'Dashboard', 'board', 'Board', 'panel', 'Panel'],
+    '大屏': ['screen', 'Screen', 'monitor', 'Monitor', 'dashboard'],
+    '地图': ['map', 'Map', 'gis', 'GIS'],
+    '轨迹': ['track', 'Track', 'trajectory', 'gps', 'GPS'],
+    '筛选': ['filter', 'Filter', 'search', 'Search'],
 }
 
 # Chinese term -> single primary English keyword (derived from CN_MAP).
@@ -178,8 +218,8 @@ PRD_STOP_WORDS = {
     '以及', '如果', '那么', '但是', '因为', '所以', '用户', '系统', '页面', '数据',
     '信息', '操作', '管理', '列表', '详情', '新增', '修改', '删除', '查询', '搜索',
     '筛选', '点击', '选择', '输入', '确认', '取消', '保存', '提交', '返回', '跳转',
-    '当前', '前端', '后端', '影响', '范围', '下拉', '条件', '字段', '全部', '异常',
-    '正常', '记录', '面板', '统计', '表页', '搜索表', '与其他', '表单', '背景',
+    '当前', '前端', '后端', '影响', '范围', '下拉', '条件', '字段', '全部',
+    '正常', '面板', '统计', '表页', '搜索表', '与其他', '表单', '背景',
     '一个', '这个', '那个', '通过', '根据', '按照', '同时', '并且',
     '要求', '需求', '描述', '说明', '备注', '注意', '重要', '优先', '级别',
     '方案', '设计', '开发', '测试', '上线', '版本', '迭代', '更新', '发布',

package/templates/qoder/scripts/context_pack.py

@@ -247,19 +247,43 @@ def _compute_and_print(query, platform, page_type):
     print('- 模板: .qoder/templates/prototype-web.html / prototype-app.html')
     print('- PRD 模板: .qoder/templates/prd-full-template.md / prd-quick-template.md')
 
-    # ---- 7. Repo Wiki ----
-    wikis = []
-    if os.path.isdir(os.path.join(BASE, '.qoder', 'repowiki')):
-        wikis.append('.qoder/repowiki/')
+    # ---- 7. Repo Wiki (语义级模块文档, 优先参考) ----
     code_dir = os.path.join(BASE, 'data', 'code')
+    wiki_results = []
+    try:
+        from common.repowiki import search_wiki, build_wiki_index
+        from common.terms import get_cn_map_with_auto
+        wiki_idx_path = os.path.join(INDEX_DIR, 'wiki-index.json')
+        if not os.path.isfile(wiki_idx_path):
+            build_wiki_index(code_dir, wiki_idx_path)
+        cn_map = get_cn_map_with_auto()
+        wiki_results = search_wiki(query, INDEX_DIR, code_dir, cn_map)
+    except Exception:
+        pass
+
+    # 也列出 wiki 目录 (供手动浏览)
+    wiki_dirs = []
+    if os.path.isdir(os.path.join(BASE, '.qoder', 'repowiki')):
+        wiki_dirs.append('.qoder/repowiki/')
     if os.path.isdir(code_dir):
         for p in sorted(os.listdir(code_dir)):
             if os.path.isdir(os.path.join(code_dir, p, '.qoder', 'repowiki')):
-                wikis.append('data/code/{}/.qoder/repowiki/'.format(p))
-    if wikis:
-        print('\n## 7. Repo Wiki 可用 (模块级文档, 优先参考)')
-        for w in wikis:
-            print('- ' + w)
+                wiki_dirs.append('data/code/{}/.qoder/repowiki/'.format(p))
+
+    if wiki_results or wiki_dirs:
+        print('\n## 7. Repo Wiki (语义级模块文档, 比源码更精准)')
+        if wiki_results:
+            print('  相关模块文档 ({} 条, 带行号引用, 优先读这些):'.format(len(wiki_results)))
+            for i, wr in enumerate(wiki_results[:5], 1):
+                print('  {}. [{}] {}'.format(i, wr.get('project','?'), wr.get('title','')))
+                if wr.get('dependent_files'):
+                    print('     核心文件: ' + ', '.join(wr['dependent_files'][:2]))
+                if wr.get('md_path'):
+                    print('     文档: ' + os.path.relpath(wr['md_path'], BASE))
+        elif wiki_dirs:
+            print('  Wiki 可用但无精确匹配, 手动浏览:')
+            for w in wiki_dirs:
+                print('  - ' + w)
 
 
 if __name__ == '__main__':

package/templates/qoder/scripts/git_sync.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
 Weekly Knowledge Graph Update
@@ -1053,6 +1053,25 @@ def main():
         if not (sync_only or prd_only):
             verify_result = verify_indexes(config)
 
+        # Step 5.6: Build Repo Wiki index (Qoder IDE 生成的语义级模块文档)
+        if not (sync_only or prd_only):
+            try:
+                from common.repowiki import build_wiki_index, find_repowiki_dirs
+                code_dir = os.path.join(BASE, 'data', 'code')
+                wiki_dirs = find_repowiki_dirs(code_dir)
+                if wiki_dirs:
+                    print('\n=== Building Wiki Index (Repo Wiki 语义图谱) ===')
+                    out = os.path.join(INDEX_DIR, 'wiki-index.json')
+                    r = build_wiki_index(code_dir, out)
+                    if isinstance(r, dict) and r.get('stats'):
+                        s = r['stats']
+                        print('  Wiki: {} 项目 / {} 模块文档 / {} 关键词'.format(
+                            s.get('projects',0), s.get('pages',0), s.get('keywords',0)))
+                else:
+                    print('\n=== Wiki Index: 无 Repo Wiki (可选, Qoder IDE 生成后自动纳入) ===')
+            except Exception as e:
+                print('  [WARN] Wiki index build failed (不阻塞): {}'.format(str(e)[:80]))
+
         # 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:

package/templates/qoder/scripts/search_index.py

@@ -78,7 +78,82 @@ def _search_cache_key(query, platform):
     return hashlib.md5(raw.encode('utf-8')).hexdigest()[:16]
 
 
+def _check_index_freshness():
+    """轻量检查索引是否过期 (代码改了但索引没更新)。
+
+    抽样 data/code/ 下最新修改的文件, 与 .index-meta.json 的 last_sync 比。
+    过期则打印提示 (不阻塞搜索)。
+    用一个静默文件标记避免每次搜索都提示 (.runtime/.index-stale-warned)。
+    """
+    try:
+        import datetime as _dt
+        meta_path = os.path.join(BASE, 'data', 'index', '.index-meta.json')
+        if not os.path.isfile(meta_path):
+            return
+        with open(meta_path, encoding='utf-8') as f:
+            meta = json.load(f)
+        last_sync_str = meta.get('last_sync', '')
+        if not last_sync_str:
+            return
+        last_sync = _dt.datetime.strptime(last_sync_str, '%Y-%m-%d %H:%M')
+
+        # 抽样: 找 data/code/ 下最新修改的 .java/.vue/.js 文件 (只扫一层子目录的最近文件)
+        code_dir = os.path.join(BASE, 'data', 'code')
+        if not os.path.isdir(code_dir):
+            return
+        newest_mtime = 0
+        for proj in os.listdir(code_dir):
+            proj_dir = os.path.join(code_dir, proj)
+            if not os.path.isdir(proj_dir):
+                continue
+            # 只看 src 目录下的文件 (避免 .git 干扰)
+            src_dir = os.path.join(proj_dir, 'src')
+            if not os.path.isdir(src_dir):
+                continue
+            # 抽样: os.walk 只走一层 (限制深度), 找最新 mtime
+            for root, dirs, files in os.walk(src_dir):
+                # 限制深度: 只走 3 层 (够采样, 不全扫)
+                depth = root[len(src_dir):].count(os.sep)
+                if depth >= 3:
+                    dirs[:] = []
+                    continue
+                for fn in files:
+                    if fn.endswith(('.java', '.vue', '.js', '.ts')):
+                        try:
+                            mt = os.path.getmtime(os.path.join(root, fn))
+                            if mt > newest_mtime:
+                                newest_mtime = mt
+                        except OSError:
+                            pass
+                if newest_mtime > 0:
+                    break  # 拿到一个项目的最新就够了
+
+        if newest_mtime <= 0:
+            return
+        newest_dt = _dt.datetime.fromtimestamp(newest_mtime)
+        # 过期判定: 代码文件比索引新超过 1 小时
+        if (newest_dt - last_sync).total_seconds() > 3600:
+            # 静默标记: 避免每次搜索都提示 (索引更新后标记自动失效)
+            warned_path = os.path.join(BASE, '.qoder', '.runtime', '.index-stale-warned')
+            warn_mtime = os.path.getmtime(warned_path) if os.path.isfile(warned_path) else 0
+            meta_mtime = os.path.getmtime(meta_path)
+            if warn_mtime > meta_mtime:
+                return  # 已经提示过了 (在本次索引周期内)
+            print('[提示] 代码有更新但知识图谱未刷新 (上次索引: %s)' % last_sync_str)
+            print('  刷新: python .qoder/scripts/git_sync.py --index-only')
+            try:
+                os.makedirs(os.path.dirname(warned_path), exist_ok=True)
+                open(warned_path, 'w').close()
+            except OSError:
+                pass
+    except Exception:
+        pass  # 新鲜度检查失败不阻塞搜索
+
+
 def search_keywords(query, platform=None):
+    # 新鲜度检查 (代码改了但索引没更新 → 提示, 不阻塞)
+    _check_index_freshness()
+
     # 结果缓存: 同 query+platform+索引未变 → 直接返回缓存输出
     cache_key = _search_cache_key(query, platform)
     cache_path = os.path.join(BASE, '.qoder', '.runtime', 'search-cache-%s.txt' % cache_key)
@@ -114,6 +189,53 @@ def search_keywords(query, platform=None):
         pass
 
 
+def _expand_chinese_query(query):
+    """把中文查询拆成英文搜索词。
+
+    三级匹配:
+      1. 精确匹配: "异常" 在 CN_MAP → 直接扩展
+      2. 分词匹配: "异常记录" → 拆成 "异常" + "记录", 各自扩展
+         (贪心最长匹配: 从长到短扫 CN_MAP 的 key)
+      3. 兜底: 拆不出来的部分, 原样小写 (让英文子串索引做匹配)
+
+    同时合并 BUSINESS_PATH_MAP 的路径模式。
+    """
+    words = []
+    # 合并 CN_MAP + PRD 自动扩展
+    try:
+        from common.terms import get_cn_map_with_auto
+        cn_map = get_cn_map_with_auto()
+    except ImportError:
+        cn_map = CN_MAP
+
+    # 1. 精确匹配
+    if query in cn_map:
+        words.extend(cn_map[query].split())
+    if query in BUSINESS_PATH_MAP:
+        words.extend(p.strip('/-').lower() for p in BUSINESS_PATH_MAP[query])
+
+    # 2. 分词匹配 (查询比单个 CN_MAP key 长 → 需要拆词)
+    if not words and len(query) >= 3:
+        # 贪心最长匹配: 把 CN_MAP keys 按长度降序排, 逐个从 query 里找
+        remaining = query
+        matched_segments = []
+        for cn in sorted(cn_map.keys(), key=len, reverse=True):
+            if cn in remaining:
+                matched_segments.append(cn)
+                remaining = remaining.replace(cn, ' ')
+        if matched_segments:
+            for seg in matched_segments:
+                words.extend(cn_map[seg].split())
+                if seg in BUSINESS_PATH_MAP:
+                    words.extend(p.strip('/-').lower() for p in BUSINESS_PATH_MAP[seg])
+            # 剩余的英文/数字片段也加进去 (兜底)
+            for frag in remaining.split():
+                if frag and frag.isascii():
+                    words.append(frag.lower())
+
+    return words
+
+
 def _search_keywords_impl(query, platform=None):
     """实际的搜索逻辑 (原 search_keywords 内容)。"""
     ki = load_index('keyword-index.json', hint='Run: python git_sync.py')
@@ -121,11 +243,7 @@ def _search_keywords_impl(query, platform=None):
         return
 
     # Expand Chinese query via the shared term maps (same maps used at build time)
-    words = []
-    if query in CN_MAP:
-        words.extend(CN_MAP[query].split())
-    if query in BUSINESS_PATH_MAP:
-        words.extend(p.strip('/-').lower() for p in BUSINESS_PATH_MAP[query])
+    words = _expand_chinese_query(query)
     if words:
         words = sorted(set(w.lower() for w in words))
         print('Chinese: {} -> English: {}'.format(query, ' '.join(words)))
@@ -346,6 +464,52 @@ def show_vben():
         print()
 
 
+def search_wiki_cli(query):
+    """搜 Repo Wiki (Qoder IDE 生成的语义级模块文档)。"""
+    try:
+        from common.repowiki import search_wiki, build_wiki_index
+        from common.terms import get_cn_map_with_auto
+    except ImportError:
+        print('Wiki 搜索不可用 (common.repowiki 模块缺失)')
+        return
+
+    cn_map = get_cn_map_with_auto()
+    code_dir = os.path.join(BASE, 'data', 'code')
+    index_dir = os.path.join(BASE, 'data', 'index')
+
+    # 自动构建 wiki 索引 (若不存在)
+    wiki_idx_path = os.path.join(index_dir, 'wiki-index.json')
+    if not os.path.isfile(wiki_idx_path):
+        print('[构建] 首次使用, 正在从 Repo Wiki 构建语义索引...')
+        r = build_wiki_index(code_dir, wiki_idx_path)
+        if isinstance(r, dict) and r.get('stats'):
+            s = r['stats']
+            print('  完成: {} 项目 / {} 模块文档 / {} 关键词\n'.format(
+                s.get('projects',0), s.get('pages',0), s.get('keywords',0)))
+        else:
+            print('  未找到 Repo Wiki (data/code/*/.qoder/repowiki/)')
+            print('  在 Qoder IDE 里对项目生成 Repo Wiki 后可用')
+            return
+
+    results = search_wiki(query, index_dir, code_dir, cn_map)
+    if not results:
+        print('No wiki pages match: {}'.format(query))
+        return
+
+    print('Wiki pages matching: {} ({} found)\n'.format(query, len(results)))
+    for i, r in enumerate(results, 1):
+        print('  {}. [{}] {}'.format(i, r.get('project','?'), r.get('title','')))
+        if r.get('dependent_files'):
+            deps = r['dependent_files'][:3]
+            print('     依赖: ' + ', '.join(deps[:2]))
+            if len(r['dependent_files']) > 2:
+                print('          (共 {} 个文件)'.format(len(r['dependent_files'])))
+        if r.get('md_path'):
+            rel = os.path.relpath(r['md_path'], BASE)
+            print('     文档: ' + rel)
+    print('\n  提示: 读 wiki 文档 (带行号引用) 比读源码更省 token')
+
+
 def print_usage():
     print('Usage:')
     print('  search_index.py <keyword> [--platform web|app]  - Search code')
@@ -354,6 +518,7 @@ def print_usage():
     print('  search_index.py --field <name>                 - Field usage')
     print('  search_index.py --api <keyword>                - API endpoints')
     print('  search_index.py --components                   - UI components')
+    print('  search_index.py --wiki <keyword>               - Repo Wiki 语义模块文档 (精准)')
     print('  search_index.py --modules                      - Project overview')
     print('  search_index.py --list                         - Top 50 keywords')
     print('  search_index.py --vben                         - Vben design tokens')
@@ -382,6 +547,8 @@ if __name__ == '__main__':
         search_field(args[1])
     elif args[0] == '--api' and len(args) >= 2:
         search_api(args[1])
+    elif args[0] == '--wiki' and len(args) >= 2:
+        search_wiki_cli(args[1])
     elif args[0] == '--components':
         show_components()
     elif args[0] == '--modules':