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。