要做什么

「AI Agent Task Board」是一个教学向的 MVP 项目——一个极简的任务管理看板，支持创建、查看、修改状态、删除任务。技术栈是 FastAPI + SQLite + 原生 HTML/CSS/JS，零构建工具。

但这个项目真正的目的不是做一个看板，而是演练多 Agent 协作的工作流：PM Agent 出需求与开发、DEV Agent 写代码、QA Agent 验证，每个阶段之间由人类确认门控，文档作为 Agent 间的通信媒介。

整体流程：三角色四阶段

整个项目按以下分工推进：

PM Agent → DEV Agent → QA Agent → 人类验收
（文档产出） （代码实现） （测试验证） （阶段门控）

PM Agent 产出四份文档：PRD（用户故事 + 验收标准）、data_model（字段定义 + 状态流转规则）、api_contract（5 个端点的完整请求/响应 Schema + 错误码）、dev_plan（阶段划分 + 门禁规则）。这四份文档就是后续所有 Agent 的"合同"，Agent 只读文档路径，不传全文。

DEV Agent 按文档实现后端 5 个 API 端点（POST/GET /tasks、GET/PUT/DELETE /tasks/{id}）和前端页面。

QA Agent 负责真实验证——不是看代码说"应该能跑"，而是实际启动服务、发 curl 请求、比对返回结果与契约是否一致。

每个阶段结束后硬暂停，人类确认后才进入下一阶段。这条规则直接写进了 dev_plan.md。

关键环节与踩的坑

1. 第一次 DEV 因任务过大而失败

第一轮 DEV Agent 被要求"读取 4 份文档 + 创建项目结构 + 实现后端 + 实现前端 + 写依赖文件 + 启动验证"，单次任务太重，输出 token 耗尽，代码没写完就截断了。

教训：子 Agent 任务必须拆小。 第二轮把范围缩到"只做后端 5 个端点 + 真实验证"，单文件 backend/main.py 搞定，23 个验证用例全部通过。

2. Windows 下 curl 中文编码陷阱

验证 POST /tasks 时，含中文的请求体经 git-bash 内联 curl 传输后被损坏，FastAPI 解析失败返回 422。最初误以为是代码问题，排查后发现是 shell 编码问题。

解决：改用 UTF-8 文件传请求体：

1
2
3
4
5

# 写请求体到文件，用 --data-binary 避免 shell 编码干扰
echo '{"title":"测试任务","description":"描述"}' > /tmp/request_body.json
curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/request_body.json

3. Swagger 缺失 Request Body 的根因定位

QA 阶段发现 POST /tasks 在 Swagger UI 中没有 Request Body 输入区，Try-it-out 发出空 body 返回 422。

根因很典型：路由函数签名只声明了裸 Request 对象，没有 Pydantic 模型参数。 FastAPI 只在路由参数里声明了 Pydantic 模型或 Body() 时才会生成 OpenAPI requestBody。

1
2
3
4

# 问题代码（main.py 第 113-114 行）
@app.post("/tasks")
async def create_task(request: Request):  # ← 裸 Request，Swagger 不知道请求体结构
    data = await request.json()           # ← 手动解析

api_contract.md 明确要求接收 CreateTaskRequest（含 title/description 字段），但代码里既没有定义这个 Pydantic 模型，也没有在签名中声明。行为层没问题（手动解析能拿到正确数据），文档层却完全断链。

修复方向：定义 CreateTaskRequest 模型，将签名为 payload: CreateTaskRequest，Swagger 即可自动生成请求体区域。

4. 子 Agent 自述不可信，必须独立验证

第一轮 DEV Agent 汇报"全部 12 项测试通过"，但那是它自己跑的测试。实际接手后发现项目路径不对（D:/multi-agent-project 而非 D:/ai-agent-task-board），且代码结构过度工程化。

规则：子 Agent 的总结只是参考，主 Agent 必须独立验证文件是否存在、服务是否可启动、HTTP 请求是否真实返回正确结果。

最终产出

后端单文件 backend/main.py 实现 5 个端点，23 个验证用例全部通过（含完整 CRUD 流程、非法状态流转拦截、边界条件）。关键验证结果：

  • 创建(201) → 列表(200, 倒序) → 单个(200) → 改状态(200) → 删除(204) → 再查(404) ✅
  • done→todo、done→in_progress、in_progress→todo 非法流转均返回 409 ✅
  • 空白标题/不存在的 id/重复删除等边界全部按契约返回对应错误码 ✅

收获

最有价值的不是那个能跑的后端，而是多角色接力 + 文档即合同 + 阶段门控这套工作法的实际验证。三个核心原则：

  1. 任务拆小：子 Agent 单次任务不超过一个可独立验证的单元，否则输出预算耗尽前做不完
  2. 文档即通信：Agent 之间只传文档路径，不传全文；文档就是合同，代码必须严格对齐
  3. 独立验证：子 Agent 的自述不可信，主 Agent 必须亲自启动服务、发真实请求、比对结果

这套流程在后续类似项目中可以直接复用。