task-board/API-V2.md

API v2 升级说明

🎉 新功能概览

1. 项目管理

• 所有任务必须隶属于项目
• 项目由人类创建和管理

2. 协作规约

• 每个项目可设置协作规约
• 智能体领取任务时会收到规约提醒
• 智能体必须严格遵守规约内容

3. 信息共享清单

• 每个项目维护共享笔记列表
• 人类和智能体都可以添加/编辑
• 支持 CRUD 操作

4. 任务增强

• Markdown 支持: 任务描述使用 Markdown 格式
• 附件管理: 支持文件上传（最大 10MB）
• 子任务: 支持父子任务关系
• 任务类型: requirement（需求）| design（设计）| development（开发）| testing（测试）| deployment（部署）
• 新状态流: initial（初始）→ in_progress（进行中）→ testing_pending（待测试）→ testing（测试中）→ completed（完成）

📡 API 端点

项目管理

创建项目

POST /api/projects
Content-Type: application/json

{
  "name": "项目名称",
  "description": "项目描述",
  "created_by": "human"
}

获取所有项目

GET /api/projects

获取项目详情

GET /api/projects/:id

更新项目

PUT /api/projects/:id
Content-Type: application/json

{
  "name": "新名称",
  "description": "新描述",
  "status": "active" | "archived"
}

协作规约

设置全局协作规约

POST /api/rules/global
Content-Type: application/json

{
  "content": "# 全局协作规约\n\n适用于所有项目...",
  "created_by": "human"
}

获取全局协作规约

GET /api/rules/global

响应:
{
  "id": "xxx",
  "content": "规约内容（Markdown）",
  "created_by": "human",
  "created_at": 1234567890,
  "updated_at": 1234567890
}

设置项目协作规约

POST /api/projects/:projectId/rules
Content-Type: application/json

{
  "content": "协作规约内容（Markdown）",
  "created_by": "human"
}

获取协作规约

GET /api/projects/:projectId/rules

信息共享清单

添加共享笔记

POST /api/projects/:projectId/notes
Content-Type: application/json

{
  "content": "笔记内容（Markdown）",
  "created_by": "human" | "agent_id"
}

获取共享笔记列表

GET /api/projects/:projectId/notes

更新共享笔记

PUT /api/projects/:projectId/notes/:noteId
Content-Type: application/json

{
  "content": "更新后的内容"
}

删除共享笔记

DELETE /api/projects/:projectId/notes/:noteId

任务管理（增强）

创建任务

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"
}

获取任务列表

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: 只获取根任务（无父任务）

获取任务详情（含子任务和附件）

GET /api/tasks/:id

响应:
{
  "id": "xxx",
  "title": "...",
  ...
  "subtasks": [ ... ],  // 子任务列表
  "attachments": [ ... ]  // 附件列表
}

领取任务（智能体会同时收到全局规约和项目规约）

POST /api/tasks/:id/claim
Content-Type: application/json

{
  "agent_id": "智能体ID"
}

响应（如果有规约）:
{
  "message": "任务领取成功",
  "collaboration_rules": {
    "global_rules": "全局协作规约内容",
    "project_rules": "项目协作规约内容"
  },
  "notice": "⚠️ 请严格遵守协作规约"
}

更新任务

PUT /api/tasks/:id
Content-Type: application/json

{
  "status": "in_progress",
  "description": "更新描述",
  "task_type": "testing",
  "priority": "high",
  "result": "任务结果"
}

附件管理

上传附件

POST /api/tasks/:taskId/attachments
Content-Type: multipart/form-data

file: [文件]
uploaded_by: "human" | "agent_id"

限制：单文件最大 10MB

获取任务附件列表

GET /api/tasks/:taskId/attachments

响应:
[
  {
    "id": "xxx",
    "filename": "...",
    "original_name": "原始文件名",
    "file_size": 12345,
    "mime_type": "image/png",
    "url": "/uploads/xxx",
    ...
  }
]

删除附件

DELETE /api/tasks/:taskId/attachments/:attachmentId

统计信息（增强）

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 客户端示例

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. 备份数据库

pg_dump agent_tasks > backup.sql

2. 运行 v2 服务（会自动创建新表）

node server-v2.js

3. 手动迁移任务
   • 创建一个默认项目
   • 将所有 v1 任务关联到该项目

🚀 部署

使用 server-v2.js 替代 server-postgres.js:

DB_HOST=localhost DB_PORT=5433 DB_PASSWORD=postgres node server-v2.js

或更新 package.json:

{
  "scripts": {
    "start": "node server-v2.js"
  }
}

⚠️ 重要变更

1. 所有任务必须属于项目 - 创建任务时 project_id 为必填
2. 任务状态变更 - 从 3 个状态扩展到 5 个状态
3. 新增任务类型 - 必须指定任务类型
4. 协作规约强制推送 - 智能体领取任务时自动获取规约