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,153 @@
+# Loop Counter 节点
+
+Loop Counter 节点是一种循环控制节点，用于限制工作流中环路的执行次数。它通过计数机制，在达到预设上限前抑制输出，达到上限后才释放消息触发出边，从而终止循环。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `max_iterations` | int | 是 | `10` | 最大循环次数，必须 ≥ 1 |
+| `reset_on_emit` | bool | 否 | `true` | 达到上限后是否重置计数器 |
+| `message` | text | 否 | - | 达到上限时发送给下游的消息内容 |
+
+## 核心概念
+
+### 工作原理
+
+Loop Counter 节点维护一个内部计数器，其行为如下：
+
+1. **每次被触发时**：计数器 +1
+2. **计数器 < `max_iterations`**：**不产生任何输出**，出边不会被触发
+3. **计数器 = `max_iterations`**：产生输出消息，触发出边
+
+这种"抑制-释放"机制使得 Loop Counter 可以精确控制循环何时终止。
+
+### 拓扑结构要求
+
+Loop Counter 节点在图结构中有特殊的位置要求：
+
+```
+    ┌──────────────────────────────────────┐
+    ▼                                      │
+  Agent ──► Human ─────► Loop Counter ──┬──┘
+    ▲         │                         │
+    └─────────┘                         ▼
+                                   End Node (环外)
+```
+
+> **重要**：由于 Loop Counter **未达上限时不产生任何输出**，因此：
+> - **Human 必须同时连接到 Agent 和 Loop Counter**：这样"继续循环"的边由 Human → Agent 承担，而 Loop Counter 仅负责计数
+> - **Loop Counter 必须连接到 Agent（环内）**：使其被识别为环内节点，避免提前终止环路
+> - **Loop Counter 必须连接到 End Node（环外）**：当达到上限时触发环外节点，终止整个环的执行
+
+### 计数器状态
+
+- 计数器状态在整个工作流执行期间持久化
+- 当 `reset_on_emit: true` 时，达到上限后计数器重置为 0
+- 当 `reset_on_emit: false` 时，达到上限后继续累计，后续每次触发都会输出
+
+## 何时使用
+
+- **防止无限循环**：为人机交互循环设置安全上限
+- **迭代控制**：限制 Agent 自我迭代改进的最大轮次
+- **超时保护**：作为流程执行的"熔断器"
+
+## 示例
+
+### 基础用法
+
+```yaml
+nodes:
+  - id: Iteration Guard
+    type: loop_counter
+    config:
+      max_iterations: 5
+      reset_on_emit: true
+      message: 已达到最大迭代次数，流程终止。
+```
+
+### 人机交互循环保护
+
+这是 Loop Counter 最典型的使用场景：
+
+```yaml
+graph:
+  id: review_loop
+  description: 带迭代上限的审稿循环
+  
+  nodes:
+    - id: Writer
+      type: agent
+      config:
+        provider: openai
+        name: gpt-4o
+        role: 根据用户反馈改进文章
+
+    - id: Reviewer
+      type: human
+      config:
+        description: |
+          审阅文章，输入 ACCEPT 接受或提供修改意见。
+
+    - id: Loop Guard
+      type: loop_counter
+      config:
+        max_iterations: 3
+        message: 已达到最大修改次数（3次），流程自动结束。
+
+    - id: Final Output
+      type: passthrough
+      config: {}
+
+  edges:
+    # 主循环：Writer -> Reviewer
+    - from: Writer
+      to: Reviewer
+    
+    # 条件1：用户输入 ACCEPT -> 结束
+    - from: Reviewer
+      to: Final Output
+      condition:
+        type: keyword
+        config:
+          any: [ACCEPT]
+    
+    # 条件2：用户输入修改意见 -> 同时触发 Writer 继续循环 AND Loop Guard 计数
+    - from: Reviewer
+      to: Writer
+      condition:
+        type: keyword
+        config:
+          none: [ACCEPT]
+    
+    - from: Reviewer
+      to: Loop Guard
+      condition:
+        type: keyword
+        config:
+          none: [ACCEPT]
+    
+    # Loop Guard 连接到 Writer（使其保持在环内）
+    - from: Loop Guard
+      to: Writer
+    
+    # Loop Guard 达到上限时：触发 Final Output 结束流程
+    - from: Loop Guard
+      to: Final Output
+
+  start: [Writer]
+  end: [Final Output]
+```
+
+**执行流程说明**：
+1. 用户首次输入修改意见 → 同时触发 Writer（继续循环）和 Loop Guard（计数 1，无输出）
+2. 用户再次输入修改意见 → 同时触发 Writer（继续循环）和 Loop Guard（计数 2，无输出）
+3. 用户第三次输入修改意见 → Writer 继续执行，Loop Guard 计数 3 达到上限，输出消息触发 Final Output，终止环路
+4. 或者在任意时刻用户输入 ACCEPT → 直接到 Final Output 结束
+
+## 注意事项
+
+- `max_iterations` 必须为正整数（≥ 1）
+- Loop Counter **未达上限时不产生任何输出**，出边不会触发
+- 确保 Loop Counter 同时连接环内节点和环外节点
+- `message` 字段可选，默认消息为 `"Loop limit reached (N)"`