​

统一运行时流式重构计划

​

目标

​

存在原因

• 当前行为分散在多个运行时特定的数据整形路径中。
• 格式化/合并的 bug 可能在一个路径中修复但在其他路径中仍然存在。
• 投递一致性、重复抑制和恢复语义更难以推理。

​

目标架构

1. 运行时适配器仅发出规范事件。
2. 共享流组装器合并并最终化文本/工具/状态事件。
3. 共享频道投射器一次性应用频道特定的分块/格式化。
4. 共享投递账本强制执行幂等发送/重放语义。
5. 出站频道适配器执行发送并记录投递检查点。

• turn_started
• text_delta
• block_final
• tool_started
• tool_finished
• status
• turn_completed
• turn_failed
• turn_cancelled

​

工作流

​

1）规范流式契约

• 在核心中定义严格的事件模式 + 验证。
• 添加适配器契约测试以保证每个运行时发出兼容事件。
• 尽早拒绝格式错误的运行时事件并提供结构化诊断信息。

​

2）共享流处理器

• 用一个处理器替换运行时特定的合并器/投射器逻辑。
• 处理器负责文本增量缓冲、空闲刷新、最大块拆分和完成刷新。
• 将 ACP/main/subagent 配置解析移入一个辅助函数以防止偏差。

​

3）共享频道投射

• 保持频道适配器简单：接受最终化的块并发送。
• 将 Discord 特定的分块特殊处理仅移至频道投射器。
• 在投射之前保持管道与频道无关。

​

4）投递账本 + 重放

• 添加每轮/每块投递 ID。
• 在物理发送前后记录检查点。
• 重启时，幂等地重放待处理的块并避免重复。

​

5）迁移和切换

• 第一阶段：影子模式（新管道计算输出但旧路径发送；进行比较）。
• 第二阶段：按运行时逐个切换（acp，然后 subagent，然后 main，或按风险反序）。
• 第三阶段：删除旧版运行时特定流式代码。

​

非目标

• 此重构中不更改 ACP 策略/权限模型。
• 除投射兼容性修复外，不进行频道特定功能扩展。
• 不重新设计传输/后端（acpx 插件契约保持不变，除非事件对等需要）。

​

风险和缓解措施

• 风险：现有 main/subagent 路径的行为回归。 缓解：影子模式差异比较 + 适配器契约测试 + 频道端到端测试。
• 风险：崩溃恢复期间的重复发送。 缓解：持久化投递 ID + 投递适配器中的幂等重放。
• 风险：运行时适配器再次出现偏差。 缓解：所有适配器必须通过共享契约测试套件。

​

验收标准

• 所有运行时通过共享流式契约测试。
• Discord ACP/main/subagent 在微小增量时产生等效的间距/分块行为。
• 崩溃/重启重放不会对相同的投递 ID 发送重复块。
• 旧版 ACP 投射器/合并器路径已移除。
• 流式配置解析是共享的且与运行时无关。