# DevFlow 使用手册

> "本地优先的个人开发流程驾驶舱"
>
> 本手册对齐真实代码（核对基准 2026-06-15）。命令、状态枚举、节点类型均以 `package.json` / `crates/df-core/src/types.rs` / `crates/df-nodes/src/` 为准。

```mermaid
graph LR
    A[想法池] -->|评估| B[项目管理]
    B -->|创建| C[任务队列]
    C -->|执行| D[工作流引擎]
    D -->|合并| E[Git仓库]
```

```mermaid
graph LR
    A[想法] -->|收集| B[任务]
    B -->|分配| C[分支]
    C -->|自动化| D[工作流]
    D -->|提交| E[代码]
```

## 🚀 快速开始

### 运行应用

```bash
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
```

### 一句话功能
你的项目流程，本地跑，AI 辅助，数据不出门

## 🎯 核心价值链

### 任务 → 分支 → 工作流 → 合并

#### 1. 任务管理
- **创建任务**：指定项目、标题、分支名
- **状态流转**：见下方「任务状态」7 态
- **优先级**：P0（紧急）到 P3（低），数字越小优先级越高

#### 2. 分支绑定
```bash
# 创建任务时自动生成分支
# 例如：feature/devflow-improve
```

#### 3. 工作流执行
- **环境检查**：依赖验证、端口检查
- **运行测试**：单元测试、集成测试
- **构建产物**：打包、优化、部署

#### 4. 实时监控
- **事件日志**：每个节点执行状态
- **错误处理**：失败重试、人工审批

## 📋 功能模块

### 🤖 AI Chat
- **多 Provider**：支持配置多个 AI 提供商（OpenAI / GLM / DeepSeek / Claude 兼容模式 / Anthropic 原生协议），可在「设置」中管理并指定默认
- **工具调用**：代码生成、分析
- **流式响应**：实时输出

### 💡 想法池
- **轻量版**：聚焦核心
- **预留对抗评估**：后续升级

### 📂 项目管理
- **多项目支持**：切换不同仓库
- **状态同步**：与 Git 分支联动

### 📚 知识库（收藏夹）
- **Tier1 AI 提炼**：从 AI 对话/工作流中自动提炼候选经验条目，附带 `reasoning`（"为何值得沉淀"）判断依据
- **向量检索**：知识条目带 `embedding` 列，支持语义检索（OpenAI 兼容 `/v1/embeddings`，Anthropic 协议不支持 embedding）
- **分类管理**：审查规则、Prompt模板、踩坑经验等 7 种 kind
- **生命线管理**：candidate → pending_review → published → archived，带 reuse_count / verified 信号

### ⚙️ 设置
- **AI 配置**：多 Provider 管理（新增/编辑/删除/设默认）、模型选择
- **通用设置**：主题、语言

## 🔧 核心功能详解

### 任务操作流程

#### 1. 创建任务
```typescript
// 在项目详情页点击 "+ 新任务"
- 填写任务标题
- 选择项目
- （可选）指定分支名
```

#### 2. 任务执行
- **自动创建分支**：`git checkout -b feature/task-name`
- **绑定任务 ID**：Git commit 自动关联
- **状态同步**：合并后任务标记为已完成

#### 3. 工作流运行
```typescript
// 点击"运行测试工作流"
1. 环境检查 → 验证依赖
2. 运行测试 → 执行单元测试
3. 构建产物 → 生成发布包
```

### AI Chat 使用

#### 基础对话
- 直接提问
- 代码审查
- 问题诊断

#### 工具调用
- **生成代码**：根据描述生成完整实现
- **文件操作**：读取、写入（write_file）、局部编辑（patch_file）、追加（append_file）、搜索（search_files）项目文件
- **项目管理**：创建/更新/删除项目、绑定目录
- **任务管理**：创建/更新/删除任务
- **Shell 执行**：在项目目录运行命令（run_command，需人工审批）
- **知识库**：自动提炼对话经验到知识库

## 💡 想法池功能

### 创建想法
```typescript
// 简单记录
- 标题：一句话描述
- 描述：详细说明（可选）
- 优先级：P1~P3
- 标签：便于分类
```

### 状态管理

想法共 6 个状态（对齐 `crates/df-core/src/types.rs` 的 `IdeaStatus` 枚举）：

| 状态值 | 含义 | 说明 |
|--------|------|------|
| `draft` | 草稿 | 初始创建 |
| `pending_review` | 待评估 | 已提交，等待 AI/人工评估 |
| `approved` | 已批准 | 评估通过，可晋升为项目 |
| `rejected` | 已拒绝 | 评估未通过 |
| `promoted` | 已晋升 | 已转为项目（`promoted_to` 写入目标 project_id）|
| `archived` | 已归档 | 历史归档 |

典型流转：`draft → pending_review → approved → promoted`（正向）/ `→ rejected → archived`（淘汰）。

### 未来升级
- **对抗式评估**：正方+反方+分析师
- **智能推荐**：相关想法关联

## 🌟 特色功能

### 本地优先
- **数据存储**：SQLite 本地数据库
- **无需网络**：基础功能离线可用
- **隐私保护**：代码不出本地

### 实时监控
- **事件流**：基于 Tauri 的 EventBus（进程内 `tokio::sync::broadcast` 发布/订阅，前端经 `@tauri-apps/api/event` 的 emit/listen 接收），非 WebSocket
- **进度显示**：工作流执行进度
- **错误提示**：失败原因分析

### 工作流节点

实际内置 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 节点。条件分支由工作流引擎层处理。

## 📊 使用统计

### 个人效能
- **任务完成率**：按时完成任务比例
- **分支管理**：活跃分支数量

### 项目进度
- **阶段分布**：规划/开发/测试/上线
- **任务积压**：待处理任务数量
- **开发速度**：每周完成任务数

## 🎨 界面说明

### 颜色系统
- **主色**：紫色（#6B46C1）
- **成功色**：绿色（#10B981）
- **警告色**：黄色（#F59E0B）
- **错误色**：红色（#EF4444）

### 任务状态图标含义
任务共 7 个状态（对齐 `crates/df-core/src/types.rs` 的 `TaskStatus` 枚举）：

| 状态值 | 含义 | 图标建议 |
|--------|------|----------|
| `todo` | 待开始 | 📋 |
| `in_progress` | 进行中 | 🔨 |
| `in_review` | 代码审查中 | 👀 |
| `testing` | 测试中 | 🧪 |
| `done` | 已完成 | ✅ |
| `blocked` | 已阻塞 | 🚫 |
| `cancelled` | 已取消 | 🗑️ |

> 分支状态另设 3 态：`active` / `merged` / `abandoned`（见 `BranchStatus` 枚举，与任务状态独立）。

## ⚠️ 注意事项

### Git 集成
- 必须初始化 Git 仓库
- 配置用户邮箱和姓名
- 保持分支命名规范

### AI 配置
- 需要有效的 API Key（在「设置」中添加 Provider 时录入，前端做 mask 处理防泄露）
- 检查网络连接
- 关注 Token 使用量（对话记录会累计 prompt/completion tokens 落库）

### 工作流设计
- 避免长时间阻塞操作
- 设置合理的超时时间（Script 节点可用 `timeout_secs`）
- 保留人工干预接口（Human 节点）

## 🔄 更新日志

### v1.0 (2026-06-11)
- ✅ 完成核心功能
- ✅ 任务管理系统
- ✅ 工作流引擎
- ✅ AI Chat 集成
- ✅ 本地数据存储

### 计划功能
- 🔄 想法对抗式评估
- 🔄 更多工作流节点
- 🔄 团队协作功能
- 🔄 数据导出功能

## 📞 支持

- 问题反馈：创建 Issue
- 功能建议：想法池提交

---

**记住**：这不是全流程操作系统，而是专注于本地任务流程的工具。简单、实用、可靠。