Cherry Studio Agent 配置热更新已打开会话如何即时生效配置修改【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio导读本篇技术指南聚焦 Cherry Studio 中的一项行为变更Agent 配置被编辑后正在打开甚至正在运行的 Agent 会话将直接采用新配置不再需要关闭重开会话或等待空闲超时。你将了解该变更的生效规则、底层连接对账reconcile机制的实现原理、权限模式作为安全例外单独处理的细节以及各配置项实际生效的时序。该变更由 PR #16946 引入详见 变更说明并已同步至仓库内的破坏性变更记录集 v2-refactor-temp/docs/breaking-changes。一、变更前的问题配置修改被静默忽略在引入本变更之前如果用户编辑了一个 Agent而该 Agent 的某个会话正处于打开状态那么大部分配置修改都会被该会话静默忽略直到满足以下任一条件才真正生效会话空闲超过 5 分钟运行时连接因空闲 TTL 被回收下次恢复时重新拉取配置会话被关闭后重新打开重建连接时从最新配置重新派生。尤其严重的是MCP 服务器相关的编辑在旧行为下对一个正在运行的会话修改 MCP 服务器集合或定义完全不生效——运行中的会话不会感知这些变化。从源码看5 分钟空闲窗口正是运行时默认空闲 TTL 的体现// src/main/ai/agentSession/AgentSessionRuntimeService.ts const DEFAULT_IDLE_TTL_MS 5 * 60 * 1000空闲 TTL 到期后连接被关闭下一次消息到来时ensureConnection会基于最新配置重新连接配置因此迟到生效。这也解释了为什么用户过去需要等待空闲窗口或手动重开会话。二、变更后的行为配置编辑即时推进到会话新的行为规则可以概括为一张立即 / 下一条消息对照表配置项类别生效时机权限模式permission-mode立即生效安全例外见下文第四节MCP 服务器集合 / 定义从下一条消息开始Plan / 小模型plan/small models从下一条消息开始技能启用 / 禁用从下一条消息开始工作区绑定workspace binding从下一条消息开始最大轮数max turns从下一条消息开始指令instructions从下一条消息开始提供商 API 密钥从下一条消息开始模型model特殊PATCH { model: null }会整体失效会话见第五节关键保证进行中的响应in-flight response绝不会被配置编辑打断——当前轮次的输出完整结束后新配置才从下一条消息开始生效用户不再需要关闭重开会话也不需要等待 5 分钟空闲窗口编辑后发送的第一条消息可能稍慢因为会话运行时需要重新连接以加载新配置。三、底层机制连接对账Connection Reconcile双通道该行为由 Agent 会话运行时的push pull 双通道对账实现核心代码位于 AgentSessionRuntimeService.ts。3.1 Push 通道Agent 更新事件驱动当 Agent 被编辑时运行时服务监听handleAgentUpdated事件遍历所有属于该 Agent 的会话条目逐个对其活动连接发起对账// src/main/ai/agentSession/AgentSessionRuntimeService.ts private async handleAgentUpdated(agentId: string, updates: UpdateAgentDto, agent: AgentEntity): Promisevoid { const modelEdited Object.prototype.hasOwnProperty.call(updates, model) const reconciles: Promisevoid[] [] for (const entry of this.entries.values()) { if (entry.agentId ! agentId) continue // A cleared model (PATCH { model: null }) is unroutable, not stale — fully invalidate. if (modelEdited !agent.model) { this.invalidateModelClearedEntry(entry) continue } // Bookkeeping: fresh turns are stamped with (and steers gated on) the entrys latest model. if (agent.model) entry.modelId agent.model reconciles.push(this.reconcileEntryConnection(entry)) } await Promise.all(reconciles) }代码注释明确了设计意图push 通道是相对每次新轮次都会做的 pull 检查的延迟优化——它让 Agent 编辑立即作用于空闲/活跃连接而不必等待下一条消息。值得注意有些输入变化不会触发agent-updated事件例如会话内技能切换、MCP 定义编辑、工作区切换这些场景没有 push完全由 pull 通道覆盖。3.2 对账裁决verdict语义每次对账由连接的reconcile(input)方法返回一个裁决结果类型定义在 runtime/types.tsexport type AgentRuntimeReconcileResult current | patched | rebuild | invalid | failed运行时服务根据裁决结果采取不同动作见 AgentSessionRuntimeService.ts 的reconcileEntryConnection裁决含义运行时动作current连接配置已是最新无需任何操作patched热修补已应用如工具策略保持连接rebuild属于生成期冻结类配置模型、工作区、技能、子模型、MCP 定义等发生变化无正在进行的轮次时主动关闭连接等待下次拉取重建有活跃轮次则保留连接由下一次新轮次的 pull 承接invalid期望配置已不可派生Agent/会话/模型行被删除与模型被清空同等处理整体失效条目failed热修补失败如收紧权限失败失败关闭fail closed暂停活跃轮次并拆除连接防止继续运行在旧的更宽松的策略下failed分支的注释点明其安全语义一个失败的 live patch 可能让连接继续执行旧的更宽松的策略——快照中的permissionMode会门控canUseTool所以失败的收紧绝不能继续运行。3.3 Pull 通道新轮次必然对账对账并非只靠 push。在 AgentSessionRuntimeService.ts 中每个新轮次在连接上都会执行一次 reconcile一条连接若携带正在运行的 SDK 流绝不会在此处对账——关闭它会丢失进行中的响应一个新的、尚未准入的轮次必须对账——它必须运行在最新配置上对账动作作用于捕获时的连接TOCTOU 纪律即使对账期间条目被替换也绝不对后继者误操作。这保证了即使 push 因某种原因缺席下一条消息也必然以最新配置启动——正是从下一条消息生效这一规则的最底层兜底。四、权限模式唯一立即生效的安全例外变更说明强调权限模式的变更尤其收紧立即生效即使在响应中途这是出于安全考虑。源码在 ClaudeCodeRuntimeDriver.ts 的reconcile实现中给出了精确细节const permissionModeChanged baseline.live.toolPolicy.permissionMode ! fresh.live.toolPolicy.permissionMode // Claudes set_permission_mode control request can terminate work already in flight. Keep the // mode (and the local approval gate that mirrors it) frozen for the active turn; the host pulls // reconcile again before admitting the next turn, when the SDK update is safe to apply. const deferPermissionMode permissionModeChanged this.adapter?.isTurnActive true实际语义比摘要更精细空闲会话无活跃轮次新的权限模式通过 SDK 的setPermissionMode控制请求立即推送到子进程本地审批门approval gate同步刷新活跃轮次中由于set_permission_mode控制请求可能终止正在飞行中的工作权限模式会在当前轮次保持冻结推迟到下一个轮次边界应用——此时由宿主在下一条消息准入前再次 pull 对账来执行更新工具禁用等策略变更不受此限制reconcile中先于 rebuild 裁决应用安全的工具策略事实——新禁用的工具在当前轮次即可收紧只有权限模式等待边界。此外若对账期间setPermissionMode等操作抛错驱动返回failed宿主按失败关闭处理暂停活跃轮次并拆除连接确保绝不会停留在旧的宽松策略上。对应地AgentRuntimeConnection.reconcile的接口契约runtime/types.ts明确写道可现场应用的工具策略事实会在 rebuild 裁决前就地修补唯一例外是权限模式变更——它在活跃轮次中保持冻结在下一次轮次边界应用。五、模型被清空整体失效而非迟到生效handleAgentUpdated中有一个专门分支如果编辑是PATCH { model: null }AgentEntitySchema.model可空Agent 将无法路由到任何模型此时不是标记过期而是整体失效该运行时条目暂停活跃轮次让渲染端得知其已停止abort 随后通过轮次流的 abort 监听器拆除会话closeSession落定轮次、丢弃排队中的后续消息、关闭连接从条目表中移除该 entry同时自动丢弃任何正在进行的旧模型连接其 entry 已非当前connect()会关闭自己打开的连接而不是安装它——无模型 Agent 绝不能留下仍指向旧模型的过期条目。注释还补充了一个边界场景删除模型的user_model行会通过外键onDelete: set null把agent.model置空但该路径不会发出 agent update 事件因此不会走到这个事件驱动的处理器这类情况由其他机制覆盖活跃轮次在自己的捕获模型上完成、排队中的后续消息被startNextTurn的模型复检拦截、新的派发在聊天上下文中以未配置模型快速失败。六、空闲 TTL、连接重建与首条消息延迟变更后用户唯一可感知的代价是编辑后的第一条消息可能启动稍慢。这是因为push 对账可能返回rebuild模型、工作区、技能、子模型、MCP 定义等属于生成期冻结的配置变化此时若无活跃轮次运行时主动关闭连接closeConnectionAsync下一条消息到来时ensureConnection基于最新配置重新连接——新配置自然生效。rebuild判定基于连接配置的rebuildSignature重建签名比较ClaudeCodeRuntimeDriver.ts 中签名不匹配时会记录变更事实并返回rebuild。需要注意的是重建在有后台占用background occupancy或轮次转换transitioning时会被推迟reconcileEntryConnection检查hasLiveTurn、isAgentSessionRuntimeTransitioning、hasAgentSessionRuntimeBackgroundWork只要存在其一就保留连接把重建留给下一次新轮次的 pull——这同样保证了绝不在工作中途打断的承诺。状态机中对应的事件是connection-rebuild-deferred见 agentSessionRuntimeState.ts。七、测试验证与发布注意事项仓库测试覆盖了这一行为的核心路径AgentSessionRuntimeService.test.tsreconciles the connection on any agent update without closing a current one任何 Agent 更新都触发连接对账且不关闭当前连接pushes a reconcile for configuration-only updates纯配置更新如{ configuration: { permission_mode: plan } }也会推送对账fails closed and logs when a push reconcile throwspush 对账抛错时失败关闭并记录日志pauses the active stream and preserves queued turns when a live reconcile failslive 对账失败时暂停活跃流并保留排队轮次驱动层对账的current/patched/rebuild/invalid/failed全裁决矩阵见 ClaudeCodeRuntimeDriver.test.ts 与 PiRuntimeConnection.test.ts。对发布经理的提示原文即含进行中的响应不会被配置编辑打断新配置从下一条消息开始生效权限模式收紧是安全例外立即生效若在发布前还有其他 Agent 会话对账相关的变更条目需要合并处理。八、总结本变更的实质是给 Cherry Studio 的 Agent 会话运行时补齐了配置编辑 → 连接即时对账这条链路push 通道handleAgentUpdated事件驱动让空闲/活跃连接立即感知配置变化消除等 5 分钟空闲或重开会话的旧行为pull 通道每条新消息必然对账作为兜底保证从下一条消息生效安全例外权限模式收紧在空闲时立即推送、活跃轮次中冻结到边界应用失败则 fail closed整体失效模型被清空的 Agent 会话被完全拆除绝不残留指向旧模型的过期运行时。如果你在使用中编辑了正在对话的 Agent 配置只需知道两条规则正在输出的响应不会被中断下一条消息将运行在最新配置上——唯一需要接受的代价是编辑后首条消息因重新连接而略慢。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考