盘点结果解读
本文解决什么问题 / 何时读:拿到 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 模型指定核实际生效位置。
两点补充:
- 网关只看请求携带的模型名,不区分主会话与子 Agent 角色;
agents=类规则是按客户端匹配的,不是通用父子角色开关。 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 档位列表;请求的档位不在列表内时按「就近映射」而非报错 |
能力差异直接影响分组:
- 成员在当次任务能力上可互换才适合同组;能力不可互换时按能力分层,每层准备多个来源。
- 能力层用嵌套组表达时,「组存在」与「已接进唯一入口」是两件事,要分别核对。
- 硬性要求(长上下文、图像、工具调用)的成员若被放进同一回退链,前层失效时请求会落到不具备该能力的成员上。
能力缺口的判定口径见路由治理的成员分层一节。
额度信息不在盘点结构内
盘点快照不含额度窗口字段。额度、订阅到期时间与账号级并发窗口要在观测与配额查询中读取,不要在盘点输出里找对应字段,也不要用盘点推算余量。额度类型划分、任务档位与成本边界见额度、任务与成果。
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 与变更边界走带回读的变更流程。