V2.0 重大升级：项目管理、协作规约、子任务、附件支持
新功能： 1. 项目管理 - 所有任务隶属于项目 2. 协作规约 - 每个项目可设置规约，智能体自动接收 3. 信息共享清单 - 项目级别的共享笔记 4. 任务增强： - Markdown 格式描述 - 附件上传支持（最大10MB） - 子任务/父任务关系 - 任务类型（需求/设计/开发/测试/部署） - 新状态流（初始/进行中/待测试/测试中/完成） 技术变更： - 新增 multer 依赖（文件上传） - 新增 4 张数据库表 - 完整的 API v2 文档 注意：需要新数据库或迁移旧数据
This commit is contained in:
work-1
@@ -0,0 +1,394 @@
|
||||
# API v2 升级说明
|
||||
|
||||
## 🎉 新功能概览
|
||||
|
||||
### 1. 项目管理
|
||||
- 所有任务必须隶属于项目
|
||||
- 项目由人类创建和管理
|
||||
|
||||
### 2. 协作规约
|
||||
- 每个项目可设置协作规约
|
||||
- 智能体领取任务时会收到规约提醒
|
||||
- 智能体必须严格遵守规约内容
|
||||
|
||||
### 3. 信息共享清单
|
||||
- 每个项目维护共享笔记列表
|
||||
- 人类和智能体都可以添加/编辑
|
||||
- 支持 CRUD 操作
|
||||
|
||||
### 4. 任务增强
|
||||
- **Markdown 支持**: 任务描述使用 Markdown 格式
|
||||
- **附件管理**: 支持文件上传（最大 10MB）
|
||||
- **子任务**: 支持父子任务关系
|
||||
- **任务类型**: requirement（需求）| design（设计）| development（开发）| testing（测试）| deployment（部署）
|
||||
- **新状态流**: initial（初始）→ in_progress（进行中）→ testing_pending（待测试）→ testing（测试中）→ completed（完成）
|
||||
|
||||
## 📡 API 端点
|
||||
|
||||
### 项目管理
|
||||
|
||||
#### 创建项目
|
||||
```http
|
||||
POST /api/projects
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "项目名称",
|
||||
"description": "项目描述",
|
||||
"created_by": "human"
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取所有项目
|
||||
```http
|
||||
GET /api/projects
|
||||
```
|
||||
|
||||
#### 获取项目详情
|
||||
```http
|
||||
GET /api/projects/:id
|
||||
```
|
||||
|
||||
#### 更新项目
|
||||
```http
|
||||
PUT /api/projects/:id
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "新名称",
|
||||
"description": "新描述",
|
||||
"status": "active" | "archived"
|
||||
}
|
||||
```
|
||||
|
||||
### 协作规约
|
||||
|
||||
#### 设置项目协作规约
|
||||
```http
|
||||
POST /api/projects/:projectId/rules
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"content": "协作规约内容（Markdown）",
|
||||
"created_by": "human"
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取协作规约
|
||||
```http
|
||||
GET /api/projects/:projectId/rules
|
||||
```
|
||||
|
||||
### 信息共享清单
|
||||
|
||||
#### 添加共享笔记
|
||||
```http
|
||||
POST /api/projects/:projectId/notes
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"content": "笔记内容（Markdown）",
|
||||
"created_by": "human" | "agent_id"
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取共享笔记列表
|
||||
```http
|
||||
GET /api/projects/:projectId/notes
|
||||
```
|
||||
|
||||
#### 更新共享笔记
|
||||
```http
|
||||
PUT /api/projects/:projectId/notes/:noteId
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"content": "更新后的内容"
|
||||
}
|
||||
```
|
||||
|
||||
#### 删除共享笔记
|
||||
```http
|
||||
DELETE /api/projects/:projectId/notes/:noteId
|
||||
```
|
||||
|
||||
### 任务管理（增强）
|
||||
|
||||
#### 创建任务
|
||||
```http
|
||||
POST /api/tasks
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"project_id": "项目ID", // 必填
|
||||
"parent_task_id": "父任务ID", // 可选，创建子任务时使用
|
||||
"title": "任务标题",
|
||||
"description": "# 任务描述\n\n使用 **Markdown** 格式",
|
||||
"task_type": "development", // requirement | design | development | testing | deployment
|
||||
"priority": "normal", // low | normal | high
|
||||
"created_by": "human"
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取任务列表
|
||||
```http
|
||||
GET /api/tasks?project_id=xxx&status=initial&root=true
|
||||
|
||||
参数：
|
||||
- project_id: 按项目过滤
|
||||
- status: initial | in_progress | testing_pending | testing | completed
|
||||
- parent_task_id: 获取某任务的子任务
|
||||
- root=true: 只获取根任务（无父任务）
|
||||
```
|
||||
|
||||
#### 获取任务详情（含子任务和附件）
|
||||
```http
|
||||
GET /api/tasks/:id
|
||||
|
||||
响应:
|
||||
{
|
||||
"id": "xxx",
|
||||
"title": "...",
|
||||
...
|
||||
"subtasks": [ ... ], // 子任务列表
|
||||
"attachments": [ ... ] // 附件列表
|
||||
}
|
||||
```
|
||||
|
||||
#### 领取任务（智能体会收到协作规约）
|
||||
```http
|
||||
POST /api/tasks/:id/claim
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "智能体ID"
|
||||
}
|
||||
|
||||
响应（如果项目有协作规约）:
|
||||
{
|
||||
"message": "任务领取成功",
|
||||
"collaboration_rules": "项目协作规约内容",
|
||||
"notice": "⚠️ 请严格遵守项目协作规约"
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新任务
|
||||
```http
|
||||
PUT /api/tasks/:id
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "in_progress",
|
||||
"description": "更新描述",
|
||||
"task_type": "testing",
|
||||
"priority": "high",
|
||||
"result": "任务结果"
|
||||
}
|
||||
```
|
||||
|
||||
### 附件管理
|
||||
|
||||
#### 上传附件
|
||||
```http
|
||||
POST /api/tasks/:taskId/attachments
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: [文件]
|
||||
uploaded_by: "human" | "agent_id"
|
||||
|
||||
限制：单文件最大 10MB
|
||||
```
|
||||
|
||||
#### 获取任务附件列表
|
||||
```http
|
||||
GET /api/tasks/:taskId/attachments
|
||||
|
||||
响应:
|
||||
[
|
||||
{
|
||||
"id": "xxx",
|
||||
"filename": "...",
|
||||
"original_name": "原始文件名",
|
||||
"file_size": 12345,
|
||||
"mime_type": "image/png",
|
||||
"url": "/uploads/xxx",
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 删除附件
|
||||
```http
|
||||
DELETE /api/tasks/:taskId/attachments/:attachmentId
|
||||
```
|
||||
|
||||
### 统计信息（增强）
|
||||
|
||||
```http
|
||||
GET /api/stats
|
||||
|
||||
响应:
|
||||
{
|
||||
"total_agents": 5,
|
||||
"active_agents": 2,
|
||||
"total_projects": 3,
|
||||
"total_tasks": 20,
|
||||
"tasks_by_status": {
|
||||
"initial": 5,
|
||||
"in_progress": 3,
|
||||
"testing_pending": 2,
|
||||
"testing": 1,
|
||||
"completed": 9
|
||||
},
|
||||
"tasks_by_type": {
|
||||
"requirement": 4,
|
||||
"design": 3,
|
||||
"development": 8,
|
||||
"testing": 3,
|
||||
"deployment": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🗄️ 数据库变更
|
||||
|
||||
### 新增表
|
||||
|
||||
1. **projects** - 项目表
|
||||
- id, name, description, created_by, created_at, updated_at, status
|
||||
|
||||
2. **collaboration_rules** - 协作规约表
|
||||
- id, project_id, content, created_by, created_at, updated_at
|
||||
|
||||
3. **project_notes** - 项目共享笔记表
|
||||
- id, project_id, content, created_by, created_at, updated_at
|
||||
|
||||
4. **attachments** - 附件表
|
||||
- id, task_id, filename, original_name, file_path, file_size, mime_type, uploaded_by, uploaded_at
|
||||
|
||||
### 修改表
|
||||
|
||||
**tasks** 表新增字段：
|
||||
- `project_id` - 所属项目（外键，必填）
|
||||
- `parent_task_id` - 父任务ID（外键，可选）
|
||||
- `task_type` - 任务类型（requirement/design/development/testing/deployment）
|
||||
- 状态值更新为：initial | in_progress | testing_pending | testing | completed
|
||||
|
||||
## 🔧 使用示例
|
||||
|
||||
### Python 客户端示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
API_BASE = "http://localhost:3000/api"
|
||||
|
||||
# 1. 创建项目
|
||||
project = requests.post(f"{API_BASE}/projects", json={
|
||||
"name": "智能客服系统",
|
||||
"description": "基于 AI 的客服系统开发项目"
|
||||
}).json()
|
||||
|
||||
project_id = project['id']
|
||||
|
||||
# 2. 设置协作规约
|
||||
requests.post(f"{API_BASE}/projects/{project_id}/rules", json={
|
||||
"content": """
|
||||
# 协作规约
|
||||
|
||||
1. **代码规范**: 严格遵循 PEP 8
|
||||
2. **提交规范**: 每次提交必须包含测试
|
||||
3. **沟通规范**: 遇到问题及时在共享清单记录
|
||||
4. **测试要求**: 覆盖率不低于 80%
|
||||
"""
|
||||
})
|
||||
|
||||
# 3. 创建任务
|
||||
task = requests.post(f"{API_BASE}/tasks", json={
|
||||
"project_id": project_id,
|
||||
"title": "设计数据库架构",
|
||||
"description": "## 需求\n\n设计用户、会话、消息三张表",
|
||||
"task_type": "design",
|
||||
"priority": "high"
|
||||
}).json()
|
||||
|
||||
task_id = task['id']
|
||||
|
||||
# 4. 智能体注册并领取任务
|
||||
agent = requests.post(f"{API_BASE}/agents/register", json={
|
||||
"name": "数据库设计专家",
|
||||
"type": "design",
|
||||
"capabilities": ["database_design", "sql"]
|
||||
}).json()
|
||||
|
||||
response = requests.post(f"{API_BASE}/tasks/{task_id}/claim", json={
|
||||
"agent_id": agent['id']
|
||||
}).json()
|
||||
|
||||
# 智能体会收到协作规约
|
||||
if 'collaboration_rules' in response:
|
||||
print("收到协作规约:")
|
||||
print(response['collaboration_rules'])
|
||||
|
||||
# 5. 添加共享笔记
|
||||
requests.post(f"{API_BASE}/projects/{project_id}/notes", json={
|
||||
"content": "数据库已选择 PostgreSQL 15",
|
||||
"created_by": agent['id']
|
||||
})
|
||||
|
||||
# 6. 上传附件（设计图）
|
||||
with open('database_schema.png', 'rb') as f:
|
||||
requests.post(
|
||||
f"{API_BASE}/tasks/{task_id}/attachments",
|
||||
files={'file': f},
|
||||
data={'uploaded_by': agent['id']}
|
||||
)
|
||||
|
||||
# 7. 完成任务
|
||||
requests.put(f"{API_BASE}/tasks/{task_id}", json={
|
||||
"status": "completed",
|
||||
"result": "数据库架构设计完成，详见附件"
|
||||
})
|
||||
```
|
||||
|
||||
## 📝 迁移指南
|
||||
|
||||
如果你有使用 v1 版本的数据，需要：
|
||||
|
||||
1. **备份数据库**
|
||||
```bash
|
||||
pg_dump agent_tasks > backup.sql
|
||||
```
|
||||
|
||||
2. **运行 v2 服务**（会自动创建新表）
|
||||
```bash
|
||||
node server-v2.js
|
||||
```
|
||||
|
||||
3. **手动迁移任务**
|
||||
- 创建一个默认项目
|
||||
- 将所有 v1 任务关联到该项目
|
||||
|
||||
## 🚀 部署
|
||||
|
||||
使用 `server-v2.js` 替代 `server-postgres.js`:
|
||||
|
||||
```bash
|
||||
DB_HOST=localhost DB_PORT=5433 DB_PASSWORD=postgres node server-v2.js
|
||||
```
|
||||
|
||||
或更新 `package.json`:
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"start": "node server-v2.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ⚠️ 重要变更
|
||||
|
||||
1. **所有任务必须属于项目** - 创建任务时 `project_id` 为必填
|
||||
2. **任务状态变更** - 从 3 个状态扩展到 5 个状态
|
||||
3. **新增任务类型** - 必须指定任务类型
|
||||
4. **协作规约强制推送** - 智能体领取任务时自动获取规约
|
||||
Reference in New Issue
Block a user