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.

referencesinventory.md

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

盘点结果解读

本文解决什么问题 / 何时读:拿到 magpie-inventory.v1 盘点快照后,用本文逐段读懂字段含义、风险提示与各自的处置入口;在据此做任何配置变更决策前,先读「边界声明」。

本文的字段名、层级与风险 code 全部对齐同仓库的权威示例 config/inventory.example.json。本文不另立字段名,也不另立风险码;示例之外的检查项按「扩展检查项」单独标注。

本文中的脚本与路径以 Skill 安装目录 <skill-dir>/ 为基准:命令在该目录下执行,盘点快照与本机私有层文件分别位于同一目录内的 state/ 与 config/*.local.json,不入库。

权威示例

项 说明
权威示例 config/inventory.example.json
性质 脱敏盘点输出格式示例,所有标识与计数均为占位,不代表任何真实环境
自带说明 示例的 notes 数组写明占位声明、各 risk code 释义、severity 取值与账号脱敏约定
读法 字段名、层级、code 集合以示例为准;真实快照以实际输出为准,两者不一致时按待修问题反馈,不在阅读时临时换名

示例中的 example-agent-a、example-provider-a、group/example-main、group/example-subagent 都是占位标识;accounts: 2、visible_models: 0 这类计数同样只是占位。

边界声明

盘点结果是只读快照,不是事实源。

  • 盘点反映某一次生成时刻的可见状态。generated_at 之后发生的任何变化都不在快照内。
  • 盘点可能部分覆盖:某个字段读不到就是读不到,记为缺失或未知,不是 0,也不是「没有」。
  • 真正的事实源是 Magpie 自身配置与请求日志(usage / routing log);盘点只是它们的一次投影。
  • 快照会过期:做变更决策前要重新盘点。上一次盘点不能当作当前状态使用。
  • 盘点不评估任务质量,也不提供派发授权。它不判断某个模型是否够用,也不代表可以向某个组派活。

段内字段的缺失语义统一为「未知」:读不到就留空,不写 0、不写 false、不写空数组充数。

顶层结构

magpie-inventory.v1 由四段加四个元字段组成:

字段 类型 含义 谁在用
schema string 恒为 magpie-inventory.v1,用于识别格式 使用者与配套脚本;格式不匹配即停止解读
generated_at string 本次盘点生成时刻(ISO 8601,UTC);全篇「当前」以它为准 使用者判断快照新鲜度
magpie_version string 产出该盘点的 Magpie 版本 使用者判断字段口径是否与当前版本一致
agents array 各客户端的模型可见性、当前模型与是否经由网关路由 使用者排查「改了组为什么没生效」
providers array provider 及其模型、账号、能力与启用状态 使用者做额度与能力判断
groups array routing group 的路由模式、成员与规则、层宽 使用者做路由治理
risks array 本次盘点识别出的风险项(含严重度、成因与落点) 使用者决定是否处理;不自动执行
notes array 快照自带的口径说明(占位声明、code 释义、severity 口径、脱敏约定) 使用者读盘时的第一手说明

notes 与 schema 一样属于快照的一部分:读盘时先读 notes,它给出的口径优先于任何外部经验。

盘点入口脚本

只引用入口,不在此改变其设计:

脚本 用途
scripts/magpie_inventory.py scan 只读盘点,产出本文描述的 magpie-inventory.v1 快照(agents/providers/groups/risks/notes)
scripts/magpie_route.py inspect 只读快照,内容是 providers/groups/可选 quotas,字段与本文口径不同,别当同一份快照读
scripts/magpie_observe.py 只读观测与诊断,产出观测与诊断记录
scripts/magpie_change.py 变更前后态对比
scripts/magpie_outcomes.py 成果与用量归档

盘点是只读动作:不写配置、不登录、不消耗额度。

注意 magpie_route.py inspect 也把 schema 标成 magpie-inventory.v1,但它不含本文描述的 agents、risks、notes,多了 observed_at 与 quotas。两者字段集不同,读盘时先看实际字段,不要按 schema 名直接套本文的段落口径。

agents 段

agents[] 逐客户端描述「这个客户端的模型请求落在哪里」。

字段 含义
name 客户端名(如某个 harness 或原生客户端)
model 该客户端当前主模型
subagent_model 该客户端的子 Agent 模型;未单独指定时为继承主会话
subagent_effort 该客户端子 Agent 的推理档位
gateway_routed 该客户端的模型请求是否经由 Magpie 网关
visible_models 该客户端可见的模型数量

gateway_routed 的含义

  • 为真:该客户端的请求经由 Magpie 网关,改 Magpie 的组、成员与规则会影响它的落点。
  • 为假:该客户端的请求不在 Magpie 路由治理范围内。它可能是原生直连,或在客户端侧写死了模型。

必须强调:gateway_routed 为假的客户端,改 Magpie 的组不会影响它。对这类客户端谈「组内分层」「回退」「规则命中」都不成立;要改它,得改客户端侧配置,并按子 Agent 模型指定核实际生效位置。

两点补充:

  1. 网关只看请求携带的模型名,不区分主会话与子 Agent 角色;agents= 类规则是按客户端匹配的,不是通用父子角色开关。
  2. visible_models 是可见性,不是路由关系。客户端可见某个模型,不等于该模型的请求经由网关。

subagent_model 与 subagent_effort

  • subagent_model 未单独指定时,子 Agent 不会因此自动继承主入口的意图分流;它会沿该客户端的继承/默认链落到统一默认或普通组。若需要子代理走意图入口,必须把子代理默认显式指向该入口并验证规则命中。
  • subagent_effort 是子 Agent 侧的推理档位,与主会话档位是两件事;子 Agent 模型的档位支持范围由该模型所在 provider 的能力决定。
  • 两项都不指定时,对应本盘点格式里的 SUBAGENT_REENTERS_MAIN_ROUTE 风险项。

providers 段

providers[] 逐 provider 描述「有哪些来源、它们能做什么、当前是否启用」。

字段 含义
id / name provider 标识与显示名
models 该 provider 当前暴露的模型数量(示例中为占位计数)
accounts 该 provider 下的账号数量
account_labels 脱敏账号标签列表(见「账号为什么只以脱敏标签出现」)
multi_account 该 provider 下是否配置了多个账号
enabled 该 provider 当前是否处于启用状态
account_order_set 显式账号顺序的确认状态,三态(见下)
capabilities 能力描述对象,含 vision 与 reasoning_efforts 两项(见下)

accounts 给数量,account_labels 给脱敏标签列表:数量用于判断是否存在账号间选择空间,标签用于把快照里的每个账号对回其脱敏身份。

计数与来源数只表示配置候选

盘点里的 models、accounts、members 以及层内来源数,都只表示配置候选数:

  • 不等于独立账号容量。同一 provider 下的多个账号可能共享同一套餐池,一处打满会同时影响多个候选。
  • 不等于实时健康。成员是否当前可服务、额度窗口是否读得到,要另按盘点风险项与运行时记录核;快照里的计数不表示此刻都在线。

计数只用来回答「结构上有没有第二选择空间」,不用于承诺容量或可用性。

multi_account:两种行为差异

multi_account 为真表示该 provider 下有多个账号,于是「选哪个账号」成为一个真实决策。两种行为:

行为 触发条件 含义
默认按余量智能挑选 provider 账号层未确认显式顺序 在有剩余额度的订阅中优先选择最先重置的账号;不是「免费优先」规则
显式账号顺序 provider 账号层配置了显式顺序 按账号在顺序表里的位置依次尝试,便于核对回退链

multi_account 为假(单账号 provider)时,没有账号间的选择空间:并发上限、队列等待等限制以账号级为准,组内 routing 不能替代账号级限制,路由策略也改变不了该 provider 的容量。

-### account_order_set:三态,不要读成布尔结论

取值 含义
true 读取路径确认该 provider 存在显式账号顺序
false 读到了该 provider 的账号顺序字段,其中没有显式顺序条目
null 未知:读取路径未覆盖持久化账号顺序(CLI 未暴露该顺序等)

判读口径:

  • 读取路径看不到持久化账号顺序时(CLI 未暴露该顺序、登录记录不在读取范围内等),应输出 null,而不是用别的信号拼一个布尔结论。
  • null 只表示「读不到」,不表示「没有顺序」,更不表示「一定按余量智能挑选」。
  • 不能从并发配置(accountConcurrency)、账号 active 状态或「某个 accountOrder 字段缺失」推导存在显式账号顺序;这些只说明并发或启用状态,不说明账号先后次序。
  • 也不能据 null 或 false 断言该 provider 走 smart 语义。smart 只是没有显式顺序时的一种可能,实际落点以 provider 账号层设置与运行时 per-try 记录为准。
  • ACCOUNT_ORDER_UNSET 风险的含义是「未能确认显式账号顺序,需要回读」,不是「已确认没有顺序且一定按余量挑选」。

接入方式、账号级并发与队列、以及账号顺序的三层载体(请求参数、持久化位置、运行时观测)见供应商与账号接入。

capabilities:字段级口径

capabilities 描述该 provider 支持的能力,示例给出两项:

能力项 字段 含义
图像输入 vision(boolean) 该 provider 是否支持图像输入
推理档位 reasoning_efforts(array) 支持的 effort 档位列表;请求的档位不在列表内时按「就近映射」而非报错

能力差异直接影响分组:

  1. 成员在当次任务能力上可互换才适合同组;能力不可互换时按能力分层,每层准备多个来源。
  2. 能力层用嵌套组表达时,「组存在」与「已接进唯一入口」是两件事,要分别核对。
  3. 硬性要求(长上下文、图像、工具调用)的成员若被放进同一回退链,前层失效时请求会落到不具备该能力的成员上。

能力缺口的判定口径见路由治理的成员分层一节。

额度信息不在盘点结构内

盘点快照不含额度窗口字段。额度、订阅到期时间与账号级并发窗口要在观测与配额查询中读取,不要在盘点输出里找对应字段,也不要用盘点推算余量。额度类型划分、任务档位与成本边界见额度、任务与成果。

groups 段

groups[] 逐 routing group 描述「成员有多少、按什么模式选、层是否够宽」。

字段 含义
id 组标识
routing 路由模式(组级)
stays 会话保持语义(组级)
members 组内成员数量(示例中为占位计数)
rules 组内规则条数(示例中为占位计数)
single_source_tiers 当前只有唯一可用来源的层(层标识列表)

single_source_tiers 怎么算

判定口径:某一层(或某个组)当前只有唯一可用来源时,判定为单来源。

  • 判据是当前可用来源数为 1,不是「成员数为 1」。成员存在但都处于不可服务状态时,该层同样没有可用来源。
  • 盘点只标出是哪一层单来源,不替用户决定该层是否必须补宽。
  • 嵌套组按内层自身的可用来源判定;外层成员里放着一个组,不等于外层多了来源。

为什么是风险:该来源额度打满或被限流后,这一层整体失效;请求会穿透到下一层,或在整条链都不可用时直接失败。层内来源数、当前可用数与路由方式应在变更前后分别回读。

一条容易误判的事:额度休息、供应商关闭与成员移除在盘点上不是同一种状态。判定口径与实测差异见路由治理;本文只提醒不要把「休息」直接读成「该层没被引用」或「模型已下线」。

成员数量、routing 模式、stays 与规则在盘点里的呈现

项 盘点呈现 注意
成员 members 给成员数量 成员清单与配置顺序以组配置为准;pattern 成员的呈现与展开口径见路由治理
routing 模式 组级 routing 字段 模式取值与各模式的实测差异见路由治理
stays 组级会话保持字段 配置里存为 affinity,按 stays 键核会误判为未写入;null 表示默认值,不表示失败
规则 rules 给规则条数 规则命中目标与实际落点要分开断言,二者不一致时的排查路径见路由治理

嵌套组的表示

  • 内层组在组配置中作为一个成员槽位出现(形如 group/<group-id>),不是一个被展开的模型列表。
  • 嵌套关系不单列字段:盘点用 single_source_tiers 标出单来源层,用 members 给出成员数量。
  • 内外层的 routing 与规则相互独立:外层写 order 不会把内层也变成固定顺序。
  • stays 不独立:会话保持只由外层 affinity 对经外层请求生效;内层 stays 只在直接请求内层组时生效。
  • 内层为空、全员休息或已停用时,外层不会因为「引用存在」就获得该能力。
  • 嵌套深度上限是结构约束,不是成本授权。

risks 段

risks[] 是检查项,不是判决:它指出「这里值得看一眼」,是否处理、如何处理由用户决定。盘点不会自动改配置。

每个风险项的四个键

键 类型 含义
code string 风险类别标识,取值见下表
severity string 严重度:info / warn / high 三档;由盘点者按当次成本边界判定,不是固定标签
detail string 成因说明(自然语言);同一 code 在不同环境下的 detail 不同
where string 落点:问题所在组、provider 或客户端的标识

severity 只用 info / warn / high 三档,取值集合固定;不同环境不会出现 medium / low。严重度本身依赖当次成本边界:同一条风险在不同额度水位下可以判成不同档。读盘时以快照里的 severity 为准,不套用历史结论。

风险是提示,不是纠错结论

盘点里的风险项只说明「这里值得看一眼」。有些风险项的触发输入直接来自本机画像 config/profile.local.json(昂贵模型标记、辅助路由目标、主入口组),画像记录的是用户已确认的意图;另一些风险项的触发来自配置本身(跨层 fallback 字段、组成员可服务状态等),但同样要回到画像与用户确认的意图去核。

因此:

  • 跨层回退(CROSS_LAYER_FALLBACK)可能是用户有意设计的兜底链,不按错误处理;
  • 辅助请求走组外(AUX_CALLS_OUTSIDE_GROUP)可能是客户端侧本就独立指定模型的形态,不等于配置漏配;
  • 混合资源池(不同成本档位成员放在同一组)常常是用户确认过的成本边界。

处置顺序固定:先按画像与用户确认的意图核意图,再决定是否调整。判定为有意设计时保留现状并记录理由,不要一律纠错、不要按风险项直接改配置。

权威风险码(示例中的 7 个)

code 成因 处置建议
SINGLE_SOURCE_TIER 某一层或某个组当前只有唯一可用来源 为该层补第二个来源,或明确接受该层失效时穿透到下一层;见路由治理
EXPENSIVE_FALLBACK 高成本模型位于回退链上,前层不可用时会被兜底消耗 确认该高成本成员在链上的位置与触发条件;确认后前移更省的来源或收紧回退范围
SUBAGENT_REENTERS_MAIN_ROUTE 子 Agent 默认模型未单独指定,可能沿默认链落到非预期入口,且不会自动继承主入口意图分流 显式指定子 Agent 模型/入口与档位,并验证实际 served;见子 Agent 模型指定
CROSS_LAYER_FALLBACK 存在跨层回退路径,请求可能落到非预期能力层,成本与归因口径不一致 用真实请求读 served model 与逐次尝试序列确认落点;必要时收紧外层成员。落点检查一并在此项下做:把「规则命中」与「实际落点」分开断言,不要用规则命中推断实际服务模型
ACCOUNT_ORDER_UNSET 多账号 provider 未能确认存在显式账号顺序,实际落点由 provider 账号层的默认策略决定 回读账号顺序本身,确认是按余量挑选还是有确定次序;见供应商与账号接入
AUX_CALLS_OUTSIDE_GROUP 网页搜索、压缩、会话标题等辅助调用未纳入当前入口组 逐项核客户端是否允许独立指定模型;不假定绑定组即接管全部辅助调用
DEAD_MEMBER 组成员当前不可服务:provider 已停用、模型未暴露等 核该成员当前可服务状态;不等于额度耗尽,不要按额度问题处理。已停用的 provider 记录可保留供其它用途,是否移出活跃组由用户决定

已归并的旧检查项

下表只用于对照:左列是已废弃的旧检查项名称,不再出现在盘点输出里;其成因与处置已并入右侧的权威风险码。

旧检查项 归并到 说明
规则命中与实际落点不一致 CROSS_LAYER_FALLBACK 落点检查并入该码的处置建议
成员当前不可服务 DEAD_MEMBER 语义等价,仅保留权威码
provider 已停用 DEAD_MEMBER 作为该码的成因之一
多账号未设显式顺序 ACCOUNT_ORDER_UNSET 语义等价,仅保留权威码
辅助调用绕过路由 AUX_CALLS_OUTSIDE_GROUP 语义等价,仅保留权威码

扩展检查项(实现脚本当前示例未包含)

以下检查项是盘点可能报出的补充项。实现脚本当前示例未包含,属扩展检查项;它们与上表 7 个权威码不构成同一集合,读者在盘点输出里见到时按扩展项理解,不要假定它们必然出现,也不要把它们当作权威码引用。

检查项 成因 处置建议
ACCOUNT_QUOTA_REST 账号处于额度休息 这是会自己过期的时间窗,不是配置错误;等待过期或由下一层承接
GROUP_DISABLED 路由组被停用,不响应请求 由用户在应用界面的路由页确认开启;不要用 CLI 反复试探
GROUP_HAS_DISABLED_MEMBER 组内存在已停用成员 回读成员状态与规则引用后逐项处理;已停用成员仍被规则引用时先解引用
AGENT_NOT_GATEWAY_ROUTED 客户端模型请求不经由 Magpie 网关 该客户端不在路由治理范围内;改 Magpie 的组不会影响它
QUOTA_WINDOW_UNKNOWN 额度窗口读不到(多窗口中部分缺失) 保留未知,不写 0;不据短窗口余量承诺可持续批量执行

账号为什么只以脱敏标签出现

理由:账号身份是私密信息。盘点结果仅留本地 state;需要公开样例时使用合成数据,不能把本机快照直接当作夹具或入库。

脱敏后仍然保留的可用信息:

保留项 盘点中的位置 用途
扫描内标签 account_labels 同一 provider 本次扫描内区分账号;不表示实际 accountOrder,也不保证跨次稳定
所属 provider providers[].id 归属与容量归因
是否多账号 multi_account 判断是否存在账号间选择空间
账号数量 accounts 判断该 provider 的账号规模量级

盘点输出不包含:key、token、cookie、完整邮箱、完整账号 ID。账号只以 account-<n> 标签出现;邮箱片段、域名、昵称与上游半遮罩都不回显。映射只在本次扫描内存中存在,按 provider 独立编号,不落盘。示例的 notes 也重申了这条约定。

从盘点到下一步

下表指向同一发布中的配套参考文档,按「在盘点里看到什么」选读:

盘点里看到什么 下一步读
第一次配置、客户端接入、网关地址与可见性 入门
要建组、排组内顺序、做能力分层与模板 路由模板
多账号 provider、账号级并发与队列、额度窗口与刷新 供应商与账号接入
已有组的成员、路由模式、规则与嵌套回退异常 路由治理
额度类型、任务分层、成本边界与临期额度 额度、任务与成果

盘点只回答「现在长什么样」,不回答「应该怎么调」。要改,先读对应文档确定判据,再按操作入口与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