拆解 magpie 架构一个不到 15MB 的单二进制如何驱动 20 个 AI 编码 Agent【免费下载链接】magpieEvery agents model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.项目地址: https://gitcode.com/gh_mirrors/magpie28/magpiemagpie 是一款本地 AI 模型网关工具它以不到 15MB 的单个 Go 二进制把 Claude Code、Codex、Gemini CLI 等 20 多个 AI 编码 Agent 统一接到一个本地网关默认127.0.0.1:3425上让你从菜单栏随意切换任意 Agent 的任意模型并在配额耗尽时自动故障转移。本文带你从架构视角拆解这个麻雀虽小、五脏俱全的项目它靠什么做到单二进制、网关如何路由、Agent 配置如何被安全改写、UI 又是如何打包进同一个可执行文件的。整体架构三层结构一张图magpie 的核心是一个常驻本地的LLM 网关它同时说四种线协议OpenAI Chat Completions/v1/chat/completionsOpenAI Responses/v1/responsesAnthropic Messages/v1/messagesGemini generateContent/v1beta/models/…协议之间可以互相翻译——流式输出、工具调用、推理reasoning内容都支持。所以 Codex 可以用 DeepSeekClaude Code 可以用 KimiGemini CLI 可以用 GLM。请求流是这样的你的 AgentClaude Code / Codex / Gemini CLI / 40 ↓ 只改 base URL 和本地 token magpie 网关 127.0.0.1:3425 ↓ 路由组故障转移 / smart / pace 等 5 种模式 你的供应商API Key 厂商、Claude/ChatGPT 订阅、Ollama 本地模型三个关键入口代码都值得一读网关默认地址与本地令牌定义在 gateway.go其中Token magpie每个 Agent 还有专属令牌magpie-agent网关据此识别是谁在说话子系统级设计文档集中在 docs/subsystems/每个子系统一页是理解架构的最佳地图模块拆解44 个 internal 包各司其职magpie 用 Go 1.26 编写见 go.modinternal/下有 44 个包。驱动 20 Agent 的核心是下面这几个1.internal/agent—— 一个 Agent 一个文件这个包有 80 个非测试 Go 文件每个受支持的 Agent 独占一个文件claude.go、codex.go、gemini.go、zed.go、goose.go……新增一个 Agent 基本就是加一个文件。每个 Agent 文件声明三件事概念作用Bin/Dir如何检测本机是否安装了该 AgentPath/Fields配置文件在哪、要改写哪些字段base URL、API key、模型钩子检测、重启提示、WSL 双胞胎处理等可选行为配置改写有两条安全底线设计文档见 agent-wiring.md原子写入只改那一个关键字段注释、顺序、格式原样保留可完全还原magpie 把自己改过什么记在applied.json把改之前的值存在stash.json断开连接时原样恢复而不是靠猜2.internal/gateway—— 108 个文件的心脏网关是整个项目最重的包。它做的事比转发请求多得多模型解析把provider/model解析到供应商、Key 或订阅账号候选与故障转移一个 Key 挂了自动试下一个限流、欠费、配额耗尽分别休息不同时长协议翻译Agent 说 Chat 协议、上游只懂 Messages 时中间自动转译会话亲和一个对话尽量留在同一个账号上好让供应商的 prompt cache 继续命中完整的决策逻辑smart / order / rotate / usage / pace 五种路由模式见 gateway-routing.md。3.internal/provider—— 供应商、Key 与订阅账号三类上游统一抽象成Provider普通 API Key、订阅账号你登录的 Claude、ChatGPT、Copilot直接当供应商给其他 Agent 用、以及插件账号。额度allowance读取、token 自动续期、多账号切换都在这里见 providers-accounts.md。其中最有意思的是 Claude 订阅桥Claude 订阅请求由真正的本地claude二进制代为回答magpie 把工具的调用通过 MCP 桥接过去并让同一会话的多轮对话复用同一个 Claude Code 进程以命中缓存设计细节见 claude-subscription-bridge.md。4.internal/guiinternal/plugin—— UI 与插件宿主GUI 基于 Wails v3但前端 JS 是零框架、零打包器的页面文件通过 Go 的//go:embed直接嵌进二进制api.go 第 135 行页面与 Go 后端走同一个 JSON API。插件则运行在 Bun 上还支持网关中间件形态的 JS 钩子onRequest/onEvent/onResponse。为什么是不到 15MB 的单二进制这是 magpie 工程上最值得新手学习的部分答案藏在 Makefile 和 go.mod 里① 纯 Go几乎零 CGO 依赖。依赖清单非常克制TUI 用 charmbracelet/bubbletea配置解析用手写编辑库 internal/edit/数据库是纯 Go 实现的modernc.org/sqlite不用系统 SQLite所以能任意交叉编译。② 构建标签切换形态。同一份源码两种产物构建标签产物场景production桌面 AppWails 系统 WebView本机 GUInoguiCGO_ENABLED0纯终端 CLI/TUI/Web可交叉编译到任何平台③ 一次性交叉编译 7 个目标。make release-cli循环darwin/linux/windows/android的 amd64/arm64 全部静态产出Docker 镜像Dockerfile更是基于 distroless只有二进制 busyboxNAS 上跑毫无压力。④ UI 不额外下载。窗口、菜单栏面板、magpie web浏览器模式渲染的都是同一份内嵌网页资产换皮肤不需要分发新文件。一个请求的完整旅程新手版以在 Claude Code 里敲下一句话、实际走 DeepSeek为例改写配置magpie 把 Claude Code 的 base URL 指到127.0.0.1:3425key 填magpie-claude见 agent-wiring.md识别来者网关读 token 前缀知道请求来自 Claude Code解析模型deepseek/deepseek-v4-pro→ DeepSeek 供应商 → 选一个有余额的 Key翻译Anthropic Messages 请求 → OpenAI Chat 协议流式返回SSE 逐段回传若中途供应商挂了且一个字节都没发出自动换下一个候选记账token、缓存命中、花费写入 Usage 统计值得延伸阅读的架构文档如果你打算深入源码这些子系统契约文档比任何博客都权威每篇都带源码符号级链接网关路由与回退gateway-routing.mdAgent 配置接线与漂移检测agent-wiring.md供应商与订阅账号生命周期providers-accounts.mdGUI 外壳托盘/面板/窗口/Web 模式gui-shell.md网关中间件插件gateway-middleware.md全量 CLI 命令与端点参考reference.md总结这套架构做对了什么单一职责分层agent管接线gateway管路由翻译provider管钱和账号互不越界可逆性是设计原则applied.jsonstash.json让任何一次配置改写都可精确回滚内嵌优于分发UI、图标、字体全部go:embed用户拿到的就是一个自包含二进制文档即契约docs/subsystems/ 要求每篇子系统文档在行为变化时同步更新架构演进可追溯想亲手把这套网关跑起来一条make cli就能在终端里体验完整的 magpie。【免费下载链接】magpieEvery agents model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.项目地址: https://gitcode.com/gh_mirrors/magpie28/magpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考