开源 AI SDK 设计：先把核心接口做薄

开源 AI SDK 设计先把核心接口做薄一、SDK 最怕第一版就长成框架做开源 AI SDK 时很容易把愿景写得很大支持所有模型、所有工具、所有 Agent、所有存储。结果第一版接口复杂、依赖很重、用户不知道从哪里开始。SDK 的价值不在于包办一切而在于提供稳定、薄、可组合的核心能力。一个好的 AI SDK 应先解决最小闭环统一请求模型、流式输出、错误处理、重试、配置和类型定义。至于 Agent 编排、记忆、插件和 UI可以放在扩展层。核心越薄越容易被不同项目采用。二、分层结构核心小扩展自由flowchart TD A[Core SDK] -- B[Model Client] A -- C[Streaming] A -- D[Error Types] E[Agent Extension] -- A F[Memory Extension] -- A G[UI Adapter] -- A核心层只做稳定抽象。比如generate、stream、embed这类接口可以统一不同供应商的特殊能力可以通过 options 或 provider 扩展。不要为了兼容所有特性把核心接口设计成巨大的配置对象。用户看一眼就想关掉文档。扩展层可以更灵活。Agent、工具调用、向量库、前端 Hook、Node 服务端适配都可以作为独立包。这样用户只安装自己需要的部分依赖更轻维护边界也清楚。三、接口示例少而稳定下面是一个简化的 TypeScript 接口。它不追求覆盖所有场景只表达核心契约。export interface ModelClient { generate(input: GenerateInput): PromiseGenerateOutput; stream(input: GenerateInput): AsyncIterableStreamChunk; } export interface GenerateInput { messages: Array{ role: user | system | assistant; content: string }; temperature?: number; maxTokens?: number; }这个接口的好处是容易理解。用户能很快知道 SDK 做什么。后续接入不同模型时只需要实现ModelClient。如果一开始就把记忆、工具、路由、缓存全塞进GenerateInput核心接口会很快失控。错误类型也要稳定。认证失败、限流、超时、无效请求、解析失败应该分开。调用方需要根据错误类型决定重试、提示用户还是降级。四、开源维护文档比抽象更重要SDK 开源后README 是第一个产品界面。用户想知道如何安装、如何调用、如何处理错误、如何接入自己的模型。不要先写长篇架构理念先给能跑的 20 行代码。开源项目的第一体验往往决定用户是否继续。版本策略也要克制。核心接口一旦发布就不要频繁破坏。实验性能力可以放在experimental命名空间或独立包。这样既能探索又不会让用户每次升级都痛苦。最后依赖要少。AI SDK 不应该因为一个小函数引入半个生态。能用原生能力就用原生能力必须引入依赖时说明原因。少即是多在 SDK 里尤其重要。五、总结开源 AI SDK 的核心应薄而稳定模型调用、流式输出、错误类型和配置管理先做好Agent 与记忆放到扩展层。接口越小用户越容易理解依赖越少项目越容易长期维护。