绝尘
998a2f243d
squash合并: - 意图识别层论证(8维度+10业界佐证) - 多主题上下文管理愿景+并存论证+补充论证(多轮agentic) - 架构设计文档物理分类(四子目录+INDEX+命名规范+引用同步+边界清晰化) - 前端架构技术债清单归档
283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
# DevFlow 业务系统设计
|
||
|
||
> 创建: 2026-06-10 | 状态: 设计中 | 最后重写: 2026-06-15 (DOC-01 硬伤修复)
|
||
>
|
||
> **本文档为 ARCHITECTURE.md 的实质载体**（项目无独立 ARCHITECTURE.md 文件）。所有数据模型、设计决策均以源码为基准，已剔除虚构内容。
|
||
|
||
---
|
||
|
||
## 一、产品定位
|
||
|
||
| 维度 | 定义 |
|
||
|------|------|
|
||
| **一句话** | AI 原生的个人开发流程驾驶舱，从想法到任务到工作流的本地工具 |
|
||
| **目标用户** | 个人开发者 |
|
||
| **核心价值** | 想法池 → 项目 → 任务 → 工作流（DAG），AI 贯穿每个环节 |
|
||
| **差异化** | 想法第一公民 + AI 全程参与 + 本地优先（零运维） |
|
||
|
||
---
|
||
|
||
## 二、用户旅程设计
|
||
|
||
### 2.1 核心旅程
|
||
|
||
```
|
||
想法池 项目 任务 工作流
|
||
────────────────────────────────────────────────────────────────────────────
|
||
捕捉想法 → 评估评分 → 晋升立项 → 创建任务 → 绑定分支 → 执行 DAG 工作流
|
||
│ │ │ │
|
||
└── 淘汰/归档 └── 多任务 └── 自动执行 └── Script/Ai/Human
|
||
```
|
||
|
||
### 2.2 四个阶段详细设计
|
||
|
||
#### 阶段一：想法池 (Idea Pool)
|
||
|
||
**用户场景**：快速捕捉想法、评估、筛选。
|
||
|
||
| 操作 | 描述 | AI 参与 |
|
||
|------|------|---------|
|
||
| **捕捉** | 文本输入 | 无 |
|
||
| **评估** | 启发式评分（可行性/影响力/紧迫性） | 当前固定算法，Phase 2 接 LLM |
|
||
| **晋升** | 高分想法晋升为项目 | AI 生成项目初始化建议 |
|
||
| **淘汰** | 低分想法归档或删除 | 无 |
|
||
|
||
**状态机**（对齐 `IdeaStatus` 枚举）：
|
||
```
|
||
draft → pending_review → approved → promoted（正向）
|
||
→ rejected → archived（淘汰）
|
||
```
|
||
|
||
#### 阶段二：项目 (Project)
|
||
|
||
| 操作 | 描述 | AI 参与 |
|
||
|------|------|---------|
|
||
| **创建** | 从想法晋升 或 手动创建 | AI 生成描述/技术栈建议 |
|
||
| **绑定目录** | 关联本地代码目录（自动探测技术栈） | 无 |
|
||
| **软删/恢复** | 回收站机制（deleted_at） | 无 |
|
||
|
||
**状态机**（对齐 `ProjectStatus` 枚举）：
|
||
```
|
||
planning → in_progress → testing → releasing → completed
|
||
→ paused → in_progress（恢复）
|
||
→ cancelled
|
||
```
|
||
|
||
#### 阶段三：任务 (Task)
|
||
|
||
| 操作 | 描述 | AI 参与 |
|
||
|------|------|---------|
|
||
| **创建任务** | 标题+描述 | AI 从需求拆解任务 |
|
||
| **执行工作流** | 触发 DAG 工作流 | AI 参与每个 Ai 节点 |
|
||
|
||
**状态机**（对齐 `TaskStatus` 枚举，7 态）：
|
||
```
|
||
todo → in_progress → in_review → testing → done
|
||
→ blocked → in_progress（解除阻塞）
|
||
→ cancelled
|
||
```
|
||
|
||
#### 阶段四：工作流 (Workflow)
|
||
|
||
**实际内置 3 种节点类型**（均在 `crates/df-nodes/src/` 完整实现）：
|
||
|
||
| 节点 | 文件 | 作用 | 阻塞 |
|
||
|------|------|------|------|
|
||
| **Script** | `script_node.rs` | Shell 命令执行（经 `df-execute::shell`） | 否 |
|
||
| **Ai** | `ai_node.rs` | LLM 文本生成/分析（非流式 complete） | 否 |
|
||
| **Human** | `human_node.rs` | 人工审批/确认（单选/多选） | 是 |
|
||
|
||
> 不存在 Condition / Parallel / Docker / Git / Notify / HTTP / Subflow 节点。
|
||
> 条件分支由工作流引擎层处理（条件表达式引擎见 `条件表达式引擎-2026-06-15.md`）。
|
||
|
||
**工作流执行生命周期**：
|
||
```
|
||
pending → running → completed
|
||
→ paused → running（恢复）
|
||
→ failed → running（重试）
|
||
→ cancelled
|
||
```
|
||
|
||
---
|
||
|
||
## 三、跨领域功能设计（已实现）
|
||
|
||
### 3.1 知识库 (Knowledge)
|
||
|
||
Tier1 AI 提炼：从 AI 对话中自动提炼候选经验条目，附带 reasoning 判断依据。
|
||
|
||
| 知识类型 | 来源 | 复用场景 |
|
||
|---------|------|---------|
|
||
| 审查规则 | 代码审查结论 | 后续审查参考 |
|
||
| Prompt 模板 | 成功的 AI 对话 | 类似场景复用 |
|
||
| 踩坑经验 | 错误修复过程 | 类似问题提醒 |
|
||
|
||
**生命线**：candidate → pending_review → published → archived，带 reuse_count / verified 信号。
|
||
|
||
### 3.2 AI 多 Provider
|
||
|
||
支持配置多个 AI 提供商（OpenAI 兼容 / GLM / DeepSeek / Anthropic 原生协议），可在设置中管理并指定默认。
|
||
|
||
详见 [df-ai AI集成模块](../03-模块文档/df-ai-AI集成模块-2026-06-12.md)。
|
||
|
||
### 3.3 EventBus 事件总线
|
||
|
||
进程内 `tokio::sync::broadcast` 发布/订阅，前端经 `@tauri-apps/api/event` 的 emit/listen 接收。**不是 WebSocket**。
|
||
|
||
---
|
||
|
||
## ~~三、跨领域功能设计（已废弃规划）~~
|
||
|
||
> 以下章节曾详述标注系统、决策留痕、经验进化、AI 编排（ModelRouter/Agent 协作）等设计。
|
||
> 这些功能**从未实现**，对应表（annotations/decisions/features/test_cases）也从未建表。
|
||
> 保留此节仅作历史存档参考，读者应视为"规划意图"而非"现有能力"。
|
||
|
||
### ~~3.1 标注系统 (Annotation)~~ — ❌ 未实现
|
||
|
||
### ~~3.2 决策留痕 (Decision Journal)~~ — ❌ 未实现
|
||
|
||
### ~~3.3 经验进化 (Evolution)~~ — ⚠️ 部分落地为知识库（knowledges 表），但远不及原规划规模
|
||
|
||
### ~~3.4 AI 编排（ModelRouter / Agent 协作）~~ — ❌ ModelRouter 从未存在；Agent 协作属 Phase 2 规划（B 路线）
|
||
|
||
---
|
||
|
||
## 四、数据模型设计（V1-V13 迁移实际表）
|
||
|
||
> 核对基准：`crates/df-storage/src/migrations.rs` 建表 SQL + `models.rs` Record 结构体。
|
||
|
||
### 全量表清单（13 业务表 + 1 元表）
|
||
|
||
#### 活跃业务表（11 张）— 有上层代码读写
|
||
|
||
| # | 表名 | 建表版本 | 用途 | 对应 Model | 活跃消费者 |
|
||
|---|------|---------|------|-----------|-----------|
|
||
| 1 | `ideas` | V1+V2 | 想法池 | IdeaRecord | df-ideas crate |
|
||
| 2 | `projects` | V1+V11+V12 | 项目管理 | ProjectRecord | df-project crate |
|
||
| 3 | `tasks` | V1+V2 | 任务管理 | TaskRecord | commands::task（IPC handler 直连 CRUD） |
|
||
| 4 | `workflow_executions` | V1+V2 | 工作流执行实例 | WorkflowRecord | df-workflow crate |
|
||
| 5 | `node_executions` | V1 | 节点执行审计 | NodeExecutionRecord | df-workflow executor |
|
||
| 6 | `ai_conversations` | V3+V4/V5/V6 | AI 对话历史 | AiConversationRecord | commands::ai |
|
||
| 7 | `ai_providers` | V9 | AI 提供商配置 | AiProviderRecord | commands::ai::provider |
|
||
| 8 | `ai_tool_executions` | V9 | AI 工具调用审计 | AiToolExecutionRecord | commands::ai |
|
||
| 9 | `knowledges` | V7+V8/V10 | 知识库条目 | KnowledgeRecord | commands::knowledge |
|
||
| 10 | `knowledge_events` | V10 | 知识生命线事件 | KnowledgeEventRecord | commands::knowledge |
|
||
| 11 | `app_settings` | V13 | 通用 KV 设置 | (无独立 model) | commands::settings（手写 Repo） |
|
||
|
||
#### 遗留表（2 张）— DDL 存在但无活跃业务消费者
|
||
|
||
> `df-task` crate 已于 2026-06-14 移除（零引用清理）。以下表仍在 migrations.rs 中创建、models.rs 有结构体、CRUD 可用，但当前**无上层业务代码写入或消费**。
|
||
|
||
| # | 表名 | 建表版本 | 原始用途 | 状态 |
|
||
|---|------|---------|---------|------|
|
||
| 12 | `branches` | V2 | Git 分支绑定 | ⚠️ 无消费者（DDL 存在，CRUD 可用但无人调用） |
|
||
| 13 | `releases` | V1 | 发布记录 | ⚠️ **功能性死表**：DDL 存在且含 version/status/task_ids/changelog/released_at 完整 schema，但全代码库零业务读写——无 ReleaseStatus 枚举、无 release 相关 IPC command、前端无发布管理页面。属"建了但从未使用"的空壳占位。 |
|
||
|
||
#### 内部元表
|
||
|
||
| # | 表名 | 建表版本 | 用途 |
|
||
|---|------|---------|------|
|
||
| - | `schema_version` | V0 | 迁移版本跟踪（仅存 version INTEGER，无业务语义） |
|
||
|
||
### 不存在的表（曾出现在早期规划但从未建表）
|
||
|
||
| 表名 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| `workflow_defs` | ❌ 从未建表 | 工作流定义以 dag_json 内嵌在 workflow_executions 中 |
|
||
| `connections` | ❌ 从未建表 | 连接配置使用 app_settings KV 表存储 |
|
||
| `artifacts` | ❌ 从未建表 | 产出物概念未落地 |
|
||
| `annotations` | ❌ 从未建表 | 标注系统属已废弃规划 |
|
||
| `decisions` | ❌ 从未建表 | 决策留痕属已废弃规划 |
|
||
| `features` | ❌ 从未建表 | 需求功能清单未落地 |
|
||
| `test_cases` / `test_runs` | ❌ 从未建表 | 测试模块未落地 |
|
||
| `knowledge`（单数）| ❌ 不存在的旧命名 | 实际表名为 `knowledges`（复数），V7 建表 |
|
||
| `merge_requests` | ❌ 从未建表 | 合并请求未落地 |
|
||
|
||
---
|
||
|
||
## 五、关键设计决策
|
||
|
||
### D1: 想法是第一公民
|
||
- 想法池独立于项目，可以独立运转
|
||
- 晋升是单向操作（想法→项目），但保留追溯
|
||
|
||
### D2: 本地优先
|
||
- SQLite 嵌入，不依赖云服务
|
||
- 所有数据存储在本地
|
||
- 零运维，安装即用
|
||
|
||
### D3: 引擎不绑定业务
|
||
- DAG 引擎纯粹做编排，不感知具体业务语义
|
||
- 业务逻辑在 df-nodes 实现（Node trait 是纯接口）
|
||
|
||
### D4: AI 贯穿全程
|
||
- AI Chat 对话 + 工作流 AiNode 双路径
|
||
- AI 输出作为决策依据，最终决策权在人
|
||
|
||
---
|
||
|
||
## 六、Crate 结构
|
||
|
||
实际 **8 个 crate**（`crates/` 目录下）：
|
||
|
||
| Crate | 职责 |
|
||
|-------|------|
|
||
| `df-core` | 公共类型（types.rs）、事件定义、工具函数 |
|
||
| `df-workflow` | DAG 引擎（拓扑排序、执行器、Node trait） |
|
||
| `df-nodes` | 内置节点（Ai / Script / Human） |
|
||
| `df-ai` | AI 集成层（LlmProvider trait、OpenAI 兼容、Anthropic、ContextManager、工具注册基础设施） |
|
||
| `df-execute` | Shell 执行（跨平台封装） |
|
||
| `df-storage` | SQLite 存储层（migrations、CRUD 宏、Repo） |
|
||
| `df-ideas` | 想法池业务逻辑（评估、晋升） |
|
||
| `df-project` | 项目管理业务逻辑（目录绑定、技术栈探测） |
|
||
|
||
> 原始设计文档（Phase1架构决策 ADR-003）曾写 "13 个独立 crate"，属过时数字，未随代码演进更新。实际为以上 8 个。
|
||
|
||
---
|
||
|
||
## 七、MVP 验证场景
|
||
|
||
**Phase 1 目标**：跑通"创建想法 → 晋升项目 → 创建任务 → 执行 3 节点工作流 → 查看结果"
|
||
|
||
```
|
||
1. 用户在想法池输入"做一个 Markdown 编辑器"
|
||
2. 启发式评估可行性，给出评分和建议
|
||
3. 用户点击"晋升为项目"
|
||
4. 系统创建项目
|
||
5. 用户创建任务"实现基础编辑功能"
|
||
6. 用户点击"运行工作流"
|
||
7. DAG 执行: [Script: 环境检查] → [Ai: 代码生成] → [Human: 审批]
|
||
8. 前端经 EventBus 实时展示执行日志
|
||
9. 执行完成，结果持久化到 SQLite
|
||
10. 用户刷新页面，数据仍在
|
||
```
|
||
|
||
---
|
||
|
||
## 八、已确认的设计决策
|
||
|
||
### Q1: 想法评分维度 ✅ 已确认
|
||
**决策**：采用 C 方案 — 可行性/影响力/紧迫性 + 综合分 (3+1 维)
|
||
- 与 `evaluator.rs` 已实现的 `EvalDimension` 对齐
|
||
- `IdeaScores { feasibility, impact, urgency, overall }` 保留
|
||
|
||
### Q2: 发布模块 ✅ 已确认（当前为死表状态）
|
||
**决策**：Phase 1 不做发布功能。releases 表 DDL 存在但无业务逻辑，待后续激活。
|
||
- 不做自动化发布流程
|
||
- 前端无发布入口
|
||
|
||
### Q3: AI 评估 Phase 1 范围 ✅ 已确认
|
||
**决策**：Phase 1 用固定算法评分，延后接入 LLM
|
||
- `ScoringEngine` 当前返回基于启发式规则的分数
|
||
- Phase 2 接入 LLM 后替换为 AI 评分
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [df-nodes 节点集合](../03-模块文档/df-nodes-节点集合-2026-06-12.md) — 3 节点详述
|
||
- [df-ai AI 集成模块](../03-模块文档/df-ai-AI集成模块-2026-06-12.md) — Provider / Context / 工具注册
|
||
- [df-storage 存储层](../03-模块文档/df-storage-存储层-2026-06-12.md) — 迁移 / CRUD / Repo
|
||
- [df-workflow 工作流引擎](../03-模块文档/df-workflow-工作流引擎-2026-06-12.md) — DAG / Executor
|
||
- [Phase1 架构决策](./Phase1架构决策-2026-06-12.md) — ADR 记录（注意：ADR-001/003 含过时信息，以本文档为准）
|