pi coding agent 多站点模型接入:用一个扩展替代手写 models.json

Source

pi coding agent 多站点模型接入:用一个扩展替代手写 models.json

用 pi coding agent 接第三方模型站点,默认流程是编辑 ~/.pi/agent/models.json,一个站点一段配置。站点少的时候没问题,站点一多就变成体力活:复制、改字段、重启、去 /model 里找,模型列表更新了还得手动对齐。

这篇介绍一个替代方案:用扩展在启动时把外部配置注册成 provider。配置存在单独的 provider-hub.json 里,models.json 不动。

本文覆盖安装、添加站点、连接测试、多站点切换、配置迁移、常见报错,以及它内部到底做了什么。文中的命令和配置都在 Windows 11 + Node 26 + pi 0.84.4 上实际跑过,Linux 和 macOS 路径同理,把 C:\Users\<你>\.pi\agent 换成 ~/.pi/agent 即可。

一、为什么不用手写

手写 models.json 有几个具体麻烦:

  1. 字段容易填错,且不报错。contextWindow 写成 0,表现是聊两句就触发压缩或者直接报上下文超限。
  2. 模型列表不会自动更新。站点上新、下线模型,你不去 curl /models 就不知道。
  3. key 和官方配置混在一起。备份目录、分享配置时容易连带泄露。
  4. 改完要重启。pi 不会监听这个文件的变化。

还有一个不容易想到的:apiKey 末尾多一个空格,JSON 完全合法,请求却一直 401。没有报错,没有日志,只能靠猜。

如果只有一两个站点,这些都能忍。五个以上,值得换个方式。

二、环境

  • pi coding agent 0.84 及以上(pi --version 查看)
  • Node.js 20 以上(pi 自带运行时,一般不用单独装)

扩展用 TypeScript 写,pi 通过 jiti 在运行时转译,不需要构建,也没有编译产物。这意味着装下来的就是源码,node_modules 里只有开发用的类型依赖。

三、安装与卸载

从 npm 安装(推荐):

pi install npm:pi-provider-hub-multi

固定版本:

pi install npm:pi-provider-hub-multi@0.2.1

从 GitHub 安装指定 tag:

pi install git:github.com/Sunrisies/pi-provider-hub@v0.2.1

只对当前项目生效,加 -l:

pi install -l npm:pi-provider-hub-multi

装完重启 pi,输入 /providers 能打开菜单就说明成功。

注意:npm install pi-provider-hub-multi 不会让 pi 加载它。pi 的包管理走 pi install,它会把包写进 ~/.pi/agent/settings.json 的 packages 字段。

查看已装了什么:

pi list

升级:

pi update npm:pi-provider-hub-multi

卸载:

pi remove npm:pi-provider-hub-multi

卸载只从 settings.json 里移除条目,provider-hub.json 会保留。想彻底清干净,手动删掉它。

四、添加一个站点

输入 /providers,选「+ 添加新站点」,然后按提示填:

  1. 站点名称:随便起,比如 my-proxy。插件会据此生成 provider id(小写、连字符),中文名会让你补一个短 id。
  2. Base URL:只填域名也行,比如 api.example.com。它会先试 https://api.example.com/v1/models,不通再试 https://api.example.com/models。
  3. API Key:直接粘贴。注意这里是明文显示,pi 的输入框没有密码模式。
  4. 协议:不确定就选「自动检测」。它会先按 OpenAI 兼容试 Bearer,返回 401/403 再换 x-api-key(Anthropic 风格);选 Google 时用 x-goog-api-key。
  5. 筛选关键词:可以留空(导入全部),也可以写 claude,gpt-4o;前面加 - 表示排除,比如 -embedding,-whisper。
  6. 确认导入:会显示前几个模型、跳过数量和最终使用的接口地址。

几个填写示例:

站点类型 Base URL 协议
OpenAI 兼容中转 https://api.example.com/v1 OpenAI Chat
只给域名 api.example.com 自动检测
Anthropic 官方或中转 https://api.anthropic.com/v1 Anthropic Messages
Google Gemini https://generativelanguage.googleapis.com/v1beta Google
本地 Ollama / LM Studio http://127.0.0.1:11434/v1 OpenAI Chat

保存后立刻生效,打开 /model 就能看到新站点下的模型。

五、验证

先看列表:

pi --list-models

输出里能找到 <provider-id> <model-id> <上下文> <输出上限> 就说明注册成功,例如:

my-proxy gpt-4o-mini 128K 8.2K

再做一次真实调用测试:

/providers test my-proxy

它会选一个模型发一句 ping,最多 16 个 token,成功时显示类似:

连接成功:my-proxy · gpt-4o-mini · 812ms · pong

失败时显示 HTTP 状态和错误信息,比如 HTTP 401: invalid api key。

状态码对照:

  • 401:key 错、过期,或者鉴权方式选错(该用 x-api-key 却发了 Bearer)。
  • 403:key 有效但没权限,常见于没加 IP 白名单。
  • 404:路径不对,多半是 /v1 加多了或少了。
  • 429:限流或额度用完,等一会儿或去充值。
  • 超时:网络不通、代理没配,或者站点本身挂了。

六、多站点与默认模型

配好几个站点之后,/model 里会按 provider 分组列出模型,选中即切换,当前会话立即生效。

想让某个模型成为新会话的默认值,改 ~/.pi/agent/settings.json:

{
    
      
  "defaultProvider": "my-proxy",
  "defaultModel": "gpt-4o-mini"
}

也可以只在某次启动时指定,不改配置:

pi --provider my-proxy --model gpt-4o-mini

插件本身不修改这两个字段。默认模型属于使用习惯,交给用户自己定比较稳妥。

七、配置文件

所有站点存在 ~/.pi/agent/provider-hub.json,权限 0600。结构大致如下:

{
    
      
  "version": 1,
  "providers": [
    {
    
      
      "id": "my-proxy",
      "name": "my-proxy",
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "sk-xxxx",
      "api": "openai-completions",
      "filter": "claude,gpt-4o",
      "models": [
        {
    
      
          "id": "gpt-4o-mini",
          "name": "gpt-4o-mini",
          "contextWindow": 131072,
          "maxTokens": 8192,
          "vision": true,
          "reasoning": false
        }
      ],
      "createdAt": "2026-11-17T00:00:00.000Z",
      "updatedAt": "2026-11-17T00:00:00.000Z"
    }
  ]
}

字段说明:

  • api:openai-completions、anthropic-messages、openai-responses、google-generative-ai 之一。
  • filter:上次使用的筛选表达式,刷新时作为默认值带出来。
  • models:注册给 pi 的模型快照,/providers refresh 时整体替换。

换设备时把这个文件拷过去,或者在新设备上重新 /providers add。npm 包里不含任何 key 和站点配置。

八、从 models.json 迁移

如果你已经有 models.json,不想重新填一遍,可以写个一次性脚本转换。先备份原文件,再执行:

// migrate.mjs —— 把 models.json 里明文 key 的站点转到 provider-hub.json
import {
    
       readFileSync, writeFileSync } from "node:fs";
import {
    
       join } from "node:path";

const dir = process.env.PI_CODING_AGENT_DIR ?? join(process.env.USERPROFILE ?? process.env.HOME, ".pi", "agent");
const raw = JSON.parse(readFileSync(join(dir, "models.json"), "utf8"));
const now = new Date().toISOString();

const providers = Object.entries(raw.providers ?? {
    
      }).map(([id, p]) => ({
    
      
  id,
  name: id,
  baseUrl: p.baseUrl ?? "",
  apiKey: p.apiKey ?? "",
  api: p.api ?? "openai-completions",
  filter: "",
  models: (p.models ?? []).map((m) => ({
    
      
    id: m.id,
    name: m.name ?? m.id,
    contextWindow: m.contextWindow ?? 131072,
    maxTokens: m.maxTokens ?? 8192,
    vision: (m.input ?? []).includes("image"),
    reasoning: m.reasoning === true,
  })),
  createdAt: now,
  updatedAt: now,
})).filter((p) => p.baseUrl && p.models.length > 0);

writeFileSync(
  join(dir, "provider-hub.json"),
  JSON.stringify({
    
       version: 1, providers }, null, 2),
  {
    
       mode: 0o600 },
);
console.log(`已转换 ${
      
        providers.length} 个站点`);

两个注意点:

  1. 只迁移 apiKey 是明文的条目。如果 models.json 里用的是 $ENV_VAR 形式,直接搬过来会被当作字面量,鉴权会失败,需要手动改成实际 key。
  2. 迁移后把 models.json 里对应的条目删掉或改名,否则同一个 id 会同时存在于两处,扩展注册时覆盖它,删站点之后又会恢复成旧配置,容易看花眼。

九、命令表

命令 作用
/providers 打开菜单
/providers add 添加站点
/providers list 列出站点,选中可看详情
/providers refresh [id] 重新拉取模型列表,省略 id 时选站点
/providers test [id] 发 ping 测试连通性
/providers edit <id> 改 URL、key、协议
/providers remove <id> 删除站点并注销 provider
/providers path 打印配置文件路径

edit 里 URL 和 key 留空表示保持不变,避免每次改协议都要重输 key。

所有子命令都支持 Tab 补全,输入 /providers re 再按 Tab 会列出 refresh、remove。

十、常见问题

Q:拉了 0 个模型?

先确认 base URL。用 curl 直接试:

curl -s -H "Authorization: Bearer $KEY" https://api.example.com/v1/models | head -c 300

返回 404,把 /v1 去掉或加上再试;返回 HTML,说明这个地址不是 API 端点,可能少了 /v1 或者被网关拦了。

Q:模型列表有,但聊天报错?

多半是协议选错。Anthropic 风格的站点要选 anthropic-messages,路径是 /messages 而不是 /chat/completions。也可能站点只支持流式,而非流式请求被拒。用 -p 模式跑一句能快速确认:

pi --provider my-proxy --model gpt-4o-mini -p "say hi" --no-session

Q:key 会被上传吗?

不会。key 只写在本机的 provider-hub.json,扩展只在你点刷新或测试时发请求,发往你自己填的地址。

Q:价格为什么显示 0?

/models 接口通常不返回价格,插件统一填 0。这只影响 pi 的成本统计显示,不影响实际计费。

Q:内网网关能用吗?

能,地址填 http://192.168.x.x:8080/v1 即可,需要 pi 能访问到该地址。走 HTTP 而不是 HTTPS 也可以,插件不强制加密。

Q:和 models.json 冲突怎么办?

provider id 撞上内置或已存在的 provider 时会二次确认。确认后会覆盖同名 provider 的模型列表,删掉扩展配置后恢复原样。

Q:重启后配置丢了?

配置写在 ~/.pi/agent/provider-hub.json,不在项目目录,也不在会话里。如果文件存在但 /providers list 是空的,多半是 JSON 损坏,命令会提示是否覆盖重建,覆盖前先备份。

Q:能同步到其他客户端吗?

不能。它只注册给 pi。Cursor、Claude Code 有自己的配置方式,需要单独填。

十一、它做了什么

核心就一件事:在扩展初始化时调用 pi.registerProvider(id, config)。pi 会等待扩展的初始化函数执行完再进入会话,所以注册的 provider 对 pi --list-models 也是可见的。

export default function providerHub(pi: ExtensionAPI) {
    
      
  const {
    
       config } = loadConfig(getAgentDir());
  for (const p of config.providers) {
    
      
    if (p.models.length === 0) continue;
    pi.registerProvider(p.id, toProviderConfig(p));
  }
}

一个必须注意的点:registerProvider 传入 models 时是替换该 provider 的全部模型,不是追加。所以空模型列表不注册,否则会把内置的同名 provider 清空。

拉取模型时做了几件事:

  • 枚举候选端点(带不带 /v1),逐个试
  • 枚举鉴权方式(Bearer → x-api-key),401/403 时切换
  • 兼容 {data:[]}、{models:[]}、{result:{data:[]}} 和裸数组几种返回
  • 过滤 embedding、whisper、rerank 等非对话模型
  • 上下文长度优先读接口字段,没有就按名字推断(-128k、-1m、claude 等)
  • 拉列表超时 15 秒,连接测试 20 秒

还有一个容易被忽略的细节:apiKey 里的 $ 会被 pi 当作环境变量插值,开头是 ! 会被当作命令执行。注册前必须转义成 $$ 和 $!,否则带 $ 的 key 会鉴权失败,而且很难查。

十二、局限

  • 不支持自定义流式协议,只覆盖四种内置 api。
  • key 明文存储,依赖文件权限保护。
  • 不做路由、重试、负载均衡、用量统计。
  • 模型列表是快照,站点更新后需要手动 refresh。
  • 模型元数据靠接口字段加名称推断,contextWindow 和 maxTokens 可能不准,只影响 pi 的上下文管理和成本显示。

十三、参考

  • 项目地址:https://github.com/Sunrisies/pi-provider-hub
  • npm:https://www.npmjs.com/package/pi-provider-hub-multi
  • pi.dev 页面:https://pi.dev/packages/pi-provider-hub-multi
  • 安装:pi install npm:pi-provider-hub-multi
  • 许可证:MIT

本文为原创,转载请注明出处。