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.

referencesgateway-resilience.md

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

网关长跑韧性与故障隔离

当模型列表消失、额度卡片停更、多个供应商同时超时、插件宿主内存持续增长,或客户端请求中断时读本文。分别检查推理、目录、认证、额度和进程生命周期,再决定是否重启。机器开机时间长、进程多或一次负载高,均不能单独证明故障原因。

针对“宿主持续增长,但不能中断任务”的具体顺序、事件关联和插件归因等级,读内存增长分层取证。

请求可用但慢、或怀疑 Agent/Skill 输入过重时,读输入开销与职责交接;从网关分查网络与输入证据,其他层的规则调整交对应维护方,效果仍结合缓存和任务质量复核。

个人进程号、账号、用量和日志原件保存在本机私有状态目录;公开文档只保留复核方法和已证实的机制。

1. 固定现场,不叠加诊断进程

  1. 记录 magpie --version、故障时间和时区。核现有应用、网关监听者、插件宿主父子链、启动时间和实际可执行路径;不另起网关做诊断。
  2. 核 provider/plugin 开关、实际绑定来源、模型暴露状态及组成员。只输出白名单,不打印认证、密钥、完整配置或带身份的错误原文。
  3. 做短时连续 CPU/RSS 采样,同时核磁盘、swap、认证文件变化与相关日志。累计 CPU 是历史消耗,单次 RSS 偏高不等于内存泄漏。
  4. CLI 读取设总超时;超时保留 TIMEOUT,不叠加同类全量扫描或连续空轮询。
  5. 修改前存 0600 快照;沿已有授权逐字段修改并回读。发现其他 writer 改动时重新对账,不整文件回滚。

健康检查只证明对应本机接口可用。恢复推理仍需请求的实际 tries、最终 served、状态与用量;已有新鲜回执时不重复探测。真实请求限用户授权内的最小验证。

2. 分开核五条链路

链路 应核证据 解释边界
推理 时间、实际 tries、状态、最终 served、用量 候选 order 出现不等于请求过;最终 200 可能由回退来源服务
目录 实时列表、暴露/隐藏、账号模型限定、客户端列表 空列表不证明下架;静态备用目录不证明当前地区支持
认证 token 存在性/过期、刷新回执、保存结果、消费者 额度未知不等于退出登录;有 token 不等于刷新成功
额度 readAt、窗口重置、刷新回执、历史采样 卡片不动不等于没有调用;不同入口可能共用一个订阅池
进程 监听所属、父子链、启动时间、IPC、更新交接 多个 host/app-server 不自动构成冲突;PPID=1 不自动等于废弃

路由持续有成功回执而额度卡长期没有新采样点时,先排额度采样。重启后恢复只能记为“重启后恢复”,具体刷新停顿原因仍需证据。

模型 hook 超时条数是本地事件数,不是外部 HTTP 请求数。npm registry 不可达不能直接解释全部 hook 超时;须核当时是否安装依赖、哪个事件反复触发刷新,以及内存增长的关联。

内存健康结合压力、swap 速率与缓存判断,不因 swap 总量较高就手动删除交换文件或停止系统内存服务。Apple 内存指标说明将这些指标分别定义。

3. 已复现:双插件认证同步导致刷新循环

一次故障中,常规订阅插件向副 provider 复制完整 OAuth 记录,副插件又将同一记录改成来源引用。两种表示交替落盘,触发 auth 变更事件;宿主失效并重载模型目录,重新执行同步 hook:

插件 A 写完整登录 → auth 变更 → 目录刷新
插件 B 写来源引用 → auth 变更 → 目录刷新 → 再回到 A

使用两个虚拟账号及真实同步函数离线复现;停止一个同步方后,重复执行不再写入。现场定向关闭未使用的副插件后,认证文件停止持续变化。附近也发生过应用与宿主换代,后继宿主的 CPU/内存正常,不能当作同一个旧宿主自行回收内存的证据。这支持认证循环的判断,不证明历史上每次掉线均由它引起,也没有证明宿主具体的内存保留实现。

插件迭代要求:

  • 同一共享认证记录只有一个写入者;按宿主支持的引用机制复用登录,不让插件互相修正同一份数据。
  • models/usage 等高频读取 hook 保持幂等,真实内容未变则不落盘;不靠每次复制认证来“保鲜”。
  • provider off 与 plugin off 是两个开关。关闭 provider 不证明插件后台 hook 已停止;停用插件后核实际绑定、认证文件变化和 host 状态。停用前列明其全部 provider 的影响。
  • 用虚拟账号、隔离存储和无网络 fixture 复现,不反复消费真实 refresh token 验证竞争。

多供应商同时异常时,先核共享宿主循环,再判断单家供应商或机器性能。

宿主超时与取消的放大效应

宿主 inTime 的超时仅放弃等待,底层模型目录 hook 可继续运行;普通额度 RPC 的取消也不等同于底层任务终止。在隔离虚拟插件上已复现:目录 RPC 超时返回后,多份底层任务仍挂起;普通额度任务收到 abort 后仍等待,直到插件完成。这是未完成任务保留,尚不能称已完成对象永远不被 GC 回收。认证事件风暴可能放大此类积压,但没有故障时的分配栈就不能量化其对历史内存增长的贡献。

结论须绑定实际加载的宿主脚本哈希。上述现象在 Magpie 0.1.2522 对应脚本复现;该版 Go 父进程的退役等待阶段最多十分钟,后续停止还有额外等待和强制退出保护,不能把十分钟当整个回收过程的严格上限。因此“关闭输入后短时仍等待”不等于“受正常托管的旧宿主会永久残留”。父进程被外部终止是另一种生命周期。

补修不能只加 Promise.race:还需插件 I/O 接受取消、按账号合并重复目录/额度读取,并限制未完成任务。没有实现与回归证据时不把这些建议记为已修。内存观察同时记录 RSS、物理 footprint 和虚拟预留,不能用大块未分配地址空间判定泄漏。

可复现的宿主任务生命周期缺口已提交 上游 issue #4678,内含无网络虚拟插件复现。它不是本地配置已修复宿主实现的证明。

4. MiniMax Code:登录、额度与模型消失

内置 API/Coding Plan 与 OAuth 插件入口分别检查;不据 UI 名字认定是同一渠道,也不把两个入口当双份额度。

  1. 开关:provider 是否 off?插件是否启用、实际由哪个版本服务?关闭的 OAuth provider 在某些 CLI 过滤路径可能显示普通余额接口“未配置”;交叉核 accounts、绑定和开关,不能据此让用户填写 Balance URL。
  2. 目录:核实时目录、暴露项、delisted、账号限定和组成员。地区列表可能不同;失败后回退静态备用目录,不证明原模型被下架。先核实时目录,再调整暴露项。
  3. 认证:只读 token 元数据及刷新/保存结果。一次性 refresh token 需要正确串行化和持久保存;两个 host、一次超时或历史 signed-out 文本,不足以证明竞争消费。须保留刷新失败、保存结果或较新凭据的证据。
  4. 额度:对比账号接口、额度接口、采样时间与请求。未知保留未知,旧的用尽窗口不当当前限额。一个入口能读订阅、另一入口异常时先定位过滤路径,不重置账号。
  5. 路由:优先使用已接入且符合用户资源策略的稳定入口,不为恢复同一模型盲开重复 OAuth 来源。核组内位置与 classifier,区分分类器和 worker 请求。直接请求只证明该入口可用,组落点另核真实回执。

必须重新登录时,由用户完成必要授权;不擅自删凭据或复制其他应用的 refresh token,不循环执行登录、刷新或 provider test。

5. 更新交接、进程残留与重启

更新时新主进程可接管监听,旧进程暂留以完成在途请求;两代进程可能是正常交接。插件宿主可通过管道/IPC 服务而不监听 TCP,“PPID=1 + 无监听”不足以证明可清理。

调查残留要绑定 exe、启动时间、旧父进程、交接日志、IPC/文件持有和在途任务。exe/cwd 消失或不可中断等待只是线索,不能单独证明无业务价值,不据此批量 kill。

真正的操作系统重启会终止原来的用户进程,AbandonProcessGroup 不能让进程跨系统重启存活。相同 PID 可能复用;必须区分重启应用、服务和操作系统。

终止主进程后由 launchd 拉起属于服务重启,会中断在途请求,不等于 Magpie 自身更新交接。自动拉起取决于实际 job、KeepAlive 条件、退出状态和节流设置,不把本机配置当通用默认。

KeepAlive、ThrottleInterval 和 AbandonProcessGroup 的语义可核 Apple launchd 手册源码,并以安装版 man launchd.plist 复核;其中没有跨系统重启保留进程的机制。

重启/清理前确认授权、归属、在途影响和恢复入口;之后核监听、插件加载与代表性请求。不擅自 kill host 的父进程,不用固定周期重启掩盖认证循环。

自启任务的正常退出重拉循环

自启任务设无条件 KeepAlive=true 时,启动器若发现另一个实例已服务网关并正常退出,launchd 仍可能按节流间隔不断重拉。核 launchctl print 的实际 job PID、state、runs 和 last exit code:持续出现“spawn scheduled、退出码0、runs增加”,且监听者始终是另一个稳定 PID,支持调查这一循环;不能据“另一个实例存在”就终止它。

若需求是“正常退出不重拉,启动器异常退出才重拉”,可在核实退出语义后选条件 KeepAlive={SuccessfulExit:false},保留所需 RunAtLoad。它只监督该 job 自己启动的进程,不会监督一个独立 GUI 实例的后续崩溃,不能当成完整网关故障自愈。应用更新可能改写自启文件,之后须重新回读。

改 plist 不等于运行中的 job 已更新;重新装载 job 可能结束其进程。有正在运行的 job 时,不为改偏好直接 bootout。只有明确授权、确认 job 无运行 PID,且实际网关归属已核清时,才安排定向重载;备份前态、只改目标键,随后核监听者未变、健康状态及 runs 不再持续增加。

“不影响任务”的维护边界

只读巡检可在任务运行时有界、低频执行,仍会占用少量 CPU/I/O,避免叠加全量扫描。自动清理只能处理有明确归属、保留期和已结束证据的具名临时产物;已退出的普通进程没有可回收的用户内存,僵尸应由父进程回收。CPU低、无TCP监听、文件路径消失都不等于任务结束。

重启应用、清空缓存或结束进程需要对应组件支持停止接新任务、排空在途工作和恢复服务;单次连接数为0也有竞态。无法证明安全窗口时只报告并延期,不承诺全机“等同重启且零中断”。当前 Guardian 只读报告不代表已经实现任务感知的自动维护。

6. 只读巡检

scripts/gateway_guardian.sh 保留 status/reap/guard/cache/all 名称,本版均为只读报告:

bash <skill-dir>/scripts/gateway_guardian.sh status
bash <skill-dir>/scripts/gateway_guardian.sh all

reap 只报僵尸数量和 PPID=1 宿主线索;guard 按可配置 RSS 阈值提示复核;cache 只统计已知缓存的过期文件。它不杀进程、不重启、不删缓存、不截断日志;DRY_RUN=0 也不开放写操作。

旧脚本 dry-run 未覆盖缓存删除,guard 也缺少完整归属与托管核验。Skill 更新不会自动替换仓库外运行副本;核 launchd 实际脚本路径和哈希,沿已有授权备份并窄更新后才记为采用。脚本不安装后台任务,不修改 launchd/Magpie 配置。

有界连续采样

需要判断趋势时,使用 magpie_resilience.py,避免重复调用会加载插件或刷新所有供应商的 CLI:

python3 <skill-dir>/scripts/magpie_resilience.py collect \
  --samples 6 --interval 10 \
  --output <skill-dir>/state/resilience/observation.local.json

结果文件拒绝覆盖、权限 0600,输出目录必须为 0700。默认约五十秒,样本/间隔有限且总观察不超过五分钟;参数和实际覆盖时间均写入回执。脚本只读 ps 和认证文件的 stat 元数据,不读取认证内容、不调用 Magpie CLI、不请求网络。配置目录沿 XDG_CONFIG_HOME,也可显式指定 --config-dir。

按 PID 与启动时间分段,宿主更换不能拼成一条内存曲线。认证 mtime 变化次数是相邻采样的观测下界,无法捕获采样间全部写入;合法 token 刷新也会改变时间戳。采样失败记 unknown/partial 并非零退出,不能当零进程/零增长。RSS 变化和认证写入只提供线索,不输出“已确诊泄漏”或自动触发清理。

7. 等待上游期间的本地缓解

按现场需要选择,先保存前态与可读计划,使用已装 CLI 支持的命令;不把以下操作全部设为通用默认。

发现 最小缓解 回读与边界
官方包与多个旧 fork 同时加载,共享认证写入者不清楚 核功能差异和当前绑定;选择满足当前需求的已安装插件后,magpie plugin use <spec> <provider>,再 plugin off <unused-spec> 保留源码、凭据、账号和组成员;核实际 serving spec、模型与账号数量。停用一个插件影响它提供的所有 provider
不用的副 provider 已 off,其插件却仍运行 hook 停用对应未使用插件 不通过删除账号、清空凭据或重置额度止血
运行期频繁换版本,难以绑定故障基线 可选择 magpie update channel stable 和 magpie update auto on notify 24h 只更改更新偏好,不降级当前版本;notify 不会自动安装修复,看到重要修复后安排验证窗口
探测脚本、GUI 或多个 Agent 反复全量读取 先复用已有回执和本机文件元数据;手动刷新合并为单次有界操作 保留正常自动额度采样和推理,不用高频全量 quota/sync 轮询代替健康检查
巡检依赖 RSS 单阈值定时 kill 使用只读报告;具名复核后才安排有影响的恢复动作 不修改系统 swap,不根据 PPID=1/无监听清理,不承诺无中断

每次变化后检查配置的目标与无关字段、实际 provider 绑定、正常模型最小请求及其 served;随后连续采样。插件切换可以触发宿主正常换代,不能把新 PID 的低 RSS 作为旧进程回收证明。恢复时只撤销本次仍匹配预期后态的字段,不把旧快照整文件覆盖回去。

完整盘点见环境体检和脱敏盘点;插件绑定见插件与客户端接入。

8. 恢复判据

短时复核:认证文件不再持续改写、目录读回、host 资源不再持续失控、网关健康、实际请求成功。记录窗口和同时发生的升级、开关、重启,不把单次通过称为长期稳定。

跨有效期 OAuth 刷新、不同地区目录、多客户端并发、长期内存走势、厂商计费和 Agent 后续执行效果,按证据分别保留 NOT_VERIFIED;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