AGENTS.md@src/host/orchestrator git:20260923.4575b13A

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

# Orchestrator Module Rules

## 范围与职责

适用于 `src/host/orchestrator/`。

治理一次 Workflow Run 的运行时事实与生命周期：

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

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

## 状态所有权

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

- 运行状态只能由 orchestrator 内部语义化操作修改；
- 运行快照及核心运行事实必须有明确写入边界，同一事实不得存在多个无协调写入者；
- 模块外不得直接修改运行实例内部状态；
- 调用方表达“希望发生什么”，而非直接操作状态；
- 查询与修改接口必须明确区分；
- 对外暴露的运行状态默认只读诊断数据。

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

## 生命周期

Workflow Run 生命周期：创建 → 启动 → 推进 → 暂停/中断/恢复 → 完成/失败/停止 → 清理。

必须保证：

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

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

## 依赖边界

- 依赖方向：外部能力 → 依赖接口 / Capability / Adapter → Orchestrator → 运行时状态与生命周期。
- 仅在存在真实替换、测试隔离、模块边界或外部实现隔离需求时增加抽象，不得为形式解耦创建无职责接口层。

## 错误处理

- 运行语义错误必须有稳定、可识别的错误类型或错误码（如 `WfError`），错误信息说明：发生了什么、当前状态、缺少什么、如何修正；
- 区分业务/运行语义失败与非关键辅助操作失败。业务失败不得静默吞掉或伪装成功。
- 新增或修改稳定错误码时，同步检查调用方、Tool 层错误呈现、测试与契约。

## 核心原则

1. 运行事实由 orchestrator 统一治理，状态只有明确所有者与写入边界。
2. 状态变化必须通过语义化操作完成。
3. 生命周期必须显式、完整、可清理。
4. 运行时确定性事实与 Agent 语义判断分离。
5. 并发、取消、超时与清理必须有明确契约。
6. 外部实现经契约缝注入，不反向侵入核心状态。