CodePilot 旧聊天切换模型失败诊断实录：从 409 ROUTE_REQUIRES_HANDOFF 到跨服务商续聊修复

人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载导读本文以 CodePilot 开源仓库中的 old-chat-model-switch-diagnosis-2026-09-05.md 诊断报告为主体完整还原一次真实故障的定位、修复与回归验证全过程升级后的旧聊天在切换模型时反复提示Runtime、服务商和模型没有保存成功根因并非单一 bug而是 continuation policy 误判、路由校验视图不一致、Codex Account 冷缓存三重因素叠加。读完本文你将掌握 CodePilot 聊天路由route与 Runtime 线程执行绑定thread-execution-binding的底层机制理解replay_context续聊模型、ROUTE_REQUIRES_HANDOFF与INVALID_ROUTE_MODEL两个关键错误码的语义以及该项目如何用三层自动化测试单元、E2E、回归将此类跨服务商切模型场景固化下来。一、问题现场旧聊天切换模型为何保存失败1.1 用户诉求与表面现象版本升级后用户对既有旧聊天执行模型切换操作时UI 提示Runtime、服务商和模型没有保存成功。用户对行为预期提出了非常明确的约束只允许锁定Agent / Runtime不得锁定服务商与模型同一旧聊天必须能切换不同服务商的兼容模型必须保留聊天 ID、历史消息及当前页面不允许创建、导入或跳转到新聊天。也就是说这是一次原地改道的需求——聊天身份session ID不可变历史不可丢页面不可跳只有 Runtime 下的 Provider Model 组合可以变化。1.2 从 UI 报错到 HTTP 层真相UI 上笼统的保存失败背后真实发生在 HTTP 路由接口PATCH /api/chat/sessions/:id/route上。该接口在 route.ts 中实现存在多层 409 冲突语义错误码触发条件ROUTE_REVISION_CONFLICTexpected_route_revision与当前绑定的routeRevision不一致乐观并发控制RUNTIME_RECOVERY_REQUIRED绑定状态为legacy_unbound且未带recovery标记RUNTIME_OWNERSHIP_CONFLICT聊天已 bound 到 Runtime A却请求切换到 Runtime B跨 Runtime 改道ROUTE_REQUIRES_HANDOFFbound 状态下 continuation mode 判定为new_sessionROUTE_CHANGE_UNSUPPORTEDcontinuation mode 判定为unsupportedINVALID_ROUTE_MODEL/INVALID_ROUTE_PROVIDER/RUNTIME_ROUTE_INCOMPATIBLE/ROUTE_CREDENTIALS_UNAVAILABLE路由校验层拒绝见 route-validation.ts诊断报告确认真实 Dev 环境旧聊天GPT 模型切到 DeepSeek 时接口返回409 ROUTE_REQUIRES_HANDOFF而模型选择器仍允许选择目标模型UI 层把该拒绝压成了通用保存失败——这是第一条根因的完整链条。二、三重根因剖析为什么看起来能选保存却必败2.1 根因一Codex continuation policy 把换 Provider 定义为new_sessionCodePilot 为每个 Runtime 定义了一套续聊策略continuation policy核心数据结构位于 continuation-policy.tsexport type RouteChangeMode in_session | replay_context | new_session | unsupported; export const RUNTIME_CONTINUATION_POLICIES { claude_code: { continuationKey: claude_code:db_replay, modelChange: replay_context, providerInstanceChange: replay_context, contextImport: db_replay, }, codepilot_runtime: { continuationKey: codepilot_runtime:db_replay, modelChange: replay_context, providerInstanceChange: replay_context, contextImport: db_replay, }, codex_runtime: { continuationKey: codex_runtime:thread_provider, modelChange: in_session, providerInstanceChange: replay_context, // 修复前为 new_session contextImport: canonical_handoff, }, };routeChangeMode的判定顺序是先比较 Runtime不同则new_session再比较 Provider不同则取该 Runtime 的providerInstanceChange最后比较 Model不同则取modelChange。修复前codex_runtime的providerInstanceChange是new_session因此同一 Codex 聊天只要切换服务商就会进入需要移交到新会话的分支而 route.ts 中对 bound 聊天遇到new_session直接返回409 ROUTE_REQUIRES_HANDOFF与用户绝不新建聊天的诉求正面冲突。对照实验还排除了泛化误判同服务商切换模型的真实旧聊天如 GLM-5.3 → Flash → GLM-5.3、Sol → Terra → Sol两次 PATCH 均为 200说明失败只出现在跨服务商路径上且两条真实复现路径的 Runtime 都是codex_runtime。2.2 根因二路由校验只查已落库模型与执行视图不一致第二条根因来自校验与执行两个环节的视图分裂模型选择器的候选列表来自当前 provider catalog执行期的 resolverprovider-resolver.ts同样允许 catalog 中尚未落库的模型而旧版路由校验只检查数据库中已物化的provider_models表。结果用户在模型管理页Settings之外直接切换一个尚未落库的 catalog 模型时执行层认为它可用路由层却返回INVALID_ROUTE_MODEL。诊断报告特别指出一个掩蔽效应——先打开一次模型管理页会让目录落库从而掩盖该问题这也解释了为何问题仅在特定路径未预先访问模型管理页上复现。E2E 用例 old-chat-model-route.spec.ts 特意使用无物化行的目标 ProviderDeepSeek V4 Flash来钉住这一场景。2.3 根因三Codex Account 校验只读路由模块的内存缓存第三条根因发生在codex_account虚拟提供商的模型校验上。旧实现只查询当前路由模块的内存缓存实机在 DeepSeek 回复后切回 GPT 时再次报INVALID_ROUTE_MODEL而独立模型接口仍能返回该 GPT 模型——说明当前路由没有目录缓存并不等于模型不可用。诊断结论是冷缓存只是未做发现而非否定模型存在显式选择模型时应允许一次有时限bounded的模型发现而不是直接判死。这一原则最终写进了 route-validation.ts 的注释与实现。需要强调的是报告明确限定这三条逻辑没有 Windows 分支同服务商切换的真实旧聊天对照成功因此不能据此声称每一种旧聊天、每一种模型组合都会失败——结论边界是诊断可信度的组成部分。三、修复方案从策略、上下文到校验的全链路改造3.1 策略层Codex 同 Runtime 换 Provider 改为replay_context核心改动是 continuation policy 中codex_runtime.providerInstanceChange由new_session改为replay_context见上文代码。语义变为产品聊天原地不动adapter 在下一次发送时以聊天摘要 压缩边界过滤后的最近历史重建服务商绑定的原生执行线程。同时路由变更只修改原聊天的 Provider Model保留 owner、聊天 ID 和全部消息跨 Runtime 改道依然返回RUNTIME_OWNERSHIP_CONFLICTcanHandoff: true提示可移交但不会自动跳新聊天。3.2 上下文层Codex adapter 的摘要 历史重建replay_context的实际执行位于 continuation-context.ts 的buildCodexContinuationInput其行为要点历史迭代器newestHistoryFirst以调用方传入的快照为种子从新到旧分页读取每页 200 条、beforeRowId游标、排除心跳 ack遇sessionSummaryBoundaryRowid即停保证只取摘要边界之前的消息成功 resume 的原生线程不做 DB 分页。压缩边界过滤token 预算扣除包装开销与图片额度WRAPPER_TOKEN_ALLOWANCE 256、每张图IMAGE_TOKEN_ALLOWANCE 2048后逐条累积放不下的历史被省略并注入提示[Earlier conversation omitted to fit the context budget; do not assume omitted requirements are known.]。附件还原restoreAttachments仅用户消息的!--files:...--首部信封可回放restoreassistant/工具文本不会被解释为本地文件授权路径经resolveInTreeAttachmentPath校验项目内、文件存在图片仅在目标模型声明支持时附像素否则降级为文件引用文本。不复制产品消息复用已有的历史归一化 / token budget 逻辑buildFallbackContext以preserveContent: true组装最终输入。3.3 线程引用ref生命周期只有首轮被接受才替换Codex 每次执行依赖原生 thread 的引用ref。修复确立的替换规则是只有新执行线程的首轮被接受后才替换 ref启动/输入失败时保留旧 ref重试重新带入上下文切回旧 Provider 时使用当前聊天最新历史而非旧分支。codex-thread-continuation.test.ts中对应用例包括同 Provider resume 仅换模型、跨三种 Provider 重建、MCP 配置变化或 resume 失败时重建历史、历史一次性注入text.split(What colour?).length - 1 1、启动/输入失败保留旧 ref 重试、切回后携带期间全部新对话、保留当前输入与图片输入。3.4 校验层复用执行 resolver 的 DB catalog 视图route-validation.ts 的validateRuntimeRoute重写为与执行期一致的双视图校验普通 ProviderresolveProviderForSessioncallScene: interactive_chat→ 在availableModels中查找目标模型 →getModelCompat检查 Runtime 兼容 →getProviderCompat检查凭据credentials-missing/credentials-unreadable/!hasCredentials→ROUTE_CREDENTIALS_UNAVAILABLE受管虚拟 Provider从listManagedVirtualProviderModelGroups匹配模型与兼容性envProvider比对ENV_CLAUDE_CODE_MODELS的modelId/upstreamModelId。校验仍然继续拒绝手动隐藏、不存在、不兼容及凭据不可用的路线。codex_account分支单独处理显式选择允许最多 2500ms的目录发现fetchCodexModels({ timeoutMs: 2500 })而isServerRecoverySafeMode()时为cacheOnly: true被动全量 feed 继续只写缓存、不启动 Codex 进程——把显式选择的发现权利与后台被动发现的资源成本明确区分开。四、真实验证一次跨三服务商的旧聊天改道修复验证全部在真实旧聊天上完成npm run electron:dev computer-use 操作未新建或导入产品聊天。诊断报告给出的验证矩阵如下场景结果修复前8 月 26 日问候CodePilotGLM-5.3 → Flash → GLM-5.3两次 PATCH 200同服务商对照正常修复前8 月 4 日 Codex 账号旧聊天Sol → Terra → Sol两次 PATCH 200同服务商对照正常修复前同一 Codex 账号旧聊天Sol → DeepSeek V4 FlashPATCH 409 /ROUTE_REQUIRES_HANDOFF修复后同一旧聊天 GPT → DeepSeek → GLM → DeepSeek → GPT每步最终保存成功始终同一聊天及页面Runtime 固定 Codex切到 DeepSeek 后实际发送一条历史核对消息模型正常回复并准确复述切换前第一条用户消息本机 proxy 与 chat 请求终态均为 200DB 核对聊天总数始终 587目标旧聊天原有 9 条消息保留smoke 新增一问一答后 11 条已切回原 GPT 模型route revision 为 6其中两个值得注意的细节诊断阶段 GLM 对照聊天回到原模型时选择器使用稳定 IDsonnet原保存值为上游 IDglm-5.3[1m]语义一致两次正常选择使 revision 2——说明路由层的route_revision是每次成功 PATCH 递增一次的 CAS 版本号UI 必须携带最新值才能避免ROUTE_REVISION_CONFLICT。修复后链式切换GPT → DeepSeek → GLM → DeepSeek → GPT每一步都成功保存说明replay_context在双向反复切换下也稳定。五、自动化与防回归三层测试把场景钉死5.1 E2E三个 Runtime 同/跨 Provider 切换old-chat-model-route.spec.ts 在隔离的 Playwright 数据库CODEPILOT_E2E_DATA_DIR前缀强校验中对claude_code、codepilot_runtime、codex_runtime三个 Runtime 各执行一轮通过 HTTP 创建 ProviderGLM 源 DeepSeek 目标后者不物化目录行直接UPDATE chat_sessions SET runtime_binding_state bound模拟 legacy 绑定旧聊天HTTP PATCH 同服务商切模型200revision 1→ 写入历史消息 → 走 UI 选择器切回200revision 2→ 切跨服务商模型200revision 3session ID / runtime_pin 不变断言聊天总数与目标聊天消息列表逐字节不变、页面 URL 保持在/chat/:id最后跨 Runtime PATCH 必须返回409 RUNTIME_OWNERSHIP_CONFLICT。报告记录跨 Provider case 修复前在 Codex 分支 RED409修复后 GREEN目录未落库用例修复前 REDINVALID_ROUTE_MODEL修复后 GREEN。5.2 单元测试路由校验与 Codex 续聊runtime-route-validation.test.tscatalog 模型无需先访问模型管理页即可通过新 catalog 模型与旧物化行并存继续拒绝隐藏/不存在/不兼容模型Codex 冷缓存下显式选择可发现recovery safe mode 下不启动 Codex 发现。codex-thread-continuation.test.ts同 Provider resume、跨三种 Provider、MCP 变化、resume 失败、历史一次性注入、启动/输入失败重试、切回保留期间历史、图片输入共 9 组场景。5.3 回归与发布状态完整npm run test5475 pass / 0 fail / 1 既有 skip补充启动失败用例及强化断言后定向 17/17类型检查与 Harness boundary 通过E2E 合跑本轮模型切换与相邻的 GLM 身份冲突回归3/3 通过Runtime / Composer guardrail见 docs/guardrails/Runtime.md与执行计划、技术交接同步无 schema 变更、无发布操作基线9bef7299/ v0.67.13状态为 Code complete / Tests pass / 旧聊天路径 Smoke passed未发版。六、边界与后续诊断结论的适用前提报告明确划定了本次修复的边界只确认了本轮模型切换与一次真实历史承接一条历史核对消息不能代替相邻计划的跨 Runtime handoffruntime-thread-ownership-and-handoff.md、三引擎长历史/压缩及缓存成本矩阵根因与修复均针对codex_runtime的跨服务商路径Claude Code 与 CodePilot Runtime 本就以db_replay方式支持同/跨 Provider 切换2500ms 是显式选择的发现上限recovery safe mode 下退化为纯缓存查询属于安全与可用性的权衡设计。七、总结这次诊断的价值在于一个 UI 层保存失败的笼统提示最终被拆解为策略误判ROUTE_REQUIRES_HANDOFF、视图不一致INVALID_ROUTE_MODEL、冷缓存误杀Codex Account 发现缺失三个相互独立的缺陷并各自给出了源码级的修复与测试固化。对使用者而言核心心智模型是CodePilot 的聊天路由 Runtime 所有权不可跨 Provider/Model 组合同 Runtime 内可原地改道 乐观版本号revision CAS 双视图校验DB 落库 ∪ catalog 实时。修复后的行为与用户诉求完全对齐同一旧聊天、同一页面、历史不丢、Runtime 锁定、服务商与模型自由切换。如果你正在排查类似能选不能存的模型切换问题建议按本报告的路径复现先看 continuation-policy.ts 确认目标 Runtime 的providerInstanceChange/modelChange再看 route-validation.ts 确认校验视图是否与执行 resolver 一致最后用 old-chat-model-route.spec.ts 的场景矩阵做回归对照。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐解决Archon聊天面板加载失败从报错到修复的终极实战指南解决Archon聊天面板加载失败从报错到修复的终极实战指南 Archon作为一款能够创建其他AI代理的先进AI编码框架其聊天面板是用户与AI交互的核心界面。人工智能AI Agent代码智能体工作流自动化流程编排后端前端CLIAIRI 接入 Z.ai 聊天服务商全指南从 API Key 到意识模块模型选择AIRI 接入 Z.ai 聊天服务商全指南从 API Key 到意识模块模型选择 Z.ai 提供与 OpenAI 格式完全兼容的聊天 API借助这一特性AAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染ChatBox项目iOS端数据导出功能修复解析ChatBox项目iOS端数据导出功能修复解析 ChatBox是一款广受欢迎的跨平台聊天应用近期其iOS版本的数据导出功能出现了异常导致用户无法正常备份对话AI 应用桌面应用大模型上一篇在游戏机上刷B站wiliwili让你用手柄畅享视频体验下一篇高效工作新体验Zen Browser 5分钟终极配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考