taichuy 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 扩展宿主 contract；RuntimeExtension 实现 runtime slot；CapabilityPlugin 贡献用户选择的能力。具体生命周期和允许写入口按相关局部规则取证，不把三者混为同一插件类型。
Truth and Task Routing
架构文档定义关系，AGENTS 定义执行约束，源码与运行态揭示实际行为。三者不一致时定位偏离；不自动扩大授权去改架构或业务语义。
| 当前任务 | 读取与定位 |
|---|---|
| 接口装配、认证、Binding、Kernel、stream / cancel / deadline | interface-lifecycle → 架构对应主题 |
| API 输入输出、错误模型 | api-design → route / DTO / typed Handler |
| 状态转换、事务、幂等 | state-and-consistency → 状态写 owner |
| 核心与适配器、外部依赖、HostExtension | boundary-design → 局部 AGENTS / ports |
| 新资源或实现落点 | implementation-rules |
| Rust 类型、async、锁与实现自查 | rust-backend-practices 的相关章节及 completion self-check |
| 内置模型、metadata overlay、runtime read model | builtin-data-model-contract |
| Settings API、注册、角色 operation 授权 | console-settings-registration |
| Agent Flow 节点输入、debug artifact、运行日志 | agentflow-runtime-node-payload |
| 新抽象、公共参数、重复防御、转发层 | design-rules；具体坏味道查 anti-patterns |
| 判断规则例外 | examples |
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。当前行为与直接风险证据充分即停止；编译或源码门禁不代替行为测试，未运行的重型验证不冒充通过。