环境体检详解
本文解决什么问题 / 何时读:使用 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 也可能瞬时读到旧状态,例如报组不存在而该组实际存在。两个写入者并发改同一份配置,结果是互相覆盖或漂移:一次写入在「命令返回成功」之后被另一侧悄悄回退,配置哈希与成员表不再是刚才那一版。这类问题不会以报错形式出现,只会表现为「刚改好的规则不生效」或「成员莫名其妙回来了」。
纪律。
- 一次变更只有一个操作者。GUI 改完即停用 CLI 对同一目标的写入,或反过来。
- GUI 与 CLI 不同时编辑同一份配置,尤其不同时编辑同一个组。
- 变更窗口内暂停 GUI 的配置编辑;后台推理无需停止——停的是配置编辑,不是请求处理。
- 每次写入后回读:配置哈希、成员表、规则与可配置的路由字段。不以「命令返回成功」作为唯一证据。
体检如何发现迹象。 single_writer_risk 从两侧取迹象:一侧是 GUI 进程是否在运行、本次会话是否即将执行 CLI 写入——两者同时成立即为潜在双写入,判 warn;另一侧是配置在两次回读之间是否变化——发生即判 fail,这类证据优先于任何推断。体检只报告迹象,不代替操作者做决定,也不代替回读。
典型表现与真实原因。 见到下表左列现象时,先怀疑右列,而不是直接改配置。
| 现象 | 更可能的真实原因 |
|---|---|
| 成员刚移除又出现 | GUI 写回覆盖了 CLI 的改动 |
| 命令报组不存在,但组确实存在 | CLI 瞬时读到旧状态 |
| 写入成功但回读字段缺失 | 字段被存到另一个键名(如 stays 存为 affinity),不是没写入 |
| 规则存在但不生效 | 规则被追加在末尾,既有规则先命中 |
| 改动只在 GUI 里可见 | 两处写入源不同,CLI 读的是配置文件 |
| 改动在 CLI 里可见,客户端不可见 | 客户端模型目录是静态快照,未重建 |
字段名差异与规则顺序的完整说明见路由治理,本文不复述细节。
边界二:CLI 版本差异导致字段不可用时怎么办
magpie <子命令> --help 退出 0 不等于能力存在。某些安装版本只返回总帮助,参数是否被该版本接受无从判断;同一子命令在不同版本里的字段集合也可能不同。按以下顺序处置,每步都留可核对的证据。
- 先看版本。
magpie --version记录安装版,后续所有语法以该版本为准;本 Skill 各参考记录的字段语义都绑定具体版本,跨版本需重新核对。 - 再看该子命令的帮助。 确认帮助文本是该子命令自身的帮助、而不是总帮助,并确认目标字段名出现在其中。
- 用隔离环境验证参数。 在临时 HOME/XDG 配置目录下、通过子进程环境变量执行,避免改动当前 shell 的 HOME;不把真实认证复制进测试目录。此举只验证参数是否被接受,不代替真实环境的落盘验证。
- 读回实际落盘字段。 命令返回 0 不等于写进了你以为的键。回读配置文件,确认字段真实存在、值符合预期。
- 不支持就降级或等版本。 降级到该版本确实支持的写法,或等版本支持后再做;不要为了迁就旧版本把字段塞进配置文件手改绕过 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 的命名与语义约定,不改变其实现设计。