# df-nodes 节点集合

> 创建: 2026-06-10 | 最后更新: 2026-06-15

---

## 概述

df-nodes 提供 DevFlow 工作流引擎的内置节点。所有节点实现 df-workflow 的 `Node` trait。

## 当前状态

3 种节点全部完整实现（`execute()` 非 stub，有真实逻辑 + 单测覆盖）。

## 节点清单

| 节点 | 功能 | 阻塞 | node_type | 实现状态 |
|------|------|------|-----------|---------|
| AiNode | 调用 LLM 完成文本生成/分析（非流式 complete） | 否 | `ai` | ✅ 完整 |
| ScriptNode | Shell/脚本执行 | 否 | `script` | ✅ 完整 |
| HumanNode | 人工审批/确认（单选/多选） | 是 | `human` | ✅ 完整 |

> 历史文档曾列 8 节点（AI/Script/Docker/Git/Human/Notify/HTTP/Subflow）全标骨架。实际仅 AI/Script/Human 3 节点存在，其余 5 节点（Docker/Git/Notify/HTTP/Subflow）从未实现，已从本文档删除。

## 节点详述

### AiNode（ai_node.rs）

工作流中无人值守的 AI 步骤：从节点 config 读取 OpenAI 兼容 / Anthropic 协议 provider 配置与 prompt，经 `df_ai::build_provider` 工厂选协议，调一次 LLM `complete()`（非流式），输出文本供下游消费。

- **参数解析**：`parse_params(config, inputs)` 与 `execute` 解耦（便于单测）。`prompt` 取值优先级：上游 `inputs["prompt"]` > `config.prompt`，两者皆无则报错。
- **必填**：`base_url` / `api_key`。空 `api_key` 早失败（避免空 key 吃 401 误报「Key 无效」）。
- **协议**：`protocol` 默认 `openai_compat`；`anthropic` 走 GLM 订阅 / Claude 官方。
- **model 兜底**：留空时 `default_model = "gpt-4o-mini"`，避免 provider 构造 panic。
- **输出**：`{ text, model, usage: {prompt_tokens, completion_tokens, total_tokens} }`。
- **与 AI Chat 区别**：AiNode 由 DAG Executor 自动驱动（嵌入自动化链路），非交互对话。

### ScriptNode（script_node.rs）

执行 Shell 脚本或自定义命令，复用 `df_execute::shell::execute`（跨平台：Windows `cmd /C` / Unix `sh -c`）。

- **必填**：`command`。
- **可选**：`timeout_secs`、`working_dir`。
- **失败语义**：非零退出码视为执行失败（`bail!` 带 exit_code + stderr）。
- **输出**：`{ stdout, stderr, exit_code, duration_ms }`。

### HumanNode（human_node.rs）

阻塞节点，订阅事件总线 → 发 `HumanApprovalRequest` → `select!` 轮询 `HumanApprovalResponse` / 超时 / 取消。

- **执行顺序**：先 `subscribe()` 再 `send(Request)`（broadcast 不回放，反序会丢 Response 死等到超时）；`send` 必须 `await`（否则 Future 不 poll、Request 不进 channel）。
- **审批模式**（F-260615-01）：`select_type` 缺省 `Single`，非 `"multiple"` 一律按 Single 处理。
  - Single → 决策数必须 = 1
  - Multiple → 决策数必须 ≥ 1
  - `options` 空 → 允许自由文本（仅受数量约束）；非空 → 每项必须 ∈ options
  - 兼容旧调用方：`decisions` 空但 `decision` 非空时按 `[decision]` 单值处理
- **非法决策不立即 Err**：warn 记录 + continue 续等下一条合法 Response（由超时兜底），避免一次手误杀死节点。
- **超时**：默认 3600s。
- **取消**：每 500ms tick 检查 `node_status.is_cancelled`。
- **输出**：`{ decision（首项，向后兼容）, decisions（数组）, comment }`。

## 文件结构

```
crates/df-nodes/src/
├── lib.rs          — 模块入口（声明 ai_node / human_node / script_node 三个 pub mod）
├── ai_node.rs      — AiNode（LLM 文本生成/分析）
├── script_node.rs  — ScriptNode（Shell 执行）
└── human_node.rs   — HumanNode（人工审批/确认，阻塞）
```

## 依赖关系

```
df-core
  ← df-workflow (Node trait)
    ← df-nodes
      ← df-ai (AiNode: build_provider / LlmProvider)
      ← df-execute (ScriptNode: shell::execute)
      ← df-core (HumanNode: events::WorkflowEvent / SelectType)
```

## 相关文档

- [df-workflow 工作流引擎](./df-workflow-工作流引擎-2026-06-12.md)
- [df-ai AI 集成模块](./df-ai-AI集成模块-2026-06-12.md)