03 · 技术选型

SDK、框架还是裸写

📚 系列导航：这是《Agent 开发进阶》的第 3 篇（共 24 篇）。上一篇你用光谱给业务定了档，这一篇解决紧接着的问题：用什么写——四条技术路线怎么选，选错了怎么留退路。下一篇：04 · 手写 Agent 循环。

档位一定，群里立刻有人甩给你四个名字：Claude Agent SDK、OpenAI Agents SDK、LangGraph，还有人劝你"别用框架，裸写"。每一派都言之凿凿，你越听越晕。我的建议是先别站队——选型不是信仰问题，是约束条件问题：团队几个人、模型策略是单押还是多备、要定制到多深。这一篇只干一件事：给你一张四路线对比表和一棵三问决策树，半小时做出一个"以后能反悔"的选型。

看完这一篇，你会拿到：

• 一张四条路线对比表（抽象层级/锁定风险/调试体验/生态）
• 一棵三问决策树：团队阶段 × 模型策略 × 定制深度
• 一条保命原则：模型调用永远自己包一层抽象
• 一份含"何时迁移"触发条件的选型 ADR（动手产出）

---

01 四条路线对比：没有全能选手

2026 上半年的格局（各家演进快，以官方文档为准）：

路线	抽象层级	锁定风险	调试体验	生态
Claude Agent SDK	高，内置循环	绑 Claude 系	好	官方生态
OpenAI Agents SDK	高	绑 OpenAI 系为主	好	官方生态
LangGraph	中，状态机	绑框架不绑模型	中，图可视化	社区大
裸写循环	无	零	全透明	全自造

打个比方：官方 SDK 像精装公寓，拎包入住但承重墙不能砸；LangGraph 像毛坯房，水电自己布，麻烦但可控；裸写像自建房，每块砖都懂，但下水道也得自己通。

💡 一句话总结：省事、可控、透明三样只能挑两样——先认清你最不能放弃哪一样。

02 决策树：三个问题走到叶子

第一问处在什么阶段：学习期或验证期 → 裸写（下一篇就带你写），透明度就是学习速度。第二问模型策略：认定深度绑定一家 → 用该家官方 SDK，省下的工程量实打实；要多模型备份或路由 → LangGraph，或"SDK + 自己包一层抽象"。第三问定制深度：流程是复杂多步状态流（可回退、可分支、要断点续跑）→ LangGraph 的状态机合适；流程简单 → 别为用框架而用框架。三问走完还犹豫，默认官方 SDK——当下后悔成本最低的选项。

💡 一句话总结：阶段、模型策略、定制深度三问走完，答案基本只剩一个。

03 本课策略：先裸写懂原理，再上 SDK 提效

本课 04–07 篇会带你裸写完整循环，之后的示例才双路径给（裸写版 + SDK 版）。不是炫技，是我见过太多"被框架绑架"的人：出了 bug 分不清是自己的问题还是框架的问题，只能去 issue 区烧香。懂原理的人换框架是一周的事，不懂的人被框架每次升级牵着走。另一条保命原则不管选哪条路都成立：模型调用永远自己包一层抽象——我吃过亏，深度绑定某框架后想换模型，重写了 60% 的代码；包了抽象层之后，再换模型只改一个文件。

💡 一句话总结：框架可以换、模型可以换，你对原理的理解和你留的抽象层不会背叛你。

04 动手：写一份带"退路"的选型 ADR

任务：为你的项目走一遍三问决策树，写成选型 ADR：背景约束（团队/模型策略/定制深度）、选定路线、放弃路线及原因，以及最关键的一节——何时迁移：写下 2–3 条具体触发条件（如"需要接第二家模型时""框架升级连续两次破坏兼容时""状态流复杂到要断点续跑时"）。

验收标准：ADR 里每条迁移触发条件都是可观察的事件，不是"感觉不合适了"。

两种结果都正常：选了 SDK/框架，没问题，带着抽象层意识去用，04–07 照学，那是你的 debug 底气；选了裸写，也没问题，但把"重试/流式/并行需求出现时评估迁移"写进触发条件——裸写别硬扛生产。

05 小结

你现在应该能：用对比表说清四条路线的取舍、用三问决策树给项目选型、写出含迁移触发条件的 ADR。

选型是可逆决策——前提是留了抽象层。下一篇 04 · 手写 Agent 循环，动手拆引擎：100 行代码看清所有框架的本质。

---

📎 实战案例

工程师深度绑定某框架后想换模型，评估发现要重写 60% 代码，加班两周才迁完。重构时他在模型调用外包了一层自己的抽象接口，半年后再换模型只改一个文件、耗时半天——抽象层是自己留的后路，框架崇拜的代价很贵。

踩坑

• 我深度绑定某框架后想换模型，重写了 60% 代码——从此模型调用永远自己包一层。
• 裸写生产系统，重试/流式/并行全自造，三个月后一半开发时间在修轮子——裸写适合学习和轻量场景。
• 选型 ADR 只写"选什么"没写"何时迁移"，一年后没人说得清当初的约束还成不成立——触发条件和结论同样重要。