vault backup: 2026-05-28 18:41:41
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user