refactor: 0.1.0-beta

2026-08-18 03:57:06 +08:00 · 2026-08-13 22:01:11 +08:00
parent a3ec2a0dfc
commit 3e7a15017d
401 changed files with 8696 additions and 182189 deletions
@@ -0,0 +1,889 @@
+# Loop + Dialect 完整落地方案
+
+## 1. 设计目标
+
+这是一个从零设计的服务端方案，不依赖当前项目的服务端实现。
+
+目标只有四个：
+
+1. Loop 的状态决策是纯函数，外层运行器用递归驱动它，直到得到最终答案。
+2. LLM 使用原生请求和原生流事件，不再造一套平行的模型消息结构。
+3. Cursor 的 Bidi、RunSSE、protobuf 只存在于 Dialect 和 Transport 中。
+4. `messages` 永远是完整、顺序固定、只追加的历史，保证前缀缓存稳定。
+
+模型调用是无状态的。每一次调用都发送完整的 `RequestMessages`，而不是向模型发送“上一次请求的差异”。
+
+## 2. 顶层结构
+
+代码目录只保留四个模块：
+
+```text
+server/
+  loop/        纯函数状态转换、消息历史和下一步决定
+  llm/         原生请求、原生响应流、供应商适配器
+  transport/   Connect、Bidi、RunSSE、CursorDialect、运行器
+  store/       SQLite 状态、调用记录、输入和工具去重
+```
+
+`CursorDialect` 是 `transport/` 里的协议翻译文件，不单独形成目录。客户端是远端能力：服务端向它发工具请求，它经 Bidi 返回工具结果；因此也不在服务端拆出 `client/` 模块。
+
+`store/` 只是基础设施适配器：它保存状态和提交记录，不决定下一步动作。
+
+依赖方向固定为：
+
+```text
+transport -> loop
+transport -> llm
+transport -> store
+
+CursorDialect (inside transport) -> loop / llm
+```
+
+`transport/runner` 是很薄的组装代码：它执行 `Command`，把外部结果再送回 `loop`。`loop` 不依赖 protobuf、HTTP、SSE、连接对象、Store、客户端或具体 LLM 供应商。
+
+## 3. 三类核心数据
+
+### 3.1 模型请求
+
+直接使用 `internal/backend/cursor/llm/request.go` 中的结构：
+
+```text
+RequestMessages {
+  SystemPrompt
+  Messages []Message
+  Tools []ToolDefinition
+}
+```
+
+这里有一个重要边界：
+
+- `Messages` 是会话历史，必须只追加。
+- `SystemPrompt` 和 `Tools` 是本次请求构建出来的请求部分。
+- 前缀缓存约束只针对 `Messages`。
+- 不能通过合并、去重、重排或“修正上一条消息”来构建历史。
+
+每次请求的模型上下文都是：
+
+```text
+RequestMessages {
+  SystemPrompt: buildPrompt(input, state)
+  Messages:     state.messages
+  Tools:        buildTools(input, state)
+}
+```
+
+`buildPrompt` 和 `buildTools` 可以每次重新计算，但不能修改 `state.messages`。
+
+### 3.2 模型响应
+
+直接使用 `internal/backend/cursor/llm/response.go` 中的结构：
+
+```text
+ResponseEvent {
+  Start
+  TextStart / TextDelta / TextEnd
+  ThinkingStart / ThinkingDelta / ThinkingEnd
+  ToolCallStart / ToolCallDelta / ToolCallEnd
+  Done
+  Error
+}
+```
+
+完整响应使用 `AssistantMessage`。工具结果使用 `ToolResultMessage`。用户输入使用 `UserMessage`。
+
+`internal/backend/cursor/llm/stream.go` 中的接口是 LLM 边界：
+
+```text
+ResponseStream.Recv(context) -> (ResponseEvent, error)
+```
+
+LLM 适配器可以将 OpenAI、Anthropic、Gemini 或其他供应商的响应转换为这些原生中间结构，但不能把供应商私有的流格式泄漏到 Loop。
+
+### 3.3 Loop 输入
+
+Loop 只接收有语义的输入，不接收网络数据：
+
+```text
+Input =
+  Start {
+    userMessage: UserMessage
+    context:     []ContextSupplement
+  }
+| LLMEvent {
+    callID: string
+    event:  ResponseEvent
+  }
+| ToolResult {
+    message: ToolResultMessage
+  }
+| UserMessage {
+    message: UserMessage
+  }
+| Cancel {
+    reason: string
+  }
+```
+
+`BidiAppend` 解码后只能生成这些输入。Loop 不需要知道输入原来来自 Bidi、HTTP 还是测试代码。
+
+上下文补充如果要被模型看到，必须转换成新的消息追加到历史；不能回写旧消息：
+
+```text
+旧 messages + 新 UserMessage(context supplement)
+```
+
+## 4. 状态：已提交部分与正在生成部分
+
+运行中的状态分为两部分：
+
+```text
+RuntimeState {
+  committed       ConversationState
+  pendingResponse *PendingResponse
+}
+
+ConversationState {
+  conversationID
+  turnID
+  messages           []llm.Message
+  waiting           *WaitingClient
+  status             Ready | WaitingLLM | WaitingClient | Final | Failed | Canceled
+  lastCommitID       string
+}
+```
+
+### 4.1 `messages`
+
+`messages` 是唯一的模型历史：
+
+- 只能在完整的 `UserMessage`、`AssistantMessage` 或 `ToolResultMessage` 完成后追加。
+- 已经追加的消息永远不变。
+- 顺序永远按照发生顺序排列。
+- 不使用 map 作为模型消息容器。
+- 不在重放时重新生成时间戳、随机 ID 或不稳定字段。
+- 工具调用的签名、思考签名和供应商响应 ID 原样保留。
+
+### 4.2 `pendingResponse`
+
+`pendingResponse` 是本次 LLM 流的临时聚合器，不属于模型历史：
+
+```text
+PendingResponse {
+  callID
+  partialMessage
+  openContentBlocks
+  openToolCalls
+  usage
+}
+```
+
+它只接收流中的增量事件。只有 `Done` 才能把完整的 `AssistantMessage` 追加到 `messages`。
+
+`pendingResponse` 只存在于内存。每个 delta 都可以被实时发送给 RunSSE，也可以写入诊断日志，但不会被提交到 `ConversationState`。
+
+如果进程在 `Done` 前重启：
+
+```text
+丢弃 pendingResponse
+保留本次 callID、requestHash 和调用状态
+从最后一份已提交的 ConversationState 重试相同请求
+```
+
+不恢复半截文本，不把旧 delta 与新响应拼接，也不把旧 delta 当作模型消息。这样即使上游流不可续传，模型历史仍然一致。
+
+## 5. 纯函数转换接口
+
+Loop 的核心函数固定为：
+
+```text
+transition(state, input) -> Transition
+```
+
+返回值：
+
+```text
+Transition {
+  state
+  emit      []llm.ResponseEvent
+  command   Command
+}
+```
+
+`emit` 使用 LLM 原生 `ResponseEvent`，不创建 `AssistantTextDelta`、`ToolCallOutput` 等第二套事件。
+
+`Command` 只有几种：
+
+```text
+Command =
+  ContinueLLM
+| CallLLM {
+    callID
+    request RequestMessages
+    messagesHash string
+  }
+| CallClient {
+    operationID
+    toolCall ToolCall
+  }
+| WaitInput
+| Final {
+    message AssistantMessage
+  }
+| Failed {
+    message AssistantMessage
+  }
+| Canceled {
+    reason string
+  }
+```
+
+`Command` 是普通数据，不能携带闭包、连接、channel 或函数指针。这样它可以记录、重放和比较。
+
+## 6. Loop 的递归规则
+
+核心判断是纯函数：
+
+```text
+transition(runtimeState, input) -> Transition
+```
+
+它不执行 I/O，也不自行取得下一条输入。递归发生在外层运行器：
+
+```text
+run(state, input) {
+  result = transition(state, input)
+  publish(result.emit)
+  commitWhenNeeded(result)
+
+  if result.command is Final or Failed or Canceled or WaitInput {
+    return result
+  }
+
+  return runCommand(result.state, result.command)
+}
+```
+
+`run` 是递归入口，`transition` 是唯一的状态判断函数。网络和客户端调用不能放进纯函数，因此 `runCommand` 是外层执行器：
+
+```text
+runCommand(state, command) {
+  switch command {
+    case CallLLM:
+      return consumeLLM(state, command)
+
+    case CallClient:
+      sendClientCommand(command)
+      return { state, emit: [], command: WaitInput }
+
+    case WaitInput, Final, Failed, Canceled:
+      return { state, emit: [], command }
+
+    case ContinueLLM:
+      return invalidState("ContinueLLM without stream")
+  }
+}
+```
+
+`CallClient` 不能同步等待工具返回。它被编码为外层协议消息后，`runCommand` 立即结束本次调用；之后客户端通过 BidiAppend 提交 `ToolResultMessage`，Transport 再次调用 `run(loadedState, ToolResult)`。
+
+这里不是从旧调用栈继续等待。工具结果是一个新的外部输入，也是递归的下一层。
+
+实现时可以使用异步尾递归、trampoline 或任务调度器避免实际调用栈无限增长，但不能把业务逻辑改成一个可随意修改历史的可变状态循环。
+
+## 7. LLM 流的处理
+
+### 7.1 启动一次调用
+
+`CallLLM` 携带完整请求和请求快照信息：
+
+```text
+CallLLM {
+  callID
+  request
+  messagesHash
+}
+```
+
+`messagesHash` 是发送前按消息顺序对完整 `Messages` 序列做的稳定哈希，用来确认重试时没有改变历史。重试实际使用已保存的 `exactRequest`，不重新 build prompt、tools 或 messages。
+
+执行器：
+
+```text
+consumeLLM(state, command) {
+  stream = llm.call(command.request)
+  return readLLM(state, command.callID, stream)
+}
+```
+
+### 7.2 逐个接收事件
+
+```text
+readLLM(state, callID, stream) {
+  event = stream.Recv()
+  result = transition(state, LLMEvent(callID, event))
+  publish(result.emit)
+  commitWhenNeeded(result)
+
+  switch result.command {
+    case ContinueLLM:
+      return readLLM(result.state, callID, stream)
+
+    case CallClient, CallLLM, WaitInput, Final, Failed, Canceled:
+      return runCommand(result.state, result.command)
+  }
+}
+```
+
+上面的 `CallClient` 分支会发送一个客户端请求并返回 `WaitInput`；它不会占用 LLM 流或阻塞 HTTP handler。下一个 Bidi 输入是另一次 `run(loadedState, input)` 调用。
+
+### 7.3 各事件的状态变化
+
+```text
+Start
+  -> 创建 pendingResponse
+  -> 原样发布 ResponseEvent.Start
+
+TextStart / ThinkingStart / ToolCallStart
+  -> 打开对应内容块
+  -> 原样发布事件
+
+TextDelta / ThinkingDelta / ToolCallDelta
+  -> 追加到 pendingResponse
+  -> 原样发布事件
+
+TextEnd / ThinkingEnd / ToolCallEnd
+  -> 关闭对应内容块
+  -> 原样发布事件
+
+Done(stop)
+  -> 校验完整 AssistantMessage
+  -> 将它追加到 messages
+  -> 清空 pendingResponse
+  -> command = Final
+
+Done(toolUse)
+  -> 追加完整 AssistantMessage
+  -> 清空 pendingResponse
+  -> 取第一项未完成工具调用
+  -> command = CallClient
+
+Error / Aborted
+  -> 丢弃未完成 pendingResponse
+  -> 保存错误记录
+  -> 不把半截响应追加到 messages
+  -> command = Failed 或 Canceled
+```
+
+无论模型返回多少个 delta，`messages` 最终只追加一条完整的 `AssistantMessage`。
+
+`ResponseEvent.Partial` 是 LLM 适配器提供的当前累计视图。Loop 可以用它校验 `pendingResponse` 或供 RunSSE 重连时显示，但不能用它覆盖、修改或合并任何已提交的 `messages`。唯一允许提交到 `messages` 的助手响应来自 `ResponseEvent.Done.Message`。
+
+## 8. 外层流协议的对接
+
+外层协议分两层：
+
+```text
+Transport
+  负责连接、读写、framing、断开、heartbeat
+
+Dialect
+  负责 protobuf 消息与原生语义结构之间的翻译
+```
+
+Loop 只产生 `ResponseEvent` 和 `Command`，不直接写 RunSSE。
+
+### 8.1 输入方向
+
+```text
+BidiAppend request
+  -> Transport 解 Connect body
+  -> Dialect.decodeClientMessage
+  -> Input
+  -> transition(state, input)
+```
+
+`Dialect.decodeClientMessage` 的映射：
+
+```text
+run_request.user_message
+  -> Input.Start 或 Input.UserMessage
+
+exec_client_message.tool_result
+  -> Input.ToolResult
+
+interaction_response
+  -> Input.UserMessage 或对应 ClientInput
+
+conversation_action.cancel
+  -> Input.Cancel
+```
+
+Bidi 的 `request_id`、`append_seqno`、`conversation_id` 属于 Transport/Dialect 的关联信息，不进入模型消息文本。
+
+### 8.2 输出方向
+
+```text
+transition.emit: ResponseEvent
+  -> Dialect.encodeServerEvent
+  -> AgentServerMessage
+  -> RunSSE writer
+```
+
+推荐映射：
+
+```text
+ResponseEvent.Start
+  -> 不写协议消息；只初始化本次流的内部关联状态
+
+ResponseEvent.TextStart / ResponseEvent.TextEnd
+  -> 不写协议消息；Cursor 由 text_delta 表达可见文本
+
+ResponseEvent.TextDelta
+  -> interaction_update.text_delta
+
+ResponseEvent.ThinkingDelta
+  -> interaction_update.thinking_delta
+
+ResponseEvent.ThinkingEnd
+  -> interaction_update.thinking_completed
+
+ResponseEvent.ToolCallStart
+  -> interaction_update.tool_call_started
+
+ResponseEvent.ToolCallDelta
+  -> interaction_update.tool_call_delta
+
+ResponseEvent.ToolCallEnd
+  -> interaction_update.tool_call_completed
+
+Command.CallClient
+  -> exec_server_message
+
+ResponseEvent.Done(stop)
+  -> interaction_update.turn_ended
+  -> RunSSE end-stream
+
+ResponseEvent.Error
+  -> 协议错误消息或 RunSSE 结构化错误
+  -> RunSSE end-stream
+```
+
+这里的映射只是协议表达方式改变，事件的文本、工具调用 ID、工具名、参数、停止原因和响应 ID 都必须保留。
+
+### 8.3 LLM 流与 RunSSE 的时序
+
+```text
+RunSSE 建立
+  -> 注册 request_id
+  -> 接收 Start
+  -> 写出 TextDelta / ThinkingDelta
+  -> 写出 ToolCallDelta
+  -> 写出工具请求
+  -> 等待 BidiAppend 工具结果
+  -> 继续下一次 LLM 流
+  -> 写出 Done
+  -> 关闭 RunSSE
+```
+
+RunSSE writer 必须顺序写出事件。不能让多个 goroutine 直接写同一个连接；所有输出先进入一个有序发送队列。
+
+heartbeat 属于 Transport，不属于 LLM `ResponseEvent`，也不进入 `messages`。
+
+## 9. Dialect 的边界
+
+Dialect 只包含三类代码：
+
+### 9.1 解码
+
+将 Cursor protobuf 转换为内部输入：
+
+```text
+decodeBidiAppend(request) -> InputEnvelope
+decodeExecClientMessage(message) -> ToolResult
+decodeInteractionResponse(message) -> ClientInput
+```
+
+### 9.2 编码
+
+将原生 LLM 事件和客户端命令转换为 Cursor protobuf：
+
+```text
+encodeResponseEvent(event) -> AgentServerMessage
+encodeClientCommand(command) -> ExecServerMessage / InteractionQuery
+```
+
+### 9.3 协议关联
+
+Dialect 可以补充协议必需的：
+
+- `request_id`
+- `conversation_id`
+- `interaction_id`
+- `turn_seq`
+- `exec_id`
+- `tool_call_id`
+- Bidi 的 `append_seqno`
+
+Dialect 不可以做以下事情：
+
+- 拼接或修改模型历史。
+- 根据文本猜测工具调用。
+- 决定是否重试 LLM。
+- 执行工具。
+- 保存 Loop 状态。
+- 把 delta 合并成另一套公共事件。
+
+如果以后增加 WebSocket 方言，只需新增一个编码/解码实现，Loop、LLM 和 Client 不变。
+
+## 10. 工具调用和客户端等待
+
+模型完成一次响应并返回 `StopReasonToolUse` 时：
+
+```text
+AssistantMessage(ToolCall)
+  -> append 到 messages
+  -> command = CallClient
+```
+
+`CallClient` 是一个可持久化的普通数据：
+
+```text
+CallClient {
+  operationID
+  toolCall {
+    id
+    name
+    arguments
+  }
+}
+```
+
+Dialect 将其变成 `exec_server_message`，Transport 发送给客户端。此时 Loop 状态是 `WaitingClient`。
+
+客户端返回结果后：
+
+```text
+ToolResultMessage
+  -> append 到 messages
+  -> 当前工具调用标记完成
+  -> 仍有未完成工具调用时，command = CallClient(下一项)
+  -> 全部完成时，清空 waiting，重新 build RequestMessages，command = CallLLM
+```
+
+工具结果只能通过 `ToolCallID` 关联，不能根据消息顺序猜测对应关系。
+
+一条 `AssistantMessage` 可以包含多个 `ToolCall`。第一版固定按该消息中 `Content` 的顺序逐个派发；一个工具结果提交完成后才派发下一个。这样工具结果追加到 `messages` 的顺序是确定的，连续 LLM 请求的前缀也稳定。未来若必须并行执行，也必须等全部结果完成后按原始工具调用顺序统一追加，不能按到达顺序追加。
+
+## 11. 幂等和重试
+
+Loop 的幂等规则如下：
+
+### 11.1 输入去重
+
+每个输入带有 `inputSeq` 或外部稳定 ID：
+
+```text
+inputID = requestID + appendSeqno
+```
+
+已经提交过的输入再次到达时，返回之前记录的 Transition 结果，不重复执行工具或追加消息。
+
+### 11.2 工具调用去重
+
+`operationID` 由 `conversationID + turnID + toolCallID` 生成。
+
+执行前查询提交记录：
+
+```text
+已完成 -> 直接返回已保存的 ToolResultMessage
+执行中 -> 等待原操作结果
+未执行 -> 执行一次
+```
+
+### 11.3 LLM 重试
+
+LLM 重试必须使用：
+
+```text
+同一个 callID
+相同的 messagesHash
+完全相同的 RequestMessages 序列化结果
+```
+
+不合并两次响应，不把第一次的半截文本和第二次的文本拼接起来。只有一个完整、合法的 `Done` 结果可以提交到 `messages`。
+
+如果某次响应已经提交，再收到同一 `callID` 的重复流，整次流丢弃，不追加第二条助手消息。
+
+### 11.4 同一会话的顺序
+
+同一个 `conversationID` 的输入和 LLM 流事件必须串行进入 `transition`。这是执行顺序，不是另一套业务状态机：
+
+```text
+conversation_id
+  -> 一条顺序执行链
+  -> transition
+  -> SQLite version compare-and-swap
+```
+
+可在进程内用按 `conversationID` 的短锁或任务队列减少竞争；SQLite 的 `version` 是最终裁决。任何提交发现版本已变化，就重新加载状态并重新处理尚未提交的输入。不能让两个 LLM 流同时向同一个会话追加消息。
+
+## 12. 前缀缓存保证
+
+每次 LLM 请求满足：
+
+```text
+request[n].Messages = request[n-1].Messages + newlyCommittedMessages
+```
+
+禁止：
+
+- 修改历史消息内容。
+- 合并相邻消息。
+- 把多条 tool result 重排。
+- 在旧消息中插入新的 context。
+- 每次重放重新生成随机 ID 或时间戳。
+- 把流式 delta 直接写入历史。
+
+动态 prompt 和 Tools 每次可以重新 build，但 `Messages` 的字节序列必须只增加，不回退、不重写。
+
+这里的“前缀”指每个已存在消息的语义内容和确定性序列化都不变，新增消息只排在末尾。完整 HTTP JSON body 本身不要求是字节前缀，因为 `SystemPrompt` 和 `Tools` 可以在本次请求重新 build；供应商适配器的责任是确保既有消息对应的请求片段不发生变化。
+
+建议在每次 `CallLLM` 记录：
+
+```text
+messagesHash
+messageCount
+lastMessageHash
+serializedRequestHash
+```
+
+测试必须确认连续请求满足前缀关系，而不是只比较消息数量。
+
+## 13. 持久化边界
+
+Store 至少提供以下能力：
+
+```text
+load(conversationID) -> ConversationState
+loadInputResult(inputID) -> PreviousCommit?
+commitInput(inputID, beforeVersion, nextState) -> CommitResult
+saveLLMCall(callID, exactRequest, requestHash, status)
+saveClientOperation(operationID, request, result)
+```
+
+提交顺序固定：
+
+```text
+1. transition 得到新状态和 command
+2. 对会话状态有变化时，在一个事务中保存 state、inputID 和调用记录
+3. 对 CallLLM，先保存 exactRequest 和 callID，再打开上游流
+4. 对 CallClient，先保存 waiting 和 operationID，再写出客户端请求
+5. LLM delta 实时写入 RunSSE，但不提交到 ConversationState
+6. 外部结果作为新的 Input 再进入 transition
+```
+
+流中的 delta 默认不落入会话历史，也不需要进入 SQLite outbox。可以单独保存为诊断日志，但不能把诊断日志当作下一次 LLM 的 `Messages`。
+
+`AssistantMessage`、`ToolResultMessage`、`UserMessage`、未完成的 `CallLLM` 和未完成的 `CallClient` 必须在进程重启后可恢复。RunSSE 连接和未完成 delta 不需要持久化；重连时可以重新打开当前 turn 的 RunSSE，恢复调用后重新流式展示。模型历史不受影响，因为旧 delta 从未提交。
+
+### 13.1 SQLite 最小表结构
+
+第一版不需要事件溯源库。五张表足够：
+
+```text
+conversations
+  conversation_id  primary key
+  version          integer       -- 每次已提交状态递增
+  status           text
+  turn_id          text
+  messages_json    blob          -- 按顺序的 llm.Message 数组
+  waiting_json     blob nullable -- 未完成 CallClient
+  updated_at_ms    integer
+
+input_commits
+  conversation_id
+  input_id
+  committed_version
+  result_json      blob          -- 重复 Bidi 输入的返回结果
+  primary key (conversation_id, input_id)
+
+llm_calls
+  call_id          primary key
+  conversation_id
+  request_json     blob          -- exactRequest
+  request_hash     text
+  messages_hash    text
+  status           text          -- planned, streaming, committed, failed, canceled
+  assistant_hash   text nullable
+
+client_operations
+  operation_id     primary key
+  conversation_id
+  turn_id
+  tool_call_id
+  tool_index       integer
+  request_json     blob
+  result_json      blob nullable
+  status           text          -- planned, sent, completed, canceled
+
+stream_diagnostics
+  call_id
+  event_index
+  event_json       blob
+  primary key (call_id, event_index)
+```
+
+`stream_diagnostics` 是可选表，只用于调试和抓包分析。它绝不能被读取后回填成 `messages`。
+
+每次提交使用 SQLite 事务和乐观版本条件：
+
+```text
+update conversations
+set version = version + 1, ...
+where conversation_id = ? and version = ?
+```
+
+没有更新到一行说明发生竞争；重新加载后再处理。`input_commits` 的唯一键负责 Bidi 重放去重，`llm_calls.call_id` 和 `client_operations.operation_id` 分别负责 LLM 与工具调用去重。
+
+## 14. 取消、断线和错误
+
+### 14.1 用户取消
+
+```text
+conversation_action.cancel
+  -> Input.Cancel
+  -> transition 返回 Canceled
+  -> cancel LLM stream / client operation
+  -> 发布协议取消事件
+  -> 关闭 RunSSE
+```
+
+### 14.2 RunSSE 断线
+
+RunSSE 断开不等于用户取消。只停止当前发送连接，Loop 继续运行一段重连宽限时间。Bidi 仍可提交工具结果或取消命令。
+
+### 14.3 LLM 流错误
+
+```text
+Recv error
+  -> 生成 ResponseEvent.Error
+  -> 丢弃 pendingResponse
+  -> 保存 call failure
+  -> 根据策略 Failed 或重新发起同一 callID
+```
+
+不得把网络错误文本写成正常 `AssistantMessage`。
+
+### 14.4 客户端工具错误
+
+工具失败仍然生成 `ToolResultMessage{IsError: true}`，追加后交给下一次 LLM。只有协议连接错误、取消或系统不可恢复错误才终止 Loop。
+
+## 15. 推荐执行时序
+
+```text
+1. Transport 收到 RunSSE 或 BidiAppend
+2. Dialect 验证 request_id、seqno 和 protobuf oneof
+3. Store 加载 conversation 的 ConversationState
+4. Dialect 将客户端消息解码成 Input
+5. transition(state, input)
+6. Store 在同一事务中提交新的 state、inputID 和必要的调用记录
+7. 将 `ResponseEvent` 编码后按顺序写入 RunSSE；delta 不写入模型历史
+8. 执行 command；CallClient 发出请求后返回等待态
+9. LLM 流逐事件回到第 5 步
+10. 客户端工具结果回到第 4 步
+11. Done(stop) 后写出 turn ended，并关闭 RunSSE
+```
+
+## 16. 最小接口集合
+
+实现第一版只需要这些接口：
+
+```text
+type LLM interface {
+  Call(context, RequestMessages) -> ResponseStream
+}
+
+type Dialect interface {
+  DecodeBidi(bytes) -> InputEnvelope
+  EncodeResponse(ResponseEvent, ProtocolContext) -> AgentServerMessage
+  EncodeClientCommand(Command, ProtocolContext) -> AgentServerMessage
+}
+
+type Store interface {
+  Load(conversationID) -> ConversationState
+  FindInputCommit(conversationID, inputID) -> PreviousCommit?
+  CommitInput(inputID, expectedVersion, nextState) -> CommitResult
+  SaveLLMCall(callID, exactRequest, hashes, status)
+  SaveClientOperation(operationID, request, status)
+}
+
+type Transport interface {
+  ReceiveBidi()
+  OpenRunSSE()
+  Send(AgentServerMessage)
+}
+```
+
+客户端工具结果由 Bidi 适配器解码并再次送入 `run`，不需要一个阻塞式的 `Client.Execute` 服务端接口。接口名称可以调整，但职责不能跨层移动。
+
+## 17. 测试要求
+
+### 17.1 Loop 纯函数测试
+
+给定相同的 `state + input`，必须得到完全相同的：
+
+- 新状态。
+- `emit` 顺序。
+- `command` 内容。
+- `messagesHash`。
+
+覆盖：文本流、思考流、工具调用流、正常完成、长度停止、错误、中断、重复输入。
+
+### 17.2 前缀测试
+
+连续三次调用的 `Messages` 必须满足：
+
+```text
+M1 是 M2 的严格前缀
+M2 是 M3 的严格前缀
+```
+
+测试序列化后的消息字节，而不是只比较对象字段。
+
+### 17.3 Dialect 测试
+
+每一种协议消息都测试：
+
+```text
+protobuf -> Input
+Input/ResponseEvent -> protobuf
+```
+
+重点验证 ID、seqno、工具参数、错误码、停止原因和 oneof 分支没有丢失。
+
+### 17.4 流集成测试
+
+使用假的 `ResponseStream` 依次返回：
+
+```text
+Start -> TextDelta* -> ToolCall* -> Done
+```
+
+断言：
+
+- 每个 delta 都按顺序发到 RunSSE。
+- 只有 Done 后才追加 AssistantMessage。
+- 工具结果到达后才启动下一次 LLM。
+- 重复 Done 不产生第二条消息。
+
+## 18. 第一版落地顺序
+
+1. 固定 `llm.RequestMessages`、`ResponseEvent`、`ResponseStream` 为核心契约。
+2. 实现 `ConversationState`、`Input`、`Command` 和纯函数 `transition`。
+3. 实现 `consumeLLM`，验证流事件和 `pendingResponse` 聚合。
+4. 实现 `CallClient` 命令、工具请求发送和 `ToolResultMessage` 回传。
+5. 实现 Dialect 的 Bidi 解码和 RunSSE 编码。
+6. 加入 Store 的状态提交、输入去重和工具操作去重。
+7. 最后接入真实 Connect transport、heartbeat、重连和取消。
+
+完成后，新增一种客户端协议只需要新增 Dialect；新增一种 LLM 供应商只需要新增 LLM 适配器；新增一种工具只需要新增工具能力描述和对应的客户端协议映射。Loop 本身不需要增加状态分支。