BlueRose/BlueRoseNote

Fork 0

Files

BlueRose a507664f3e vault backup: 2026-05-31 14:42:42

2026-05-31 14:42:42 +08:00

20 KiB

Raw Blame History

title, date, tags, aliases

title

date

前言

视频
- 🚀AI编程工作流终极形态：GitNexus！零Token消耗实现代码知识图谱化！让Claude Code和Codex拥有上帝视角彻底告别盲目改代码，效率倍增

Setup

安装：
- npm install -g gitnexus
- gitnexus setup
操作命令
- 分析代码
  - npx gitnexus analyze
  - gitnexus analyze --embeddings --skills --verbose
- 启动MCP服务器:gitnexus serve
- ClaudeCode
  - CLI
    - /gitnexus-cli
    - /gitnexus-debugging
    - /gitnexus-exploring:理解代码架构。
  - Hook
    - PreToolUse
    - PostToolUse
  - MCP:claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

提高索引速度

[!tip] 适用场景大内存 + 多核 CPU 的机器（如 64GB RAM + 32 逻辑处理器），索引超大仓库（UE 引擎数百万行 C++）时使用以下优化参数。

优化参数速查

# 环境变量（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 (引擎源码，索引中)

Q&A

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 的实际决策流程：

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...

引擎类前缀短且通用，项目类前缀长且带业务含义

更优方案：预构建符号→仓库映射表

可以写一个脚本，每次索引完成后生成映射文件：

# 扫描所有仓库，输出 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 恰好同名） ← 误匹配！

具体步骤

# 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

# .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

# 3. 同步
npx gitnexus group sync @ue5-aidm

[!note] 引擎只索引一次所有项目的 group.yaml 指向同一个引擎路径，引擎重新索引后所有 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 代劳了这一步。

多项目管理速查

操作	命令
新项目加入	`analyze` → 创建 `group.yaml` → `group sync`
引擎更新	`analyze`（引擎目录），所有 Group 自动生效
项目间隔离	每个项目独立 Group，不交叉污染

实战经验：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/<hash>/，需要 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/<name>/group.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
  # ... 列出全部

二、常用命令行

# === 单模块索引（Windows）===
cd D:\UnrealEngine\UE_5.7\Engine\Source\Runtime\<ModuleName>
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/<GroupName>/group.yaml (version: 1, name, repos mapping)
# 2. MCP: group_sync({name: "<GroupName>"})
# 3. 使用: query/context/impact 传 repo: "@<GroupName>"

三、数据分享：如何让他人使用已索引数据

分享步骤

打包 .gitnexus/ 目录（每个模块一个）：

# 在 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"
    }
}

分享注册表：%USERPROFILE%\.gitnexus\registry.json
分享 Group 配置：%USERPROFILE%\.gitnexus\groups\ 目录

接收方操作

解压各模块 .gitnexus/ 到对应目录
将 registry.json 放到 %USERPROFILE%\.gitnexus\
将 groups/ 放到 %USERPROFILE%\.gitnexus\groups\
重启 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: "<symbol>", repo: "@UE5-Engine-Runtime", direction: "upstream"})`
- 执行流程追踪: `query({query: "<concept>", repo: "@UE5-Engine-Runtime"})`
- 符号上下文: `context({name: "<symbol>", 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，预计数小时

检索优先级

1. 领域 Group（如 @UE5-Engine）→ 2. 功能组 repo（如 Gameplay）→ 3. 单模块 repo（如 Engine）→ 4. grep 兜底

模块合并方案：188 模块 → 11 功能组

方案总览

组名	文件数	模块数	预计耗时
Core	2,063	1	2-4h
Engine	3,934	1	4-10h
Gameplay	2,874	53	2-4h
Rendering	1,962	30	1-2h
UI	1,194	10	30-60min
AudioSignal	623	21	15-30min
MediaMovieScene	1,209	17	30-60min
Networking	1,214	13	30-60min
PhysicsAnimation	916	20	30-60min
Platform	493	17	10-20min
Experimental	1,397	1	1-2h

各组包含模块

Core (2063 files)

Core

Engine (3934 files)

Engine

Gameplay (2874 files, 53 模块)

CoreUObject, ApplicationCore, AppFramework, Launch, Projects, Serialization
Json, JsonUtilities, XmlParser, Cbor, CoreOnline, CorePreciseFP
TypedElementFramework, TypedElementRuntime, FieldNotification, UniversalObjectLocator
TraceLog, DeveloperSettings, BuildSettings, EngineSettings
AIModule, NavigationSystem, GameplayTasks, GameplayTags, GameplayDebugger
Navmesh, MassEntity, StateStream, GameMenuBuilder
Analytics, AutomationMessages, AutomationTest, AutomationWorker
StorageServerClient, StorageServerClientDebug, RuntimeAssetCache, InstallBundleManager
PakFile, SessionServices, SessionMessages, Messaging, MessagingCommon, MessagingRpc
PreLoadScreen, FriendsAndChat, EngineMessages, CrashReportCore, Instrumentation
StudioTelemetry, PerfCounters, ClientPilot, ExternalRPCRegistry, Portal
OodleDataCompression, SandboxFile, StreamingFile, StreamingPauseRendering
CookOnTheFly, MoviePlayerProxy, NullInstallBundleManager, BlueprintRuntime
PlatformThirdPartyHelpers, CUDA, RSA, PropertyPath, AutoRTFM, AssetRegistry
UELibrary, UnrealGame, NNE, Toolbox, SymsLib, VerseCompiler, MathCore, Linux

Rendering (1962 files, 30 模块)

Renderer, RenderCore, RHI, RHICore, D3D12RHI, VulkanRHI, OpenGLDrv
NullDrv, ColorManagement, OpenColorIOWrapper
Datasmith, Interchange, MeshDescription, MeshConversion, MeshConversionEngineTypes
StaticMeshDescription, SkeletalMeshDescription, MeshUtilitiesCommon, RawMesh
ImageCore, ImageWrapper, ImageWriteQueue, TextureUtilitiesCommon
IESFile, MaterialShaderQualitySettings, SynthBenchmark

UI (1194 files, 10 模块)

Slate, SlateCore, UMG, SlateRHIRenderer, AdvancedWidgets
SlateNullRenderer, WidgetCarousel, InputCore, InputDevice

AudioSignal (623 files, 21 模块)

AudioMixer, AudioMixerCore, AudioExtensions, AudioAnalyzer, AudioLink
AudioCaptureCore, AudioCaptureImplementations, AudioDeviceEnumeration
AudioPlatformConfiguration, AudioPlatformSupport, RadAudioCodec
BinkAudioDecoder, SignalProcessing, SoundFieldRendering
NonRealtimeAudioRenderer, OpusAudioDecoder, VorbisAudioDecoder
AdpcmAudioDecoder, UEJpegComp, UEWavComp

MediaMovieScene (1209 files, 17 模块)

Media, MediaAssets, MediaUtils, MoviePlayer, MoviePlayerProxy
MovieScene, MovieSceneCapture, MovieSceneTracks, AVEncoder, AVIWriter
LevelSequence, TimeManagement, Overlay, GameplayMediaEncoder
CinematicCamera, LiveLinkInterface, LiveLinkAnimationCore
LiveLinkMessageBusFramework

Networking (1214 files, 13 模块)

Online, Net, Networking, NetworkReplayStreaming, NetworkFile
NetworkFileSystem, Sockets, WebBrowser, WebBrowserTexture
PacketHandlers, IPC, CEF3Utils, RewindDebuggerRuntimeInterface

PhysicsAnimation (916 files, 20 模块)

PhysicsCore, GeometryCore, GeometryFramework, AnimationCore
AnimGraphRuntime, Landscape, Foliage
ClothingSystemRuntimeInterface, ClothingSystemRuntimeCommon, ClothingSystemRuntimeNv
VectorVM, InteractiveToolsFramework, AugmentedReality

Platform (493 files, 17 模块)

Apple, Android, IOS, Linux, Windows, Unix, Solaris
EyeTracker, HeadMountedDisplay, VirtualProduction, HardwareSurvey
InputDevice, MRMesh, Advertising

Experimental (1397 files)

Experimental

20 KiB Raw Blame History Unescape Escape

前言