agently-stage

Agently Stage

Agently 4.1.4.7+ 需要 agently-stage>=0.3.8,<0.4.0。请使用 Stage 处理进程本地生命周期、调用形态桥接、重放通道和本地监听器分发。这些 API 各自独立可用，同时 Agently 也将 Stage 用作私有运行时机制。

按需阅读

• Stage 作用域/后端选择、StageHandle、结算、取消、调用方循环任务所有权、压力、空闲超时和快照： task-lifecycle.md。
• Stage.as_sync/as_async、StageCallBridge、StageStream、Tunnel、 EventEmitter 和兼容名称： bridges-streams-events.md。
• TriggerFlow 状态/信号、工作流关闭、恢复或应用编排：使用 agently-triggerflow。
• Actions、ExecutionResources、TaskWorkspace、RecordStore、服务或 DevTools：使用 agently-runtime。

边界

选择与调用方匹配的最小接口面：

• 当调用方和工作已具有相同形态时，直接调用/await。
• 需要显式异步生命周期时使用 async with Stage()；需要有意设置阻塞边界时使用 with Stage()。
• 单个标量适配器使用 Stage.as_sync/as_async。
• 需要在循环或线程之间读取已提交结果时使用 Stage.go(...) 加 StageHandle。
• 对于 Stage 创建的调用方循环工作，使用 Stage.create_task(...)；adopt(...) 仅用于已存在的任务。
• 注入生命周期、托管阻塞取消或迭代器转换时使用 StageCallBridge；生成器重放使用 StageStream。
• 可独立写入的进程本地重放通道使用 Tunnel，进程本地监听器使用 EventEmitter。

同步外观会阻塞其调用线程。不要桥接已经具有正确原生形态的调用。

不变量

• 主体完成和结算 是不同的事实。使用 get()/async_get() 读取主体，并在其完成很重要时使用 wait_settled()/async_wait_settled() 等待保留的后代/终结器。
• 绝不要阻塞工作所需的调用方拥有的循环。当 Stage 报告生命周期冲突时，使用匹配的异步屏障。
• 取消后，先等待结算，再声称不会发生后续 Stage 拥有的工作。Stage 无法抢占不合作的阻塞函数，也无法撤销外部副作用。
• 将并发、待处理、工作线程和空闲限制放在其实际压力边界。载体循环数量不是应用准入控制。
• 自动 Stage 作用域即使安全复用载体，也仍保持独立。

Stage 不拥有工作流推进、业务重试、持久化、授权、提供方取消确认或外部副作用。TriggerFlowExecution 仍是 Agently 的公共工作流生命周期所有者；Stage 对象和载体状态不得进入执行快照。

LocalTaskScope 和历史 Stage 分发/函数类型名称属于 0.3 兼容接口面。不要将它们作为新的所有者层来教授。