chore: import upstream snapshot with attribution

2026-07-13 12:37:51 +08:00
commit d0e4308def
614 changed files with 74458 additions and 0 deletions
@@ -0,0 +1,276 @@
+# Dynamic 执行模式指南
+
+Dynamic 执行模式允许在边级别定义并行处理行为，支持 Map（扇出）和 Tree（扇出+归约）两种模式。当消息通过配置了 `dynamic` 的边传递时，目标节点会根据拆分结果动态扩展为多个并行实例。
+
+## 1. 概述
+
+| 模式 | 描述 | 输出 | 适用场景 |
+|------|------|------|----------|
+| **Map** | 扇出执行，将消息拆分为多个单元并行处理 | `List[Message]`（打平结果） | 批量处理、并行查询 |
+| **Tree** | 扇出+归约，并行处理后按组递归合并 | 单个 `Message` | 长文本摘要、层级聚合 |
+
+## 2. 配置结构
+
+Dynamic 配置定义在**边**上，而非节点：
+
+```yaml
+edges:
+  - from: Source Node
+    to: Target Node
+    trigger: true
+    carry_data: true
+    dynamic:                    # 边级动态执行配置
+      type: map                 # map 或 tree
+      split:                    # 消息拆分策略
+        type: message           # message | regex | json_path
+        # pattern: "..."        # regex 模式必填
+        # json_path: "..."      # json_path 模式必填
+      config:                   # 模式特定配置
+        max_parallel: 5         # 最大并发数
+```
+
+### 2.1 核心概念
+
+- **动态边**：配置了 `dynamic` 的边，其传递的消息会触发目标节点的动态扩展
+- **静态边**：未配置 `dynamic` 的边，其传递的消息会**复制**到所有动态扩展实例
+- **目标节点扩展**：目标节点根据 split 结果被"虚拟"扩展为多个并行实例
+
+### 2.2 多入边一致性规则
+
+> [!IMPORTANT]
+> 当一个节点有多条入边配置了 `dynamic` 时，所有动态边的配置**必须完全一致**（type、split、config），否则执行时会报错。
+
+## 3. Split 拆分策略
+
+Split 定义如何将通过边的消息拆分为并行执行单元。
+
+### 3.1 message 模式（默认）
+
+每条通过边的消息作为独立执行单元。这是最常用的模式。
+
+```yaml
+split:
+  type: message
+```
+
+**执行行为**：
+- 源节点输出 4 条消息通过动态边
+- 拆分为 4 个并行单元，目标节点执行 4 次
+
+### 3.2 regex 模式
+
+使用正则表达式从文本内容中提取匹配项。
+
+```yaml
+split:
+  type: regex
+  pattern: "(?s).{1,2000}(?:\\s|$)"  # 每 2000 字符切分
+```
+
+**典型用例**：
+- 按段落拆分：`pattern: "\\n\\n"`
+- 按行拆分：`pattern: ".+"`
+- 按固定长度：`pattern: "(?s).{1,N}"`
+
+### 3.3 json_path 模式
+
+从 JSON 格式输出中按路径提取数组元素。
+
+```yaml
+split:
+  type: json_path
+  json_path: "$.items[*]"  # JSONPath 表达式
+```
+
+## 4. Map 模式详解
+
+Map 模式将消息拆分后并行执行目标节点，输出结果打平为 `List[Message]`。
+
+### 4.1 配置项
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `max_parallel` | int | 10 | 最大并发执行数 |
+
+### 4.2 执行流程
+
+```mermaid
+flowchart LR
+    Source["源节点输出"] --> Edge["动态边 (map)"]
+    Edge --> Split["拆分"]
+    Split --> U1["单元 1"]
+    Split --> U2["单元 2"]
+    Split --> U3["单元 N"]
+    U1 --> P1["目标节点 #1"]
+    U2 --> P2["目标节点 #2"]
+    U3 --> P3["目标节点 #N"]
+    P1 --> Merge["合并结果"]
+    P2 --> Merge
+    P3 --> Merge
+    Merge --> Output["List[Message]"]
+```
+
+## 5. Tree 模式详解
+
+Tree 模式在 Map 基础上增加归约层，将并行结果按组递归合并，最终输出单个结果。
+
+### 5.1 配置项
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `group_size` | int | 3 | 每组归约的元素数量，最小为 2 |
+| `max_parallel` | int | 10 | 每层最大并发执行数 |
+
+### 5.2 执行流程
+
+```mermaid
+flowchart TB
+    subgraph Layer1["第一层：并行执行"]
+        I1["单元 1"] --> R1["结果 1"]
+        I2["单元 2"] --> R2["结果 2"]
+        I3["单元 3"] --> R3["结果 3"]
+        I4["单元 4"] --> R4["结果 4"]
+        I5["单元 5"] --> R5["结果 5"]
+        I6["单元 6"] --> R6["结果 6"]
+    end
+    
+    subgraph Layer2["第二层：分组归约 (group_size=3)"]
+        R1 & R2 & R3 --> G1["归约组 1"]
+        R4 & R5 & R6 --> G2["归约组 2"]
+    end
+    
+    subgraph Layer3["第三层：最终归约"]
+        G1 & G2 --> Final["最终结果"]
+    end
+```
+
+## 6. 静态边消息复制
+
+当目标节点同时有动态入边和静态入边时：
+
+- **动态边消息**：按 split 策略拆分，每个单元执行一次目标节点
+- **静态边消息**：**复制**到每个动态扩展实例
+
+```yaml
+nodes:
+  - id: Task Generator
+    type: passthrough
+    config: ...
+  - id: Extra Requirement
+    type: literal
+    config:
+      content: "请使用简洁的语言"
+  - id: Processor
+    type: agent
+    config:
+      name: gpt-4o
+      role: 处理任务
+
+edges:
+  - from: Task Generator
+    to: Processor
+    dynamic:                    # 动态边：4 条任务 → 4 个并行单元
+      type: map
+      split:
+        type: message
+      config:
+        max_parallel: 10
+  - from: Extra Requirement
+    to: Processor              # 静态边：复制到所有 4 个实例
+    trigger: true
+    carry_data: true
+```
+
+**执行结果**：Processor 执行 4 次，每次收到 1 条任务 + "请使用简洁的语言"
+
+## 7. 完整示例
+
+### 7.1 旅行规划（Map + Tree 组合）
+
+```yaml
+graph:
+  nodes:
+    - id: Eat Planner
+      type: literal
+      config:
+        content: 请规划在上海吃什么
+        role: user
+    - id: Play Planner
+      type: literal
+      config:
+        content: 请规划在上海玩什么
+        role: user
+    - id: Stay Planner
+      type: literal
+      config:
+        content: 请规划在上海住哪里
+        role: user
+    - id: Collector
+      type: passthrough
+      config:
+        only_last_message: false
+    - id: Travel Executor
+      type: agent
+      config:
+        name: gpt-4o
+        role: 你是旅行规划师，请按照用户请求进行规划
+    - id: Final Aggregator
+      type: agent
+      config:
+        name: gpt-4o
+        role: 请将输入的内容整合成一份完整的旅行计划
+
+  edges:
+    - from: Eat Planner
+      to: Collector
+    - from: Play Planner
+      to: Collector
+    - from: Stay Planner
+      to: Collector
+    - from: Collector
+      to: Travel Executor
+      dynamic:                  # Map 扇出：3 个规划请求 → 3 个并行执行
+        type: map
+        split:
+          type: message
+        config:
+          max_parallel: 10
+    - from: Travel Executor
+      to: Final Aggregator
+      dynamic:                  # Tree 归约：3 个结果 → 1 个最终计划
+        type: tree
+        split:
+          type: message
+        config:
+          group_size: 2
+          max_parallel: 10
+```
+
+### 7.2 长文档摘要（Tree 模式）
+
+```yaml
+edges:
+  - from: Document Source
+    to: Summarizer
+    dynamic:
+      type: tree
+      split:
+        type: regex
+        pattern: "(?s).{1,2000}(?:\\s|$)"  # 2000 字符切分
+      config:
+        group_size: 3
+        max_parallel: 10
+```
+
+## 8. 性能建议
+
+- **控制并发**：设置合理的 `max_parallel` 避免触发 API 限流
+- **优化拆分粒度**：过细的拆分增加开销，过粗则无法充分并行
+- **Tree 组大小**：`group_size=2-4` 通常是较好的选择
+- **监控成本**：Dynamic 模式会显著增加 API 调用次数
+
+## 9. 相关文档
+
+- [边配置指南](../edges.md)
+- [工作流编排指南](../workflow_authoring.md)
+- [Agent 节点配置](../nodes/agent.md)