登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 业界 ›Hagicode 多 AI 提供者切换与互操作实现方案 ...

Hagicode 多 AI 提供者切换与互操作实现方案

端木茵茵 昨天 10:55
程序园永久vip申请，500美金$，无限下载程序园所有程序/软件/数据/等
Hagicode 多 AI 提供者切换与互操作实现方案

在现代开发工具生态中，开发者经常需要使用不同的 AI 编码助手来辅助开发工作。Anthropic 的 Claude Code CLI 和 OpenAI 的 Codex CLI 各有其优势：Claude 以出色的代码理解和长上下文处理能力著称，而 Codex 在代码生成和工具使用方面表现优异。
本文将深入分析 hagicode 项目如何实现多个 AI 提供者的无缝切换与互操作，包括核心架构设计、关键实现细节以及实践中的注意事项。
背景

问题域

hagicode 项目面临的核心挑战是在同一平台中支持多种 AI CLI，让用户能够：

  • 根据需求灵活切换不同的 AI 提供者
  • 在切换过程中保持会话状态的连续性
  • 统一抽象不同 CLI 的 API 差异
  • 为未来添加新的 AI 提供者预留扩展空间
技术挑战


  • 接口差异统一：Claude Code CLI 通过命令行调用，Codex CLI 使用 JSON 事件流
  • 流式响应处理：两种提供者都支持流式响应，但数据格式不同
  • 工具调用语义：Claude 和 Codex 对工具调用的表示和生命周期管理不同
  • 会话生命周期：需要正确管理每个提供者的会话创建、恢复和终止
分析

架构设计思路

hagicode 采用了提供者模式（Provider Pattern）结合工厂模式来抽象 AI 服务的调用。这种设计的核心思想是：

  • 统一接口抽象：定义 IAIProvider 接口作为所有 AI 提供者的统一抽象
  • 工厂创建实例：通过 AIProviderFactory 根据类型动态创建对应的提供者实例
  • 智能选择逻辑：使用 AIProviderSelector 根据场景和配置自动选择最合适的提供者
  • 会话状态管理：通过数据库持久化会话与 CLI 线程的绑定关系
关键组件

组件职责语言IAIProvider统一提供者接口C#AIProviderFactory创建和管理提供者实例C#AIProviderSelector智能选择提供者C#ClaudeCodeCliProviderClaude Code CLI 实现C#CodexCliProviderCodex CLI 实现C#AgentCliManager桌面端 CLI 管理TypeScript解决

1. 核心接口设计

IAIProvider 接口 定义了统一的提供者抽象：
  1. public interface IAIProvider
  2. {
  3.     /// <summary>
  4.     /// 提供者显示名称
  5.     /// </summary>
  6.     string Name { get; }
  8.     /// <summary>
  9.     /// 是否支持流式响应
  10.     /// </summary>
  11.     bool SupportsStreaming { get; }
  13.     /// <summary>
  14.     /// 提供者能力描述
  15.     /// </summary>
  16.     ProviderCapabilities Capabilities { get; }
  18.     /// <summary>
  19.     /// 执行单个 AI 请求
  20.     /// </summary>
  21.     Task ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default);
  23.     /// <summary>
  24.     /// 执行流式 AI 请求
  25.     /// </summary>
  26.     IAsyncEnumerable StreamAsync(AIRequest request, CancellationToken cancellationToken = default);
  28.     /// <summary>
  29.     /// 检查提供者连接性和响应速度
  30.     /// </summary>
  31.     Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default);
  33.     /// <summary>
  34.     /// 发送带嵌入式命令的消息
  35.     /// </summary>
  36.     IAsyncEnumerable SendMessageAsync(
  37.         AIRequest request,
  38.         string? embeddedCommandPrompt = null,
  39.         CancellationToken cancellationToken = default);
  40. }
复制代码
接口设计的关键特性：

  • 统一的请求/响应模型：所有提供者使用相同的 AIRequest 和 AIResponse 类型
  • 流式支持：通过 IAsyncEnumerable 统一流式输出
  • 能力描述：ProviderCapabilities 描述提供者支持的功能（流式、工具、最大 token 等）
  • 嵌入式命令：SendMessageAsync 支持将 OpenSpec 命令嵌入到提示中
2. 提供者类型枚举
  1. public enum AIProviderType
  2. {
  3.     ClaudeCodeCli,   // Anthropic Claude Code
  4.     OpenCodeCli,     // 其他 CLI（可扩展）
  5.     GitHubCopilot,    // GitHub Copilot
  6.     CodebuddyCli,    // Codebuddy
  7.     CodexCli         // OpenAI Codex
  8. }
复制代码
这个枚举为系统支持的所有提供者提供了类型安全的表示。
3. 工厂模式实现

AIProviderFactory 负责创建和管理提供者实例：
  1. public class AIProviderFactory : IAIProviderFactory
  2. {
  3.     private readonly ConcurrentDictionary _cache;
  4.     private readonly IOptions _options;
  5.     private readonly IServiceProvider _serviceProvider;
  7.     public Task<IAIProvider?> GetProviderAsync(AIProviderType providerType)
  8.     {
  9.         // 使用缓存避免重复创建
  10.         if (_cache.TryGetValue(providerType, out var cached))
  11.             return Task.FromResult<IAIProvider?>(cached);
  13.         // 从配置中获取提供者配置
  14.         var aiOptions = _options.Value;
  15.         if (!aiOptions.Providers.TryGetValue(providerType, out var config))
  16.         {
  17.             _logger.LogWarning("Provider '{ProviderType}' not found in configuration", providerType);
  18.             return Task.FromResult<IAIProvider?>(null);
  19.         }
  21.         // 根据类型创建提供者
  22.         var provider = providerType switch
  23.         {
  24.             AIProviderType.ClaudeCodeCli =>
  25.                 _serviceProvider.GetService(typeof(ClaudeCodeCliProvider)) as IAIProvider,
  26.             AIProviderType.CodexCli =>
  27.                 _serviceProvider.GetService(typeof(CodexCliProvider)) as IAIProvider,
  28.             AIProviderType.GitHubCopilot =>
  29.                 _serviceProvider.GetService(typeof(CopilotAIProvider)) as IAIProvider,
  30.             _ => null
  31.         };
  33.         if (provider != null)
  34.         {
  35.             _cache[providerType] = provider;
  36.         }
  38.         return Task.FromResult<IAIProvider?>(provider);
  39.     }
  40. }
复制代码
工厂模式的优势：

  • 实例缓存：避免重复创建相同类型的提供者
  • 依赖注入：通过 IServiceProvider 创建实例，支持依赖注入
  • 配置驱动：从配置文件读取提供者配置
  • 异常处理：创建失败时返回 null，便于上层处理
4. 智能选择器

AIProviderSelector 实现提供者选择策略：
  1. public class AIProviderSelector : IAIProviderSelector
  2. {
  3.     private readonly BusinessLayerConfiguration _configuration;
  4.     private readonly IAIProviderFactory _providerFactory;
  5.     private readonly IMemoryCache _cache;
  7.     public async Task SelectProviderAsync(
  8.         BusinessScenario scenario,
  9.         CancellationToken cancellationToken = default)
  10.     {
  11.         // 1. 尝试从场景映射获取提供者
  12.         if (_configuration.ScenarioProviderMapping.TryGetValue(scenario, out var providerType))
  13.         {
  14.             if (await IsProviderAvailableAsync(providerType, cancellationToken))
  15.             {
  16.                 _logger.LogDebug("Selected provider '{Provider}' for scenario '{Scenario}'",
  17.                     providerType, scenario);
  18.                 return providerType;
  19.             }
  21.             _logger.LogWarning("Configured provider '{Provider}' for scenario '{Scenario}' is not available",
  22.                 providerType, scenario);
  23.         }
  25.         // 2. 尝试使用默认提供者
  26.         if (await IsProviderAvailableAsync(_configuration.DefaultProvider, cancellationToken))
  27.         {
  28.             _logger.LogDebug("Using default provider '{Provider}' for scenario '{Scenario}'",
  29.                 _configuration.DefaultProvider, scenario);
  30.             return _configuration.DefaultProvider;
  31.         }
  33.         // 3. 尝试回退链
  34.         foreach (var fallbackProvider in _configuration.FallbackChain)
  35.         {
  36.             if (await IsProviderAvailableAsync(fallbackProvider, cancellationToken))
  37.             {
  38.                 _logger.LogInformation("Using fallback provider '{Provider}' for scenario '{Scenario}'",
  39.                     fallbackProvider, scenario);
  40.                 return fallbackProvider;
  41.             }
  42.         }
  44.         // 4. 无法找到可用提供者
  45.         throw new InvalidOperationException(
  46.             $"No available AI provider found for scenario '{scenario}'");
  47.     }
  49.     public async Task<bool> IsProviderAvailableAsync(
  50.         AIProviderType providerType,
  51.         CancellationToken cancellationToken = default)
  52.     {
  53.         var cacheKey = $"provider_available_{providerType}";
  55.         // 使用缓存减少 Ping 调用
  56.         if (_configuration.EnableCache &&
  57.             _cache.TryGetValue<bool>(cacheKey, out var cached))
  58.         {
  59.             return cached;
  60.         }
  62.         var provider = await _providerFactory.GetProviderAsync(providerType);
  63.         var isAvailable = provider != null;
  65.         if (_configuration.EnableCache && isAvailable)
  66.         {
  67.             _cache.Set(cacheKey, isAvailable,
  68.                 TimeSpan.FromSeconds(_configuration.CacheExpirationSeconds));
  69.         }
  71.         return isAvailable;
  72.     }
  73. }
复制代码
选择器策略：

  • 场景映射优先：首先检查业务场景是否有特定的提供者映射
  • 默认提供者回退：场景映射失败时使用默认提供者
  • 回退链兜底：逐个尝试回退链中的提供者
  • 可用性缓存：缓存提供者可用性检查结果，减少 Ping 调用
5. Claude Code CLI 提供者实现
  1. public class ClaudeCodeCliProvider : IAIProvider
  2. {
  3.     private readonly ILogger<ClaudeCodeCliProvider> _logger;
  4.     private readonly IClaudeStreamManager _streamManager;
  5.     private readonly ProviderConfiguration _config;
  7.     public string Name => "ClaudeCodeCli";
  8.     public bool SupportsStreaming => true;
  10.     public ProviderCapabilities Capabilities { get; }
  12.     public async Task ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default)
  13.     {
  14.         _logger.LogInformation("Executing AI request with provider: {Provider}", Name);
  16.         var sessionOptions = ClaudeRequestMapper.MapToSessionOptions(request, _config);
  18.         var messages = _streamManager.SendMessageAsync(request.Prompt, sessionOptions, cancellationToken);
  20.         var responseBuilder = new StringBuilder();
  21.         ResultMessage? finalResult = null;
  23.         await foreach (var streamMessage in messages)
  24.         {
  25.             switch (streamMessage.Message)
  26.             {
  27.                 case ResultMessage result:
  28.                     finalResult = result;
  29.                     responseBuilder.Append(result.Result);
  30.                     break;
  31.             }
  32.         }
  34.         if (finalResult != null)
  35.         {
  36.             return ClaudeResponseMapper.MapToAIResponse(finalResult, Name);
  37.         }
  39.         return new AIResponse
  40.         {
  41.             Content = responseBuilder.ToString(),
  42.             FinishReason = FinishReason.Unknown,
  43.             Provider = Name
  44.         };
  45.     }
  46. }
复制代码
Claude Code CLI 提供者的特点：

  • 流式管理器集成：使用 IClaudeStreamManager 与 Claude CLI 通信
  • CessionId 会话隔离：使用 CessionId 作为会话唯一标识，与系统 sessionId 区分
  • 工作目录配置：支持配置工作目录、权限模式等
  • 工具支持：支持 AllowedTools、DisallowedTools 等工具权限配置
6. Codex CLI 提供者实现
  1. public class CodexCliProvider : IAIProvider
  2. {
  3.     private readonly ILogger _logger;
  4.     private readonly CodexSettings _settings;
  5.     private readonly ConcurrentDictionary<string, string> _sessionThreadBindings;
  7.     public string Name => "CodexCli";
  8.     public bool SupportsStreaming => true;
  10.     public ProviderCapabilities Capabilities { get; }
  12.     public async IAsyncEnumerable StreamAsync(
  13.         AIRequest request,
  14.         [EnumeratorCancellation] CancellationToken cancellationToken = default)
  15.     {
  16.         _logger.LogInformation("Executing streaming AI request with provider: {Provider}", Name);
  18.         var codex = CreateCodexClient();
  19.         var thread = ResolveThread(codex, request);
  21.         var currentTurn = 0;
  22.         var activeToolCalls = new Dictionary<string, AIToolCallDelta>();
  24.         await foreach (var threadEvent in thread.RunStreamedAsync(BuildPrompt(request), cancellationToken))
  25.         {
  26.             if (threadEvent is TurnStartedEvent)
  27.             {
  28.                 currentTurn++;
  29.             }
  31.             switch (threadEvent)
  32.             {
  33.                 case ItemCompletedEvent { Item: AgentMessageItem message }:
  34.                     var messageText = message.Text ?? string.Empty;
  35.                     yield return new AIStreamingChunk
  36.                     {
  37.                         Content = messageText,
  38.                         Type = StreamingChunkType.ContentDelta,
  39.                         IsComplete = false
  40.                     };
  41.                     break;
  43.                 case ItemStartedEvent or ItemUpdatedEvent or ItemCompletedEvent:
  44.                     var toolChunk = BuildToolChunk(threadEvent, currentTurn);
  45.                     if (toolChunk?.ToolCallDelta != null)
  46.                     {
  47.                         yield return toolChunk;
  48.                     }
  49.                     break;
  51.                 case TurnCompletedEvent turnCompleted:
  52.                     activeToolCalls.Clear();
  53.                     yield return new AIStreamingChunk
  54.                     {
  55.                         Content = string.Empty,
  56.                         Type = StreamingChunkType.Metadata,
  57.                         IsComplete = true,
  58.                         Usage = MapUsage(turnCompleted.Usage)
  59.                     };
  60.                     break;
  61.             }
  62.         }
  64.         BindSessionThread(request.SessionId, thread.Id);
  65.     }
  67.     private CodexThread ResolveThread(Codex codex, AIRequest request)
  68.     {
  69.         var sessionId = request.SessionId;
  71.         // 检查是否已有绑定的线程
  72.         if (!string.IsNullOrWhiteSpace(sessionId) &&
  73.             _sessionThreadBindings.TryGetValue(sessionId, out var threadId) &&
  74.             !string.IsNullOrWhiteSpace(threadId))
  75.         {
  76.             _logger.LogInformation("Resuming Codex thread {ThreadId} for session {SessionId}", threadId, sessionId);
  77.             return codex.ResumeThread(threadId, threadOptions);
  78.         }
  80.         _logger.LogInformation("Starting new Codex thread for session {SessionId}", sessionId ?? "(none)");
  81.         return codex.StartThread(threadOptions);
  82.     }
  83. }
复制代码
Codex CLI 提供者的特点：

  • JSON 事件流处理：解析 Codex 的 JSON 事件流（TurnStarted、ItemStarted、TurnCompleted 等）
  • 会话线程绑定：使用 SQLite 数据库持久化会话与线程的绑定关系
  • 线程复用：支持恢复已有线程，保持会话连续性
  • 工具调用追踪：追踪活动工具调用状态，正确处理工具生命周期
7. 会话线程绑定机制

Codex CLI 使用 SQLite 数据库持久化会话与线程的绑定：
  1. public class CodexCliProvider : IAIProvider
  2. {
  3.     private const int SessionThreadBindingRetentionDays = 30;
  4.     private readonly ConcurrentDictionary<string, string> _sessionThreadBindings;
  5.     private readonly string _sessionThreadBindingDatabaseConnectionString;
  6.     private readonly string _sessionThreadBindingDatabasePath;
  8.     private void BindSessionThread(string? sessionId, string? threadId)
  9.     {
  10.         if (string.IsNullOrWhiteSpace(sessionId) || string.IsNullOrWhiteSpace(threadId))
  11.         {
  12.             return;
  13.         }
  15.         // 内存缓存
  16.         _sessionThreadBindings.AddOrUpdate(sessionId, threadId, (_, _) => threadId);
  18.         // 持久化到 SQLite
  19.         PersistSessionThreadBinding(sessionId, threadId);
  20.     }
  22.     private void PersistSessionThreadBinding(string sessionId, string threadId)
  23.     {
  24.         try
  25.         {
  26.             using var connection = new SqliteConnection(_sessionThreadBindingDatabaseConnectionString);
  27.             connection.Open();
  29.             using var upsertCommand = connection.CreateCommand();
  30.             upsertCommand.CommandText =
  31.                 """
  32.                 INSERT INTO SessionThreadBindings (SessionId, ThreadId, CreatedAtUtc, UpdatedAtUtc)
  33.                 VALUES ($sessionId, $threadId, $createdAtUtc, $updatedAtUtc)
  34.                 ON CONFLICT(SessionId) DO UPDATE SET
  35.                     ThreadId = excluded.ThreadId,
  36.                     UpdatedAtUtc = excluded.UpdatedAtUtc;
  37.                 """;
  38.             var nowUtc = DateTimeOffset.UtcNow.ToString("O");
  39.             upsertCommand.Parameters.AddWithValue("$sessionId", sessionId);
  40.             upsertCommand.Parameters.AddWithValue("$threadId", threadId);
  41.             upsertCommand.Parameters.AddWithValue("$createdAtUtc", nowUtc);
  42.             upsertCommand.Parameters.AddWithValue("$updatedAtUtc", nowUtc);
  43.             upsertCommand.ExecuteNonQuery();
  44.         }
  45.         catch (Exception ex)
  46.         {
  47.             _logger.LogWarning(
  48.                 ex,
  49.                 "Failed to persist Codex session-thread binding for session {SessionId} to {DatabasePath}",
  50.                 sessionId,
  51.                 _sessionThreadBindingDatabasePath);
  52.         }
  53.     }
  55.     private void LoadPersistedSessionThreadBindings()
  56.     {
  57.         using var connection = new SqliteConnection(_sessionThreadBindingDatabaseConnectionString);
  58.         connection.Open();
  60.         using var loadCommand = connection.CreateCommand();
  61.         loadCommand.CommandText = "SELECT SessionId, ThreadId FROM SessionThreadBindings;";
  62.         using var reader = loadCommand.ExecuteReader();
  63.         while (reader.Read())
  64.         {
  65.             var sessionId = reader.GetString(0);
  66.             var threadId = reader.GetString(1);
  67.             _sessionThreadBindings[sessionId] = threadId;
  68.         }
  69.     }
  70. }
复制代码
会话线程绑定的优势：

  • 会话恢复：系统重启后可以恢复之前的会话
  • 线程复用：同一会话可以复用已有的 Codex 线程
  • 自动清理：超过 30 天的绑定会被自动清理
8. 桌面端 CLI 管理

hagicode-desktop 通过 AgentCliManager 管理 CLI 选择：
  1. export enum AgentCliType {
  2.   ClaudeCode = 'claude-code',
  3.   Codex = 'codex',
  4.   // 未来可扩展: Aider, Cursor 等其他 CLI
  5. }
  7. export class AgentCliManager {
  8.   private static readonly STORE_KEY = 'agentCliSelection';
  9.   private static readonly EXECUTOR_TYPE_MAP: Record = {
  10.     [AgentCliType.ClaudeCode]: 'ClaudeCodeCli',
  11.     [AgentCliType.Codex]: 'CodexCli',
  12.   };
  14.   constructor(private store: any) {}
  16.   async saveSelection(cliType: AgentCliType): Promise<void> {
  17.     const selection: StoredAgentCliSelection = {
  18.       cliType,
  19.       isSkipped: false,
  20.       selectedAt: new Date().toISOString(),
  21.     };
  23.     this.store.set(AgentCliManager.STORE_KEY, selection);
  24.   }
  26.   loadSelection(): StoredAgentCliSelection {
  27.     return this.store.get(AgentCliManager.STORE_KEY, {
  28.       cliType: null,
  29.       isSkipped: false,
  30.       selectedAt: null,
  31.     });
  32.   }
  34.   getCommandName(cliType: AgentCliType): string {
  35.     switch (cliType) {
  36.       case AgentCliType.ClaudeCode:
  37.         return 'claude';
  38.       case AgentCliType.Codex:
  39.         return 'codex';
  40.       default:
  41.         return 'claude';
  42.     }
  43.   }
  45.   getExecutorType(cliType: AgentCliType | null): string {
  46.     if (!cliType) return 'ClaudeCodeCli';
  47.     return this.EXECUTOR_TYPE_MAP[cliType] || 'ClaudeCodeCli';
  48.   }
  49. }
复制代码
桌面端 IPC 处理器示例：
  1. ipcMain.handle('llm:call-api', async (event, manifestPath, region) => {
  2.   if (!state.llmInstallationManager) {
  3.     return { success: false, error: 'LLM Installation Manager not initialized' };
  4.   }
  6.   try {
  7.     const prompt = await state.llmInstallationManager.loadPrompt(manifestPath, region);
  9.     // 根据用户选择确定 CLI 命令
  10.     let commandName = 'claude';
  11.     if (state.agentCliManager) {
  12.       const selectedCliType = state.agentCliManager.getSelectedCliType();
  13.       if (selectedCliType) {
  14.         commandName = state.agentCliManager.getCommandName(selectedCliType);
  15.       }
  16.     }
  18.     // 使用对应的 CLI 执行
  19.     const result = await state.llmInstallationManager.callApi(
  20.       prompt.filePath,
  21.       event.sender,
  22.       commandName
  23.     );
  25.     return result;
  26.   } catch (error) {
  27.     return {
  28.       success: false,
  29.       error: error instanceof Error ? error.message : 'Unknown error'
  30.     };
  31.   }
  32. });
复制代码
9. Codex 内部的模型提供者系统

Codex 本身也支持多种模型提供者，通过 ModelProviderInfo 配置：
  1. pub const OPENAI_PROVIDER_NAME: &str = "OpenAI";
  2. pub const OLLAMA_OSS_PROVIDER_ID: &str = "ollama";
  3. pub const LMSTUDIO_OSS_PROVIDER_ID: &str = "lmstudio";
  5. pub fn built_in_model_providers() -> HashMap<String, ModelProviderInfo> {
  6.     use ModelProviderInfo as P;
  8.     [
  9.         ("openai", P::create_openai_provider()),
  10.         (OLLAMA_OSS_PROVIDER_ID, create_oss_provider(DEFAULT_OLLAMA_PORT, WireApi::Responses)),
  11.         (LMSTUDIO_OSS_PROVIDER_ID, create_oss_provider(DEFAULT_LMSTUDIO_PORT, WireApi::Responses)),
  12.     ]
  13.     .into_iter()
  14.     .map(|(k, v)| (k.to_string(), v))
  15.     .collect()
  16. }
  18. pub struct ModelProviderInfo {
  19.     pub name: String,
  20.     pub base_url: Option<String>,
  21.     pub env_key: Option<String>,
  22.     pub query_params: Option<HashMap<String, String>>,
  23.     pub http_headers: Option<HashMap<String, String>>,
  24.     pub request_max_retries: Option<u64>,
  25.     pub stream_max_retries: Option<u64>,
  26.     pub stream_idle_timeout_ms: Option<u64>,
  27.     pub requires_openai_auth: bool,
  28.     pub supports_websockets: bool,
  29. }
复制代码
Codex 的模型提供者支持：

  • 内置提供者：OpenAI、Ollama、LM Studio
  • 自定义提供者：用户可在 config.toml 中添加自定义提供者
  • 重试策略：可配置请求和流的重试次数
  • WebSocket 支持：部分提供者支持 WebSocket 传输
实践

配置示例

appsettings.json 配置多个提供者：
  1. {
  2.   "AI": {
  3.     "Providers": {
  4.       "DefaultProvider": "ClaudeCodeCli",
  5.       "Providers": {
  6.         "ClaudeCodeCli": {
  7.           "Type": "ClaudeCodeCli",
  8.           "Model": "claude-sonnet-4-20250514",
  9.           "WorkingDirectory": "/path/to/workspace",
  10.           "PermissionMode": "acceptEdits",
  11.           "AllowedTools": ["file-edit", "command-run", "bash"]
  12.         },
  13.         "CodexCli": {
  14.           "Type": "CodexCli",
  15.           "Model": "gpt-4.1",
  16.           "ExecutablePath": "codex",
  17.           "SandboxMode": "enabled",
  18.           "WebSearchMode": "auto",
  19.           "NetworkAccessEnabled": false
  20.         }
  21.       },
  22.       "ScenarioProviderMapping": {
  23.         "CodeAnalysis": "ClaudeCodeCli",
  24.         "CodeGeneration": "CodexCli",
  25.         "Refactoring": "ClaudeCodeCli",
  26.         "Debugging": "CodexCli"
  27.       },
  28.       "FallbackChain": ["CodexCli", "ClaudeCodeCli"]
  29.     },
  30.     "Selector": {
  31.       "EnableCache": true,
  32.       "CacheExpirationSeconds": 300
  33.     }
  34.   }
  35. }
复制代码
使用示例 - 后端服务
  1. public class AIOrchestrator
  2. {
  3.     private readonly IAIProviderFactory _providerFactory;
  4.     private readonly IAIProviderSelector _providerSelector;
  5.     private readonly ILogger _logger;
  7.     public AIOrchestrator(
  8.         IAIProviderFactory providerFactory,
  9.         IAIProviderSelector providerSelector,
  10.         ILogger logger)
  11.     {
  12.         _providerFactory = providerFactory;
  13.         _providerSelector = providerSelector;
  14.         _logger = logger;
  15.     }
  17.     public async Task ProcessRequestAsync(
  18.         AIRequest request,
  19.         BusinessScenario scenario)
  20.     {
  21.         _logger.LogInformation("Processing request for scenario: {Scenario}", scenario);
  23.         try
  24.         {
  25.             // 智能选择提供者
  26.             var providerType = await _providerSelector.SelectProviderAsync(scenario, request.CancellationToken);
  28.             // 获取提供者实例
  29.             var provider = await _providerFactory.GetProviderAsync(providerType);
  30.             if (provider == null)
  31.             {
  32.                 throw new InvalidOperationException($"Provider {providerType} not available");
  33.             }
  35.             _logger.LogInformation("Using provider: {Provider} for request", provider.Name);
  37.             // 执行请求
  38.             var response = await provider.ExecuteAsync(request, request.CancellationToken);
  40.             _logger.LogInformation("Request completed with provider: {Provider}, tokens used: {Tokens}",
  41.                 provider.Name,
  42.                 response.Usage?.TotalTokens ?? 0);
  44.             return response;
  45.         }
  46.         catch (Exception ex)
  47.         {
  48.             _logger.LogError(ex, "Failed to process request for scenario: {Scenario}", scenario);
  49.             throw;
  50.         }
  51.     }
  52. }
复制代码
使用示例 - 流式响应
  1. public async IAsyncEnumerable StreamResponseAsync(
  2.     AIRequest request,
  3.     BusinessScenario scenario)
  4. {
  5.     var providerType = await _providerSelector.SelectProviderAsync(scenario);
  6.     var provider = await _providerFactory.GetProviderAsync(providerType);
  8.     if (provider == null)
  9.     {
  10.         throw new InvalidOperationException($"Provider {providerType} not available");
  11.     }
  13.     await foreach (var chunk in provider.StreamAsync(request))
  14.     {
  15.         // 处理流式块
  16.         switch (chunk.Type)
  17.         {
  18.             case StreamingChunkType.ContentDelta:
  19.                 // 实时显示文本内容
  20.                 await SendToClientAsync(chunk.Content);
  21.                 break;
  23.             case StreamingChunkType.ToolCallDelta:
  24.                 // 处理工具调用
  25.                 await HandleToolCallAsync(chunk.ToolCallDelta);
  26.                 break;
  28.             case StreamingChunkType.Metadata:
  29.                 // 处理完成事件和统计
  30.                 if (chunk.IsComplete)
  31.                 {
  32.                     _logger.LogInformation("Stream completed, usage: {@Usage}", chunk.Usage);
  33.                 }
  34.                 break;
  36.             case StreamingChunkType.Error:
  37.                 // 处理错误
  38.                 _logger.LogError("Stream error: {Error}", chunk.ErrorMessage);
  39.                 throw new InvalidOperationException(chunk.ErrorMessage);
  40.         }
  41.     }
  42. }
复制代码
使用示例 - OpenSpec 命令
  1. public async Task<string> ExecuteOpenSpecCommandAsync(
  2.     string command,
  3.     string arguments,
  4.     BusinessScenario scenario)
  5. {
  6.     var providerType = await _providerSelector.SelectProviderAsync(scenario);
  7.     var provider = await _providerFactory.GetProviderAsync(providerType);
  9.     // 构建嵌入式命令提示
  10.     var commandPrompt = $"""
  11.         Execute the following OpenSpec command:
  12.         Command: {command}
  13.         Arguments: {arguments}
  15.         Please execute this command and return the results.
  16.         """;
  18.     var request = new AIRequest
  19.     {
  20.         Prompt = "Process this command request",
  21.         EmbeddedCommandPrompt = commandPrompt,
  22.         WorkingDirectory = Directory.GetCurrentDirectory()
  23.     };
  25.     var response = await provider.SendMessageAsync(request, commandPrompt);
  27.     return response.Content;
  28. }
复制代码
注意事项

1. 提供者健康检查

在切换提供者前，建议先调用 PingAsync 确保目标提供者可用：
  1. public async Task<bool> IsProviderHealthyAsync(AIProviderType providerType)
  2. {
  3.     var provider = await _providerFactory.GetProviderAsync(providerType);
  4.     if (provider == null) return false;
  6.     var testResult = await provider.PingAsync();
  8.     return testResult.Success &&
  9.            testResult.ResponseTimeMs < 5000; // 5 秒内响应视为健康
  10. }
复制代码
2. 会话隔离

使用 CessionId（Claude）或 ThreadId（Codex）确保会话隔离：

  • Claude Code CLI：使用 CessionId 作为会话唯一标识
  • Codex CLI：使用 ThreadId 作为会话标识
  1. // Claude Code CLI 会话选项
  2. var claudeSessionOptions = new ClaudeSessionOptions
  3. {
  4.     CessionId = CessionId.New(),  // 生成唯一 ID
  5.     WorkingDirectory = workspacePath,
  6.     AllowedTools = allowedTools,
  7.     PermissionMode = PermissionMode.acceptEdits
  8. };
  10. // Codex 线程选项
  11. var codexThreadOptions = new ThreadOptions
  12. {
  13.     Model = "gpt-4.1",
  14.     SandboxMode = "enabled",
  15.     WorkingDirectory = workspacePath
  16. };
复制代码
3. 错误处理

提供者不可用时的回退机制要健壮，确保至少有一个可用提供者：
  1. public async Task ExecuteWithFallbackAsync(
  2.     AIRequest request,
  3.     List preferredProviders)
  4. {
  5.     Exception? lastException = null;
  7.     foreach (var providerType in preferredProviders)
  8.     {
  9.         try
  10.         {
  11.             var provider = await _providerFactory.GetProviderAsync(providerType);
  12.             if (provider == null) continue;
  14.             // 尝试执行
  15.             return await provider.ExecuteAsync(request);
  16.         }
  17.         catch (Exception ex)
  18.         {
  19.             _logger.LogWarning(ex, "Provider {ProviderType} failed, trying next", providerType);
  20.             lastException = ex;
  21.         }
  22.     }
  24.     // 所有提供者都失败
  25.     throw new InvalidOperationException(
  26.         "All preferred providers failed. Last error: " + lastException?.Message,
  27.         lastException);
  28. }
复制代码
4. 配置验证

启动时验证所有配置的提供者设置，避免运行时错误：
  1. public void ValidateConfiguration(AIProviderOptions options)
  2. {
  3.     foreach (var (providerType, config) in options.Providers)
  4.     {
  5.         // 验证可执行文件路径（CLI 类型提供者）
  6.         if (IsCliBasedProvider(providerType))
  7.         {
  8.             if (string.IsNullOrWhiteSpace(config.ExecutablePath))
  9.             {
  10.                 throw new ConfigurationException(
  11.                     $"Provider {providerType} requires ExecutablePath");
  12.             }
  14.             if (!File.Exists(config.ExecutablePath))
  15.             {
  16.                 throw new ConfigurationException(
  17.                     $"Executable not found for {providerType}: {config.ExecutablePath}");
  18.             }
  19.         }
  21.         // 验证 API 密钥（API 类型提供者）
  22.         if (IsApiBasedProvider(providerType))
  23.         {
  24.             if (string.IsNullOrWhiteSpace(config.ApiKey))
  25.             {
  26.                 throw new ConfigurationException(
  27.                     $"Provider {providerType} requires ApiKey");
  28.             }
  29.         }
  31.         // 验证模型名称
  32.         if (string.IsNullOrWhiteSpace(config.Model))
  33.         {
  34.             _logger.LogWarning("No model configured for {ProviderType}, using default", providerType);
  35.         }
  36.     }
  37. }
复制代码
5. 缓存管理

提供者实例会被缓存，注意生命周期管理和内存使用：
  1. // 定期清理缓存
  2. public void ClearInactiveProviders(TimeSpan inactiveThreshold)
  3. {
  4.     var now = DateTimeOffset.UtcNow;
  5.     var keysToRemove = new List();
  7.     foreach (var (type, instance) in _cache)
  8.     {
  9.         // 假设提供者有 LastUsedTime 属性
  10.         if (instance.LastUsedTime.HasValue &&
  11.             now - instance.LastUsedTime.Value > inactiveThreshold)
  12.         {
  13.             keysToRemove.Add(type);
  14.         }
  15.     }
  17.     foreach (var key in keysToRemove)
  18.     {
  19.         _cache.TryRemove(key, out _);
  20.         _logger.LogInformation("Cleared inactive provider: {Provider}", key);
  21.     }
  22. }
复制代码
6. 日志记录

详细记录提供者选择、切换和执行过程，便于调试：
  1. public class AIProviderLogging
  2. {
  3.     private readonly ILogger _logger;
  5.     public void LogProviderSelection(
  6.         BusinessScenario scenario,
  7.         AIProviderType selectedProvider,
  8.         SelectionReason reason)
  9.     {
  10.         _logger.LogInformation(
  11.             "[ProviderSelection] Scenario={Scenario}, Provider={Provider}, Reason={Reason}",
  12.             scenario,
  13.             selectedProvider,
  14.             reason);
  15.     }
  17.     public void LogProviderSwitch(
  18.         AIProviderType fromProvider,
  19.         AIProviderType toProvider,
  20.         string reason)
  21.     {
  22.         _logger.LogWarning(
  23.             "[ProviderSwitch] From={FromProvider} To={ToProvider}, Reason={Reason}",
  24.             fromProvider,
  25.             toProvider,
  26.             reason);
  27.     }
  29.     public void LogProviderError(
  30.         AIProviderType provider,
  31.         Exception error,
  32.         AIRequest request)
  33.     {
  34.         _logger.LogError(error,
  35.             "[ProviderError] Provider={Provider}, RequestLength={Length}, Error={Message}",
  36.             provider,
  37.             request.Prompt.Length,
  38.             error.Message);
  39.     }
  40. }
复制代码
7. 线程安全

ConcurrentDictionary 等并发集合的使用确保线程安全：
  1. public class ThreadSafeProviderCache
  2. {
  3.     private readonly ConcurrentDictionary _cache;
  4.     private readonly ReaderWriterLockSlim _lock = new();
  6.     public IAIProvider? GetProvider(AIProviderType type)
  7.     {
  8.         // 读取操作无需锁
  9.         if (_cache.TryGetValue(type, out var provider))
  10.             return provider;
  12.         // 创建需要写锁
  13.         _lock.EnterWriteLock();
  14.         try
  15.         {
  16.             // 双重检查
  17.             if (_cache.TryGetValue(type, out provider))
  18.                 return provider;
  20.             var newProvider = CreateProvider(type);
  21.             if (newProvider != null)
  22.             {
  23.                 _cache[type] = newProvider;
  24.             }
  25.             return newProvider;
  26.         }
  27.         finally
  28.         {
  29.             _lock.ExitWriteLock();
  30.         }
  31.     }
  32. }
复制代码
8. 数据库迁移

会话线程绑定数据库结构变更时需要考虑数据迁移：
  1. public class SessionThreadMigration
  2. {
  3.     public async Task MigrateAsync(string dbPath)
  4.     {
  5.         var version = await GetSchemaVersionAsync(dbPath);
  7.         if (version >= 2) return; // 已是最新版本
  9.         using var connection = new SqliteConnection(dbPath);
  10.         connection.Open();
  12.         // 迁移到 v2：添加 CreatedAtUtc 列
  13.         if (version < 2)
  14.         {
  15.             _logger.LogInformation("Migrating SessionThreadBindings to v2...");
  17.             using var addColumnCommand = connection.CreateCommand();
  18.             addColumnCommand.CommandText = "ALTER TABLE SessionThreadBindings ADD COLUMN CreatedAtUtc TEXT;";
  19.             addColumnCommand.ExecuteNonQuery();
  21.             using var backfillCommand = connection.CreateCommand();
  22.             backfillCommand.CommandText =
  23.                 """
  24.                 UPDATE SessionThreadBindings
  25.                 SET CreatedAtUtc = COALESCE(NULLIF(UpdatedAtUtc, ''), $nowUtc)
  26.                 WHERE CreatedAtUtc IS NULL OR CreatedAtUtc = '';
  27.                 """;
  28.             backfillCommand.Parameters.AddWithValue("$nowUtc", DateTimeOffset.UtcNow.ToString("O"));
  29.             backfillCommand.ExecuteNonQuery();
  30.         }
  32.         await UpdateSchemaVersionAsync(dbPath, 2);
  33.         _logger.LogInformation("Migration to v2 completed");
  34.     }
  35. }
复制代码
总结

hagicode 通过提供者模式、工厂模式和选择器模式的组合，实现了一个灵活、可扩展的多 AI 提供者架构：

  • 统一接口抽象：IAIProvider 接口屏蔽了不同 CLI 的差异
  • 动态实例创建：AIProviderFactory 支持运行时创建提供者实例
  • 智能选择策略：AIProviderSelector 实现场景驱动的提供者选择
  • 会话状态持久化：通过数据库绑定确保会话连续性
  • 桌面端集成：AgentCliManager 支持用户选择和配置
这种架构设计的优势在于：

  • 可扩展性：添加新的 AI 提供者只需实现 IAIProvider 接口
  • 可测试性：提供者可以独立测试和模拟
  • 可维护性：每个提供者的实现独立，职责单一
  • 用户友好：支持场景自动选择和手动切换
通过这种设计，hagicode 成功实现了 Claude Code CLI 和 Codex CLI 的无缝切换与互操作，为开发者提供了灵活、强大的 AI 编码助手体验。
参考资料


  • HagiCode 项目地址：github.com/HagiCode-org/site
  • HagiCode 官网：hagicode.com
  • Claude Code 官方文档：docs.anthropic.com
  • OpenAI Codex 文档：platform.openai.com
  • Codex SDK 官方仓库：github.com/openai/codex
  • HagiCode 多平台 CLI 支持：https://docs.hagicode.com/blog/hagicode-ai-cli-multi-platform-support/

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！
HagicodeAI提供者切换操作

使用道具 举报

相关推荐
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
端木茵茵
昨天 10:55

0

粉丝关注

20

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫