尧图网站建设 
free-coding-models Router v2 引擎深度解析内容验证故障转移与持久化熔断器是如何实现的【免费下载链接】free-coding-modelsFind, benchmark and install in CLI 170 FREE coding LLM models across 15 providers in real time项目地址: https://gitcode.com/gh_mirrors/fr/free-coding-modelsfree-coding-models 是一款帮助开发者在 15 免费供应商中查找、压测并一键安装 170 免费编码 LLM 模型的开源工具而它内置的Router v2是第二代智能模型路由引擎。本文深度解析 Router v2 的两项核心机制——内容验证故障转移HTTP 200 不再等于成功与持久化熔断器熔断状态跨重启存活并顺带拆解故障归因与决策追踪帮你理解它如何保证 AI 编程流量永远落一个能用的模型上。为什么需要一台更强的路由器200 黑洞问题Router v2 是 v1 智能路由器的强化重建版运行在独立端口默认 19380开发环境 29380上与 v1 共享同一套模型集合、供应商密钥和配置互不干扰。它要解决的头号痛点是免费供应商著名的假成功返回HTTP 200但choices数组是空的返回HTTP 200但响应体里嵌着一个error对象SSE 流正常连接、正常关闭却从头到尾没有产出任何有用内容。v1 把上述三种情况全部计为成功故障转移引擎从未触发编程 Agent 只是静默地什么也没收到。这就是 Router v2 被称为强化重建版的根本原因。完整背景见 docs/router-v2.md。内容验证故障转移200 响应如何被验明正身双层内容门非流式与 SSE 流验证逻辑集中在 response-gate.js 中分为两层第一层非流式响应体校验。validateChatCompletionPayload对已解析的 200 JSON 体做检查response-gate.js#L48-L78strict 模式下只有当第一个 choice 携带真实内容时才放行——内容定义为非空文本、tool_calls、旧式function_call或推理 tokenreasoning_content。特别值得注意的是纯推理输出也算有效内容因为部分思考模型会先流式输出推理再输出正文绝不能误判为失败。第二层流式增量追踪器。createStreamReadinessTracker把每个到达的 SSE 文本块喂给observe()逐帧提取data:负载回答两个问题信号含义useful流已产出真实内容文本增量 / 工具调用 / 推理errorPayload某个 SSE 帧携带了error对象流式门控的 Hold Buffer 策略真正的杀手锏在守护进程 router-daemon.js 中的 hold-buffer 策略router-daemon.js#L2940-L3026可以概括为一个状态机先扣住不转发。上游流的前几个数据块先进入路由器本地的 hold buffer客户端暂时收不到任何字节看到错误帧 → 立刻切换。若在产出内容前出现errorPayload路由器中止上游连接、记一次真实失败故障转移到下一个模型——错误永远到不了你的工具看到有用内容 → 一次性冲刷。flushHold()先写响应头并附上决策追踪头再缓冲内容一起放行缓冲溢出 → 放行。单个事件超过 256KB 还无法判定异常供应商行为则直接透传避免无限缓冲把请求卡死流闭合但零内容 → 真失败。没有产出任何有用内容就关闭的流记为empty_stream故障并继续切换而不是成功完成内容产出后上游报错 → 保留部分输出。已转发内容后出现的错误保留已输出的部分、干净关闭同时如实记一次失败v1 会误标成功。故障归因400 不再误伤健康模型每次失败都会被 failure-classifier.js 归类为 16 种类型之一并生成一份判决kind、责任方、是否故障转移、是否损伤健康度、是否按Retry-After暂停配额。最有价值的改进是责任归因客户端 4xx请求体过大、字段不被支持仍故障转移到下一个模型但永不计入熔断器——一次格式错误的请求再也不会把三个健康模型的熔断全部打爆429 限流该模型按Retry-After窗口暂停上限 15 分钟窗口内直接跳过401/403 密钥失效阻塞该供应商的其余候选但视为配置问题不扣模型健康分200-but-garbage 家族invalid_json/empty_choices/empty_content/error_payload/empty_stream必须故障转移且必须计为真实失败。分类器是纯函数、零副作用因此极易单测——对应测试位于 test/router-v2.test.js。持久化熔断器跨重启的模型健康记忆四态状态机熔断器实现在 breaker-store.js 的BreakerStore类中相比 v1 有三个关键升级1. 状态持久化到磁盘。v1 的熔断器只存内存守护进程一重启全部清零又因为探测轮询会跳过探测缓存中还算新鲜的模型一个恰好在重启前变坏的模型会毫发无损地重新接回真实流量直到再失败三次。v2 把熔断状态原子写入~/.free-coding-models-router-v2-breakers.json路径定义见 constants.js#L72-L74文件权限 0600启动时自动恢复——冷却期跨越重启完整生效。2. 新增 DEGRADED 预警态。当连续失败数达到失败阈值的60%时模型进入DEGRADED状态仍可被路由但排名低于健康模型仪表盘显示为琥珀色警告——你在熔断触发之前就能看到异常状态含义路由行为CLOSED健康正常参与竞争DEGRADED连续失败达阈值 60%可路由排名靠后仪表盘黄灯OPEN触发熔断连续失败达阈值默认 3 次完全跳过进入冷却期HALF_OPEN冷却期满放行试探流量成功则完全重置再失败则再次 OPENOPEN → HALF_OPEN的晋升是惰性的——在下一次候选评分时顺带检查冷却时间breaker-store.js#L116-L127无需后台定时器。3. 递增式冷却。每个模型记住自己的tripCount熔断每多触发一次冷却时间翻倍30s → 60s → 120s → 240s → 480s上限为初始值的16 倍总冷却上限默认 300 秒。一个好了又坏、坏了又好的抖动模型再也不可能每 30 秒就溜回轮转阵容捣乱。同时markSuccess完全重置健康状态但刻意保留tripCount作为递增冷却的记忆breaker-store.js#L186-L203。持久化细节原子写 防抖 TTL防抖刷盘状态变更只置脏标记2 秒防抖后统一落盘FLUSH_DEBOUNCE_MS 2000避免高频故障时磁盘写入风暴原子写通过共享工具atomicWriteJson先写临时文件再重命名中途崩溃也不会留下半截 JSON30 天 TTL30 天无更新的条目自动剔除状态文件永远不会无限膨胀自愈加载文件损坏时记录警告并全新启动绝不阻塞守护进程启动。决策追踪每一次路由都留下完整证据链v1 的请求日志只有一个failover: true/false布尔值——你知道切过却不知道为什么切、跳过了谁。v2 为每个请求记录一条有序追踪decision-trace.jsskipped调度前被排除的候选及机器可读原因circuit_open、quota_paused、auth_error…attempts实际派发的每次尝试含状态码、延迟、错误类型served最终产出答案的模型。追踪结果通过响应头直接暴露给 Agentx-fcm-v2-model、x-fcm-v2-attempts以及单行摘要x-fcm-v2-decisiondecision-trace.js#L106-L118格式形如servedModel!outcome|modelA:429-modelB:200|skips2所有请求完整尝试链 跳过原因还会持久化到~/.free-coding-models-router-v2-history.json环形上限 500 条供 TUI 的 Router v2 仪表盘TUI 中按ShiftV和 Web 仪表盘查看。隐私契约追踪只包含路由元数据——模型键、状态码、耗时、错误类型不含 prompt、不含响应正文、不含任何 API 密钥。快速上手启动 Router v2 并观察它的免疫系统Router v2 现已并入主守护进程无需额外配置docs/router-v2.mdfree-coding-models --daemon # 前台启动端口 19280 free-coding-models --daemon-status # 查看状态 free-coding-models --daemon-stop # 停止把编程工具的 base URL 指向http://localhost:19280/v1模型名填fcm即可享受全链路路由填fcm:provider/modelId则钉住单个模型走完整个路由链规范化 → 内容门 → 熔断更新这是 TUI 中CtrlT经路由器测试动作背后的机制。可调整的关键参数写入~/.free-coding-models.json的router.failover配置项默认值作用bodyReadTimeoutMs30000非流式上游读体超时根治悬挂请求totalBudgetMs120000整条故障转移链的总墙钟预算contentValidationstrict内容门严格度strict/basic/offlastResortModel关闭全集合失败后给指定模型最后一次机会核心文件地图模块职责src/core/router-v2/response-gate.js内容验证门非流式体校验 SSE 增量追踪器src/core/router-v2/breaker-store.js持久化熔断器四态机、递增冷却、原子落盘src/core/router-v2/failure-classifier.js16 类失败分类与责任归因策略src/core/router-v2/decision-trace.js每请求决策追踪与x-fcm-v2-*头src/core/router-v2/request-history.js500 条环形请求历史支撑仪表盘src/core/router-v2/constants.js端口、状态文件路径、fcm:...模型钉住语法test/router-v2.test.jsRouter v2 单元测试写在最后Router v2 的设计哲学可以浓缩为一句话把供应商说成功了换成内容确实到了把内存里的好脾气换成磁盘上的真记忆。内容验证故障转移堵死了免费供应商最常见的 200 黑洞持久化熔断器让冷却期不怕重启、让抖动模型付出递增代价而决策追踪让每一次路由决策都事后可审计。对日常使用免费模型跑编码 Agent 的你来说这意味着更少的静默空回复——这正是 Router v2 值得你花 5 分钟读懂的地方。【免费下载链接】free-coding-modelsFind, benchmark and install in CLI 170 FREE coding LLM models across 15 providers in real time项目地址: https://gitcode.com/gh_mirrors/fr/free-coding-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 free-coding-models Router v2 引擎深度解析：内容验证故障转移与持久化熔断器是如何实现的
free-coding-models Router v2 引擎深度解析内容验证故障转移与持久化熔断器是如何实现的【免费下载链接】free-coding-modelsFind, benchmark and install in CLI 170 FREE coding LLM models across 15 providers in real time项目地址: https://gitcode.com/gh_mirrors/fr/free-coding-modelsfree-coding-models 是一款帮助开发者在 15 免费供应商中查找、压测并一键安装 170 免费编码 LLM 模型的开源工具而它内置的Router v2是第二代智能模型路由引擎。本文深度解析 Router v2 的两项核心机制——内容验证故障转移HTTP 200 不再等于成功与持久化熔断器熔断状态跨重启存活并顺带拆解故障归因与决策追踪帮你理解它如何保证 AI 编程流量永远落一个能用的模型上。为什么需要一台更强的路由器200 黑洞问题Router v2 是 v1 智能路由器的强化重建版运行在独立端口默认 19380开发环境 29380上与 v1 共享同一套模型集合、供应商密钥和配置互不干扰。它要解决的头号痛点是免费供应商著名的假成功返回HTTP 200但choices数组是空的返回HTTP 200但响应体里嵌着一个error对象SSE 流正常连接、正常关闭却从头到尾没有产出任何有用内容。v1 把上述三种情况全部计为成功故障转移引擎从未触发编程 Agent 只是静默地什么也没收到。这就是 Router v2 被称为强化重建版的根本原因。完整背景见 docs/router-v2.md。内容验证故障转移200 响应如何被验明正身双层内容门非流式与 SSE 流验证逻辑集中在 response-gate.js 中分为两层第一层非流式响应体校验。validateChatCompletionPayload对已解析的 200 JSON 体做检查response-gate.js#L48-L78strict 模式下只有当第一个 choice 携带真实内容时才放行——内容定义为非空文本、tool_calls、旧式function_call或推理 tokenreasoning_content。特别值得注意的是纯推理输出也算有效内容因为部分思考模型会先流式输出推理再输出正文绝不能误判为失败。第二层流式增量追踪器。createStreamReadinessTracker把每个到达的 SSE 文本块喂给observe()逐帧提取data:负载回答两个问题信号含义useful流已产出真实内容文本增量 / 工具调用 / 推理errorPayload某个 SSE 帧携带了error对象流式门控的 Hold Buffer 策略真正的杀手锏在守护进程 router-daemon.js 中的 hold-buffer 策略router-daemon.js#L2940-L3026可以概括为一个状态机先扣住不转发。上游流的前几个数据块先进入路由器本地的 hold buffer客户端暂时收不到任何字节看到错误帧 → 立刻切换。若在产出内容前出现errorPayload路由器中止上游连接、记一次真实失败故障转移到下一个模型——错误永远到不了你的工具看到有用内容 → 一次性冲刷。flushHold()先写响应头并附上决策追踪头再缓冲内容一起放行缓冲溢出 → 放行。单个事件超过 256KB 还无法判定异常供应商行为则直接透传避免无限缓冲把请求卡死流闭合但零内容 → 真失败。没有产出任何有用内容就关闭的流记为empty_stream故障并继续切换而不是成功完成内容产出后上游报错 → 保留部分输出。已转发内容后出现的错误保留已输出的部分、干净关闭同时如实记一次失败v1 会误标成功。故障归因400 不再误伤健康模型每次失败都会被 failure-classifier.js 归类为 16 种类型之一并生成一份判决kind、责任方、是否故障转移、是否损伤健康度、是否按Retry-After暂停配额。最有价值的改进是责任归因客户端 4xx请求体过大、字段不被支持仍故障转移到下一个模型但永不计入熔断器——一次格式错误的请求再也不会把三个健康模型的熔断全部打爆429 限流该模型按Retry-After窗口暂停上限 15 分钟窗口内直接跳过401/403 密钥失效阻塞该供应商的其余候选但视为配置问题不扣模型健康分200-but-garbage 家族invalid_json/empty_choices/empty_content/error_payload/empty_stream必须故障转移且必须计为真实失败。分类器是纯函数、零副作用因此极易单测——对应测试位于 test/router-v2.test.js。持久化熔断器跨重启的模型健康记忆四态状态机熔断器实现在 breaker-store.js 的BreakerStore类中相比 v1 有三个关键升级1. 状态持久化到磁盘。v1 的熔断器只存内存守护进程一重启全部清零又因为探测轮询会跳过探测缓存中还算新鲜的模型一个恰好在重启前变坏的模型会毫发无损地重新接回真实流量直到再失败三次。v2 把熔断状态原子写入~/.free-coding-models-router-v2-breakers.json路径定义见 constants.js#L72-L74文件权限 0600启动时自动恢复——冷却期跨越重启完整生效。2. 新增 DEGRADED 预警态。当连续失败数达到失败阈值的60%时模型进入DEGRADED状态仍可被路由但排名低于健康模型仪表盘显示为琥珀色警告——你在熔断触发之前就能看到异常状态含义路由行为CLOSED健康正常参与竞争DEGRADED连续失败达阈值 60%可路由排名靠后仪表盘黄灯OPEN触发熔断连续失败达阈值默认 3 次完全跳过进入冷却期HALF_OPEN冷却期满放行试探流量成功则完全重置再失败则再次 OPENOPEN → HALF_OPEN的晋升是惰性的——在下一次候选评分时顺带检查冷却时间breaker-store.js#L116-L127无需后台定时器。3. 递增式冷却。每个模型记住自己的tripCount熔断每多触发一次冷却时间翻倍30s → 60s → 120s → 240s → 480s上限为初始值的16 倍总冷却上限默认 300 秒。一个好了又坏、坏了又好的抖动模型再也不可能每 30 秒就溜回轮转阵容捣乱。同时markSuccess完全重置健康状态但刻意保留tripCount作为递增冷却的记忆breaker-store.js#L186-L203。持久化细节原子写 防抖 TTL防抖刷盘状态变更只置脏标记2 秒防抖后统一落盘FLUSH_DEBOUNCE_MS 2000避免高频故障时磁盘写入风暴原子写通过共享工具atomicWriteJson先写临时文件再重命名中途崩溃也不会留下半截 JSON30 天 TTL30 天无更新的条目自动剔除状态文件永远不会无限膨胀自愈加载文件损坏时记录警告并全新启动绝不阻塞守护进程启动。决策追踪每一次路由都留下完整证据链v1 的请求日志只有一个failover: true/false布尔值——你知道切过却不知道为什么切、跳过了谁。v2 为每个请求记录一条有序追踪decision-trace.jsskipped调度前被排除的候选及机器可读原因circuit_open、quota_paused、auth_error…attempts实际派发的每次尝试含状态码、延迟、错误类型served最终产出答案的模型。追踪结果通过响应头直接暴露给 Agentx-fcm-v2-model、x-fcm-v2-attempts以及单行摘要x-fcm-v2-decisiondecision-trace.js#L106-L118格式形如servedModel!outcome|modelA:429-modelB:200|skips2所有请求完整尝试链 跳过原因还会持久化到~/.free-coding-models-router-v2-history.json环形上限 500 条供 TUI 的 Router v2 仪表盘TUI 中按ShiftV和 Web 仪表盘查看。隐私契约追踪只包含路由元数据——模型键、状态码、耗时、错误类型不含 prompt、不含响应正文、不含任何 API 密钥。快速上手启动 Router v2 并观察它的免疫系统Router v2 现已并入主守护进程无需额外配置docs/router-v2.mdfree-coding-models --daemon # 前台启动端口 19280 free-coding-models --daemon-status # 查看状态 free-coding-models --daemon-stop # 停止把编程工具的 base URL 指向http://localhost:19280/v1模型名填fcm即可享受全链路路由填fcm:provider/modelId则钉住单个模型走完整个路由链规范化 → 内容门 → 熔断更新这是 TUI 中CtrlT经路由器测试动作背后的机制。可调整的关键参数写入~/.free-coding-models.json的router.failover配置项默认值作用bodyReadTimeoutMs30000非流式上游读体超时根治悬挂请求totalBudgetMs120000整条故障转移链的总墙钟预算contentValidationstrict内容门严格度strict/basic/offlastResortModel关闭全集合失败后给指定模型最后一次机会核心文件地图模块职责src/core/router-v2/response-gate.js内容验证门非流式体校验 SSE 增量追踪器src/core/router-v2/breaker-store.js持久化熔断器四态机、递增冷却、原子落盘src/core/router-v2/failure-classifier.js16 类失败分类与责任归因策略src/core/router-v2/decision-trace.js每请求决策追踪与x-fcm-v2-*头src/core/router-v2/request-history.js500 条环形请求历史支撑仪表盘src/core/router-v2/constants.js端口、状态文件路径、fcm:...模型钉住语法test/router-v2.test.jsRouter v2 单元测试写在最后Router v2 的设计哲学可以浓缩为一句话把供应商说成功了换成内容确实到了把内存里的好脾气换成磁盘上的真记忆。内容验证故障转移堵死了免费供应商最常见的 200 黑洞持久化熔断器让冷却期不怕重启、让抖动模型付出递增代价而决策追踪让每一次路由决策都事后可审计。对日常使用免费模型跑编码 Agent 的你来说这意味着更少的静默空回复——这正是 Router v2 值得你花 5 分钟读懂的地方。【免费下载链接】free-coding-modelsFind, benchmark and install in CLI 170 FREE coding LLM models across 15 providers in real time项目地址: https://gitcode.com/gh_mirrors/fr/free-coding-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考