AGENTS.md@src/host/orchestrator git:20260922.c07a623A

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

# Orchestrator Module Rules

## 适用范围
适用于 `src/host/orchestrator/`。本文件定义 orchestrator 模块特有的治理边界、运行时契约和修改规则；通用规范遵循根 `AGENTS.md`。

本文件描述稳定治理原则，不是当前源码结构说明。除非架构契约变化，否则不因文件移动、重命名或内部重构而修改。

## 核心职责
治理一次 Workflow Run 的运行时事实与生命周期：

- 管理运行实例及运行时状态；
- 驱动节点执行与状态推进；
- 管理暂停、恢复、终止、清理；
- 管理等待、子代理事件与协作状态；
- 同步运行事实到持久化层及宿主能力；
- 保证状态、生命周期和并发行为符合运行时契约。

判断归属：该修改是否改变 Workflow Run 的运行事实、状态转换、生命周期或运行时协调机制？若主要属于其他领域，应放到对应模块。

## 非职责
不负责：

- Agent 语义判断：是否重新规划、是否有设计风险、是否更换 Agent、是否向上汇报、是否修改 Workflow 结构；
- Workflow 文档与结构编辑：可读取定义，但结构修改必须通过规定存储或编排能力完成；
- Tool 协议层：Schema、可见性、调用方身份派生、对外协议格式；
- UI 与展示：展示形式、前端状态、界面交互；
- 具体外部实现：不得直接依赖具体 Tool、Agent、存储或其他基础设施实现，应通过依赖接口、能力缝或适配层注入。

## 状态所有权
Orchestrator 是 Workflow Run 运行时状态的主要所有者。

- 运行状态只能由 orchestrator 内部语义化操作修改；
- 模块外不得直接修改运行实例内部状态；
- 调用方表达“希望发生什么”，而非直接操作状态；
- 查询与修改接口必须明确区分；
- 对外暴露的运行状态默认只读诊断数据。

无对应语义化 API 时，应增加或调整明确的运行时操作，而不是暴露内部状态。

### 单一写者
运行快照及核心运行事实必须有明确写入边界，同一事实不得存在多个无协调写入者。状态变化通过表达业务语义的方法完成，如修改节点状态、运行状态、标记暂停/完成/失败，而非直接改字段。

## 生命周期
Workflow Run 必须有明确可追踪的生命周期：

```text
创建 → 启动 → 推进 → 暂停/中断/恢复 → 完成/失败/停止 → 清理
```

必须保证：

- 创建有明确初始化边界；
- 启动失败能清理已建立状态；
- 暂停、恢复、终止、失败、完成有明确状态语义；
- 终态释放运行资源；
- 清理逻辑幂等；
- 新增定时器、监听器、等待器等必须有释放路径。

状态转换必须集中、明确、可验证。新增状态或转换时：说明生命周期语义、检查现有转换、检查恢复/终止/清理路径、增加测试。

## 依赖边界
依赖方向：

```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 实例。需要时间等外部因素时，优先通过显式参数传入。

纯函数应满足：相同输入 → 相同输出，不修改输入，无隐藏副作用，不依赖隐式全局状态。

## 错误处理
运行语义错误必须有稳定、可识别的错误类型或错误码。错误信息应说明：发生了什么、当前状态、缺少什么、如何修正。

区分业务/运行语义失败与非关键辅助操作失败。业务失败不得静默吞掉或伪装成功。

新增或修改稳定错误码时，同步检查调用方、Tool 层错误呈现、测试、相关文档或契约。

## 模块内部组织
文件结构不是架构契约。禁止为“看起来模块化”机械拆分。拆分应基于真实职责边界、变化原因、依赖边界、测试边界、生命周期边界。

不要创建无明确职责的 `utils.ts`、`helpers.ts`、`common.ts`、`shared.ts`、`misc.ts` 等万能聚合文件。

不得通过增加继承层扩展职责。新增能力优先组合、独立模块、明确依赖接口、明确运行时服务。改变核心继承结构应作为独立架构变更，不得夹带在普通功能修改或重构中。

## 架构演进
本文件不记录当前源码的具体文件、类、函数、状态变量、继承层级或 import 路径。这些属于源码或架构文档。

内部实现变化时，先判断治理原则是否仍成立。仅实现变化而治理原则未变，不应修改本文件。仅当模块职责、模块边界、状态所有权、生命周期契约或依赖治理原则变化时，才重新审视本文件。

## 核心原则
1. 运行事实由 orchestrator 统一治理。
2. 状态只有明确所有者和写入边界。
3. 状态变化必须通过语义化操作完成。
4. 生命周期必须显式、完整、可清理。
5. 运行时确定性事实与 Agent 语义判断分离。
6. 依赖通过明确边界进入，不直接侵入具体实现。
7. 副作用必须可识别，纯函数必须保持纯粹。
8. 并发、取消、超时和清理必须有明确契约。
9. 新增能力优先组合，不继续堆叠继承层。
10. 文件结构可变化，模块治理边界不可随意突破。