BlueRose/BlueRoseNote

Fork 0

Files

BlueRose 074e0ede37 vault backup: 2026-05-27 20:57:53

2026-05-27 20:57:53 +08:00

12 KiB

Raw Blame History

目录结构

docs
- Netease_AITA_AssetMaker.md：项目技术、设计细节入口文档，方便Agent来寻找
Projects：UE工程目录。

测试

UE测试技术

可视化日志
自动测试框架

知识图谱

为了杜绝 CC 盲目调用 cat、grep 读取原始大文件，你必须在项目根目录下创建 .claude_rules 或 .claudecode.json，强制注入以下系统指令（System Prompt）：

# Claude Code 行为准则 - 虚幻引擎双栈项目
## 1. 核心原则：图谱优先 (Graph-First Execution)
- 严禁直接使用 `cat`、`view_file`、`grep` 或 `find` 作为你探索代码库、规划功能或调试 Bug 的第一步。
- 面对任何任务，你必须**首先**调用 `gitnexus-project` 或 `gitnexus-ue-engine` 获取依赖关系、符号定义与调用拓扑。
- 只有在你通过图谱精准锁定了需要修改或深入阅读的“手术切片（Code Slice）”时，才允许对该特定文件使用直接读取命令。

## 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++ 图谱节点进行互查。

GitNexus

针对引擎与项目的gitnexus图谱：

{
  "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"]
    }
  }
}

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 的守护进程：

# 启动 Graphify 实时监听项目文件、设计文档和编译输出元数据
graphify . --watch --exclude "Binaries/,DerivedDataCache/,Intermediate/"

这将持续更新本地的知识拓扑，特别是当你修改了 Puerts 的 TS 逻辑或新增了 Markdown 规划文档时，Graphify 会自动建立反向链接（Backlinks）。

编写胶水脚本让 CC 读取 Graphify

由于 Graphify 会生成结构化的持久化数据，你可以写一个简单的 CLI 胶水工具（或作为 CC 可以运行的命令）让 CC 能快捷检索 Graphify 的宏观节点：

# 创建一个名为 query_macro.sh 的工具供 CC 调用
# 用法: ./query_macro.sh "Puerts 战斗系统设计"
cat .graphify/nodes.json | grep -i "$1"

实施计划

阶段 1：功能规划期 (Planning)

任务：你想在 Puerts 脚本中新增一个技能释放组件，并调用 C++ 写的底层属性系统（AttributeSet）。
CC 的自动决策：
1. CC 遵循规则，不盲读文件。首先调用 Graphify 相关的宏观图谱，查看现有的 TS/Skills/ 目录下各模块的耦合度。
2. 调用 gitnexus-project 检索 C++ 属性系统的基类定义，获取 UAttributeSet 的继承拓扑。
3. 结果：CC 在没有加载一行具体 C++ 实现代码的前提下，完成了方案规划，Token 消耗极低。

阶段 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++ 反射导出边界都完全符合规范。

阶段 3：调试 Bug 期 (Debugging)

任务：游戏在调用某个 TS 导出的 C++ 接口时发生了崩溃（Crash）或逻辑死锁。
CC 的自动决策：
1. CC 拿到调用栈（Callstack）后，直接将崩溃符号输入 gitnexus-project。
2. GitNexus 逆向追踪该符号的调用链（Caller/Callee），直接指出：“该 C++ 接口被 3 个 TS 脚本在 OnPostInit 生命周期中并行调用，可能导致了竞态条件。”
3. 结果：无需人工为其复制几千行的生命周期管理代码，CC 通过图谱边（Edges）直接抓住了引发 Bug 的核心链路。

Debug

LLDB

1. 安装与环境配置

首先，你需要确保本地安装了 LLDB，并为 Claude Code 配置 MCP 服务。

方案 A：使用官方/社区 LLDB-MCP (推荐) 在终端中运行以下命令添加 MCP 调试服务：

# 使用 uvx 或 npx 自动安装并运行 lldb-mcp-server
claude mcp add lldb-debugger -- command "uvx" --args "lldb-mcp-server"

可能是https://github.com/stass/lldb-mcp

方案 B：开启 LLDB 2026 原生 MCP 支持 现代版本的 LLDB（v19+）已内置 MCP 协议支持。你可以在项目目录下启动它：

lldb --protocol-server start --port 59999

2. 安装调试“技能” (Skill)

为了让 Claude 具备系统化的调试思维（而不只是乱试命令），你需要从 Skills.sh 或 GitHub 安装技能包：

# 安装通用的调试技能包
claude skill install AlmogBaku/debug-skill

VSCode

这的确是一个非常典型的架构差异问题。你提到通过 COM (Component Object Model) 接口控制 Visual Studio，这非常精准，因为 VS 的底层重度依赖 Windows 的 COM 组件机制（如 DTE 对象）。但对于 VS Code 来说，情况完全不同。VS Code 是基于 Electron 和 Node.js/TypeScript 构建的，它根本没有 COM 接口。要让 MCP (Model Context Protocol) 或者外部 AI Agent 控制 VS Code，特别是进行断点调试，社区目前有几套非常成熟的开源方案和设计思路：

一、 VS Code 的 MCP 控制方案

针对 VS Code 的架构，目前主要有三种主流的控制路径：

1. “由内向外”方案：Agent 直接作为 VS Code 插件 (目前最稳定、最主流)

与其让外部的 MCP 服务去“黑客”般地控制 VS Code，不如让 Agent 直接运行在 VS Code 内部。

原理：像 Cline、Roo Code 这样的插件，它们本身就拥有完整的 VS Code Extension API 权限（可以打开文件、打断点、读取控制台）。
MCP 的角色：在这种架构下，VS Code 插件作为 MCP Client，它去连接外部的 MCP Server（比如获取特定的代码分析工具、数据库查询权限等），而不是让 MCP 来控制 VS Code。

2. DAP-MCP 桥接方案 (专门针对断点调试)

VS Code 所有的调试能力都是基于 DAP (Debug Adapter Protocol) 构建的。如果你想让一个外部的 Agent（比如你终端里的 Claude Code）控制 VS Code 的调试器，最好的办法是拦截或桥接 DAP。

原理：启动一个 mcp-server-dap。这个 MCP 服务把 Agent 发出的 MCP 指令（如“继续执行”、“查看变量”）翻译成标准的 DAP 协议，直接发给 VS Code 底层的 Debug Adapter（比如 cppdbg 或 lldb-dap）。
效果：AI 不需要点击 VS Code 的 UI 按钮，它直接和 VS Code 背后那个真正负责调试的引擎对话。

3. “由外向内”方案：WebSocket / RPC 桥接插件

如果你的 Agent 必须在外部运行，且需要控制 VS Code 的 UI（比如让编辑器滚动、高亮某一行代码）。

原理：需要在 VS Code 里安装一个暴露 WebSocket 或 HTTP 接口的桥接插件。外部的 MCP Server 通过向这个本地端口发送 JSON-RPC 指令，插件再调用 VS Code API 来执行操作。

12 KiB Raw Blame History Unescape Escape