Unity自主代理MCP
🤖 Unity 2022.3.22f1的全面自主代理框架 它将模型上下文协议（MCP）的强大功能与先进的人工智能决策能力相结合。
🌟 主要特点
🧠 自主代理能力
- 智能任务规划：人工智能驱动的任务分解和执行计划
- 决策：具有学习能力的上下文感知决策树
- 自我完善：从用户互动和结果中不断学习
- 多智能体协调：支持多个自主代理协同工作
🎮 Unity集成
- 完全编辑器控制：完整的Unity编辑器自动化和操作
- 运行时AI：游戏中自主NPC行为和调试
- 资产管理：智能资产创建、优化和组织
- 场景管理：自动场景设置、优化和测试
🔧 高级MCP功能
- 可扩展架构：基于插件的自定义工具和处理程序系统
- 实时通信：与外部AI服务的低延迟TCP/IP通信
- 多提供商支持：与Claude、GPT、Gemini和自定义LLM提供商兼容
- 资源管理：智能资源分配和优化
🏗️ 架构概述
┌─────────────────────────────────────────────────────────────┐
│ Unity Autonomous Agent MCP │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ Agent Core │ │ Task Planner │ │ Decision │ │
│ │ │ │ │ │ Engine │ │
│ │ - State Mgmt │ │ - Task Decomp │ │ - ML Models │ │
│ │ - Learning │ │ - Priority │ │ - Context │ │
│ │ - Memory │ │ - Scheduling │ │ - Reasoning │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ MCP Server │ │ Unity Bridge │ │ Plugin │ │
│ │ │ │ │ │ System │ │
│ │ - Protocol │ │ - Editor API │ │ - Custom │ │
│ │ - Handlers │ │ - Runtime API │ │ Tools │ │
│ │ - Transport │ │ - Asset Mgmt │ │ - Extensions │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Unity Engine (2022.3.22f1) │
└─────────────────────────────────────────────────────────────┘📋 需求
- Unity 2022.3.22f1 或更高版本（测试到Unity 6.1）
- .NET/C#9.0
- Node.js 18.0.0+ 使用npm（用于TypeScript服务器）
- Python 3.8+ （适用于ML/AI组件）
- 外部LLM提供者 （Claude、OpenAI、Gemini或自定义）
🚀 快速开始
重新分析的细节和能力差距记录在 docs/capability-matrix.md.1.安装
# Clone the repository
git clone https://github.com/KinofSin/UnityAutonomousMCP.git
cd UnityAutonomousMCP
# Install Unity Package
# In Unity Editor: Window > Package Manager > Add package from git URL
# Enter: file:///path/to/UnityAutonomousMCP/com.autonomous-unity.mcp2.设置TypeScript服务器
npm install
npm run build
npm run smokenpm run smoke 验证计划者+执行者行为（包括 run_tests -> get_test_job 轮询）用于成功和失败的测试作业终端路径，而不需要实时Unity编辑器。
3.运行模式
# Autonomous bootstrap (local dry-run using mock Unity bridge)
npm run dev -- -- "inspect scene and update scripts"
# MCP stdio mode (for Claude/Cursor/Windsurf MCP client config)
npm run dev -- --mcp
# Force mock bridge explicitly
npm run dev -- --mock -- "inspect scene and update scripts"4.运输桥配置（真正的Unity连接）
Unity包主机（位于Unity编辑器内）提供两种传输：
- HTTP端点：
POST /mcp/tool上UNITY_HTTP_PORT（默认值8080) - TCP端点：以换行符分隔的JSON
UNITY_TCP_PORT（默认值8081)
节点侧网桥环境变量：
UNITY_TRANSPORT=http # http | tcp | mock
UNITY_HOST=127.0.0.1
UNITY_HTTP_PORT=8080
UNITY_TCP_PORT=8081
UNITY_TIMEOUT_MS=10000
UNITY_TEST_POLL_ATTEMPTS=30
UNITY_TEST_POLL_INTERVAL_MS=1000
UNITY_TEST_POLL_TIMEOUT_MS=1200005.配置克劳德桌面
{
"mcpServers": {
"unity-autonomous-agent": {
"command": "node",
"args": ["path/to/server/dist/index.js"],
"env": {
"UNITY_HOST": "localhost",
"UNITY_TRANSPORT": "http",
"UNITY_HTTP_PORT": "8080",
"UNITY_TCP_PORT": "8081",
"AI_PROVIDER": "anthropic",
"AI_API_KEY": "your-api-key"
}
}
}
}6.开始使用
- 开放Unity项目
- 导航至
Edit > Preferences > Autonomous Agent MCP - 配置主机+HTTP/TCP端口
- 点击“连接”启动Unity传输主机
- 启动MCP服务器(
npm run dev -- --mcp) - 通过您首选的MCP客户端开始与AI交互
✅ 当前实施状态（此仓库）
- 能力矩阵+差距分析:
docs/capability-matrix.md - 自主规划师核心:
server/src/planner.ts - 政策护栏:
server/src/policy.ts - 计划执行人:
server/src/executor.ts - MCP服务器工具 (
autonomous_plan,unity_tool_call,list_capabilities):server/src/mcpServer.ts - 真正的Unity网桥传输（HTTP/TCP+env驱动模式）:
server/src/unityBridge.ts - autonomous_plan的具体步骤合同:
server/src/contracts.ts - Unity 2022.3.22f1包装脚手架:
com.autonomous-unity.mcp/
- 编辑器设置/提供程序： Editor/AutonomousMcpSettingsProvider.cs - 实际运输主机： Editor/AutonomousMcpTransportHost.cs - 工具调度员： Editor/AutonomousMcpToolDispatcher.cs - 运行时条目组件： Runtime/AutonomousMcpRuntime.cs
🔁 端到端autonomous_plan合约映射
autonomous_plan 现在发出具体的Unity工具有效载荷：
read_console→{ level, limit }manage_scene→{ action: "inspect_active_scene" }manage_script→{ action: "create_or_update", scriptPath, contents }*（当目标意味着代码更改时）*validate_script→{ strict }*（脚本编辑后）*run_tests→{ mode }*（当目标提到测试时；返回jobId)*get_test_job→{ jobId }*（遗嘱执行人投票至completed或failed)*batch_execute→{ operations: [{ tool: "manage_scene", params: { action: "save_active_scene" } }] }
测试执行流程
run_tests启动异步Unity测试运行程序作业(editmode或playmode)- 服务器接收
{ jobId, status: "queued" } - 执行器自动调用
get_test_job直到终端状态 - 最终测试总结（通过/失败/跳过+每个测试细节）包含在执行结果中
测试轮询策略限制
UNITY_TEST_POLL_ATTEMPTS：的最大轮询迭代次数get_test_job（夹紧1..300）UNITY_TEST_POLL_INTERVAL_MS：轮询之间的延迟（毫秒）（限制为100..60000）UNITY_TEST_POLL_TIMEOUT_MS：轮询周期的总超时时间（限制在1000..1800000）
🤖 自主代理功能
智能任务规划
- 目标分解：将复杂任务分解为可管理的子任务
- 优先级管理：基于上下文的动态任务优先级
- 资源分配：系统资源的最佳分配
- 依赖解析：处理任务依赖关系和冲突
学习与适应
- 模式识别：从用户行为和偏好中学习
- 性能优化：随着时间的推移提高效率
- 错误恢复：从错误中吸取教训，避免重复
- 情境感知：适应项目特定要求
多智能体协调
- Agent通信：协调多个专业代理
- 任务分配：在代理实例之间分配工作负载
- 冲突解决：处理相互竞争的优先事项和资源冲突
- 协作式问题解决：结合多个代理视角
🔧 MCP工具和功能
🎮 Unity编辑器工具
- 场景管理：自动创建、修改、优化场景
- 资产运营：智能资产创建和组织
- 游戏对象控制：高级对象操作和优化
- 组件管理：动态组件添加和配置
- 构建自动化：自动化构建流程和优化
🧩 高级开发工具
- 代码生成：AI辅助脚本编写和优化
- 测试自动化：自动创建和执行测试
- 性能分析：实时性能监控和优化
- 调试助手：智能错误检测和解决
- 文档生成：自动生成技术文档
🎯 运行时AI功能
- NPC行为：动态智能NPC行为系统
- 游戏平衡：自动游戏平衡测试和调整
- 玩家分析：实时玩家行为分析
- 动态难度：自适应难度调节系统
- 内容生成：程序内容创建和优化
🔌 插件系统
创建自定义插件以扩展功能：
[AutonomousPlugin("custom-tool")]
public class CustomToolPlugin : IAutonomousTool
{
public async Task ExecuteAsync(ToolContext context)
{
// Your custom tool logic
return new ToolResult { Success = true, Data = result };
}
}📊 性能与监控
实时度量
- 代理性能：监控代理效率和准确性
- 资源使用情况：跟踪CPU、内存和网络利用率
- 任务完成：测量任务成功率和时间
- 学习进度：跟踪代理随时间的改进
优化功能
- 缓存系统：对常用数据进行智能缓存
- 批处理：一起优化多个操作
- 预测性加载：预测并预加载所需资源
- 适应性绩效：根据系统能力调整性能
🛡️ 安全与安保
安全措施
- 沙盒执行：将代理操作与关键系统隔离
- 权限系统：对代理功能的精细控制
- 审计日志：完成所有代理行为的审计跟踪
- 回滚能力：撤消代理修改系统
最佳实践
- 定期备份：主要操作前的自动备份
- 验证检查：执行前验证操作安全
- 用户确认：需要确认破坏性操作
- 错误处理：全面的错误恢复机制
🤝 贡献
我们欢迎捐款！请查看我们的 贡献指南 了解详情。
开发设置
- 克隆存储库
- 安装依赖项(
npm install在服务器目录中） - 开放Unity项目
- 在首选项中启用开发人员模式
- 开始贡献！
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- 受自主代理和人工智能决策最新进展的启发
- 社区的反馈和贡献是无价的
______________________________________________________________________
🚀 准备好用AI驱动的自主性来改变你的Unity开发了吗？
立即开始构建智能、自我改进的Unity项目！