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

07-Other/AI/AI Agent/UnrealEngine/GitNexus 知识图谱.md

@@ -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)
@@ -20,3 +32,197 @@
 			- PreToolUse
 			- PostToolUse
 		- 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 代劳了这一步。

07-Other/AI/AI Agent/UnrealEngine/Graphify 知识图谱.md

@@ -1,6 +1,19 @@
+---
+title: Graphify 知识图谱
+date: 2026-05-28
+tags:
+  - ai-agent
+  - knowledge-graph
+  - graphify
+  - gitnexus
+  - ue5
+aliases:
+  - Graphify
+  - 知识图谱工具
+---
 # 前言
 - https://github.com/safishamsi/graphify
-- 安装:pip install graphifyy && graphify install
+- 安装: `pip install graphifyy`，然后 `graphify claude install`（注册到 Claude Code）
 
 **一个面向 AI 编码助手的技能。** 在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 `/graphify`，它会读取你的文件、构建知识图谱，并把原本不明显的结构关系还给你。更快理解代码库，找到架构决策背后的"为什么"。
 
@@ -9,32 +22,21 @@
 > Andrej Karpathy 会维护一个 `/raw` 文件夹，把论文、推文、截图和笔记都丢进去。graphify 就是在解决这类问题 —— 相比直接读取原始文件，每次查询的 token 消耗可降低 **71.5 倍**，结果还能跨会话持久保存，并且会明确区分哪些内容是实际发现的，哪些只是合理推断。
 
 # 安装
+
 ## 平台支持
 
-| 平台            | 安装命令                                   |
-| ------------- | -------------------------------------- |
-| Claude Code   | `graphify install`                     |
-| Codex         | `graphify install --platform codex`    |
-| OpenCode      | `graphify install --platform opencode` |
-| OpenClaw      | `graphify install --platform claw`     |
-| Factory Droid | `graphify install --platform droid`    |
-| Trae          | `graphify install --platform trae`     |
-| Trae CN       | `graphify install --platform trae-cn`  |
+安装 graphify Python 包：
 
-Codex 用户还需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，这样才能并行提取。OpenClaw 目前的并行 agent 支持还比较早期，所以使用顺序提取。Trae 使用 Agent 工具进行并行子代理调度，**不支持** PreToolUse hook，因此 AGENTS.md 是其常驻机制。
-
-然后打开你的 AI 编码助手，输入：
-
-```
-/graphify .
+```bash
+pip install graphifyy
+# 或
+uv tool install graphifyy
 ```
 
-## 让助手始终优先使用图谱（推荐）
+然后使用对应平台命令将技能注册到 AI 助手：
 
-图构建完成后，在项目里运行一次：
-
-| 平台 | 命令 |
-|------|------|
+| 平台 | 注册命令 |
+|------|----------|
 | Claude Code | `graphify claude install` |
 | Codex | `graphify codex install` |
 | OpenCode | `graphify opencode install` |
@@ -43,23 +45,45 @@ Codex 用户还需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `mult
 | Trae | `graphify trae install` |
 | Trae CN | `graphify trae-cn install` |
 
-**Claude Code** 会做两件事：
-1. 在 `CLAUDE.md` 中写入一段规则，告诉 Claude 在回答架构问题前先读 `graphify-out/GRAPH_REPORT.md`
-2. 安装一个 **PreToolUse hook**（写入 `settings.json`），在每次 `Glob` 和 `Grep` 前触发
+> [!tip] 平台差异
+> - **Codex** 用户需要在 `~/.codex/config.toml` 的 `[features]` 下打开 `multi_agent = true`，才能并行提取
+> - **OpenClaw** 并行 agent 支持较早期，使用顺序提取
+> - **Trae** 使用 Agent 工具进行并行子代理调度，==不支持== PreToolUse hook，AGENTS.md 是其常驻机制
 
-如果知识图谱存在，Claude 会先看到：_"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."_ —— 这样 Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。
+然后打开 AI 编码助手，输入：
 
-**Codex、OpenCode、OpenClaw、Factory Droid、Trae** 会把同样的规则写进项目根目录的 `AGENTS.md`。这些平台没有 PreToolUse hook，所以 `AGENTS.md` 是它们的常驻机制。
+```
+/graphify .
+```
 
-卸载时使用对应平台的 uninstall 命令即可（例如 `graphify claude uninstall`）。
+## 让助手始终优先使用图谱（推荐）
 
-**常驻模式和显式触发有什么区别？**
+图构建完成后，在项目里运行对应平台的 install 命令（见上表）。
 
-常驻 hook 会优先暴露 `GRAPH_REPORT.md` —— 这是一页式总结，包含 god nodes、社区结构和意外连接。你的助手在搜索文件前会先读它，因此会按结构导航，而不是按关键字乱搜。这已经能覆盖大部分日常问题。
+**Claude Code** 上会做两件事：
 
-`/graphify query`、`/graphify path` 和 `/graphify explain` 会更深入：它们会逐跳遍历底层 `graph.json`，追踪节点之间的精确路径，并展示边级别细节（关系类型、置信度、源位置）。当你想从图谱里精确回答某个问题，而不仅仅是获得整体感知时，就该用这些命令。
+1. 在 `CLAUDE.md` 中写入规则，告诉 Claude 在回答架构问题前先读 `graphify-out/GRAPH_REPORT.md`
+2. 安装 **PreToolUse hook**（写入 `settings.json`），在每次 `Glob` 和 `Grep` 前触发
 
-可以这样理解：常驻 hook 是先给助手一张地图，`/graphify` 这几个命令则是让它沿着地图精确导航。
+> [!quote] Hook 提示效果
+> *"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."*
+>
+> Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。
+
+> [!info] 其他平台
+> **Codex、OpenCode、OpenClaw、Factory Droid、Trae** 把同样规则写入 `AGENTS.md`。这些平台没有 PreToolUse hook，AGENTS.md 是其常驻机制。
+
+卸载时使用对应平台的 uninstall 命令（如 `graphify claude uninstall`）。
+
+## 常驻模式 vs 显式触发
+
+> [!important] 常驻 hook
+> 优先暴露 `GRAPH_REPORT.md` —— 一页式总结，包含 ==god nodes==、==社区结构== 和 ==意外连接==。助手在搜索文件前会先读它，按结构导航而非按关键字搜索。覆盖大部分日常问题。
+
+`/graphify query`、`/graphify path` 和 `/graphify explain` 会更深入：逐跳遍历底层 `graph.json`，追踪节点间精确路径，展示边级别细节（关系类型、置信度、源位置）。适合精确回答特定问题。
+
+> [!abstract] 一句话理解
+> 常驻 hook ==先给助手一张地图==，`/graphify` 命令则 ==让助手沿着地图精确导航==。
 
 <details>
 <summary>手动安装（curl）</summary>
@@ -160,166 +184,114 @@ graphify trae-cn uninstall
 Token 压缩效果会随着语料规模增大而更明显。6 个文件本来就塞得进上下文窗口，所以 graphify 在这种场景里的价值更多是结构清晰度，而不是 token 压缩。到了 52 个文件（代码 + 论文 + 图片）这种规模，就能做到 71x+。每个 `worked/` 目录里都带了原始输入和真实输出（`GRAPH_REPORT.md`、`graph.json`），你可以自己跑一遍核对数字。
 
 # 针对UE开发的使用方式
-### 具体的实施路线图
-1. **安装 Graphify 并配置 ClaudeCode 技能：** 在你的项目根目录运行：
-```
-graphify install  # 自动向 CLAUDE.md 注入架构索引规则
-/graphify .      # 生成初始代码图
-```
-2. **编写 `CLAUDE.md` 引导：** 在项目根目录创建或修改 `CLAUDE.md`：
-> **Architecture Context:** Always read `graphify-out/GRAPH_REPORT.md` before answering architecture questions. **UE Standards:** Follow Unreal Engine 5.x coding standards (PascalCase, U-Prefixes).
-3. **开发 MCP 插件：** 如果你有能力，实现一个简单的 MCP Server，能够通过命令行搜索 UE 的 `Reflection Database`。
 
-### 总结建议
-- **如果你追求立即理解代码逻辑：** 优先配置 **Graphify**。它能让 Claude 从“逐行看代码”进化到“看地图写代码”。
-- **如果你在进行长期复杂的特性开发：** 引入 **Graphiti** 作为 Claude 的“开发日志”，防止它忘记你之前的架构决策。
+## 核心结论
 
----
+> [!warning] Graphify ==不适合==索引 UE 引擎源码
+> 引擎数百万行 C++ + 海量宏（`UCLASS()`、`GENERATED_BODY()`），LLM 语义提取成本极高且不精确。
+>
+> **引擎源码 → [[GitNexus 知识图谱|GitNexus]]**（Tree-sitter AST，无 LLM 成本）
 
-# 具体执行方案
----
+**Graphify 的正确定位：项目业务层的宏观语义图谱。**
 
-实现这一方案的关键在于将 `graphify` 从一个“傻瓜式扫描器”转变为一个“受控的提取引擎”。针对 Unreal Engine 的庞大规模，我们需要通过精确的路径控制和排除规则来实施。
+索引范围：
+- 项目 C++ 业务代码（`Source/`）
+- 设计文档和规范（`.trae/documents/`、`.trae/specs/`）
+- 策划案和架构说明（Markdown）
+- 排除所有编译产物、第三方插件、UE 配置/资产
 
-以下是具体的执行方法与命令：
-### 1\. 离线构建 Engine 基础图谱 (The Static Atlas)
+## 实际配置（已验证 ✅）
 
-由于引擎源码几乎不变量，我们只需构建一次。
+### 1. 创建 `.graphifyignore`
 
-**执行策略：** 只索引 `Public` 接口，忽略所有实现（`.cpp` ）和私有目录。
-**具体命令：**
-```
-# 进入引擎 Source 目录
-cd /d D:/UnrealEngine/UE_5.7/Engine/Source
+> [!important] .graphifyignore 是唯一的排除机制
+> 排除规则通过 `.graphifyignore` 控制（==gitignore 语法==）。**不存在** `--include`、`--ignore`、`--output`、`index` 等 CLI 参数 —— 这些都是虚构的。
 
-claude --dangerously-skip-permissions
+```gitignore
+# UE 编译产物
+Binaries/
+Intermediate/
+Saved/
+DerivedDataCache/
+Build/
 
-# 执行 graphify 扫描
-# --include: 仅包含 Public 文件夹下的头文件，这是剪枝的核心
-# --ignore: 排除掉极其庞大的第三方库和中间件
-/graphify index . \
-  --output D:/MatrixTA/AIGameDev/AIDM0/Docs/Graphify/UE5.7_Header.graph \
-  --include "**/Public/**/*.h" \
-  --ignore "ThirdParty/**,Developer/**,Programs/**,Intermediate/**,**/Private/**" 
+# UE 配置和资产（非代码）
+Config/
+Content/
+
+# 第三方插件
+Plugins/LogicDriver/
+Plugins/UnrealImGui/
+# ... 等
+
+# AI 工具配置（非项目内容）
+.kilocode/
+.trae/skills/
+.trae/plans/
+.trae/.obsidian/
 ```
 
-**提示：** 这一步在 M1 Ultra 上可能仍需数十分钟。建议通过 `--max-depth` 限制继承链的抓取深度，通常设置为 5 已经能覆盖 90% 的关键基类（如 `UObject` -> `AActor` -> `APawn` -> `ACharacter` ）。
+### 2. 构建图谱
 
----
-
-### 2\. ~~针对 UE 的“剪枝”策略配置文件~~
-
-为了避免长命令，建议在项目根目录创建一个 `.graphifyconfig` (或工具支持的配置文件)。
-
-**精细化剪枝逻辑：**
-
-- **反射优先：** 重点提取带有 `GENERATED_BODY()` 的类。
-- **模块白名单：** 如果你主要做游戏逻辑，只包含以下核心模块：
-	- `Runtime/Engine`
-		- `Runtime/Core`
-		- `Runtime/CoreUObject`
-		- `Runtime/InputCore`
-
-**自动化剪枝脚本示例 (Python)：** 如果你发现 `graphify` 无法过滤细碎路径，可以用这个脚本生成一个“干净”的临时符号链接目录供其索引：
-```python
-import os
-from pathlib import Path
-
-source_dir = Path("/Users/Shared/Epic Games/UE_5.4/Engine/Source/Runtime")
-target_dir = Path("./UE_Thin_Source")
-
-# 仅挑选核心模块的 Public 目录建立软链接
-core_modules = ['Engine', 'Core', 'CoreUObject', 'RenderCore']
-
-for module in core_modules:
-    pub_path = source_dir / module / "Public"
-    if pub_path.exists():
-        os.makedirs(target_dir / module, exist_ok=True)
-        os.symlink(pub_path, target_dir / module / "Public")
-```
-
-然后对 `UE_Thin_Source` 运行 `/graphify` 。
-
----
-
-### 3\. 实时构建 Project 业务图谱 (The Dynamic Layer)
-业务代码变动频繁，需要更轻量、更高频的更新。
-**执行命令：**
-```
-# 在你的项目根目录执行，排除插件和中间文件
-/graphify index ./Source \
-  --output ./project_current.graph \
-  --ignore "**/Intermediate/**,**/Binaries/**" \
-  --watch
-```
-
-**进阶：结合 ClaudeCode 的 `CLAUDE.md`** 在项目根目录的 `CLAUDE.md` 中添加指令，让 Claude 意识到有两个图谱存在：
-```
-### Knowledge Graph Context
-- **Static Engine Graph:** \`~/ue_engine_full.graph\` (Read-only, contains UE5 API)
-- **Project Graph:** \`./project_current.graph\` (Updated on save, contains business logic)
-- **Rule:** When a class is prefixed with 'U' or 'A' and not in Project Graph, query Engine Graph via \`mcp-graph-tool\`.
-```
-
-#### C++ & Puerts代码图谱
 ```bash
-# 同时指定项目路径和外部引擎路径
-# TODO:添加Index Plugins
-/graphify index ./Source ./TypeScript \
-  --output ./Docs/Graphify/Project/Project.graph \
-  --include "*.cpp,*.h,*.hpp,*.ts" \
-  --ignore "**/Intermediate/**,**/ThirdParty/**"
+/graphify . --directed --no-viz
 ```
 
-#### 增量更新模式（逻辑合并 - 推荐方案）
-这是最符合工程实践的方法。先建立基础图谱，再将其他目录的内容“追随”进去。`graphify` 的 `--update` 标志会自动处理节点冲突并合并新的关系。
+- `--directed`：构建有向图（保留 source → target 方向）
+- `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
+- 输出固定到 `graphify-out/`，**不存在** `--output` 参数
+
+### 3. 安装常驻规则
 
-**执行命令：**
 ```bash
-# 第一步：索引引擎（静态基础）
-/graphify index /path/to/ue_engine/Source/Runtime \
-  --output ./ue_workspace.graph \
-  --include "**/Public/**/*.h"
-
-# 第二步：将项目目录合并到同一个图谱中
-/graphify index ./MyProject/Source \
-  --output ./ue_workspace.graph \
-  --update  # 关键参数：在现有图谱基础上合并
+graphify claude install
 ```
 
+在 `CLAUDE.md` 中写入规则 + 注册 PreToolUse hook，让 CC 优先用图谱导航而非盲搜 grep。
 
+### 4. 增量更新
 
+```bash
+/graphify . --update    # 只重新提取变更文件，合并到已有图谱
+```
 
----
+## 双图谱架构（Graphify + GitNexus）
 
-### 4\. 实施 Multi-Graph 挂载的 MCP 方案
-要让 ClaudeCode 真正理解这两个图谱，你需要一个简单的 MCP Server 来做中转。
+| 工具 | 索引目标 | 技术 |
+|------|----------|------|
+| **Graphify** | 项目业务层：设计文档、模块架构、策划案 | LLM 语义 + AST |
+| **GitNexus** | 项目 + 引擎符号层：C++ 类继承、函数调用链 | Tree-sitter AST |
 
-**开发建议：**
-1. **加载：** 启动时同时 Load 两个 `.graph` 文件到内存。
-2. **查询逻辑：**
-	```
-	async function searchClass(className) {
-	  // 1. 先查项目图谱
-	  let result = projectGraph.find(className);
-	  if (!result) {
-	    // 2. 如果没找到，且符合 UE 命名规范，查引擎图谱
-	    result = engineGraph.find(className);
-	  }
-	  return result;
-	}
-	```
+### 引擎源码（一次性索引）
 
-### 总结执行清单：
-1. **环境准备：** 确定 UE 引擎路径。
-2. **首次索引：** 使用上述“剪枝命令”生成 `ue_engine_full.graph` ，存放在家目录作为持久缓存。
-3. **项目配置：** 在项目内运行带有 `--watch` 的 `graphify` 。
-4. **注入 Claude：** 编写 MCP Server 将两个图谱的查询接口暴露给 ClaudeCode。
+```bash
+cd D:\UnrealEngine\UE_5.7\Engine\Source
+npx gitnexus analyze --skip-agents-md --skip-skills
+```
 
-这种“重引擎索引 + 轻业务监控”的模式，能保证在 64GB 内存的本地环境下，ClaudeCode 既能秒回 API 调用问题，又能深刻理解你的业务代码耦合。你想尝试编写这个 MCP 路由器的代码吗？
+> [!note] 下载版引擎
+> 下载版引擎无 `.git`，不需要 `--skip-git`；源码克隆版需要去掉此参数。
+
+GitNexus MCP 单实例自动服务所有已索引仓库，通过 `repo` 参数区分目标。
+
+### CLAUDE.md 路由优先级
+```mermaid
+graph TD
+    A[收到任务] --> B{需要什么信息?}
+    B -->|业务意图/模块关系| C[Graphify]
+    B -->|精确符号/调用链| D[GitNexus AIDM]
+    B -->|引擎底层 API| E[GitNexus UE Engine]
+    B -->|设计文档/规范| F[Graphify 社区]
+```
+
+> [!tip] 当前状态（2026-05-28）
+> - Graphify AIDM：==4,168 nodes · 5,427 edges · 532 communities==
+> - GitNexus AIDM：==59,371 symbols · 106,882 edges · 300 flows==
+> - GitNexus UE Engine：索引中（`npx gitnexus analyze` 后台运行）
 
 
 # 其他项目用命令行
+
 ## AssetMaker
 ### Graphify
 #### 前置条件
@@ -356,12 +328,12 @@ pip install watchdog
 # 指定目录
 /graphify D:\AI\Website\CharacterMaker --directed --no-viz
 ```
-
 - `--directed`：构建有向图（保留边方向）
 - `--no-viz`：跳过 HTML 可视化，只生成 GRAPH_REPORT.md + graph.json
-- 输出位置：`D:\AI\Website\CharacterMaker\graphify-out\`
-- **注意**：`--output` 不是有效 flag，graphify 固定输出到项目根目录的 `graphify-out/`
-- **注意**：`--ignore` 不是有效 flag，排除规则一律通过 `.graphifyignore` 文件控制
+
+> [!warning] 常见误区
+> - `--output` ==不是有效 flag==，graphify 固定输出到项目根目录的 `graphify-out/`
+> - `--ignore` ==不是有效 flag==，排除规则一律通过 `.graphifyignore` 文件控制
 
 #### watch 模式（文件变更时自动更新图谱）
 Claude Code 中运行（通过 skill 调度）：
@@ -373,5 +345,3 @@ Claude Code 中运行（通过 skill 调度）：
 ```powershell
 python -m graphify.watch D:\AI\Website\CharacterMaker --debounce 3
 ```
-
-## GitNexus

07-Other/AI/AI Agent/UnrealEngine/UnrealEngine Hardness Game Development.md

@@ -69,85 +69,115 @@
 
 # 知识图谱
 
-为了**杜绝 CC 盲目调用 `cat`、`grep` 读取原始大文件**，你必须在项目根目录下创建 `.claude_rules` 或 `.claudecode.json`，强制注入以下系统指令（System Prompt）：
+| 工具 | 层级 | 职责 | 技术 |
+|------|------|------|------|
+| **Graphify** | 宏观语义层 | 设计文档、模块架构、策划案、跨文件概念关系 | LLM 语义提取 + AST |
+| **GitNexus** | 微观符号层 | C++ 类继承、函数调用链、符号精确定位 | Tree-sitter AST（无 LLM 成本） |
+
+- **Graphify 不适合索引 UE 引擎源码**：引擎源码（`Engine/Source`）数百万行 C++ + 海量宏（`UCLASS()`、`GENERATED_BODY()`），Graphify 的 LLM 语义提取会极其昂贵且不精确。**引擎源码唯一指定 GitNexus。**
+- **GitNexus 不适合设计文档**：GitNexus 基于 Tree-sitter 解析代码 AST，不处理 Markdown/策划文档的语义关系。**设计文档唯一指定 Graphify。**
+
+## 实际配置方案
+### Step 1：GitNexus 索引 UE 引擎源码（一次性）
+```bash
+cd D:\UnrealEngine\UE_5.7\Engine\Source
+npx gitnexus analyze --skip-agents-md --skip-skills --skip-git
+```
+
+- `--skip-agents-md`：避免在引擎目录生成 CLAUDE.md
+- `--skip-git`：引擎目录可能不是独立 git 仓库
+- 引擎代码是静态的，索引一次即可，无需日常更新
+- GitNexus MCP 会**自动发现**新索引的仓库（单实例服务所有仓库）
+
+### Step 2：Graphify 索引项目业务层
+```bash
+# 1. 创建 .graphifyignore（排除引擎、编译产物、第三方插件）
+# 2. 构建知识图谱
+/graphify . --directed --no-viz
+```
+
+`.graphifyignore` 关键排除项：
+```gitignore
+# UE 编译产物
+Binaries/
+Intermediate/
+Saved/
+DerivedDataCache/
+Build/
+
+# UE 配置和资产（非代码）
+Config/
+Content/
+
+# 第三方插件
+Plugins/LogicDriver/
+Plugins/UnrealImGui/
+# ... 等
+
+# AI 工具配置（非项目内容）
+.kilocode/
+.trae/skills/
+.trae/plans/
+```
+
+保留的索引目标：
+- `Source/`：项目 C++ 业务代码
+- `Plugins/CelpecTalent/`、`Plugins/RPGGameCore/` 等：项目自有插件
+- `.trae/documents/`、`.trae/specs/`：设计文档和规范
+
+### Step 3：CLAUDE.md 路由规则
 ```markdown
-# Claude Code 行为准则 - 虚幻引擎双栈项目
-## 1. 核心原则：图谱优先 (Graph-First Execution)
-- 严禁直接使用 `cat`、`view_file`、`grep` 或 `find` 作为你探索代码库、规划功能或调试 Bug 的第一步。
-- 面对任何任务，你必须**首先**调用 `gitnexus-project` 或 `gitnexus-ue-engine` 获取依赖关系、符号定义与调用拓扑。
-- 只有在你通过图谱精准锁定了需要修改或深入阅读的“手术切片（Code Slice）”时，才允许对该特定文件使用直接读取命令。
+## Architecture-Aware Routing
 
-## 2. 结合 Graphify 宏观地图
-- 优先读取项目根目录下的 `graphify` 摘要信息（`graph.html` 对应的结构或本地生成的报告），理解模块耦合和设计意图，再深入 GitNexus 的微观 AST。
-
-## 3. 引擎与项目上下文隔离
-- 当查询虚幻引擎原生 API（如 `AActor`, `UObject`, `FRHICommandList`）或探索引擎底层实现时，必须唯一调用 `gitnexus-ue-engine`。
-- 当查询项目业务逻辑、游戏模式、数据资产或 Puerts 脚本时，必须唯一调用 `gitnexus-project`。
-
-## 4. Puerts (TS) 与 C++ 双栈跳转链路
-- 本项目采用 Puerts 架构。TypeScript 中的 `UE.X` 映射到 C++ 中的 `AX` 或 `UX`。
-- 如果你在处理 TS 逻辑时遇到架构瓶颈，请通过 `gitnexus-project` 查询 `Typing/ue/index.d.ts` 中对应的符号。利用该声明文件作为桥梁，切换到 C++ 图谱节点进行互查。
+1. 理解业务意图 → Graphify（graphify-out/graph.json）
+2. 精确符号查询 → GitNexus AIDM 仓库
+3. 引擎底层 API → GitNexus UE Engine 仓库
+4. 设计文档/规范 → Graphify 社区标注
 ```
 
-## GitNexus
-针对引擎与项目的gitnexus图谱：
-```json
-{
-  "mcpServers": {
-    "gitnexus-project": {
-      "command": "node",
-      "args": ["/path/to/gitnexus/cli.js", "serve", "--cwd", "/path/to/YourUEProject"]
-    },
-    "gitnexus-ue-engine": {
-      "command": "node",
-      "args": ["/path/to/gitnexus/cli.js", "serve", "--cwd", "/path/to/UnrealEngine/Engine/Source"]
-    }
-  }
-}
+### MCP 配置说明
+**不需要修改 MCP 配置。** GitNexus MCP 是单实例多仓库架构：
 ```
-### C++ 与 Puerts (TypeScript) 双栈桥接
-Puerts 通过生成器会将 UE 的 C++ 类反射为 TypeScript 声明文件（通常位于 `YourProject/Typing/ue/index.d.ts`）。
-- **图谱配置**：确保 `gitnexus-project` 的配置文件（`.gitnexus.json`）将 `Typing/` 目录和你的 TS 脚本目录（如 `TS/` 或 `Content/JavaScript/`）同时纳入索引。
-- **作用机制**：借由 Tree-sitter-typescript，GitNexus 会将 TS 中的 `UE.AActor` 关系链导向 `index.d.ts`，让 CC 从 TypeScript 跳跃回 C++ 原生符号。
-
-## Graphify
-在你的虚幻项目根目录下，开启 Graphify 的守护进程：
-```bash
-# 启动 Graphify 实时监听项目文件、设计文档和编译输出元数据
-graphify . --watch --exclude "Binaries/,DerivedDataCache/,Intermediate/"
+现有 MCP 实例（gitnexus）
+  ├── AIDM（项目代码，59K symbols）
+  ├── UE_5.7（引擎源码，索引中）
+  └── 其他已索引仓库
 ```
 
-这将持续更新本地的知识拓扑，特别是当你修改了 Puerts 的 TS 逻辑或新增了 Markdown 规划文档时，Graphify 会自动建立反向链接（Backlinks）。
+通过 `repo` 参数区分目标：
+- 查项目代码：`gitnexus_context({name: “URPGAttributeComponent”, repo: “AIDM”})`
+- 查引擎源码：`gitnexus_context({name: “AActor”, repo: “UE_5.7”})`
 
-#### 编写胶水脚本让 CC 读取 Graphify
-由于 Graphify 会生成结构化的持久化数据，你可以写一个简单的 CLI 胶水工具（或作为 CC 可以运行的命令）让 CC 能快捷检索 Graphify 的宏观节点：
-```bash
-# 创建一个名为 query_macro.sh 的工具供 CC 调用
-# 用法: ./query_macro.sh "Puerts 战斗系统设计"
-cat .graphify/nodes.json | grep -i "$1" 
-```
+## 实施计划
+### 阶段 1：功能规划期 (Planning)
+**任务**：新增一个技能释放组件，调用 C++ 底层属性系统（AttributeSet）。
 
-### 实施计划
-#### 阶段 1：功能规划期 (Planning)
-- **任务**：你想在 Puerts 脚本中新增一个技能释放组件，并调用 C++ 写的底层属性系统（AttributeSet）。
-- **CC 的自动决策**：
-    1. CC 遵循规则，不盲读文件。首先调用 Graphify 相关的宏观图谱，查看现有的 `TS/Skills/` 目录下各模块的耦合度。
-    2. 调用 `gitnexus-project` 检索 C++ 属性系统的基类定义，获取 `UAttributeSet` 的继承拓扑。
-    3. **结果**：CC 在没有加载一行具体 C++ 实现代码的前提下，完成了方案规划，Token 消耗极低。
+**流程**：
+1. 调用 Graphify 查询 `graphify-out/graph.json`，了解现有技能系统与属性系统的模块关系
+2. 调用 `gitnexus_context({name: “URPGAttributeSet”, repo: “AIDM”})` 获取属性系统的继承拓扑
+3. 调用 `gitnexus_impact({target: “URPGAttributeSet”, direction: “upstream”, repo: “AIDM”})` 评估修改影响范围
+4. Graphify 高亮相关设计文档（`.trae/specs/ARPGGameDevelopment/`）
 
-#### 阶段 2：编写代码期 (Coding)
-- **任务**：在 TS 中实现具体的绑定逻辑，并调用引擎的定时器 `FTimerManager`。
-- **CC 的自动决策**：
-    1. CC 调用 `gitnexus-ue-engine`，查询 `GetWorld()->GetTimerManager().SetTimer(...)` 的精准函数签名与参数定义（避免盲猜宏和重载）。
-    2. CC 检索 `Typing/ue/index.d.ts`，确保 Puerts 生成的 `UE.FTimerManager` 包含了正确的映射。
-    3. **结果**：CC 写出的 TypeScript 代码精准无误，甚至连复杂的 C++ 反射导出边界都完全符合规范。
+**结果**：CC 在未加载具体 C++ 实现代码的前提下完成方案规划，Token 消耗极低。
 
-#### 阶段 3：调试 Bug 期 (Debugging)
-- **任务**：游戏在调用某个 TS 导出的 C++ 接口时发生了崩溃（Crash）或逻辑死锁。
-- **CC 的自动决策**：
-    1. CC 拿到调用栈（Callstack）后，直接将崩溃符号输入 `gitnexus-project`。
-    2. GitNexus 逆向追踪该符号的调用链（Caller/Callee），直接指出：“该 C++ 接口被 3 个 TS 脚本在 `OnPostInit` 生命周期中并行调用，可能导致了竞态条件。”
-    3. **结果**：无需人工为其复制几千行的生命周期管理代码，CC 通过图谱边（Edges）直接抓住了引发 Bug 的核心链路。
+### 阶段 2：编写代码期 (Coding)
+**任务**：在 C++ 中实现绑定逻辑，调用引擎定时器 `FTimerManager`。
+**流程**：
+1. 调用 `gitnexus_context({name: “FTimerManager”, repo: “UE_5.7”})` 获取引擎侧精准函数签名
+2. 调用 `gitnexus_query({query: “timer set timer”, repo: “UE_5.7”})` 查找引擎中定时器的执行流
+3. Graphify 确认修改不违反项目架构约束（`.trae/documents/02_程序架构/开发规范.md`）
+
+**结果**：CC 写出的代码精准匹配引擎 API，避免盲猜宏和重载。
+
+### 阶段 3：调试 Bug 期 (Debugging)
+**任务**：C++ 接口在 TS 调用时崩溃。
+**流程**：
+1. CC 获取调用栈，将崩溃符号输入 GitNexus
+2. `gitnexus_context` 逆向追踪调用链（Caller/Callee）
+3. `gitnexus_impact` 列出所有受影响执行流
+4. Graphify 检查是否有相关设计文档记录了已知限制或迁移计划
+
+**结果**：通过图谱边（Edges）直接定位 Bug 核心链路，无需人工复制几千行生命周期管理代码。
 
 # Debug
 ## LLDB