pi-dynamic-models

pi install npm:@wbline/pi-dynamic-models

Pi 会把包记录到 ~/.pi/agent/settings.json，并自动启用其中声明的扩展。仅 npm install -g 不会激活 Pi 扩展。

为 pi 提供动态模型发现能力。启动时从配置的 OpenAI 兼容服务器拉取模型列表与元数据，自动注册为可选 provider——无需手动维护模型清单。

配置

1. 安装包

在 Pi agent 设置（~/.pi/agent/settings.json）中添加：

{
  "packages": [
    "local:/path/to/playbook/packages/pi-dynamic-models"
  ]
}

2. 创建配置文件

创建 ~/.pi/agent/pi-dynamic-models.json：

[
  {
    "provider": "my-provider",
    "baseUrl": "https://your-server.com/v1",
    "apiKey": "your-api-key",
    "api": "openai-completions"
  }
]

字段说明

字段	必填	说明
provider	✓	在模型选择器中显示的名称
baseUrl	✓	服务器地址，如需要请包含 /v1
apiKey		字面量密钥、环境变量名或 $ENV_VAR。开放服务器可省略或设为 "none"。
api		Pi API 类型（默认：openai-completions）。

支持的 API 类型

值	适用场景
openai-completions	Ollama、vLLM、LM Studio、llama.cpp 及大多数本地服务器
openai-responses	兼容 OpenAI Responses API 的服务器
anthropic-messages	兼容 Anthropic 的代理
google-generative-ai	兼容 Google AI 的服务器
azure-openai-responses	Azure OpenAI

工作原理

启动时对每个 provider 并行请求：

1. GET {baseUrl}/models — 模型 ID 列表
2. GET {baseUrl}/metas — 模型元数据

/metas 支持如下响应格式：

{
  "object": "list",
  "data": [
    {
      "id": "example-model",
      "object": "meta",
      "owned_by": "relay",
      "context_window": 524288,
      "max_tokens": 65536,
      "input": ["text", "image"]
    }
  ]
}

字段映射：

metas 字段	模型字段	缺省
id	id	—
name	name	回退为 id
context_window	contextWindow	128000
max_tokens	maxTokens	16384
input	input	["text"]
reasoning	reasoning	false
thinking_level_map	thinkingLevelMap	不传
cost	cost（cache_read→cacheRead 等）	全 0

两个端点的职责不同：只有 /models 成功才会注册该 provider；/metas 仅作补充——命中列表中模型时覆写元数据，未命中则忽略，失败也不影响注册（对应字段使用默认值）。

故障排查

模型列表为空：确认配置文件位于 ~/.pi/agent/pi-dynamic-models.json，且 {baseUrl}/models 与 {baseUrl}/metas 可访问。

API 行为异常：为服务器类型设置正确的 api 字段。

API key 未解析：支持裸环境变量名（如 CLINE_API_KEY）与 $CLINE_API_KEY / ${CLINE_API_KEY} 写法；也可直接写字面量密钥。

contextWindow 始终为 128000：确认 /metas 中对应模型带有非空的 context_window。