Craft Agents 双后端架构深度解析：Claude Agent SDK 与 Pi SDK 并行的设计权衡

Craft Agents 双后端架构深度解析Claude Agent SDK 与 Pi SDK 并行的设计权衡【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一款开源的 AI 智能体桌面应用它的核心亮点是采用Claude Agent SDK 与 Pi SDK 双后端架构Anthropic 系列模型走 Claude Agent SDK而 Google AI Studio、ChatGPT Plus、GitHub Copilot、OpenAI API 等连接则统一路由到 Pi SDK 后端。本文带你通俗地看懂这套并行架构是怎么工作的以及它背后的设计权衡在哪里。为什么需要双后端先说结论没有任何单一 SDK 能覆盖所有模型厂商。Craft Agents 支持多种 LLM 连接方式详见 README.md连接方式认证方式实际后端AnthropicAPI Key / Claude Max OAuthClaude Agent SDK自定义端点OpenRouter、Ollama 等API Key 自定义 URLClaude Agent SDKGoogle AI StudioAPI KeyPi SDKChatGPT Plus / ProCodex OAuthPi SDKGitHub CopilotOAuth 设备码Pi SDKOpenAI / 兼容端点API KeyPi SDK两个 SDK 各有擅长Claude Agent SDK 提供最成熟的工具调用、原生 Skill 能力与 OAuth 生态Pi SDK 则原生支持多厂商模型注册、Bedrock/Copilot 等渠道扩展性更好。与其二选一Craft Agents 选择让两者并行用统一的抽象层对上提供一致的体验。双后端架构全景 整个后端体系集中在 packages/shared/src/agent/ 目录分层非常清晰CraftAgent 门面Facade │ 统一 API上层不感知具体后端 ▼ BaseAgent 抽象基类 ─── 权限、来源管理、计划、用量统计 │ ├── ClaudeAgent进程内Claude Agent SDK └── PiAgent子进程客户端Pi SDK工厂模式一个入口两种命运后端的选择逻辑由工厂函数统一负责核心实现在 backend/factory.ts配置里provider: anthropic→ 创建ClaudeAgent配置里provider: pi→ 创建PiAgent而该选哪个 provider完全由 LLM 连接类型决定。providerTypeToAgentProvider() 函数把连接的providerType映射到后端anthropic走 Claude 后端pi与pi_compat自定义端点走 Pi 后端。也就是说用户在界面里选了哪个 AI 服务路由就自动完成不需要理解任何架构细节。统一事件协议UI 只认一种方言双后端最大的风险是行为不一致Craft Agents 的解法在 backend/types.ts 中有明确说明Provider-agnostic events: All backends emit the same AgentEvent types所有后端发出同一套 AgentEvent 事件类型具体分工如下base-event-adapter.ts事件适配基类处理公共逻辑claude/event-adapter.ts 与 pi/event-adapter.ts把各自 SDK 的原始消息翻译成标准AgentEventevent-queue.ts统一的事件队列保证流式输出的时序一致结果就是无论底层是 Claude 还是 Pi界面看到的流式文字、工具调用可视化、权限弹窗都一模一样。BaseAgent把 80% 的重复劳动收进基类base-agent.ts 是 ClaudeAgent 和 PiAgent 的共同基类负责抽取所有后端共有的能力模型/思考级别配置、权限模式管理、来源Source管理、计划Plan启发式、配置监听、用量统计等。子类只需要实现chat、abort、capabilities这些每家不一样的部分。这是典型模板方法模式——共性下沉个性上浮。Claude 后端进程内的原生体验ClaudeAgent 直接在 Electron 主进程内运行通过anthropic-ai/claude-agent-sdk的query()流式接口驱动对话。它承担三类连接Anthropic 直连API Key 或 Claude Max/Pro OAuth第三方/自托管端点——借助 SDK 原生支持的自定义 base URL一个连接即可接入 OpenRouter、Vercel AI Gateway、Ollama 等值得注意的细节Claude 后端使用原生 SDK Skill 工具加载工作区技能见 base-agent.ts 的注释无需额外转换能力最完整。Pi 后端子进程隔离的务实选择Pi 后端是整个架构里最有意思的权衡。PiAgent 本身只是个轻量子进程客户端它 spawn 一个独立的pi-agent-server子进程通过 stdin/stdout 上的 JSONL 协议通信。为什么多此一举packages/pi-agent-server/src/index.ts 的文件头注释给出了答案This design isolates the Pi SDKs ESM heavy dependencies into a separate process, avoiding bundling issues in the Electron main process.原因很实际Pi SDK 是纯 ESM 且依赖链很重如果打进 Electron 主进程会产生严重的打包冲突独立成子进程后SDK 崩溃或卡死也不会拖垮主进程主进程只需管理子进程生命周期、转发事件。子进程内部则承担了完整的 Pi SDK 交互会话创建、提示词发送、工具执行、权限执行事件再转发回主进程渲染见 pi-agent-server/src/index.ts。工具名的对应关系维护在 pi/constants.tsPI_TOOL_NAME_MAP思考级别映射为THINKING_TO_PI让两种 SDK 的工具与思考参数说同一种语言。此外Pi 后端通过 session-tool-defs.ts 把会话级工具如call_llm、spawn_session、browser_tool以代理形式注册进子进程实际执行仍在主进程侧完成——这是跨进程架构下保持工具生态统一的关键技巧。模型路由与能力差异的护栏 ⚖️双后端并行最怕的是张冠李戴把 Claude 的模型发给 Pi。Craft Agents 在 resolveModelForProvider() 中设置了跨厂商护栏如果会话存留的模型属于另一个厂商会自动清空并回退到连接的默认模型从根源上避免错配。其他体现权衡的决策维度Claude 后端Pi 后端权衡点运行方式进程内独立子进程 JSONL RPC打包兼容性与进程隔离认证注入环境变量API Key / OAuth初始化时经凭证管理器传入子进程凭证不落明文连接预校验SDK 发一轮最小请求实测连接时校验无预检接口如实暴露各自能力差异默认模型回退回退到 Opus回退到空串由 Pi 内部选择尊重各 SDK 惯例技能Skill原生 SDK Skill 工具手动解析 mention 注入用兼容性补齐能力差距声明式能力表 BACKEND_CAPABILITIES 则让会话层按能力做决策而不是判断 provider 字符串为将来接入第三个后端留好了口子。设计权衡总结 回顾这套双后端架构可以提炼出四条值得借鉴的经验抽象层先行AgentBackend接口 BaseAgent基类 统一事件协议让双后端对外表现为单后端子进程隔离用进程边界解决打包冲突与稳定性问题比硬啃依赖兼容性成本低得多声明式能力而非命令式分支路由、模型、校验都收敛到 driver-types.ts 定义的ProviderDriver驱动里主流程不再散落if provider pi护栏式防御跨厂商模型校验、provider-auth 组合校验llm-connections.ts把配置错误拦在创建之前。代价同样明确双份事件适配器要长期维护跨进程的工具代理增加复杂度子进程还带来一条 JSONL 协议的调试面。但对 Craft Agents 来说用可控的维护成本换来了一个 App 连接所有模型的产品能力——这正是这次设计权衡最值得称道之处。延伸阅读关键源码路径 后端工厂与路由packages/shared/src/agent/backend/factory.ts统一后端接口定义packages/shared/src/agent/backend/types.ts公共基类packages/shared/src/agent/base-agent.tsClaude 后端实现packages/shared/src/agent/claude-agent.tsPi 子进程客户端packages/shared/src/agent/pi-agent.tsPi 独立服务进程packages/pi-agent-server/src/index.ts项目总览与安装指南README.md【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考