@hupan56/wlkj 2.2.6 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "2.2.6",
+  "version": "2.3.1",
   "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,300 @@
+# -*- 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), ...]。
+
+    健壮性: repowiki 目录可能存在但为空/损坏/正在生成中。
+    只返回 metadata 文件存在且非空的目录。
+    """
+    results = []
+    if not os.path.isdir(code_dir):
+        return results
+    try:
+        projects = os.listdir(code_dir)
+    except OSError:
+        return results
+    for proj in projects:
+        try:
+            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)
+                if not os.path.isdir(lang_dir):
+                    continue
+                meta = os.path.join(lang_dir, 'meta', 'repowiki-metadata.json')
+                if not os.path.isfile(meta):
+                    continue
+                # 校验文件非空 (生成中可能写出 0 字节文件)
+                try:
+                    if os.path.getsize(meta) < 10:
+                        continue  # 太小, 可能正在生成
+                except OSError:
+                    continue
+                results.append((proj, lang_dir))
+                break  # 每个项目只取一个语言版本
+        except OSError:
+            continue  # 权限/路径问题, 跳过这个项目
+    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:
+        if not os.path.isfile(meta_path):
+            return None
+        if os.path.getsize(meta_path) < 10:
+            return None  # 正在生成或空
+        with open(meta_path, encoding='utf-8') as f:
+            data = json.load(f)
+        # 校验基本结构
+        if not isinstance(data, dict):
+            return None
+        # wiki_catalogs 可能为空 (生成中)
+        if not data.get('wiki_catalogs'):
+            return None  # 没有内容, 视为无效
+        return data
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        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:
+        {'index': {...}, 'stats': {...}} 或 {'index': {}, 'stats': {...}}
+        始终返回含 'index' 和 'stats' 两个 key 的 dict (调用方可安全 .get)。
+        wiki 不存在/为空/损坏时 index 为 {}, stats 计数为 0。
+    """
+    index = {}  # keyword -> [entry, ...]
+    stats = {'projects': 0, 'pages': 0, 'keywords': 0}
+
+    wiki_dirs = find_repowiki_dirs(code_dir)
+    if not wiki_dirs:
+        # wiki 不存在或都损坏 → 写空索引, 避免每次搜索都重建
+        _write_wiki_index(output_path, index, stats)
+        return {'index': index, 'stats': stats}
+
+    for project, wiki_root in wiki_dirs:
+        try:
+            meta = load_wiki_metadata(wiki_root)
+            if not meta:
+                continue  # 这个项目的 wiki 损坏/为空, 跳过
+            stats['projects'] += 1
+
+            catalogs = meta.get('wiki_catalogs') or []
+            items = meta.get('wiki_items') or []
+            # catalog_id -> title 映射
+            id_to_title = {}
+            for it in items:
+                if isinstance(it, dict):
+                    cid = it.get('catalog_id')
+                    if cid:
+                        id_to_title[cid] = it.get('title', '')
+
+            for cat in catalogs:
+                try:
+                    if not isinstance(cat, dict):
+                        continue
+                    cat_id = cat.get('id', '')
+                    name = cat.get('name', '') or ''
+                    desc = cat.get('description', '') or ''
+                    dep_files = cat.get('dependent_files', '') or ''
+                    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([str(title), str(name), str(desc)])
+                    if dep_files:
+                        kw_text += ' ' + str(dep_files).replace(',', ' ').replace('/', ' ')
+                    keywords = _extract_keywords(kw_text)
+
+                    entry = {
+                        'project': project,
+                        'title': str(title or name),
+                        'catalog_id': str(cat_id),
+                        'md_path': md_path,
+                        'dependent_files': [f.strip() for f in str(dep_files).split(',') if f.strip()],
+                        'description': str(desc),
+                    }
+
+                    for kw in keywords:
+                        index.setdefault(kw, [])
+                        if entry not in index[kw]:
+                            index[kw].append(entry)
+                except (OSError, TypeError, ValueError):
+                    continue  # 单条 catalog 出错不影响其他
+        except (OSError, TypeError):
+            continue  # 整个项目的 wiki 出错, 跳过
+
+    stats['keywords'] = len(index)
+    _write_wiki_index(output_path, index, stats)
+    return {'index': index, 'stats': stats}
+
+
+def _write_wiki_index(output_path: str, index: dict, stats: dict) -> None:
+    """安全写入 wiki-index.json (best-effort, 失败不崩)。"""
+    try:
+        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)
+    except OSError:
+        pass
+
+
+def _find_md_for_catalog(wiki_root: str, catalog_id: str, name: str) -> Optional[str]:
+    """在 content/ 目录下找对应的 markdown 文件。
+
+    文件名通常等于 catalog name (.md), 在某个子分类目录下。
+    健壮性: name 为空/content 目录不存在时返回 None。
+    """
+    if not name:
+        return None
+    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/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

@@ -464,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')
@@ -472,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')
@@ -500,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':