路由治理:把一个组做成用户唯一入口
面向「客户端只绑定一个组,不在具体模型之间手动切换」的部署与排障。
基于 Magpie 0.1.1307 的版本核验,结论按该版本记录;换版本后先用
magpie --version 和原生帮助复核。
以下命令在 Skill 目录内执行,scripts/、config/、state/ 均相对该目录。
职责分工:
- smart-split 是入口设计和规则语义的权威说明。
- cli-contract 与 operations 约束 CLI 写入和变更流程。
- token-strategy 维护额度类型、任务档位和成本边界。
- 本文只记录统一入口落地时的排障顺序、版本实测差异和验收检查;不另立一套规则语义。
0. 治理目标
用户只设一个组入口,其余分层都在组内解决。配置合格的四条判据:
- 客户端只绑定组 ID,不改具体模型。
- 不同难度能落到预期能力层,并可从 usage 的 served model 读回。
- provider 额度耗尽或限流时,路由链有明确的下一落点;整条链都失败时仍如实返回错误。
- 成本顺序符合当次已确认边界:若用户已确认某个池可混合免费、赠送额度与套餐后备, 保留该设计;若当次目标明确硬性零消耗,才建立或拆出只含免费资源的入口。
1. 排障:先定位失败类型
用 magpie usage --csv --last 6h 按 provider / status / error_message 聚类,再决定处理位置。
下面四类的负责人不同,不能一律靠改组解决:
| 症状 | 优先核对 | 处理位置 |
|---|---|---|
| 供应商明确报免费额度已用完 | 该 provider 是否额度为 0,却仍被组内选中 | 移出活跃组;保留 provider 记录供其它客户端使用 |
| 供应商限流或排队拒绝(429 / queued / retry in Ns) | 单账号、单 provider 还是整组容量;并发峰值与队列等待 | 先核 provider 账号级 account-concurrency 与有界 queue,再考虑分流;不是多建组 |
| 账号登录失效 | 错误时间窗和当前可服务状态 | 真人重新登录;网关侧不能代替 |
| 路由组被停用(switched off) | 组的 disabled 标记 |
0.1.1307 记录的处理路径是在 Magpie GUI 的 Routing 页开启 |
先看额度和状态,再改组。 优先以 magpie quota 核额度;读不到时保留未知,不写 0。
成员显示 not served 表示该成员当前不可用(供应商关闭、模型未暴露等),不等于额度耗尽。
HTTP 成功也不等于任务质量通过;内容质量仍要由任务验收判断。
若需真人重新登录,先保留失败证据和时间窗,再由账号 owner 处理;路由治理不代替账号维护。
0.1.1307 帮助与既有 CLI 合同只确认 provider 账号级并发/队列控制;未核到可替代它们的
组级并发或组级队列开关,也未核到独立的“冷却”子命令;冷却是否由队列参数或供应商侧承担,
标 NOT_VERIFIED。组的职责是组织成员和失败路径,不是绕过账号限制。
2. 实测坑
2.1 disabled 无 CLI 开关
组的 disabled: true 使其不响应请求,也不出现在 /v1/models。CLI 没有 enable/disable 子命令;
magpie group add 同名替换不清该标记,且会替换掉已有 rules。
0.1.1307 的报错文案指向 Magpie 的 Routing 页;本文未核到其他开启机制。提前请真人在 GUI 开启,
不要反复用 CLI 试探。
2.2 provider fallback 每次调用整体替换
0.1.1307 隔离探针显示:连续两次 magpie provider fallback <provider> <target>,第二次覆盖第一次,
不是追加。需要多个 fallback 目标时,必须在同一次调用里给全;逐次调用不能累积成链。
2.3 provider fallback 可以指向组
0.1.1307 治理记录确认 magpie provider fallback <provider> group/<id> 可写入,配置回读仍指向组。
该样本中组继续按自己的 routing 和 rules 路由;升级或改配置后仍需请求验证。
因此不要把组当成普通模型展开后重写规则。
2.4 逗号多值:普通模型可并列,组目标要单独给
0.1.1307 实测:
- 普通
provider/model目标可以在一次调用中用逗号并列。 group/<id>目标可以单独写入,但把组目标与普通模型放进同一个逗号串会失败, CLI 会把整串当成一个模型名。
所以不要把所有目标机械地拼成逗号串。含组的回退优先写成「一个组目标 + 组内 order」, 让内层负责后续层级;需要多级 provider fallback 时,再按同一次调用的语法核对回读。
2.5 stays 在配置里存为 affinity
magpie group set <id> stays=turn 成功后,CLI 回读显示 stays turn,
但 providers.json 中没有 stays 键,而是写在 affinity 字段。
按 stays 键核配置会误判为未写入;null 表示默认值,不表示失败。
核对脚本应读 affinity,或直接以 magpie group <id> 的 CLI 输出为准。
2.6 GUI 与 CLI 会同时写配置
Magpie GUI 会写回 ~/.config/magpie/providers.json,可能把刚移除的成员重新写回。
CLI 也可能瞬时读到旧状态(例如报组不存在,但该组实际存在)。
治理期间保持单一配置操作者:GUI 改完即停用 CLI 同组写入,或反过来。 每次写入后回读配置哈希、成员表和规则,不以“命令返回成功”作为唯一证据。
2.7 本机解析到回环的厂商域名会让全局代理被绕过
按 Magpie 0.1.1307 源码核对,若厂商域名在本机解析中指向 127.0.0.1
(本机“屏蔽”条目),网关报 dial tcp 127.0.0.1:443: connect: connection refused;
同一时刻经代理访问该域名返回真实服务器响应,给该 provider 单独设置代理后恢复。
该版本源码可解释这条链路:
- 全局代理先由
netproxy.For选定;netproxy.Func随后用onLAN解析目标主机。 当解析出的地址都是私网、链路本地、回环或 CGNAT 时,网关丢弃全局代理并直连。 这是为局域网内另一台网关或本地模型设计的直连取舍,本机“屏蔽”条目也会命中它。 - provider 自己的代理通过请求上下文的 choice 传递;
Func在 onLAN 判定前先返回 这个 choice,所以不会被上述解析结果绕过。 loopback在 provider choice 之前直接识别回环字面量、localhost与.localhost后缀,并直连;普通域名解析到回环则会继续走到上面的 onLAN 分支,表现为先解析、 后直连回环地址失败。
判据顺序:
- 先看报错里的地址:目标是
127.0.0.1(或本机回环)时,先核对主机解析来源与本地服务, 不要先改代理规则。 - 用代理单独访问该域名,确认代理侧可达(拿到真实响应即证明代理链路通)。
- 再决定是修本机解析还是给 provider 指定代理。provider 级代理优先:它不动系统文件, 可随时回退。
- 源码结论绑定 0.1.1307 的
netproxy与lan;升级后先复核这两个模块再复用结论。 provider URL 自身就是回环地址时仍不会走代理,这不是本节场景。
注意:CLI 可能不接受 provider 的代理字段(报 unknown field),此时只能在应用界面里设,
或按该版本源码里的存储字段名直接写入配置文件后回读核对。
2.8 全局直连与 provider 级代理是两层,不能互相替代
2026-10-25 观测,并核对 Magpie 0.1.1371 源码(netproxy、provider/proxy、
settings)。当只有一个供应商需要走代理、其余供应商直连更快时,可以把全局代理设为
直连、只给那一个 provider 指定代理。这与 §2.7 是同一条出口链路的两端:§2.7 处理
「全局代理被绕过」,本节处理「全局代理本身是否应该存在」。
以下语义绑定 0.1.1371 的 netproxy、 provider/proxy 与 settings, 不把旧版核对记录当作新版或所有客户端的保证:
- 全局层:
netproxy.For依次判定设置里的全局代理值。"direct"直接返回直连;""不是「无代理」,而是继续跟随环境变量里的*_PROXY与系统代理;其余值按该地址 代理。settings.CheckProxy只接受""、"direct"和 http/https/socks5/socks5h 地址。 因此「把全局代理清空」并不等于「全局直连」;后续是否代理取决于环境变量、系统设置 与绕过条件,没有可用代理时也可能直连。此处direct只约束 Magpie 的应用层代理选择, 不关闭系统 VPN/TUN 或其他透明转发。 - provider 层:
provider.Via用netproxy.With(ctx, p.ProxyChoice())把该 provider 自己的代理写进请求上下文。netproxy.Func在做onLAN判定之前先返回这个 choice, 非空 choice 优先于全局值及onLAN;空值仍继承全局,direct显式直连。 回环字面量、localhost与.localhost仍先于 choice 直连(见 §2.7)。ProxyChoice的取值顺序: 单 key 先查该 key 的AccountProxies,再查 provider 的Proxy;带账号时先查当前内存 对象里的账号级AccountProxies和 providerProxy,仅当AccountProxies == nil且Proxy == ""时,改从配置里保存的 同名记录读取,再按账号级 → provider 级取值。storedPicks是空值时的替代来源,不是 第三级顺序回退。 - 账号层:经
ViaLogin/ViaSignedIn发出的请求先取账号自己的非空 choice,再取 provider 的;两者均未指定时才继承全局。因此有显式代理的账号可在全局direct下继续 走代理,没有显式 choice 的账号会受全局值影响;不是所有登录路径都自动经过这些函数。
所以「全局直连 + provider 级代理」是可行且可回退的组合,但有三条边界必须先核:
- 先核哪些出口真的需要代理。 直连可达的供应商不必绕远;对每个供应商域名分别做 「直连」与「经代理」两种探测。同一目标直连失败而经代理可达,才支持该环境下选代理; 两种都失败应标为未定位,继续查解析、代理出口、TLS 或服务端错误,不能据此断言代理有效。 两种都可达则按稳定性与延迟选择。收到真实 HTTP 响应只证明链路可达,不证明登录或模型 调用成功。判断依据是探测结果,不是厂商地区或既往个人环境的结论。
- 改全局值会影响的不只是网关。
netproxy.EnvWith(choice, env)先取显式 choice, 仅在它为空时读取全局值;有效值为direct才移除子进程的代理环境变量。带显式 provider 代理的调用不因全局direct自动直连;厂商 CLI 自己的配置或系统透明转发仍需另核。 部分签到请求由网关进程内发出,不经过EnvWith;走全局还是账号/provider choice, 取决于该请求是否携带对应上下文,不能仅凭「签到」或「登录」名称判断。 改完要单独验证一次登录态刷新、签到读取与 provider 连通性测试,不要只看网关请求。 - provider 级代理字段可能没有 CLI 写入口。 当版 CLI 报
unknown field时,只能在 应用界面里设,或按该版本源码里的存储字段名直接写配置文件后回读核对。这条与 §2.7 末尾的注意事项同源。
变更前保存两层前态。在已获配置变更授权时,先给必须代理的 provider 设置并验证显式代理,
再把全局改为 direct;已有正确的 provider 代理就保留,不重复覆盖。每步独立回读与探测,
避免先撤掉唯一可用出口。回退先恢复本次改动的全局值,再恢复本次改动的 provider 字段;
每步核对现场仍与预期后态一致,发生漂移即停,不用整文件覆盖其他配置。
验收至少覆盖:显式代理 provider 与其余 provider 的连通性、需要的登录/刷新路径,
以及授权内代表性网关请求的 tries、served 与错误;成功落点不能证明此前没有失败尝试。
使用有界探测,不把单次成功扩大为稳定性结论。未经过 Magpie 的客户端出口不受这些设置保证;
本节是文档与源码核对,不代表已替读者执行配置变更或生产验证。
2.9 规则命中、目标不可用与分类器回退要分开断言
按 Magpie 0.1.1307 源码核对,规则命中正确,实际服务模型却不是规则 指向的那个,至少有两条不同路径:
- 目标不可用(
rule.unready=true):规则命中的成员当前没有可用候选,例如额度休息、 并发限制或供应商关闭。0.1.1307 的候选顺序是「规则use目标 → 后续匹配规则的then目标 → 组默认顺序」。原目标不可用时,可用的then目标先承接并写入rule.instead; 没有可用规则目标时才保留组默认顺序,此时instead可为空。休息候选会移到队尾, 多个休息候选通常只探测其中一个,不等于全部从尝试链删除。 观测样本:外层规则命中某嵌套组,该嵌套组当时无可用候选,外层按当时的候选顺序落到 下一成员。对该内层组直接发请求是另一个样本:全组仅剩一个可用候选,被尝试后失败, 不能据此判断外层其它成员也没有回退。 - 分类器回退(
rule.classified.fallback=previous):intent 分类超时、失败或分类器所在 供应商休息时,若无本轮候选 intent 可用则不命中任何 intent;上一轮 intent 仍在本轮候选 集合中时,0.1.1307 会沿用上一轮 intent。表现为规则号可能变化、use目标保持不变。
所以「规则命中」和「实际落点」必须分别断言:
- 从请求日志读
rule(命中的规则号与use目标)。 - 分别读
rule.unready/then/instead与rule.classified.error/fallback,区分目标不可用、 后续规则承接和分类器回退。 - 从同一条的
tries读尝试序列与状态,从served读最终服务模型。 - 出现不符时,先查成员是否处于额度休息或分类器是否失败,再谈配置顺序;休息状态是 会自己过期的时间窗, 不是配置错误。
2.10 强模型入组后会被兜底消耗,顺序只是降低概率
按 Magpie 0.1.1307 源码核对,把一个额度受限但能力强的模型加入组后,
即使它排在末尾,前面各层都不可用(额度休息、并发限流)时,请求就会落到它并消耗额度。
以下顺序结论适用于外层 routing=order 的新 turn / 新会话重选路径:
排在中间:前面的层一旦不可用,它就是下一个落点。
排在末位:只有此前各层都无可用候选时才会被选中;休息中的候选会被移到队尾。
stays=auto时,已应答且缓存仍值得保持的成员可继续留在前面;它此前服务的强模型 不会因为前层恢复而立即退回末位。stays=turn在新 turn 重新按顺序选择;session与strict更粘滞。smart、weight或manual下,“排在末位”不表达同一个含义。规则提升:用一条窄的意图规则
use=<该模型>。命中时它被提到最前,其余成员留在后面。顺序末位:只降低非规划新 turn 落到它的概率,不是额度硬闸门。
硬性不消耗:用成员移除或
pause排除;pause的条件不含 intent,不能用 intent 精确暂停。已核对 0.1.1307 的组与规则配置模型:没有“规则未命中则把成员移出回退”的开关。 GUI 层按同版本界面复核,跨版本重核。
验收按“规划类请求是否落到它”和“非规划类请求有没有误落到它”两条分别统计, 只看前者会漏掉额度被消耗掉的另一半。
3. 建组、拆组与成员分层
入口规则如何表达意图,以 smart-split 为准;成本和额度分类以 token-strategy 为准。本节只补充落地时的建组/拆组判据。
先读 smart-split 的「先尊重已有选择」:按用户私有画像和当次授权核对成本边界,不从组名推断免费或付费属性。需要不同成本硬边界时,另立或拆出符合该边界的入口。
适合同组:成员在当次任务能力上可互换,失败后可用相同验收标准承接,且不会违反 当次已确认成本边界。典型是同一能力档位的多个来源;组负责组织成员和失败路径。
考虑拆组:以下条件只有在违反当次明确要求、且用回读/请求证据确认后,才成为拆组理由; 不能拿通用偏好覆盖 smart-split 已确认的有意混合设计:
- 能力不可互换:当次任务硬性要求长上下文、图像、工具调用或语言能力,而部分成员未证实具备。 核对点:模型目录能力、配置回读,以及每个能力层的代表性请求和 served model。
- 成本边界被违反:当次明确要求硬性零消耗,但现有成员会消耗套餐、点数或余额; 有意混合资源组不属于这种情况。核对点:用户确认边界、token strategy 分类和实际落点。
- 归属方或观测口径不能满足:专属资源、共享资源或计费主体必须分开归因,而当前 usage/routing log 无法区分。核对点:同一时间窗内的 provider/model、account/key 与错误归因。
- 需要不同的 provider 账号控制:账号并发和队列必须分开设为不同值; 组内 routing 不能替代 provider 账号限制。核对点:provider 级只读回读和限流观测。
统一入口可按能力层表达主次,层内是否允许免费、套餐、点数或余额承接,完全沿用
smart-split 的用户确认边界和 token-strategy.md 分类;不在此重复维护成本表。
额度为 0 的 provider 只有在违反当次边界或无法承接时才移出活跃组;移出前保留 provider
只读状态和错误证据,且不删除 provider 记录。
3.1 能力层要显式接进入口,且每层准备多个来源
能力层用嵌套组表达时,先把「组存在」和「组已接进唯一入口」分开核对:
magpie groups只能证明组存在,不能证明外层入口会选到它。- 回读外层入口的完整
members,确认每个需要独立承接的能力层都有显式引用。 - 回读内层
members、routing、stays 和off状态,确认至少有一个当前可服务来源。 - 用直接请求和经外层入口的请求分别看 routing log 的
tries与served; 只在外层日志里偶发看到某个模型,不能据此认定它已有独立能力层。
同一解析后的 provider/model 与固定 effort 可能同时出现在两个兄弟嵌套组,例如能力组与
免费池。0.1.1307 展开嵌套时会把该成员折叠到第一次出现的位置,同时保留它在后续组的位置;
不同固定 effort 是不同成员,不会互相折叠。引用后续组的规则仍可按该组自己的顺序选到它。
因此这不是组循环,也不是同一请求里的两条并行路径;但共享会改变外层默认顺序中的首次落点。
归因时用 via、tries 和 served 看它当时从哪个槽位被选。先保留用户有意确认的混合
资源组,不要为了消除重复而删除免费池中的有效成员。
每个能力层都应有多个来源。某一层只有一个候选来源时,该候选进入额度休息、并发限制或 供应商关闭后,该层在最前通常无法承接,外层会先尝试下一层;休息候选会移到队尾并可能 作为探测候选保留,关闭或移除才是无候选承接。这并不表示该层未被引用或模型已下线。 层内来源数、当前可用数和路由方式应在变更前后分别回读。
3.2 嵌套组的内外层路由与规则相互独立,stays 不是
外层组只把内层组当作一个成员槽位,内层仍按自己的 routing、rules 和 stays 选来源。 因此:
- 外层写
order,不会把内层也变成固定顺序;内层若仍是smart/auto,实际来源 仍由内层决定。 - 要让整条入口链可预测,外层和内层都要回读并统一到本次需要的行为;只改外层不能 证明内层语义已对齐。
- 0.1.1307 中经外层请求的候选会按内层 routing/rules 重排,但会话保持只用外层
affinity;内层stays只在直接请求内层组时生效。不要把直接请求时的内层保持行为 推广到经外层入口的请求。 - 嵌套深度和成员可用性都要单独检查;内层为空、全休息或被关闭时,外层不会因为 引用存在就获得该能力。
变更后用同一能力层做一次直接请求和一次经外层入口的请求,分别核对两层 tries,
确认外层选中预期内层、内层再按声明路由选中预期来源。只看到最终 served 不足以
判断是哪一层完成了回退。
嵌套组只在内层是一组可独立维护的同层来源时使用。外层引用内层后,内层作为
一个模型按自身 routing 和 rules 继续。不要把组自身放进自己,或让同一组在同一祖先链上
重复;引用已停用、无可用成员的内层,或为隐藏配置复杂度增加层级,都会让排障失真。
同一 provider/model 与固定 effort 出现在兄弟嵌套组时会折叠到首次出现位置,见上文共享
成员的处理。
嵌套深度上限为 8,不能把组自身或形成环的组放进自己。
变更后逐层回读外层成员、内层成员、rules、routing、disabled 和 provider fallback;
再做每个能力层的代表性请求,用 routing log 的 per-try 序列和 usage 的 served model
确认外层先到哪个内层、内层再选哪个成员。
本文的 routing log 指本机 routing/YYYY-MM-DD.jsonl(或 gz)路由日志,采集口径见
观测说明;该来源未核到时按 NOT_VERIFIED 记录,不用其它日志顶替。
4. 规则变更后的落点检查
规则语义和推荐顺序见 smart-split 的规则节。 落地时额外核对:
- 新增规则通常落在末尾;既有规则可能先命中,需用
magpie group rule mv调整并回读顺序。 - 带 intent 的规则需要 classifier。尚无 intent 规则时,单独设置 classifier 会被拒; 首条 intent 规则可同时传 classifier,或先建立 intent 再单独设置。
- 意图措辞要互斥,避免分类器无法区分;纯“运行命令”不必然是轻任务。
- 不依赖固定标签协议;以分类器的实际落点为准。
5. 单组可配置项
以下字段均在 magpie group set 中,按当前版本帮助核对:
| 字段 | 适用建议 | 说明 |
|---|---|---|
effort=auto |
需要自动定档时 | 由 classifier 决定每轮推理档;需已有 classifier |
stays=turn |
需要每轮重新路由时 | 在每轮边界重新选择;auto 可能在缓存仍值得时继续粘住原账号 |
stays=off |
接受缓存下降时 | 每请求重新路由,最不粘滞 |
levels= |
显式声明客户端可选档位 | 成员不支持所请求档位时按“就近映射”,不报错 |
context= |
需要覆盖默认上下文长度时 | 告知客户端该组可承接的上下文长度;默认取组内最大成员 |
routing=smart |
接受默认策略时 | 在有剩余额度的订阅中优先选择最先重置的账号;不是「免费优先」规则 |
routing=order |
需要可预测顺序时 | 按成员顺序尝试,最适合核对回退链 |
routing=rotate |
需要轮换成员账号时 | 每轮推进到下一成员的账号或 key;实际轮换效果需请求验证 |
routing=usage |
需要按剩余额度均衡时 | 选剩余额度更多的账号;额度读不到时不要假设可精算 |
routing=pace |
有可靠周期额度信息时 | 按窗口流失速度安排;信息缺失时保留未知 |
routing=weight |
需要请求配比时 | 按成员权重分摊请求;一个成员休息时退出本轮,下一成员承接回退 |
routing=manual |
固定验收模型时 | 只走指定成员,无自动失败回退 |
weight= |
帮助仅定义于 routing=weight |
配比分流;在其他路由模式下的运行时作用未验证 |
fast= |
供应商确实支持时 | 快速通道;不支持的成员会被拒 |
effort=agent |
默认 | 按客户端请求的推理档执行 |
stays 的取舍:auto / session 偏向粘滞;turn 每轮重选;
off 每请求重选但可能损失缓存;strict 连账号失效也不迁移,错误会直接返回 Agent。
粘滞只是失败的一个候选解释,是否构成真因要看 usage 的错误时间窗和落点。
manual 与 pick 是同一状态的两个入口:pick 把每次请求固定到指定成员,其他成员和
rules 等待,直到重新 pick 或改路由;不要用它验收会触发失败回退的场景。
order 需要区分三层事实:
- 配置成员顺序:
providers.json或magpie group <id>回读到的成员列表。 显式命名成员按配置顺序排在前面;pattern 成员保留 pattern 本身,后续按当时模型目录 列出的顺序展开,新匹配模型会加入、失效匹配会离开。配置回读必须同时看显式成员、 pattern 和当前展开数量,不能把 pattern 的动态展开误当成手工调序失败。 - 版本内语义合同:当前 CLI help 明确
order是第一个成员直到不能应答,再下一个; 这是本版本可依赖的官方合同。 - routing log / usage 观测:routing log 中的 runtime
order数组、账号展开、失败后重排、 per-trytries和 served model 是运行时证据,不能反推配置成员顺序,也不能单独用来否定 第 2 层合同。usage CSV 可用于最终 provider/model、状态和错误聚类;本证据边界未核到 per-try 序列,完整 try 链应从 routing log 或逐请求日志核对。
因此,不得把 runtime order 数组与配置列表不同直接解释为“调序无效”或“order 语义未证”;
只能说该样本尚未解释 runtime 数组的展开/排序方式。若要验证配置顺序的因果效果,须固定其他配置,
只调整成员顺序,逐请求记录每次 try 序列和 served model。
6. 计点层的有界溢出
计点或按余额付费成员只能作为明确授权的兜底层,不能成为免费池失败后的无界泄压区。 落地时同时满足:
- 容量有界:在 provider 账号级设置并发上限和有界队列;这些限制跨模型、组和客户端共享。 起点沿用 token-strategy 的保守建议,按观测调整,不在本文复制数值表。
- 路径有界:回读计点 provider 的 fallback、计点成员所在的外层/内层组、嵌套引用和 rules。
计点层通常是终点;若配置了继续向外扩散的 fallback,必须确认其成本授权。若某时段绝不允许
计点消耗,用
pause硬排除或移出该成员并回读,不靠排序或 use 猜测。 - 观测有界:按实际 served provider/model 统计请求占比、错误率、延迟分位和并发峰值; 成本以余额或账单读数为准,价格缺失写 unknown,不用目录价冒充实付。
- 停止条件明确:计点层请求占比短窗突增、其错误率/延迟显著恶化,或免费层错误类型
从排队变为额度耗尽时,先停止计点层承接并修复上游,不继续用重试扩大消耗。停止动作应是
可回读的
pause、成员移除或经核实语法的 fallback 重写;执行后核对 routing log 不再出现 计点成员 try。不要为了快速止损直接整文件回滚 providers.json,以免覆盖并发写入者。
嵌套深度上限是结构约束,不是成本授权;允许 8 层不表示可以配置 8 层计费回退。
7. 免费窗口迁移验收
免费期、赠送窗口或订阅窗口结束时,不能只改组名或删除成员。迁移验收至少包含:
- 固定日期边界和时区,区分订阅周期、免费窗口和点数批次到期,不以一种时间替代另一种。
- 重新核候选模型暴露状态、额度类型和服务状态;失效成员从活跃组移除或明确保留原因。
- 保存迁移前配置快照、成员、规则、fallback、并发和队列到
state/私有层,绑定内容哈希。 - 对每个能力层发真实代表性请求,不只做配置回读。
- 用
magpie usage读实际 served model,确认各层落点符合新窗口预期;异常落点先解释再扩大流量。
失败判据:日期或额度类型不明、候选不可服务、目录未更新、任一能力层落到违反成本边界的成员、 错误率或延迟劣化无法解释、或 usage/routing log 无法归因,均不得扩大流量。
回滚先做最小字段恢复:暂停或移除本次新增成员,恢复本次变更的成员、routing、rules 和 fallback 字段,并逐项回读;只有确认无并发写入者且保存了完整前态时,才按既有变更流程考虑 更大的恢复动作。回滚后仍要发代表性请求,确认旧边界恢复。
8. 效果验证
配置回读不等于生效。发代表性请求,并查看实际落点:
curl -s http://127.0.0.1:<port>/v1/chat/completions \
-H "Content-Type: application/json" -H "Authorization: Bearer <local-key>" \
-d '{"model":"group/<id>","messages":[{"role":"user","content":"<该难度的一句话>"}],"max_tokens":25}'- 响应里的
model可能是组名,不一定是最终成员;以magpie usage的served_model为准。 - 完整尝试链看 routing log 的 per-try
tries;usage CSV 只用于最终 served model、状态和错误聚类。 - 每个意图至少测一次,核对是否落到预期能力层。
- 对比修复前后的失败率和错误类型,只判断是否缓解目标故障;同时保留时间窗、改项和混杂因素, 不把一次对比直接当成因果证明。
- 记录
CONFIG_READBACK_VERIFIED只证明配置落盘,active 落点仍需真实请求。
9. 客户端侧
9.1 主会话与子 Agent
- 客户端只绑组:
magpie <agent> group/<id>。绑具体模型会绕过组内分流。 - 子 Agent 的模型选择属于客户端配置,另见 子 Agent 模型指定。 不要假设网关能覆盖客户端写死的模型,也不要假定某条客户端子命令一定写入了核心配置; 以实际配置回读和重启后的 served model 为准。
- 修改客户端配置、重启 app-server 或切换默认模型都属于独立动作,需相应授权。
- 组被停用时,绑定命令可能报
has no routing group;这不等于组不存在,需回查disabled。
9.2 模型目录是静态快照
按 2026-10-21 当日客户端行为记录,Codex 配置 model_catalog_json 时,该文件用于限定或隐藏
模型目录,是静态快照(该结论来自当次客户端侧观察,非 CLI help 条款):
它不会因为 Magpie 新增路由组或 Codex 新增模型而自动刷新。即使组已配置成功,
旧目录也可能让客户端看不到新组。每次新增组或升级模型后,都要重新生成目录、回读内容并重启客户端;
只重启而不重建目录不能保证新模型出现。
落地检查:
- 记录当前目录路径、内容哈希和生成来源,确认它确实被客户端配置引用。
- 重新生成后检查 JSON 可解析、目标组可见,以及需要隐藏的模型仍保持隐藏。
- 重启后从客户端模型列表和实际请求两处分别核对;仅看配置文件不算生效。
- 同时保留「目录过期」和「组被停用」两个候选原因,分别用目录内容与
disabled回查。
目录中的个人模型选择属于私有配置,不写入通用 Skill。此机制与 magpie group listed=no
是不同层级:前者控制客户端可见目录,后者控制 Magpie 是否单独列出组成员。
9.3 辅助模型与路由组
会话标题、描述/摘要、输入预测、自动审批/复核、记忆提取、压缩等辅助调用,是否走当前路由组 取决于客户端:有些允许单独指定模型,有些继承主会话,有些使用固定内置模型,版本之间也可能变化。 不能假定绑定了 Smart Split 就自动接管所有辅助调用。
处理原则:
- 不承担关键判断、安全审批或长上下文压缩的辅助调用,若客户端允许独立指定,优先使用低成本且能力 已核实的明确模型。
- 压缩、记忆、自动审批等会影响后续上下文或安全边界的调用,不能只按价格降级;先核能力、 失败方式和用户可接受的权限范围。
- 未被客户端暴露为可配置项的调用,保持当前实现并标
NOT_VERIFIED,不要为了“统一入口” 伪造一个并未生效的绑定。
核验方法:
- 从安装版客户端帮助、配置 schema 和实际回读确认是否存在独立模型字段;未读到不等于不存在, 先记录具体缺口。
- 保持业务内容不可读,仅触发一次代表性辅助行为,再用
magpie usage的时间窗、请求类型、 provider 和 served model 定位对应记录。 - 无法区分辅助请求与主请求、usage 没有记录、或客户端版本不支持时,标记
NOT_VERIFIED; 不以主会话落点推断辅助调用也已覆盖。 - 具体模型值和是否启用由当次配置 owner 决定,本参考不写个人账号、额度或模型 ID。
10. 证据边界与文档边界
已核对:CLI 字段语义、smart/rotate/weight/manual、pattern 展开、嵌套深度和规则语义来自
0.1.1307 安装版 magpie --version / magpie group --help / magpie group rule --help。
disabled、fallback 覆盖、组目标、stays/affinity、GUI/CLI 同写和配置回读来自版本核验
及隔离 HOME/XDG 探针,证据范围限于 0.1.1307 和所测配置;升级后必须重测。
§2.7 的回环解析绕过全局代理、provider choice 与 loopback 例外,§2.8 的全局直连与
provider 级代理两层语义(direct 与 "" 的区别、ProxyChoice 取值顺序、EnvWith
对登录类子进程的影响,以及进程内签到请求受全局值影响但不经 EnvWith),§2.9 的
unready/then 承接与分类器 fallback=previous,
§2.10 的顺序路径与 pause 无 intent 条件,
§3.1 的兄弟嵌套组共享成员折叠规则,以及 §3.2 的外层 affinity 对经外层请求生效,
来自上游 tag v0.1.1307 的
netproxy、gateway/rules、gateway/classify、gateway/fallback、gateway/affinity
与 provider/group 源码核对。§2.8 的代理优先级另以上游 tag
v0.1.1371 为准,来源链接在该节;不依赖跨版本逐字节一致的假设。升级后先复核相关模块。
仍为 NOT_VERIFIED:
- 调整配置后的真实 served model 分布、失败回退和嵌套组逐层接管行为;必须按本文验收。
- runtime
order数组的展开/排序算法,以及它是否直接等于完整尝试序列;不能用该数组反推 配置成员顺序或官方order合同。 weight配置在order路由下是否仍参与运行时选择;help 只定义它在weight下的语义, 未提供order下的结论。- 计点层溢出的实际占比、成本和停止阈值;本文只给检查方法,不预设数值。
routing=weight在多账号展开后的实际比例。- 辅助调用是否可独立指定模型、是否被统一组接管,以及客户端目录重建后的可见性。
- provider 级代理字段能否由 CLI 写入(当次安装版 CLI 报
unknown field,只在应用界面可设)。 - 全局直连下,登录类厂商 CLI 子进程与各供应商的进程内签到请求需分别验证; §2.8 只给出影响边界与核对方法,不保证所有登录路径可用。
- 组内强模型在额度长期耗尽的前置层下会被消耗多少,无法预先量化。
stays=auto与直接请求嵌套组时的粘滞在跨层回退后的具体保持时长,未做运行时复验; 本文只记录源码语义与验收方法。- 上游 GUI 与配置文件之外的机制未全量审计;“没有规则未命中移出回退的开关”限于已核
0.1.1307 配置模型与帮助。
model_catalog_json应按静态目录治理:只有明确重建并回读后,才假设目录内容变化; 重建后的客户端可见性仍需按 §9.2 验证,不能由配置文件存在本身证明。
不把 CLI 帮助语义、配置回读或一次观测混合成因果证明;实际行为以代表性请求和 served model 为准。
11. 边界
- 不自动开启停用供应商、消耗卡、改全部客户端默认模型或启动 worker。
- 维护具名组不等于激活所有使用者;启用与配置是两次独立授权。
- 不把个人额度、账号或具体 provider 模型 ID 写进通用 Skill 文档;留在
config/*.local.json与state/私有层,不进版本库。 - 本文记录的是 0.1.1307(§2.8 另经 0.1.1371 核对)的实测行为;升级后重新核对 CLI 语法、 配置字段和落点。