# pi-models-respect

一个让模型列表保持整洁的 [pi 包](https://pi.dev/packages)。

对于你在 `models.json` 里显式配置了 `models` 列表的 provider，只有你配置的
模型保持可见——内置 catalog 里那一大堆模型（比如 openrouter 的全量目录）
会安静地退到一边。

不会删除任何东西：provider 定义、模型定义、凭据都原样保留。本包只影响
pi 的模型视图中*显示哪些*模型。

> 🇬🇧 English version: [README.md](./README.md)

## 为什么需要它

pi 的 `models.json` 是追加式语义：内置 provider 保留完整 catalog，你显式配置
的 `models` 条目在其上合并。所以像 openrouter 这类 provider，即使你只配置了
几个模型，也会显示 300 多个内置模型。单靠 `models.json` 无法缩减这个列表。

这个包在不改变 pi 解析 provider 方式的前提下补上了这个缺口。

## 安装

```sh
pi install npm:@aiti-ai/pi-models-respect
```

或者直接指向本仓库：

```sh
pi install git:github.com/aiti-ai/pi-models-respect
```

## 工作原理

扩展包住了 `ModelRuntime` 和 `ModelRegistry` 上的模型查询入口
（`getModels`、`getAvailable`、`getAvailableSnapshot`、`getAll`、`find`）。
对于每个在 `~/.pi/agent/models.json` 里显式配置了 `models` 列表的 provider，
只有这些显式配置的模型 id 保持可见。没有显式 `models` 列表的 provider
（比如依赖内置 catalog 的 sensenova）完全不受影响。

白名单 100% 从 `models.json` 生成（按文件 mtime 自动重读）。用你的模型向导
增删模型后，下一次查询即反映——无需改扩展、无需重启。

## 示例

`~/.pi/agent/models.json` 里这样配置：

```json
{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "api": "openai-completions",
      "models": [
        { "id": "z-ai/glm-5.2:free" },
        { "id": "openai/gpt-oss-20b:free" }
      ]
    }
  }
}
```

openrouter 下只有 `z-ai/glm-5.2:free` 和 `openai/gpt-oss-20b:free` 保持可见——
其余内置 catalog 从模型选择、`modelRegistry.getAll()`、`modelRegistry.getAvailable()`
和 `modelRegistry.find()` 中隐藏。

## 配置

没有独立配置文件。白名单完全跟随 `models.json`。

## 依赖要求

- pi（编码 agent）——本包是 pi 扩展
- `~/.pi/agent/models.json` 中对你想要精简的 provider 配置了显式 `models` 列表

## License

MIT