git:20260922.c07a623 to git:20260923.4575b13
17 added, 79 removed. Audit A to A.
# Orchestrator Module Rules
- ## 适用范围
- 适用于 `src/host/orchestrator/`。本文件定义 orchestrator 模块特有的治理边界、运行时契约和修改规则；通用规范遵循根 `AGENTS.md`。
+ ## 范围与职责
- 本文件描述稳定治理原则，不是当前源码结构说明。除非架构契约变化，否则不因文件移动、重命名或内部重构而修改。
+ 适用于 `src/host/orchestrator/`。
- ## 核心职责
治理一次 Workflow Run 的运行时事实与生命周期：
- 管理运行实例及运行时状态；
- 驱动节点执行与状态推进；
- 管理暂停、恢复、终止、清理；
- 管理等待、子代理事件与协作状态；
- 同步运行事实到持久化层及宿主能力；
- 保证状态、生命周期和并发行为符合运行时契约。
判断归属：该修改是否改变 Workflow Run 的运行事实、状态转换、生命周期或运行时协调机制？若主要属于其他领域，应放到对应模块。
- ## 非职责
- 不负责：
-
- - Agent 语义判断：是否重新规划、是否有设计风险、是否更换 Agent、是否向上汇报、是否修改 Workflow 结构；
- - Workflow 文档与结构编辑：可读取定义，但结构修改必须通过规定存储或编排能力完成；
- - Tool 协议层：Schema、可见性、调用方身份派生、对外协议格式；
- - UI 与展示：展示形式、前端状态、界面交互；
- - 具体外部实现：不得直接依赖具体 Tool、Agent、存储或其他基础设施实现，应通过依赖接口、能力缝或适配层注入。
-
## 状态所有权
+
Orchestrator 是 Workflow Run 运行时状态的主要所有者。
- 运行状态只能由 orchestrator 内部语义化操作修改；
+ - 运行快照及核心运行事实必须有明确写入边界，同一事实不得存在多个无协调写入者；
- 模块外不得直接修改运行实例内部状态；
- 调用方表达“希望发生什么”，而非直接操作状态；
- 查询与修改接口必须明确区分；
- 对外暴露的运行状态默认只读诊断数据。
无对应语义化 API 时，应增加或调整明确的运行时操作，而不是暴露内部状态。
- ### 单一写者
- 运行快照及核心运行事实必须有明确写入边界，同一事实不得存在多个无协调写入者。状态变化通过表达业务语义的方法完成，如修改节点状态、运行状态、标记暂停/完成/失败，而非直接改字段。
-
## 生命周期
- Workflow Run 必须有明确可追踪的生命周期：
- ```text
- 创建 → 启动 → 推进 → 暂停/中断/恢复 → 完成/失败/停止 → 清理
- ```
+ Workflow Run 生命周期：创建 → 启动 → 推进 → 暂停/中断/恢复 → 完成/失败/停止 → 清理。
必须保证：
- 创建有明确初始化边界；
- 启动失败能清理已建立状态；
- 暂停、恢复、终止、失败、完成有明确状态语义；
- 终态释放运行资源；
- 清理逻辑幂等；
- 新增定时器、监听器、等待器等必须有释放路径。
状态转换必须集中、明确、可验证。新增状态或转换时：说明生命周期语义、检查现有转换、检查恢复/终止/清理路径、增加测试。
## 依赖边界
- 依赖方向：
- ```text
- 外部能力 → 依赖接口 / Capability / Adapter → Orchestrator → 运行时状态与生命周期
- ```
-
- 具体实现不得反向侵入核心状态管理。禁止循环依赖、绕过公开接口、直接依赖 Tool/Agent 具体实现、通过共享可变对象隐式耦合。
-
- 仅在存在真实替换、测试隔离、模块边界或外部实现隔离需求时增加抽象，不得为形式解耦创建无职责接口层。
-
- ## 公共接口
- 模块外不得依赖内部实现细节。公共 API 修改必须同步检查调用方、类型契约、生命周期、错误处理、测试和相关架构文档。
-
- 区分内部实现变化与运行时契约变化。纯内部重构不得无故改变外部行为。运行时语义变化必须记录：旧行为 → 新行为 → 原因 → 影响范围 → 测试变化。
-
- Tool 名称、参数 Schema、输出 Schema、稳定错误码属于外部契约时，普通重构不得无意改变。
-
- ## 并发与异步
- 并发正确性优先于代码简洁。
-
- - **Check-Then-Act**：检查运行状态并登记时，不得在 check 与 act 之间出现导致竞争的异步切换；运行锁、登记、恢复去重不得出现 `check → await → act` 使并发调用同时通过。
- - **去重**：启动、恢复、接续、事件处理等运行级操作必须有明确去重策略。Promise 或进行中操作承担去重时，应在第一次异步等待前登记，并在成功、失败、取消路径正确清理。
- - **等待**：先登记等待器，再启动可能触发事件的操作；正确处理完成、失败、取消、超时；结束后清理等待状态。不得依赖任意 `sleep` 保证事件顺序。
- - **取消与超时**：取消必须沿生命周期正确传播。新增 Timer、Timeout、Listener、Waiter、Subscription、Background Task 必须定义清理路径。不得引入无界重试或无法终止的后台任务。
-
- ## 副作用边界
- 可执行运行时副作用，但必须有明确责任边界：持久化运行事实、启动或中断子任务、发送运行时消息、修改运行时状态、创建或清理等待状态、创建或清理定时器、调用外部运行能力。
-
- 副作用不得隐藏在名称模糊的 helper、看似纯函数、通用工具或无关模块中。对于尽力而为的副作用，应区分“副作用失败”与“运行本身失败”，不得吞掉异常把运行失败伪装成成功。
-
- ## 纯函数边界
- 与运行时状态无关的确定性计算应保持纯函数。纯函数不得隐式依赖全局可变状态、当前时间、随机源、文件系统、网络、数据库、Agent Session 或 Runtime 实例。需要时间等外部因素时，优先通过显式参数传入。
-
- 纯函数应满足：相同输入 → 相同输出，不修改输入，无隐藏副作用，不依赖隐式全局状态。
+ - 依赖方向：外部能力 → 依赖接口 / Capability / Adapter → Orchestrator → 运行时状态与生命周期。
+ - 仅在存在真实替换、测试隔离、模块边界或外部实现隔离需求时增加抽象，不得为形式解耦创建无职责接口层。
## 错误处理
- 运行语义错误必须有稳定、可识别的错误类型或错误码。错误信息应说明：发生了什么、当前状态、缺少什么、如何修正。
- 区分业务/运行语义失败与非关键辅助操作失败。业务失败不得静默吞掉或伪装成功。
-
- 新增或修改稳定错误码时，同步检查调用方、Tool 层错误呈现、测试、相关文档或契约。
-
- ## 模块内部组织
- 文件结构不是架构契约。禁止为“看起来模块化”机械拆分。拆分应基于真实职责边界、变化原因、依赖边界、测试边界、生命周期边界。
-
- 不要创建无明确职责的 `utils.ts`、`helpers.ts`、`common.ts`、`shared.ts`、`misc.ts` 等万能聚合文件。
-
- 不得通过增加继承层扩展职责。新增能力优先组合、独立模块、明确依赖接口、明确运行时服务。改变核心继承结构应作为独立架构变更，不得夹带在普通功能修改或重构中。
-
- ## 架构演进
- 本文件不记录当前源码的具体文件、类、函数、状态变量、继承层级或 import 路径。这些属于源码或架构文档。
-
- 内部实现变化时，先判断治理原则是否仍成立。仅实现变化而治理原则未变，不应修改本文件。仅当模块职责、模块边界、状态所有权、生命周期契约或依赖治理原则变化时，才重新审视本文件。
+ - 运行语义错误必须有稳定、可识别的错误类型或错误码（如 `WfError`），错误信息说明：发生了什么、当前状态、缺少什么、如何修正；
+ - 区分业务/运行语义失败与非关键辅助操作失败。业务失败不得静默吞掉或伪装成功。
+ - 新增或修改稳定错误码时，同步检查调用方、Tool 层错误呈现、测试与契约。
## 核心原则
- 1. 运行事实由 orchestrator 统一治理。
- 2. 状态只有明确所有者和写入边界。
- 3. 状态变化必须通过语义化操作完成。
- 4. 生命周期必须显式、完整、可清理。
- 5. 运行时确定性事实与 Agent 语义判断分离。
- 6. 依赖通过明确边界进入，不直接侵入具体实现。
- 7. 副作用必须可识别，纯函数必须保持纯粹。
- 8. 并发、取消、超时和清理必须有明确契约。
- 9. 新增能力优先组合，不继续堆叠继承层。
- 10. 文件结构可变化，模块治理边界不可随意突破。
+
+ 1. 运行事实由 orchestrator 统一治理，状态只有明确所有者与写入边界。
+ 2. 状态变化必须通过语义化操作完成。
+ 3. 生命周期必须显式、完整、可清理。
+ 4. 运行时确定性事实与 Agent 语义判断分离。
+ 5. 并发、取消、超时与清理必须有明确契约。
+ 6. 外部实现经契约缝注入，不反向侵入核心状态。