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.

referencespreflight.md

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

环境体检详解

本文解决什么问题 / 何时读:使用 magpie-optimizer 之前,或排查环境问题时,用 scripts/magpie_preflight.py check 看清本机此刻的可观察状态——CLI 是否可用、配置是否可读、网关是否通、路由日志是否可查、是否存在两个配置写入者——并据此决定下一步是「可以动手」「先修环境」还是「先问用户」。需要读懂某个 check 的判定依据、ok / warn / fail 各自的含义,或需要判断某个 FAIL 是否必须修时,读本文。

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

体检的定位

体检是只读的,输出的是「此刻可观察到的状态」,不是「配置是否正确」的结论。

  • 只做读取:读文件、读进程状态、读本机 HTTP 接口、列目录。不写配置、不改路由、不登录账号、不消耗模型额度。
  • 不评判意图。组里放什么模型、混合池是否有意为之、某条直连路径是否该保留,属于用户已确认的设计,体检不据此判 FAIL。
  • 判据只落在「能不能观察、能不能继续」上。配置语义是否合理,不在体检范围。
  • 结果不构成变更授权。它不替代变更计划、配置哈希绑定、漂移检查、写入后回读,也不替代真实请求验证。
  • 是一次快照。体检结束到实际动手之间配置可能已被改动;结论过期时重跑,不沿用旧快照。
  • 不代替验收。体检不判断任务质量,也不签发任何完成标记。

体检怎么运行

python3 <skill-dir>/scripts/magpie_preflight.py check --output <skill-dir>/state/preflight.json
项 说明
输入 只读本机状态;不接收配置内容作为写入指令
输出 state/ 下的 JSON;字段白名单,不含凭证、账号与私密内容
权限 输出文件 0600,落在 Skill 目录内的 state/ 私有层,不入版本库
只读保证 不调用任何写子命令;不执行 magpie 写操作
可选深度项 额度读取、进程探测等可以按需关闭;关闭时记 NOT_VERIFIED 而非「通过」
与其它入口的关系 scripts/magpie_inventory.py 做脱敏盘点,scripts/public_release_check.py 检查发布条件;三者共用同一只读纪律

退出码只表示体检本身是否跑完,不表示环境是否合格。体检结果看 JSON 里的每条 status,不看退出码。

check code 表

check code 是本 Skill 与 scripts/magpie_preflight.py 之间的约定,实现可调整:以脚本 --help 与实际输出为准,code 名称随脚本版本变化时本文同步更新。下表覆盖当前约定的全部 check;ok / warn / fail 三列分别是「该状态意味着什么」,最后一列是失败时的第一步排查顺序。

check code 检查什么 判定依据(具体看什么) ok warn fail 失败时先查什么
python_runtime 运行本 Skill 脚本的解释器 python3 --version 的主次版本;脚本只依赖标准库,无需 pip 安装 版本满足最低要求,脚本可直接运行 版本偏低但脚本仍能启动,部分代码路径未验证 找不到 python3,或版本低于要求,脚本无法运行 PATH 中的 python3 指向何处;系统自带解释器版本;换用已装的新版解释器重跑,不改脚本依赖
cli_version 已安装 Magpie CLI 是否可用 magpie --version 退出码为 0 且能解析出版本串 可执行且版本可读,后续语法一律以该版本为准 版本可读但低于本 Skill 已核版本,存在语法差异风险 命令不存在、退出非 0,或输出无法解析 安装位置与 PATH;是否换了 shell 环境导致路径不同;先用安装版帮助核对语法,不靠升级掩盖差异
cli_field_support 目标字段 / 子命令在安装版是否存在 magpie <子命令> --help 是否返回该子命令自身的帮助(含目标字段),而不是总帮助 帮助中明确列出目标字段,可按该字段写入 只返回总帮助,能力未证实;既不等于不支持,也不能当作支持 帮助中明确不含该字段,或该子命令被拒 见边界二的五步处置顺序
config_readable 网关配置文件是否可读可解析 在 XDG 约定位置读到配置文件,JSON 可解析;只取字段白名单投影 可读、可解析,字段投影可用 可解析但部分字段缺失,或权限受限导致个别字段读不到 文件不存在、权限拒绝,或 JSON 解析失败 XDG_CONFIG_HOME 是否被覆盖;文件权限与属主;是否存在第二个配置位置同时生效
gateway_reachable 本机网关 HTTP 接口是否可达 对 <gateway-url> 发只读请求,检查状态码与响应结构 可达且响应结构符合预期 可达但结构异常,或延迟明显高于往常 连接被拒、超时,或返回非预期状态 先分清是网关不通还是模型不通,见边界三;地址与 <port> 从实际配置或界面核实
gateway_process 网关进程与监听是否与配置一致 进程是否存在,监听地址是否与配置/界面显示一致 进程在且监听地址一致 进程在但监听地址与配置不一致,可能存在多个实例 找不到运行中的网关进程 是否只装了客户端而网关未启动;是否有旧实例占用同一地址;不为体检去启动或停止进程
agents_detected 本机可见的 harness / agent 客户端 客户端配置目录与关键配置文件的存在性(只列目录,不读私密内容) 得到客户端清单,可作为客户端侧核对的入口 部分客户端配置存在但无法判定当前是否在用 未发现任何客户端配置 客户端安装位置;配置目录是否被环境变量改写
model_catalog_readable 客户端模型目录是否可读可解析 目录文件存在、JSON 可解析、目标组在目录中是否可见 可解析且目标组可见 可解析但目标组不可见;目录是静态快照,不会自动刷新 目录不存在或不可解析 目录路径是否被客户端配置实际引用;目录过期与组被停用是两个候选原因,分别回查(路由治理 §9.2)
model_exposed 目标路由组与成员是否在网关侧暴露 只读列出组与模型;组成员的可服务状态;组的 disabled 标记 组可用且至少有一个当前可服务成员 组存在,但成员处于不可服务状态,或组处于停用标记 组不存在,或客户端绑定直接报「无对应路由组」 组被停用与目录过期要分开断言;绑定报错不等于组不存在(路由治理 §9.1)
routing_log_readable 路由日志是否可读、覆盖窗口多长 本机 routing/YYYY-MM-DD.jsonl(或压缩形式)能读取,行数与时间窗合理 可读且时间窗可用于本轮观测 只覆盖部分日期,或部分字段缺失 不可读、不存在,或内容明显截断 日志目录位置与保留期;核不到该来源时记 NOT_VERIFIED,不用其它日志顶替
quota_readable 额度能否读到(可选深度项) 只读额度接口返回可解析结构 可读,额度窗口与到期信息可核 部分账号读不到,保留未知,不写 0 整体不可读 账号登录态与平台侧刷新;额度读数不能反推配置是否正确,也不等于供应商承诺的容量
proxy_path_risk 请求路径是否可能被全局代理规则误判 供应商主机在本机解析出的地址是否落在私网/回环/CGNAT 保留区间;provider 是否单独指定了代理 解析结果正常,或该 provider 已单独指定代理 存在保留区间解析但当前未观测到失败,属潜在风险 已观测到「解析到回环后直连被拒」的失败形态 先看报错里的目标地址,再决定是修解析还是给 provider 指定代理(路由治理 §2.7)
hosts_loopback_risk 本机解析条目是否把供应商域名指向回环 目标域名在本机解析结果中是否指向本机回环地址(如 127.0.0.1)或同类本地条目 解析到真实地址 存在屏蔽条目,但当前受影响的 provider 未出现失败 解析到回环且相关请求已失败 解析来源与本地屏蔽条目;用代理单独访问该域名验证代理链路是否通
single_writer_risk 当前是否存在两个配置写入者并存的迹象 GUI 是否在运行、本次会话是否即将执行 CLI 写入;两次回读之间配置是否变化 只有一个写入者,或当前处于明确的只读阶段 有迹象但无并发写入证据(例如 GUI 在运行但本轮只读) 已观测到并发写入:两次回读之间配置哈希或成员表发生变化 暂停其中一方的配置编辑,先回读哈希与成员表(边界一)
credential_exposure 输出与报告是否可能带出凭证 报告字段白名单、密钥字段过滤、输出文件权限是否为 0600 无凭证字段,权限正确 输出目录权限偏宽,但内容本身无凭证 出现凭证、账号标识或本机绝对路径 立即停止对外分享该文件;重新生成脱敏版本,并核对是采集端还是输出端泄漏

症状 → 先看哪个 check

体检出错时不要按 check 顺序逐条读,先按症状定位。

症状 先看 说明
脚本根本跑不起来 python_runtime 与 Magpie 无关的解释器问题
命令提示找不到,或版本读不出 cli_version 先确认 CLI 在不在,再谈字段
某个字段写不进、或回读不到 cli_field_support、config_readable 前者是版本能力,后者是存储位置
请求全部失败,但 GUI 里有数据 gateway_reachable、gateway_process GUI 走自己的进程或缓存,不能证明网关可用
只有某一个 provider 失败 proxy_path_risk、hosts_loopback_risk 单点失败优先怀疑解析与代理旁路
刚改的配置不生效 single_writer_risk、model_catalog_readable 先排除并发写入与静态目录过期
客户端里看不到新组 model_exposed、model_catalog_readable 组停用与目录过期要分别断言
找不到落地证据 routing_log_readable 核不到该来源记 NOT_VERIFIED,不换来源顶替
报告不敢发出去 credential_exposure 先止分享再重生成

边界一:GUI 与 CLI 同写配置的风险与「单一配置操作者」纪律

风险。 GUI 会把自身界面状态写回同一份配置文件,可能把刚移除的成员重新写回;CLI 也可能瞬时读到旧状态,例如报组不存在而该组实际存在。两个写入者并发改同一份配置,结果是互相覆盖或漂移:一次写入在「命令返回成功」之后被另一侧悄悄回退,配置哈希与成员表不再是刚才那一版。这类问题不会以报错形式出现,只会表现为「刚改好的规则不生效」或「成员莫名其妙回来了」。

纪律。

  1. 一次变更只有一个操作者。GUI 改完即停用 CLI 对同一目标的写入,或反过来。
  2. GUI 与 CLI 不同时编辑同一份配置,尤其不同时编辑同一个组。
  3. 变更窗口内暂停 GUI 的配置编辑;后台推理无需停止——停的是配置编辑,不是请求处理。
  4. 每次写入后回读:配置哈希、成员表、规则与可配置的路由字段。不以「命令返回成功」作为唯一证据。

体检如何发现迹象。 single_writer_risk 从两侧取迹象:一侧是 GUI 进程是否在运行、本次会话是否即将执行 CLI 写入——两者同时成立即为潜在双写入,判 warn;另一侧是配置在两次回读之间是否变化——发生即判 fail,这类证据优先于任何推断。体检只报告迹象,不代替操作者做决定,也不代替回读。

典型表现与真实原因。 见到下表左列现象时,先怀疑右列,而不是直接改配置。

现象 更可能的真实原因
成员刚移除又出现 GUI 写回覆盖了 CLI 的改动
命令报组不存在,但组确实存在 CLI 瞬时读到旧状态
写入成功但回读字段缺失 字段被存到另一个键名(如 stays 存为 affinity),不是没写入
规则存在但不生效 规则被追加在末尾,既有规则先命中
改动只在 GUI 里可见 两处写入源不同,CLI 读的是配置文件
改动在 CLI 里可见,客户端不可见 客户端模型目录是静态快照,未重建

字段名差异与规则顺序的完整说明见路由治理,本文不复述细节。

边界二:CLI 版本差异导致字段不可用时怎么办

magpie <子命令> --help 退出 0 不等于能力存在。某些安装版本只返回总帮助,参数是否被该版本接受无从判断;同一子命令在不同版本里的字段集合也可能不同。按以下顺序处置,每步都留可核对的证据。

  1. 先看版本。 magpie --version 记录安装版,后续所有语法以该版本为准;本 Skill 各参考记录的字段语义都绑定具体版本,跨版本需重新核对。
  2. 再看该子命令的帮助。 确认帮助文本是该子命令自身的帮助、而不是总帮助,并确认目标字段名出现在其中。
  3. 用隔离环境验证参数。 在临时 HOME/XDG 配置目录下、通过子进程环境变量执行,避免改动当前 shell 的 HOME;不把真实认证复制进测试目录。此举只验证参数是否被接受,不代替真实环境的落盘验证。
  4. 读回实际落盘字段。 命令返回 0 不等于写进了你以为的键。回读配置文件,确认字段真实存在、值符合预期。
  5. 不支持就降级或等版本。 降级到该版本确实支持的写法,或等版本支持后再做;不要为了迁就旧版本把字段塞进配置文件手改绕过 CLI。

字段名差异。 stays 在配置里可能存为 affinity 这类字段名;按 stays 键核配置会误判为未写入,而 null 表示默认值、不表示失败。字段存储名的完整说明见路由治理 对应小节。体检在 cli_field_support 中只报告「字段是否被该版本支持」,不判定配置内容。

降级路径选择。

情况 处置 不做什么
字段在帮助中存在,命令返回成功但回读缺字段 按存储名回读核对,区分「键名不同」与「未写入」 不因为键名不同就判定失败并重试
字段在帮助中不存在 降级到该版本支持的写法,或等版本 不手改配置文件绕过 CLI
帮助只返回总帮助 判定为「能力未证实」,先用隔离环境验证 不把「exit 0」当能力存在
版本明显低于已核版本 整体按该版本帮助重核语法 不直接套用新版本文档里的命令

边界三:网关不通与模型不通的区别

先定位失败类型,再决定处理位置。下面按症状归类,细节坑位以路由治理 为准。

症状 可能位置 先查什么
网关地址连接被拒或超时,本机调用 CLI 也不通 网关进程未启动,或监听地址与配置不一致 进程与监听地址;地址与 <port> 取自实际配置或界面,不靠默认端口猜
网关通,某个 provider 的请求报「连接被拒」,且报错里的目标地址是本机回环 本机解析把供应商域名指向回环,或全局代理被旁路 报错里的目标地址;本机解析来源与屏蔽条目;provider 是否已单独指定代理(路由治理 §2.7)
网关通,但客户端模型列表里看不到某个组或模型 客户端模型目录是静态快照尚未重建;或该组被停用 分别回查目录内容与组的 disabled,不要用一个原因解释两种现象(§9.1、§9.2)
网关与目录都正常,请求返回服务端错误或供应商错误 供应商侧或账号侧 按 provider、状态、错误信息聚类,并保留错误时间窗;账号登录失效需真人处理
网关通、供应商通,请求返回 200 但落点不符合预期 规则命中与实际服务模型不一致;或请求落到当前不可服务的成员 分别断言规则命中、尝试序列与 served model,不用 HTTP 状态码代替落点判断(§2.9)
想让大部分供应商直连、只让个别供应商走代理 全局代理与 provider 级代理是两层,语义不同 先逐个探测哪些域名直连可达;全局值用 direct 而非清空(空值是继续跟随系统代理);provider 级代理需应用界面或按源码字段名写入(路由治理 §2.8)
配置已改,客户端仍看不到新组 目录未重建或客户端未重启 重建目录、回读内容、重启后从客户端列表与真实请求两处分别核对(§9.2)
只有部分客户端不通 客户端未绑定组、绑定被停用组,或走了原生直连 客户端侧绑定状态;直连路径是否本就不经网关

HTTP 成功不等于任务质量通过。 状态码与响应结构只说明请求被处理,不说明内容可用、落点正确或质量达标。内容质量仍由任务验收判断;路由落点由 served model 证据判断。

证据等级与 NOT_VERIFIED

体检结论要标证据边界,避免被当成比它更硬的结论。

等级 含义 典型来源
已观察 本次直接读到的事实 进程存在、字段可解析、HTTP 状态码
已推断 由观察推出,可能有其它解释 由 hosts_loopback_risk 推出失败原因
NOT_VERIFIED 本轮没有核到,或已核但结论超出证据 未读到的额度、跨版本语义、真实落点分布

读不到不等于读出来是空值,也不等于不存在。额度读不到写未知,不写 0;日志读不到记 NOT_VERIFIED,不用其它日志顶替。

体检输出怎么用

先看什么

顺序 先看哪类 为什么先看它 怎么处理
1 FAIL 中的可写性类:config_readable、cli_field_support、single_writer_risk、credential_exposure 这些决定本轮能不能动手,以及动手后证据是否可信 先修或先停;不带着不可写、字段不支持或双写入风险进入变更
2 FAIL 中的可达性类:gateway_*、routing_log_readable、model_exposed 决定这轮观测与验证有没有数据来源 定位失败类型后再继续,不要把「取不到数据」当成「没有问题」
3 WARN 中的漂移风险类:cli_version、model_catalog_readable、proxy_path_risk、hosts_loopback_risk、agents_detected 决定已有结论要打什么折扣 记录为待核项,并在结论中标明证据范围与版本前提
4 ok 项 只作基线 记录为可观察事实,不当作「配置正确」的结论

两条必须记住的边界

  • 体检通过 ≠ 可以安全变更。 体检是只读快照。它不替代变更授权、变更计划与哈希绑定、漂移检查,也不替代写入后回读与真实请求验证。
  • 体检 FAIL 中有的是「用户有权决定是否继续」,不是「必须修」。 例如 proxy_path_risk 命中保留区间但当前无真实请求受影响、agents_detected 为空可能只是本机不使用客户端、quota_readable 读不到只说明额度未知。体检负责把事实摆出来并说明处置顺序,是否继续由用户决定;反过来,涉及可写性、凭证泄漏与已观测到的连接失败则属于必须先处理的项。

常见误用

误用 正确做法
把体检全绿当成「配置无需调整」 体检只判可观察性,不判配置优劣
把体检 FAIL 全部当成阻塞 先分「必须修」与「用户可决定继续」
把 warn 当成 fail,或反之 warn 是「结论要打折」,不是「不能动」
用体检结果替代真实请求验证 落点仍需代表性真实请求与 served model 证据
体检后隔很久才动手,仍沿用旧结论 动手前重跑,或至少重读配置哈希
体检发现异常后直接改配置 先分清是环境问题还是用户已确认的设计

报告字段怎么读

每条 check 的输出应包含:check code、状态、证据(可复核的事实,例如退出码、字段是否存在、进程是否存在)、以及下一步。证据只写观察到的事实,不写推断;推断放在下一步里并标明前提。

与其它脚本的分工

  • scripts/magpie_preflight.py:只读环境体检,本文的 check code 权威在脚本侧。
  • scripts/magpie_inventory.py:脱敏盘点,产出配置字段白名单投影,与体检的「能不能读」是不同层次的问题。
  • scripts/public_release_check.py:发布前检查,判断 Skill 自身是否满足发布条件,不判断本机环境。

三者共用同一份只读纪律:不写配置、不登录、不消耗模型额度,不把凭证、账号、本机绝对路径写进输出。脚本尚不存在时,本文只固定 check code 的命名与语义约定,不改变其实现设计。

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