omp packages

pi-provider-hub0.1.0

Manage custom Pi model providers, discover models, and query balances.

aaroncarry Published 1 month ago MIT ~194 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

Pi Provider Hub

English | 简体中文

Pi Provider Hub 是一个 Pi 扩展，用于在交互式 TUI 中管理自定义模型供应商。它能发现远程模型、把凭据与 models.json 隔离、在当前会话中即时注册变更，还可以查询特定供应商的账户余额。

环境要求

  • Pi（@earendil-works/pi-coding-agent）0.85.1 或更高版本。本扩展使用 Pi 的公开 Extension API。
  • Node.js 22.19.0 或更高版本（即 Pi 运行所需的运行时）。

安装

从 GitHub 安装到所有 Pi 会话：

pi install git:github.com/aaroncarry/pi-provider-hub

如需固定到某个标签或提交：

pi install git:github.com/aaroncarry/pi-provider-hub@v0.1.0

无需构建步骤；扩展是 TypeScript 源码，由 Pi 直接加载。安装后请重启 Pi。扩展会注册一个斜杠命令：/provider。管理命令仅在 Pi 的交互式 TUI 中可用。

本地开发

克隆仓库后，可以在单个会话中直接加载本地副本：

pi -e /path/to/pi-provider-hub

或将本地副本安装到所有 Pi 会话：

pi install /path/to/pi-provider-hub

命令

/provider
/provider add
/provider list
/provider refresh [provider]
/provider refresh all
/provider balance [provider]
/provider balance all
/provider money [provider]
/provider money all
/provider edit [provider]
/provider remove [provider]

/provider 打开管理菜单。money 是 balance 的完全别名。

添加

/provider add 先要求输入 Provider ID，然后依次选择协议、输入 Base URL 和掩码显示的 API Key。输入的 ID 直接同时用作永久 Provider ID 和初始显示名称。显示名称之后可以通过 /provider edit 修改。

扩展会解析出一个可用的标准 Base URL，请求其 /models 端点，验证所选生成协议的路由，并允许用户保存全部或部分模型。对于模型 ID 和协议都能精确匹配的情况，直接继承 Pi 已注册模型目录中的能力元数据；只有无法匹配或存在冲突的模型才需要手动配置推理支持。当输入的 URL 只包含源（origin）时，扩展会同时测试该源和其约定的 /v1 Base URL，并保存可用的一者。协议验证发送一个空的 JSON 请求，不会触发模型生成。路由缺失、服务器错误或返回 HTML 页面都会在保存 Provider 之前被拒绝。余额支持在后续检测，不会给创建流程增加步骤。添加 Provider 不会切换当前会话模型；之后请使用 /model 选择。

列表

/provider list 显示每个受管 Provider 的 ID、协议、Base URL、模型数量、凭据状态和缓存的余额。它从不显示 API Key，也不发起网络请求。

刷新模型

/provider refresh 选择并刷新一个 Provider。refresh all 以并发上限三刷新所有受管 Provider。失败会被隔离并汇总展示。

刷新可以发现新增模型。新的精确目录匹配会继承 Pi 的已知能力。已有的本地模型（包括手动配置的能力）不会仅因远程响应变化而被覆盖或删除。显式删除模型请通过 /provider edit。

刷新余额

/provider balance 和 /provider money 执行相同的余额查询。all 参数会刷新所有受管 Provider。首次查询时，扩展会探测同源的已知余额 API 并保存检测到的适配器；后续查询复用该适配器。结果会缓存供 /provider list 使用，余额查询失败不影响模型可用性。

自动检测支持以下常见约定：

  • Sub2API：/usage
  • New API：/dashboard/billing/subscription、/dashboard/billing/usage，以及可选的 /api/usage/token/
  • DeepSeek：/user/balance
  • MiniMax token plans：/v1/token_plan/remains 和 /v1/api/openplatform/coding_plan/remains
  • 智谱 token plans：/api/monitor/usage/quota/limit

如果这些响应格式都无法识别，命令会提示余额数据不可用。它不会要求用户输入端点路径或 JSON 字段映射。

编辑与删除

/provider edit 可以修改显示名称、Base URL、API Key、协议、推理支持、兼容性选项和所选模型。其中的 Inherit known model capabilities 操作在确认后，会把无歧义的 Pi 目录元数据重新应用到已配置的模型上。连接相关的修改在保存前会先测试。修改 Base URL 会清除已检测的余额适配器，以便下次余额查询重新检测。删除已有模型需要单独确认。

/provider remove 会删除 Provider 元数据、凭据、余额状态和当前运行时注册。如果该 Provider 正为当前会话模型提供服务，则拒绝删除；请先切换模型。

支持的协议

  • openai-completions
  • openai-responses
  • anthropic-messages

模型发现使用 GET <resolved-base-url>/models。OpenAI 协议使用 Bearer 认证。Anthropic 发现使用 x-api-key 和 anthropic-version 请求头，并遵循标准的 after_id 分页约定。

文件

所有路径都基于 Pi 的公开 getAgentDir() API 推导。设置：

PI_CODING_AGENT_DIR=/pi/agent

后，扩展使用：

/pi/agent/models.json
/pi/agent/auth.json
/pi/agent/pi-provider-hub.json
  • models.json 存放 Provider 元数据和所选模型声明。
  • auth.json 存放 API Key 凭据。
  • pi-provider-hub.json 记录受管的 Provider ID、检测到的余额适配器和缓存的余额。它绝不包含 API Key。

写入时先在目标目录生成临时文件，再原子重命名。更新会保留无关的 Provider 和凭据条目。多文件写入失败时回滚到改动前的确切文件内容。

模型元数据默认值

发现端点通常只提供模型 ID。Pi Provider Hub 首先在 Pi 已注册的模型目录中按相同 API 协议查找精确的模型 ID。如果所有匹配条目的能力元数据完全一致，就继承 reasoning、thinkingLevelMap、compat、input、contextWindow 和 maxTokens。Provider 身份、Base URL、凭据、请求头和定价永远不会被继承。

无法匹配的模型和存在冲突的目录条目使用保守的本地默认值：

reasoning: false
input: ["text"]
contextWindow: 128000
maxTokens: 16384
cost: 0

这些值是本地声明，不是经验证的远程能力。创建 Provider 时只对无法安全解析的模型询问推理支持。之后可通过 /provider edit 覆盖推理设置，模型刷新会保留已有设置。还可以设置 supportsDeveloperRole 和 supportsReasoningEffort 兼容性选项。

安全边界

  • API Key 在输入时掩码显示，绝不会出现在 models.json、扩展状态、通知、日志或会话记录中。
  • 仅在用户确认 Provider 来源（origin）后才发送凭据。
  • 余额端点必须与 Provider Base URL 同源。
  • 重定向会被拒绝而不是跟随。
  • 已知的云元数据主机被屏蔽。
  • HTTP 会暴露传输中的凭据，需要明确确认风险后才能使用。
  • 发现和余额请求均为只读且可取消。模型发现和余额请求 15 秒超时；协议验证 10 秒超时。
  • 扩展不会调用 shell 命令获取凭据。

元数据主机屏蔽清单无法阻止所有 SSRF 技术，包括 DNS 重绑定或允许主机上的恶意服务。只配置可信的端点。

故障排查

  • "Configuration saved, but registration in the current session failed" — 运行 /reload 在当前会话中重新注册 Provider。
  • 无法删除某个 Provider 或其模型 — 当前会话正在使用它，请先用 /model 切换模型。
  • 余额提示"unavailable" — 该供应商不符合"刷新余额"一节列出的任何约定；模型可用性不受影响。

已知限制

  • 管理命令只能在 Pi 的交互式 TUI 模式下使用，不支持非 TUI 模式。
  • 仅支持标准的 /models 响应格式。
  • 余额检测仅支持上文列出的供应商约定。
  • 当 Pi 目录中没有无歧义的精确匹配时，模型能力元数据使用保守默认值。
  • 没有后台轮询；模型和余额刷新均由用户发起。
  • 更新 models.json 时会解析 Pi 的 JSONC 子集并以格式化的 JSON 重写，因此已有注释和自定义格式不会被保留；已有配置值会保留。
  • Provider ID 不可重命名。

开发

安装依赖时跳过生命周期脚本，然后运行检查和测试：

npm install --ignore-scripts
npm run check
npm test

许可证

MIT