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.

referencesplugin-guide.md

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

插件与客户端接入

本文解决什么问题 / 何时读:Magpie 插件是什么、安装前必须向用户确认什么、插件装好后客户端(Codex / Claude Code / 其他)如何接入门。准备安装插件、或安装后模型在客户端里看不见时读本文。

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

Magpie 插件是什么

Magpie 插件是装在本机的扩展单元,由发布者提供一个或多个 provider 的接入实现。插件不改变 Magpie 已有 provider 的路由语义,只扩大「能看见什么、能调什么」。

一句话边界:插件扩展的是「Magpie 能看到什么、能调什么」,不改变已有 provider 的路由语义。

三类形态:

类型 典型用途 接入后需要确认什么
订阅类账号接入 把某订阅账号的额度纳入 Magpie 统一调度,成为可路由成员 该账号是否已在本机登录、额度窗口如何计、是否与既有组成员共享同一额度池
聚合网关接入 接入一个已聚合多家上游的网关,作为单一 provider 入口 网关地址是否为本机回环、它内部已做路由时是否与 Magpie 路由叠加、失败时落点归谁
工具类增强 增加客户端辅助能力(模型目录同步、子 Agent 工具、只读探针等) 是否在后台常驻、是否发起网络请求、是否改写客户端模型目录

判读要点:

  • 插件只影响它自己声明的 provider 与能力;已存在的组、成员、规则和客户端目录不因装插件而自动变化。
  • 插件运行时与用户同权限运行,能读到本机 provider 配置与凭证文件。
  • 已装插件在初始化时可能拉取其运行时;需要零联网时走离线 inspect 路径,不自动执行 sync、update、plugin install 或 quota reset(见CLI 与变更边界)。
  • 插件名、provider 名、模型 ID 的具体形态以安装版 magpie --version 与 magpie plugin --help 的实际输出为准,不在本文写死。

安装前必须向用户确认的四件事

安装是有副作用的动作。四项未确认前不安装:先问清,再展示计划,再等用户明确同意。

1. 来源

要问什么 为什么要问 用户可能的回答
这个插件从哪里来:官方发布、第三方仓库,还是用户自建? 插件以用户权限运行,来源不可核就无法判断它会做什么 官方文档推荐的 / 某个第三方仓库 / 我自己写的 / 不清楚,是应用里推荐的
有可核的发布者名称与版本号吗?发布页或源码能打开吗? 版本不明则无法复核变更、无法回滚,也无从比对装前装后 有发布者和版本号 / 只有名字没有版本 / 找不到了

2. 权限范围

要问什么 为什么要问 用户可能的回答
它能读哪些本机文件与配置,能写哪些? 插件可读 provider 配置与凭证;写入范围决定是否影响既有 provider 与客户端目录 只读本机配置 / 会读写客户端模型目录 / 会写路由组 / 不清楚
是否发起网络请求,请求到哪里? 外连范围决定数据与用量流向,也是判断是否夹带行为的第一道信号 完全离线 / 会连发布者服务器同步 / 会连上游接口 / 不清楚
是否在后台常驻运行? 后台运行的影响面超出安装那一刻,卸载前不易察觉 装完就退出 / 常驻后台 / 不清楚

3. 影响哪些 provider

要问什么 为什么要问 用户可能的回答
安装后是新增 provider,还是改写 / 接管已有 provider? 改写已有 provider 会让既有组成员、客户端目录与历史落点统计全部失真,属于静默的路由语义变更 纯新增 / 会接管 example/provider-a / 会刷新已有 provider 的模型列表 / 不清楚
会不会改动已有 provider 的账号绑定、模型可见性或路由组归属? 账号绑定与可见性改动会静默改变哪些模型可被调用 不动已有 provider / 会重新绑定账号 / 会重置可见性 / 不清楚

4. 是否需要凭证

要问什么 为什么要问 用户可能的回答
需要哪些凭证,落在哪个文件或环境变量? 凭证落点决定泄露面与清理成本,落在公开层(入库文件)内属于事故 需要一个 API key,存本机配置 / 需要订阅登录态 / 不需要凭证 / 不清楚
凭证会不会上传到发布者服务器? 外传与否把风险从本地误配升级为对外泄露 不会上传 / 会用于校验 / 不清楚
是否需要使用者亲自登录? 代登录牵涉账号切换与额度动作,超出安装本身的授权 需要我自己登录 / 我已有登录态 / 不清楚

确认完成后的记录方式:四项结论写入交付说明,不写入凭证原文;来源、版本、影响范围保留可核标识。

安装与回读验证流程

五步,前四步可在无模型调用前提下完成,第五步才产生真实请求。

命令族说明:下面 magpie plugin 下的子命令名以安装版 magpie plugin --help 的实际输出为准;部分版本该命令族只返回总帮助,exit 0 不能证明能力,必要时在临时 HOME+XDG_CONFIG_HOME+XDG_CACHE_HOME、MAGPIE_NO_ACCOUNTS=1 下先确认参数。命令中的尖括号由实际对象替换,不直接执行模板。

第 1 步:列出可安装项(只读)

magpie plugin list
期望看到什么 异常时怎么办
可安装项清单,含名称、来源标识、版本或提供方 命令报不存在:确认安装版 CLI 是否提供该子命令,改用界面或帮助文本核对,不臆造子命令名
每个候选的说明足够判断来源与影响范围 说明缺失:按「来源」一项退回用户确认,不凭名称推测

此步只读,不触发安装、不联网同步。

第 2 步:展示来源与影响,请用户确认

期望看到什么 异常时怎么办
四项确认结论逐条对应到该插件,来源可核 来源不可核:停止,改走降级路径
明确说明会新增哪些 provider、是否触碰已有 provider 影响面覆盖已有 provider:缩小到只装新增部分,或请用户明确接受后再继续
用户明确表示同意安装 用户未确认或含糊:保持未安装状态,先给出待确认清单

第 3 步:安装

magpie plugin add <plugin-name>
期望看到什么 异常时怎么办
安装成功,明确返回插件标识与版本 安装失败:保留完整错误信息,先判断是来源问题、依赖缺失还是凭证缺失,不反复重试
过程中若提示需要联网拉取运行时,先取得用户同意 自动拉取运行时:属额外网络动作,先确认再继续
未顺带发生未授权动作(未切账号、未重置额度、未改全部客户端默认模型) 发现连带的账号或额度变更:立即停下并报告实际发生了什么,不自行补偿

第 4 步:回读

回读三件事:插件是否启用、新增了哪些 provider 与模型、账号是否已绑定。

magpie plugin list
magpie models
magpie groups
期望看到什么 异常时怎么办
插件处于启用状态 仍显示未启用:核对插件自身状态与组是否被停用,disabled 与插件未启用是两个候选原因,分别回查
magpie models 出现新 provider / 模型 ID 目录未更新:按模型目录是静态快照重建目录并回读,不靠重启代替重建
账号绑定状态与用户预期一致 账号未绑定:区分「未绑定」与「已绑定但不可用」,分别回查凭据与额度状态

回读只证明落盘。CONFIG_READBACK_VERIFIED 不等于模型已可用。

第 5 步:发一个代表性请求

在授权范围内发一次真实请求,核对实际 served model 落在预期成员上。

期望看到什么 异常时怎么办
magpie usage today 中该请求的 served model 落在预期成员 落到非预期成员:按路由治理定位命中规则与回退路径
客户端侧也能观察到同一落点 客户端报模型不可见:先查该客户端可见列表与目录重建,再查网关侧
请求未触发未预期的扣费或卡消耗 发生额外消耗:保留记录并回报用户,由用户决定是否调整

配套脚本入口

以下脚本名可能尚不存在,本文只引用,不以其存在作为前提:

脚本 用途
scripts/magpie_preflight.py 安装前只读预检:版本、可见目录、当前 provider 清单
scripts/magpie_inventory.py 盘点插件、provider、模型与组清单,输出不含凭证的投影
scripts/public_release_check.py 公开发布前的合规自检:占位符、真实标识、路径与凭证泄漏

客户端接入门

通用

项目 要求
模型目录 客户端要能看见的模型 ID,必须在该客户端的可见列表里;不可见的 ID 即使网关侧可用也无法被选中
网关地址 本机回环地址,用 <gateway-url> 占位;端口写 <port>,从实际界面或配置核实,不硬编码
绑定粒度 客户端只绑组 group/<group-id>;绑具体模型会绕过组内分流

模型目录是静态快照:新增组、升级模型或装插件后都要重新生成目录、回读内容并重启客户端,只重启不重建目录不能保证新模型出现。落地检查与「目录过期」「组被停用」两个候选原因的排查见路由治理客户端侧章节。

Codex

Codex 的主模型与子 Agent 模型是两层,可分别指定。结论摘要:

层级 结论
主会话模型 客户端配置项指定,是默认落点
子 Agent 模型 独立于主会话,可与主模型不同;优先级为单 agent 指定 → 统一默认 → 继承主会话
可见性前提 子 Agent 的模型名必须在 Codex 可见列表内

完整三层优先级、字段名与坑位见子 Agent 模型指定。

为什么子 Agent 会意外走主路由:当三层优先级都没有显式指定时,子 Agent 继承主会话模型。此时网关侧看到的是同一个模型名,无法区分主会话与子 Agent 请求,于是表现为子 Agent 静默走了主路由。

派发前的边界提示:某些客户端存在「任务消息被后端封装、只有自家模型能读」的边界,跨模型派发会失败。派发前先读子 Agent 模型指定确认该限制的处理方式,不要在会话中途来回切换模型。

Claude Code / 其他客户端

项目 说明
模型 ID 形态 与 Codex 同理,形态由 Magpie 目录决定:同一模型在不同客户端目录里显示形态可能不同,按各客户端实际目录中的 ID 使用,不把不同显示拼写当成两个独立策略
可见性 同样受 Magpie 目录与客户端可见列表控制;不可见即不可选
子 Agent 模型 属于客户端配置,不假设网关能覆盖客户端写死的模型

其他客户端的具体字段、层级与继承链随客户端版本变化,本文不展开未经核实的字段。核实顺序:先看该客户端安装版帮助与配置 schema,再看实际回读;未读到不等于不存在,先记录具体缺口。

明确禁止

  • 不自动安装未知插件。
  • 不把 token / cookie / 凭证写进日志、报告或 Skill 文件。
  • 不替用户决定账号切换、额度重置或登录。
  • 不在未确认来源与影响范围时执行安装。
  • 不把「插件已启用」当作「模型已可用」。
  • 不在插件运行时拉取、联网同步或后台常驻动作上越过用户授权。
  • 不凭插件名称推测其 provider、额度或影响面。

没有可安装插件时的降级说明

没有可安装插件不影响核心路由能力,只是可用资源少:分组、路由组、规则、可见性与客户端接入门径都不依赖插件存在。

降级路径 适用条件 做法
直接用 provider add Magpie CLI 本身支持该 provider 的原生接入 改走原生 CLI:magpie provider add / magpie accounts add / magpie plugin add,语法见CLI 命令参考,接入验证按供应商与账号接入执行,建组与配规则再按操作入口
用官方文档里的账号导入入口 该 provider 官方提供账号导入界面或命令 由使用者在官方入口完成导入,再回读 Magpie 侧是否可见
只用已有 provider 现有 provider 目录已覆盖当前任务所需能力 复用现有 provider 与组,只做组内分层与时段规则,不新增接入面
先升级 Magpie 目标插件或 provider 能力在当前安装版缺失 升级前先确认升级会改变哪些行为;升级后重新核对 CLI 语法、配置字段与落点

选择顺序:优先选不改写已有 provider 的路径。升级会变更行为与字段,先核实再执行,不自动升级。

各路径共同的收尾:按安装与回读验证流程的第 4、5 步确认落点,用实际 served model 而非配置回读判断成功。

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