| name | orchestrator-usage |
| description | Orchestrator 层定位、设计决策、与上下层的关系。开发者面向的 opinionated 库,Server 基于它构建。 |
Orchestrator 层 — 面向开发者的编排库
定位
三层自由度递减:
- Session 层:纯库,完全 DI,零假设
- Orchestrator 层:库,但硬编码部分默认行为
- Server 层:框架,基于 orchestrator,加传输层
Orchestrator 和 Server 的分界线:transport 和 coordination 是正交的。串行队列、fork 路由、engine 生命周期管理跟"用 WS 还是 REST"无关。
入口
唯一推荐入口是 createStelloAgent(config),返回 StelloAgent 实例。
StelloAgent 隐藏内部组件(orchestrator/factory/runtimeManager),只暴露操作方法。开发者通过 config 声明意图,不需要理解内部装配过程。
硬编码的 opinionated 行为
这些行为由 orchestrator 内部固定,开发者不能替换:
- 同 session 串行,不同 session 并行 — SessionOrchestrator 的 promise 链队列
- Engine hooks 合并 — Factory 将用户 hooks 和 Scheduler 闭包合并,同 key 下都触发
- Runtime ref-counting — acquire/release 引用计数,归零回收(可配 idleTtlMs 延迟)
- 显示拓扑由 SessionTree 直接维护 — fork 默认挂在 source 节点下(engine 用
options.topologyParentId ?? this.session.id 兜底)。orchestrator 不做显示拓扑
的路由改写;调用方可通过显式传入 topologyParentId 覆盖。
可注入的扩展点
| 注入点 | 说明 | 默认值 |
|---|
| Scheduler | 调度时机 | 手动触发 |
| EngineHookProvider | 开发者自定义 hook | 无 |
| SplitGuard | fork 前置校验 | 无限制 |
| RuntimeRecyclePolicy | 空闲回收策略 | 立即回收 |
Session 接入的两种方式
- 直接提供 runtime.resolver — 开发者自己适配 EngineRuntimeSession
- 提供 session.sessionResolver + consolidateFn — StelloAgent 自动适配 @stello-ai/session
方式 2 是 @stello-ai/session 的推荐接入路径。
核心设计决策
- StelloAgent 是门面,不是组装器 — 隐藏内部组件,只暴露操作方法
- 只有一种 config 形状 — 没有 legacy 兼容路径,减少认知负担
- hooks 是不可变的开发期配置 — 构造时注入,运行期间不可修改
- Server 承接 StelloAgent — 通过 attach/detach 管理连接态,通过 turn/stream 转发请求