AGENTS.md@src/host · diff
git:20260923.4575b13 to git:20260928.0bc633c
43 added, 45 removed. Audit A to A.
# Host Rules
- 适用于 `src/host/` 全域。本文件是 Host 半区**跨模块通用规则**的唯一承接点。
+ 适用于 `src/host/`。本文件是 Host 跨模块通用规则的唯一承接点。
- ## 本层承担什么
+ ## 本层职责与归属
- Host 根是「包级入口 + 宿主组合 + 宿主级横切契约」的落点，职责只有三类：
+ Host 根只承担三类职责：
- 1. **包级入口**：对外发布路径固定的插件入口（主插件入口与服务进程入口）。入口只做装配与协调；
- 2. **宿主组合根**：装配各模块公共能力、建立事件观察、汇总生命周期与清理；
- 3. **宿主级横切契约**：多个模块共同消费、但不属于任一模块领域的最小契约（输入校验、官方服务最小结构、跨进程共享的解析规则等）。
+ 1. **包级入口**：发布路径固定的插件入口（主插件入口、服务进程入口），只做装配与协调。
+ 2. **宿主组合根**：装配公共能力、建立事件观察、汇总生命周期与清理。
+ 3. **宿主级横切契约**：两个以上模块以相同语义消费、且不拥有业务状态的最小契约（输入校验、官方服务最小结构、跨进程共享解析规则等）。
- 判断标准：一段代码若只服务一个模块，归属该模块；若被**两个以上模块**以相同语义消费，且它不拥有任何业务状态，
- 才属于本层。禁止把本层当作「放不下的代码」的收容所。
+ 判断：只服务一个模块的代码归该模块；被两个以上模块同语义消费且无业务状态才归本层。禁止把本层当“放不下代码”的收容所。
- ## 入口规则
+ ## 入口
- - 入口只做三件事：解析装配参数、装配模块能力、协调进程/插件生命周期。**不承载业务语义**；
- - 装配所需的默认值必须来自配置契约的**唯一来源**，入口不得复制默认值清单、校验清单或字段映射；
- - 入口对模块的引用只走模块的**公共入口或对外契约文件**，不得触达内部实现细节；
- - 入口的失败必须显式（明确错误 / 非零退出码），不得静默降级。
+ - 只做三件事：解析装配参数、装配模块能力、协调进程/插件生命周期；不承载业务语义。
+ - 默认值来自配置契约唯一来源；不得复制默认值清单、校验清单或字段映射。
+ - 引用模块只走公共入口或对外契约文件，不得触达内部实现。
+ - 失败必须显式：明确错误 / 非零退出码，不得静默降级。
- ## 横切契约规则
+ ## 横切契约
- - **单一来源**：同一官方能力的最小结构契约、同一官方服务的枚举投影、同一解析规则，全 Host 只允许一处实现；
- - **零业务状态**：横切契约只含纯结构类型与纯函数（解析、投影、校验）；不持有实例状态、缓存、定时器或生命周期；
- - **不决定降级语义**：契约只表达事实（服务是否可用、清单是什么），缺失时的降级（报错 / 空清单 / 告警）由调用方按各自语义决定；
- - **依赖方向**：横切契约只允许依赖 shared 的纯类型与 Node 内置能力；**不得**反向依赖任何业务模块，也不得依赖 api / client。
+ - **单一来源**：同一官方能力最小结构、枚举投影、解析规则，全 Host 只允许一处实现。
+ - **零业务状态**：只含纯结构类型与纯函数（解析、投影、校验）；不持有实例状态、缓存、定时器或生命周期。
+ - **不决定降级语义**：契约只表达事实；缺失时的降级由调用方按各自语义决定。
+ - **依赖方向**：只允许依赖 shared 纯类型与 Node 内置能力；不得反向依赖业务模块、api 或 client。
- ## 宿主组合根规则
+ ## 宿主组合根
- - 组合根是本层唯一的「知道所有模块」的位置：装配顺序、事件观察、清理顺序在此显式排列；
- - 事件观察只做「翻译与转发」：把官方事件翻译成领域调用，不在组合根里实现领域判断；
- - 生命周期汇总按**依赖逆序**清理，且每一步都幂等；子资源的撤销权归宿主，模块不得自建第二套撤销表；
- - 官方事件与官方 payload 的本地声明属于 program 级事实，只允许在本层收窄声明（只声明本插件真正消费的字段），
- - 不得伪造官方不存在的契约；对形状漂移一律运行时守卫 + 降级，不得因未知字段抛错。
+ - 本层唯一“知道所有模块”的位置：装配顺序、事件观察、清理顺序显式排列。
+ - 事件观察只做翻译与转发：官方事件翻译成领域调用，不在组合根实现领域判断。
+ - 生命周期按依赖逆序清理，每一步幂等；子资源撤销权归宿主，模块不得自建第二套撤销表。
+ - 官方事件与 payload 的本地声明属 program 级事实，只允许在本层收窄声明（只声明真正消费的字段）；不得伪造官方不存在的契约。
+ - 形状漂移一律运行时守卫 + 降级，不因未知字段抛错。
## 跨模块协作
- - 两个模块需要共享同一能力时，优先「一方提供公共入口 + 另一方经注入消费」，其次才是本层的横切契约；
- - 本层只承接**无领域归属**的共同事实，不承接「两个模块的协作逻辑」；
- - 跨进程协作只经磁盘事实与启动参数，不共享内存；
+ - 两模块共享能力，优先“一方公共入口 + 另一方注入消费”，其次本层横切契约。
+ - 本层只承接无领域归属的共同事实，不承接两个模块的协作逻辑。
+ - 跨进程协作只经磁盘事实与启动参数，不共享内存。
## 模块通用规则
### 状态所有权与单一事实源
- - 每个事实只允许一个所有者与一个写入边界；状态变化只经所有者表达业务语义的操作（方法 / 事件）完成，禁止直接改字段；
- - 禁止跨模块直接修改对方内部状态；对外暴露的状态默认只读，查询接口与修改接口必须区分；
- - 无对应语义化操作时，增加明确操作而不是暴露内部状态；
- - 同一概念只允许一处本体（一处字面量 + 一处映射）；使用方引用本体。
+ - 每个事实只有一个所有者与一个写入边界；状态变化只经所有者表达业务语义的操作（方法/事件），禁止直接改字段。
+ - 禁止跨模块直接修改对方内部状态；对外状态默认只读，查询与修改接口区分。
+ - 无对应语义化操作时，增加明确操作，而不是暴露内部状态。
+ - 同一概念只允许一处本体（一处字面量 + 一处映射），使用方引用本体。
### 纯函数与副作用
- - 确定性计算（判定、归一化、投影、签名与键推导、字段映射）必须实现为纯函数；
- - 副作用只出现在有明确职责的位置，不得藏在名称模糊的 helper 或看似纯计算的函数中；
- - 数据必须「传入即全部事实」：不得从环境或全局隐式读取输入。
+ - 确定性计算（判定、归一化、投影、签名与键推导、字段映射）必须是纯函数。
+ - 副作用只出现在有明确职责的位置，不得藏在模糊 helper 或看似纯计算的函数中。
+ - 数据必须“传入即全部事实”，不得从环境或全局隐式读取输入。
### 错误处理
- - 错误必须可行动：说明发生了什么、当前状态、缺少什么、如何恢复；
- - 区分运行语义失败与 best-effort 辅助失败：前者不得吞掉或伪装成功；后者必须写明降级链，且可在注释与测试中追溯；
- - 辅助路径不得静默失效：双线护栏类降级必须保证至少一条生效；
- - 稳定错误码 / 错误类型属对外契约，新增或修改必须同步调用方、测试与文档；
- - 外部 / 官方形状漂移按运行时守卫收窄并降级，不因未知字段抛错；**降级方向必须与业务语义一致**。
+ - 错误必须可行动：说明发生了什么、当前状态、缺少什么、如何恢复。
+ - 区分运行语义失败与 best-effort 辅助失败：前者不得吞掉或伪装成功；后者必须写明降级链，并可在注释与测试中追溯。
+ - 辅助路径不得静默失效；双线护栏类降级至少一条生效。
+ - 稳定错误码/错误类型属对外契约，新增或修改必须同步调用方、测试与文档。
+ - 外部/官方形状漂移按运行时守卫收窄并降级，不因未知字段抛错；降级方向必须与业务语义一致。
### 契约稳定性与兼容性
- - 字段增删兼容优先：新增字段默认可选；删除或改义必须给出兼容路径与旧数据读取行为；退役字段只保留读取兼容，禁止新增写入；
- - 修改公共契约必须同步检查调用方、测试、Tool Schema 与相关文档；
+ - 字段增删兼容优先：新增字段默认可选；删除或改义必须给出兼容路径与旧数据读取行为；退役字段只保留读取兼容，禁止新增写入。
+ - 修改公共契约必须同步检查调用方、测试、Tool Schema 与相关文档。
- 行为变化必须显式记录：旧行为 → 新行为 → 原因 → 影响范围 → 测试变化；纯重构不得夹带行为变化。
## 修改前确认
1. 是否改变公共入口导出面或其它公共契约？
- 2. 是否引入反向依赖、循环依赖，或绕过依赖缝直接引用其它模块的内部实现文件？
- 3. 是否产生第二份事实源，或第二套持久化协议？
+ 2. 是否引入反向依赖、循环依赖，或绕过依赖缝直接引用其它模块内部实现？
+ 3. 是否产生第二份事实源或第二套持久化协议？
4. 是否引入新的并发窗口、未释放资源或非确定性依赖？
- 5. 涉及本层时：这段代码属于包级入口、宿主组合，还是横切契约？有没有更合适的模块归属？
+ 5. 本层代码属于包级入口、宿主组合，还是横切契约？有无更合适的模块归属？
## 核心原则
包级入口只装配不承载语义；横切契约单一来源且无状态；官方能力只收窄不伪造；宿主组合显式且生命周期可追踪；模块内聚、依赖单向、协作经公共入口。
-