xiaoxixi 55da3204f8 feat: coordinate live turn delivery

2026-07-17 15:56:52 +08:00

28 KiB

Raw Blame History

流式 Turn、Reasoning 展示与 Channel 投递设计

状态：拟议设计，尚未实现。

本文定义 PicoBot 未来的流式模型输出、reasoning 展示、工具过程展示和 Channel 实时投递架构。当前运行时行为仍以 docs/ARCHITECTURE.md 和代码为准。实施本设计时允许重做内部、WebSocket、TUI、WebUI 和 Channel 协议；只要求 SQLite 数据库提供可靠迁移路径。

1. 背景

当前 Provider 只提供一次性 chat() 调用。AgentLoop 等待完整响应，将 content、reasoning_content 和 tool calls 组装为 ChatMessage，Session 在 AgentLoop 完成后原子持久化本轮消息，再通过 OutboundMessage 发送最终正文。

这个模型具有清晰的持久化语义，但无法表达：

正文和 reasoning 的实时增量；
reasoning、正文、工具调用在一个 Turn 中的自然交错；
TUI 和 WebUI 对同一个运行中 Turn 的一致展示；
飞书等 Channel 通过编辑消息呈现流式效果；
不支持编辑的 Channel 自动降级为只发送最终结果；
取消、失败、慢消费者和投递失败时的确定行为。

现有 Channel::send_delta(chat_id, delta) 没有 Turn 身份、消息身份、reasoning/text 分类、工具边界、终态和取消语义，也绕过现有出站排序机制，不适合作为后续架构基础。

2. 参考实现结论

本设计综合了 reference/ryvos、reference/zeroclaw、reference/hermes-agent 和 PicoBot 当前实现。

2.1 Ryvos

Ryvos 把 thinking 作为正式内容块，并区分 TextDelta 与 ThinkingDelta。它说明 Provider 层必须结构化解析 reasoning、正文和工具调用，不能依赖最终字符串中的 <think> 后处理。

可吸收：

Provider 流的类型化增量；
reasoning 与正文分离；
工具参数增量组装；
thinking-only 响应的明确处理；
reasoning effort/thinking budget 的统一配置概念。

2.2 ZeroClaw

ZeroClaw 把 reasoning 作为不透明 Provider 数据保留，用于要求历史回放的模型，同时处理 reasoning_content、reasoning、内联 <think> 和不同 Provider 的回放限制。

可吸收：

可展示 reasoning 与 Provider 回放状态分离；
reasoning 字段别名归一化；
Provider 专用历史状态不能跨 Provider 发送；
内联 think block 必须在 Provider 归一化边界处理；
reasoning 是否展示与是否回放是两个独立策略。

2.3 Hermes

Hermes 新增了 Agent 到 Gateway 的结构化展示事件，并明确规定流事件属于 presentation，而不是 conversation history。它还通过 message segment boundary 处理“工具前正文 → 工具 → 工具后正文”。

可吸收：

流事件描述发生的事实，不携带平台发送策略；
展示流与持久化历史严格分离；
工具边界必须结束当前正文 segment；
高频更新需要合并，关键事件发送前需要 flush；
TUI 的活动 Turn 与已完成 transcript 分离；
Channel/平台决定如何呈现统一状态。

不直接复制：

typed events、旧 callbacks 和 TUI 字符串事件并存；
reasoning 使用独立 callback，没有进入新事件模型；
客户端用大型 TurnController 重建服务端状态；
一个 GatewayStreamConsumer 同时承担聚合、限流、平台编辑、think 清理、overflow 和 fallback。

2.4 PicoBot

PicoBot 已有以下适合保留的不变量：

同一 Session 由单 worker 串行处理；
不同 Session 并发；
worker_generation 和 state_version 防止迟到结果提交；
完整 Agent Turn 通过原子持久化接口提交；
普通出站消息按 (channel, chat_id) 有序投递；
Channel、Session、Agent、Provider 和 Storage 边界明确。

流式设计不能破坏这些不变量。

3. 设计目标

OpenAI-compatible 和 Anthropic Provider 支持流式正文、reasoning、tool calls 和 usage。
TUI 与 WebUI 使用同一运行态模型显示正文、reasoning、工具进度和取消/失败状态。
Channel 可以选择实时更新或只发送最终结果。
支持消息编辑的 Channel 能以同一远端消息呈现流式效果。
慢客户端或慢 Channel 不得反压 Provider 和 AgentLoop，也不得积压大量过时 token。
丢失任意中间更新后，下一次更新必须自动收敛到正确状态。
Completed 必须表示本轮数据库提交已经成功。
reasoning 展示文本与 Provider 回放状态必须隔离。
Channel 展示差异不能改变模型上下文和数据库历史。
保持模块数量、事件词汇和状态 owner 尽可能少。

4. 非目标

不保留旧 WebSocket、TUI、WebUI 或 Channel 流式协议兼容性。
不要求每个 Provider 都能返回可展示 reasoning。
不把 Provider 的加密/签名 reasoning payload 展示给用户。
不逐 token 持久化数据库。
不保证重连后恢复尚未完成 Turn 的每一个历史帧。
不让所有外部 Channel 默认以多条追加消息模拟流式效果。
不把流式展示事件作为可重放的事件溯源日志。

5. 核心决策

5.1 只有两个权威模型

系统只维护两个跨层权威模型：

ConversationMessage：最终持久化事实，用于会话历史和下轮模型上下文；
TurnState：单次运行的临时展示状态。

Provider 的 SSE chunk 是 Provider 内部输入；Channel 的远端消息 ID 是单个 TurnSink 的私有投递状态。两者都不是全局领域模型。

5.2 服务端拥有唯一运行态

Session 侧 TurnController 是运行中 Turn 的唯一状态 owner。TUI、WebUI 和 Channel 不根据一串增量自行重建 reasoning、正文、工具和 segment 关系，只渲染服务端发布的 TurnSnapshot。

5.3 下发幂等快照，不下发可靠 token 流

Provider 到 AgentLoop 使用 delta；TurnController 到展示端使用包含完整当前状态的快照。

每个快照带单调递增 revision。消费者只接受 revision 更大的快照，并以新快照整体替换旧状态。因此：

丢失中间更新不会损坏内容；
慢消费者可以跳过过时状态；
更新重试不会重复拼接正文；
最终快照能修复暂态渲染；
外部 Channel 编辑消息天然获得完整累计内容。

5.4 latest-wins，而不是 token 队列

每个活动 Turn 使用 Tokio watch 或等价 latest-value primitive 发布 Arc<TurnSnapshot>。生产者覆盖旧值，消费者读取最新值。终态显式编码在快照中，不能仅依赖 sender 关闭表达完成。

5.5 每个 Channel Turn 使用独立 TurnSink

Channel 为每次 Turn 创建一个 sink。Sink 独占远端消息 ID、编辑状态和平台私有资源，终态后销毁。通用协调器不保存平台消息映射，也不理解飞书卡片 API。

5.6 完整消息投递与活动 Turn 展示分离

MessageBus / OutboundDispatcher：完整消息、通知、命令结果和需要可靠确认的独立投递；
DeliveryCoordinator：活动 Turn 快照、展示策略、节流和 TurnSink 生命周期。

不把 token 或快照塞入现有 outbound MPSC。

6. 数据模型

6.1 Provider 私有流

pub enum ProviderChunk {
    Text(String),
    Reasoning(String),
    ToolCallStart {
        index: usize,
        id: Option<String>,
        name: Option<String>,
    },
    ToolCallArguments {
        index: usize,
        delta: String,
    },
    ProviderState(ProviderReasoningState),
    Usage(Usage),
    Done(FinishReason),
}

ProviderChunk 只允许在 providers 与 agent 模块间使用，不进入 Bus、Session 协议或 Channel。

6.2 可展示 reasoning 与回放状态

pub struct ProviderReasoningState {
    pub provider: String,
    pub payload: serde_json::Value,
}

pub struct AssistantMessageData {
    pub content: String,
    pub reasoning: Option<String>,
    pub provider_state: Option<ProviderReasoningState>,
    pub tool_calls: Vec<ToolCall>,
}

约束：

reasoning 可以按展示策略下发；
provider_state 永远不下发给客户端或 Channel；
provider_state.provider 与当前 Provider 不一致时禁止回放；
压缩历史时默认不把原始 reasoning 写入 Timeline；
日志不得记录完整 reasoning 或 provider payload。

6.3 Turn 标识

pub struct TurnId(pub uuid::Uuid);
pub struct BlockId(pub uuid::Uuid);

一次用户输入对应一个 Turn。Turn 开始时预分配最终 assistant message_id，使运行态和最终历史能稳定关联。

6.4 TurnState

pub struct TurnState {
    pub id: TurnId,
    pub session_id: String,
    pub message_id: String,
    pub revision: u64,
    pub status: TurnStatus,
    pub phase: TurnPhase,
    pub blocks: Vec<TurnBlock>,
    pub usage: Option<Usage>,
    pub error: Option<String>,
}

pub enum TurnStatus {
    Running,
    Completed,
    Cancelled,
    Failed,
}

pub enum TurnPhase {
    Queued,
    Reasoning,
    Responding,
    Acting,
    Finalizing,
}

TurnPhase 是展示状态，不等于模型 reasoning：

等待首个模型 chunk 时可显示 Queued；
收到 reasoning delta 时进入 Reasoning；
收到正文 delta 时进入 Responding；
执行工具时进入 Acting；
模型结束、等待持久化时进入 Finalizing。

6.5 有序 TurnBlock

pub enum TurnBlock {
    Reasoning {
        id: BlockId,
        iteration: u32,
        text: String,
    },
    Assistant {
        id: BlockId,
        iteration: u32,
        text: String,
    },
    Tool {
        id: String,
        iteration: u32,
        name: String,
        arguments: serde_json::Value,
        status: ToolStatus,
        preview: Option<String>,
    },
}

pub enum ToolStatus {
    Running,
    Completed,
    Failed,
}

有序 block 直接表达 reasoning、正文和工具的交错，不再维护多个平行字符串或让客户端猜测工具边界。

6.6 Agent 语义事件

pub enum TurnEvent {
    ReasoningDelta {
        iteration: u32,
        delta: String,
    },
    TextDelta {
        iteration: u32,
        delta: String,
    },
    TextSegmentFinished {
        iteration: u32,
    },
    ToolStarted {
        iteration: u32,
        call: ToolCall,
    },
    ToolFinished {
        iteration: u32,
        call_id: String,
        success: bool,
        preview: Option<String>,
    },
}

AgentLoop 只发过程事实。Turn 的 start、finalize、complete、cancel 和 fail 由 Session worker 调用 TurnController，因为 Session 才拥有生命周期、持久化和 stale-state 判断。

7. Provider 层

7.1 流式优先接口

#[async_trait]
pub trait LLMProvider: Send + Sync {
    async fn stream(
        &self,
        request: ChatCompletionRequest,
    ) -> Result<ProviderStream, ProviderError>;
}

标题生成、压缩等需要完整响应的代码通过 collect_provider_stream() 收集同一实现，避免分别维护 stream 和 non-stream HTTP 路径。

7.2 OpenAI-compatible

至少处理：

delta.content；
delta.reasoning_content；
delta.reasoning；
同一 payload 同时出现 content 与 reasoning；
tool call id/name/arguments 分片；
usage-only final chunk；
reasoning-only 响应；
内联 think tag 被任意 SSE chunk 切分。

<think>、<reasoning> 等内联标签使用有状态 parser 在 Provider 归一化边界转换为 ProviderChunk::Reasoning，不能在 Channel 或客户端重复清理。

7.3 Anthropic

至少处理：

text content block；
thinking/redacted thinking block；
signature 或其他回放元数据；
tool_use block 和 input JSON delta；
content block start/delta/stop；
message usage 和 stop reason。

thinking 文本进入 reasoning，签名和原始 block 进入 provider_state。历史回放必须保持 Provider 要求的块顺序和签名完整性。

7.4 reasoning-only

Provider 不擅自把 reasoning 提升为正文。AgentLoop 在最终轮发现只有 reasoning、没有正文且没有工具调用时，执行统一产品策略：

默认生成一个明确的空正文终态，并在 UI 保留 reasoning；或
后续配置允许把 reasoning 作为正文 fallback。

首版建议不泄漏 reasoning 为正文，由 UI 显示“模型未返回最终正文”。

8. AgentLoop 与 TurnController

8.1 AgentLoop

AgentLoop 消费 ProviderChunk 并：

累积本轮完整 AssistantMessageData；
将展示事实发给 TurnEmitter；
组装 tool calls；
Provider 完成当前迭代后执行工具；
在工具开始前发出 TextSegmentFinished；
将完整 assistant/tool messages 加入内部历史；
返回最终 AgentProcessResult。

AgentLoop 不访问 MessageBus、DeliveryCoordinator 或 Channel。

8.2 TurnController

TurnController：

是 TurnState 的唯一写入者；
把 TurnEvent reduce 为有序 blocks；
维护 revision、status 和 phase；
发布最新 TurnSnapshot；
不执行 Provider、工具、数据库或 Channel I/O。

推荐接口：

impl TurnController {
    pub fn start(... ) -> (Self, TurnEmitter, watch::Receiver<Arc<TurnSnapshot>>);
    pub fn begin_finalizing(&mut self);
    pub fn complete(&mut self, usage: Option<Usage>);
    pub fn cancel(&mut self, reason: Option<String>);
    pub fn fail(&mut self, error: String);
}

TurnEmitter 应轻量、无 Channel 感知，并在 Turn 终止后拒绝新事件。

8.3 stale-state

Session worker 在以下位置校验 worker_generation 和必要的 state_version：

创建 Turn 后、调用 Provider 前；
发布会产生用户可见变化的快照前；
工具批次完成后；
最终数据库提交前；
发布 Completed 前。

旧 generation 的 Turn 必须进入 Cancelled 或静默终止，禁止继续编辑 Channel 远端消息。

9. DeliveryCoordinator

DeliveryCoordinator 是活动 Turn 的唯一展示协调器，职责包括：

订阅 watch::Receiver<TurnSnapshot>；
解析当前目标的 PresentationPolicy；
在下发前移除隐藏的 reasoning/tool blocks；
根据 Channel LivePolicy 节流；
为 Turn 创建并持有 TurnSink；
对 Running 快照进行 best-effort 更新；
对终态快照立即 flush；
有界等待 sink 结束；
报告最终投递结果。

9.1 合并和背压

watch 自动覆盖过时快照；
WebSocket/cli_chat 建议最多约 30 FPS；
飞书建议从 500ms 更新间隔开始；
正在滚动或渲染压力高时，客户端无需向服务端反馈节流，丢弃中间快照即可；
终态不等待节流 timer，必须立即发送；
Running 更新失败不重试旧快照，等待下一最新快照；
Completed 最终投递使用正常可靠重试语义。

9.2 与 OutboundDispatcher 的关系

DeliveryCoordinator 不取代 OutboundDispatcher。

组件	负责
OutboundDispatcher	完整独立消息、通知、命令结果、定时投递、可靠重试
DeliveryCoordinator	活动 Turn 的运行快照、节流、展示过滤和 sink 生命周期

两者对同一 (channel, chat_id) 的最终写操作必须有统一排序边界。实现时可以复用 per-conversation lane owner，但不能把所有快照排进 lane 的普通 MPSC；lane 应只持有 TurnSink 任务或 latest snapshot receiver。

10. Channel 与 TurnSink

10.1 接口

删除 Channel::send_delta，保留普通 send，增加：

pub enum LivePolicy {
    FinalOnly,
    Snapshot {
        min_interval: Duration,
    },
}

#[async_trait]
pub trait Channel: Send + Sync + 'static {
    fn live_policy(&self) -> LivePolicy;

    async fn open_turn(
        &self,
        target: TurnTarget,
    ) -> Result<Box<dyn TurnSink>, ChannelError>;

    async fn send(&self, msg: OutboundMessage) -> Result<(), ChannelError>;
}

#[async_trait]
pub trait TurnSink: Send {
    async fn update(&mut self, snapshot: &TurnSnapshot) -> Result<(), ChannelError>;
    async fn finish(&mut self, snapshot: &TurnSnapshot) -> Result<(), ChannelError>;
    async fn abort(&mut self, snapshot: &TurnSnapshot) -> Result<(), ChannelError>;
}

TurnSink 的每个调用都接收完整、过滤后的快照。Sink 不拼接 token。终态方法保留 &mut self，使协调器可以在瞬态错误或超时后重试同一个、仍持有远端消息 ID 的 sink；终态成功或重试耗尽后由协调器销毁 sink。

10.2 cli_chat

LivePolicy::Snapshot，默认约 33ms；
update/finish/abort 都发送统一 turn_updated frame；
WebUI 与 TUI 使用完全相同的 TurnSnapshot；
Session 不匹配时客户端忽略渲染，但可标记未读；
终态后客户端可请求历史作最终校准。

10.3 飞书

配置关闭实时展示时使用 FinalOnly sink；
开启时使用 Snapshot sink；
第一个有可见内容的 Running 快照创建卡片；
后续快照编辑同一卡片；
sink 内持有远端 message ID；
reasoning/tool block 由 PresentationPolicy 决定是否进入卡片；
中间编辑失败不影响 Agent；
finish 做最终编辑，必要时退化为发送一条完整最终消息；
卡片长度限制、拆分和平台限流属于 FeishuTurnSink 私有实现。

10.4 不支持编辑的 Channel

实现 FinalOnlyTurnSink：忽略 Running 快照，只在 finish 时发送最终投影。默认不通过多条追加消息模拟流式，以免产生无法收回的碎片消息。

11. 展示策略

pub struct PresentationPolicy {
    pub live: bool,
    pub reasoning: ReasoningVisibility,
    pub tools: ToolVisibility,
}

pub enum ReasoningVisibility {
    Hidden,
    Collapsed,
    Expanded,
}

pub enum ToolVisibility {
    Hidden,
    Compact,
    Detailed,
}

建议默认值：

TUI/WebUI：live=true，reasoning=Collapsed，tools=Detailed；
外部 Channel：live 由 Channel 配置决定，reasoning=Hidden，tools=Compact；
Scheduler/无人值守投递：FinalOnly，reasoning=Hidden。

策略由 DeliveryCoordinator 在数据离开 Gateway 核心前应用。Channel 和客户端不能只靠“隐藏 UI”实现 reasoning 保密。

12. TUI 与 WebUI

客户端状态简化为：

history     已持久化消息
active_turn 当前 TurnSnapshot（每个 session 最多一个）

收到快照时：

if snapshot.revision > active_turn.revision:
    active_turn = snapshot

渲染规则：

Reasoning block 显示为折叠或展开区域；
Assistant block 显示为正文 segment；
Tool block 显示运行中/成功/失败状态；
phase 控制 spinner 文案；
Completed/Cancelled/Failed 显示明确终态；
当前 session 之外的快照不进入当前消息列表；
Completed 后以历史响应替换 active turn，避免展示态与数据库态长期并存。

WebUI 对 Running Markdown 可以按动画帧或快照频率渲染，Completed 时进行最终 sanitize。TUI 原地重绘 active turn，不把每个更新追加为新 transcript 行，也不在用户向上滚动时强制跳到底部。

13. WebSocket 协议

不保留旧 assistant_response 流程。活动 Turn 使用一个统一 frame：

{
  "type": "turn_updated",
  "turn": {
    "id": "...",
    "session_id": "...",
    "message_id": "...",
    "revision": 12,
    "status": "running",
    "phase": "responding",
    "blocks": []
  }
}

Completed、Cancelled 和 Failed 仍使用 turn_updated，只改变完整快照的 status。避免为每个生命周期阶段增加一组容易漂移的 frame 类型。

历史协议应返回持久化后的 reasoning、completion_status、turn_id 和 iteration，但不返回 provider_state。

14. 持久化和提交顺序

流式过程中不逐 token 写 SQLite。完成顺序固定为：

Provider 完成
  → AgentLoop 组装 emitted_messages
  → Session 校验 generation/state_version
  → 原子写入本轮全部消息
  → TurnController.complete()
  → 发布 Completed 快照
  → TurnSink.finish()

因此 TurnStatus::Completed 的含义是：数据库已经提交成功，最终展示可以安全收敛到历史。

14.1 取消

建议首版语义：

没有 Assistant 正文：不持久化 assistant 消息，Turn 标记 Cancelled；
已向用户展示部分正文：持久化部分正文并标记 completion_status=cancelled；
已完成的 assistant/tool/tool-result 链必须保持 Provider 可接受的结构；
reasoning 可随取消消息保存，但展示仍受 policy 控制；
取消后 TurnEmitter 关闭，迟到 delta 被丢弃。

14.2 失败

Provider 在任何可见正文前失败：Turn Failed，错误作为结构化 error 展示，不创建 assistant 历史；
已产生部分正文后失败：按 interrupted partial 保存，标记 completion_status=interrupted；
持久化失败：不得发布 Completed，Turn Failed，并明确告知用户流式预览未保存；
Running Channel 更新失败不改变 Turn 结果；最终 finish 失败按现有投递错误处理。

15. SQLite 迁移

建议为 messages 增加：

turn_id             TEXT NULL
iteration           INTEGER NULL
completion_status   TEXT NOT NULL DEFAULT 'completed'
reasoning_content   TEXT NULL          -- 已存在，语义调整为可展示 reasoning
provider_state      TEXT NULL          -- JSON，Provider 私有回放状态

要求：

新库 schema 测试；
旧库迁移测试；
已有 reasoning_content 数据原样保留；
provider_state 解析失败时降级为不回放，不能使历史不可读；
Session 加载继续修复 tool-call chains；
原子提交覆盖完整 Turn 的所有 emitted messages。

是否新增 turns 表首版暂不需要。运行中 Turn 只存在内存，历史可通过 messages.turn_id 分组。如果未来要跨 Gateway 重启恢复运行态，再单独设计 durable turn lease/state。

16. 生命周期与并发不变量

每个 Session 最多一个活动主 Turn。
TurnController 是 TurnState 的唯一写入者。
AgentLoop、DeliveryCoordinator 和 TurnSink 不持有 Session mutex 执行慢 I/O。
worker_generation 变化后，旧 Turn 不得发布新快照或提交消息。
Running 快照是 best-effort；终态快照必须显式、完整且有界投递。
慢 sink 只能跳过中间状态，不能阻塞 Provider 或 AgentLoop。
Completed 必须晚于数据库成功提交。
TurnSink 的生命周期由 DeliveryCoordinator 所有，并通过 TaskSupervisor 回收。
Provider stream、节流 timer、Channel 编辑、取消和 shutdown 都必须有硬时间界限。
presentation 过滤不能修改 ConversationMessage 或 Agent 历史。

17. 模块布局

src/providers/stream.rs
    ProviderChunk、ProviderStream、FinishReason、collect helper

src/agent/turn_event.rs
    TurnEvent、TurnEmitter

src/session/turn.rs
    TurnState、TurnBlock、TurnController、TurnSnapshot

src/delivery/mod.rs
src/delivery/coordinator.rs
src/delivery/policy.rs
    watch 订阅、展示过滤、节流、sink 生命周期

src/channels/base.rs
    Channel、LivePolicy、TurnSink

src/channels/cli_chat.rs
    WebSocketTurnSink

src/channels/feishu.rs
    FeishuTurnSink

src/protocol.rs
    TurnSnapshot 序列化

observability 继续记录 Agent/tool 遥测，不承担 UI stream。MessageBus 不新增 token/turn 队列。

18. 明确拒绝的替代方案

18.1 每 token 一个 OutboundMessage

拒绝原因：填满 bounded bus/lane、重试乱序、慢 Channel 反压 Agent、最终消息和暂态更新语义混淆。

18.2 端到端 delta 协议

拒绝原因：客户端和每个 Channel 都必须实现累积、去重、segment、取消和丢帧恢复状态机，最终产生多个事实 owner。

18.3 客户端自行组合 reasoning/tool/text

拒绝原因：TUI、WebUI 和 Channel 行为会漂移；重连和切 session 时难以恢复；服务端已经拥有全部事实。

18.4 把流式事件写入数据库

拒绝原因：消息历史膨胀，事务语义复杂，压缩和 Provider 回放被展示细节污染。

18.5 在 Channel 全局保存 turn_id 映射

拒绝原因：owner 和清理边界不清晰。每 Turn 一个 sink 可以让远端消息状态自然随生命周期释放。

18.6 一个巨型跨平台 StreamConsumer

拒绝原因：通用合并/策略与平台 API 细节耦合。DeliveryCoordinator 只做统一调度，具体远端编辑由各 TurnSink 自己实现。

19. 验证策略

19.1 Provider

SSE 任意字节和 UTF-8 边界切分；
reasoning/content 同时出现；
reasoning 与 content 字段别名；
think tag 跨 chunk；
多 tool calls 交错参数 delta；
usage-only chunk；
Anthropic thinking signature round-trip；
中途断线、超时和取消。

19.2 TurnController

reasoning → text → tool → reasoning → text 的 block 顺序；
segment boundary；
parallel tool status；
revision 严格递增；
终态后拒绝新事件；
reasoning-only、empty response、取消和失败。

建议用 property tests 验证：任意合法 TurnEvent 序列 reduce 后不产生相邻可合并同类 block、重复 tool id 或终态后变更。

19.3 DeliveryCoordinator

慢 sink 只收到最新快照；
终态绕过节流；
hidden reasoning 在到达 sink 前已经移除；
Running 更新失败后能由下一快照恢复；
finish 可靠重试；
shutdown 有界；
stale generation 停止更新。

19.4 客户端和 Channel

WebUI/TUI revision 去重；
session 切换不显示迟到 Turn；
Completed 后历史校准；
Markdown 未完成块与最终块；
飞书 create/edit/final fallback；
FinalOnly sink 不发送中间内容；
远端长度限制与节流。

19.5 Storage

新库 schema；
旧 schema 迁移；
provider_state 损坏降级；
cancelled/interrupted 消息恢复；
完整 Turn 原子提交失败不产生部分历史。

20. 实施顺序

增加数据库迁移和新的消息 reasoning/provider state 语义。
引入 ProviderChunk 和流式优先 Provider trait。
实现 OpenAI-compatible streaming 和 collect helper。
实现 TurnEvent、TurnController、TurnSnapshot 及纯单元测试。
AgentLoop 接入 TurnEmitter，但暂时只使用最终结果投递。
增加 DeliveryCoordinator、LivePolicy 和 TurnSink。
重做 cli_chat WebSocket 为统一 turn_updated 快照。
重做 TUI/WebUI 为 history + active_turn 渲染模型。
实现 Anthropic streaming 和完整 provider_state 回放。
实现 FeishuTurnSink 的创建、编辑、终态和 fallback。
删除旧 send_delta、旧 reasoning 特例和 Channel 侧 think 清理。
更新 ARCHITECTURE.md、README、AGENTS.md 和运行时产品知识。

每一步都必须保持非流式最终回复可用；但不为旧协议保留双栈兼容代码。

21. 实施前需确认的产品策略

这些选择不改变架构，但必须在实现前确定默认值：

/stop 后是否持久化已展示的部分正文。本文建议持久化并标记 cancelled。
TUI/WebUI reasoning 默认折叠还是隐藏。本文建议折叠。
外部 Channel reasoning 默认策略。本文建议隐藏。
reasoning-only 是否允许提升为正文。本文建议不提升。
provider_state 的保留期限和 LLM 原始响应审计策略。

22. 架构验收标准

设计完成实现后，应能用以下陈述准确描述系统：

Provider 只负责模型协议，AgentLoop 只负责模型/工具语义。
Session 拥有 Turn 生命周期和最终持久化。
TurnController 是运行态的唯一事实来源。
DeliveryCoordinator 只投影展示，不修改历史。
每个 Channel Turn 的远端状态只存在于一个 TurnSink。
客户端只渲染服务端快照，不重建领域状态。
中间快照可以丢，最终状态一定可收敛。
reasoning 展示、reasoning 回放和“系统正在工作”是三个不同概念。
Completed 永远意味着数据库已经提交成功。

28 KiB Raw Blame History Unescape Escape

流式 Turn、Reasoning 展示与 Channel 投递设计

1. 背景

2. 参考实现结论

2.1 Ryvos

2.2 ZeroClaw

2.3 Hermes

2.4 PicoBot

3. 设计目标

4. 非目标

5. 核心决策

5.1 只有两个权威模型

5.2 服务端拥有唯一运行态

5.3 下发幂等快照，不下发可靠 token 流

5.4 latest-wins，而不是 token 队列

5.5 每个 Channel Turn 使用独立 TurnSink

5.6 完整消息投递与活动 Turn 展示分离

6. 数据模型

6.1 Provider 私有流

6.2 可展示 reasoning 与回放状态

6.3 Turn 标识

6.4 TurnState

6.5 有序 TurnBlock

6.6 Agent 语义事件

7. Provider 层

7.1 流式优先接口

7.2 OpenAI-compatible

7.3 Anthropic

7.4 reasoning-only

8. AgentLoop 与 TurnController

8.1 AgentLoop

8.2 TurnController

8.3 stale-state

9. DeliveryCoordinator

9.1 合并和背压

9.2 与 OutboundDispatcher 的关系

10. Channel 与 TurnSink

10.1 接口

10.2 cli_chat

10.3 飞书

10.4 不支持编辑的 Channel

11. 展示策略

12. TUI 与 WebUI

13. WebSocket 协议

14. 持久化和提交顺序

14.1 取消

14.2 失败

15. SQLite 迁移

16. 生命周期与并发不变量

17. 模块布局

18. 明确拒绝的替代方案

18.1 每 token 一个 OutboundMessage

18.2 端到端 delta 协议

18.3 客户端自行组合 reasoning/tool/text

18.4 把流式事件写入数据库

18.5 在 Channel 全局保存 turn_id 映射

18.6 一个巨型跨平台 StreamConsumer

19. 验证策略

19.1 Provider

19.2 TurnController

19.3 DeliveryCoordinator

19.4 客户端和 Channel

19.5 Storage

20. 实施顺序

21. 实施前需确认的产品策略

22. 架构验收标准

28 KiB

Raw Blame History