插件与客户端接入
本文解决什么问题 / 何时读: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 而非配置回读判断成功。