搞定 AI 编程工作台的后台分布式难题
做 AI 编程工作台这种产品，后台架构有个很特别是地方：每个用户会话，说到底，就是一个活着的、有状态的、能跟你耗上一两个小时的"生命体"。用户丢一句话进来，系统得挑一个合适的 AI Provider——Claude Code、Codex、Gemini、Kimi、CodeBuddy 等等，光数名字就得掰半天手指头——然后拉起子进程，通过流式通道实时把执行结果推回去，还得在 SignalR 上同步各种状态变更。
这事要搁传统无状态 HTTP + Redis 方案身上，头疼的问题就来了：
- 多 Provider 管理碎了一地。每种 AI CLI 工具有自己的进程模型、自己的流式输出格式、自己的超时脾气，十几套逻辑揉在一起，代码很快就变成了——你懂的——意大利面条。也不是说不能吃，只是吃得胃疼。
- 超时不可控，全看命。一个 AI 操作可能跑三分钟完事，也可能跟你耗上两个小时。用全局统一超时配置？那短操作被无故掐断的场景，啧，想想都替用户委屈。反过来，长操作把线程池吃光，也不是什么美好的画面。
- 并发要精打细算，毕竟 GPU 不是大风刮来的。同时跑太多 AI 操作，机器资源直接拉满；但太保守也不行，花钱买的算力白白晾着，这跟把空调开到 16 度然后盖棉被有什么区别。得按全局许可，精确控住活跃会话数。
- 状态管理复杂到怀疑人生。每个会话有自己的消息队列、阶段状态、绑定的执行器——这些是有状态的数据，硬往无状态 HTTP 模型里塞，就只能拿 Redis 当万能胶水粘。粘是粘上了，然后你就会发现自己写了一座山的序列化/反序列化和分布式锁逻辑。写完之后对着屏幕发呆：我到底在解决业务问题，还是在跟基础设施搏斗？
这几个问题凑在一起，与其说是技术挑战，不如说是架构选型的灵魂拷问。
关于 HagiCode
这些东西不是凭空想出来的。本文分享的方案来自我们在 HagiCode 项目里的真刀真枪踩坑经验。HagiCode 是个面向 AI 协作编程的桌面工作台，它的后台要在单进程里协调十几种 AI CLI 工具，还得给前端提供低延迟的实时响应——说白了，就是又要马儿跑，又要马儿不吃草，还要马儿边跑边唱歌。
下面要讲的 Orleans 架构，正是我们在开发 HagiCode 过程中实打实踩坑、实打实优化出来的东西。如果你觉得这套方案有点意思，那说明我们的工程底子还不赖——那么 HagiCode 本身，或许也值得你多看两眼。
选型：为什么是 Orleans
面对前面的灵魂拷问，我们认认真真看了三条路：
方案 A：无状态 API + Redis 状态管理。逻辑倒也简单——每个请求从 Redis 掏会话状态、执行操作、再写回去。水平扩展确实舒服，但 Redis 状态结构会跟着业务一起膨胀，膨胀到你不知道自己到底在维护一个缓存还是在维护一个隐式的数据库。状态一致性得靠锁，流式通信得额外搭 WebSocket/SSE 路由层。说白了，Redis 在这里就是个共享大字典，真正需要的有状态抽象，它给不了。
方案 B：Actor 模型框架（Dapr / Akka.NET）。Dapr 的 Actor 能力本身够用，但它要求部署 Sidecar——对本地桌面端产品来说，杀鸡用牛刀都算抬举了，简直是开坦克去买菜。Akka.NET 的 Actor 模型更偏向低延迟短任务，动辄一两小时的长生命周期工作流，你得自己操心持久化和恢复，框架不给兜底。
方案 C：Microsoft Orleans。看到 Orleans 的 Virtual Actor 模型的时候，怎么说呢，那种感觉就像——找了半天钥匙，结果发现就在自己口袋里。有几个特性简直是为我们这种场景量身缝制的：
- Activation/Deactivation 自动管理：你不用操心 grain 什么时候生、什么时候死，运行时帮你全包了。一个会话对应一个 grain，会话在 grain 就在，会话结束 grain 自动回收。这种"不用管"的感觉，经历过手动生命周期管理的人才会懂。
IAsyncEnumerable<T>原生流式支持：从 CLI 进程输出到前端展示，全程异步流式，不需要中间缓冲队列。就这一个特性，帮我们省掉了至少上千行手写胶水代码。[AlwaysInterleave]和[ResponseTimeout]：细粒度的并发和超时控制，按接口级配，不是全局一刀切。终于不用在"要么全短、要么全长"之间做痛苦的选择了。- 内置持久化状态（
IPersistentState<T>）：状态自动持久化，不需要再额外搭分布式缓存。省心，真的省心。
评估下来，Orleans 对 HagiCode 后台的核心需求几乎是对号入座：
| 能力 | Orleans 对应方案 |
|---|---|
| 有状态会话 | IPersistentState<T>+ SQLite Shard 持久化 |
| 流式输出 | IAsyncEnumerable<T>原生支持，自动穿透到 SignalR |
| 长超时控制 | [ResponseTimeout("02:00:00")]按接口粒度配置 |
| Provider 多态路由 | ExecutorGrainFactory根据AIProviderType分发 |
| 并发控制 | SessionConcurrencyManager配合 grain 单线程调度 |
五个核心设计决策
选好了工具只是第一步。怎么落地，才是真正见功夫的地方。以下是我们踩过坑、爬起来、拍拍土之后沉淀下来的五个关键设计。有的是经验，有的是教训，有的......算了，反正都写出来你自己看。
1. Facade Grain 模式
整个系统的核心调度 grain 是SessionGrain。但它不直接处理所有逻辑——真要那么干，它会变成一个上万行的上帝类。上帝类这种东西，写的时候觉得自己无所不能，改的时候觉得自己一无是处。
我们把特定领域逻辑委托给两个运行时组件：ChatSessionGrain处理聊天模式，ProposalSessionGrain处理提案模式。
internal partial class SessionGrain( |
ILogger<SessionGrain> logger, |
IServiceProvider serviceProvider, |
IExecutorGrainFactory executorGrainFactory, |
IMessageService messageService, |
[PersistentState("session")] IPersistentState<SessionState> state) |
: Grain, ISessionGrain |
{ |
internal ChatSessionGrain ChatSessionComponent => |
_chatSessionComponent ??= new ChatSessionGrain(RuntimeContext); |
internal ProposalSessionGrain ProposalSessionComponent => |
_proposalSessionComponent ??= new ProposalSessionGrain(RuntimeContext); |
internal ISessionRuntimeComponent GetRuntimeComponent(SessionType sessionType) => |
sessionType switch |
{ |
SessionType.Chat => ChatSessionComponent, |
SessionType.Proposal => ProposalSessionComponent, |
_ => throw new ArgumentOutOfRangeException(nameof(sessionType)) |
}; |
} |
这个模式的设计的干净利落：grain 身份稳定，不随 session 类型变来变去；外部调用者只管和ISessionGrain打交道，里面怎么分活它不操心；组件本身无状态，随时可以按需重建；两者共享同一份SessionState持久化状态，数据一致性天然搞定。谁说架构设计不能优雅来着？
2. 多态执行器工厂
HagiCode 支持十几种 AI CLI 工具，每种都要独立的进程管理和流式输出。我们为每种工具实现了一个专用 grain——ClaudeCodeGrain、CodexGrain、GeminiGrain等等，名儿列出来跟点名似的。然后靠工厂统一路由：
internal sealed class ExecutorGrainFactory : IExecutorGrainFactory |
{ |
public IExecutorStreamGrain GetExecutorGrain( |
AIProviderType executorType, CessionId cessionId) |
{ |
return executorType switch |
{ |
AIProviderType.ClaudeCodeCli => ExecutorStreamGrainAdapter.From( |
_grainFactory.GetGrain<IClaudeCodeGrain>(cessionId.Value)), |
AIProviderType.CodexCli => ExecutorStreamGrainAdapter.From( |
_grainFactory.GetGrain<ICodexGrain>(cessionId.Value)), |
AIProviderType.GeminiCli => ExecutorStreamGrainAdapter.From( |
_grainFactory.GetGrain<IGeminiGrain>(cessionId.Value)), |
// ... 10+ providers |
_ => throw new NotSupportedException( |
$"Unsupported executor type: {executorType}") |
}; |
} |
} |
所有执行器 grain 实现同一个IExecutorStreamGrain接口，通过ExecutorStreamGrainAdapter做统一适配。上层代码完全不感知底下用的是哪个 Provider——加一个新工具？新增一个 grain 类，在工厂的 switch 里加一行，完事。这种扩展点，怎么说呢，像是给未来的自己留了一扇门，门后面也不用什么复杂的迷宫，径直走进去就好。
3. 流式通信管道
Orleans 对IAsyncEnumerable<T>的原生支持，让流式输出变得特别自然。以ClaudeCodeGrain为例：
public async IAsyncEnumerable<ClaudeCodeResponse> ExecuteCommandStreamAsync( |
string command, |
string? heroId, |
[EnumeratorCancellation] CancellationToken token = default) |
{ |
var (provider, configuration) = await CreateProviderAsync(heroId, token); |
await foreach (var response in SendAsync(command, provider, context, token)) |
{ |
yield return response; |
} |
} |
整个管道是这样的：CLI 进程 stdout → grain 流式 yield →ExecutorGrainFactory包装为SessionMessage→SessionGrain通过 SignalR 推到前端。每一步都是异步流式的，没有中间缓冲，没有同步阻塞。这也是 Orleans 相比传统方案最爽的一点——你不需要在 grain 内部维护一个ConcurrentQueue然后手动推，yield return四个字搞定