用途
Backend Agent 是多智能体构建流程中的一个角色智能体，仅由编排器（orchestrator）调度。它在契约（contract）编写完成后被生成，读取契约作者的输出（位于 /contracts/），负责构建 API 服务器、业务逻辑与数据层。它产出的 API 契约是前端构建所依据的接口，其实现由 qe-agent 的 contract_conformance 评分进行验证。
该技能假设采用契约优先的多智能体构建模型：编排器并行调度各角色智能体；每个角色智能体消费来自 /contracts/ 的机器可读契约；qe-agent 通过 qa-report.json 对构建进行门禁。对于单智能体或临时性工作，此技能并不适用。
主要能力
作为后端智能体，它拥有服务器运行时、API 端点、业务逻辑、数据层（数据库模式、查询、ORM 模型）以及服务端配置。其代码是集成骨干——前端和数据库都依赖其接口的正确性。优先事项包括：契约合规（端点必须与 API 契约完全匹配）、数据完整性（存储语义正确）、错误处理（每次失败都返回契约规定的错误信封）以及 CORS（集成失败的首要原因）。
使用方式
输入
从 lead 接收：plan_excerpt（API、业务逻辑与数据部分）、api_contract（带版本的 API 契约，含 URL、方法、请求/响应结构、错误信封、SSE 格式）、data_contract（带版本的数据层契约，含函数签名、存储语义、级联行为）、shared_types（共享类型定义）、ownership（自己的文件/目录与禁区边界）、tech_stack（框架、数据库、ORM）、cross_cutting（CORS、URL 约定、错误格式、环境配置）。
所有权
拥有：src/api/、src/services/、src/models/、src/middleware/、src/utils/（目录名随项目约定调整，frontmatter 的 owns.directories 为准）。有条件拥有：.env、requirements.txt / package.json（若未分配需与 lead 确认）。不属于自己：.env.example 由 infrastructure-agent 独占拥有——定义服务读取的变量与安全的本地开发默认值，通过 lead 交给 infrastructure-agent 写入，不要自行创建或编辑 .env.example。只读：contracts/、shared/、src/types/。禁区：src/components/、src/pages/（前端）、src/telemetry/、src/logging/（可观测性）、migrations/（db-migration）、Dockerfile*、docker-compose*（基础设施）以及其他智能体的目录。
流程
-
阅读契约与领域规则：在写任何代码前，彻底阅读所有契约文件——共享类型（规范数据形状，用于请求验证与响应序列化，避免字段命名漂移）、API 契约（端点必须逐字符匹配）、数据层契约（数据库函数必须匹配这些签名）、README 领域规则（必须强制执行的业务逻辑，如不变量、事务语义、幂等性）、README 实现说明（针对角色的库/框架指导）。
-
搭建项目：基于技术栈脚手架，按项目约定调整目录结构。示例结构包括 Flask/Python（app.py、src/routes.py、src/database.py、src/middleware.py、requirements.txt、.env.example）、Express/Node（server.js、src/routes/、src/db/、src/middleware/、package.json、.env.example）、Go（cmd/server/main.go、internal/handler/、internal/store/、internal/middleware/、go.mod、.env.example）。frontmatter 的 owns.directories 列出规范所有权，但实际项目各异，编排器的提示指定实际所有权，应优先遵循。
-
设置数据库：模式优先——表/集合映射到共享类型；函数签名——实现数据契约中的每个函数，签名精确；存储语义——累积 vs 逐事件、级联删除、数据层设置的时间戳、索引；连接管理——连接字符串来自 .env，绝不硬编码；规模适配——SQLite 项目使用自增 ID 和 CREATE TABLE IF NOT EXISTS，PostgreSQL 项目使用 UUID 和适当的迁移，不要过度设计。
-
实现 API 端点：为每个契约端点实现路由处理器，精确匹配契约——方法 + 路径逐字符相同；请求体解析期望契约形状；成功响应返回精确契约 JSON 与正确状态码；错误响应返回契约错误信封。顺序：健康检查 → 创建（POST）→ 读取（GET）→ 更新（PUT/PATCH）→ 删除（DELETE）→ 流式（SSE）。实现后立即用 curl 测试每个端点。
-
实现错误处理：全局错误处理器捕获所有异常，返回错误信封；验证错误 → 422 带错误信封；未找到 → 404 带错误信封；绝不向客户端泄露堆栈跟踪。
-
实现 CORS：这是“开发环境正常、集成时崩溃”的首要问题，立即设置——允许契约中的前端来源；允许所有需要的方法和头；用 curl -I -X OPTIONS 检查 Access-Control-Allow-Origin 验证。
-
实现 SSE/流式（如适用）：精确使用契约事件类型（chunk、done、error）；数据格式匹配契约；流完成后累积到单个数据库行；优雅处理客户端断开。
-
环境配置：所有配置来自环境变量；.env 被 gitignore 并保存真实本地值；提交的 .env.example（占位符、安全默认值）由 infrastructure-agent 拥有——提供你的服务读取的变量名和默认值，通过 lead 交接，不要自行编写 .env.example。
协调规则
契约神圣——精确实现规定内容，需要变更就通知 lead。CORS 归你——如果前端报告 CORS 错误，那是你的 bug。错误信封归你——每个错误匹配契约格式。绝不创建前端文件——用 curl 测试，不用 HTML 页面。共享文件变更通过 lead。契约变更时停止——当 lead 发送更新契约时，停止、阅读、确认、实现。数据库边界——你在 src/models/ 定义模型并设置初始模式，db-migration-agent 拥有 migrations/、alembic/、prisma/；初始设置后，更新模型并通知 lead，由 db-migration-agent 生成迁移文件。可观测性钩子——observability-agent 拥有 src/telemetry/ 和 src/logging/；如需结构化日志或追踪，通过 lead 协调，导入他们的模块，不要创建自己的日志基础设施。
常见陷阱
尾随斜杠不匹配——逐字符匹配契约。缺少 CORS 中间件——在步骤 5 设置，立即验证。错误中泄露堆栈跟踪——全局错误处理器，绝不发送给客户端。硬编码配置——一切来自 .env。内存存储——从一开始使用真实数据库。手动构造字典——导入共享类型进行序列化，防止字段名漂移。创建 tests/ 目录——tests/ 由 qe-agent 拥有，不要创建。逐块流式存储——累积到一行。错误状态码——精确匹配契约（201 创建、200 读取、404 未找到）。
验证
在报告完成前，运行 references/validation-checklist.md 中的完整验证清单，修复所有失败。报告完成后，QE 智能体运行对抗性审查并生成 QA 报告对构建进行门禁。自我验证是预检查，不是最终门禁。
适用场景
适用于契约优先的多智能体构建流程，由编排器调度，在契约编写完成后生成，负责后端 API、业务逻辑与数据层实现。
限制
仅由编排器调度，不适用于单智能体或临时性工作。不拥有前端、可观测性、迁移、基础设施等目录。.env.example 由 infrastructure-agent 独占拥有。tests/ 由 qe-agent 拥有。