pi-cliproxy-provider

通过 CLIProxyAPI 代理在 Pi 编码助手中访问 Claude、Gemini、GPT、Grok、Kimi 等多家模型。

前置条件

1. 已安装并运行 CLIProxyAPI（默认端口 8317）
2. CLIProxyAPI 的 config.yaml 中已配置至少一组 api-keys 及对应的模型凭证
3. Pi 编码助手 v1.0.0+

安装

pi install npm:@rotart/pi-cliproxy-provider

环境变量

变量	必填	默认	说明
CLIPROXY_API_KEY	是	—	CLIProxyAPI 的 api-keys 中配置的密钥
CLIPROXY_BASE_URL	是	—	CLIProxyAPI 地址（建议含 /v1），如 http://localhost:8317/v1
CLIPROXY_BOOT_TIMEOUT_MS	否	5000	扩展启动时预拉模型超时（毫秒）
CLIPROXY_RETRY_TIMEOUT_MS	否	5000	session_start 自动补拉超时（毫秒）
CLIPROXY_RELOAD_TIMEOUT_MS	否	30000	/cliproxy-reload 手动刷新超时（毫秒）

设置方式（以 PowerShell 为例）：

$env:CLIPROXY_API_KEY = "your-api-key-1"
$env:CLIPROXY_BASE_URL = "http://localhost:8317/v1"

BASE_URL 说明：会自动 trim、去掉尾部 /，并避免拼出重复的 /models。扩展不会自动补上缺失的 /v1，请按代理实际挂载路径填写。

使用

1. 设置必填环境变量
2. 启动 CLIProxyAPI
3. 启动 Pi
4. 在 Pi 中执行 /model，选择 CLIProxyAPI Provider 下的模型
5. 若代理晚于 Pi 启动：通常会在会话开始时自动再试一次；仍失败则执行 /cliproxy-reload
6. 代理侧增删模型后，优先用 /cliproxy-reload 刷新（不必全局 /reload）

模型发现时序（1.1）

扩展加载（async factory）
  └─ boot 预拉（默认 5s）
       ├─ 成功且非空 → 注册真实模型列表
       └─ 失败或 0 个模型 → 注册空壳（models: []）

会话开始 session_start
  ├─ 已有非空列表 → 仅通知一次「已加载 N 个模型」（若尚未展示）
  └─ 仍为空且本生命周期未补拉过 → 再试一次（默认 5s）

手动 /cliproxy-reload（默认 30s）
  ├─ 成功且非空 → 全量替换模型列表
  └─ 失败或 0 个模型 → 保留已有非空列表，并 warning 提示

并发的 boot / 补拉 / 手动刷新会合并为同一次进行中的请求。

模型能力发现

扩展会从 CLIProxyAPI 拉取你在 config.yaml 中配置的模型别名。

1. 若条目带有正数 context_window / contextWindow 或 max_tokens / maxTokens / max_output_tokens，优先使用这些值
2. 其余字段由本地启发式推断

模型关键词	推理	图像（默认）	上下文窗口	最大输出
Claude 系列	✅	✅	200K	8192
GPT-5 系列	✅	✅	200K	16384
GPT-4o / GPT-4.1	✅	✅	200K	16384
Gemini 系列	✅	✅	1M	8192
含 vision 的 ID	视系列	✅	视系列	视系列
Grok 3 系列	✅	✅	131K	131072
Grok 4 系列	✅	✅	1M / 500K	131072
grok-imagine-*	❌	❌	1M	131072
Kimi 系列	✅	❌	128K	16384
GPT-4（非 4o/4.1）	✅	❌	200K	16384
o 系列	✅	❌	200K	32768
其他	❌	❌	128K	4096

说明：

• 成本字段默认全为 0（不猜测定价）
• 不附带 thinkingLevelMap；需要精细思考档位时用 modelOverrides
• 白名单外的多模态模型、或要把某模型改回仅文本，请用 modelOverrides

高级配置：modelOverrides

在 ~/.pi/agent/models.json 中使用 modelOverrides：

{
  "providers": {
    "cliproxy": {
      "modelOverrides": {
        "claude-sonnet-latest": {
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 16384,
          "cost": {
            "input": 3.0,
            "output": 15.0,
            "cacheRead": 0.3,
            "cacheWrite": 3.75
          }
        },
        "kimi-k2": {
          "input": ["text", "image"],
          "contextWindow": 262144,
          "maxTokens": 16384
        },
        "some-text-only-claude-alias": {
          "input": ["text"]
        }
      }
    }
  }
}

支持的覆盖字段：name、reasoning、thinkingLevelMap、input、cost、contextWindow、maxTokens、headers、compat。

开发

npm install
npm test

故障排查

问题	可能原因	解决
Provider 不可见	环境变量未设置	检查 CLIPROXY_API_KEY 和 CLIPROXY_BASE_URL
模型列表为空（0 个模型）	CLIProxyAPI 未启动、不可达，或尚未配置模型	启动/配置代理后执行 /cliproxy-reload
启动稍慢（约数秒）	boot 预拉在等代理	正常；可用 CLIPROXY_BOOT_TIMEOUT_MS 调小/调大
刷新失败但旧模型还在	失败或空列表保护	符合 1.1 设计；修好代理后再 /cliproxy-reload
上下文被截断	启发式窗口不准且代理未返回 context 字段	通过 modelOverrides 设置 contextWindow
推理/思考不可用	模型 ID 未匹配启发式	modelOverrides 设置 "reasoning": true
图像识别报错 / 非预期带图	不在白名单或白名单误匹配	用 modelOverrides 调整 input
想重置扩展状态	自动补拉预算按扩展加载生命周期计算	使用 Pi 全局 /reload 重载扩展

许可

MIT