把AI助手塞进代码库：我们踩过的架构坑

全球开发者都在往项目里塞AI助手，但真正跑顺的没几个。HagiCode团队最近公开了他们集成OpenCode的完整踩坑记录——从"每个会话一个独立进程"的设想，到被迫改成"系统级共享运行时"，中间隔着一堆400 BadRequest和内存爆炸的深夜。

这事得从OpenCode说起。它是GitHub上的一个开源AI编程助手项目，HagiCode想把它接进来当后端模型用，干代码生成、编辑、工作流执行这些活。听起来顺理成章，实际干起来才发现，两个早期方案一个被砍（C# SDK），一个虽然留着但麻烦不断。

最大的坑是架构选型。团队最初设计"每会话独立进程"模型，觉得隔离性好、出问题不怕互相影响。跑起来才发现资源开销高得吓人——进程启动、内存占用、上下文切换，全成了瓶颈。最后被迫重构，改成系统级共享运行时，一套进程服务多个会话。

另一个坑更隐蔽：复用外部端点。有些请求缺了上下文直接抛400 BadRequest，调试时根本摸不清是OpenCode的问题还是调用方式的问题。团队的原话是"全是泪"，最后只能把端点调用逻辑重新梳理，确保上下文传递不丢链。

HagiCode的架构分五层落地。最上层是仓库集成，通过MonoSpecs配置（.hagicode/monospecs.yaml）注册OpenCode仓库，这里有个小决策：不用Git子模块，改用普通仓库+统一脚本（scripts/clone-repos.mjs）管理克隆和同步。理由是子模块的权限和协作问题太头疼。

往下是Provider层，OpenCodeCliProvider实现IAIProvider接口，作为对接外部AI服务的标准抽象。这一层原本要扛"独立进程"的复杂度，重构后改成共享运行时，代码变薄了，但状态管理和错误恢复的逻辑变厚了——会话怎么挂、怎么重启、怎么不丢上下文，都是这里操心。

团队把这段经历整理出来，给后来想集成OpenCode的人当路标。技术分享这事，他们打了个比方：美好的东西不一定要拥有，静静看着它美好就够了。但坑还是得自己填。