# v3.0 使用指南

## 🚀 快速开始

### 1. 启动服务器
```bash
cd /data/openclaw/workspace/agent-task-service
node server.js
```

### 2. 访问界面
浏览器打开: `http://10.0.6.5:3000/index-v3.html`

---

## 📖 功能说明

### 🏠 首页 - Dashboard 仪表盘
- **统计卡片**: 显示项目总数、任务总数、进行中任务、已完成任务
- **最近项目**: 快速访问最近活跃的项目
- **默认显示**: 打开页面即显示

### 📁 项目管理
1. **创建项目**
   - 点击侧边栏 `+ 新建项目`
   - 填写项目名称和描述
   - 提交创建

2. **查看项目**
   - 点击侧边栏项目名称
   - 自动切换到 Kanban 看板

### 📋 任务管理（Kanban 看板）

#### 查看任务
- **5列布局**: 初始 → 进行中 → 待测试 → 测试中 → 完成
- **任务卡片**: 显示标题、类型、优先级、执行者、子任务数、附件数

#### 创建任务
1. 点击 `+ 新建任务`
2. 填写信息:
   - 任务标题 ✅
   - 任务描述 (支持 Markdown) ✅
   - 类型 (需求/设计/开发/测试/部署) ✅
   - 优先级 (低/普通/高) ✅
   - **父任务** (可选，创建子任务) ✅
   - **执行者** (可选，分配智能体) ✅
3. 提交创建

#### 拖拽改变状态
- 鼠标按住任务卡片
- 拖动到目标列
- 松开鼠标即可更新状态

#### 查看任务详情
- 点击任务卡片
- 右侧弹出详情侧边栏
- 可以:
  - 修改状态/类型/优先级/执行者
  - 查看 Markdown 描述
  - 上传/下载/删除附件
  - 管理子任务
  - 添加子任务 (**新功能**)
  - 删除任务

#### 搜索和过滤
- **搜索框**: 输入关键词实时搜索
- **类型过滤**: 按需求/设计/开发/测试/部署筛选
- **优先级过滤**: 按高/普通/低筛选

### 🤖 智能体管理

#### 查看智能体
- 点击侧边栏 `🤖 智能体管理`
- 查看所有注册的智能体
- 显示: 名称、状态、当前任务、完成数、最后心跳

#### 状态筛选
- **全部**: 显示所有智能体
- **空闲**: 仅显示空闲的智能体
- **工作中**: 仅显示正在工作的智能体

### 📜 协作规约

#### 查看规约
- 点击顶部 `📜 规约` 按钮
- 弹出规约浮层

#### Tab 切换 (**新功能**)
- **全局规约**: 适用于所有项目的规则
- **项目规约**: 当前项目的特定规则
- 点击 Tab 标签即可切换

---

## 🎨 界面特色

### 视觉设计
- 🎨 **渐变主题**: 紫蓝渐变 (primary → primary-dark)
- 📊 **状态色**: 每种任务状态有独特颜色
- 🏷️ **类型徽章**: 需求/设计/开发/测试/部署一目了然
- 🚨 **优先级**: 高/普通/低清晰标识

### 交互体验
- 🖱️ **流畅拖拽**: 拖动任务改变状态
- ✨ **平滑动画**: 侧边栏滑入/滑出
- 📱 **响应式**: 适配桌面/平板/手机
- ⚡ **实时更新**: 30秒自动刷新数据
- 🔍 **搜索防抖**: 减少不必要的请求

### 用户体验
- 💬 **Toast 提示**: 操作成功/失败即时反馈
- ⏳ **加载状态**: Loading 转圈友好提示
- ❌ **错误处理**: 清晰的错误提示
- 🎯 **快捷操作**: 最少点击完成任务

---

## 📱 快捷操作

### 侧边栏导航
- 点击 `📊 仪表盘` → 查看全局统计
- 点击 `🤖 智能体管理` → 管理智能体
- 点击项目名称 → 查看项目任务看板

### Kanban 看板
- 点击任务卡片 → 查看详情
- 拖拽任务卡片 → 改变状态
- 搜索框输入 → 实时搜索
- 下拉菜单选择 → 快速过滤

### 任务详情
- 下拉选择器 → 即时更新字段
- 点击子任务 → 切换完成状态
- 点击附件 → 下载文件
- 点击 ✕ → 删除附件

---

## 🔧 高级功能

### 子任务管理
1. 打开父任务详情
2. 滚动到 `🔀 子任务` 部分
3. 点击 `+ 添加子任务`
4. 输入子任务标题
5. 提交即可创建

### 父子任务关联
- **创建时选择**: 创建任务时选择父任务
- **自动关联**: 子任务自动归属于父任务
- **层级显示**: 父任务卡片显示子任务数量
- **独立管理**: 子任务也可以独立操作

### 执行者分配
- **创建时分配**: 创建任务时选择执行者
- **详情中修改**: 任务详情中更改执行者
- **状态显示**: 智能体管理页查看当前任务
- **智能提示**: 显示智能体状态 (空闲/工作中)

---

## 💡 使用技巧

### 1. 高效创建任务
- 先创建父任务（主功能）
- 再创建子任务（具体步骤）
- 父任务标题要简洁明确
- 子任务标题要具体可执行

### 2. 合理分配优先级
- **高**: 紧急且重要，立即处理
- **普通**: 常规任务，按计划完成
- **低**: 可延后的任务

### 3. 充分利用 Markdown
- 任务描述支持 Markdown 格式
- 可以添加标题、列表、代码块
- 让任务说明更清晰易读

### 4. 定期查看 Dashboard
- 了解全局项目进展
- 发现瓶颈和延期任务
- 及时调整资源分配

---

## 🐛 常见问题

### Q: 拖拽后任务状态没有更新？
A: 检查后端服务器是否正常运行，查看浏览器控制台是否有错误提示。

### Q: 附件上传失败？
A: 检查文件大小是否超过 10MB，确认后端 API 正常。

### Q: 智能体列表为空？
A: 需要先通过 API 注册智能体，或使用测试脚本创建测试数据。

### Q: 搜索没有结果？
A: 搜索是实时的，检查拼写是否正确，尝试使用关键词而非完整句子。

---

## 🎯 最佳实践

### 项目管理
1. 为每个项目设置清晰的描述
2. 定期查看项目规约
3. 保持项目任务数量适中（建议 <50）

### 任务管理
1. 任务标题简洁明确 (≤20字)
2. 任务描述详细完整
3. 合理使用父子任务分解复杂工作
4. 及时更新任务状态
5. 重要任务上传相关附件

### 智能体协作
1. 为智能体分配明确的任务
2. 定期检查智能体状态
3. 合理分配工作量，避免过载

---

## 📞 技术支持

### 文档
- **设计文档**: `DESIGN-v3.md`
- **任务清单**: `TASKS-v3.md`
- **完成报告**: `COMPLETION-REPORT-v3.md`
- **符合性检查**: `check-design.md`

### 代码
- **主文件**: `public/index-v3.html` (2,341 行)
- **备份文件**: `public/index-v3-backup.html`

---

**版本**: v3.0  
**更新日期**: 2026-02-24  
**状态**: ✅ 生产就绪