Index of every page on this site: llms.txt
All skills
cat-xierluo avatar

/magpie-optimizer

@5fb69a0
Run it yourself

用 Magpie 配置并优化 AI 工作效能:接入供应商、订阅与插件,配置模型路由组与意图规则,管理网关、可见性、共享 MCP 与搜索;盘点额度与套餐,诊断 Token 消耗与限流,把每次调整关联真实任务验收效果。

Use this Skill: https://skilld.dev/gh/cat-xierluo/legal-skills/magpie-optimizer

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesrouting-governance.md

≈9.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

路由治理:把一个组做成用户唯一入口

面向「客户端只绑定一个组,不在具体模型之间手动切换」的部署与排障。 基于 Magpie 0.1.1307 的版本核验,结论按该版本记录;换版本后先用 magpie --version 和原生帮助复核。

以下命令在 Skill 目录内执行,scripts/、config/、state/ 均相对该目录。

职责分工:

  • smart-split 是入口设计和规则语义的权威说明。
  • cli-contract 与 operations 约束 CLI 写入和变更流程。
  • token-strategy 维护额度类型、任务档位和成本边界。
  • 本文只记录统一入口落地时的排障顺序、版本实测差异和验收检查;不另立一套规则语义。

0. 治理目标

用户只设一个组入口,其余分层都在组内解决。配置合格的四条判据:

  1. 客户端只绑定组 ID,不改具体模型。
  2. 不同难度能落到预期能力层,并可从 usage 的 served model 读回。
  3. provider 额度耗尽或限流时,路由链有明确的下一落点;整条链都失败时仍如实返回错误。
  4. 成本顺序符合当次已确认边界:若用户已确认某个池可混合免费、赠送额度与套餐后备, 保留该设计;若当次目标明确硬性零消耗,才建立或拆出只含免费资源的入口。

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 分支,表现为先解析、 后直连回环地址失败。

判据顺序:

  1. 先看报错里的地址:目标是 127.0.0.1(或本机回环)时,先核对主机解析来源与本地服务, 不要先改代理规则。
  2. 用代理单独访问该域名,确认代理侧可达(拿到真实响应即证明代理链路通)。
  3. 再决定是修本机解析还是给 provider 指定代理。provider 级代理优先:它不动系统文件, 可随时回退。
  4. 源码结论绑定 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 和 provider Proxy,仅当 AccountProxies == nil 且 Proxy == "" 时,改从配置里保存的 同名记录读取,再按账号级 → provider 级取值。storedPicks 是空值时的替代来源,不是 第三级顺序回退。
  • 账号层:经 ViaLogin / ViaSignedIn 发出的请求先取账号自己的非空 choice,再取 provider 的;两者均未指定时才继承全局。因此有显式代理的账号可在全局 direct 下继续 走代理,没有显式 choice 的账号会受全局值影响;不是所有登录路径都自动经过这些函数。

所以「全局直连 + provider 级代理」是可行且可回退的组合,但有三条边界必须先核:

  1. 先核哪些出口真的需要代理。 直连可达的供应商不必绕远;对每个供应商域名分别做 「直连」与「经代理」两种探测。同一目标直连失败而经代理可达,才支持该环境下选代理; 两种都失败应标为未定位,继续查解析、代理出口、TLS 或服务端错误,不能据此断言代理有效。 两种都可达则按稳定性与延迟选择。收到真实 HTTP 响应只证明链路可达,不证明登录或模型 调用成功。判断依据是探测结果,不是厂商地区或既往个人环境的结论。
  2. 改全局值会影响的不只是网关。 netproxy.EnvWith(choice, env) 先取显式 choice, 仅在它为空时读取全局值;有效值为 direct 才移除子进程的代理环境变量。带显式 provider 代理的调用不因全局 direct 自动直连;厂商 CLI 自己的配置或系统透明转发仍需另核。 部分签到请求由网关进程内发出,不经过 EnvWith;走全局还是账号/provider choice, 取决于该请求是否携带对应上下文,不能仅凭「签到」或「登录」名称判断。 改完要单独验证一次登录态刷新、签到读取与 provider 连通性测试,不要只看网关请求。
  3. 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 目标保持不变。

所以「规则命中」和「实际落点」必须分别断言:

  1. 从请求日志读 rule(命中的规则号与 use 目标)。
  2. 分别读 rule.unready/then/instead 与 rule.classified.error/fallback,区分目标不可用、 后续规则承接和分类器回退。
  3. 从同一条的 tries 读尝试序列与状态,从 served 读最终服务模型。
  4. 出现不符时,先查成员是否处于额度休息或分类器是否失败,再谈配置顺序;休息状态是 会自己过期的时间窗, 不是配置错误。

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 能力层要显式接进入口,且每层准备多个来源

能力层用嵌套组表达时,先把「组存在」和「组已接进唯一入口」分开核对:

  1. magpie groups 只能证明组存在,不能证明外层入口会选到它。
  2. 回读外层入口的完整 members,确认每个需要独立承接的能力层都有显式引用。
  3. 回读内层 members、routing、stays 和 off 状态,确认至少有一个当前可服务来源。
  4. 用直接请求和经外层入口的请求分别看 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 需要区分三层事实:

  1. 配置成员顺序:providers.json 或 magpie group <id> 回读到的成员列表。 显式命名成员按配置顺序排在前面;pattern 成员保留 pattern 本身,后续按当时模型目录 列出的顺序展开,新匹配模型会加入、失效匹配会离开。配置回读必须同时看显式成员、 pattern 和当前展开数量,不能把 pattern 的动态展开误当成手工调序失败。
  2. 版本内语义合同:当前 CLI help 明确 order 是第一个成员直到不能应答,再下一个; 这是本版本可依赖的官方合同。
  3. routing log / usage 观测:routing log 中的 runtime order 数组、账号展开、失败后重排、 per-try tries 和 served model 是运行时证据,不能反推配置成员顺序,也不能单独用来否定 第 2 层合同。usage CSV 可用于最终 provider/model、状态和错误聚类;本证据边界未核到 per-try 序列,完整 try 链应从 routing log 或逐请求日志核对。

因此,不得把 runtime order 数组与配置列表不同直接解释为“调序无效”或“order 语义未证”; 只能说该样本尚未解释 runtime 数组的展开/排序方式。若要验证配置顺序的因果效果,须固定其他配置, 只调整成员顺序,逐请求记录每次 try 序列和 served model。

6. 计点层的有界溢出

计点或按余额付费成员只能作为明确授权的兜底层,不能成为免费池失败后的无界泄压区。 落地时同时满足:

  1. 容量有界:在 provider 账号级设置并发上限和有界队列;这些限制跨模型、组和客户端共享。 起点沿用 token-strategy 的保守建议,按观测调整,不在本文复制数值表。
  2. 路径有界:回读计点 provider 的 fallback、计点成员所在的外层/内层组、嵌套引用和 rules。 计点层通常是终点;若配置了继续向外扩散的 fallback,必须确认其成本授权。若某时段绝不允许 计点消耗,用 pause 硬排除或移出该成员并回读,不靠排序或 use 猜测。
  3. 观测有界:按实际 served provider/model 统计请求占比、错误率、延迟分位和并发峰值; 成本以余额或账单读数为准,价格缺失写 unknown,不用目录价冒充实付。
  4. 停止条件明确:计点层请求占比短窗突增、其错误率/延迟显著恶化,或免费层错误类型 从排队变为额度耗尽时,先停止计点层承接并修复上游,不继续用重试扩大消耗。停止动作应是 可回读的 pause、成员移除或经核实语法的 fallback 重写;执行后核对 routing log 不再出现 计点成员 try。不要为了快速止损直接整文件回滚 providers.json,以免覆盖并发写入者。

嵌套深度上限是结构约束,不是成本授权;允许 8 层不表示可以配置 8 层计费回退。

7. 免费窗口迁移验收

免费期、赠送窗口或订阅窗口结束时,不能只改组名或删除成员。迁移验收至少包含:

  1. 固定日期边界和时区,区分订阅周期、免费窗口和点数批次到期,不以一种时间替代另一种。
  2. 重新核候选模型暴露状态、额度类型和服务状态;失效成员从活跃组移除或明确保留原因。
  3. 保存迁移前配置快照、成员、规则、fallback、并发和队列到 state/ 私有层,绑定内容哈希。
  4. 对每个能力层发真实代表性请求,不只做配置回读。
  5. 用 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 新增模型而自动刷新。即使组已配置成功, 旧目录也可能让客户端看不到新组。每次新增组或升级模型后,都要重新生成目录、回读内容并重启客户端; 只重启而不重建目录不能保证新模型出现。

落地检查:

  1. 记录当前目录路径、内容哈希和生成来源,确认它确实被客户端配置引用。
  2. 重新生成后检查 JSON 可解析、目标组可见,以及需要隐藏的模型仍保持隐藏。
  3. 重启后从客户端模型列表和实际请求两处分别核对;仅看配置文件不算生效。
  4. 同时保留「目录过期」和「组被停用」两个候选原因,分别用目录内容与 disabled 回查。

目录中的个人模型选择属于私有配置,不写入通用 Skill。此机制与 magpie group listed=no 是不同层级:前者控制客户端可见目录,后者控制 Magpie 是否单独列出组成员。

9.3 辅助模型与路由组

会话标题、描述/摘要、输入预测、自动审批/复核、记忆提取、压缩等辅助调用,是否走当前路由组 取决于客户端:有些允许单独指定模型,有些继承主会话,有些使用固定内置模型,版本之间也可能变化。 不能假定绑定了 Smart Split 就自动接管所有辅助调用。

处理原则:

  • 不承担关键判断、安全审批或长上下文压缩的辅助调用,若客户端允许独立指定,优先使用低成本且能力 已核实的明确模型。
  • 压缩、记忆、自动审批等会影响后续上下文或安全边界的调用,不能只按价格降级;先核能力、 失败方式和用户可接受的权限范围。
  • 未被客户端暴露为可配置项的调用,保持当前实现并标 NOT_VERIFIED,不要为了“统一入口” 伪造一个并未生效的绑定。

核验方法:

  1. 从安装版客户端帮助、配置 schema 和实际回读确认是否存在独立模型字段;未读到不等于不存在, 先记录具体缺口。
  2. 保持业务内容不可读,仅触发一次代表性辅助行为,再用 magpie usage 的时间窗、请求类型、 provider 和 served model 定位对应记录。
  3. 无法区分辅助请求与主请求、usage 没有记录、或客户端版本不支持时,标记 NOT_VERIFIED; 不以主会话落点推断辅助调用也已覆盖。
  4. 具体模型值和是否启用由当次配置 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 语法、 配置字段和落点。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts18d3 checks · Risk SAFE
  • Gen Agent Trust Hub18d

    This skill provides a robust and security-conscious framework for managing AI model routing and telemetry via the Magpie CLI. It includes extensive defensive measures such as local-loopback-only network enforcement, restricted file permissions (0600), comprehensive credential redaction logic, and a self-auditing suite to prevent secret leakage.

  • Socket18d

    No alerts

  • Snyk18d

    Risk: LOW · No issues

Signed by skilld at 5fb69a0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated yesterday
Other metadata
metadata
{
  "version": "1.8.1",
  "author": "杨卫薪律师(微信ywxlaw)",
  "homepage": "https://github.com/cat-xierluo/legal-skills"
}

README badge

README badge for cat-xierluo/legal-skills/magpie-optimizer