@llmgates_api/pi-llmgates-provider

Pi provider 扩展，对接 LLMGates 网关：从 GET /v1/models 动态发现模型，注册到 pi，并按模型路由到对应的 OpenAI 兼容推理端点。另提供 2API 兼容层，可并行接入多个 NewAPI、Sub2API、CLIProxyAPI 实例。

参考实现：@router-for-me/pi-cliproxyapi-provider

默认网关： https://apihk.llmgates.com/v1
API Key 格式： sk-llmgates-...

目录

• 快速开始
• 安装
• 使用
• 多网关 2API 兼容层
• 功能概览
• 配置
• 模型映射
• 定价与费用估算
• 安全
• 故障排查
• 开发
• 发布（维护者）
• 相关文档
• 许可证

快速开始

# 安装
pi install npm:@llmgates_api/pi-llmgates-provider

pi
/login LLMGates

安装或更新后执行 /reload 或重启 pi 使扩展生效。详细安装选项见 安装。

安装

环境要求： pi、Node ≥ 22.19、 @earendil-works/pi-coding-agent / @earendil-works/pi-ai ≥ 0.81.0, < 0.82.0（基线 0.81.1）。

本扩展使用 native Provider API，不支持 pi 0.80.x。

npm

pi install npm:@llmgates_api/pi-llmgates-provider          # 最新版
pi install npm:@llmgates_api/[email protected]   # 指定版本
pi install -l npm:@llmgates_api/pi-llmgates-provider      # 仅当前项目（否则装到 ~/.pi/agent/）

源码

pi install git:… 自 0.2.7 起不再支持：发布产物是编译后的 dist/（不提交进仓库），pi 的 git 安装只跑 npm install --omit=dev，拿不到 dist/，扩展会静默不加载。源码安装请用 pi install .（见下方「本地开发」，需先 npm run build）。

本地开发 / 一次性运行

git clone https://github.com/ax128/pi-llmgates.git
cd pi-llmgates
npm install
pi install .

# 单次试用，不写入全局配置
pi -e npm:@llmgates_api/pi-llmgates-provider

使用

pi
/login LLMGates

菜单路径：/login → Sign in with an account → LLMGates

| 字段 | 默认值 | | --- | --- | | base URL | https://apihk.llmgates.com/v1 | | API key | 你的 sk-llmgates-* |

登录成功后：

• 模型立即注册可用
• API key 存入 pi auth.json（OAuth 凭证）
• baseUrl、providerId、providerName 写入 ~/.pi/agent/llmgates/config.json（交互式登录不写 apiKey）

凭证校验失败最多重试 5 次（含非法 URL、网络/HTTP/JSON 错误），之后中止登录。远程 HTTP 会被拒绝，可在 5 次内改正为 HTTPS 或 loopback HTTP。

常用命令

| 命令 | 说明 | | --- | --- | | /login LLMGates | 选择并配置 LLMGates、NewAPI、CLIProxyAPI、Sub2API 或通用兼容网关 | | /balance | 查看钱包、订阅余额 | | /endpoint <chat\|messages\|responses\|auto> [model-id] | 切换或清除一个 core 模型的推理出口 | | /endpoint-setting | 交互式多选，批量切换 core 与 2API 模型的推理出口 | | /model | 选择已注册的 LLMGates 模型 | | /calls | 查看本轮或本会话的 per-model 用量与费用明细 | | /reload | 安装或更新插件后重载扩展 | | /llmgates list \| remove <id> \| help | 列出、删除或查看兼容网关实例帮助 | | /llmgates-reload | 强制刷新 core 与全部 2API 的模型 catalog（绕过 freshness window，重写 thinking 档位等缓存） |

重新配置：随时再跑 /login LLMGates。/logout 清除 auth.json 登录凭证后，env / llmgates/config.json 中的 ambient 配置才会重新生效。交互式登录不会写入新的 API Key，也不会删除文件中已有的 ambient apiKey。

多网关 2API 兼容层

除 LLMGates 官方网关外，本扩展支持同时接入多个 OpenAI 兼容 2API 网关。每个实例有独立的 provider ID、base URL 和 API key，模型通过 GET /v1/models 发现后注册到 pi。

支持的网关

| 网关 | scheme | 典型用途 | 源码 | | --- | --- | --- | --- | | NewAPI | newapi | 自托管 AI 模型聚合与渠道管理 | QuantumNous/new-api | | Sub2API | sub2api | 订阅配额分发与多账号中转 | Wei-Shaw/sub2api | | CLIProxyAPI（CPA） | cpa | 本地 CLI 订阅代理，默认端口 8317 | router-for-me/CLIProxyAPI | | 通用 OpenAI 兼容网关 | default | 任意实现 GET /v1/models 的网关；仅需 URL + API Key，实例 ID 由 hostname 自动生成 | — |

同一 scheme 可添加多个实例（例如 work-newapi 与 home-newapi，或两个不同 hostname 的 default 实例），不同 scheme 也可并存。default 同一 hostname 重复添加时会自动分配 -2、-3 后缀。Base URL 可不写 /v1，扩展会自动规范到 /v1/models 探测。默认所有 scheme 共用 OpenAI Chat Completions 兼容 adapter，不会按 scheme 或模型名自动切换协议；如需改用 messages / responses，用 /endpoint-setting 显式配置（见 2API 的出口覆盖）。

添加实例（通用流程）

pi
/login LLMGates

/login 列表中不再单独显示 LLMGates 2API。进入 LLMGates 后先选择网关类型，顺序为 LLMGates（默认、最上方）→ NewAPI → CLIProxyAPI → Sub2API → 通用网关（default）。选择 LLMGates 会配置 core provider；选择其余类型会添加独立的 2API 实例。

兼容实例的后续提示顺序：

• NewAPI / CLIProxyAPI / Sub2API：实例 Provider ID → 显示名称（留空则使用 ID）→ Base URL → API Key
• 通用网关（default）：Base URL → API Key（实例 ID 由 URL hostname 自动生成，冲突时追加 -2 等后缀）

| 字段 | 说明 | | --- | --- | | scheme | 仅用于标签与 URL 占位提示，占位符不是默认值 | | 实例 ID | 须手动指定，用于 /login <id>、/model 与 /llmgates remove；1–64 字符，字母/数字开头，可含 . _ - | | Base URL | 须完整填写，通常以 /v1 结尾 | | API Key | 须显式输入；以 literal string 存入 auth.json，不展开 !cmd、$ENV 或 ${...} |

添加成功后执行 /model 选择该实例下的模型。Pi 0.81 模型选择器按 provider ID 区分同名模型，例如 grok-4.5 [work-newapi]。

运行 /logout，在选择器中选择实例的显示名称（可输入实例 ID 搜索），Pi 会删除 auth.json 凭证；本扩展监听该文件变更并异步删除对应的 2API registry、停止 provider 和 endpoint override。该实例不会保留为可恢复配置；若当前进程无法监听文件，执行 /reload 或重启会完成清理。

分网关简明教程

NewAPI

1. 按 NewAPI 文档 部署实例（Docker 或二进制均可）。
2. 在 NewAPI 控制台创建 API Key，确认 GET /v1/models 可访问。
3. 在 pi 中执行 /login LLMGates，选择 NewAPI，然后依次填写：
   • 实例 ID：如 work-newapi
   • 显示名称：如 工作 NewAPI（可留空）
   • Base URL：如 https://your-newapi-host/v1
   • API Key：控制台下发的密钥
4. /llmgates list 确认实例，/model 选用模型。

Sub2API

1. 按 Sub2API 仓库 的 deploy/ 说明部署（默认服务端口常为 8080）。
2. 在 Sub2API 管理后台生成 API Key。
3. 在 pi 中执行 /login LLMGates，选择 Sub2API，然后依次填写：
   • 实例 ID：如 team-sub2api
   • Base URL：如 https://sub2api.example.com/v1（本地可为 http://127.0.0.1:8080/v1）
   • API Key：后台生成的密钥
4. /model 选择模型开始对话。

CLIProxyAPI（CPA）

1. 按 CLIProxyAPI README 启动本地代理（默认监听 http://127.0.0.1:8317）。
2. 完成 CLI OAuth 登录后，确认 GET http://127.0.0.1:8317/v1/models 返回模型列表。
3. 在 pi 中执行 /login LLMGates，选择 CLIProxyAPI，然后依次填写：
   • 实例 ID：如 local-cpa
   • Base URL：http://127.0.0.1:8317/v1（loopback HTTP 允许）
   • API Key：按 CPA 实例配置填写（须非空；若网关未启用 Bearer 鉴权，以实际部署为准）
4. /model 选择 CPA 暴露的模型。

参考实现：@router-for-me/pi-cliproxyapi-provider（专注 CPA；本扩展在其基础上统一支持 NewAPI / Sub2API / CPA 多实例）。

管理命令

| 命令 | 说明 | | --- | --- | | /llmgates list | 列出实例 ID、scheme、base URL 和 display name（不显示密钥） | | /llmgates remove <id> | 删除指定实例及其 registry / auth / endpoint override 记录 | | /llmgates help | 显示用法与已知限制 | | /login <id> | 重新配置已登录实例的 base URL 和 API key（出现认证方式选择时请选 oauth 登录项；“Sign in with an API key” 项仅提示凭证已受管） |

实例 registry 写入 ~/.pi/agent/llmgates/2api.json，与 auth.json 均以 0600 权限写入，并使用跨进程文件锁、锁内重读和原子替换保护并发更新。

与 LLMGates 的差异

每个 2API 实例仅提供模型发现与推理，不提供余额、钱包、订阅或账号功能；/balance 仅适用于 core llmgates。

已知限制

• 正常启动时 /login 列表不再显示 llmgates-2api；仅当 core 不可用（llmgates/config.json identity 解析失败，或 legacy api_key / 损坏的 auth.json 触发 fail-closed）时，才显示恢复入口「LLMGates 兼容网关恢复」，用于在无 core 的情况下添加兼容实例。
• Pi 的 /logout 不提供扩展清理回调；本扩展通过监听 auth.json 变更清理已登出的 2API registry、provider 和 endpoint override。若监听未运行，/reload 或重启会补做清理；不会保留原实例作为可恢复配置。
• 若 auth.json 整体缺失或暂时损坏（如手动重置凭证、同步工具改写中途），本轮清理会被跳过以防止误删全部实例；文件恢复可读后清理自动继续。
• /llmgates remove <id> 后该实例的模型会立即消失；受 Pi 扩展 API 限制，/logout 仍可能短暂列出已删除的 ID，执行 /reload 后会完成清理。
• 若 auth.json 中存在没有对应 registry 记录的孤儿 auth key，/llmgates remove 无法处理，须手动删除 ~/.pi/agent/auth.json 中对应 ID 的条目。

功能概览

1. 在 /login 中注册 provider llmgates
2. 交互式配置：/login LLMGates 或 /login llmgates（baseUrl + API key）
3. 通过 GET /v1/models?client_version=pi 校验凭证并拉取目录
4. 将网关 catalog 映射为 pi 模型，按模型设置 api（responses / chat_completions / messages）
5. 跳过 image / video 生成 类模型（不适合 pi coding agent）
6. /balance — 通过 GET /v1/user/balance 查询钱包与订阅
7. TUI 扩展状态行：agent 运行中仅 Turn 17m.19c.$1.78；跑完或取消 settle 后同时展示 All 1h1m.100c, Turn 30m.20c.$10.10（All 为 session 累计，Turn 为本轮；下一轮开始时恢复仅 Turn）。session 费用可通过 /calls → This session 查看。父会话 assistant 用量在 message_end 时统计；同步 pi subagent / Cursor Task 工具结果与 .pi-subagents/artifacts/*_meta.json 汇总计入同一计数器；async / background 子代理通过 subagent:async-complete 旁路采集（缺 token 时再读 status.json / child session.jsonl）。设 LLMGATES_TPS_SUBAGENT=0 可关闭子代理旁路与 meta 扫描（父模型与 Cursor Task 仍统计）。用量聚合在后台任务链中执行，不阻塞 agent 循环。

配置

非交互式配置

适用于 CI 或无头环境，推荐使用环境变量，或使用 ~/.pi/agent/llmgates/config.json：

{
  "baseUrl": "https://apihk.llmgates.com/v1",
  "providerId": "llmgates",
  "providerName": "LLMGates"
}

可选在文件中写入 apiKey（/login 不会写入该字段）：

{
  "baseUrl": "https://apihk.llmgates.com/v1",
  "apiKey": "sk-llmgates-...",
  "providerId": "llmgates",
  "providerName": "LLMGates"
}

连接解析优先级（各来源不交叉借用 URL / key）：

1. auth.json 中的 OAuth 登录凭证（若存在）
2. 否则 env 中的 key + env URL（或官方默认 URL）
3. 否则文件中的 key + 文件 URL（或官方默认 URL）

环境变量

| 变量 | 作用 | | --- | --- | | LLMGATES_BASE_URL | 覆盖 llmgates/config.json 的 baseUrl | | LLMGATES_API_KEY | 覆盖 llmgates/config.json 的 apiKey | | LLMGATES_PROVIDER_ID | 覆盖 providerId（勿与内置 provider 冲突） | | LLMGATES_PROVIDER_NAME | 覆盖 providerName | | LLMGATES_PRICING_AUTO_UPDATE | 覆盖 pricingAutoUpdate（默认 true；0 / false 关闭） | | LLMGATES_DEBUG | 设为 1 / true / yes 时输出调试日志 | | LLMGATES_BLOCK_PRIVATE_URLS | 设为 1 / true / yes 时拒绝 IP 字面量 形式的 private / link-local 网关地址（loopback 仍允许）；hostname（如 gateway.local）不受此规则约束 | | LLMGATES_TPS_SUBAGENT | 默认启用；设为 0 / false / no 时关闭子代理 async 旁路与 meta 扫描 | | PI_OFFLINE | 设为 1 / true / yes 时跳过网络 catalog 刷新 |

上述开关统一解析：1 / true / yes / on 为开，0 / false / no / off 为关，其余值视为未设置（回落到各自默认）。

模型映射

| 网关字段 | Pi 字段 | | --- | --- | | id | id | | display_name | name | | context_window | contextWindow | | max_output_tokens | maxTokens | | capability_tags（vision） | input：text + image | | capability_tags（image / video generation） | 跳过 | | inference_endpoint 或 web_chat_endpoint | 每模型 api |

| endpoint 值 | pi api | | --- | --- | | responses | openai-responses | | chat_completions | openai-completions | | messages | anthropic-messages |

同时存在时，inference_endpoint 优先于 web_chat_endpoint。

思考等级（reasoning effort）

本插件对 所有 /model 可选模型（core LLMGates 与 2API）使用同一套固定档位，并 原样透传 给上游，不做 remap、不读网关 supported_reasoning_levels、不用 pi-ai 内置稀疏 map：

| pi 档位 | 发送给上游的 effort | | --- | --- | | off | none | | low | low | | medium | medium | | high | high | | xhigh | xhigh | | max | max |

minimal 不在 universal map 里（null 禁用）——LLMGates 上绝大多数模型（含 Claude）没有这一档；若个别 OpenAI 模型需要，用下方 modelOverrides 单独打开。

所有模型 reasoning: true，选择器始终暴露上述档位。上游不支持某档或返回 400 时由用户自行降档或换模型；插件不代为 clamp / 映射。

仍会从 pi-ai 精确 metadata 继承 传输层 compat（如 Anthropic forceAdaptiveThinking、supportsTemperature: false），这只影响请求形状，不改变 effort 字符串。

磁盘缓存恢复时也会重写为上述 universal map（不保留旧缓存里的 remap）。/llmgates-reload 可强制刷新 catalog。

用户级微调（pi 原生钩子）：在 ~/.pi/agent/models.json 用 providers.<实际 providerId>.modelOverrides 覆盖单个模型的思考等级（默认 provider ID 为 llmgates；最顶层，合并语义，只覆盖你写的 key）：

{
  "providers": {
    "llmgates": {
      "modelOverrides": {
        "gpt-5.6-sol": { "thinkingLevelMap": { "xhigh": null, "max": null } }
      }
    }
  }
}

thinkingLevelMap 的 key 为 off / minimal / low / medium / high / xhigh / max，value 为 string（发送给网关的 effort）或 null（禁用该档）。这是 pi 自带的模型覆盖钩子，不涉及 apiKey。

模型出口（endpoint / api）

可在聊天框切换一个 core LLMGates 模型的推理出口：

/endpoint <chat|messages|responses|auto> [model-id]

• 省略 model-id 时只修改当前模型；当前模型不是 core LLMGates 时拒绝，需显式指定 core model ID。
• 显式 ID 使用 core provider 精确匹配，不做 fuzzy match；同名 2API 模型不会被选中。
• chat → openai-completions，messages → anthropic-messages，responses → openai-responses。
• auto 只清除该模型的 per-model endpoint；若存在 defaults.endpoint，会回落到 defaults，而非跳过它直达网关值。
• 命令先原子保存 ~/.pi/agent/llmgates/models.json，再联网强制刷新 catalog、写入 provider store、发布并校验；目标是当前模型时还会重新绑定 registry 中的新对象。只有全部完成才显示成功。
• PI_OFFLINE、网络失败、provider 尚未就绪、store 写入失败或当前模型重绑失败时显示 warning：配置已保存但未完全激活，可联网后重试命令；重绑失败也可用 /model 重新选择。
• 命令进行中再次执行会被拒绝；本命令本身不支持批量，批量请用 /endpoint-setting。
• 仅修改 core provider；2API 模型请用 /endpoint-setting。

批量切换：/endpoint-setting

/endpoint-setting

• 两步交互：第一步勾选要修改的模型（支持跨 provider 多选），第二步选择 chat / messages / responses / auto。
• 第一步在 TUI 下是交互式勾选列表：↑↓ 移动、空格勾选、Tab 整组勾选、Ctrl+A 全选、Ctrl+D 清空（这三个操作在过滤时只作用于当前过滤结果）、直接输入即过滤（Backspace / Ctrl+U 清除搜索）、Enter 确认、Esc 取消。RPC 模式没有组件通道，回退为文本清单：把要修改的模型前的 [ ] 改成 [x]。
• 覆盖 core + 全部 2API 实例的模型；两步中任意一步取消或零选中都不会写入任何文件。
• 列表按 provider 分组，显示「model-id · 名字 · 当前出口」，* 表示已有 override。第三方扩展与 pi 内置 provider 的模型没有 api 写入通道，因此只作汇总披露、不可勾选；在文本清单中手工写入这些 id 会被明确拒绝并说明原因。
• 需要交互式界面：TUI 与 RPC 模式可用；print / json 模式会提示改用 /endpoint，不会报错也不会写文件。
• 每个 provider 只加一次锁、写一次文件、刷新一次，分组串行执行。
• 三态结果：全部成功为 info；文件已写入但未激活（离线 / provider 未就绪 / 被更新的刷新取代 / 部分模型未生效 / 当前模型重绑失败）一律为 warning，不会误报成功；只有所有 provider 都写入失败才是 error。跨 provider 部分成功时逐 provider 说明状态，已成功的部分保持生效，不回滚。
• 与 /endpoint、/endpoint-setting、/llmgates-reload 共用同一把 in-flight 锁：任一命令执行期间，其余命令会被拒绝。
• 2API 的上游是否支持 messages / responses 取决于你自己的中转部署，本扩展不探测、不拦截；选错了用 /endpoint-setting 选 auto，或对 core 模型用 /endpoint chat <model-id> 回退。

强制刷新 catalog：/llmgates-reload

/llmgates-reload

• 强制刷新 core + 全部 2API 实例的模型 catalog，绕过 background freshness window；会联网拉取 /v1/models 并写入各 provider store（含 thinking 档位等 metadata）。
• 不接受参数；与 /reload 不同——/reload 只重载扩展代码，不刷新 catalog。
• 每个 provider 串行执行一次 refreshEndpointForeground()；执行前会 waitForIdle()。
• 三态结果：全部刷新成功为 info；至少一个 provider 成功、其余 offline / 未就绪 / 被取代 / 抛错为 warning（文案含 partial）；零 provider 刷新成功且并非全部 hard-fail 时为 warning（did not update any provider，不含 partial）；全部 provider hard-fail 为 error。
• 与 /endpoint、/endpoint-setting 共用 in-flight 锁；任一命令执行期间会被拒绝。
• 若当前模型的 provider 刷新成功但该 model id 已不在新 catalog 中，追加 warning 提示用 /model 重选（不会 silent 保留 stale binding）。

也可手工编辑 ~/.pi/agent/llmgates/models.json：

{
  "defaults": { "endpoint": "responses" },
  "models": {
    "gpt-5.6-sol":      { "endpoint": "chat_completions" },
    "claude-sonnet-4-6": { "endpoint": "messages" }
  }
}

• 值接受别名：responses / chat·chat_completions·completions / messages·anthropic。
• 优先级：per-model > defaults > 网关 inference_endpoint/web_chat_endpoint > 按 id 启发式。
• 文件不存在（ENOENT）表示清空 override；有效 object 替换当前配置；JSON/根结构畸形时 warning 并继续使用该 core provider 实例的 last-known-good（首次加载则无 override，不与其他实例共享）。其他文件系统错误（如 EACCES / EISDIR）不会静默改路由：显式刷新在请求 catalog 前失败，后台刷新只 warning，并保留旧模型与缓存。warning 不输出 API key、文件原文或任意底层错误正文。
• 手工编辑后，endpoint 与 thinking metadata 只会在下一次成功的 core catalog refresh 完成网络映射、cache 写入和内存发布后生效。cache-only、PI_OFFLINE、freshness-window skip 都不会重映射缓存模型；网络或 cache 写入失败也保留旧值。这里没有周期 timer 或“最长 5 分钟自动生效”保证；优先使用 /endpoint 触发已验证的前台刷新。
• 缓存保存写入时的 api、thinkingLevelMap 与 compat；恢复时 api/thinking map 不重映射，只有既有的旧 Kimi 条目可补 transport compat。代码回滚不会改写配置。若旧版需人工清除 per-model 设定，删除对应 models.<id>.endpoint 后重启；随后按剩余优先级解析（可能先回落到 defaults.endpoint，不一定直接使用网关值）。store 的 checkedAt 若仍在 5 分钟 freshness window 内，仍可能暂用旧 api，需等待窗口并触发一次成功 refresh。新版可直接用 /endpoint auto [model-id]。
• llmgates/models.json 仅供 core llmgates provider 使用；2API 兼容层完全不读取它，两侧配置互不影响。

2API 的出口覆盖

2API 实例的 override 存放在每实例独立文件 ~/.pi/agent/llmgates/2api-models/<instanceId>.json，结构与 llmgates/models.json 相同（defaults.endpoint + models.<id>.endpoint），由 /endpoint-setting 或手工编辑维护。

• 优先级：per-model > defaults > chat_completions。2API 不使用网关 inference_endpoint 或按 id 的启发式——未配置 override 时行为与 0.1.12 完全一致。
• 与 core 双向隔离：core 不读 2api-models/，2API 不读 llmgates/models.json。
• 手工编辑后下一次 catalog refresh 即生效，无需重启。
• /llmgates remove <id> 会一并删除该实例的 override 文件；因此用同名 ID 重建实例时不会复活旧配置。删除失败会归入 partial 提示，不阻断其余清理步骤。
• 降级注意：若从 0.2.0 回退到 0.1.12，provider store 缓存中残留的非 openai-completions 模型会被旧版校验拒绝，该 2API 实例在首次成功联网 refresh 之前模型不可见。override 文件不会丢失，旧版会忽略 2api-models/——删除该目录不能解决 store 问题，联网触发一次成功的 catalog refresh（或重启 pi）即可自愈。

定价与费用估算

TUI 与 /calls 显示的费用为上游零售 API 费率估算，与 LLMGates 钱包扣费可能不同；账户实际消费请用 /balance 查询。

配置文件集中在 ~/.pi/agent/llmgates/（旧版平铺在 ~/.pi/agent/ 下的 llmgates.json、llmgates-2api.json、llmgates-model-pricing.json 会在扩展加载时自动迁移）：

llmgates/config.json — provider 配置与自动更新开关：

{
  "baseUrl": "https://apihk.llmgates.com/v1",
  "pricingAutoUpdate": true
}

设为 "pricingAutoUpdate": false 或 LLMGATES_PRICING_AUTO_UPDATE=0 则仅使用本地/manual 价格。

llmgates/models.json — core 每模型出口（endpoint / api）覆盖，由 /endpoint、/endpoint-setting 或手工编辑维护；文件本身不会从网关自动同步。详见 模型出口。

llmgates/2api-models/<instanceId>.json — 每个 2API 实例的出口覆盖，结构同上，由 /endpoint-setting 或手工编辑维护；/llmgates remove 时随实例一并删除。

llmgates/pricing.json — 可编辑的 USD / 100 万 token 单价（input、output、cacheRead、cacheWrite）。键为 modelId 或 provider/modelId（如 openai/gpt-5.6-sol）：

{
  "_comment": "overrides 始终优先于 rates 与自动同步",
  "updatedAt": 0,
  "lastAutoSyncAt": 0,
  "rates": {
    "openai/gpt-5.6-sol": { "input": 5, "output": 30, "cacheRead": 0.5, "cacheWrite": 6.25 }
  },
  "overrides": {
    "anthropic/claude-sonnet-4-6": { "input": 3, "output": 15, "cacheRead": 0.3, "cacheWrite": 3.75 }
  }
}

启用 pricingAutoUpdate 时，每次 /models 刷新会在后台从 LiteLLM 同步 catalog 模型的零售价（不阻塞列表）：缺失模型立即拉取，否则每 24h 刷新。同步失败时保留缓存与静态规则（LLMGATES_DEBUG=1 可查看详情）。自动同步只写 rates，不修改 overrides。catalog 外 rates 条目在刷新时保留。每次刷新会重读磁盘，手改无需重启。extensions/model-pricing.ts 中的静态规则为离线兜底。同步成功后会在内存中 patch 已注册模型的 cost 字段，不额外请求 catalog。

Pi 内置 footer 在 OAuth 登录时可能仍显示 (sub)，该标记与 LLMGates 计费无关。

安全

• API key 一律视为 literal string；!、$、${...}、$$、$! 等不会被解释为 shell 命令或环境变量展开。
• 连接归属原子化，优先级见 连接解析优先级；env key 不借用 file URL，file key 不借用 env URL，OAuth 不借用 env / file URL。
• 远程网关须使用 HTTPS；HTTP 仅允许 loopback（localhost、127.0.0.0/8、::1、IPv4-mapped loopback）。无 insecure 覆盖开关。
• 网关网络调用（/models、/balance、推理）使用全操作超时、5 MiB 响应体上限、同源手动重定向。
• 启用 pricingAutoUpdate 时，零售价同步从 raw.githubusercontent.com 拉取固定 LiteLLM JSON（后台、30s 超时、8 MiB 上限），不阻塞目录或推理。可通过配置或 LLMGATES_PRICING_AUTO_UPDATE=0 关闭。
• TPS / 费用统计在后台队列预处理 assistant usage；畸形 usage 跳过或归零，失败不影响推理（LLMGATES_DEBUG=1 记录详情）。
• 启动采用 cache-first；cache-only、离线或 freshness-window skip 直接使用缓存中的 routing/thinking metadata。session 启动可触发一次后台刷新，但没有周期刷新 timer；失败会 warning 并保留旧 catalog/cache。
• 普通 catalog refresh 只有在网络映射与 cache 写入都成功后才发布新模型；网络或 cache 写入失败保留内存与磁盘旧值。登录后 cache 写入失败是例外：不撤销登录，会话使用已验证目录，磁盘保留旧缓存。
• 优先 /login 或 LLMGATES_API_KEY，避免在 llmgates/config.json 存 key。配置写入 mode 0600 且原子替换。
• 不支持 / 不安全： 通过 ~/.pi/agent/models.json overlay 配置本 provider 的 apiKey（pi 可能重新启用 config-value 语法）。请勿这样做。
• 历史迁移： auth.json 中若存在 type: "api_key" 凭证，注册 fail-closed。删除该条目或 /logout 后 /reload；扩展不会自动迁移或改写 auth.json。
• 默认网关：https://apihk.llmgates.com/v1。

故障排查

| 现象 | 处理 | | --- | --- | | 安装后扩展未加载 | /reload 或重启 pi | | 安装后无模型 | /login LLMGates；检查 LLMGates 侧 key 的 allowed_models | | 启动时 401 / 403 | 重新 /login 或更新 LLMGATES_API_KEY | | Kimi / tokenization failed | 升级本扩展后 /reload；Kimi 不接受 developer role，扩展会注入 compat。也可新建会话再试（中途从其他模型切到 K3 不稳定） | | 看不到 image / video 模型 | 预期行为 — 生成类模型按 capability_tags 过滤 | | 列表出现意外生成模型 | 网关 catalog 须用 image_generation、video_* 等 tag 标记；未标记的模型会保留 | | 费用与账单不一致 | TUI 费用为上游零售价估算；账户消费看 /balance | | 需要调试日志 | LLMGATES_DEBUG=1 后 /reload |

开发

git clone https://github.com/ax128/pi-llmgates.git
cd pi-llmgates
npm install
npm run build    # 编译 extensions/ → dist/（pi.extensions 指向 dist，源码改动后必须重新 build）
npm run check    # typecheck + vitest
pi install .

设计与实现文档见 docs/README.md。

发布（维护者）

发布前必须先过本地门禁（npm run gate → 安装 .tgz → 功能验证 → gate-record-pass.sh），见 docs/pre-publish-gate.md。

Agent / 维护者完整 npm 流程（要认证链接 → 等用户回复 → 发布 → 给安装命令）见：

• docs/pre-publish-gate.md（门禁，不可跳过）
• docs/npm-package.md（开头「Agent 标准发布对话」）
• AGENTS.md

set -a && source .env && set +a
node ./scripts/npm-publish-auth-link.mjs   # 把链接发给操作者
./scripts/publish-npm.sh --otp=<验证码>   # 对方回复后再执行

相关文档

| 文档 | 说明 | | --- | --- | | docs/README.md | 内部设计规格、实施计划与源码入口索引 | | LLMGates | 网关与 API Key | | pi 文档 | Pi 扩展与 Provider API |

许可证

MIT — 见 LICENSE