用途
eino-compose 是 CloudWeGo Eino 框架的编排包，导入路径为 github.com/cloudwego/eino/compose。它用于把模型、模板、工具、Lambda 等组件组合成多步骤的可执行流水线或图，适合构建需要多步处理、分支、循环或字段映射的 LLM 应用流程。
三种编排 API
包内提供三种编排 API：
- Graph：有向图拓扑，支持循环（Pregel 模式）或不支持循环（DAG 模式），采用整体输入/输出对齐。
- Chain：线性顺序拓扑，不支持循环，采用整体输入/输出对齐。Chain 在 Pregel 模式的 Graph 之上实现，但强制线性拓扑。
- Workflow：DAG 拓扑，不支持循环，支持字段级映射。
三者都会编译为 Runnable[I, O]，暴露 Invoke、Stream、Collect、Transform 方法。
选择建议：Chain 用于顺序流水线（如 prompt -> model -> parser），API 最简单；Graph 用于需要分支、循环（如 ReAct agent）或扇出/扇入的场景；Workflow 用于需要在不同结构体类型节点之间做字段级映射的场景，且仅支持 DAG。
主要能力
Graph
使用 compose.NewGraphInputType, OutputType 创建。可通过 AddChatModelNode、AddChatTemplateNode、AddToolsNode、AddLambdaNode、AddPassthroughNode、AddGraphNode 添加节点；通过 AddEdge 连接节点（含 compose.START 与 compose.END）；通过 compose.NewGraphBranch 与 AddBranch 实现条件分支。编译后调用 Invoke 执行。
Chain
使用 compose.NewChainInputType, OutputType 创建，通过链式 Append 方法构建。可用的 Append 方法包括：AppendChatModel、AppendChatTemplate、AppendToolsNode、AppendAgenticToolsNode、AppendLambda、AppendGraph、AppendParallel、AppendBranch、AppendPassthrough、AppendRetriever、AppendEmbedding、AppendLoader、AppendIndexer、AppendDocumentTransformer。编译后调用 Invoke 执行。
Workflow
使用 compose.NewWorkflowInputStruct, OutputStruct 创建。通过 AddLambdaNode 添加节点，并用 AddInput 配合字段映射辅助函数连接。字段映射辅助函数包括：MapFields、ToField、FromField、MapFieldPaths、ToFieldPath、FromFieldPath。通过 End().AddInput(...) 指定输出。编译后执行。
流式编程
Runnable[I, O] 提供四种交互模式：
- Invoke：输入 I，输出 O，Lambda 构造器为 compose.InvokableLambda。
- Stream：输入 I，输出 *StreamReader[O]，Lambda 构造器为 compose.StreamableLambda。
- Collect：输入 *StreamReader[I]，输出 O，Lambda 构造器为 compose.CollectableLambda。
- Transform：输入 *StreamReader[I]，输出 *StreamReader[O]，Lambda 构造器为 compose.TransformableLambda。
框架会在模式间自动转换：Invoke 调用时所有内部节点以 Invoke 模式运行；Stream/Collect/Transform 调用时所有内部节点以 Transform 模式运行，缺失的模式会被自动补齐。流原语位于 github.com/cloudwego/eino/schema，例如 schema.PipeT 返回 sr、sw，通过 sw.Send(chunk, nil) 与 sw.Close() 写入，通过 sr.Recv() 与 sr.Close() 读取。
AgenticToolsNode
AgenticToolsNode 是 ToolsNode 的智能体版本，操作 *schema.AgenticMessage 而非 *schema.Message，提取 FunctionToolCall 内容块并返回 FunctionToolResult 内容块。可通过 compose.NewAgenticToolsNode(ctx, &compose.ToolsNodeConfig{...}) 从相同的 ToolsNodeConfig 创建，在 Graph 中用 AddAgenticToolsNode 添加，在 Chain 中用 AppendAgenticToolsNode 追加。与 ToolsNode 的关键区别：输入为 *schema.AgenticMessage（读取 ContentBlockTypeFunctionToolCall 块），输出为 []*schema.AgenticMessage（写入 ContentBlockTypeFunctionToolResult 块）；支持多模态工具结果（文本、图像、音频、视频、文件）；处理 ToolSearchFunctionToolResult 以支持动态工具发现；复用相同的 ToolsNodeConfig，现有工具无需改动。
编译与运行
通过 g.Compile(ctx, ...) 编译，可传入 compose.WithGraphName("my_graph")、compose.WithNodeTriggerMode(compose.AllPredecessor)（DAG 模式）等选项。非流式调用 r.Invoke(ctx, input)；流式调用 r.Stream(ctx, input)，随后循环 stream.Recv() 直到 io.EOF，并注意关闭流。
状态图
可在单次请求内跨节点共享状态：创建图时传入 compose.WithGenLocalState(func(ctx context.Context) *MyState {...})，并在节点上使用 compose.WithStatePreHandler 与 compose.WithStatePostHandler 在节点执行前后读写状态。
使用方式与注意事项
- 大多数场景默认使用 Graph；仅在简单线性流水线时使用 Chain；需要不同结构体类型之间的字段级映射时使用 Workflow。
- 始终展示 Compile 步骤，g.Compile(ctx) 返回 Runnable[I, O]。
- 始终关闭 StreamReader，获取流后立即使用 defer sr.Close()。
- 上游输出类型必须匹配下游输入类型，或使用 WithInputKey/WithOutputKey 进行 map 转换。
- 循环图（如 ReAct agent）使用默认 Pregel 模式（AnyPredecessor）；DAG 设置 AllPredecessor。
- 可用 compose.WithCallbacks(handler) 在运行时注入日志/追踪。
- 可用 compose.WithCheckPointStore(store) 配合中断节点实现暂停/恢复工作流。
参考文件
可按需阅读以下文件获取详细 API、示例与高级用法：reference/graph.md（完整 Graph API、分支、状态图、循环图、完整 ReAct 示例）、reference/chain.md（Chain API、使用时机、链中的并行/分支）、reference/workflow.md（Workflow API、字段级映射辅助函数、约束）、reference/stream.md（StreamReader/Writer、Pipe/Copy/Merge、Lambda 构造器、自动转换规则）、reference/callback.md（回调时机、处理器注册、触发规则、追踪示例）、reference/call-option.md（按请求的 CallOption、组件类型选项、节点定位）、reference/checkpoint-and-state.md（CheckPointStore、中断/恢复、状态管理）。
限制
资料未提供该包的收费、价格、平台支持范围、性能指标或效果数据，这些信息暂未提供。