AGENTS.md@src/host git:20260923.4575b13A

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

# 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. 涉及本层时：这段代码属于包级入口、宿主组合，还是横切契约？有没有更合适的模块归属？

## 核心原则

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