企业官网建设流程全解析

1. 项目概述：当AI助手真正“理解”你的Unity项目

如果你是一名Unity开发者，并且尝试过用Cursor、Claude Code这类AI编程助手来辅助开发，大概率经历过这样的挫败感：你问它“给我的角色加一个二段跳”，它生成的代码要么调用了不存在的API，要么完全无视你项目中正在使用的CharacterController组件和现有的输入系统。你不得不花大量时间向AI解释你的项目结构、命名规范、已安装的包，甚至游戏的核心机制。这种“鸡同鸭讲”的沟通成本，常常让人感觉不如自己手写来得快。

这正是GladeKit Unity MCP要解决的核心痛点。它不是一个简单的代码补全工具，而是一个深度集成到Unity编辑器与AI客户端之间的“翻译官”和“项目专家”。通过Model Context Protocol（MCP），它让Cursor、Claude、Windsurf等AI助手能够直接“看见”并“操作”你的Unity编辑器。这意味着AI不再是在真空中生成代码片段，而是基于你当前打开的场景、选中的物体、项目设置以及你自定义的设计文档来提供精准的协助。

想象一下这样的场景：你选中场景中的玩家角色，然后在AI聊天框里输入“为这个角色添加一个受击闪烁效果”。AI不仅能生成正确的代码，还能自动将脚本挂载到选中的物体上，甚至根据你项目使用的是URP还是HDRP来调整Shader代码。或者，你问“敌人是如何生成的？”，AI能通过语义搜索在你的项目脚本中找到相关的EnemySpawnManager脚本，并基于其中的逻辑为你解释或修改。这就是GladeKit带来的范式转变——将AI从一个需要你不断提供上下文的“实习生”，变成一个真正理解你项目上下文、能直接动手干活的“资深技术搭档”。

1.1 核心价值：从通用代码生成到项目感知协作

市面上的AI编程工具大多停留在“增强版自动补全”阶段。它们基于公开代码库训练，能生成语法正确的通用代码，但对你项目的独特环境一无所知。GladeKit Unity MCP的核心价值在于填补了这层认知鸿沟，它通过几个关键设计实现了真正的项目感知：

第一，完整的Unity上下文注入。启动后，MCP服务器会主动扫描你的Unity项目，获取包括当前渲染管线（Built-in/URP/HDRP）、输入系统（旧的Input Manager或新的Input System Package）、已安装的Package、场景层级结构、选中的游戏对象等实时信息。这些信息会作为系统提示词的一部分，在每次与AI交互时自动发送。因此，AI生成的代码会天然适配你的项目配置，避免出现“在URP项目里生成Built-in管线Shader”这类低级错误。

第二，超过230个可调度的具体工具。这是与另一个知名项目unity-mcp最本质的区别。unity-mcp提供了约40个较为笼统的工具，而GladeKit将Unity Editor的常见操作拆解成了15个类别下的230多个原子化工具。从创建基本几何体、修改材质球属性，到设置动画状态机、配置NavMesh烘焙参数，甚至调用Profiler进行性能快照，几乎涵盖了日常开发的所有操作。AI可以通过调用这些工具，直接对编辑器进行操作，而不仅仅是生成需要你手动复制粘贴的代码。

第三，可扩展的项目知识库（GLADE.md）。每个项目都有自己独特的“黑话”和规则。你可以在项目根目录创建一个GLADE.md文件，就像一份给AI看的项目入职手册。里面可以定义你的游戏类型（“3D平台跳跃”）、核心机制（“玩家使用CharacterController，允许二段跳”）、美术规范（“像素风，精灵图基准尺寸16x16”）、代码规范（“脚本用PascalCase，文件夹用snake_case”）。这个文件会被MCP服务器读取，并注入到每一次AI请求的上下文中，确保AI的建议始终符合你的项目约定。

注意：GLADE.md的文件名是大小写敏感的，在Mac/Linux系统上必须确保完全一致，并且要放在与Assets、ProjectSettings同级的项目根目录下，否则服务器将无法识别。

2. 核心架构与工作原理拆解

要理解GladeKit为何强大，我们需要深入其架构。它并非一个单一的黑盒应用，而是一个精巧的双层客户端-服务器体系，通过标准化的MCP协议进行通信。

2.1 架构全景：三层通信模型

整个系统运行涉及三个核心部分，它们协同工作，将AI的“思考”转化为Unity编辑器中的“行动”。

[AI客户端层] (Cursor, Claude Code, Windsurf, Claude Desktop, Unity AI Gateway) | | 传输层：基于MCP协议的通信 (stdio 或 HTTP) v [GladeKit MCP服务器层] (一个独立的Python进程：gladekit-mcp) | | 内部处理：工具路由、上下文管理、云服务交互 v [Unity Bridge层] (一个Unity Editor插件，UPM包形式) | | Unity Editor API v [你的Unity项目与编辑器状态]

第一层：AI客户端。这是你直接交互的界面，如Cursor的聊天面板或Claude Desktop的对话窗口。它们内置或配置了MCP客户端功能，负责将你的自然语言请求封装成MCP协议格式，发送给MCP服务器，并接收和展示服务器的回复与工具调用结果。

第二层：GladeKit MCP服务器（Python进程）。这是整个系统的“大脑”。它由几个关键模块组成：

• bridge.py：负责与第三层的Unity Bridge建立HTTP连接（默认localhost:8765），转发工具调用请求并返回结果。
• prompts.py：动态生成系统提示词。这是智能的关键，它会读取Unity Bridge上报的项目上下文（渲染管线、输入系统等）以及本地的GLADE.md文件，组合成一份详尽的“情况说明书”附在每次请求中。
• tools/目录：定义了230多个工具的OpenAI函数调用（Function Calling）格式的Schema。它告诉AI每个工具叫什么、需要什么参数、干什么用。
• cloud.py（可选）：如果配置了GLADEKIT_API_KEY，此模块会与GladeKit的云服务api.gladekit.com通信，启用RAG知识库检索和跨会话记忆等高级功能。

第三层：Unity Bridge（C# Editor插件）。这是执行操作的“手”。它以UPM包的形式安装在你的Unity项目中，启动一个本地HTTP服务器（默认端口8765）。它包含所有230多个工具的具体C#实现。当收到来自MCP服务器的工具调用指令时，它通过Unity Editor的API直接执行相应的编辑器操作，比如实例化一个预制体、修改组件属性或执行一个编辑器菜单命令，然后将执行结果（成功或失败信息）返回。

这种架构的优势在于解耦和标准化。MCP服务器和AI客户端通过标准协议通信，因此支持任何实现了MCP的客户端。Unity Bridge专注于与Editor API交互，功能稳定。任何一方的更新都不会严重影响另一方。

2.2 MCP协议：AI与工具对话的“普通话”

Model Context Protocol (MCP) 可以理解为AI应用与外部工具和服务通信的“普通话”或标准协议。它由Anthropic提出，旨在标准化LLM与外部资源（工具、数据库、API）的交互方式。在GladeKit中，MCP协议定义了：

• 工具（Tools）：AI可以调用的具体操作，每个工具都有明确的名称、描述和参数格式。
• 资源（Resources）：AI可以读取的上下文信息，在GladeKit中包括“当前场景结构”、“项目脚本列表”、“GLADE.md内容”等。
• 提示词（Prompts）：预定义的提示模板，用于引导AI行为。

当你在AI客户端输入“创建一个红色立方体放在玩家面前”时，客户端通过MCP协议询问服务器：“有哪些工具可用？”服务器返回工具列表。AI模型（如Claude 3）根据你的指令和工具描述，决定调用create_primitive工具，并生成符合Schema的参数{“type”: “cube”, “position”: “relative_to_selected”, “material_color”: “#FF0000”}。客户端再通过MCP协议将这个调用请求发送给服务器，服务器转发给Unity Bridge执行，最终结果通过同一通道返回并显示给你。

3. 详细配置与连接指南

理解了原理，接下来就是动手搭建。配置过程分为两大步：在Unity中安装Bridge插件，以及在你的AI客户端中配置MCP服务器连接。

3.1 第一步：安装Unity Bridge插件

这是让Unity编辑器“开口说话”的一步。GladeKit的Unity Bridge以UPM（Unity Package Manager）包的形式提供，安装非常简便。

1. 打开你的Unity项目。
2. 点击顶部菜单栏的Window > Package Manager，打开包管理器窗口。
3. 在包管理器左上角，点击“+”按钮，选择“Add package from git URL...”。
4. 在弹出的输入框中，粘贴以下Git仓库URL（注意包含子目录路径）：https://github.com/Glade-tool/glade-mcp-unity.git?path=/unity-bridge
5. 点击“Add”。Unity会开始从Git仓库下载并导入这个包。导入完成后，你可能会在Window菜单下看到一个新的“GladeKit MCP”选项，用于查看连接状态。

安装完成后，Bridge插件会自动在后台启动一个本地HTTP服务器，默认监听localhost:8765。你无需进行任何额外操作。可以通过Window > GladeKit MCP打开面板，查看“Bridge”指示灯是否为绿色（连接正常）。

实操心得：有时在导入大量资源后启动Unity，Bridge可能启动稍慢。如果后续连接客户端失败，可以先打开这个面板，确认Bridge状态是否就绪。如果指示灯为红色，尝试重启Unity通常可以解决。

3.2 第二步：配置AI客户端连接MCP服务器

这是让AI客户端“听懂”Unity的一步。你需要一个“中介程序”来连接AI客户端和Unity Bridge，这个中介就是gladekit-mcp这个Python包。官方推荐使用uvx来运行它，uvx是uv工具链的一部分，可以理解为更快速、更现代的pip。

首先，安装uv（一次性操作）：

• macOS / Linux:打开终端，运行以下命令：

  curl -LsSf https://astral.sh/uv/install.sh | sh

  安装后，可能需要重启终端或运行source ~/.bashrc（或source ~/.zshrc）来使uv命令生效。
• Windows:以管理员身份打开PowerShell，运行：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

接下来，根据你使用的AI客户端，选择对应的配置方式。所有配置的核心都是告诉客户端：“当你需要和Unity对话时，去运行uvx gladekit-mcp这个命令，并通过标准输入输出（stdio）与它通信。”

针对Claude Code的配置（推荐使用一键命令）：

Claude Code是目前对MCP支持最友好的编辑器之一。官方提供了最简便的一键配置命令。

• macOS / Linux:在终端中运行：

  claude mcp add --transport stdio gladekit-unity --scope user -- uvx gladekit-mcp

• Windows:在命令提示符或PowerShell中运行：

  claude mcp add --transport stdio gladekit-unity --scope user -- cmd /c uvx gladekit-mcp

  这条命令会自动在Claude Code的配置文件中添加正确的MCP服务器设置。--scope user表示此配置对所有项目生效。

针对Cursor编辑器的配置：

1. 打开Cursor，进入Settings（设置）。
2. 在侧边栏找到MCP选项。
3. 点击“Add new MCP server”。
4. 在配置编辑框中，粘贴以下JSON内容：

   { "mcpServers": { "gladekit-unity": { "command": "uvx", "args": ["gladekit-mcp"] } } }

5. 保存配置并重启Cursor。

针对Claude Desktop应用的配置：

Claude Desktop的配置是一个本地配置文件。

1. 找到配置文件所在位置：
   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
2. 用文本编辑器（如VS Code、记事本）打开此文件。
3. 在JSON结构中，找到或添加mcpServers字段，将其修改为如下内容（如果文件为空或没有该字段，则直接创建这个结构）：

   { "mcpServers": { "gladekit-unity": { "command": "uvx", "args": ["gladekit-mcp"] } } }

4. 保存文件，并完全重启Claude Desktop应用。

针对Unity内置AI Gateway（原生集成，无需外部客户端）：

这是最无缝的体验，AI助手直接内嵌在Unity编辑器中。但需要较新版本的Unity（6000.3+）并安装AI Assistant包。

1. 确保Unity版本符合要求，并通过Package Manager安装com.unity.ai.assistant@2.x包。
2. 在Unity中，点击Edit > Project Settings > AI > MCP Servers。
3. 点击“Open Config File”，这会打开一个JSON配置文件。
4. 将配置内容替换为：

   { "enabled": true, "path": "", "mcpServers": { "gladekit-unity": { "type": "stdio", "command": "uvx", "args": ["gladekit-mcp"] } } }

5. 关键步骤：配置PATH。Unity进程的环境变量可能和你的终端不同。在Path Configuration部分，将你终端中的PATH值粘贴到User Path字段。
   • 获取PATH：在终端运行echo $PATH(Mac/Linux) 或echo %PATH%(Windows)。
6. 点击“Refresh Config File and Reload Servers”。
7. 在Servers部分，查看gladekit-unity的状态，应为“StartedSuccessfully”。

避坑指南：Unity AI Gateway连接失败，90%的原因都是PATH问题。如果状态显示“FailedToStart”，点击“Inspect”查看具体错误。如果提示找不到uvx，除了正确设置User Path，还有一个更稳妥的方案：改用pip安装。在终端运行pip install gladekit-mcp，然后将上述配置中的"command"改为"python"，"args"改为["-m", "gladekit_mcp"]。这样可以绕过uvx的路径依赖问题。

完成以上任一种客户端的配置后，启动你的AI客户端（或重启Unity，如果是AI Gateway），你应该就能在聊天界面中感受到不同。尝试输入一些与Unity相关的指令，比如“列出当前场景中的所有物体”，如果配置成功，AI应该能够调用工具并返回实际的项目信息。

4. 高级功能深度解析与实战应用

基础连接只是开始，GladeKit真正提升效率的在于其一系列高级功能。这些功能将AI从一个被动的代码生成器，转变为一个主动的、有记忆的、懂你项目的开发伙伴。

4.1 脚本语义搜索：让AI成为你的项目“活字典”

你是否曾在几百个脚本中寻找某个特定功能的实现？或者向AI提问时，它因为不知道你项目中有相关代码而胡编乱造？脚本语义搜索功能就是为了解决这个问题。

原理：该功能基于OpenAI的文本嵌入（Embedding）模型。当你启用此功能（通过设置OPENAI_API_KEY环境变量）后，GladeKit MCP服务器会为你项目Assets目录下的所有C#脚本创建嵌入向量。当你在对话中提问，例如“我的玩家生命值是怎么计算的？”，服务器会将你的问题也转化为向量，然后与所有脚本向量进行相似度计算，找出语义上最相关的几个脚本，并将它们的内容作为上下文提供给AI。

配置方法：你需要一个OpenAI的API密钥（在 platform.openai.com/api-keys 申请，使用text-embedding-3-small模型，每次搜索成本极低）。然后在你的MCP配置中，以环境变量的形式传入：

{ "mcpServers": { "gladekit-unity": { "command": "uvx", "args": ["gladekit-mcp"], "env": { "OPENAI_API_KEY": "sk-your-openai-api-key-here" } } } }

对于Claude Desktop或Unity AI Gateway，修改对应的配置文件，在gladekit-unity的配置项中添加"env"字段即可。

实战效果：启用后，当你问“敌人AI的巡逻逻辑是怎样的？”，AI会先通过语义搜索找到EnemyAIController.cs或PatrolState.cs，读取其代码，然后基于实际的代码逻辑向你解释，甚至提出修改建议。这彻底杜绝了AI“凭空想象”你的代码结构，让它的回答始终扎根于你的项目现实。

安全提示：你的API密钥仅用于向OpenAI的嵌入端点发送脚本文本以生成向量，脚本内容不会被用于训练，且GladeKit不会存储你的密钥。如果不设置此密钥，search_project_scripts工具依然可用，只是返回的脚本列表没有经过相关性排序。

4.2 GLADE.md与技能校准：打造专属的AI助手

GLADE.md：项目的灵魂文件。这个文件是你与AI对齐项目认知的最强工具。它不限于技术规范，更应包含游戏设计意图。例如：

# 《星海巡游者》项目手册 ## 核心设计 - **类型**： 俯视角太空基地建设与生存游戏。 - **核心循环**： 采集资源 -> 扩建基地 -> 研发科技 -> 防御虫潮。 - **美术基调**： Low Poly科幻风，主色调为深蓝、金属灰，搭配霓虹点缀。 ## 技术栈与规范 - **渲染管线**： URP 14.0.8。 - **输入系统**： 新版Input System。动作映射前缀：`Player_`, `UI_`。 - **代码规范**： - 所有`MonoBehaviour`脚本以`Manager`, `Controller`, `System`后缀结尾。 - 私有字段前缀下划线：`_currentHealth`。 - 资源加载使用`Addressables`，禁止`Resources.Load`。 - **实体命名**： `PF_`（预制体），`MAT_`（材质），`SFX_`（音效）。 ## 特定规则 - 玩家单位移动使用`A* Pathfinding Project`插件，勿用Unity原生NavMesh。 - 所有UI动画需通过`DoTween`驱动，禁用`Animator`。 - 场景中“Environment”静态物体必须标记为`Static`（Occluder Static）。

当AI在每次交互前都读到这份文档，它生成的代码、提出的建议都会自觉遵循这些规则，极大减少了后续的代码审查和返工。

技能校准：自适应你的经验水平。GladeKit会默默分析你的对话用语。如果你频繁使用“GameObject”、“Prefab”、“MonoBehaviour”等专业术语，它会将你标记为“专家”模式，回复变得简洁、技术性强，直接给出代码和工具调用。如果你是新手，问“怎么让一个东西动起来？”，它会识别出你的基础水平，回复时会先解释概念（“我们可以通过为物体添加一个脚本，在Update函数中修改它的位置来实现移动…”），并提供更详细的步骤和鼓励性语言。这个校准结果会保存在项目下的.gladekit/skill_level.json文件中，在不同会话间保持。

4.3 云智能层：跨会话记忆与知识增强

这是GladeKit的付费增值功能（需要GLADEKIT_API_KEY），但它设计得非常优雅——有则增强，无则无感。

功能一：RAG知识库。当你使用get_relevant_tools工具（用于根据任务描述查找相关工具）时，除了返回工具列表，系统还会查询GladeKit维护的一个 curated Unity 知识库。这个知识库可能包含了特定Unity API的常见坑点、错误模式的解决方案、最佳实践等。这些外部知识会和工具建议一起注入给AI，使其建议更加精准可靠。

功能二：跨会话持久化记忆。核心工具remember_for_session允许你在对话中让AI记住一个事实，比如“这个项目中，金币的预制体是PF_Coin.prefab”。在免费版中，这个记忆只在当前对话会话中有效。启用云智能后，这些记忆会被加密上传到云端，并在你未来的新会话中，自动作为上下文的一部分重新注入。这意味着AI拥有了“长期记忆”，不再需要你反复告知相同的信息。

功能三：惯例提取。云端后台会分析你积累的所有记忆，自动提炼出你的编码模式和偏好（例如，你总是用_前缀私有字段，你偏好使用ScriptableObject做数据配置）。未来，这些被提取的“惯例”可能会被用来进一步优化AI对你的服务，比如自动建议符合你习惯的代码结构。

配置与降级：要启用这些功能，只需在MCP配置的env字段中加入"GLADEKIT_API_KEY": "your-key"。如果密钥无效或网络不通，所有功能会优雅降级：get_relevant_tools仍返回工具列表（只是没有RAG知识），remember_for_session退化为会话内存，整个系统继续正常工作，保障了核心体验的稳定性。

5. 工具生态与扩展开发指南

GladeKit提供的230多个工具是其生产力的基石。这些工具并非随意堆砌，而是按照Unity编辑器的功能模块精心组织的15个类别。

5.1 工具类别与使用策略

核心工具类别预览：

• 场景与游戏对象：创建、销毁、选择、父子化、激活/禁用物体。
• 脚本：创建新的C#脚本、附加脚本到物体、打开脚本编辑器。
• 预制体：实例化预制体、解包预制体、创建预制体变体。
• 材质与着色器：创建材质、修改材质属性（颜色、纹理、浮点数）、分配材质给渲染器。
• 动画：操作Animator Controller、设置动画参数、播放动画状态。
• UI：创建Canvas、各种UI控件（Button, Image, TextMeshPro）、设置锚点布局。
• 物理：添加刚体、碰撞体、修改物理材质。
• 光照与渲染：创建光源、调整光源参数、修改环境光设置。
• 音频与VFX：添加音频源、粒子系统、修改其属性。
• 导航与AI：烘焙NavMesh、设置NavMesh代理。
• 性能分析：触发Profiler录制、获取性能数据快照。

工具发现机制：由于AI客户端（如Claude Code）有可调用工具的数量限制（约128个），GladeKit默认只暴露约80个最常用的核心工具。但这不代表其他工具不可用。当你需要完成特定任务时，应使用get_relevant_tools这个元工具。你可以用自然语言描述你的任务，例如“我想调整角色的混合树（Blend Tree）”，该工具会从全部230多个工具中，筛选出与“混合树”、“动画”、“Animator”相关的工具（如get_animator_parameters,set_animator_float_parameter等），并使其在当前会话中可用。这是一种按需加载的动态工具发现策略。

元工具详解：

• get_relevant_tools：如上所述，基于任务描述的工具发现器。
• remember_for_session：让AI记住一个关键信息，如“主角的脚本名是PlayerController”。
• recall_session_memories：让AI回忆在当前会话中记住的所有事情。
• batch_execute：批量执行多个工具调用，适合复杂多步操作。
• search_project_scripts：执行脚本语义搜索。

5.2 如何为GladeKit贡献新工具

GladeKit是开源的，其工具库的扩展性设计得非常清晰。添加一个新工具需要同时修改C#端的实现和Python端的定义。

步骤一：在Unity Bridge（C#）中添加工具实现

1. 在unity-bridge/Editor/Tools/Implementations/目录下，找到合适的类别子目录（如Physics），或创建一个新的。
2. 新建一个C#脚本，例如AddSpringJointTool.cs。
3. 让这个类实现ITool接口。Name属性是工具的唯一标识符（建议用蛇形命名add_spring_joint），Execute方法是工具的核心逻辑。

using System.Collections.Generic; using UnityEditor; using UnityEngine; namespace GladeKit.Unity.Editor.Tools.Implementations.Physics { public class AddSpringJointTool : ITool { public string Name => "add_spring_joint"; public string Execute(Dictionary<string, object> args) { // 1. 参数解析与验证 if (!args.TryGetValue("game_object_path", out object goPathObj) || string.IsNullOrEmpty(goPathObj as string)) { return ToolUtils.CreateErrorResponse("Missing or invalid 'game_object_path' argument."); } string gameObjectPath = (string)goPathObj; // 2. 通过路径找到场景中的游戏对象 GameObject targetGo = GameObject.Find(gameObjectPath); if (targetGo == null) { return ToolUtils.CreateErrorResponse($"GameObject with path '{gameObjectPath}' not found."); } // 3. 执行核心操作：添加Spring Joint组件 var springJoint = targetGo.AddComponent<SpringJoint>(); // 4. 设置可选参数（示例） if (args.TryGetValue("spring", out object springObj) && float.TryParse(springObj.ToString(), out float springValue)) { springJoint.spring = springValue; } if (args.TryGetValue("damper", out object damperObj) && float.TryParse(damperObj.ToString(), out float damperValue)) { springJoint.damper = damperValue; } // 5. 返回成功响应，可附带额外信息 var extras = new Dictionary<string, object> { { "component_added", "SpringJoint" }, { "game_object", targetGo.name } }; return ToolUtils.CreateSuccessResponse($"Successfully added SpringJoint to '{targetGo.name}'.", extras); } } }

步骤二：在MCP服务器（Python）中注册工具Schema

1. 在mcp-server/src/gladekit_mcp/tools/目录下，找到对应的类别文件，如physics.py。
2. 在工具列表中添加新工具的Schema定义。这个Schema遵循OpenAI函数调用格式，用于描述工具如何被AI调用。

# 在 physics.py 的 tools 列表中添加 { "type": "function", "function": { "name": "add_spring_joint", # 必须与C#端的Name一致 "description": "Adds a Spring Joint component to a specified GameObject. A Spring Joint attempts to keep two Rigidbodies a certain distance apart, using a spring force.", "parameters": { "type": "object", "properties": { "game_object_path": { "type": "string", "description": "The full hierarchical path to the GameObject in the scene (e.g., 'Player/Arm/Hand')." }, "spring": { "type": "number", "description": "The spring force used to keep the objects together. Higher values make the spring stiffer. Optional, defaults to component's default." }, "damper": { "type": "number", "description": "The amount of damping applied to the spring oscillation. Higher values reduce oscillation faster. Optional, defaults to component's default." } }, "required": ["game_object_path"] # 只有这个参数是必需的 } } }

完成这两步后，工具就注册成功了。Unity Bridge通过反射自动发现所有实现了ITool的类，因此无需额外的注册代码。重新启动MCP服务器，AI就可以通过get_relevant_tools发现并使用你这个新添加的add_spring_joint工具了。

6. 常见问题排查与优化技巧

即使按照指南操作，在实际部署中仍可能遇到一些问题。以下是基于社区反馈和实测总结的常见问题与解决方案。

6.1 连接类问题

问题：AI客户端显示“无法连接到MCP服务器”或工具列表为空。

• 检查Unity Bridge状态：首先确认Unity编辑器已打开且项目加载完毕。打开Window > GladeKit MCP，查看“Bridge”指示灯是否为绿色。如果是红色，尝试重启Unity。
• 检查端口占用：默认端口8765可能被其他程序占用。在终端运行：
  • Mac/Linux:lsof -i :8765
  • Windows:netstat -ano | findstr :8765如果发现占用，可以终止占用进程，或修改Unity Bridge的端口（需要修改插件源码并重新编译，对新手不推荐）。
• 验证MCP服务器命令：在终端直接运行uvx gladekit-mcp。如果命令未找到，说明uv安装或PATH配置有问题。如果命令执行但立即退出或报错，可能是Python环境或依赖问题。尝试用pip install gladekit-mcp安装，然后在客户端配置中将命令改为python，参数改为["-m", "gladekit_mcp"]。

问题：Unity AI Gateway中服务器状态为“FailedToStart”。

• 点击“Inspect”查看详细错误：这是最关键的一步，错误信息会明确指出问题，通常是“Command not found: uvx”。
• PATH配置是重中之重：Unity进程的PATH环境变量独立于你的终端。务必在Project Settings的AI > MCP Servers页面，将你从终端echo $PATH或echo %PATH%得到的完整路径字符串，粘贴到“User Path”字段，然后点击“Refresh”。
• 备用方案（推荐）：放弃uvx，使用pip安装。在终端运行pip install gladekit-mcp，然后在Unity的MCP配置中，将"command"改为"python"，"args"改为["-m", "gladekit_mcp"]。这通常更稳定。

6.2 功能类问题

问题：在Claude Code里，我听说有200多个工具，但看起来只有几十个。

• 这是正常设计：Claude Code等客户端对单次会话可加载的工具数量有限制（约128个）。GladeKit默认加载约80个最通用的核心工具以保证性能和稳定性。
• 使用get_relevant_tools：当你需要做特定任务时（如“设置导航网格”或“调整粒子系统”），在聊天中明确告诉AI：“请使用get_relevant_tools帮我找到与导航烘焙相关的工具”。AI会调用该工具，从后台检索出所有相关工具并加载到当前会话中，之后你就可以使用了。

问题：GLADE.md文件似乎没有被读取，AI的回答没有遵循里面的规则。

• 检查文件名和位置：确保文件名为精确的GLADE.md（在Mac/Linux上大小写敏感），并且位于Unity项目的根目录（与Assets、Packages、ProjectSettings文件夹同级）。
• 检查文件格式：确保是有效的UTF-8编码的Markdown文件，没有奇怪的字符。
• 重启MCP服务器：GLADE.md在MCP服务器启动时读取。修改文件后，需要重启你的AI客户端或MCP服务器进程（对于stdio模式，重启客户端即可）以使更改生效。

问题：语义搜索好像没起作用，AI还是找不到我的脚本。

• 确认API密钥已配置：检查你的MCP配置中OPENAI_API_KEY环境变量是否正确设置。
• 检查网络连接：确保你的机器可以访问OpenAI的API端点（api.openai.com）。某些网络环境可能需要配置代理。
• 查看日志：以调试模式启动MCP服务器可能看到更多信息。你可以尝试临时修改客户端配置，在命令后添加--verbose参数（如果支持），或直接运行uvx gladekit-mcp查看控制台输出。
• 首次索引需要时间：首次启用时，服务器需要为所有脚本生成嵌入向量，如果项目很大，可能会有短暂延迟。

6.3 性能与使用技巧

优化响应速度：

• 保持Unity项目整洁：避免在Assets目录下存放大量非脚本文件（如图片、模型），因为语义搜索会遍历所有.cs文件。可以使用.gladeignore文件（如果未来支持）或确保脚本组织在特定文件夹。
• 按需加载工具：不要一次性请求加载所有工具。始终通过get_relevant_tools按任务需求加载，可以减少初始化的开销和AI的认知负担。
• 使用批处理：对于复杂的多步操作，可以考虑让AI使用batch_execute工具，将多个操作打包成一个请求，减少来回通信的次数。

提升交互效率：

• 从具体到抽象：刚开始使用时，给AI的指令要具体。例如，不说“优化这个场景”，而说“检查当前场景的Draw Call数量，并列出使用相同材质但未静态批处理的物体”。随着AI通过GLADE.md和你的对话记忆更了解项目后，可以逐渐使用更抽象的指令。
• 结合使用：将GladeKit MCP与AI客户端的代码补全、聊天功能结合。用聊天来规划功能和描述需求，用GladeKit来执行具体的编辑器操作和查询项目上下文，用传统的代码补全来编写具体的算法逻辑。
• 主动提供反馈：当AI调用工具产生的结果不符合预期时，在聊天中纠正它。例如，“刚才创建的立方体尺寸太大了，请将其缩放设置为(0.5,0.5,0.5)”。这种反馈会被会话记忆捕获，帮助AI在后续操作中调整其参数选择。

从我的实际使用经验来看，GladeKit Unity MCP最大的价值在于它创造了一个“可操作的对话界面”。开发不再是纯粹的打字，而是与一个理解你项目语境的智能体进行协作。它尤其擅长那些繁琐、重复但需要上下文感知的任务：比如按照特定规范批量重命名资源、根据设计文档搭建基础场景结构、或者快速查询和修改分散在不同脚本中的游戏参数。它并没有取代开发者，而是将开发者从大量机械的上下文切换和查找中解放出来，让我们能更专注于真正创造性的游戏设计逻辑本身。