A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
Unity AI 交互框架
UniAI 是面向 Unity 的 AI 交互框架,提供统一的 Chat、Agent、Tool、MCP、多模态、生成式资产和上下文窗口能力。框架既可用于 Unity Editor 助手,也可嵌入游戏 Runtime。
ModelEntry 描述能力、端点、行为和 AdapterId,模型差异由 adapter/dialect 处理,不在 Provider 主流程硬编码模型名。UnityWebRequest 与自定义 SSE 解析实现流式输出。[UniAITool] 自动反射注册,AIAgentRunner 支持多轮 tool loop、工具结果回放和 reasoning 内容回放。IContextProvider 外部上下文注入。gpt-image-2 通过 image dialect 适配。AdapterAttribute 自动发现。| 依赖 | 版本 |
|---|---|
| Unity | 2022.3+ |
| UniTask | 2.3.3+ |
| Newtonsoft.Json | Unity 内置或手动导入 |
通过 Unity Package Manager 添加 Git URL:
https://github.com/PiscesGameDev/UniAI.git
或手动克隆到项目:
git clone https://github.com/PiscesGameDev/UniAI.git Assets/UniAI
UniAI 依赖 UniTask。如项目未安装,可通过 Package Manager 添加:
https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask
打开 Window > UniAI > Manager,在「渠道」Tab 中配置 Claude、OpenAI 或 OpenAI-compatible 服务。
支持环境变量覆盖 API Key,例如:
ANTHROPIC_API_KEYOPENAI_API_KEYGEMINI_API_KEYDEEPSEEK_API_KEY代码创建直连客户端:
using System.Collections.Generic;
using UniAI;
var client = AIClient.Create(new ChannelEntry
{
Protocol = ProviderProtocol.OpenAI,
ApiKey = "your-api-key",
BaseUrl = "https://api.openai.com/v1",
Models = new List<string> { "gpt-4o" }
});
using Cysharp.Threading.Tasks;
using UnityEngine;
using UniAI;
var client = AIClient.Create(UniAISettings.Instance.ToConfig());
var response = await client.SendAsync(new AIRequest
{
Model = "gpt-4o",
SystemPrompt = "你是一个 Unity 游戏开发助手。",
Messages =
{
AIMessage.User("如何优化 Draw Call?")
}
});
if (response.IsSuccess)
Debug.Log(response.Text);
流式响应:
await foreach (var chunk in client.StreamAsync(request))
{
if (!string.IsNullOrEmpty(chunk.DeltaText))
Debug.Log(chunk.DeltaText);
}
结构化输出:
var typed = await client.SendAsync<MyData>(new AIRequest
{
Model = "gpt-4o",
Messages = { AIMessage.User("返回 JSON 格式的角色属性") },
ResponseFormat = AIResponseFormat.JsonSchema<MyData>()
});
多模态输入:
var request = new AIRequest
{
Model = "gpt-4o",
Messages =
{
AIMessage.UserWithImage("分析这张截图", imageBytes, "image/png")
}
};
ModelRegistry 统一管理模型元数据。模型元数据决定能力、默认端点、上下文窗口、行为标志和 adapter。
var entry = ModelRegistry.Get("gpt-image-2");
bool canChat = ModelRegistry.HasCapability("gpt-4o", ModelCapability.Chat);
bool canGenerateImage = ModelRegistry.HasCapability("gpt-image-2", ModelCapability.ImageGen);
int contextWindow = ModelRegistry.GetContextWindow("deepseek-v4-pro");
ModelEndpoint endpoint = ModelRegistry.GetEndpoint("gpt-image-2");
自定义模型可在 Manager 的「模型」Tab 中添加,也可写入 UniAISettings.CustomModels。查找优先级为:用户自定义模型 > 内置预设。
重要字段:
Capabilities: Chat、VisionInput、ImageGen、ImageEdit、Embedding 等。Endpoint: ChatCompletions、ImageGenerations、ImageEdits 等。AdapterId: 显式指定 provider-specific adapter/dialect。Behavior: 框架内置行为标志。BehaviorTags / BehaviorOptions: adapter 私有行为扩展。UniAI 使用 “模型元数据 + adapter/dialect” 处理模型差异。
核心机制:
AdapterAttribute 声明 adapter id、目标扩展点、协议、能力、优先级。AdapterDiscovery 通过反射发现工厂。AdapterRegistry<TFactory> 负责按扩展点维护工厂。AdapterCatalog 为 Editor 提供可选 adapter 列表,并按 ModelEntry + ChannelEntry 过滤兼容项。已使用的扩展点:
ConversationProvider: 对话 Provider 工厂,例如 Claude / OpenAI。OpenAIChatDialect: OpenAI-compatible Chat 差异,例如 DeepSeek thinking reasoning replay。ImageGenerationProvider: 生成式资产 Provider 工厂。OpenAIImageDialect: OpenAI Images API 模型差异,例如 gpt-image-2。新增 OpenAI-compatible Chat 方言时,实现 IOpenAIChatDialectFactory 并添加 AdapterAttribute。新增 OpenAI Images 模型差异时,实现 IOpenAIImageDialectFactory。新增生成式 Provider 时,实现 IGenerativeProviderFactory。
使用 [UniAITool] 标记静态工具类,框架会自动扫描注册。
[UniAITool(
Name = "read_file",
Group = ToolGroups.Core,
Description = "Read file content. Actions: 'read'.",
Actions = new[] { "read" })]
internal static class ReadFileTool
{
public static async UniTask<object> HandleAsync(JObject args, CancellationToken ct)
{
var path = (string)args["path"];
var text = await File.ReadAllTextAsync(path, ct);
return ToolResponse.Success(new { text });
}
public class ReadArgs
{
[ToolParam(Description = "File path to read.")]
public string Path;
}
}
在 Project 中创建 Create > UniAI > Agent Definition,配置:
代码运行 Agent:
var runner = new AIAgentRunner(client, agentDefinition);
await foreach (var evt in runner.RunStreamAsync(messages))
{
switch (evt.Type)
{
case AgentEventType.TextDelta:
Debug.Log(evt.Text);
break;
case AgentEventType.ToolCallStart:
Debug.Log($"Tool: {evt.ToolCall.Name}");
break;
case AgentEventType.ToolCallResult:
Debug.Log(evt.ToolResult);
break;
}
}
Agent 内部已拆分为:
AgentLoop: 多轮 tool loop 状态机。AgentToolExecutor: 本地 Tool 与 MCP Tool 执行。ToolCallArgumentSanitizer: 修复/规范化 tool arguments。AgentMessageFactory: 构造 assistant tool-call history。MCP Server 配置方式:
Create > UniAI > MCP Server Config。npx -y @modelcontextprotocol/server-filesystem .AgentDefinition.McpServers。Agent 启动时会自动连接启用的 MCP Server。MCP Tools 会合并到 Agent 可用工具中;MCP Resources 会通过 McpResourceProvider 注入 ContextPipeline。本地 [UniAITool] 与 MCP Tool 同名时,本地工具优先。
ContextPipeline 负责长对话处理:
IContextProvider 外部上下文注入代码示例:
var pipeline = new ContextPipeline(client);
pipeline.AddProvider(new MyContextProvider());
var processed = await pipeline.ProcessAsync(
messages,
systemPrompt,
modelId,
config.General.ContextWindow,
session,
ct);
Editor Chat 会通过 ConversationContextPreparer 注入 Unity 上下文,例如选中对象、Console、工程资源。Runtime 可通过 IConversationContextProvider 注入自己的上下文来源。
生成式资产通过模型能力和 adapter 自动路由。Editor 内置 manage_generate Tool,可由 Agent 自动调用;代码也可以直接使用 GenerativeProviderRouter。
var config = UniAISettings.Instance.ToConfig();
var model = "gpt-image-2";
var entry = ModelRegistry.Get(model);
var channels = config.FindChannelsForModel(model);
var route = GenerativeProviderRouter.Resolve(channels, entry, model, config.General);
if (route.Provider == null)
{
Debug.LogError(route.Error);
return;
}
var result = await route.Provider.GenerateAsync(new GenerateRequest
{
Prompt = "A stylized Unity editor robot mascot",
AssetType = GenerativeAssetType.Image,
Size = "1024x1024",
Quality = "auto",
OutputFormat = "png",
Count = 1
}, ct);
gpt-image-2 通过 openai.images.gpt-image-2 image dialect 适配生成和编辑请求。图片编辑会根据 dialect 使用 JSON 或 multipart/form-data。
ChatOrchestrator 是对话生命周期编排层,当前职责保持很薄:
ConversationContextPreparer 准备消息。IConversationRunner。AgentEventSessionApplier 将事件应用到 ChatSession。可注入策略:
IConversationContextProvider: 外部上下文来源。IChatSessionPersistence: 会话保存策略。IChatTitlePolicy: 标题生成策略。ToolExecutionGuardFactory: 工具执行守卫,例如 Editor 中的 EditorAgentGuard。var orchestrator = new ChatOrchestrator();
orchestrator.Configure(new ChatOrchestratorDependencies
{
ContextProvider = NullConversationContextProvider.Instance,
Persistence = new ChatHistorySessionPersistence(history),
TitlePolicy = new FirstUserMessageTitlePolicy()
});
orchestrator.EnsureRuntime(config, modelSelector, agentDefinition);
await orchestrator.StreamResponseAsync(new ChatStreamRequest
{
Session = session,
ContextSlots = 0,
Config = config,
ModelId = modelSelector.CurrentModelId
});
菜单:Window > UniAI > Manager
主要 Tab:
[UniAITool] 工具。菜单:Window > UniAI > Chat
能力:
Runtime/
├── Core/
│ ├── AIClient / ChannelManager
│ ├── ChannelRouteSelector / ProviderCache / AIProviderFactoryRegistry
│ ├── Adapters/
│ │ ├── AdapterAttribute / AdapterCatalog
│ │ └── AdapterRegistry / AdapterDiscovery
│ ├── ChatOrchestrator
│ ├── ConversationRuntimeFactory / ConversationRuntime
│ ├── ConversationContextPreparer
│ ├── McpConversationInitializer
│ ├── AgentEventSessionApplier
│ └── ChatSessionPolicies
├── Models/
│ └── AIRequest / AIResponse / AIMessage / AIContent / AITool / AIStreamChunk
├── Providers/
│ ├── Claude/
│ ├── OpenAI/
│ │ └── Chat/
│ ├── IAIProvider / IAIProviderFactory
│ └── JsonSseProviderBase
├── Agent/
│ ├── AIAgentRunner / AgentLoop / AgentToolExecutor
│ └── UniAIToolRegistry / ToolSchemaGenerator / ToolResponse
├── Chat/
│ └── ChatSession / ChatHistoryManager / FileChatHistoryStorage
├── Context/
│ └── ContextPipeline / TokenEstimator / MessageSummarizer / IContextProvider
├── MCP/
│ └── McpClientManager / McpClient / Transports / McpResourceProvider
├── Generative/
│ ├── GenerativeProviderRouter / IGenerativeProviderFactory
│ └── Providers/OpenAI/Images/
└── Http/
└── AIHttpClient / SSEDownloadHandler / SSEParser
Editor 层主要负责 Unity UI 和 Editor 特有注入:
Editor/
├── Setting/ # Manager 窗口和配置 Tab
├── Chat/ # Chat 窗口、StreamingController、ContextCollector
├── Agent/ # Agent 资产扫描和 Inspector
├── MCP/ # MCP Server 管理和 Inspector
└── Tools/ # Editor 内置 [UniAITool]
如果只想在代码中直接调用,可实现 IAIProvider:
public sealed class MyProvider : IAIProvider
{
public string Name => "MyProvider";
public UniTask<AIResponse> SendAsync(AIRequest request, CancellationToken ct)
{
throw new NotImplementedException();
}
public IUniTaskAsyncEnumerable<AIStreamChunk> StreamAsync(AIRequest request, CancellationToken ct)
{
throw new NotImplementedException();
}
}
var client = new AIClient(new MyProvider());
框架级扩展建议优先使用 adapter 工厂:
IAIProviderFactory: 对话 Provider 路由。IOpenAIChatDialectFactory: OpenAI-compatible Chat 模型差异。IGenerativeProviderFactory: 生成式资产 Provider 路由。IOpenAIImageDialectFactory: OpenAI Images 模型差异。所有工厂通过 [Adapter(...)] 自动发现。Editor 的模型编辑界面会通过 AdapterCatalog 展示与模型和渠道兼容的 adapter。
配置来源:
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 | ChannelEntry.EnvVarName + UseEnvVar 覆盖 API Key |
| 2 | UniAISettings.asset | Assets/Resources/UniAI/ 下的运行时配置 |
会话历史默认使用 FileChatHistoryStorage,Editor 存储在 Library/UniAI/History。Runtime 可通过 IChatSessionPersistence 注入自己的保存方式。
Apache License 2.0 - Copyright 2025 PiscesGameDev
mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnos
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
Browser automation using accessibility snapshots instead of screenshots