文档 — DaiFlow

1 快速开始

环境要求

依赖	最低版本	说明
`Python`	3.11+	后端运行时
`Node.js`	18+	前端构建
`Git`	任意	仓库管理

安装步骤

bash

# 1. 克隆仓库
git clone https://github.com/CodyCodeAgent/daiflow
cd daiflow

# 2. 创建并激活 Python 虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. 安装 Python 依赖
pip install -r requirements.txt
pip install -e .

# 4. 构建前端
cd frontend && npm install && npm run build && cd ..

# 5. 启动（自动打开浏览器）
daiflow start

💡 桌面端： 如果你希望使用桌面 App，安装 Electron 依赖后运行 cd electron && npm install && npm run dev。

开发模式

开发时推荐分别启动前后端以获得热重载体验：

bash

# 终端 1：后端（热重载）
uvicorn daiflow.main:app --reload --port 8000

# 终端 2：前端（HMR，代理到 :8000）
cd frontend && npm run dev

首次配置

1

进入 Settings 页面

配置 AI 模型、Base URL 和 API Key。支持 Cody SDK、Claude Code 或 Cursor Runner。

2

创建项目

添加项目名称和描述，关联一个或多个本地 Git 仓库（可指定前端/后端/自定义类型）。

3

等待知识库生成

系统对每个仓库并发生成四层项目知识（结构、业务流、模块、索引），完成后进入 READY 状态。

4

创建任务，进入 DevFlow

填写任务描述（可附 PRD 文档链接、图片），选择 Runner，然后进入五阶段工作流。

2 配置指南

Runner 配置

DaiFlow 支持三种 AI 执行后端，通过 Settings → Runner Configs 进行管理，支持三级解析策略：

优先级	作用范围	说明
1（最高）	任务级	创建任务时手动指定 Runner
2	项目级	项目设置中的默认 Runner
3（最低）	全局	Settings 中配置的全局默认

📌 推荐使用 Cody SDK 作为默认 Runner（进程内执行，延迟最低）。安装方式：pip install cody-ai

环境变量

变量名	默认值	说明
`DAIFLOW_HOME`	`~/.daiflow/`	数据目录，存储 DB、Session 日志、项目知识
`DAIFLOW_LOG_RETENTION_DAYS`	`30`	Session 日志清理阈值（天）
`DAIFLOW_CORS_ORIGINS`	localhost:3000/8000	允许的 CORS 来源（逗号分隔）

MCP 服务器

DaiFlow 支持 Model Context Protocol (MCP) 服务器集成。在 MCP 管理 页面添加服务器后，AI 执行时可自动调用 MCP 工具扩展能力。

示例配置

{
  "name": "my-mcp-server",
  "command": "node",
  "args": ["/path/to/server.js"],
  "env": { "API_KEY": "..." },
  "enabled": true
}

3 五阶段 DevFlow

DaiFlow 的核心是五阶段工作流，每个阶段都有对应的任务状态，通过状态机严格管控流转，防止跳跃和逆序操作。

🚀 阶段 01 — 任务初始化

系统自动执行以下操作（可重试）：

将项目仓库复制到任务工作目录（~/.daiflow/tasks/{task_id}/）
检出指定分支，建立独立工作空间
同步技能库（Skill 文件），供 AI 读取项目规范
复制项目知识索引（project.md + constitution.md）

初始化完成后需用户手动确认，进入方案阶段。

📐 阶段 02 — 技术方案

AI 基于任务描述、PRD 文档与项目知识生成结构化技术方案：

支持附上 PRD 图片和文档链接作为输入
方案以 Markdown 格式呈现，支持多轮对话细化
方案持久化到 plan.md，用户确认后锁定
锁定自动触发 AI 任务拆解（Todo 生成）

📋 阶段 03 — 任务拆解

AI 复用方案阶段的 Session（保持上下文），将技术方案拆解为有序 Todo 列表：

每个 Todo 包含：标题、详细描述、预期输出
待办列表持久化到 todo.json
支持与 AI 对话调整 Todo 列表
用户确认后进入编码阶段

💻 阶段 04 — 编码实现

每个 Todo 使用独立 AI Session 执行：

顺序执行，前一个 Todo 完成后才能执行下一个
实时 Diff 展示，可查看每一步的代码变更
支持跳过（Skip）和批量执行（Run All）
失败后可重试，状态机保障一致性

⚠️ 编码阶段的 AI 修改直接作用于任务工作目录，请在审查阶段仔细检查 Diff 后再提交。

🔍 阶段 05 — 代码审查

汇总所有 Todo 产生的 Diff，进行最终审查：

展示全量代码变更（多仓库支持）
AI 自动生成 Commit Message，支持对话调整
一键提交并推送 MR 到 Git 远程仓库
支持与 AI 对话进行代码审查讨论

4 架构说明

DaiFlow 采用分层架构，前端通过 HTTP REST + WebSocket 与 FastAPI 后端通信，AI 执行通过可插拔 Runner 完成。

架构图

┌─────────────────────────────────────────┐
│  Electron Shell（桌面端，可选）           │
│  进程托管 / venv 管理 / 动态端口分配       │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────┴──────────────────────┐
│  React SPA（Vite 6 + TypeScript）        │
│  WebSocket 订阅频道 / REST API 调用       │
└──────────────────┬──────────────────────┘
                   │ HTTP REST + WebSocket
┌──────────────────┴──────────────────────┐
│  FastAPI（async Python 3.11+）           │
│  Routers → Services → Workflow          │
├────────────────┬────────────────────────┤
│  Runner 后端   │  SQLite (ORM + Alembic) │
│  Cody / Claude │  JSONL Session 日志     │
│  Code / Cursor │  ~/.daiflow/ 本地存储   │
└────────────────┴────────────────────────┘

Session 架构

所有 AI 交互共享统一执行模式：

SessionRunner：执行 Runner → 写日志到 .jsonl → 更新 DB 状态 → 通过 WSManager 广播
三个数据接口覆盖所有场景：DB 状态快照 / JSONL 日志回放 / WebSocket 实时推送
WebSocket 协议：单连接多路复用，客户端订阅频道（session:{session_id}）接收事件

状态机

任务和 Todo 状态通过 transitions 库（AsyncMachine）管控，禁止直接修改状态字段：

状态	说明
`CREATED`	任务已创建，等待初始化
`INITIALIZING`	正在拉取代码、同步技能库
`PLANNING`	AI 生成技术方案中
`PLAN_LOCKED`	方案已锁定，正在拆解 Todo
`TODO_READY`	Todo 就绪，等待用户确认开始编码
`CODING`	逐条执行 Todo 编码中
`REVIEWING`	代码审查阶段
`DONE`	任务完成，MR 已提交

5 API 概览

后端服务运行在 http://localhost:8000，提供以下 REST API：

分类	端点
设置	`GET/PUT /api/settings`，`GET /api/settings/check`
项目	`CRUD /api/projects`，`POST .../init`，`GET .../knowledge`
任务	`CRUD /api/tasks`，`POST .../lock-plan`，`POST .../start-coding`
DevFlow	`POST /api/tasks/{id}/plan`，`POST .../todo`，`POST /api/todos/{id}/execute`
Session	`GET /api/sessions/{id}/status`，`GET .../logs`
WebSocket	`WS /api/ws`（subscribe / chat / ping）
审查	`GET /api/tasks/{id}/diff`，`POST .../submit-mr`
技能	`CRUD /api/skills`，`POST .../link`
对话	`CRUD /api/conversations`，`POST .../init`

📖 完整 API 文档请访问 http://localhost:8000/docs（服务启动后自动生成 Swagger UI）。

DaiFlow 文档