vault backup: 2026-05-28 18:41:41

2026-05-28 18:41:41 +08:00
parent 09bcdadf62
commit 50d9b02b65
3 changed files with 445 additions and 239 deletions
--- a/Agent/UnrealEngine/GitNexus
+++ b/Agent/UnrealEngine/GitNexus
@@ -1,3 +1,15 @@
+---
+title: GitNexus 知识图谱
+date: 2026-05-28
+tags:
+  - ai-agent
+  - knowledge-graph
+  - gitnexus
+  - ue5
+aliases:
+  - GitNexus
+  - 代码知识图谱
+---
 # 前言
 - 视频
 	- [🚀AI编程工作流终极形态：GitNexus！零Token消耗实现代码知识图谱化！让Claude Code和Codex拥有上帝视角彻底告别盲目改代码，效率倍增](https://www.bilibili.com/video/BV1vy9XBrExq/?share_source=copy_web&vd_source=fe8142e8e12816535feaeabd6f6cdc8e)
@@ -19,4 +31,198 @@
 		- Hook
 			- PreToolUse
 			- PostToolUse
-		- MCP:`claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp`
+		- MCP:`claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp`
+
+## 提高索引速度
+
+> [!tip] 适用场景
+> 大内存 + 多核 CPU 的机器（如 64GB RAM + 32 逻辑处理器），索引超大仓库（UE 引擎数百万行 C++）时使用以下优化参数。
+
+### 优化参数速查
+```powershell
+# 环境变量（PowerShell）
+$env:NODE_OPTIONS="--max-old-space-size=32768"
+$env:UV_THREADPOOL_SIZE="16"
+$env:GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES="67108864"
+
+# 分析命令
+npx gitnexus analyze `
+  --embeddings 0 `
+  --max-file-size 1024 `
+  --skip-agents-md --skip-skills --skip-git `
+  -v
+```
+
+### 参数详解
+
+| 参数 | 默认值 | 优化值 | 作用 |
+|------|--------|--------|------|
+| `NODE_OPTIONS=--max-old-space-size` | 4GB | ==32GB== | Node 堆上限，大内存减少 GC 停顿 |
+| `UV_THREADPOOL_SIZE` | 4 | ==16== | libuv I/O 线程池，加速文件读取 |
+| `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` | 8MB | ==64MB== | 每 worker 批次更大，减少调度开销 |
+| `--max-file-size` | 512KB | ==1024KB== | 允许索引更大头文件（UE 很多 `.h` >512KB） |
+| `--embeddings 0` | 启用 | ==0== | 关闭 embedding 生成，节省内存和 CPU |
+
+> [!note] Worker 线程数
+> GitNexus 内部自动使用 `os.cpus()` 个 worker 线程解析文件，无需手动配置。
+> 32 个逻辑处理器 = ==32 个并行 worker==。
+
+> [!warning] 注意
+> `--max-old-space-size` 不要超过物理可用内存的 50%，留余量给 OS 和其他进程。
+
+# 跨仓库引用解析
+GitNexus MCP 是 ==单实例多仓库== 架构，一个 MCP Server 自动服务所有已索引仓库。
+```
+gitnexus MCP (单实例)
+  ├── AIDM (项目代码，59K symbols)
+  ├── UE_5.7 (引擎源码，索引中)
+```
+
+---
+
+## Q1：Claude Code 怎么知道查哪个仓库？
+> [!important] 核心问题
+> GitNexus MCP **没有** "搜索所有仓库" 的全局查询能力。每个查询必须指定 `repo` 参数。
+> CC 不会自动知道 `AActor` 在 AIDM 还是 UE_5.7——它需要靠规则判断。
+
+### 当前机制：命名约定 + 试探查询
+GitNexus 仓库之间是**互相隔离**的。验证结果：
+
+| 查询 | repo | 结果 |
+|------|------|------|
+| `context({name: "URPGAttributeComponent"})` | AIDM | ==找到==，5 个匹配 |
+| `context({name: "AActor"})` | AIDM | ==找不到==（引擎 API 不在项目索引中） |
+| `query({query: "AActor BeginPlay"})` | AIDM | ==无结果==（FTS 也查不到） |
+
+**CC 的实际决策流程：**
+
+```mermaid
+graph TD
+    A[收到符号查询任务] --> B{符号名称模式?}
+    B -->|"U/A/F前缀 + 非项目自有"| C[尝试 repo: UE_5.7]
+    B -->|"RPG/Celpec/LWS 等已知项目前缀"| D[尝试 repo: AIDM]
+    B -->|"无法判断"| E[先查 AIDM]
+    E -->|未找到| C
+    E -->|找到| F[使用 AIDM 结果]
+    C -->|未找到| G[告知用户符号未索引]
+    C -->|找到| H[使用引擎结果]
+    D --> F
+```
+
+> [!tip] 命名约定是最实用的判据
+> - **引擎符号**：`UObject`、`AActor`、`FVector`、`TArray`、`UActorComponent`...
+> - **项目符号**：`URPGAttributeComponent`、`ULWSWorldGenerator`、`CelpecTalent`...
+> - 引擎类前缀短且通用，项目类前缀长且带业务含义
+
+### 更优方案：预构建符号→仓库映射表
+
+可以写一个脚本，每次索引完成后生成映射文件：
+
+```bash
+# 扫描所有仓库，输出 symbol → repo 映射
+npx gitnexus list --json | jq -r '.[] | "\(.name): \(.symbols)"'
+```
+
+CC 读取这个映射表就能精确路由。这是一次性开销，可以放入 CLAUDE.md 或 hook 中。
+
+---
+
+## Q2：多个项目共用一个引擎，Group 怎么配？
+### 推荐方案：每个项目独立 Group
+假如你有 3 个项目都基于 UE_5.7：
+
+```
+UE_5.7 (引擎，公共)
+  ├── AIDM (修仙 MMORPG)
+  ├── ProjectB (另一个游戏)
+  └── ProjectC (第三个项目)
+```
+
+**为每个项目独立创建 Group：**
+```
+@ue5-aidm     → { UE_5.7, AIDM }
+@ue5-projectb → { UE_5.7, ProjectB }
+@ue5-projectc → { UE_5.7, ProjectC }
+```
+
+> [!warning] 不要把所有项目放进一个 Group
+> 如果 `@ue5-all` 包含所有项目，在 AIDM 上做 impact 分析会 fan-out 到 ProjectB/ProjectC 的符号，造成**跨项目污染**。
+
+### 为什么不能一个引擎 Group 被多个项目引用？
+Group 的 `group_sync` 是**显式的**——它把 Group 内所有仓库的 IMPORTS/EXTENDS 边做精确匹配并建立桥接。如果把三个项目放进一个 Group：
+- `URPGAttributeComponent`（AIDM）→ `UActorComponent`（引擎） ← 正确
+- `USomeManager`（AIDM）→ `USomeManager`（ProjectB 恰好同名） ← **误匹配！**
+
+### 具体步骤
+```bash
+# 1. 索引引擎（一次性，所有项目共享）
+cd D:\UnrealEngine\UE_5.7\Engine\Source
+npx gitnexus analyze --skip-agents-md --skip-skills --skip-git --embeddings 0
+
+# 2. 每个项目索引 + 创建 group.yaml
+cd D:\MatrixTA\AIGameDev\AIDM
+npx gitnexus analyze
+```
+
+```yaml
+# .gitnexus/group.yaml
+repos:
+  aidm:
+    path: D:\MatrixTA\AIGameDev\AIDM
+  engine:
+    path: D:\UnrealEngine\UE_5.7\Engine\Source
+links:
+  - type: extends
+    from: aidm
+    to: engine
+```
+
+```bash
+# 3. 同步
+npx gitnexus group sync @ue5-aidm
+```
+
+> [!note] 引擎只索引一次
+> 所有项目的 `group.yaml` 指向同一个引擎路径，引擎重新索引后所有 Group 自动更新。
+
+### 多项目管理速查
+
+| 操作 | 命令 |
+|------|------|
+| 新项目加入 | `analyze` → 创建 `group.yaml` → `group sync` |
+| 引擎更新 | `analyze`（引擎目录），所有 Group 自动生效 |
+| 项目间隔离 | 每个项目独立 Group，不交叉污染 |
+
+---
+
+## Q3：有了 Group，Q1 的问题是不是可以更简单地解决？
+**是的。** Group 从根本上改变了 Q1 的路由方式。
+
+### 没有 Group（Q1 的困境）
+```
+CC 收到 "查 AActor" → 猜引擎 → 指定 repo: "UE_5.7"
+CC 收到 "查 URPGAttributeComponent" → 猜项目 → 指定 repo: "AIDM"
+猜错了 → 重试另一个仓库 → 浪费 token 和时间
+```
+
+### 有了 Group（Q3 的解决方案）
+```
+CC 收到任何查询 → repo: "@ue5-aidm"
+GitNexus 自动跨仓库搜索 → 返回结果（注明了来自哪个仓库）
+```
+
+> [!tip] Group 是统一命名空间
+> `context({name: "AActor", repo: "@ue5-aidm"})` → 引擎侧找到
+> `context({name: "URPGAttributeComponent", repo: "@ue5-aidm"})` → 项目侧找到
+>
+> **CC 不再需要猜测符号属于哪个仓库。** 始终用 Group 名查询即可。
+
+### 更新后的路由规则
+有了 Group，CLAUDE.md 路由可以简化为：
+```
+1. 任何符号查询 → 始终用 repo: "@ue5-aidm"
+2. impact 分析 → repo: "@ue5-aidm"（自动 fan-out 引擎继承链）
+3. 业务意图/设计文档 → Graphify
+```
+
+**Q1 中复杂的"先查 AIDM → 未找到 → 查引擎"试探逻辑完全不需要了。** Group 让 GitNexus 代劳了这一步。