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.

referencesprovider-integration.md

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

供应商与账号接入

本文解决什么问题 / 何时读:使用者要把已有的 API key、订阅登录或插件接入 Magpie,并需要理解接入后模型为什么在客户端里看不见、多个账号为什么落到不同来源、以及额度打满时请求会去哪里。在「新建 provider」「登录后不生效」「客户端选不到模型」「多账号落点随机」这四类问题出现时读本文。

本文只讲接入与接入后的行为。组内路由语义、规则坑位与实测差异以路由治理为准;CLI 写入语法与凭证边界以CLI 与变更边界为准;额度分类与成本边界以额度、任务与成果为准。命令形态一律先以安装版 magpie --version 和实际帮助为准。

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

三种接入方式

方式 适用资源 命令入口 凭证落在哪 典型可用模型来源
A. API key 自有密钥的按量或套餐接口 magpie provider add <preset> <your-key> Magpie 本机 provider 配置(默认 ~/.config/magpie/providers.json,尊重 XDG_CONFIG_HOME) 该 provider 暴露的 example/model-strong、example/model-fast
B. OAuth / 订阅登录 有订阅会话或需真人授权的平台 magpie accounts add <agent>、magpie accounts import <agent> 登录态由平台侧持有,Magpie 只保存账号引用与状态 订阅内模型,如 example/model-strong
C. 插件接入 由插件封装的平台、自建后端或非标准协议 插件安装与插件配置入口(见插件与客户端接入) 插件自己的配置位置,不经 provider 配置 插件自行暴露的模型目录

选择顺序:

  • 平台给的是可复制的密钥,走 A。
  • 平台只给网页登录或订阅会话,走 B。
  • 平台需要专用协议或自建服务,走 C;插件尚未安装时先读插件与客户端接入,不要用 A 的 key 形态硬接。

A. API key 接入

命令入口(形态示意,按安装版 magpie provider --help 核对):

magpie provider add <preset> <your-key>

步骤:

  1. 获取 key。在供应商控制台单独生成,命名可辨识(区分个人 / 团队用途),权限取最小范围。key 只在需要时生成一次,不复用、不外发。
  2. 执行命令。把 <preset> 换成安装版提供的供应商预设名,把 <your-key> 换成实际密钥。为避免落入 shell 历史,用交互式输入或环境变量读取(见安全边界)。
  3. 回读配置。magpie providers(安装版对应列表入口)确认 provider 已出现且状态可用;再 magpie provider models example/provider-a 看它暴露了哪些模型。
  4. 直连测试。安装版若提供 magpie provider test example/provider-a,用它确认凭证本身可用。命令不存在时,改用一次最小直连请求核凭证(见接入后的验证)。

常见偏差:

偏差 表现 排查与处理
key 贴错位置 key 被当成模型名,模型目录出现异常条目,或 provider 一直不 ready 回读 provider 条目与模型列表,确认密钥没有落进模型 ID 或其它位置字段;删掉误建条目后重加
多平台共用一个 key 一个平台成功,另一个平台报认证失败 key 与平台一一对应;核对 base URL 与平台绑定,不要跨平台复用同一密钥
key 泄漏到 shell 历史 命令可在历史或会话记录中检索到密钥 改用交互式输入或环境变量;已泄漏的 key 立即在控制台吊销并重建,不做「先留着」
exit 0 但能力不存在 magpie provider <子命令> --help 只返回总帮助 exit 0 不证明子命令存在;必要时在隔离 HOME/XDG 下核对参数(口径见CLI 与变更边界)

B. OAuth / 订阅登录接入

命令入口(形态示意,按安装版帮助核对):

magpie accounts add <agent>
magpie accounts import <agent>

<agent> 是接入方(客户端)标识。add 走新增账号流程,import 用于导入已存在的账号记录。

步骤:

  1. 触发登录。执行 magpie accounts add <agent>,按提示进入平台授权流程。
  2. 完成授权。授权页、2FA、验证码都由真人在平台侧完成;代理或网关侧不能代替这一步。
  3. 确认账号出现。回读账号列表,确认账号标签、状态与是否已启用。列表里只以脱敏标签出现。
  4. 核模型目录。magpie provider models example/provider-b 确认订阅内模型已暴露;再到客户端侧确认该模型在可见列表内(见可见性控制)。

常见偏差:

偏差 表现 排查与处理
登录态过期 请求返回认证类错误,账号标记失效 需真人重新登录,网关侧不能代替;先保留失败证据与时间窗再交账号 owner 处理
团队号与个人号混淆 同一 provider 下两个账号外观相近,落点归属说不清 用脱敏标签分别标注归属与计费主体;确认归属不是「同一个 provider 的两个账号」就算区分开了
登录成功但模型仍不可见 账号已登录,客户端列表为空 先核可见性开关与客户端目录,再核 provider 是否真的暴露该模型;不要先改组
重复登录生成多个账号 同一订阅出现多条账号记录 接入前先看账号列表,确认是否已存在;重复记录会增加并发与额度的归因难度

C. 插件接入

插件接入用于平台需要专用协议、自建后端或非标准鉴权的情况。形态是「安装插件 → 在插件配置里填自己的凭证 → 插件向 Magpie 暴露一组模型」:凭证落在插件自己的配置位置,不写入 provider 配置,也不参与 provider 级账号并发与队列。

要点:

  • 插件暴露的模型与 provider 暴露的模型在客户端侧表现一致,都要过可见性这一关。
  • 插件的安装与初始化可能下载其运行时;不希望联网时使用离线方式核对,不自动执行 sync、update 或 plugin install。
  • 插件相关的客户端配置、模型目录与排障细节见插件与客户端接入。

可见性控制

可见性回答的是「哪个客户端能看见哪些模型」,与路由组回答的「请求落到哪个模型」是两层事。

命令 作用 典型用途
magpie visible <agent> ... 控制该客户端在模型目录里能看见哪些模型 客户端装好了但列表为空、想对某个客户端隐藏某组模型
magpie provider models <provider> 查看某个 provider 暴露的模型 确认模型是否已被 provider 暴露、模型 ID 是否正确
magpie models <agent> 查看某客户端当前可见的模型列表 核可见性调整是否真的生效

判读顺序:

  1. 模型没在目录里,客户端就选不到。先确认模型在 provider 侧已暴露,再确认它在目标客户端的可见列表里。
  2. 改 Magpie 的组不影响未接入的客户端。客户端没有指向本机网关、或走原生直连时,组内成员和顺序对它没有作用。
  3. 客户端目录可能是静态快照,不会因 Magpie 新增组而自动刷新;重建目录与重启客户端的核验方法见路由治理。
  4. 客户端可见目录与「Magpie 是否单独列出组成员」是不同层级,两者都要分开核。

多账号 provider

同一 provider 下挂多个账号时,Magpie 的选择方式有两种。两者不是「有没有生效」的区别,而是「按什么规则选」的区别。

行为 表现 何时用
默认按余量智能挑选 系统按各账号剩余额度 / 健康度选,当前余量好的账号优先 账号之间能力等价、可互换,谁服务结果都合格
显式账号顺序 按设定顺序尝试,前一个不行才轮到下一个 账号之间有偏好差异,如个人账号优先、团队账号兜底

何时需要显式顺序:

  • 能力不同。账号 A 支持长上下文或图像,账号 B 不支持;余量挑选可能选到 B。
  • 额度窗口不同。账号 A 是短周期窗口、账号 B 是长周期窗口,按余量挑选会让消耗落在非预期窗口。
  • 账号归属不同。个人账号与团队账号混在同一 provider,余量挑选无法保证不误用他人配额。
  • 需要保证不误用他人配额。这一条本身就足以要求显式顺序,而不是依赖余量。

字段口径与设置路径:

环节 形态 说明
配置层级 provider 级配置项 账号顺序挂在 provider 上,不是组内成员顺序。组内 routing 管的是「成员模型之间」,账号顺序管的是「同一 provider 的账号之间」,两层互相独立
GUI 入口 provider 设置页的账号区 调整账号先后顺序
CLI 入口 形态示意 magpie provider <account-order> <provider> ... 子命令名以安装版 magpie provider --help 为准;部分版本可能只在 GUI 暴露该入口
回读 再次读取 provider 的账号列表 设置后必须回读确认顺序真的生效
runtime 证据 routing log 的 per-try tries 与 served model 运行时实际尝试了哪个账号

设置后必须回读确认顺序真的生效。否则会出现「看起来生效、实际仍按余量挑选」:配置层顺序已改,但运行时仍在按余量择一,落点与预期不一致。

「配置顺序 / CLI 声明语义 / runtime 观测」三层的区别,以及为什么 runtime 数组不能反推配置顺序,见路由治理 的 order 三层事实一节。

额度窗口、并发与队列、账号休息

  • 额度窗口:短周期(如数小时)、周、月等窗口并存,不同窗口不能换算成一个百分比。quota.resetsAt、订阅 until 与积分批次 expires_at 互不等价;任一项读不到时保留未知,不写成 0,也不按另一种窗口推算。
  • 并发:并发上限是账号级的,跨模型、跨组、跨客户端共享同一账号池。多建组不增加容量;两个入口消耗同一账号池时,先核对来源再计容量。
  • 队列:有界队列决定排队长度与最长等待时间。等待超时属于队列层,不等于额度耗尽。
  • 账号休息:额度打满后账号进入不可用状态,请求转向下一个来源;休息是有起点的时间窗,会自己过期,不是配置错误。
现象 属于哪一层 先查什么 不要做什么
剩余百分比看起来还有,请求仍被拒 额度窗口层 各窗口分别读数(magpie quota --json),区分订阅窗口与积分批次 不要把多个窗口合成一个百分比再判断
429、queued、retry in Ns 并发层 provider 账号级并发上限与有界队列 不要多建组或重复加成员来「扩容」
账号突然不服务,请求落到下一个来源 账号休息层 该账号的当前窗口读数与休息时间窗 不要立刻改配置、重置账号或删 provider 记录
请求等待较久但没有失败 队列层 队列长度与等待时间设置 不要把它当成额度耗尽去改额度策略
客户端看不到刚接入的模型 可见性层 magpie provider models <provider> 与客户端可见列表 不要改 Magpie 的组来解决可见性问题
同一 provider 下两个账号落点说不清 账号层 显式账号顺序与回读结果 不要只凭余量挑选结果反推归属

账号级参数按CLI 与变更边界 的原生命令维护:

magpie provider account-concurrency <provider> <account-or-key-id> 1
magpie provider queue <provider> 2 15
magpie provider rpm <provider> <已确认的每分钟上限>

省略修改值即为查询。账号并发在跨模型、跨组、跨客户端共享;off 或 0 表示不限,不能当「停用」。

接入后的验证

命令成功不等于已生效。四步逐步做,任一步缺证据都不算接入完成。

  1. 直连请求。发一条最小真实请求确认凭证可用:

    magpie <agent> <model> <prompt>

    <model> 用 <provider>/<model-id> 或 group/<group-id> 形态,<prompt> 用一句可判定的短请求。

  2. 看路由日志确认实际 served model。路由日志的 per-try tries 给出尝试序列,served 给出最终服务模型。响应体里的 model 可能是组名,不一定是最终成员。

  3. 核 magpie usage today 落点。看实际 provider/model、状态与错误聚类,确认落点符合预期。注意用量来源可能重叠,不把不同来源直接相加。

  4. 核配置回读。重新读取 provider、账号与组的配置,确认写入内容与顺序确实落盘。

判定口径:

现象 结论
命令返回成功 只证明命令执行完,不证明已生效
HTTP 200 只证明通道通,不等于任务质量通过;内容质量由任务验收判断
配置回读一致 只证明落盘(记 CONFIG_READBACK_VERIFIED),真实落点仍需代表性请求
客户端列表出现模型 只证明可见性调整生效,不代表路由已指向它

辅助入口(按文件名引用,可能尚未落地):

  • scripts/magpie_preflight.py:接入前自检,核对安装版、配置可读性与前置条件。
  • scripts/magpie_inventory.py:盘点已接入的 provider、账号与模型,输出脱敏清单。
  • scripts/public_release_check.py:发布前扫描文档与脚本中的凭证、真实路径与身份信息。

安全边界

⚠️ 以下为硬性边界,不因「方便验证」放宽。

规则 具体做法
凭证只交给 Magpie key、token、密码不写进任何 Skill 文件、脚本、文档、报告、截图或命令历史
示例只用占位 命令与示例一律用 <your-key>,不出现任何真实 key 或 token 形态的字符串(不写真实长度、前缀或结尾片段)
避免落入历史 用交互式输入或环境变量读取密钥;必要时用 read -s 或从受控文件读取,不要把密钥作为命令行参数明文传递
不粘贴片段 报告、日志摘要、issue 与聊天中都不粘贴 key 的任何片段,包括首尾几位
账号只用脱敏标签 账号以 account-a / account-b 形式出现;不写真实账号名、邮箱、昵称与登录标识
读数也要脱敏 magpie quota --json 的 raw 含账号信息,不直接输出;magpie provider account-concurrency 可能打印私有账号,只保留限制值
不整体导出配置 providers.json 含密钥,不整份放进报告、测试或 Git;读取只在进程内做比较与白名单投影
不顺手改动 一次接入不顺带开启已关闭的供应商、重置额度、切换登录态或改所有客户端默认模型

自查口径:文档中出现的每个凭据位置都应是尖括号占位;每个身份都应是脱敏标签;每条路径都应是 <skill-dir>/...,本机私有文件应写成 config/<name>.local.json 或 state/<name>.json;每个端口都应是 <port>。发布前用 scripts/public_release_check.py 或等效人工检查复核一遍。

回读与证据边界

  • 接入类结论的证据来源只有三类:安装版 CLI 帮助与回读、配置文件的字段回读、真实请求的 served model。三者互不替代。
  • 命令返回成功、配置写入成功,都只是中间证据;「已生效」需要一次落到预期来源的代表性请求。
  • 读不到的字段保留未知,不写 0、不按同类字段推算;额度、并发与队列的读数各自独立,不互相推导。
  • 本文只描述接入与接入后的行为,不复述组内路由的实测坑细节;相关排障顺序与版本差异见路由治理。
  • 命令形态随安装版变化。执行前先读 magpie --version 与对应 --help;若某子命令只返回总帮助,标 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