# Agent-Backend API 契约 (v2.6)

Agent 通过 HTTP API 与黑板交互。本文档是 prompt 模板和后端路由的共同 Source of Truth。

## 通用约定

- Base URL: `http://{api_host}:{api_port}`
- Content-Type: `application/json`
- 错误响应格式（422/409）：
  ```json
  {
    "error": "error_code",
    "detail": "人类+Agent 可读的错误描述",
    "valid_values": { "field": ["allowed", "values"] },
    "hint": "修复建议"
  }
  ```

---

## 1. POST /api/projects/{project_id}/tasks/{task_id}/outputs

写入产出物。

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `agent` | string | ✅ | Agent ID（如 `zhangfei-dev`） |
| `type` | string | ✅ | 产出类型。合法值：`code`, `document`, `data`, `config`, `other` |
| `title` | string | ✅ | 产出标题（简要描述） |
| `content` | string | ⬜ | 产出内容（文本直传模式）。与 `content_path` 二选一 |
| `content_path` | string | ⬜ | 产出文件路径（路径引用模式）。与 `content` 二选一 |
| `summary` | string | ⬜ | 内容摘要 |
| `metadata` | object | ⬜ | 附加元数据 |

### 行为

- 如果传了 `content` 而没传 `content_path`：后端自动将内容写入 `artifacts/{task_id}/{title}` 并填充 `content_path`
- `type` 的别名 `content_type` 也被接受（兼容），但优先用 `type`

### 成功响应 (200)

```json
{"ok": true, "output_id": 42}
```

### 错误响应

- **422**: 字段缺失或值不合法。`valid_values` 会列出合法值
- **500**: 内部错误（不应出现，出现说明后端有 bug）

### 示例

```bash
curl -X POST http://127.0.0.1:8083/api/projects/demo/tasks/task-001/outputs \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": "zhangfei-dev",
    "type": "code",
    "title": "csv_sorter.py",
    "content": "import csv\nimport argparse\n...",
    "summary": "CSV排序小程序，支持按任意列降序/升序排序"
  }'
```

---

## 2. POST /api/projects/{project_id}/tasks/{task_id}/status

更新任务状态。

### 状态机

```
pending ──→ claimed ──→ working ──→ review ──→ done
   │           │           │           │
   │           │           │           └──→ pending（驳回重做）
   │           │           ├──→ blocked ──→ pending
   │           │           ├──→ failed ──→ pending（重试）
   │           │           └──→ cancelled
   │           ├──→ pending（超时回收）
   │           └──→ cancelled
   └──→ cancelled
```

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `status` | string | ✅ | 目标状态 |
| `agent` | string | ✅ | Agent ID |
| `detail` | string | ⬜ | 状态变更说明（失败原因、驳回理由等） |

### Agent 常用转换

| 从 | 到 | 何时 |
|----|-----|------|
| claimed | working | 开始执行任务 |
| working | review | 完成任务，提交审查 |
| working | failed | 执行失败 |

### 成功响应 (200)

```json
{"ok": true, "old_status": "working", "new_status": "review"}
```

### 错误响应

- **409**: 状态转换不合法。响应会包含合法的目标状态列表

```json
{
  "error": "invalid_transition",
  "detail": "Cannot transition from claimed to review",
  "valid_transitions": {"claimed": ["working", "pending", "cancelled"]},
  "hint": "You must go through 'working' before 'review'"
}
```

### 示例

```bash
# 开始工作
curl -X POST http://127.0.0.1:8083/api/projects/demo/tasks/task-001/status \
  -H 'Content-Type: application/json' \
  -d '{"status": "working", "agent": "zhangfei-dev"}'

# 完成，提交审查
curl -X POST http://127.0.0.1:8083/api/projects/demo/tasks/task-001/status \
  -H 'Content-Type: application/json' \
  -d '{"status": "review", "agent": "zhangfei-dev"}'

# 失败
curl -X POST http://127.0.0.1:8083/api/projects/demo/tasks/task-001/status \
  -H 'Content-Type: application/json' \
  -d '{"status": "failed", "agent": "zhangfei-dev", "detail": "无法连接数据库"}'
```

---

## 3. GET /api/projects/{project_id}/tasks/{task_id}?expand=all

获取任务完整信息（含产出、评论、事件、审查）。

### 查询参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `expand` | string | `all` 返回所有关联数据 |

### 响应字段

包含任务基本信息 + 聚合字段：

| 字段 | 说明 |
|------|------|
| `status` | 当前状态 |
| `outputs` | 产出列表 |
| `reviews` | 审查记录 |
| `events` | 事件时间线 |
| `comments` | 评论 |
| `review_status` | 审查状态（null/pending/approved/rejected/rebuttal） |

---

## 4. POST /api/projects/{project_id}/tasks/{task_id}/comments

添加评论（Agent fallback 时可用）。

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `author` | string | ✅ | 评论者 |
| `body` | string | ✅ | 评论内容 |

---

## 5. GET /api/projects/{project_id}/tasks

列出项目任务。

### 查询参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `status` | string | 按状态过滤 |
| `assignee` | string | 按负责人过滤 |

---

## 变更日志

| 日期 | 变更 |
|------|------|
| 2026-05-17 | 初始版本。基于端到端实测发现的问题制定 |