diff --git a/docs/03-模块文档/df-ai-AI集成模块-2026-06-12.md b/docs/03-模块文档/df-ai-AI集成模块-2026-06-12.md index 98059b5..011ef73 100644 --- a/docs/03-模块文档/df-ai-AI集成模块-2026-06-12.md +++ b/docs/03-模块文档/df-ai-AI集成模块-2026-06-12.md @@ -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` 表（审计日志）。 diff --git a/docs/03-模块文档/df-nodes-节点集合-2026-06-12.md b/docs/03-模块文档/df-nodes-节点集合-2026-06-12.md index 76a8aa3..88e93df 100644 --- a/docs/03-模块文档/df-nodes-节点集合-2026-06-12.md +++ b/docs/03-模块文档/df-nodes-节点集合-2026-06-12.md @@ -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) diff --git a/docs/08-用户指南/使用手册-2026-06-12.md b/docs/08-用户指南/使用手册-2026-06-12.md index 98f9038..d321825 100644 --- a/docs/08-用户指南/使用手册-2026-06-12.md +++ b/docs/08-用户指南/使用手册-2026-06-12.md @@ -1,6 +1,8 @@ # DevFlow 使用手册 > "本地优先的个人开发流程驾驶舱" +> +> 本手册对齐真实代码（核对基准 2026-06-15）。命令、状态枚举、节点类型均以 `package.json` / `crates/df-core/src/types.rs` / `crates/df-nodes/src/` 为准。 ```mermaid graph LR @@ -21,9 +23,18 @@ graph LR ## 🚀 快速开始 ### 运行应用 + ```bash -bun install -bun run tauri dev +npm install +npm run tauri dev +``` + +> 命令来源：`package.json` 的 `scripts`（`dev` / `build` / `tauri`）。不要使用 `bun`，仓库脚本统一走 npm（如 `dev:restart` 内部调用 `npm run dev:stop`）。 + +构建发布包： + +```bash +npm run tauri build ``` ### 一句话功能 @@ -35,8 +46,8 @@ bun run tauri dev #### 1. 任务管理 - **创建任务**：指定项目、标题、分支名 -- **状态流转**：待开始 → 进行中 → 待审查 → 已合并 -- **优先级**：P0（紧急）到 P3（低） +- **状态流转**：见下方「任务状态」7 态 +- **优先级**：P0（紧急）到 P3（低），数字越小优先级越高 #### 2. 分支绑定 ```bash @@ -56,7 +67,7 @@ bun run tauri dev ## 📋 功能模块 ### 🤖 AI Chat -- **单 Provider**：简化配置 +- **多 Provider**：支持配置多个 AI 提供商（OpenAI / GLM / DeepSeek / Claude 兼容模式 / Anthropic 原生协议），可在「设置」中管理并指定默认 - **工具调用**：代码生成、分析 - **流式响应**：实时输出 @@ -69,12 +80,13 @@ bun run tauri dev - **状态同步**：与 Git 分支联动 ### 📚 知识库（收藏夹） -- **静态收集**：个人经验碎片 -- **分类管理**：审查规则、Prompt模板、踩坑经验 -- **快速搜索**：标题、标签、内容 +- **Tier1 AI 提炼**：从 AI 对话/工作流中自动提炼候选经验条目，附带 `reasoning`（"为何值得沉淀"）判断依据 +- **向量检索**：知识条目带 `embedding` 列，支持语义检索（OpenAI 兼容 `/v1/embeddings`，Anthropic 协议不支持 embedding） +- **分类管理**：审查规则、Prompt模板、踩坑经验等 7 种 kind +- **生命线管理**：candidate → pending_review → published → archived，带 reuse_count / verified 信号 ### ⚙️ 设置 -- **AI 配置**：Provider、模型选择 +- **AI 配置**：多 Provider 管理（新增/编辑/删除/设默认）、模型选择 - **通用设置**：主题、语言 ## 🔧 核心功能详解 @@ -142,18 +154,21 @@ bun run tauri dev - **隐私保护**：代码不出本地 ### 实时监控 -- **事件流**：WebSocket 实时更新 +- **事件流**：基于 Tauri 的 EventBus（进程内 `tokio::sync::broadcast` 发布/订阅，前端经 `@tauri-apps/api/event` 的 emit/listen 接收），非 WebSocket - **进度显示**：工作流执行进度 - **错误提示**：失败原因分析 ### 工作流节点 -```typescript -// 支持的节点类型 -- Script：执行 Shell 命令 -- Human：人工审批 -- Condition：条件判断 -- Parallel：并行执行 -``` + +实际内置 3 种节点类型（均在 `crates/df-nodes/src/` 完整实现）： + +| 节点 | 文件 | 作用 | +|------|------|------| +| **Script** | `script_node.rs` | 执行 Shell 命令（经 `df-execute::shell`），支持 `command` / `timeout_secs` / `working_dir`，非零退出码即失败 | +| **Ai** | `ai_node.rs` | 调用 LLM 完成生成/分析（OpenAI 兼容 + Anthropic 协议），由 DAG Executor 自动驱动 | +| **Human** | `human_node.rs` | 人工审批（subscribe → 发 HumanApprovalRequest → select! 等待响应），支持单选/多选 | + +> 不存在独立的 Condition / Parallel / Docker / Git / Notify / HTTP / Subflow 节点。条件分支由工作流引擎层处理。 ## 📊 使用统计 @@ -175,12 +190,20 @@ bun run tauri dev - **警告色**：黄色（#F59E0B） - **错误色**：红色（#EF4444） -### 图标含义 -- 📋：待开始 -- 🔨：进行中 -- 👀：待审查 -- ✅：已合并 -- 🗑️：已废弃 +### 任务状态图标含义 +任务共 7 个状态（对齐 `crates/df-core/src/types.rs` 的 `TaskStatus` 枚举）： + +| 状态值 | 含义 | 图标建议 | +|--------|------|----------| +| `todo` | 待开始 | 📋 | +| `in_progress` | 进行中 | 🔨 | +| `in_review` | 代码审查中 | 👀 | +| `testing` | 测试中 | 🧪 | +| `done` | 已完成 | ✅ | +| `blocked` | 已阻塞 | 🚫 | +| `cancelled` | 已取消 | 🗑️ | + +> 分支状态另设 3 态：`active` / `merged` / `abandoned`（见 `BranchStatus` 枚举，与任务状态独立）。 ## ⚠️ 注意事项 @@ -190,14 +213,14 @@ bun run tauri dev - 保持分支命名规范 ### AI 配置 -- 需要有效的 API Key +- 需要有效的 API Key（在「设置」中添加 Provider 时录入，前端做 mask 处理防泄露） - 检查网络连接 -- 关注 Token 使用量 +- 关注 Token 使用量（对话记录会累计 prompt/completion tokens 落库） ### 工作流设计 - 避免长时间阻塞操作 -- 设置合理的超时时间 -- 保留人工干预接口 +- 设置合理的超时时间（Script 节点可用 `timeout_secs`） +- 保留人工干预接口（Human 节点） ## 🔄 更新日志 @@ -222,4 +245,4 @@ bun run tauri dev --- -**记住**：这不是全流程操作系统，而是专注于本地任务流程的工具。简单、实用、可靠。 \ No newline at end of file +**记住**：这不是全流程操作系统，而是专注于本地任务流程的工具。简单、实用、可靠。