Backend Development

Outcome and Entry

把已确认目标落到正确的后端 owner，保持 contract、状态和调用边界。先读 api/AGENTS.md；改 crate 前读 crates/AGENTS.md，再读改动目录的局部规则。复用用户已确认的目标、授权与 AC，不重复审批。

行为验证使用 test-driven-development；只有业务语义、权限、数据影响或范围尚未确定时回到 problem-framing，不把局部实现判断变成新的产品决策。

Backend Architecture Map

先理解 请求架构与调用生命周期 的总体结构与维护边界，再按任务读主题，无需先遍历全项目架构。

api-server（唯一进程内 composition root）
  Protocol Adapter → Canonical Interface / 冻结计划
                   → typed Handler → Business / Execution
                   → 结果与收尾 → 协议投影

• Protocol Adapter 负责协议解析、认证接入和响应投影；业务入口经注册 Binding / Plan 进入统一调用内核。
• Canonical Interface 拥有调用身份、阶段与终态；业务 owner 拥有规则和事务，执行与存储模块承接稳定 ports。
• 调用终态、业务 commit/rollback、协议 delivery/ack 各有 owner，不能互相推断；关闭连接不自动等于取消业务。
• 这是调用关系，不是 Cargo 依赖图。crate owner 与允许依赖只维护在 api/crates/AGENTS.md；实际 mount 与 Catalog、声明与编译快照的关系由架构文档解释。
• 插件选型按治理边界、贡献、执行方式与作用域分别判断；可信宿主内部实现归 HostExtension，公开协议受管贡献不因设置页、数据或接口注册而升级类型。旧 RuntimeExtension / CapabilityPlugin 分配限制单独作为当前实现事实取证。

Truth and Task Routing

架构文档定义关系，AGENTS 定义执行约束，源码与运行态揭示实际行为。三者不一致时定位偏离；不自动扩大授权去改架构或业务语义。

Implementation Decisions

• 状态变更经唯一明确 owner；核心规则不依赖外部协议格式、存储细节或临时 UI 形态。
• 公共接口表达具体对象和动作，Rust 类型表达不变量，错误显式传播；不为拆分而增加无职责包装层。
• 前端缺业务字段、排序 / 筛选 / 聚合结果时补职责单一的后端 DTO / API / 查询；字段沿用 DTO / 领域原名。
• 系统内置数据与用户 metadata、宿主与插件写集等专项边界，按上表加载对应真值；不因任何后端改动加载所有专项。
• 新增或改变目标、source of truth、权限、历史数据处理或对外 contract 时回到需求对齐；已批准范围内的装配、fixture 与局部实现修正继续。

Evidence and Exit

完成开发后用 qa-evaluation 对照架构与行为验收。交付保留 route / service / domain / adapter 等改动 owner、关键决策与证据指针；已有 AC 标明已覆盖、未覆盖及延后项。

执行成本、Cargo 并发、证据复用与资源失败转向沿用 test-driven-development。当前行为与直接风险证据充分即停止；编译或源码门禁不代替行为测试，未运行的重型验证不冒充通过。