From d6753ffdfb233e58de935e35bad0b546f3bd0777 Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Sun, 17 May 2026 18:34:04 +0800
Subject: [PATCH] auto-sync: 2026-05-17 18:34:04

---
 docs/design/agent-api-contract.md | 198 ++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)
 create mode 100644 docs/design/agent-api-contract.md

diff --git a/docs/design/agent-api-contract.md b/docs/design/agent-api-contract.md
new file mode 100644
index 0000000..d80d6ec
--- /dev/null
+++ b/docs/design/agent-api-contract.md
@@ -0,0 +1,198 @@
+# 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 | 初始版本。基于端到端实测发现的问题制定 |