AGENTS.md@src/host/api git:20260922.cf8e5a9A

Immutable. This exact content never changes and is served at /api/v1/blob/b60b39b7d54870d0.

# API Boundary Module Rules

适用于 `src/host/api/`（Host 进程面向 GUI 的 HTTP API 边界）。通用规范遵循根 `AGENTS.md`；本文件只写本边界特有的稳定规则，不描述当前文件结构。

## 核心职责

把 GUI 的 HTTP 请求翻译成对 Host 领域能力的调用，并把结果与失败翻译回稳定的对外响应契约（端点名、响应包形状、错误码、HTTP 状态）。

判断归属：该改动是否改变「请求如何被翻译成领域调用」或「对外响应契约」？只改变领域语义判断（合法性、状态机推进、冲突策略、持久化形状）应放到对应领域模块。

## 非职责

- 领域决策：合法性判断、状态推进、编排、冲突策略；
- 持久化与数据目录布局：文件落盘、原子发布、路径计算一律归 storage；外部配置文件格式归其对应领域模块；
- 运行态内存事实：运行锁、快照、子代理表归 orchestrator；
- 客户端展示：不得在端点内固化 UI 布局尺寸或文案分支逻辑。

## 契约（可执行）

- 端点名以共享协议常量为唯一来源；新增端点必须同时进入共享常量与白名单，两者零漂移；
- 未知端点 404、参数缺失 400；调用方错误不得被响应成 500；
- 领域模块只抛稳定错误码，HTTP 状态映射只发生在边界；领域模块不得引用传输层错误类型；
- 响应包形状、错误码语义与端点名属对外契约，变更必须同步客户端、协议常量与测试。

## 状态、副作用与生命周期

- 本层不持有业务状态：不缓存领域数据、不自建持久化、不保存跨请求可变的实例字段；
- 领域能力只经宿主能力缝注入；能力缺失必须给出明确错误或降级响应，不得静默失效；
- 流式端点必须绑定请求中止信号，在请求结束或断连时释放上游资源；
- 副作用（落盘、子进程、网络调用）必须经对应领域模块的入口，不得在端点或辅助函数中直接实施。

## 依赖方向

- 边界依赖领域，领域不依赖边界；端点组之间不得互相依赖——新增端点组只登记到汇聚清单；
- 跨模块协作只经能力缝、命令、事件或服务；不得直接修改其他模块的内部状态。

## 修改前确认

1. 这是协议转换，还是领域决策？
2. 是否改变端点名、响应形状、错误码或状态映射？
3. 调用方、客户端、协议常量与测试是否同步？

## 核心原则

薄边界、单向依赖、契约稳定、无状态、错误可翻译。