使用者痛点洞察

• 过小导致对话被截断长对话会因 token 限制被裁剪，导致模型失去历史信息。
• 工具调用失败后无法恢复一次工具执行错误可能导致整个 Turn 失效，使用者体验骤降。
• 中断操作不一致按下停止按钮后程序需要立即停止所有活动并保证状态一致性。
• 错误处理不透明LLM 调用失败或工具报错时缺少可追踪日志，难以定位问题。
• token 使用未聚合跨步累计不准确导致计费与监控出现误差。

. TurnFlow 概述

TurnFlow 是 Agent 的主要执行引擎，定义在 packages/agent-core/src/loop/run-turn.ts。它的职责可以概括为：

• 管理从接收到使用者 prompt 到产生最终回复的完整循环
• 一个 Turn 可能包含多次 LLM 调用 — 因为工具调用会触发新的 generate step
• 聚合 token 用量 — 跨 step 累计 usage，在 turn 结束时统一上报
• 执行收敛控制 — max steps、abort 检查、continuation hook

从代码签名看。runTurn: Promise

export async function runTurn: Promise {
// input 包含: turnId,signal,llm,buildMessages,// tools/buildTools,hooks,maxSteps,...
}
interface TurnResult {
stopReason: LoopTurnStopReason;// 'end_turn' | 'aborted'
steps的观点是，number;usage: TokenUsage;}

. 完整循环流程

. Context Injection

在每个 Step 开始前，executeLoopStep 调用 hooks.beforeStep. 这个钩子由上层 Agent 注入。负责准备当前 Step 所需的上下文：

• IInjectionManager：
• IGoalMode：

• // turn-step.ts : executeLoopStep
  if {
  const beforeStep = await hooks.beforeStep({
  turnId,stepNumber: currentStep,signal,llm,});if {
  throw new Error;}
  }

  设计要点： 在上下文接近窗口上限时压缩消息，所以工具表解析被延迟到 beforeStep 之后。若先解析工具表再执行注入，Compaction 丢弃的动态 schema 会导致工具表与消息状态不一致。

  . System Prompt Assembly

  调用 buildMessages 建立发送给 LLM 的完整消息列表。这个列表通常包含：

  • BASICSYSTEM PROMPT :Agent Profile 定义的 behavior prompt
  • TOOL DESCRIPTION: 每个可用工具的 JSON Schema
  • INJECTED CONTEXT: Step 中注入的所有提醒和状态
  • CONVERSATION HISTORY: 来自 ContextMemory 的消息序列
  • // 外部传递函数 function buildMessages{ return contextMemory.map }

    . LLM Generate

    S通过 chatWithRetry 调用 llm.chat。主要流程如下:

    • *流式接收 tokens* — via onTextDelta / onThinkDelta / onToolCallDelta 回调实时推送.- *Usage 跟踪* — 响应返回后立即调用 recordUsage .
    • *解析响应* — 从 LLMChatResponse 中提取文本内容和工具调用列表.- *Stop Reason 推导* — deriveStepStopReason 决定是否继续或结束.

      // 流式回调创建
      function createChatStreamingCallbacks: ChatStreamingCallbacks {
      return {
      onTextDelta: => dispatchEvent,onThinkDelta: => dispatchEvent,onToolCallDelta: => dispatchEvent({
      说到type，'tool.call.delta',toolCallId : delta.toolCallId,name : delta.name,argumentsPart : delta.argumentsPart
      }),// ...
      };}

      
      // deriveStopReason
      function deriveStepStopReason: LoopSte…{
      switch{
      case 'truncated': return 'max_tokens';按理说，case 'filtered': return 'filtered';case 'paused': return 'paused';case 'completed':
      case undefined:return response.toolCalls.length>0?'tool_use':'end_turn';case 'tool_calls': return response.toolCalls.length...?// ...
      }
      }

      . Response Processing

      • *end_turn* — 模型无请求工具，文本已流式推送给 UI，turn 自然结束.- *tool_use* — 模型请求执行工具进入工具流程.- *max_tokens/paused*—流式响应中断。如果残留未完成工具调用则记录为未执行.- *filtered*—内容被过滤跳过.- content.part事件分派，每个文本段落/思考段落都有唯一 UUID，用于 transcript 内容块构成.. Tool Execution

        分为五个阶段，以 provider 顺序严格进行:

        1. *Phase A:* **预检** 验证每个调用：名称存在？参数 JSON 可解析，匹配 schema？任何检查失败标记 rejected 并生成错误结果但不中断批次.
        2. *Phase B:* **准备钩子**。可 block 或返回 syntic result 或更新 args.
        3. *Phase C:* **授权钩子**。一样可 block 或返回 syntic result —— 权限入口点。
        4. *Phase D:* **并发调度**。 至于实现智能并发，
           - 无冲突 -> 并发 - 有冲突 -> 串行化 via ToolAccesses.conflict - stopBatchAfterThis -> 跳过后续所有。- global lock via ToolAccesses.all - none 永不冲突。- 按 provider 顺序分派 tool.result event 确保配对。其实，kotlin // tool-scheduler.ts : ToolScheduler.add const scheduledTask = { ...task。result:createControlledPromise};if){ this.queuedTasks.push;//排队等待 }else{ this.start;//立即启动 } return scheduledTask.result; *Phase E:* **结果收尾** finalizeToolResult。不过，所有 tools 执行完毕后依次调用 hooks.finalizeToolResult。接下来按 provider 顺序派发 tool.result events。

           . Loop Decision

           `while{` ... } 主要逻辑的观点是，- 当 stepResult.stopReason === ‘tool_use’ 时 continue 循环。- 当终端 stop reason 时检查 continuation hook。- maxSteps 超限抛出 MaxStepsExceededError。话说回来，- AbortSignal 抛出立即中断并返回 aborted. - 媒体投影降级后续 Step 使用降级建立器。至于代码片段，kotlin // run-turn.ts 主循环主要 while{ signal.throwIfAborted;不过，if\tthrow createMaxStepsExceededError;不过，steps +=1;const stepResult = await executeLoopStep;if continue，const continuation = await hooks?话说回来，.shouldContinueAfterStop?.，if break;}\`\`\`\`\`"

           \r \r \r \r \r...\r<\/table>" ---

           . Turn Completion

           - 聚合 usage 返回 —— TurnResult 包含 stopReason、steps、usage. - AgentRecords 持久化 —— 写入 wire.jsonl. - 启动 turn 后钩子 —— step.end 携带 timing 信息. - Goal Mode 检查 —— 根据 shouldContinueAfterStop 判断是否自动发起 continuation turn. ` ` ` ` ---

           . 上下文管理深入

           ContextMemory 数据结构

           via IAgentContextMemoryService 接口暴露：

           export interface IAgentContextMemoryService {
           说到get，readonly ContextMessage;// 获取完整历史
           再看append，void;// 追加消息
           appendLoopEvent: void;按理说，// 添加 loop event
           从clear来看，void;// 清空历史
           undo这方面，UndoCut;// 撤销末尾消息
           applyCompaction: ContextCompactionResult;// 应用压缩 }

           Step结果\r	Turn动作\r
           `tool_use` \r	继续循环——工具结果已追加到 ContextMemory。下轮 LLM 会看到\r
           `max_tokens` \r	同上——通常触发 continuation\r