Craft Agents 消息排队完全指南：midStreamBehavior 字段如何贯穿全链路

Craft Agents 消息排队完全指南midStreamBehavior 字段如何贯穿全链路【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agentscraft-agents-oss是一款开源 AI 代理开发工具支持多模型连接、会话管理和流式响应。当 AI 正在打字streaming时你又按下了发送键这条消息是立即插队还是排队等待答案就藏在midStreamBehavior这个配置字段里。本文将完整拆解该字段从定义、持久化、决策到消息回放的全链路实现。 什么是 midStreamBehaviorSteer 还是 QueueAgent 还在输出回复时用户发来新消息有两种处理哲学模式行为适用场景steer转向尝试把新消息注入当前正在进行的回合in-flight turn想立刻改变 AI 方向queue排队不打断当前回合消息进队列回合自然结束后按序重放想稳定收尾、避免中途打断这个字段定义在 LLM 连接配置LlmConnection中字段声明llm-connections.ts —— Behavior when the user sends a message while the agent is still streaming对旧版config.json保持向后兼容可选字段读取时统一走解析函数兜底。按提供商选择默认值不同后端对插队的支持程度不同因此默认值按提供商区分llm-connections.tsanthropic →queueClaude 的 steer 是模拟实现借 PreToolUse hook 注入如果回合结束前没有工具触发注入会失败变成steer_undelivered白付了 tokenpi / pi_compat →steerPi 原生支持.steer()非破坏性、保留完整上下文没有副作用。唯一的读取入口resolveMidStreamBehavior全项目约定判断 steer 还是 queue永远只通过resolveMidStreamBehavior(connection)而不是直接看providerType。该函数llm-connections.ts对遗留连接字段不存在或配置损坏非法值自动回落到按提供商的默认值是整条链路的单一事实来源。⚙️ 配置写入与持久化字段的生命周期从创建连接那一刻就开始了创建时写入默认值createBuiltInConnection会调用defaultMidStreamBehavior(providerType)把显式默认值落盘connection-setup-logic.ts这样设置页第一次加载就能看到打勾。更新时保留字段updateLlmConnection在合并其他字段时midStreamBehavior要么取新值、要么保留旧值不会被覆盖丢失storage.ts。设置界面可切换Electron 设置页的 AI 连接右键菜单提供 Steer / Queue 子菜单用户点击后走onSetMidStreamBehavior更新连接并持久化AiSettingsPage.tsx。 全链路核心SessionManager 的中途发送分支真正的分叉发生在服务端SessionManager.sendMessage的 mid-stream 分支SessionManager.ts逻辑非常清晰若会话正在处理isProcessing先用resolveMidStreamBehavior解析出行为steer调用agent.redirect(message)尝试注入当前回合若后端返回失败已强制中止自动降级进入排队queue完全跳过redirect()不打断、不中止当前回合继续跑完两种路径下都会立刻创建 user message 推给 UI——steer 成功发accepted状态否则发queued状态未 steer 成功的消息统一压入managed.messageQueue并同步落盘flush保证崩溃不丢消息。 回放机制messageQueue 的 FIFO 重放排队消息不会凭空消失链路后半段由三个环节闭环回合结束时检查队列onProcessingStopped触发后先检查messageQueue.length 0有就调processNextQueuedMessage没有才真正结束会话SessionManager.tsFIFO 重放processNextQueuedMessage取队首消息、清除isQueued标记、把 UI 状态从queued更新为processing然后递归调sendMessage重放SessionManager.ts。重放失败会发出带Retry按钮的类型化错误queued_message_replay_failed而不是笼统的未知错误崩溃恢复冷启动水合会话时会扫描磁盘上残留的isQueued true的孤儿消息重新压回messageQueue并立即重放SessionManager.ts。✅ 测试保障与版本说明该特性的可靠性有专门的测试覆盖解析函数 存储往返测试midstream-behavior.test.ts —— 覆盖显式值优先、遗留连接回落、损坏配置回落、字段更新保留等场景创建连接时种子默认值测试connection-setup-logic.test.ts功能发布说明Steer vs Queue 的动机与失败形态对比0.9.1.md。 总结midStreamBehavior一条链路的完整路径是创建连接写入默认值 → config.json 持久化 → 设置页可视化切换 → SessionManager.sendMessage 中途分支决策steer 注入 / queue 入队 → 回合结束 onProcessingStopped → processNextQueuedMessage FIFO 重放 → 崩溃后冷启动孤儿消息恢复设计上最值得学习的一点决策逻辑只放在会话管理器一处后端 Agent 代码零改动且所有读取都收敛到resolveMidStreamBehavior单一入口让旧配置、坏配置都能优雅降级。这也是字段贯穿全链路却不散乱的关键。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考