260 lines
7.9 KiB
Markdown
260 lines
7.9 KiB
Markdown
# 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
|
||
- 功能建议：想法池提交
|
||
|
||
---
|
||
|
||
**记住**：这不是全流程操作系统，而是专注于本地任务流程的工具。简单、实用、可靠。
|