HagiCode 是怎么把 13 个 Agent CLI 接到一套系统里的
关于 HagiCode
本文分享的方案，来自我们在 HagiCode 项目里摸爬滚打的实践。HagiCode 是一个 AI 代码助手整合平台，目标很纯粹——用一套安装、一套配置，把主流 Agent CLI 全都接进来给用户用。
"13 个"这个数字是怎么来的
先说一个被反复问到的数字——为什么是 13 个 Agent CLI。
其实答案就藏在AIProviderType这个枚举里，像藏在窗外的竹影里，只要你肯看，就能看见。原始定义长这样：
public enum AIProviderType |
{ |
ClaudeCodeCli = 0, |
CodexCli = 1, |
GitHubCopilot = 2, |
CodebuddyCli = 3, |
OpenCodeCli = 4, |
IFlowCli = 5, // 已废弃 |
HermesCli = 6, |
QoderCli = 7, |
KiroCli = 8, |
KimiCli = 9, |
GeminiCli = 10, |
DeepAgentsCli = 11, |
ReasonixCli = 12, |
PiCli = 13, |
} |
枚举一共 14 个值，可是IFlowCli=5这条路已经走不通了。在AIProviderFactory里，它被显式挡在了门外：
if (providerType == AIProviderType.IFlowCli) |
{ |
throw new NotSupportedException("IFlowCli is no longer supported"); |
} |
再配合IsActivelySupportedProviderType()做一次过滤，真正在系统里"活着"的，就是13 个：Claude Code、Codex、GitHub Copilot、CodeBuddy、OpenCode、Hermes、Qoder、Kiro、Kimi、Gemini、DeepAgents、Reasonix、Pi。
这就是"13"的由来。不是个营销数字，是代码里真真切切数出来的。毕竟数字是不会骗人的，骗人的只是我们自己罢了。
分层架构：把变化关在笼子里
接 13 个 CLI 的核心思路，其实就一句话：让业务代码不关心它调的到底是哪一个。
我们把它拆成了六层，从上往下看：
1. 身份层 ——AIProviderType
枚举就是每个 CLI 的"身份证号"。任何地方提到一个 CLI，都用这个枚举值标识，字符串和枚举之间用ToStringValue()/ToAIProviderType()互转。简单，却不可或缺。
2. 业务契约层 ——IAIProvider/IAIProviderFactory
业务侧只认IAIProvider这个接口，里面定义的是"发一个 prompt、拿到流式回复"这种通用动作。至于底下是 Claude 还是 Codex，业务不关心——就像你写信，只管把信交出去，至于邮差姓什么，谁在乎呢？
3. 适配器层 ——*CliProvider
每个 CLI 对应一个薄适配器，比如PiCliProvider、ReasonixCliProvider、ClaudeCodeCliProvider。这些适配器要做的事情很少：把通用的业务请求翻译成具体 CLI 能懂的参数，再把具体 CLI 的输出翻译回来。它们故意写得很薄，新加一个 CLI，基本就是抄一个现成的，改改而已。
4. 共享运行时层 ——ICliProvider<TOptions>
这一层在HagiCode.Libs里，是真正干脏活累活的地方：跨平台拉起进程、处理 stdio 传输、解析流式输出、处理超时和重试。所有适配器都复用同一套运行时，所以对接一个新 CLI 时，进程管理这块基本不用重写。
打个比方，适配器层是"翻译官"，共享运行时层是"快递公司"。翻译官只管把话说清楚；包裹怎么送、路上堵不堵车，那是快递公司的事。各司其职，世界就清净了。
5. 工厂路由层 ——AIProviderFactory
CreateProvider里一个switch，按AIProviderType实例化对应适配器，顺带校验IsConfigured。这是唯一一处"知道具体类型"的地方，被严格隔离在工厂里。变化只允许在一个角落里发生，其余地方都干干净净。
6. 目录 / UI 投影层 ——main-professions.yaml
这一层有意思，它不是代码，是数据。
主职业清单（"我是个前端"、"我是个后端"、"我是个全栈"这种角色画像）由main-professions.yaml这个预设文件驱动，通过HeroPrimaryProfessionPresetProvider读出来，再投影到前端 UI。新增一个主职业，不需要改一行代码，改 YAML 就行。数据代替代码，省心。
顺便说一句，这块是 HagiCode 重构最大的地方。早期版本里有个叫
AgentCliInstallRegistry的代码内注册表，后来发现维护成本太高——代码写多了，人也就累了——整套被推倒，换成了数据驱动 + 健康监测的方案。这也是为什么 HagiCode 现在能快速扩展职业类型的原因。
安装这事儿怎么解决
13 个 CLI 都要装，每个官方安装方式还不一样，这就是另一座山了。
我们的做法是Docker Compose 预装 + 外部管理兜底。镜像里把主流 CLI（Claude Code、Codex、Copilot、CodeBuddy、OpenCode、Qoder、Kiro、Kimi、Gemini、Pi）都预装好，用户拉镜像就能用，不用自己一条条敲命令。装好了，心情自然也好。
对于需要在本地环境单独装的，安装命令矩阵大概是这样（已核对官方文档）：
| CLI | 官方安装方式 |
|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
| Codex | npm install -g @openai/codex |
| GitHub Copilot | npm install -g @github/copilot |
| CodeBuddy | npm install -g @tencent-ai/codebuddy-code |
| OpenCode | npm i -g opencode-ai@latest |
| Qoder | npm install -g @qoder-ai/qodercli |
| Kiro | curl -fsSL https://cli.kiro.dev/install | bash |
| Kimi | curl -LsSf https://code.kimi.com/install.sh | bash |
| Gemini | npm |
| Hermes | 官方脚本，保留 docs-only 兜底 |
| DeepAgents / Reasonix | 见各自官方文档 |
前端PrimaryProfessionCard.tsx这块也跟着变了——它现在没有"安装 CLI"按钮，而是展示 CLI 可用性、版本探测结果，以及"这个 CLI 由外部管理"的兜底提示。也就是说，装不装得起来由系统层负责，UI 只负责如实反馈状态。状态和逻辑各写一遍，迟早会对不上，那又何必呢？
加一个新 CLI 要做啥
落到实操，在 HagiCode 里加一个新 CLI，大概也就这么几步：
- 在
AIProviderType里加一个枚举值 - 抄一个现成的
*CliProvider，改成新 CLI 的参数和输出解析 - 在
AIProviderFactory的switch里加一行路由 - 如果要进主职业目录，在
main-professions.yaml里配一下 - 镜像里加一条安装命令（或者走外部管理兜底）
整套流程下来，核心改动不超过两百行代码——这便是这套抽象真正的价值。每多接一个 CLI，边际成本都很低，业务代码一行都不用改。条条大路通罗马，只是我们这条路，稍微好走一点罢了。
总结
回头看，"接 13 个 CLI"听着吓人，可拆开看，其实也就两层功夫：
一层是把变化隔离——通过AIProviderType枚举 +IAIProvider契约 + 薄适配器 + 共享运行时，让业务代码和具体 CLI 解耦；另一层是把配置数据化——用main-professions.yaml这种 YAML 预设驱动目录和 UI，避免每加一个东西都要动代码。
这套方案，是我们在 HagiCode 实际开发里踩过坑、迭代过几轮才稳定下来的。如果你正在做类似的"多 Provider 整合"系统，希望这个分层思路能给你一点参考。毕竟，Agent CLI 这两年还会继续冒出来，一个能快速接入新 CLI 的架构，比