better-custom

English

为 Pi 和 Oh My Pi (OMP) 管理自定义 provider 的更好方式。

一个交互式向导(/custom-provider),用于添加、编辑、删除自定义 LLM provider——无需手工编辑配置文件。

功能特性

• 从 models.dev 目录添加 —— 直接挑选已知 API 站点(OpenRouter、DeepSeek、Groq、xAI 等);base URL、模型列表、元数据 全部来自目录(官方 SDK,带 jsDelivr 保鲜层和内置离线快照),完全不探测。
• 添加任意自定义端点 —— 支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini、Ollama。自动探测会查询 /models 和所有已知元数据来源;也可以手动输入(逐个模型,进入各自的元数据菜单, 各项以解析结果为起点)。
• 自动检测模型元数据 —— 上下文窗口、最大输出 token、image/video 输入、 reasoning 支持/档位,直接从网关本身(LiteLLM /model/info + /model_group/info、站点公开目录、OpenAI GET /models/{id}、列表内联 元数据、Ollama 原生 API)和 models.dev 学习。见 元数据如何解析。
• 重新探测并对账 —— 再次查询 /models,在一个三态列表里统一处理: 新模型、元数据更新(context 128000 -> 1000000、image [+]、 max-out 8192 -> 32000)、端点不再返回的模型(标记 unsupported)。 [x] 应用、[-] 保留已存元数据、[ ] 移除/跳过。
• 事后一切可改 —— 逐模型字段(reasoning 上限、图像输入、上下文窗口、 最大输出 token、headers/端点覆盖)、批量删除模型、provider 的 API flavor、端点、重命名、删除。
• 合理且诚实的默认值 —— 实测值优先;推测值在选择器中带标记 ([models.dev] / [local rules]);默认值填充的项不显示。目录里的 退化数据(maxTokens == contextWindow)会自动钳制。
• developer role 探测 —— 拒绝 OpenAI developer 角色的端点(比如 Kimi 订阅端点)会自动写入 compat.supportsDeveloperRole: false,pi 就会 继续发 system 而不是报 400。
• 官方风格的存储 —— API key 写入 ~/.pi/agent/auth.json(就是 /login 写的那个文件),模型声明写入 models.json。旧版内联的 apiKey 自动迁移。见存储。
• 正确处理 reasoning 档位 —— 探测到 provider 的 effort 选项时,向导 会写入完全匹配的 thinkingLevelMap;新模型默认开启 reasoning,上限 xhigh。
• 路径自适应探测 —— /models 在给定 base 上没响应时自动尝试加/去 /v1 的变体;非本地 http:// 自动回退 https://。失败后可以重试或改 手动输入。

安装

pi install npm:better-custom-provider        # 从 npm
pi install https://github.com/real-wudaoshi/better-custom   # 从 GitHub
pi install /path/to/better-custom            # 从本地检出

建议用 pi install,而不是手动把文件夹复制到 ~/.pi/agent/extensions/: pi install 会执行 npm install,运行时依赖(model-probe、yaml) 才会装好。手动复制也能启动,但 YAML 配置会退化为 JSON(JSON 是合法的 YAML 子集)。

使用方法

在 pi 中运行 /custom-provider,然后选择 添加 provider、 编辑 provider 或 删除 provider。

添加

1. 从 models.dev 目录添加 —— 挑选 provider、命名、输入 API key(或 选 none)、多选模型。元数据全部来自目录。
2. 自定义端点 —— 选择 provider 类型,输入端点地址、名称、API key, 然后:
   • 自动探测 —— 探测 /models + 元数据来源,多选模型并内联显示 元数据;或
   • 手动添加 —— 输入 id,进入该模型的元数据菜单(reasoning / 图像 输入 / 上下文窗口 / 最大输出 token),确认后输入下一个 id;留空或 esc 结束。

编辑

选择一个 provider,然后:重新探测模型(如上对账)、逐模型编辑、 删除模型(批量)、手动添加模型、API flavor、Endpoint、 重命名 provider、删除 provider。

逐模型编辑只原地修改单个字段——未触碰的字段(cost、headers、覆盖项) 都会保留。

元数据如何解析

每个字段按优先级分层解析:

1. 实测 —— 来自网关的真实数据:LiteLLM /model/info 和 /model_group/info、New API 风格的 GET {site}/api/models/public(免鉴权)、 OpenAI GET /models/{id}(含 capabilities.reasoning.effort_options)、 /models 列表内联元数据(OpenRouter、One API / New API 的 meta 字段 和 supported_endpoint_types)、Gemini 的 inputTokenLimit、Ollama 的 /api/tags + /api/show。
2. models.dev —— 精确到单个模型的目录条目,标记 [models.dev]。
3. 本地规则 —— 内置知名模型表(OpenAI、Anthropic、DeepSeek、Qwen、 Kimi、GLM、Gemini 等),标记 [local rules]。匹配前会先归一化 id, 所以中转装饰过的 id(bailian/deepseek-v4-pro、gpt-5@20250807、 claude-sonnet-4-6[1m])也能命中。可通过 ~/.model-probe-rules.json 扩展(见 model-probe)。
4. 协议兜底 —— 其他来源都不知道时,按协议给限制值(anthropic 200K/32K、google 1M/64K、openai 258K/32K)。
5. 默认值 —— image: false、video: false、reasoning: true。

重新探测时只有第 1–2 层的值会改写已有配置;推测值和默认值只是新模型的 起点。视频输入会被探测并作为选择器标签展示,但 pi 的模型配置没有 video 字段,仅用于展示。

存储

Pi(官方拆分方式,和 /login 一致):

• ~/.pi/agent/auth.json —— 凭证,以 provider id 为键 ({"type": "api_key", "key": ...});$ENV / !command 引用有效。 pi 对任意 provider id 都会自动解析。选择 none 会写入 "dummy" / "ollama" 占位符,provider 仍可正常加载。
• ~/.pi/agent/models.json —— provider 声明(baseUrl、api、compat、 models)。pi 只从 models.json 加载自定义 provider;models-store.json 是 pi 内部给内置 provider 用的目录缓存,不适合存放自定义模型。
• 旧版内联的 apiKey 会在下次保存时自动迁移到 auth.json;删除 provider 会一并删除其 auth.json 条目,重命名会同步迁移。

OMP:provider 和密钥保持内联在 models.yml / models.yaml(已有文件 保持原格式,新建配置为 models.yml)。保存 YAML 会重写格式、丢弃注释。

开发

纯 TypeScript,由 pi 直接加载,无需构建步骤。探测逻辑在独立的 model-probe 包里。

npm run check   # 用 node --check 对每个源文件做语法检查

结构:index.ts(命令入口)· src/flows/(add / edit / delete / shared)· src/ui/(选择器、提示)· src/config.ts(models.json + auth.json 读写、迁移)· src/model-entry.ts(模型/provider 配置构建)· src/api-key.ts、src/url.ts、src/presets.ts(辅助)。

许可证

MIT