feat(eino): sync zh documents

Change-Id: I43a526ceaff63339e9dee705f0d55c5d6695d2f9

Author: shentongmartin

content/zh/docs/eino/Eino: 贡献规范.md

@@ -0,0 +1,23 @@
+---
+Description: ""
+date: "2025-07-21"
+lastmod: ""
+tags: []
+title: 'Eino: 贡献规范'
+weight: 0
+---
+
+Eino 代码的贡献形式：
+
+1. 贡献代码的同学以 Fork PR 的形式提交代码
+   1. 提交 PR 时，请写清楚贡献代码的前因后果
+2. Eino Maintainers 会定期 Review 提交的 PR，并在 PR 中的 Conversion 讨论代码内容
+3. 代码达到合入条件后，由 Eino Maintainers 触发单测并合入。
+
+# 组件贡献
+
+Eino 组件的实现一般会在 Eino-Ext 仓库中的特定目录下，新建一个 Go Sub Module，独立开发和维护。
+
+- 必须包含中英文的 README
+- 必须包含丰富准确的 Examples
+- 必须包含 callback.Handler 的切面点位的注入

content/zh/docs/eino/FAQ.md

@@ -0,0 +1,144 @@
+---
+Description: ""
+date: "2025-12-01"
+lastmod: ""
+tags: []
+title: FAQ
+weight: 0
+---
+
+# Q: cannot use openapi3.TypeObject (untyped string constant "object") as *openapi3.Types value in struct literal，cannot use types (variable of type string) as *openapi3.Types value in struct literal
+
+检查 github.com/getkin/kin-openapi 依赖版本不能超过 v0.118.0
+
+# Q: Agent 流式调用时不会进入 ToolsNode 节点。或流式效果丢失，表现为非流式。
+
+- 先更新 eino 版本到最新
+
+不同的模型在流式模式下输出工具调用的方式可能不同: 某些模型(如 OpenAI) 会直接输出工具调用；某些模型 (如 Claude) 会先输出文本，然后再输出工具调用。因此需要使用不同的方法来判断，这个字段用来指定判断模型流式输出中是否包含工具调用的函数。
+
+ReAct Agent 的 Config 中有一个 StreamToolCallChecker 字段，如未填写，Agent 会使用“非空包”是否包含工具调用判断：
+
+```go
+**func **firstChunkStreamToolCallChecker(_ context.Context, sr *schema.StreamReader[*schema.Message]) (bool, error) {
+    **defer **sr.Close()
+
+    **for **{
+       msg, err := sr.Recv()
+       **if **err == io.EOF {
+          **return **false, nil
+       }
+       **if **err != nil {
+          **return **false, err
+       }
+
+       **if **len(msg.ToolCalls) > 0 {
+          **return **true, nil
+       }
+
+       **if **len(msg.Content) == 0 { // skip empty chunks at the front
+          **continue**
+**       **}
+
+       **return **false, nil
+    }
+}
+```
+
+上述默认实现适用于：模型输出的 Tool Call Message 中只有 Tool Call。
+
+默认实现不适用的情况：在输出 Tool Call 前，有非空的 content chunk。此时，需要自定义 tool Call checker 如下：
+
+```
+_toolCallChecker := func(ctx context.Context, sr *schema.StreamReader[*schema.Message]) (bool, error) {_
+_    defer sr.Close()_
+_    for {_
+_       msg, err := sr.Recv()_
+_       if err != nil {_
+_          if errors.Is(err, io.EOF) {_
+_             // finish_
+_             break_
+_          }_
+
+_          return false, err_
+_       }_
+
+_       if len(msg.ToolCalls) > 0 {_
+_          return true, nil_
+_       }_
+_    }_
+_    return false, nil_
+}
+```
+
+上面这个自定义 StreamToolCallChecker，在模型常规输出 answer 时，需要判断**所有包**是否包含 ToolCall，从而导致“流式判断”的效果丢失。如果希望尽可能保留“流式判断”效果，解决这一问题的建议是：
+
+> 💡
+> 尝试添加 prompt 来约束模型在工具调用时不额外输出文本，例如：“如果需要调用 tool，直接输出 tool，不要输出文本”。
+>
+> 不同模型受 prompt 影响可能不同，实际使用时需要自行调整 prompt 并验证效果。
+
+# Q: [github.com/bytedance/sonic/loader](http://github.com/bytedance/sonic/loader): invalid reference to runtime.lastmoduledatap
+
+老版本 sonic 不兼容 go1.24，更新版本大于 v1.13.2 即可
+
+# Q: Tool Input 反序列化失败：failed to invoke tool call {tool_call_id}: unmarshal input fail
+
+目前模型一般不会产生非法 json 输出，可以先确认下反序列化失败原因是什么，大概率是模型输出超长截断导致。
+
+# Q: Eino 如何实现批处理节点？ 类似 Coze 中的批处理节点
+
+Eino 目前不支持批处理，可选方法有两种
+
+1. 每次请求按需动态构建 graph，额外成本不高。 这种方法需要注意 Chain Parallel 要求其中并行节点数量大于一，
+2. 自定义批处理节点，节点内自行批处理任务
+
+# Q: fornax sdk 中发生 panic / panic 栈中存在 fornax sdk
+
+先把 Fornax sdk 和 eino 版本升级到最新试下
+
+# Q: eino 支持把模型结构化输出吗
+
+分两步，第一步要求模型输出结构化数据，有三个方法：
+
+1. 部分模型支持直接配置（比如 openai 的 response format），可以看下模型配置里有没有。
+2. 通过 tool call 功能获得
+3. 写 prompt 要求模型
+
+得到模型结构化输出后，可以用 schema.NewMessageJSONParser 把 message 转换成你需要的 struct
+
+# Q：图片识别场景中报错：One or more parameters specified in the request are not valid
+
+检查模型是否支持图片输入（doubao 系列只有带 vision 的模型才支持）
+
+# Q: 如何获取模型(chat model)输出的 Reasoning Content/推理/深度思考 内容：
+
+如果模型封装支持输出 Reasoning Content/推理/深度思考 内容，这些内容会储存到模型输出的 Message 的 Extra 字段，在封装目录下会提供类似 GetReasoningContent/GetThinking 函数，用这些方法可以从 message 中获取到。
+
+# Q：报错中包含"context deadline exceeded" "timeout" "context canceled"
+
+超时或者 ctx 被框架服务框架或人为取消，调整超时或者排查代码即可。  如果觉得模型等组件返回时间过长不符合预期，可以直接去找服务提供方，eino 只做透传，不需要提 eino oncall
+
+# Q：想要在子图中获取父图的 State 怎么做
+
+如果父图和子图存在 state ，子图的 state 会覆盖父图的 state 。因此，需要自定义 context key ，在调用子图前，调用 compose.ProcessState() 方法先获取父图的 state ，将父图 state 传入到自定义的 context key 中。
+
+# Q:  eino-ext 支持的 Model 模型的如何适配多模特的输入输出 ？
+
+eino-ext 支持的多模态输入输出场景，可以查阅 [https://www.cloudwego.io/zh/docs/eino/ecosystem_integration/chat_model](https://www.cloudwego.io/zh/docs/eino/ecosystem_integration/chat_model) 对应模型的 Examples 示例;
+
+# Q: 使用最新的多模态支持字段 UserInputMultiContent 输入多模态数据，但模型侧好像没有我传入的多模态数据或者多模态输入时，读不到 multicontent 的内容
+
+最新版本的 Eino 引入 UserInputMultiContent 与  AssistantGenMultiContent 分别表达用户侧输入的多模态数据与模型侧返回的多模态数据，其中 eino-ext 中的 chatmodel 实现都已经做了适配，如果发现模型侧没有收到多模态信息，可以尝试升级下我们使用的模型的包。go get 到最新版本再次尝试运行看是否问题得到解决。
+
+# Q: 升级到 0.6.x 版本后，有不兼容问题
+
+根据先前社区公告规划 [Migration from OpenAPI 3.0 Schema Object to JSONSchema in Eino · cloudwego/eino · Discussion #397](https://github.com/cloudwego/eino/discussions/397)，已发布 eino V0.6.1 版本。重要更新内容为移除了 getkin/kin-openapi 依赖以及所有 OpenAPI 3.0 相关代码。
+
+eino-ext 部分 module 报错 undefined: schema.NewParamsOneOfByOpenAPIV3 等问题，升级报错的 eino-ext module 到最新版本即可。
+
+如果 schema 改造比较复杂，可以使用 [JSONSchema 转换方法](https://bytedance.larkoffice.com/wiki/ZMaawoQC4iIjNykzahwc6YOknXf)文档中的工具方法辅助转换。
+
+# Q: context canceled / context deadline exceeded
+
+调用 eino 时传入的 ctx 被取消/超时了，与框架无关。

content/zh/docs/eino/_index.md

@@ -1,6 +1,6 @@
 ---
-Description: Eino 是基于 Go 的 AI 应用开发框架
-date: "2025-03-18"
+Description: Eino 是基于 Golang 的 AI 应用开发框架
+date: "2025-11-20"
 lastmod: ""
 linktitle: Eino
 menu:

content/zh/docs/eino/core_modules/_index.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-02-10"
+date: "2025-07-21"
 lastmod: ""
 tags: []
 title: 'Eino: 核心模块'

content/zh/docs/eino/core_modules/chain_and_graph_orchestration/_index.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-02-10"
+date: "2025-07-21"
 lastmod: ""
 tags: []
 title: 'Eino: Chain & Graph & Workflow 编排功能'
@@ -45,7 +45,7 @@ Eino 对「编排」有着这样的洞察：
   - 详细信息参考：[Eino: Callback 用户手册](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)
 - 提供了 call option 的机制，**扩展性**是快速迭代中的系统最基本的诉求
   - 详细信息参考：[Eino: CallOption 能力与规范](/zh/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities)
-- 提供了 “类型对齐” 的开发方式的强化，降低开发者心智负担，把 Go 的**类型安全**特性发挥出来
+- 提供了 “类型对齐” 的开发方式的强化，降低开发者心智负担，把 golang 的**类型安全**特性发挥出来
   - 详细信息参考：[Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles)
 - 提供了 “**流的自动转换**” 能力，让 “流” 在「编排系统的复杂性来源榜」中除名
   - 详细信息参考：[Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)

content/zh/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities.md

@@ -1,10 +1,10 @@
 ---
 Description: ""
-date: "2025-01-22"
+date: "2025-11-20"
 lastmod: ""
 tags: []
 title: 'Eino: CallOption 能力与规范'
-weight: 5
+weight: 6
 ---
 
 **CallOption**: 对 Graph 编译产物进行调用时，直接传递数据给特定的一组节点(Component、Implementation、Node)的渠道
@@ -296,6 +296,7 @@ compiledGraph.Invoke(ctx, input, WithCallbacks(handler))
 
 // 只对特定类型节点生效的 call option
 compiledGraph.Invoke(ctx, input, WithChatModelOption(WithTemperature(0.5))
+compiledGraph.Invoke(ctx, input, WithToolOption(WithXXX("xxx"))
 
 // 只对特定节点生效的 call option
 compiledGraph.Invoke(ctx, input, WithCallbacks(handler).DesignateNode("node_1"))

content/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual.md

@@ -1,10 +1,10 @@
 ---
 Description: ""
-date: "2025-03-18"
+date: "2025-12-01"
 lastmod: ""
 tags: []
 title: 'Eino: Callback 用户手册'
-weight: 4
+weight: 5
 ---
 
 ## 解决的问题
@@ -94,7 +94,7 @@ type RunInfo struct {
   - 有接口的 Component：是啥接口，就是啥
   - Lambda：固定值 Lambda
   - Graph Node: 用内部的 Component/Lambda/Graph 的值。
-  - Graph 自身：固定值 Graph / Chain. （之前曾有 StateGraph / StateChain ，现已整合到 Graph / Chain 中）
+  - Graph 自身：固定值 Graph / Chain / Workflow. （之前曾有 StateGraph / StateChain ，现已整合到 Graph / Chain 中）
 
 ### Callback Input & Output
 

content/zh/docs/eino/core_modules/chain_and_graph_orchestration/chain_graph_introduction.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-03-28"
+date: "2025-12-01"
 lastmod: ""
 tags: []
 title: 'Eino: Chain/Graph 编排介绍'

…ph_orchestration/interrupt_checkpoint.md …ph_orchestration/checkpoint_interrupt.mdcontent/zh/docs/eino/core_modules/chain_and_graph_orchestration/interrupt_checkpoint.md renamed to content/zh/docs/eino/core_modules/chain_and_graph_orchestration/checkpoint_interrupt.md content/zh/docs/eino/core_modules/chain_and_graph_orchestration/interrupt_checkpoint.md renamed to content/zh/docs/eino/core_modules/chain_and_graph_orchestration/checkpoint_interrupt.md

@@ -1,12 +1,19 @@
 ---
 Description: ""
-date: "2025-08-07"
+date: "2025-11-20"
 lastmod: ""
 tags: []
 title: 'Eino: Interrupt & CheckPoint使用手册'
-weight: 6
+weight: 7
 ---
 
+> 💡
+> 注意：v0.3.26 版本中因为代码编写错误导致 CheckPoint 的序列化内容产生 break，新接入 CheckPoint 使用 v0.3.26 以后的版本，建议直接使用最新。
+>
+> eino 提供了兼容分支，使用了 checkpoint 且版本低于 v0.3.26 的业务在升级 eino 时可以先升级到兼容分支，老数据淘汰后再升级到主干。
+>
+> 因为兼容分支会引入额外的性能开销并且一般来说业务 agent checkpoint 有不太长的有效期，所以分支没有合入主干。具体联系 ou_d474ba32675f1d7f6c3a9a2e8b3b3df7
+
 # 介绍
 
 使用 Interrupt & CheckPoint 功能，可以实现在指定位置暂停 Graph 执行并在之后断点续传，如果是 StateGraph，还可以在断点续传前修改 State。
@@ -236,7 +243,7 @@ g.AddAnyGraph("node1", subGraph, WithGraphCompileOptions(
     WithInterruptAfterNodes([]string{"node2"}),
 ))
 
-g.Compile(ctx, WithCheckPointer(cp))
+g.Compile(ctx, WithCheckPointStore(cp))
 ```
 
 如果在子图中 interrupt，resume 时修改的 state 应为子图 state。TODO，说明下 StateModifier 中 Path 使用

content/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-03-18"
+date: "2025-11-20"
 lastmod: ""
 tags: []
 title: 'Eino: 编排的设计理念'
@@ -9,15 +9,15 @@ weight: 2
 
 大模型应用编排方案中，最火的就是 langchain 以及 langgraph，其官方提供了 python 和 ts 的 sdk，这两门语言以其灵活性著称，灵活性给 sdk 的开发带来了极大的便利，但同时，也给 sdk 的使用者带来了极大的困扰和心智负担。
 
-Go 作为一门 极其简单 的编程语言，确定的 `静态类型` 是让其变得简单的重要原因之一，而 eino，则保持了这一重要特性: `确定的类型` + `Compile 时类型检查`。
+golang 作为一门 极其简单 的编程语言，确定的 `静态类型` 是让其变得简单的重要原因之一，而 eino，则保持了这一重要特性: `确定的类型` + `Compile 时类型检查`。
 
 ## 以上下游 `类型对齐` 为基本准则
 
 eino 的最基础编排方式为 graph，以及简化的封装 chain。不论是哪种编排方式，其本质都是 `逻辑节点` + `上下游关系` 。在编排的产物运行时，都是从一个逻辑节点运行，然后下一步运行和这个节点相连的下一个节点。
 
 这之间蕴含了一个基本假设：**前一个运行节点的输出值，可以作为下一个节点的输入值。**
 
-在 Go 中，要实现这个假设，有两个基本方案：
+在 golang 中，要实现这个假设，有两个基本方案：
 
 1. 把不同节点的输入输出都变成一种更泛化的类型，例如 `any` 、`map[string]any` 等。
    1. 采用泛化成 any 的方案，但对应的代价是: 开发者在写代码时，需要显式转换成具体类型才能使用。这会极大增加开发者的心智负担，因此最终放弃此方案。
@@ -222,7 +222,7 @@ AddChatModelNode("xxx", model, WithStreamStatePostHandler(postHandler))
 
 Runnable 的一个重要作用就是提供了 「Invoke」、「Stream」、「Collect」、「Transform」 四种调用方式。
 
-> 上述几种调用方式的介绍以及详细的 Runnable 介绍可以查看: [Eino: 基础概念介绍](/zh/docs/eino/overview)
+> 上述几种调用方式的介绍以及详细的 Runnable 介绍可以查看: [Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials#share-AqaQddcjSoFFojxmFVcchOHTnsf)
 
 假设我们有一个 `Graph[[]*schema.Message, []*schema.Message]`，里面有一个 ChatModel 节点，一个 Lambda 节点，Compile 之后是一个 `Runnable[[]*schema.Message, []*schema.Message]`。
 
@@ -285,11 +285,10 @@ func TestTypeMatch(t *testing.T) {
 
 在 stream 模式下，拼接帧 是一个非常常见的操作，拼接时，会先把 `*StreamReader[T] ` 中的所有元素取出来转成 `[]T`，再尝试把 `[]T` 拼接成一个完整的 `T`。框架内已经内置支持了如下类型的拼接:
 
-- `*schema.Message`:  详情见 `schema.ConcatMessages()`
+- `*schema.Message`:  详情见 `schema.``ConcatMessages``()`
 - `string`: 实现逻辑等同于 `+=`
 - `[]*schema.Message`: 详情见 `compose.concatMessageArray()`
 - `Map`: 把相同 key 的 val 进行合并，合并逻辑同上，若存在无法合并的类型，则失败 (ps: 不是覆盖)
-- `Struct` 或 `Struct 指针`：先转成 `[]map[string]any` 的，再以 map 的逻辑合并。要求 struct 中不能有 unexported field。
 - 其他 slice：只有当 slice 中只有一个元素是非零值时，才能合并。
 
 对其他场景，或者当用户想用定制逻辑覆盖掉上面的默认行为时，开发者可自行实现 concat 方法，并使用 `compose.RegisterStreamChunkConcatFunc()` 注册到全局的拼接函数中。
@@ -340,19 +339,12 @@ Eino 的 Graph 中的数据在 Node、Branch、Handler 间流转时，一律是
 
 ### 扇入与合并
 
-**扇入**：多个上游的数据汇入到下游，一起作为下游的输入。需要明确定义多个上游的输出，如何**合并（Merge）**起来。Eino 的选择是，首先要求多个上游输出的**实际类型**必须相同且为可合并的类型。
+**扇入**：多个上游的数据汇入到下游，一起作为下游的输入。需要明确定义多个上游的输出，如何**合并（Merge）**起来。
 
-可合并的类型可以是：
+默认情况下，首先要求多个上游输出的**实际类型**必须相同且为 Map，且相互间 key 不可重复。其次：
 
-- Map 类型，且相互间 key 不重复。
-- 任意类型，且通过 `compose.RegisterValuesMergeFunc` 注册了合并函数。
-
-其次：
-
-- 在非流式场景下，
-  - 如果输入的类型有注册过合并函数，则使用注册的合并函数合并为一个值。
-  - 如果输入的类型是 Map，则合并成为一个 Map，包含所有上游的所有键值对。
-- 在流式场景下，将类型相同的多个上游 StreamReader 合并为一个 StreamReader。实际 Recv 时从效果为从多个上游 StreamReader 中公平读取。
+- 在非流式场景下，合并后成为一个 Map，包含所有上游的所有键值对。
+- 在流式场景下，将类型相同的多个上游 StreamReader 合并为一个 StreamReader。实际 Recv 时效果为从多个上游 StreamReader 中公平读取。
 
 在 AddNode 时，可以通过添加 WithOutputKey 这个 Option 来把节点的输出转成 Map：
 
@@ -474,11 +466,12 @@ Eino 支持各种维度的 Call Option 分配方式：
 - 每个节点有确定的前序节点，当所有前序节点都完成后，本节点才具备运行条件。
 - 不支持图中有环，因为会打破“每个节点有确定的前序节点”这一假定。
 - 支持 Branch。在运行时，将 Branch 未选中的节点记为已跳过，不影响 AllPredecessor 的语义。
-- 不需要手动对齐 SuperStep。
 
 > 💡
-> 设置 NodeTriggerMode == AllPredecessor 后，节点会在所有前驱就绪后执行，但并不是立即执行，而是依然遵循 SuperStep——在一批节点全部执行完成后再运行新的可运行节点。
+> 设置 NodeTriggerMode = AllPredecessor 后，节点会在所有前驱就绪后执行，但并不是立即执行，而是依然遵循 SuperStep——在一批节点全部执行完成后再运行新的可运行节点。
+>
+> 如果在 Compile 时传入 compose.WithEagerExecution()，则就绪的节点会立刻运行。
 >
-> 如果在 Compile 是传入 compose.WithEagerExecution()，则就绪的节点会立刻运行。
+> 在 Eino v0.4.0 版本及之后的版本中，设置 NodeTriggerMode = AllPredecessor 后会默认开启 EagerExecution。
 
 总结起来，pregel 模式灵活强大但有额外的心智负担，dag 模式清晰简单但场景受限。在 Eino 框架中，Chain 是 pregel 模式，Workflow 是 dag 模式，Graph 则都支持，可由用户从 pregel 和 dag 中选择。