AGENTS.md@src/host/graph · diff
git:20260922.cf8e5a9 to git:20260923.4575b13
14 added, 88 removed. Audit A to A.
# Graph Module Rules
- ## 适用范围
-
- 适用于 `src/host/graph/`。本文件定义图契约模块特有的稳定治理边界与修改规则；通用规范遵循根 `AGENTS.md`，测试规范遵循 `tests/AGENTS.md`。
-
- 本文件描述治理原则，不是源码结构说明。文件移动、重命名或内部重构后，只要职责、事实源、依赖方向与对外契约未变，本文件不随之修改。
+ ## 范围与职责
- ## 核心职责
+ 适用于 `src/host/graph/`。
提供「工作流图」的确定性契约与判定：图的形状与连接点语义、图的构造与只读查询、结构合法性校验与规范化、编排质量检查（问题清单）、组织元参数的归一化与规模护栏。
- 判断归属：该修改是否改变**图契约、图判定口径或图的规模约束**？若主要属于其他领域（运行推进、Agent 语义、Tool 协议、UI 展示、持久化），应放到对应模块。
-
- ## 非职责
-
- - 不读写持久化、文件、网络或数据库，不管理运行锁与运行状态；
- - 不推进生命周期，不拥有任何跨调用存活的状态；
- - 不做 Agent 语义判断（是否重规划、是否汇报、是否改变执行策略）；
- - 不注册 Tool、不定义 Tool Schema、不渲染界面；
- - 不直接修改其他模块的内部状态。
-
- ## 纯函数契约
-
- 判定与计算一律为纯函数：相同输入 → 相同输出，不修改入参，不依赖全局可变状态、当前时间、随机源、文件系统或运行时实例。
-
- - 唯一例外是节点/连线标识工厂：其唯一性需要随机来源，该来源必须封闭在工厂内部，不得扩散进任何判定或校验逻辑；
- - 需要时间等外部因素时，通过显式参数传入；
- - 数据必须是「传入即全部事实」：不得从环境或全局读取图状态。
-
- ## 单一事实源
-
- 同一图概念只允许一处本体。流转通道判定、可执行单元口径、问题级别、问题 code 全集等，必须有唯一来源。
-
- - 禁止以「两份字面量」「结构镜像 + 列表断言」的方式重复维护同一契约；
- - 同一口径被多处使用时，使用方引用本体，而不是各自重写；
- - 跨半区（Client）因程序隔离**必须**另行实现同一口径时，两侧语义必须由**契约测试**分别锁定同一行为，不得靠跨半区 import 消除重复。
+ 判断归属：该修改是否改变**图契约、图判定口径或图相关的约束**？若主要属于其他领域（运行推进、Agent 语义、Tool 协议、UI 展示、持久化），应放到对应模块。
## 子域边界
- 本模块内部存在变化原因不同的子域：图契约与结构校验、编排质量检查、组织元参数与规模护栏。
+ 子域：图契约与结构校验、编排质量检查、组织元参数与规模护栏。
- 子域之间只通过明确的输入输出协作，不得互相承担对方职责；
- - 结构校验判定「图是否合法」（形状、连接点、拓扑）；质量检查判定「图是否编排得当」（设计提醒），不得互相重新定义对方的结论；
- - 元参数护栏只约束**代理**改图，不约束用户手工改图——是否启用由调用方按变更来源决定，本模块不做来源判定；
- - 新增能力先判断属于哪个子域，再放到该子域的职责中，不得为了就近而堆进已有文件。
-
- ## 问题级别与稳定 code
-
- - 级别语义固定：阻断级即调用方拒绝落盘；提示级只提醒、不阻断；
- - 问题 code 属对外契约：发布后不得改名或改级别；新增规则必须登记到 code 注册表；
- - 阻断级问题必须给出可执行的修复建议（这是失败方自我修正的唯一通道）；
- - 新增或修改 code 时同步检查：注册表、规则实现、聚合层、修复建议、测试。
-
- ## 公共边界
-
- - 模块外只允许经模块的**公共入口**导入，禁止直接引用模块内部文件；
- - 只把真实、稳定、可维护的契约放进公共入口，禁止「全量 barrel」把内部实现一并暴露；
- - 内部实现（单条规则、内部遍历助手、自检工具等）不进入公共入口；
- - 新增公共符号前先判断它是否表达对外稳定契约；放宽入口比收紧入口的代价更高。
+ - 结构校验判定「图是否合法」（形状、连接点、拓扑）；质量检查判定「图是否编排得当」（设计提醒），两者不得互相重新定义对方的结论；
+ - 元参数护栏只约束**代理**改图，不约束用户手工改图——是否启用由调用方按变更来源决定，本模块不做来源判定。
## 依赖边界
- - 只允许依赖共享契约层（Host/Client 共享的形状与协议常量）；
- - 不得依赖 orchestrator / tools / agent / storage / service / api / client；
- - 依赖方向单向：调用方依赖本模块的判定，本模块不反向依赖任何调用方。
-
- ## 契约稳定性
-
- - 校验问题码、检查器 code、字段语义与级别属公共契约，修改必须同步调用方、测试与文档；
- - 字段增删遵循兼容优先：新增字段默认可选；删除或改义必须说明旧数据的读取行为与兼容路径；
- - 判定口径变化（例如「什么算流程线」「什么算参与流程」）属于行为变化，必须记录：旧行为 → 新行为 → 原因 → 影响范围 → 测试变化。
-
- ## 模块内部组织
-
- - 文件结构不是架构契约，禁止为「看起来模块化」机械拆分；拆分依据只能是职责、变化原因、依赖边界与测试边界；
- - 文件命名必须表达**稳定职责与所属维度**，同族文件保持一致命名维度；名称失真的文件应立即重命名并同步全部引用；
- - 不得创建 `utils.ts`、`helpers.ts`、`common.ts`、`shared.ts`、`misc.ts` 等无明确职责的聚合文件；
- - 内部文件之间使用相对路径导入，公共入口不含实现。
-
- ## 修改前检查
-
- 1. 改动属于图契约、结构校验、质量检查还是元参数？
- 2. 是否改变判定口径？受影响的上层调用方与测试是哪些？
- 3. 是否新增/修改稳定 code、级别或字段？注册表与测试是否同步？
- 4. 是否引入非纯依赖（时钟 / 随机 / IO / 全局状态）？
- 5. 是否产生第二份事实源？
- 6. 是否越界进入其他模块职责？
-
- ## 验证
-
- 至少执行：
+ - 只允许依赖 shared 的形状与协议常量及 Node 内置能力；
+ - 本模块是判定提供方：调用方依赖本模块的判定，本模块不反向依赖调用方。
- ```text
- pnpm typecheck
- pnpm test
- pnpm build
- ```
+ ## 验证补充
- 同时确认：公共入口导出面未意外扩大、无旧路径残留、无循环依赖、无重复实现、判定口径变化已按契约记录。
+ - 问题 code 的注册表、级别与阻断/提示语义有测试锁定；
+ - 判定口径边界（什么算流程线、什么算参与流程）有测试锁定；
+ - 公共入口导出面未意外扩大。
## 核心原则
- 1. 图判定确定性优先，纯函数不可含隐藏依赖。
+ 1. 图判定确定性优先，纯函数不含隐藏依赖。
2. 同一图概念只有一处本体，禁止双份维护。
3. 结构合法性、编排质量与规模约束各守其责。
4. 问题 code 与级别是契约，新增必须登记。
- 5. 模块外只经公共入口协作，内部实现不外溢。
- 6. 依赖单向，不反向依赖调用方。
- 7. 判定口径变化必须显式记录并锁定测试。
+ 5. 判定口径变化必须显式记录。