读完了字节 Eino 全部源码：用 Go 的哲学重做 LLM 编排，Pregel 引擎把并发和流式全收编了
如果你用 Go 写过 LLM 应用，大概率遇到过这种尴尬：Python 那边有 LangChain，生态成熟、组件齐全，但用起来总有种"动态语言的随意"——类型靠文档保证，流式响应要自己拼，并发稍一复杂就失控。而 Go 这边，要么自己从零搭，要么把 LangChain 的抽象硬搬过来，结果强类型语言用出了动态语言的糙。
字节 CloudWeGo 出品的 Eino（谐音 “I know”）就是冲着这个痛点来的。我把它全量源码读了一遍：8 个顶层包、162 个源文件、32,695 行生产代码，外加 36,787 行测试——测试代码比生产代码还多，这在框架项目里相当少见。一句话概括它的野心：用 Go 的工程哲学（强类型、CSP 并发、显式错误处理）重新设计 LLM 编排的抽象边界，而不是再做一个"Go 版 LangChain"。
四层架构：从数据契约到智能体
Eino 的分层很清晰，自顶向下四层，依赖方向无环：
第一层，数据契约（schema）。定义贯穿全框架的核心结构：Message（模型输入输出）、Document（文档）、ToolInfo（工具描述），以及整个框架流式能力的基石——泛型流式抽象 StreamReader[T]。这层不依赖任何其他包，是地基。
第二层，组件抽象（components）。用 8 个最小接口描述 LLM 应用的"积木"：ChatModel、Tool、Retriever、Embedding、Indexer、Loader、Transformer、ChatTemplate。每个组件只定义"能干什么"，具体实现（接 OpenAI 还是接国产模型）全部剥离到独立仓库 eino-ext，核心仓零外部服务耦合。
第三层，编排引擎（compose）。框架的心脏，也是最有技术含量的一层。提供 Chain（线性）、Graph（循环/DAG）、Workflow（字段级映射）三种拓扑，编译后统一成 Runnable[I,O]，运行时是一个 Pregel 风格的超步（super-step）并发引擎，自动处理类型检查、流式拼接、状态、分支、中断与检查点。
第四层，智能体（adk + flow）。在引擎之上构建：adk 提供 ChatModelAgent（ReAct）、多智能体转交、人机中断、Deep/Supervisor/Plan-Execute 等预置模式；flow 提供更轻量的 ReAct、MultiQuery 等流程。
关键设计：adk 和 flow 构建在 compose 之上而非之中——ChatModelAgent 内部就是用一个 compose Graph 装配出来的 ReAct 循环。
Pregel 引擎：Go 的 CSP 哲学和 BSP 模型的结合
Eino 运行时最精彩的部分，是它的执行模型。整个图执行是一个 Pregel/BSP（整体同步并行）超步循环：
每个超步经历"提交就绪任务 → 并发执行 → 全局等待 → 把输出写入 channel → 根据边和分支计算下一超步任务"。节点之间不共享内存，只通过 channel 传递数据——每个节点一个 goroutine，超步之间全局同步。
这个设计妙在哪？“节点内并发、超步间同步"既吃满了多核并发，又从根本上规避了数据竞争——节点不共享状态，天然契合 Go 的 CSP 哲学。用 Go 写过多线程的人都知道，并发难的不是"跑起来”，而是"不出错"，Eino 用架构直接把这个难点消掉了。
还有个细节值得说：taskManager 给每个任务起 goroutine 时做了 panic recover，把堆栈包装成 error 下发——单个节点 panic 不会击穿整个图。这种防御式设计贯穿全文。
五个值得抄的设计
读完源码，有几个设计让我觉得"这框架是真的懂 Go"：
一、四范式自动降级。 一个 LLM 组件理论上要支持四种调用方式：Invoke（非流进非流出）、Stream（非流进流出）、Collect（流进非流出）、Transform（流进流出）。Eino 的做法是：组件作者只需实现其中一种，框架通过 12 个适配器自动补齐其余三种。比如你只实现了 Stream，你的 Invoke 会被自动实现为"调 Stream 再把流聚合起来"。策略模式 + 适配器模式的组合，抹平了所有组件的流式差异。
二、泛型类型擦除桥接。 用户侧 API 是强类型的 Runnable[I,O]，但引擎需要统一持有任意类型的节点。Eino 在边界做了一层擦除：泛型函数被擦成 invoke func(ctx, any, ...) (any, error)，内部再做类型断言。用户享受编译期类型安全，引擎保持类型无关的简洁——这是 Go 泛型工程化的一个典范。
三、AOP 洋葱模型 + 流复制。 可观测性（日志/追踪/指标）用 context 传播的轻量 AOP 实现，组件作者只需三行埋点。最有意思的是流式切面：当有 N 个 handler 时，框架把流 Copy(N+1) 份——前 N 份给各 handler 独立观察，最后一份给业务，观察者能消费流做计时和 token 统计，却绝不干扰业务数据流。
四、随处中断、精确恢复。 中断机制横跨三层：节点前后、工具内、智能体层，检查点把 channels、state、子图状态序列化，恢复时按地址定向注入。这让"人机协同审批"“长时间任务持久化"成为一等公民，而不是外挂补丁。
五、Agent 可以当工具用。 AgentTool 把任意 Agent 适配成 tool.BaseTool——一个智能体可以作为另一个智能体的工具被调用，多智能体协作因此变得非常自然。
隐患与思考：好框架也有成长烦恼
当然，Eino 不是没有值得警惕的地方：
反射密集是最大的成本。 用户 API 是泛型的，但引擎内部大量依赖 reflect：字段映射、类型分派、类型断言。这意味着部分类型不匹配要到 Compile 甚至运行时才暴露——比如 Workflow 的字段路径是字符串，拼错字段名不会编译报错。
超步并发的顺序不确定性。 同一超步内多个节点并发执行，如果下游对前驱完成顺序敏感，可能出现难以复现的顺序问题。框架规避了数据竞争，但逻辑顺序的正确性仍由图的构建者负责。
无界通道的内存风险。 UnboundedChan 提供无界缓冲，如果上游产出长期高于下游消费，缓冲区会无限增长。框架在流层有资源管理，但这个通道本身没有容量上限。
另外，两套编排抽象并存（adk 的 workflowAgent 是手写 goroutine 编排，flow 是更早期的轻量实现），三者能力有重叠，新用户需要花时间理解取舍边界。
给 Go 程序员的源码阅读路线
如果你想去读 Eino 源码，建议按这个顺序，由浅入深：
schema/stream.go——流式基石，看懂 StreamReader 的 Copy/Mergecompose/runnable.go——四范式自动降级compose/graph_run.go+graph_manager.go——Pregel 引擎核心adk/react.go+adk/chatmodel.go——ReAct 如何建图internal/callbacks/inject.go——洋葱切面机制
Eino 的核心竞争力，不是"又一个 LangChain”，而是用 Go 的工程哲学重新设计了 LLM 编排的抽象边界。对 Go 后端工程师来说，它既是可用的框架，也是一份高质量的"Go 并发与泛型工程"教材——32,695 行生产代码 + 36,787 行测试，本身就是最好的学习材料。如果你正在用 Go 做 AI 应用，或者单纯想看看大厂怎么把并发写到极致，这份源码值得一读。