diff --git a/07-Other/AI/AI Agent/UnrealEngine/GitNexus 知识图谱.md b/07-Other/AI/AI Agent/UnrealEngine/GitNexus 知识图谱.md index 51e3958..4f6e0a3 100644 --- a/07-Other/AI/AI Agent/UnrealEngine/GitNexus 知识图谱.md +++ b/07-Other/AI/AI Agent/UnrealEngine/GitNexus 知识图谱.md @@ -225,4 +225,190 @@ GitNexus 自动跨仓库搜索 → 返回结果（注明了来自哪个仓库） 3. 业务意图/设计文档 → Graphify ``` -**Q1 中复杂的"先查 AIDM → 未找到 → 查引擎"试探逻辑完全不需要了。** Group 让 GitNexus 代劳了这一步。 \ No newline at end of file +**Q1 中复杂的"先查 AIDM → 未找到 → 查引擎"试探逻辑完全不需要了。** Group 让 GitNexus 代劳了这一步。 + +--- + +## 实战经验：UE5.7 引擎全模块索引 + +### 一、遇到的坑与规避方法 + +#### 坑 1：Windows V8 地址空间崩溃（最严重） + +**症状**：`npx gitnexus analyze` 在 scope extraction 完成后崩溃，报 `v8::base::AddressSpaceReservation` 错误，exit code 134。无论设多大 `--max-old-space-size` 都无法解决。 + +**根因**：Windows 上 V8 引擎的 code space 有 ~4GB 上限。当解析文件过多（>15K C++ 文件）时，V8 内部函数对象超出地址空间，crash。这不是 RAM 不足，是 V8 架构限制。 + +**规避**： +- **单模块分析**：不要对 ~22K 文件的完整 Runtime 目录运行。拆成单个模块分别 analyze +- **WSL2 + Linux Node.js**：Linux V8 无此限制。WSL 内安装原生 Linux Node.js（不能用 `/mnt/c/` 的 Windows 版），`wsl bash -c "cd /mnt/d/... && NODE_OPTIONS='--max-old-space-size=30720' gitnexus analyze ..."` +- 单模块文件数建议 < 5K 文件 + +#### 坑 2：大模块 graph 构建极慢 + +**症状**：Core（2048 文件）/ Engine（3905 文件）graph 构建耗时 2-10 小时，100% CPU 单核满载。 + +**根因**：GitNexus graph 构建是单线程 Node.js 主线程执行，O(n²) 级别的符号关系计算。UE5 C++ 代码符号密度极高，关系连接极复杂。 + +**规避**： +- **大模块（>500 文件）用 WSL + 30GB heap**：`NODE_OPTIONS='--max-old-space-size=30720'` +- **小模块（<500 文件）用默认 heap 并行跑**：Windows 上直接多进程并行 +- **分批串行策略**：每个 batch 内 4-5 个模块串行（避免 npm cache 冲突），多个 batch 间并行 + +#### 坑 3：`--embeddings` 模型下载失败 + +**症状**：带 `--embeddings` 运行时，进程 100% CPU 空转数小时无输出。不带则正常。 + +**根因**：GitNexus 使用 `Snowflake/snowflake-arctic-embed-xs` 模型（~90MB），从 HuggingFace 下载。国内网络 CDN 被墙导致下载挂起。 + +**规避**： +- **方案 A：HF 镜像**（推荐）——`export HF_ENDPOINT=https://hf-mirror.com` 后运行 +- **方案 B：本地缓存**——手动下载模型文件到 `~/.cache/huggingface/hub/models--Snowflake--snowflake-arctic-embed-xs/snapshots//`，需要 content-addressed blobs + symlinks + - 关键文件：`onnx/model.onnx`（90MB）、`config.json`、`tokenizer.json`、`tokenizer_config.json`、`special_tokens_map.json` + - 注意 Windows 需要 Developer Mode 或 admin 权限才能创建 symlink，否则用硬拷贝 +- **方案 C**：修改 `embedder.js` 中 `env.allowLocalModels = true`（原始值 `false`） + +#### 坑 4：并行分析时的 npm cache 冲突 + +**症状**：同时启动 20 个 `npx gitnexus analyze`，全部静默失败。 + +**根因**：npx 在并行进程间竞争 `%LOCALAPPDATA%\npm-cache\_npx\` 目录。 + +**规避**：同一批最多 3-4 个并行 `npx`，或使用全局安装的 `gitnexus` 命令替代 `npx`。串行批内用 `for d in ...; do ...; done` 逐个执行。 + +#### 坑 5：Group 创建踩坑 + +**症状**：`group_sync` 报告全部 repos 为 `missingRepos`。 + +**根因**：`missingRepos` 是 API contract 匹配的状态，不影响代码检索功能。Group 的 `query`、`context`、`impact` 在创建后立即可用。 + +**正确 Group 格式**（`~/.gitnexus/groups//group.yaml`）： +```yaml +version: 1 +name: UE5-Engine-Runtime +description: UE5.7 Engine Runtime all modules +repos: + AIModule: D:\UnrealEngine\UE_5.7\Engine\Source\Runtime\AIModule + Core: D:\UnrealEngine\UE_5.7\Engine\Source\Runtime\Core + # ... 列出全部 +``` + +### 二、常用命令行 + +```bash +# === 单模块索引（Windows）=== +cd D:\UnrealEngine\UE_5.7\Engine\Source\Runtime\ +npx gitnexus analyze --force --skip-git --skip-agents-md --skip-skills + +# === 单模块索引 + embedding（Windows + 镜像）=== +export HF_ENDPOINT=https://hf-mirror.com +npx gitnexus analyze --force --skip-git --skip-agents-md --skip-skills --embeddings + +# === 大模块索引（WSL + 30GB heap）=== +wsl bash -c "cd /mnt/d/UnrealEngine/UE_5.7/Engine/Source/Runtime/Engine && NODE_OPTIONS='--max-old-space-size=30720' gitnexus analyze --force --skip-git --skip-agents-md --skip-skills" + +# === 检查索引状态 === +npx gitnexus status + +# === 列出所有已索引仓库 === +# 通过 MCP: mcp__gitnexus__list_repos +# 或查看注册表: cat ~/.gitnexus/registry.json + +# === 跨模块查询（Group 模式）=== +# 通过 MCP query 工具: repo: "@UE5-Engine-Runtime" + +# === 创建 Group === +# 1. 生成 ~/.gitnexus/groups//group.yaml (version: 1, name, repos mapping) +# 2. MCP: group_sync({name: ""}) +# 3. 使用: query/context/impact 传 repo: "@" +``` + +### 三、数据分享：如何让他人使用已索引数据 + +#### 分享步骤 + +1. **打包 `.gitnexus/` 目录**（每个模块一个）： + ```powershell + # 在 D:\UnrealEngine\UE_5.7\Engine\Source\Runtime\ 执行 + foreach ($d in Get-ChildItem -Directory) { + if (Test-Path "$d\.gitnexus") { + Compress-Archive -Path "$d\.gitnexus" -DestinationPath "D:\share\$d-gitnexus.zip" + } + } + ``` + +2. **分享注册表**：`%USERPROFILE%\.gitnexus\registry.json` + +3. **分享 Group 配置**：`%USERPROFILE%\.gitnexus\groups\` 目录 + +#### 接收方操作 + +1. 解压各模块 `.gitnexus/` 到对应目录 +2. 将 `registry.json` 放到 `%USERPROFILE%\.gitnexus\` +3. 将 `groups/` 放到 `%USERPROFILE%\.gitnexus\groups\` +4. 重启 Claude Code 使 MCP server 重新加载 registry + +#### 给 AI Agent 用的提示词 + +在项目的 `CLAUDE.md` 或 `AGENTS.md` 中添加： + +``` +## GitNexus 知识图谱 + +本项目的 GitNexus 知识图谱包含 UE5.7 引擎全部 Runtime 模块索引（188 个模块）。 + +### 检索规则 +- 代码搜索始终使用 Group 模式: `repo: "@UE5-Engine-Runtime"` +- 单模块查询可指定: `repo: "AIModule"` +- 影响分析: `impact({target: "", repo: "@UE5-Engine-Runtime", direction: "upstream"})` +- 执行流程追踪: `query({query: "", repo: "@UE5-Engine-Runtime"})` +- 符号上下文: `context({name: "", repo: "@UE5-Engine-Runtime"})` + +### 索引覆盖 +- 188 个 UE5.7 Runtime 模块（~863K 符号，~446K embedding 向量） +- AIDM 游戏项目（~59K 符号） + +### 限制 +- 无 GPU embedding（CPU-only），部分模块无 embeddings +- FTS 索引可能不完整（大索引构建时会降级） +``` + +### 四、UE 引擎源码检索策略 + +#### 模块拆分建议 + +| 模块规模 | 文件数 | 建议 | +|---------|--------|------| +| **小** | < 100 | 合并为一个 group 统一 analyze（如 `SmallModules`） | +| **中** | 100-500 | 单独 analyze，Windows 并行跑 | +| **大** | 500-2000 | 单独 analyze，建议 WSL + 大 heap | +| **超大** | > 2000 | 必须 WSL + 30GB heap，预计数小时 | + +#### 推荐 Group 结构 + +不要把所有 188 模块放一个 flat group——按功能域分组更高效： + +```yaml +# ~/.gitnexus/groups/UE5-Gameplay/group.yaml +repos: + AIModule: ... + NavigationSystem: ... + GameplayTasks: ... + GameplayTags: ... + Engine: ... + Core: ... + CoreUObject: ... + +# ~/.gitnexus/groups/UE5-All/group.yaml (总 Group) +repos: + # 所有 188 模块 +``` + +日常开发用 `@UE5-Gameplay`（小且精准），全局搜索用 `@UE5-All`（大且全）。 + +#### 检索优先级 + +同一页面上给检索工具一个优先级： +``` +1. 当前模块 repo → 2. 领域 Group → 3. 全局 Group → 4. grep 兜底 +``` \ No newline at end of file