chore: import upstream snapshot with attribution

docs/user_guide/zh/nodes/agent.md

@@ -0,0 +1,186 @@
+# Agent 节点
+
+Agent 节点是 DevAll 平台中最核心的节点类型，用于调用大语言模型 (LLM) 完成文本生成、对话、推理等任务。它支持多种模型提供商（OpenAI、Gemini 等），并可配置工具调用、思维链、记忆等高级功能。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `provider` | string | 是 | `openai` | 模型提供商名称，如 `openai`、`gemini` |
+| `name` | string | 是 | - | 模型名称，如 `gpt-4o`、`gemini-2.0-flash-001` |
+| `role` | text | 否 | - | 系统提示词 (System Prompt) |
+| `base_url` | string | 否 | 提供商默认 | API 端点 URL，支持 `${VAR}` 占位符 |
+| `api_key` | string | 否 | - | API 密钥，建议使用环境变量 `${API_KEY}` |
+| `params` | dict | 否 | `{}` | 模型调用参数（temperature、top_p 等） |
+| `tooling` | object | 否 | - | 工具调用配置，详见 [Tooling 模块](../modules/tooling/README.md) |
+| `thinking` | object | 否 | - | 思维链配置，如 chain-of-thought、reflection |
+| `memories` | list | 否 | `[]` | 记忆绑定配置，详见 [Memory 模块](../modules/memory.md) |
+| `skills` | object | 否 | - | Agent Skills 发现配置，以及内置的技能激活/文件读取工具 |
+| `retry` | object | 否 | - | 自动重试策略配置 |
+
+### 重试策略配置 (retry)
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | bool | `true` | 是否启用自动重试 |
+| `max_attempts` | int | `5` | 最大尝试次数（含首次） |
+| `min_wait_seconds` | float | `1.0` | 最小退避等待时间 |
+| `max_wait_seconds` | float | `6.0` | 最大退避等待时间 |
+| `retry_on_status_codes` | list[int] | `[408,409,425,429,500,502,503,504]` | 触发重试的 HTTP 状态码 |
+
+### Agent Skills 配置 (skills)
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | bool | `false` | 是否为该节点启用 Agent Skills |
+| `allow` | list[object] | `[]` | 可选的技能白名单，来源于项目级 `.agents/skills/` 目录；每个条目使用 `name` |
+
+### Agent Skills 说明
+
+- 技能统一从固定的项目级 `.agents/skills/` 目录中发现。
+- 运行时会暴露两个内置技能工具：`activate_skill` 和 `read_skill_file`。
+- `read_skill_file` 只有在对应技能已经激活后才可用。
+- 技能 `SKILL.md` 的 frontmatter 可以包含可选的 `allowed-tools`，格式遵循 Agent Skills 规范，例如 `allowed-tools: execute_code`。
+- 如果某个已选择技能依赖的工具没有绑定到当前节点，该技能会在运行时被跳过。
+- 如果最终没有任何兼容技能可用，Agent 会被明确告知不要声称自己使用了技能。
+
+## 何时使用
+
+- **文本生成**：写作、翻译、摘要、问答等
+- **智能对话**：多轮对话、客服机器人
+- **工具调用**：让模型调用外部 API 或执行函数
+- **复杂推理**：配合 thinking 配置进行深度思考
+- **知识检索**：配合 memories 实现 RAG 模式
+
+## 示例
+
+### 基础配置
+
+```yaml
+nodes:
+  - id: Writer
+    type: agent
+    config:
+      provider: openai
+      base_url: ${BASE_URL}
+      api_key: ${API_KEY}
+      name: gpt-4o
+      role: |
+        你是一位专业的技术文档撰写者，请用清晰简洁的语言回答问题。
+      params:
+        temperature: 0.7
+        max_tokens: 2000
+```
+
+### 配置工具调用
+
+```yaml
+nodes:
+  - id: Assistant
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      tooling:
+        type: function  # 工具类型：function, mcp_remote, mcp_local
+        config:
+          tools:  # 函数工具列表，来自 functions/function_calling/ 目录
+            - name: describe_available_files
+            - name: load_file
+          timeout: 20  # 可选：执行超时（秒）
+```
+
+### 配置 MCP 工具（Remote HTTP）
+
+```yaml
+nodes:
+  - id: MCP Agent
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      tooling:
+        type: mcp_remote
+        config:
+          server: http://localhost:8080/mcp  # MCP 服务器端点
+          headers:  # 可选：自定义请求头
+            Authorization: Bearer ${MCP_TOKEN}
+          timeout: 30  # 可选：请求超时（秒）
+```
+
+### 配置 MCP 工具（Local stdio）
+
+```yaml
+nodes:
+  - id: Local MCP Agent
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      tooling:
+        type: mcp_local
+        config:
+          command: uvx  # 启动命令
+          args: ["mcp-server-sqlite", "--db-path", "data.db"]
+          cwd: ${WORKSPACE}  # 可选，一般不需要配置
+          env:  # 可选，一般不需要配置
+            DEBUG: "true"
+          startup_timeout: 10  # 可选：启动超时（秒）
+```
+
+### Gemini 多模态配置
+
+```yaml
+nodes:
+  - id: Vision Agent
+    type: agent
+    config:
+      provider: gemini
+      base_url: https://generativelanguage.googleapis.com
+      api_key: ${GEMINI_API_KEY}
+      name: gemini-2.5-flash-image
+      role: 你需要根据用户的输入，生成相应的图像内容。
+```
+
+### 配置重试策略
+
+```yaml
+nodes:
+  - id: Robust Agent
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      retry:  # retry 默认启用，可以自己配置
+        enabled: true
+        max_attempts: 3
+        min_wait_seconds: 2.0
+        max_wait_seconds: 10.0
+```
+
+### 配置 Agent Skills
+
+```yaml
+nodes:
+  - id: Skilled Agent
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      skills:
+        enabled: true
+        allow:
+          - name: python-scratchpad
+          - name: rest-api-caller
+```
+
+## 相关文档
+
+- [Tooling 模块配置](../modules/tooling/README.md)
+- [Memory 模块配置](../modules/memory.md)
+- [工作流编排指南](../workflow_authoring.md)

docs/user_guide/zh/nodes/human.md

@@ -0,0 +1,114 @@
+# Human 节点
+
+Human 节点用于在工作流执行过程中引入人工交互，允许用户在 Web UI 中查看当前状态并提供输入。这种节点会阻塞工作流执行，直到用户提交响应。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `description` | text | 否 | - | 显示给用户的任务描述，说明需要人工完成的操作 |
+
+## 核心概念
+
+### 阻塞等待机制
+
+当工作流执行到 Human 节点时：
+1. 工作流暂停，等待人工输入
+2. Web UI 显示当前上下文和任务描述
+3. 用户在界面中输入响应
+4. 工作流继续执行，将用户输入传递给下游节点
+
+### 与 Web UI 交互
+
+- Human 节点在 Launch 界面以对话形式呈现
+- 用户可以查看之前的执行历史
+- 支持附件上传（如文件、图片）
+
+## 何时使用
+
+- **审核确认**：让人工审核 LLM 输出后继续
+- **修改意见**：收集用户对生成内容的修改建议
+- **关键决策**：需要人工判断才能继续的分支
+- **数据补充**：需要用户提供额外信息
+- **质量把关**：在关键节点引入人工质检
+
+## 示例
+
+### 基础配置
+
+```yaml
+nodes:
+  - id: Human Reviewer
+    type: human
+    config:
+      description: 请审阅上述内容，如满意请输入 ACCEPT，否则输入修改意见。
+```
+
+### 人机协作循环
+
+```yaml
+nodes:
+  - id: Article Writer
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      role: 你是一位专业作家，根据用户要求撰写文章。
+
+  - id: Human Reviewer
+    type: human
+    config:
+      description: |
+        请审阅文章：
+        - 满意结果请输入 ACCEPT 结束流程
+        - 否则输入修改意见继续迭代
+
+edges:
+  - from: Article Writer
+    to: Human Reviewer
+  - from: Human Reviewer
+    to: Article Writer
+    condition:
+      type: keyword
+      config:
+        none: [ACCEPT]
+        case_sensitive: false
+```
+
+### 多阶段审核
+
+```yaml
+nodes:
+  - id: Draft Generator
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+  - id: Content Review
+    type: human
+    config:
+      description: 请审核内容准确性，输入 APPROVED 或修改意见。
+
+  - id: Final Reviewer
+    type: human
+    config:
+      description: 最终确认，输入 PUBLISH 发布或 REJECT 驳回。
+
+edges:
+  - from: Draft Generator
+    to: Content Review
+  - from: Content Review
+    to: Final Reviewer
+    condition:
+      type: keyword
+      config:
+        any: [APPROVED]
+```
+
+## 最佳实践
+
+- 在 `description` 中清晰说明期望的操作和关键词
+- 使用条件边配合关键词实现流程控制
+- 考虑添加超时机制避免工作流无限等待

docs/user_guide/zh/nodes/literal.md

@@ -0,0 +1,140 @@
+# Literal 节点
+
+Literal 节点用于输出固定的文本内容。当节点被触发时，它会忽略所有输入，直接输出预定义的消息。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `content` | text | 是 | - | 输出的固定文本内容，不能为空 |
+| `role` | string | 否 | `user` | 消息角色：`user` 或 `assistant` |
+
+## 核心概念
+
+### 固定输出
+
+Literal 节点的特点：
+- **忽略输入**：不管上游传入什么内容，都不影响输出
+- **固定内容**：每次执行都输出相同的 `content`
+- **角色标记**：输出消息带有指定的角色标识
+
+### 消息角色
+
+- `user`：表示这是用户发出的消息
+- `assistant`：表示这是助手（AI）发出的消息
+
+角色设置会影响下游节点对消息的处理方式。
+
+## 何时使用
+
+- **固定提示注入**：向流程中注入固定的指令或上下文
+- **测试调试**：使用固定输入测试下游节点
+- **默认响应**：在特定条件下返回固定消息
+- **流程初始化**：作为工作流的起点提供初始内容
+
+## 示例
+
+### 基础用法
+
+```yaml
+nodes:
+  - id: Welcome Message
+    type: literal
+    config:
+      content: |
+        欢迎使用智能助手！请描述您的需求。
+      role: assistant
+```
+
+### 注入固定上下文
+
+```yaml
+nodes:
+  - id: Context Injector
+    type: literal
+    config:
+      content: |
+        请注意以下规则：
+        1. 回答必须简洁明了
+        2. 使用中文回复
+        3. 如有不确定，请说明
+      role: user
+
+  - id: Assistant
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+edges:
+  - from: Context Injector
+    to: Assistant
+```
+
+### 条件分支中的固定响应
+
+```yaml
+nodes:
+  - id: Classifier
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      role: 判断用户意图，回复 KNOWN 或 UNKNOWN
+
+  - id: Known Response
+    type: literal
+    config:
+      content: 我能帮助您完成这个任务。
+      role: assistant
+
+  - id: Unknown Response
+    type: literal
+    config:
+      content: 抱歉，我无法理解您的请求，请换一种方式描述。
+      role: assistant
+
+edges:
+  - from: Classifier
+    to: Known Response
+    condition:
+      type: keyword
+      config:
+        any: [KNOWN]
+  - from: Classifier
+    to: Unknown Response
+    condition:
+      type: keyword
+      config:
+        any: [UNKNOWN]
+```
+
+### 测试用途
+
+```yaml
+nodes:
+  - id: Test Input
+    type: literal
+    config:
+      content: |
+        这是一段测试文本，用于验证下游处理逻辑。
+        包含多行内容。
+      role: user
+
+  - id: Processor
+    type: python
+    config:
+      timeout_seconds: 30
+
+edges:
+  - from: Test Input
+    to: Processor
+
+start: [Test Input]
+```
+
+## 注意事项
+
+- `content` 字段不能为空字符串
+- 使用 YAML 多行字符串语法 `|` 便于编写长文本
+- 选择正确的 `role` 以确保下游节点正确处理消息

docs/user_guide/zh/nodes/loop_counter.md

@@ -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)"`

docs/user_guide/zh/nodes/passthrough.md

@@ -0,0 +1,206 @@
+# Passthrough 节点
+
+Passthrough 节点是最简单的节点类型，它不执行任何操作，仅将接收到的消息传递给下游节点。默认情况下只传递**最后一条消息**。它主要用于图结构的"理线"优化和上下文控制。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `only_last_message` | bool | 否 | `true` | 是否只传递最后一条消息。设为 `false` 时传递所有消息。 |
+
+### 基本配置
+
+```yaml
+config: {}  # 使用默认配置，只传递最后一条消息
+```
+
+### 传递所有消息
+
+```yaml
+config:
+  only_last_message: false  # 传递所有接收到的消息
+```
+
+## 核心概念
+
+### 透传行为
+
+- 接收上游传入的所有消息
+- **默认只传递最后一条消息**（`only_last_message: true`）
+- 设置 `only_last_message: false` 时传递所有消息
+- 不做任何内容处理或转换
+
+### 图结构优化
+
+Passthrough 节点的核心价值不在于数据处理，而在于**图结构的优化**（"理线"）：
+- 使复杂的边连接更加清晰
+- 集中管理出边配置（如 `keep_message`）
+- 作为逻辑分界点，提高工作流可读性
+
+## 关键用途
+
+### 1. 作为起始节点保留初始上下文
+
+将 Passthrough 作为工作流的入口节点，配合边的 `keep_message: true` 配置，可以确保用户的初始任务始终保留在上下文中，不会被后续节点的输出覆盖：
+
+```yaml
+nodes:
+  - id: Task Keeper
+    type: passthrough
+    config: {}
+
+  - id: Worker A
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+  - id: Worker B
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+edges:
+  # 从入口分发任务，保留原始消息
+  - from: Task Keeper
+    to: Worker A
+    keep_message: true  # 保留初始任务上下文
+
+  - from: Task Keeper
+    to: Worker B
+    keep_message: true
+
+start: [Task Keeper]
+```
+
+**效果**：Worker A 和 Worker B 都能看到用户的原始输入，而不仅仅是上一个节点的输出。
+
+### 2. 过滤循环中的冗余输出
+
+在包含循环的工作流中，循环内的节点可能产生大量中间输出。如果将所有输出都传递给后续节点，会导致上下文膨胀。使用 Passthrough 节点可以**只传递循环的最终结果**：
+
+```yaml
+nodes:
+  - id: Iterative Improver
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      role: 根据反馈不断改进输出
+
+  - id: Evaluator
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      role: |
+        评估输出质量，回复 GOOD 或提供改进建议
+
+  - id: Result Filter
+    type: passthrough
+    config: {}
+
+  - id: Final Processor
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      role: 对最终结果进行后处理
+
+edges:
+  - from: Iterative Improver
+    to: Evaluator
+  
+  # 循环：评估不通过时回到改进节点
+  - from: Evaluator
+    to: Iterative Improver
+    condition:
+      type: keyword
+      config:
+        none: [GOOD]
+  
+  # 循环结束：通过 Passthrough 过滤，只传递最后一条
+  - from: Evaluator
+    to: Result Filter
+    condition:
+      type: keyword
+      config:
+        any: [GOOD]
+  
+  - from: Result Filter
+    to: Final Processor
+
+start: [Iterative Improver]
+end: [Final Processor]
+```
+
+**效果**：无论循环迭代多少次，`Final Processor` 只会收到 `Evaluator` 的最后一条输出（表示质量通过的那条），而不是所有中间结果。
+
+## 其他用途
+
+- **占位符**：在设计阶段预留节点位置
+- **条件分支**：配合条件边实现路由逻辑
+- **调试观察点**：在流程中插入便于观察的节点
+
+## 示例
+
+### 基础用法
+
+```yaml
+nodes:
+  - id: Router
+    type: passthrough
+    config: {}
+```
+
+### 条件路由
+
+```yaml
+nodes:
+  - id: Classifier
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      role: |
+        分类输入内容，回复 TECHNICAL 或 BUSINESS
+
+  - id: Router
+    type: passthrough
+    config: {}
+
+  - id: Tech Handler
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+  - id: Biz Handler
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+edges:
+  - from: Classifier
+    to: Router
+  - from: Router
+    to: Tech Handler
+    condition:
+      type: keyword
+      config:
+        any: [TECHNICAL]
+  - from: Router
+    to: Biz Handler
+    condition:
+      type: keyword
+      config:
+        any: [BUSINESS]
+```
+
+## 最佳实践
+
+- 使用有意义的节点 ID 描述其拓扑作用（如 `Task Keeper`、`Result Filter`）
+- 作为入口节点时，出边配置 `keep_message: true` 保留上下文
+- 在循环后使用，可以过滤掉冗余的中间输出

docs/user_guide/zh/nodes/python.md

@@ -0,0 +1,89 @@
+# Python 节点
+
+Python 节点用于在工作流中执行 Python 脚本或内联代码，实现自定义数据处理、API 调用、文件操作等逻辑。脚本在共享的 `code_workspace/` 目录中执行，可访问工作流上下文数据。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `interpreter` | string | 否 | 当前 Python | Python 解释器路径 |
+| `args` | list[str] | 否 | `[]` | 追加到解释器后的启动参数 |
+| `env` | dict[str, str] | 否 | `{}` | 额外环境变量，会覆盖系统默认值 |
+| `timeout_seconds` | int | 否 | `60` | 脚本执行超时时间（秒） |
+| `encoding` | string | 否 | `utf-8` | 解析 stdout/stderr 的编码 |
+
+## 核心概念
+
+### 代码工作区
+
+Python 脚本在 `code_workspace/` 目录下执行：
+- 脚本可以读写该目录中的文件
+- 多个 Python 节点共享同一工作区
+- 工作区在单次工作流执行期间持久化
+
+### 输入输出
+
+- **输入**：上游节点的输出作为环境变量或标准输入传递
+- **输出**：脚本的 stdout 输出将作为 Message 传递给下游节点
+
+## 何时使用
+
+- **数据处理**：解析 JSON/XML、数据转换、格式化
+- **API 调用**：调用第三方服务、获取外部数据
+- **文件操作**：读写文件、生成报告
+- **复杂计算**：数学运算、算法实现
+- **胶水逻辑**：连接不同节点的自定义逻辑
+
+## 示例
+
+### 基础配置
+
+```yaml
+nodes:
+  - id: Data Processor
+    type: python
+    config:
+      timeout_seconds: 120
+      env:
+        key: value
+```
+
+### 指定解释器和参数
+
+```yaml
+nodes:
+  - id: Script Runner
+    type: python
+    config:
+      interpreter: /usr/bin/python3.11
+      timeout_seconds: 300
+      encoding: utf-8
+```
+
+### 典型工作流示例
+
+```yaml
+nodes:
+  - id: LLM Generator
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+      api_key: ${API_KEY}
+      role: 你需要根据用户的输入，生成可执行的 Python 代码。代码应当包裹在 ```python ``` 之间。
+
+  - id: Result Parser
+    type: python
+    config:
+      timeout_seconds: 30
+
+edges:
+  - from: LLM Generator
+    to: Result Parser
+```
+
+## 注意事项
+
+- 确保脚本文件放置在 `code_workspace/` 目录下
+- 长时间运行的脚本应适当增加 `timeout_seconds`
+- 使用 `env` 传递额外的环境变量，可在脚本中通过 `os.getenv` 访问

docs/user_guide/zh/nodes/subgraph.md

@@ -0,0 +1,138 @@
+# Subgraph 节点
+
+Subgraph 节点允许将另一个工作流图嵌入到当前工作流中，实现流程复用和模块化设计。子图可以来自外部 YAML 文件，也可以直接在配置中内联定义。
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `type` | string | 是 | - | 子图来源类型：`file` 或 `config` |
+| `config` | object | 是 | - | 根据 `type` 不同，包含不同的配置 |
+
+### file 类型配置
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | string | 是 | 子图文件路径（相对于 `yaml_instance/` 或绝对路径） |
+
+### config 类型配置
+
+内联定义完整的子图结构，包含与顶层 `graph` 相同的字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 子图标识符 |
+| `description` | string | 否 | 子图描述 |
+| `log_level` | string | 否 | 日志级别（DEBUG/INFO） |
+| `nodes` | list | 是 | 节点列表 |
+| `edges` | list | 否 | 边列表 |
+| `start` | list | 否 | 入口节点列表 |
+| `end` | list | 否 | 出口节点列表 |
+| `memory` | list | 否 | 子图专用的 Memory 定义 |
+
+## 核心概念
+
+### 模块化复用
+
+将常用的流程片段抽取为独立的 YAML 文件，多个工作流可以复用同一子图：
+- 例如：将"文章润色"流程封装为子图
+- 不同的主工作流都可以调用该子图
+
+### 变量继承
+
+子图会继承父图的 `vars` 变量定义，支持跨层级变量传递。
+
+### 执行隔离
+
+子图作为独立单元执行，拥有自己的：
+- 节点命名空间
+- 日志级别配置
+- Memory 定义（可选）
+
+## 何时使用
+
+- **流程复用**：多个工作流共享相同的子流程
+- **模块化设计**：将复杂流程拆分为可管理的小单元
+- **团队协作**：不同团队维护不同的子图模块
+
+## 示例
+
+### 引用外部文件
+
+```yaml
+nodes:
+  - id: Review Process
+    type: subgraph
+    config:
+      type: file
+      config:
+        path: common/review_flow.yaml
+```
+
+### 内联定义子图
+
+```yaml
+nodes:
+  - id: Translation Unit
+    type: subgraph
+    config:
+      type: config
+      config:
+        id: translation_subgraph
+        description: 多语言翻译子流程
+        nodes:
+          - id: Translator
+            type: agent
+            config:
+              provider: openai
+              name: gpt-4o
+              role: 你是一位专业翻译，将内容翻译为目标语言。
+          - id: Proofreader
+            type: agent
+            config:
+              provider: openai
+              name: gpt-4o
+              role: 你是一位校对专家，检查并润色翻译内容。
+        edges:
+          - from: Translator
+            to: Proofreader
+        start: [Translator]
+        end: [Proofreader]
+```
+
+### 组合多个子图
+
+```yaml
+nodes:
+  - id: Input Handler
+    type: agent
+    config:
+      provider: openai
+      name: gpt-4o
+
+  - id: Analysis Module
+    type: subgraph
+    config:
+      type: file
+      config:
+        path: modules/analysis.yaml
+
+  - id: Report Module
+    type: subgraph
+    config:
+      type: file
+      config:
+        path: modules/report_gen.yaml
+
+edges:
+  - from: Input Handler
+    to: Analysis Module
+  - from: Analysis Module
+    to: Report Module
+```
+
+## 注意事项
+
+- 子图文件路径支持相对路径（基于 `yaml_instance/`）和绝对路径
+- 避免循环嵌套（A 引用 B，B 再引用 A）
+- 子图的 `start` 和 `end` 节点决定了数据如何流入流出，这决定了子图如何处理父图传入的消息，以及以哪个节点的最终输出作为返回给父图的消息。