AGENTS.md@src/host git:20260928.0bc633cA

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

# Host Rules

适用于 `src/host/`。本文件是 Host 跨模块通用规则的唯一承接点。

## 本层职责与归属

Host 根只承担三类职责：

1. **包级入口**：发布路径固定的插件入口（主插件入口、服务进程入口），只做装配与协调。
2. **宿主组合根**：装配公共能力、建立事件观察、汇总生命周期与清理。
3. **宿主级横切契约**：两个以上模块以相同语义消费、且不拥有业务状态的最小契约（输入校验、官方服务最小结构、跨进程共享解析规则等）。

判断：只服务一个模块的代码归该模块；被两个以上模块同语义消费且无业务状态才归本层。禁止把本层当“放不下代码”的收容所。

## 入口

- 只做三件事：解析装配参数、装配模块能力、协调进程/插件生命周期；不承载业务语义。
- 默认值来自配置契约唯一来源；不得复制默认值清单、校验清单或字段映射。
- 引用模块只走公共入口或对外契约文件，不得触达内部实现。
- 失败必须显式：明确错误 / 非零退出码，不得静默降级。

## 横切契约

- **单一来源**：同一官方能力最小结构、枚举投影、解析规则，全 Host 只允许一处实现。
- **零业务状态**：只含纯结构类型与纯函数（解析、投影、校验）；不持有实例状态、缓存、定时器或生命周期。
- **不决定降级语义**：契约只表达事实；缺失时的降级由调用方按各自语义决定。
- **依赖方向**：只允许依赖 shared 纯类型与 Node 内置能力；不得反向依赖业务模块、api 或 client。

## 宿主组合根

- 本层唯一“知道所有模块”的位置：装配顺序、事件观察、清理顺序显式排列。
- 事件观察只做翻译与转发：官方事件翻译成领域调用，不在组合根实现领域判断。
- 生命周期按依赖逆序清理，每一步幂等；子资源撤销权归宿主，模块不得自建第二套撤销表。
- 官方事件与 payload 的本地声明属 program 级事实，只允许在本层收窄声明（只声明真正消费的字段）；不得伪造官方不存在的契约。
- 形状漂移一律运行时守卫 + 降级，不因未知字段抛错。

## 跨模块协作

- 两模块共享能力，优先“一方公共入口 + 另一方注入消费”，其次本层横切契约。
- 本层只承接无领域归属的共同事实，不承接两个模块的协作逻辑。
- 跨进程协作只经磁盘事实与启动参数，不共享内存。

## 模块通用规则

### 状态所有权与单一事实源

- 每个事实只有一个所有者与一个写入边界；状态变化只经所有者表达业务语义的操作（方法/事件），禁止直接改字段。
- 禁止跨模块直接修改对方内部状态；对外状态默认只读，查询与修改接口区分。
- 无对应语义化操作时，增加明确操作，而不是暴露内部状态。
- 同一概念只允许一处本体（一处字面量 + 一处映射），使用方引用本体。

### 纯函数与副作用

- 确定性计算（判定、归一化、投影、签名与键推导、字段映射）必须是纯函数。
- 副作用只出现在有明确职责的位置，不得藏在模糊 helper 或看似纯计算的函数中。
- 数据必须“传入即全部事实”，不得从环境或全局隐式读取输入。

### 错误处理

- 错误必须可行动：说明发生了什么、当前状态、缺少什么、如何恢复。
- 区分运行语义失败与 best-effort 辅助失败：前者不得吞掉或伪装成功；后者必须写明降级链，并可在注释与测试中追溯。
- 辅助路径不得静默失效；双线护栏类降级至少一条生效。
- 稳定错误码/错误类型属对外契约，新增或修改必须同步调用方、测试与文档。
- 外部/官方形状漂移按运行时守卫收窄并降级，不因未知字段抛错；降级方向必须与业务语义一致。

### 契约稳定性与兼容性

- 字段增删兼容优先：新增字段默认可选；删除或改义必须给出兼容路径与旧数据读取行为；退役字段只保留读取兼容，禁止新增写入。
- 修改公共契约必须同步检查调用方、测试、Tool Schema 与相关文档。
- 行为变化必须显式记录：旧行为 → 新行为 → 原因 → 影响范围 → 测试变化；纯重构不得夹带行为变化。

## 修改前确认

1. 是否改变公共入口导出面或其它公共契约？
2. 是否引入反向依赖、循环依赖，或绕过依赖缝直接引用其它模块内部实现？
3. 是否产生第二份事实源或第二套持久化协议？
4. 是否引入新的并发窗口、未释放资源或非确定性依赖？
5. 本层代码属于包级入口、宿主组合，还是横切契约？有无更合适的模块归属？

## 核心原则

包级入口只装配不承载语义；横切契约单一来源且无状态；官方能力只收窄不伪造；宿主组合显式且生命周期可追踪；模块内聚、依赖单向、协作经公共入口。