1. 项目背景与核心挑战
在AI技术快速发展的今天,开发者经常面临一个现实问题:不同的AI服务提供者各有优势,但它们的接口规范、调用方式和功能特性却各不相同。hagicode项目正是为了解决这一痛点而生,它构建了一个统一的多AI提供者切换与互操作平台。
1.1 核心需求解析
这个项目需要解决四个关键问题:
- 灵活切换:用户可以根据任务需求随时切换不同的AI提供者
- 状态保持:切换过程中需要保持会话状态的连续性
- 接口统一:抽象不同CLI的API差异,提供一致的调用方式
- 扩展预留:为未来可能接入的新AI提供者预留扩展空间
1.2 技术难点剖析
在实际开发中,我们遇到了几个棘手的技术挑战:
- 接口差异:Claude Code CLI通过命令行调用,而Codex CLI使用JSON事件流
- 流式响应:两者都支持流式响应,但数据格式和传输机制完全不同
- 工具调用:不同提供者对工具调用的表示方式和生命周期管理差异显著
- 会话管理:需要精确控制每个提供者的会话创建、恢复和终止过程
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 架构设计与核心组件
2.1 整体架构思路
hagicode采用了经典的提供者模式(Provider Pattern)结合工厂模式的设计方案。这种架构的核心优势在于:
- 解耦:将AI服务的使用与具体实现分离
- 可扩展:新增提供者不影响现有代码
- 统一管理:集中处理公共逻辑如缓存、重试等
架构工作流程如下:
- 定义统一的
IAIProvider接口 - 通过
AIProviderFactory动态创建具体提供者实例 - 使用
AIProviderSelector智能选择最适合当前场景的提供者 - 通过数据库持久化会话状态
2.2 关键组件说明
| 组件名称 | 主要职责 | 实现语言 |
|---|---|---|
IAIProvider |
定义统一的提供者接口 | C# |
AIProviderFactory |
创建和管理提供者实例 | C# |
AIProviderSelector |
根据场景智能选择提供者 | C# |
ClaudeCodeCliProvider |
Claude Code CLI的具体实现 | C# |
CodexCliProvider |
Codex CLI的具体实现 | C# |
AgentCliManager |
桌面端CLI管理 | TypeScript |
3. 核心实现细节
3.1 统一接口设计
IAIProvider接口是整个系统的基石,它定义了所有提供者必须实现的方法:
csharp复制public interface IAIProvider
{
string Name { get; } // 提供者显示名称
bool SupportsStreaming { get; } // 是否支持流式响应
ProviderCapabilities Capabilities { get; } // 能力描述
// 执行单个AI请求
Task<AIResponse> ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default);
// 执行流式AI请求
IAsyncEnumerable<AIStreamingChunk> StreamAsync(AIRequest request, CancellationToken cancellationToken = default);
// 健康检查
Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default);
// 发送带嵌入式命令的消息
IAsyncEnumerable<AIStreamingChunk> SendMessageAsync(
AIRequest request,
string? embeddedCommandPrompt = null,
CancellationToken cancellationToken = default);
}
接口设计的关键考量:
- 统一的请求/响应模型(
AIRequest/AIResponse) - 原生支持异步和取消操作
- 明确的流式处理接口(
IAsyncEnumerable) - 能力描述机制(
ProviderCapabilities)
3.2 提供者工厂实现
AIProviderFactory负责提供者实例的创建和管理:
csharp复制public class AIProviderFactory : IAIProviderFactory
{
private readonly ConcurrentDictionary<AIProviderType, IAIProvider> _cache;
private readonly IOptions<AIProviderOptions> _options;
private readonly IServiceProvider _serviceProvider;
public Task<IAIProvider?> GetProviderAsync(AIProviderType providerType)
{
// 使用缓存避免重复创建
if (_cache.TryGetValue(providerType, out var cached))
return Task.F
