# pi-fastmode-web

Pi 扩展：为 pi CLI 和 pi-web 的 GPT-5 会话自动启用 Fast Mode。

[English README](README.md)

## 行为

Fast Mode 默认在启动时 **Auto on**。

对于可信 tier provider，Fast Mode 保持当前 GPT-5 模型，并在 provider 请求中加入 `service_tier: "fast"` 来请求 OpenAI fast tier：

- `openai`
- `openai-codex`

`FAST · tier requested` 表示扩展已经请求该 tier，并不证明上游 provider 实际接受或执行了它。如果上游返回的实际 tier 仍是 `default`，保持当前模型不会带来实际加速。

对于其他 provider，Fast Mode 不会跨 provider，也不会发送 `service_tier`。它只会切换到同一 provider 上第一个可用的 fallback 模型。默认 fallback 顺序是：

1. `gpt-5.3-codex-spark`
2. `gpt-5.4-mini`

如果同一 provider 没有注册可用 fallback，Fast Mode 会显示 unsupported，并保持当前模型不变。

## 安装

```bash
pi install npm:pi-fastmode-web
# 或项目级安装
pi install -l npm:pi-fastmode-web
```

安装后重启 pi / pi-web。

> 尚未发布？可从源码安装：
>
> ```bash
> pi install ./path/to/pi-fastmode-web
> ```

## 命令

```text
/fast status
/fast
/fast on
/fast off
```

`/fast` 等同于 `/fast status`，不会切换开关。

`/fast on` 重新启用 Auto 行为，并立即应用到当前模型。

`/fast off` 关闭 Fast Mode。如果 Fast Mode 曾自动切换到 fallback 模型，它会恢复原始模型和原始 thinking level。

## 状态

| 状态 | 含义 |
| --- | --- |
| `FAST · tier requested` | 当前可信 tier GPT-5 模型保持不变，provider 调用会请求 `service_tier` |
| `FAST · model <id>` | 当前模型已经是 fallback，或已切换到 fallback 模型 `<id>` |
| `FAST · unsupported` | 没有可信 tier 路径，也没有同 provider fallback 可用 |
| `FAST · off` | Fast Mode 已关闭 |

## 配置

可选。创建 JSON 文件覆盖默认值：

**用户级**：`~/.pi/agent/extensions/pi-fastmode-web/config.json`

**项目级**（覆盖用户级）：`<项目>/.pi/pi-fastmode-web/config.json`

```json
{
  "enabled": true,
  "tierProviders": ["openai", "openai-codex"],
  "fallbackModels": ["gpt-5.3-codex-spark", "gpt-5.4-mini"],
  "serviceTier": "fast"
}
```

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 启动时 Auto on |
| `tierProviders` | `["openai", "openai-codex"]` | 可对 GPT-5 模型请求 `service_tier` 的 provider |
| `fallbackModels` | `["gpt-5.3-codex-spark", "gpt-5.4-mini"]` | 其他 provider 的同 provider fallback 模型顺序 |
| `serviceTier` | `"fast"` | 可信 tier provider 请求的 `service_tier` 值 |

旧配置 `providers` 会被忽略。旧配置 `serviceTier: "priority"` 会规范化为 `"fast"`。

## 环境要求

- `@earendil-works/pi-coding-agent` 0.83.0+（pi CLI 0.83.0+ / pi-web 0.8.x）
- 可信 tier provider 需要支持 `service_tier`；其他 provider 使用同 provider 模型 fallback

## 许可证

MIT