修复: DOC-02+03+04 模块文档+使用手册重写对齐真实代码
- DOC-02 df-nodes: 8 节点虚构→3 实际(Ai/Script/Human 全完整实现),删 5 虚构节点(Docker/Git/Notify/HTTP/Subflow)+5 虚构 *_node.rs 文件行,补每节点真实实现要点。 - DOC-03 df-ai: 删虚构 router.rs(ModelRouter)+stream.rs(StreamCollector),trait 删 supported_features 改 endpoint(),工具数 12→19(tool_registry.rs 实际核对,核对报告 §3 称 13 亦滞后)。 - DOC-04 使用手册: 7 处过期修正(bun→npm / 任务状态 4→7 态 / 优先级 P0→P3 数字越小越高 / 节点 Script/Ai/Human / EventBus tokio broadcast 非 WebSocket / 多 Provider / 知识库 Tier1 AI 提炼+向量检索)。 主代理抽查:df-nodes 虚构节点仅历史说明残留 / 使用手册 bun 零命中。批3
This commit is contained in:
@@ -19,7 +19,7 @@
|
||||
| Anthropic Provider（流式）| ✅ Sprint 8 |
|
||||
| ContextManager（分组滑窗）| ✅ Sprint 11 |
|
||||
| embed() 向量生成 | ✅ Sprint 15 |
|
||||
| AiToolRegistry（基础设施）| ✅ Sprint 5（12 工具注册在 commands/ai.rs）|
|
||||
| AiToolRegistry（基础设施）| ✅ Sprint 5（19 工具注册在 commands/ai/tool_registry.rs）|
|
||||
| coordinator | ⬜ 空壳（B 路线待填）|
|
||||
|
||||
---
|
||||
@@ -28,17 +28,17 @@
|
||||
|
||||
```
|
||||
crates/df-ai/src/
|
||||
├── lib.rs — 公共导出
|
||||
├── provider.rs — LlmProvider trait（含 embed 默认实现）
|
||||
├── lib.rs — 公共导出 + build_provider 工厂（按协议选 OpenAICompatProvider / AnthropicCompatProvider）
|
||||
├── provider.rs — LlmProvider trait（含 embed 默认实现 + endpoint 默认实现）
|
||||
├── openai_compat.rs — OpenAI 兼容实现（chat + embed）
|
||||
├── anthropic_compat.rs — Anthropic Messages API 实现（Sprint 8）
|
||||
├── context.rs — ContextManager 分组滑动窗口（Sprint 11）
|
||||
├── ai_tools.rs — AiToolRegistry + 12 工具定义
|
||||
├── coordinator.rs — AgentCoordinator 空壳（B 路线）
|
||||
├── router.rs — ModelRouter 模型路由空壳（route() 按 TaskType 选模型，当前全返回 default_model）
|
||||
└── stream.rs — StreamCollector 流式辅助（累积 chunk.delta 文本 + 跟踪 finished 标志）
|
||||
├── ai_tools.rs — AiToolRegistry + AiTool + RiskLevel（仅基础设施；具体工具定义在 src-tauri/commands/ai/tool_registry.rs）
|
||||
└── coordinator.rs — AgentCoordinator 空壳（B 路线，有意保留勿删）
|
||||
```
|
||||
|
||||
> 注：历史文档曾列 `router.rs`（ModelRouter）与 `stream.rs`（StreamCollector）两个文件，实际均不存在（已删，见全量核对报告 §3）。
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -66,11 +66,15 @@ pub trait LlmProvider: Send + Sync {
|
||||
// Provider 名称（必填）
|
||||
fn name(&self) -> &str;
|
||||
|
||||
// 支持的特性（必填：streaming / function_calling / vision）
|
||||
fn supported_features(&self) -> ProviderFeatures;
|
||||
// 实际请求端点（默认回落 name()，provider 覆盖返真实 URL，供 401/网络错误诊断）
|
||||
fn endpoint(&self) -> String {
|
||||
self.name().to_string()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 注：历史文档曾列 `supported_features() -> ProviderFeatures`（已删），当前 trait 末项为 `endpoint()`。
|
||||
|
||||
---
|
||||
|
||||
## OpenAI 兼容 Provider（openai_compat.rs）
|
||||
@@ -169,13 +173,13 @@ GLM 端对 `tool_use_id` 为 `None`/空串的 `tool_result` 块会返 500 卡死
|
||||
|
||||
> 归属：`ai_tools.rs` 仅提供基础设施（`RiskLevel` / `AiTool` / `AiToolRegistry`）；工具的具体定义与注册在 `src-tauri/src/commands/ai/tool_registry.rs::build_ai_tool_registry`，handler 即唯一执行路径（schema+risk+实现同源）。
|
||||
|
||||
13 个内置工具，按风险分级：
|
||||
19 个内置工具，按风险分级（核对 `build_ai_tool_registry`，2026-06-15）：
|
||||
|
||||
| 风险 | 工具 |
|
||||
|------|------|
|
||||
| Low（自动执行）| list_projects / list_tasks / list_ideas / read_file / list_directory |
|
||||
| Medium（需审批）| update_project / create_project / create_task / create_idea / write_file |
|
||||
| High（需审批）| delete_project / run_workflow / run_command |
|
||||
| Low（自动执行，6）| list_projects / list_tasks / list_ideas / list_trash / read_file / list_directory |
|
||||
| Medium（需审批，7）| update_project / create_project / bind_directory / create_task / update_task / create_idea / write_file |
|
||||
| High（需审批，6）| delete_task / delete_project / restore_project / purge_project / run_workflow / run_command |
|
||||
|
||||
工具执行结果写 `ai_tool_executions` 表（审计日志）。
|
||||
|
||||
|
||||
@@ -1,48 +1,73 @@
|
||||
# df-nodes 节点集合
|
||||
|
||||
> 创建: 2026-06-10 | 状态: 初稿
|
||||
> 创建: 2026-06-10 | 最后更新: 2026-06-15
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
df-nodes 提供 DevFlow 工作流引擎的 8 种内置节点。所有节点实现 df-workflow 的 `Node` trait。
|
||||
df-nodes 提供 DevFlow 工作流引擎的内置节点。所有节点实现 df-workflow 的 `Node` trait。
|
||||
|
||||
## 当前状态
|
||||
|
||||
所有 8 种节点 Schema 已定义完整，`execute()` 方法均为空实现。
|
||||
3 种节点全部完整实现（`execute()` 非 stub，有真实逻辑 + 单测覆盖）。
|
||||
|
||||
## 节点清单
|
||||
|
||||
| 节点 | 功能 | 阻塞 | 实现状态 |
|
||||
|------|------|------|---------|
|
||||
| AINode | 调用 LLM，流式输出，工具调用 | 否 | 骨架 |
|
||||
| ScriptNode | Shell/脚本执行 | 否 | 骨架 |
|
||||
| DockerNode | Docker 容器操作 | 否 | 骨架 |
|
||||
| GitNode | Git 操作 (libgit2) | 否 | 骨架 |
|
||||
| HumanNode | 人工审批/确认 | 是 | 骨架 |
|
||||
| NotifyNode | 通知 (桌面/飞书/Webhook) | 否 | 骨架 |
|
||||
| HTTPNode | HTTP 请求 | 否 | 骨架 |
|
||||
| SubflowNode | 嵌套子工作流 | 否 | 骨架 |
|
||||
| 节点 | 功能 | 阻塞 | 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）从未实现，已从本文档删除。
|
||||
|
||||
Phase 1 阶段优先实现：
|
||||
## 节点详述
|
||||
|
||||
1. **ScriptNode** — 依赖 df-execute 的 Shell 执行器 (已可用)
|
||||
2. **HumanNode** — 阻塞节点，工作流审批需要
|
||||
### AiNode（ai_node.rs）
|
||||
|
||||
Phase 2 实现：
|
||||
工作流中无人值守的 AI 步骤：从节点 config 读取 OpenAI 兼容 / Anthropic 协议 provider 配置与 prompt，经 `df_ai::build_provider` 工厂选协议，调一次 LLM `complete()`（非流式），输出文本供下游消费。
|
||||
|
||||
3. **AINode** — 依赖 df-ai Provider 实现
|
||||
- **参数解析**：`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 自动驱动（嵌入自动化链路），非交互对话。
|
||||
|
||||
Phase 4 实现：
|
||||
### ScriptNode（script_node.rs）
|
||||
|
||||
4. **DockerNode** — 依赖 bollard crate
|
||||
5. **GitNode** — 依赖 libgit2
|
||||
6. **HTTPNode** — HTTP 客户端
|
||||
7. **NotifyNode** — 通知渠道对接
|
||||
8. **SubflowNode** — 嵌套工作流引擎
|
||||
执行 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（人工审批/确认，阻塞）
|
||||
```
|
||||
|
||||
## 依赖关系
|
||||
|
||||
@@ -50,25 +75,12 @@ Phase 4 实现：
|
||||
df-core
|
||||
← df-workflow (Node trait)
|
||||
← df-nodes
|
||||
← df-ai (AINode)
|
||||
← df-execute (ScriptNode)
|
||||
```
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
crates/df-nodes/src/
|
||||
├── lib.rs — 模块入口，注册所有节点
|
||||
├── ai_node.rs — AI 节点
|
||||
├── script_node.rs — 脚本节点
|
||||
├── docker_node.rs — Docker 节点
|
||||
├── git_node.rs — Git 节点
|
||||
├── human_node.rs — 人工审批节点
|
||||
├── notify_node.rs — 通知节点
|
||||
├── http_node.rs — HTTP 节点
|
||||
└── subflow_node.rs — 子工作流节点
|
||||
← 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)
|
||||
|
||||
Reference in New Issue
Block a user