sanguo_moziplus_v2/docs/design/archive-2.0/agent-api-contract.md

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）：

  {
    "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)

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

错误响应

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

示例

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)

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

错误响应

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

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

示例

# 开始工作
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	初始版本。基于端到端实测发现的问题制定