pi-models-discovery

通用模型发现插件：读取 ~/.pi/agent/models.json 中带 "discoverModels": true 的 provider，请求 GET {baseUrl}/models（或配置的 modelsUrl）自动发现模型并注册，无需手写 models 数组。首次发现成功后模型列表持久化到本地缓存，之后每次启动直接读缓存，不再请求网络。

适合本地/自建 LLM 代理（一个网关暴露多个模型）、Ollama、vLLM 等 OpenAI 兼容服务。

安装

pi install npm:pi-models-discovery

配置

方式一：pi 终端内交互配置（推荐）

/config:model-discovery

命令打开配置面板，列出所有标记了 discoverModels 的 provider；选中某个 provider 打开它的字段页（发现开关、baseUrl、api 类型、apiKey、显示名），并可立即重新发现或删除它。添加 provider 时依次问 id、baseUrl、api 类型、apiKey（可留空）、显示名（可留空），写入 models.json 后立即生效（无需 /reload）。写入前自动备份到 models.json.discovery-bak。

注意：写回时 models.json 中的注释与自定义排版不被保留（会格式化为 4 空格缩进）。

方式二：手编 models.json

在 ~/.pi/agent/models.json 的 provider 上加 "discoverModels": true 标记：

{
  "providers": {
    "llm-proxy": {
      "name": "LLM Proxy",
      "baseUrl": "http://127.0.0.1:9000/pi/v1",
      "apiKey": "sk-1234",
      "api": "openai-completions",
      "discoverModels": true
    }
  }
}

baseUrl 和 api 必填；apiKey 可选（无鉴权服务可省略）。模型列表 URL、apiKey、headers 和 compat 相同的多个 provider 共享一次发现请求。

如果模型列表使用不同的端点，可在 models.json 中设置可选的 modelsUrl，值为模型列表的完整 URL（包含路径和所需查询参数）：

{
  "providers": {
    "foo": {
      "baseUrl": "https://api.example.com/v1",
      "modelsUrl": "https://catalog.example.com/v1/models",
      "apiKey": "$FOO_API_KEY",
      "api": "openai-completions",
      "discoverModels": true
    }
  }
}

modelsUrl 仅用于模型发现和刷新，按原值请求；聊天请求仍使用 baseUrl。未配置或为空时，沿用 {baseUrl}/models。发现请求会将 provider 现有的 apiKey 和 headers 发送到该 URL，请使用可信端点。响应格式保持不变。

手编方式修改配置后需 /reload 生效；/config:model-discovery 命令的修改立即生效。

刷新缓存

/config:model-discovery-refresh

强制重新拉取所有发现 provider 的模型列表并更新本地缓存，逐个 notify 结果。

行为

• 启动（缓存优先）：缓存命中时直接用持久化的模型列表注册，零网络请求；缓存文件位于 ~/.pi/agent/extensions/pi-models-discovery/cache.json。provider 配置指纹（baseUrl+api+apiKey+headers+compat+modelsUrl）变化时缓存自动失效，重新走网络发现。
• 在线刷新：/config:model-discovery-refresh 或 /model 打开时触发的 refreshModels 在线重新发现，并同步更新缓存。
• 离线 / 拉取失败：保留 models.json 里手写的 models（如有，作为回退），并通过会话内 notify 显式警告，不静默降级；单个 provider 失败不影响其他 provider。
• apiKey 解析（仅发现请求）：支持字面量与 $ENV_VAR / ${ENV_VAR} 插值；!command 形式跳过发现并显式警告（聊天请求仍由 pi 自身解析执行，不受影响）。
• 发现的模型默认参数：reasoning: true、input: ["text", "image"]、cost 全 0、contextWindow 1M、maxTokens 64K、compat.supportsDeveloperRole: false；provider 级 compat 会合并进每个发现的模型。
• 发现的模型默认将 thinkingLevelMap.xhigh / max 设为 null，不再假定所有后端支持这些额外档位。标准档位仍沿用 Pi 默认映射。若服务支持额外档位，可在 provider 的 compat.thinkingLevelMap 中显式开启，也可将任一不支持的档位置为 null。
• 非推理模型可设置 provider 的 compat.reasoning: false，让 /thinking 只提供 off。reasoning 和 thinkingLevelMap 会提取到模型顶层，其余 compat 字段（如 supportsReasoningEffort、thinkingFormat）正常转发。混合模型网关可用 modelOverrides 按 model.id 覆盖。旧缓存会在启动时应用当前推理配置，无需联网刷新。

下面是本地非推理服务的配置；若要开启已确认支持的额外档位，改用 "thinkingLevelMap": { "xhigh": "xhigh", "max": "max" } 并移除 "reasoning": false。

{
  "providers": {
    "local": {
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-completions",
      "discoverModels": true,
      "compat": {
        "reasoning": false,
        "supportsReasoningEffort": false,
        "thinkingLevelMap": { "xhigh": null, "max": null }
      }
    }
  }
}

• 模型元数据可携带 name / context_window（或 contextWindow，或 vLLM 的 max_model_len）/ max_tokens（或 maxTokens），缺失时用默认值。

旧的 /model-discovery、/model-discovery-refresh、/pi-model-discovery 和 /pi-model-discovery-refresh 名称仍作为兼容别名保留。

卸载

pi remove pi-models-discovery

卸载后 provider 回退为 models.json 中的静态配置（手写 models 或空）。