cfdaily
199 lines
5.2 KiB
Markdown
199 lines
5.2 KiB
Markdown
# 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 | 初始版本。基于端到端实测发现的问题制定 |
|