DevFlow/ARCHITECTURE.md

DevFlow — 产研全流程工作流平台

版本: v0.1.0 | 创建: 2026-06-10 | 状态: 设计阶段

一、项目定位

AI 原生的产研操作系统，从想法到上线的全流程编排。

核心特性

• 想法池 (Idea Pool)：持续捕捉、AI 评估、漏斗筛选、晋升立项
• 多项目并行：多项目同时推进，共享 AI/执行资源
• 多任务/分支并行：同一项目内多任务同时开发，各绑独立 Git 分支，完成后合并
• 工作流引擎：DAG 驱动，节点可扩展，支持条件分支和断点续跑
• AI 编排：多模型并行（Claude/GLM/DeepSeek），多 Agent 协作
• 标注系统 (Annotation)：所有内容支持 FIXME/TODO/QUESTION 等标注，统一收集后批量交给 AI 处理
• 需求-功能-测试可追溯：功能可选做/延/不做，每个功能对应测试用例和测试报告
• 决策留痕 (Decision Journal)：所有关键决策自动记录（原因/方案/时间/上下文），全程可追溯
• 经验进化 (Evolution)：开发过程中的模式自动沉淀为知识库（审查规则/Prompt模板/踩坑经验），持续进化复用
• 阶段插件：想法→需求→编码→测试→发布，阶段即模板

层级模型

💡 Idea Pool (想法池) — 独立运转，持续捕捉和评估
  └→ 📂 Project (项目) — 多项目并行
       ├→ 🔀 Task (任务) — 绑定 Git 分支，独立工作流
       │    └→ Workflow DAG (编码→测试→审查)
       ├→ 🔀 Task (任务) — 另一个并行任务
       │    └→ Workflow DAG
       └→ 🎯 Release (发布) — 合并多个 Task → 集成测试 → 发布

二、技术栈

层	技术	说明
Desktop	Tauri v2	Rust 后端 + WebView 前端
Frontend	Vue 3 + TypeScript + Pinia	Arco Design 组件库
Engine	Rust (Workspace)	多 crate 架构
Storage	SQLite (rusqlite)	本地优先，零运维
AI	Multi-Provider	Claude/GLM/DeepSeek/OpenAI 兼容
Container	Docker (bollard)	隔离构建/测试环境

三、系统架构

┌──────────────────────────────────────────────────────────────────┐
│                        DevFlow Desktop                            │
│                     Tauri v2 · Vue 3 · TS                        │
├──────────────────────────────────────────────────────────────────┤
│  💡 Idea Pool          │  📂 Multi-Project Manager              │
│  捕捉·评估·晋升         │  多项目并行·资源调度                     │
├────────────────────────┴─────────────────────────────────────────┤
│  🔀 Task & Branch Manager (任务/分支管理)                         │
│  多任务并行·分支创建·合并协调·冲突解决                              │
│  ┌──────────┬──────────┬──────────┬──────────────────────────┐  │
│  │ Task A   │ Task B   │ Task C   │ Release                  │  │
│  │ feat/auth│feat/pay  │fix/login │ main                     │  │
│  │ [DAG]    │ [DAG]    │ [DAG]    │ [合并→测试→发布]          │  │
│  └──────────┴──────────┴──────────┴──────────────────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│  Workflow Engine (DAG · Node · State · Event · Persist)          │
├──────────────────────┬───────────────────────────────────────────┤
│  AI Orchestrator     │  Execution Runtime                        │
│  Multi-Provider      │  Shell · Docker · SSH · Git (libgit2)     │
│  Agent Coordinator   │  Merge · Conflict Resolve                 │
├──────────────────────┴───────────────────────────────────────────┤
│  Storage Layer (SQLite)                                          │
│  ideas · projects · tasks · branches · workflows · artifacts     │
└──────────────────────────────────────────────────────────────────┘

四、Crate 结构

devflow/
├── Cargo.toml                     # Workspace 根
├── crates/
│   ├── df-core/                   # 核心类型、错误、常量、事件
│   ├── df-workflow/               # 工作流 DAG 引擎 (核心)
│   ├── df-nodes/                  # 内置节点集合 (AI/Script/Docker/Git/Human/HTTP/Subflow)
│   ├── df-ai/                     # AI 编排层 (Multi-Provider/Router/Coordinator)
│   ├── df-execute/                # 执行运行时 (Shell/Docker/SSH/Git)
│   ├── df-storage/                # 存储层 (SQLite)
│   ├── df-ideas/                  # 想法池引擎 (捕捉/评估/评分/晋升)
│   └── df-project/                # 多项目管理 (调度/上下文/时间线)
│
│   注: df-task / df-traceability / df-evolve / df-stages / df-plugin
│       5 个 crate 已移除（2026-06-14 零引用清理，推翻原"保留骨架"取舍）
├── src/                           # Tauri 主入口
│   ├── main.rs
│   ├── state.rs
│   └── commands/                  # IPC 命令
├── frontend/                      # Vue 3 前端
│   └── src/
│       ├── views/                 # 页面组件
│       ├── components/            # 业务组件
│       ├── stores/                # Pinia 状态
│       └── composables/           # 组合式函数
├── templates/                     # 工作流模板 (YAML)
└── plugins/                       # 外部插件目录

五、核心模块设计

5.1 Workflow Engine (df-workflow)

引擎不感知具体业务，只负责 DAG 执行。

• Node trait：所有节点的统一抽象 (execute, schema, is_blocking)
• DAG Executor：拓扑排序 → 并行调度 → 状态流转 → 持久化
• EventBus：tokio::sync::broadcast 异步事件广播
• Persister：SQLite 快照，支持断点续跑
• Conditions：基于表达式的条件分支引擎

5.2 Idea Pool (df-ideas)

想法是独立于项目的第一公民。

• Capture：文本/剪贴板/快捷键捕捉，不打断当前工作
• Evaluator：AI 自动评估市场潜力、竞品、技术可行性
• Scoring：多维加权评分 (0-100)
• Graph：想法关联图，相似想法自动发现，可合并
• Promotion：高分想法晋升为项目，自动携带评估结论

想法状态：Draft → PendingReview → Approved → Promoted / Rejected / Archived

5.3 Multi-Project Manager (df-project)

• ProjectSlot：每个项目的运行时槽位（活跃任务数、优先级、AI 配额）
• Scheduler：AI 并发预算分配、Docker 资源配额
• Context：项目上下文（代码结构、依赖、规范），供 AI 消费
• Timeline：项目时间线，所有事件的时序视图

项目状态：Planning / InProgress / Testing / Releasing / Completed / Paused / Cancelled

5.3.1 Task & Branch Manager (df-task) — 已移除

2026-06-14 零引用清理：df-task crate 已删除。以下内容保留作为历史设计参考，不再对应实际代码。

项目内部的并行任务管理，每个任务绑定一个 Git 分支。

• Task：独立工作单元，包含标题、描述、绑定的分支、关联的工作流
• BranchManager：自动创建分支、跟踪分支状态、与 main 的 diff 统计
• MergeCoordinator：合并策略管理、冲突检测、AI 辅助冲突解决
• ReleasePlanner：选择多个已完成的 Task 合并，编排集成测试和发布流程

Task 生命周期:
  Todo → InProgress → InReview → Testing → Done
    ↓ (随时)       ↓
  Blocked        Cancelled

分支策略:
  main ────────────────────────────────
    └── feature/auth ──── ✅ merged
    └── feature/payment ─ 🔄 in progress
    └── bugfix/login ──── ✅ merged
    └── release/v2.3 ──── ⏳ waiting (merge auth + payment)

合并协调:

1. 冲突检测：Task 完成时自动检测与 main 的冲突
2. AI 辅助解决：冲突文件交给 AI 分析并建议解决方案
3. 发布编排：选择多个 Task → 创建 release 分支 → 合并 → 集成测试 → 发布

5.4 Traceability & Annotation (df-traceability) — 已移除

2026-06-14 零引用清理：df-traceability crate 已删除。以下内容保留作为历史设计参考，不再对应实际代码。

贯穿所有阶段的可追溯性引擎。

5.4.1 标注系统 (Annotation)

任何内容（需求文档、代码、测试报告、设计文档）中都可以插入标注：

标记	含义	场景
[FIXME]	需要修复	代码/文档中发现问题
[TODO]	待办事项	后续需要补充的内容
[QUESTION]	疑问待确认	需要人工决策的问题
[RISK]	风险标记	潜在的技术/业务风险
[DECISION]	决策标记	记录为什么做此选择
[OPTIMIZE]	优化建议	可改进但不紧急

批量处理流程：

人工在各内容中插标注 → 系统统一收集所有未处理标注
    → 按类型/优先级分组 → 一键交给 AI 批量处理
    → AI 逐条处理并标记完成 → 人工确认处理结果

标注可以附加在任何实体上（需求、功能、代码文件、测试用例）。

5.4.2 需求-功能-测试映射

📋 需求 (Requirement)
  └→ 功能 (Feature) [状态: Selected / Deferred / Rejected]
       └→ 测试用例 (TestCase) [自动/手动生成]
            └→ 测试执行记录 (TestRun)
                 └→ 测试报告 (TestReport)

• 功能状态：Selected(选中做) / Deferred(延期) / Rejected(不做)
• 每个功能可标注不做的原因（自动进入决策留痕）
• AI 根据功能描述自动生成测试用例
• 测试用例与功能双向关联，覆盖率一目了然
• 测试报告自动生成，标注 PASS/FAIL/SKIP

5.4.3 决策留痕 (Decision Journal)

所有关键决策自动或半自动记录，全程可追溯。

pub struct Decision {
    pub id: DecisionId,
    pub project_id: ProjectId,
    pub context: String,          // 决策背景
    pub question: String,         // 需要决定的问题
    pub alternatives: Vec<String>,// 考虑过的方案
    pub decision: String,         // 最终决定
    pub reason: String,           // 决策原因
    pub decided_by: DecidedBy,    // AI / Human
    pub related_entity: EntityRef,// 关联实体(功能/需求/代码等)
    pub impact: String,           // 影响范围
    pub created_at: DateTime,
}

自动记录的决策场景：

• 功能标记为"不做"时，强制填写原因
• AI 选择了方案 A 而非方案 B 时，记录理由
• 代码审查中发现风险时的处理决策
• 测试失败后的修复策略选择
• 发布前的检查点决策

决策时间线视图：按时间展示项目的所有决策，支持按类型/阶段筛选。

5.4 AI Orchestrator (df-ai)

• LlmProvider trait：统一接口，各模型实现
• ModelRouter：按任务类型路由到最优模型 + 降级链
• AgentCoordinator：多 Agent 协作（Planner/Coder/Reviewer/Fixer）
• ContextManager：Token 预算管理
• ToolRegistry：工具注册（供 Agent 调用）

5.5 内置节点 (df-nodes)

节点	功能
AINode	调用 LLM，支持流式输出、工具调用
ScriptNode	Shell/脚本执行
DockerNode	Docker 容器操作
GitNode	Git 操作 (libgit2)
HumanNode	人工审批/确认 (阻塞)
NotifyNode	通知 (桌面/飞书/Webhook)
HTTPNode	HTTP 请求
SubflowNode	嵌套子工作流

六、数据模型

SQLite 表结构

-- 想法池
CREATE TABLE ideas (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    tags TEXT, -- JSON array
    source TEXT NOT NULL, -- Manual/Clipboard/AI
    status TEXT NOT NULL, -- Draft/PendingReview/Approved/Rejected/Promoted/Archived
    scores TEXT, -- JSON: {market_potential, competition, feasibility, roi, overall}
    ai_analysis TEXT,
    related_ideas TEXT, -- JSON array of idea ids
    promoted_to TEXT, -- project id
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 项目
CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    idea_id TEXT, -- 来源想法
    repo_path TEXT, -- 仓库路径
    tech_stack TEXT, -- JSON array
    status TEXT NOT NULL, -- Planning/InProgress/Testing/Releasing/Completed/Paused/Cancelled
    priority INTEGER NOT NULL DEFAULT 1, -- 0=Low, 1=Medium, 2=High, 3=Critical
    current_stage TEXT, -- Idea/Requirement/Coding/Testing/Release
    config TEXT, -- JSON: 项目级配置
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 工作流定义
CREATE TABLE workflow_defs (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    task_id TEXT, -- 关联的任务 (可为空，如项目级工作流)
    name TEXT NOT NULL,
    description TEXT,
    dag TEXT NOT NULL, -- JSON: DAG 结构
    template_id TEXT, -- 来源模板
    version INTEGER NOT NULL DEFAULT 1,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 任务 (项目内的并行工作单元)
CREATE TABLE tasks (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    status TEXT NOT NULL, -- Todo/InProgress/InReview/Testing/Done/Blocked/Cancelled
    priority INTEGER NOT NULL DEFAULT 1, -- 0=Low, 1=Medium, 2=High, 3=Critical
    branch_name TEXT, -- Git 分支名
    base_branch TEXT DEFAULT 'main', -- 基于哪个分支创建
    workflow_def_id TEXT, -- 关联的工作流定义
    assignee TEXT, -- AI agent 或人工
    merge_conflict TEXT, -- JSON: 冲突信息
    merged_at INTEGER,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 发布计划 (合并多个 Task → 发布)
CREATE TABLE releases (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    version TEXT NOT NULL, -- e.g. v2.3.0
    branch_name TEXT, -- release 分支
    task_ids TEXT NOT NULL, -- JSON array: 包含的 Task ID 列表
    status TEXT NOT NULL, -- Planning/Integrating/Testing/Ready/Published
    workflow_def_id TEXT, -- 发布工作流
    changelog TEXT,
    published_at INTEGER,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 工作流执行
CREATE TABLE workflow_runs (
    id TEXT PRIMARY KEY,
    workflow_def_id TEXT NOT NULL,
    project_id TEXT NOT NULL,
    task_id TEXT, -- 关联的任务 (可为空)
    release_id TEXT, -- 关联的发布 (可为空)
    status TEXT NOT NULL DEFAULT 'pending', -- Pending/Running/Paused/Completed/Failed/Cancelled
    node_states TEXT, -- JSON: {node_id: {status(Pending/Running/Completed/Failed/Skipped/Waiting), output, started_at, finished_at}}
    current_layer INTEGER,
    started_at INTEGER,
    finished_at INTEGER,
    error TEXT
);

-- 产出物
CREATE TABLE artifacts (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    workflow_run_id TEXT,
    node_id TEXT,
    kind TEXT NOT NULL, -- PRD/CodeChange/TestReport/ReleaseNote/Image
    title TEXT,
    content TEXT,
    file_path TEXT,
    metadata TEXT, -- JSON
    created_at INTEGER NOT NULL
);

-- 连接配置
CREATE TABLE connections (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    kind TEXT NOT NULL, -- MySQL/SSH/MongoDB/Redis/HTTP
    config TEXT NOT NULL, -- JSON (加密存储)
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- AI 模型配置
CREATE TABLE ai_providers (
    id TEXT PRIMARY KEY,
    provider TEXT NOT NULL, -- Claude/GLM/DeepSeek/OpenAI
    api_key TEXT, -- 加密存储
    base_url TEXT,
    models TEXT, -- JSON: 可用模型列表
    is_default INTEGER DEFAULT 0,
    config TEXT -- JSON: 额外配置
);

-- 需求功能清单
CREATE TABLE features (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    task_id TEXT, -- 关联任务
    requirement_id TEXT, -- 来源需求
    title TEXT NOT NULL,
    description TEXT,
    status TEXT NOT NULL DEFAULT 'selected', -- Selected/Deferred/Rejected/Completed
    priority INTEGER NOT NULL DEFAULT 1, -- 0=Low, 1=Medium, 2=High, 3=Critical
    rejection_reason TEXT, -- 不做的原因（自动进入决策留痕）
    test_case_count INTEGER DEFAULT 0,
    order_index INTEGER NOT NULL, -- 排序
    metadata TEXT, -- JSON: 额外属性
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

-- 测试用例
CREATE TABLE test_cases (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    feature_id TEXT NOT NULL, -- 关联功能
    title TEXT NOT NULL,
    description TEXT,
    preconditions TEXT, -- 前置条件
    steps TEXT NOT NULL, -- JSON: 测试步骤 [{step, expected}]
    kind TEXT NOT NULL DEFAULT 'Manual', -- Manual/Auto/AI-Generated
    priority INTEGER NOT NULL DEFAULT 1, -- 0=Low, 1=Medium, 2=High, 3=Critical
);

-- 测试执行记录
CREATE TABLE test_runs (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    task_id TEXT, -- 关联任务
    feature_id TEXT, -- 关联功能
    test_case_id TEXT NOT NULL,
    status TEXT NOT NULL, -- Passed/Failed/Skipped/Blocked
    actual_result TEXT,
    error_detail TEXT, -- 失败详情
    executed_by TEXT, -- AI/Human
    duration_ms INTEGER,
    executed_at INTEGER NOT NULL
);

-- 标注 (贯穿所有内容)
CREATE TABLE annotations (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    entity_type TEXT NOT NULL, -- Requirement/Feature/Code/TestCase/TestReport/DesignDoc
    entity_id TEXT NOT NULL, -- 关联实体 ID
    marker TEXT NOT NULL, -- FIXME/TODO/QUESTION/RISK/DECISION/OPTIMIZE
    content TEXT NOT NULL, -- 标注内容
    location TEXT, -- 文件路径+行号 / 文档段落
    status TEXT NOT NULL DEFAULT 'Open', -- Open/AI-Processing/Resolved/WontFix
    resolved_by TEXT, -- AI/Human
    resolution TEXT, -- 处理结果
    created_at INTEGER NOT NULL,
    resolved_at INTEGER
);

-- 决策留痕
CREATE TABLE decisions (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    context TEXT NOT NULL, -- 决策背景
    question TEXT NOT NULL, -- 需要决定的问题
    alternatives TEXT, -- JSON array: 考虑过的方案
    decision TEXT NOT NULL, -- 最终决定
    reason TEXT NOT NULL, -- 决策原因
    decided_by TEXT NOT NULL, -- AI/Human
    entity_type TEXT, -- 关联实体类型
    entity_id TEXT, -- 关联实体 ID
    impact TEXT, -- 影响范围
    stage TEXT, -- Idea/Requirement/Coding/Testing/Release
    created_at INTEGER NOT NULL
);

七、阶段模板

5 个内置阶段作为工作流模板（YAML 定义），用户可自定义。

• 💡 想法：市场分析 → 竞品调研 → 可行性评分
• 📋 需求：AI 生成 PRD → 人工审阅 → 任务拆解
• 💻 编码：AI 编码 → 代码审查 → 自动修复
• 🧪 测试：运行测试 → AI 分析失败 → 回归验证
• 🚀 发布：构建 → 人工确认 → 部署 → 健康检查

八、Phase 规划

Phase 1 — 引擎骨架 (4-6 周)

• df-core + df-workflow (DAG + Node trait + Executor)
• df-storage (SQLite 基础表)
• df-execute (Shell 执行)
• 最小前端：项目列表 + 工作流执行日志
• 验证：能跑通一个 3 节点的简单工作流

Phase 2 — AI 集成 (3-4 周)

• df-ai (Multi-Provider + Router + Stream)
• AI Chat 面板
• AI Node 实现
• 验证：AI 节点能流式输出到前端

Phase 3 — 想法池 + 多项目 (3-4 周)

• df-ideas (捕捉/评估/评分/晋升)
• df-project (多项目调度/上下文)
• 前端：想法池视图 + 多项目 Tab
• 验证：想法捕捉 → AI 评估 → 立项 → 工作流执行

Phase 4 — 节点丰富 + 阶段插件 (3-4 周)

• df-nodes (Docker/Git/Human/HTTP)
• df-stages (5 阶段模板) — 已移除（2026-06-14 零引用清理）
• 条件分支 + 断点续跑
• 验证：跑通标准产研流程模板

Phase 5 — 体验打磨 (4-6 周)

• 拖拽式 DAG 编辑器
• Dashboard + Timeline
• 工作流模板市场
• 桌面通知 + 系统托盘
• 自动更新
• 发布 v1.0

九、与现有资产的关系

现有资产	关系
u-desk-rust (Tauri v2)	复用架构经验：Workspace + crate 拆分 + Vue 3 传输层
workpod (Docker)	DockerNode 的执行后端，API 集成
proxy 工具链 (Rust)	连接管理 + 执行后端，内嵌调用
Skills 体系	核心逻辑迁移为节点模板，不保留 skill 形态
product-delivery-control	演进为「标准产研工作流模板」
mission-control	合同/质量门禁机制融入 Workflow Engine
CPA (LLM 代理)	AI Provider 之一

十、关键设计决策

1. 引擎不绑定业务：Workflow Engine 只做 DAG 执行，阶段是插件
2. 想法第一公民：想法池独立于项目，持续运转
3. 多项目并行：多项目同时推进，共享资源池
4. 多任务/分支并行：同一项目内多任务各绑分支，独立工作流，完成后合并
5. 标注无处不在：FIXME/TODO/QUESTION 标注可附加在任何内容上，批量收集→AI 处理
6. 需求-测试双向追溯：功能可选做/延/不做，每个功能映射测试用例和报告
7. 决策必留痕：所有关键决策自动记录，可追溯、可审计
8. 本地优先：SQLite 嵌入，不依赖云服务
9. 多模型并行：统一抽象，按任务路由，不锁定单一模型
10. 流式优先：AI 输出、Shell 输出全部流式推送到前端