custom-provider-pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 custom-provider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# custom-provider
+
+pi 扩展：在 TUI 或 RPC（Telegram 等）环境下统一管理第三方模型 Provider。
+
+一个命令入口 `/custom-provider`，九个子命令覆盖添加、删除、刷新、测试、查看/编辑配置、启用/禁用与模型修剪；既支持交互引导，也支持 `--flags` / JSON 参数非交互添加（脚本、Telegram 可用）。同一 Provider 内可混用 OpenAI 与 Anthropic 协议（按模型覆盖）。
+
+## 安装
+
+### 方式一：直接放扩展目录（已安装本机）
+
+把 `custom-provider.ts` 复制到 pi 的全局扩展目录即可热加载：
+
+```bash
+cp custom-provider.ts ~/.pi/agent/extensions/
+# 然后在 pi 里 /reload
+```
+
+### 方式二：作为 pi 包安装（发布到 npm / git）
+
+本目录已带 `pi` 清单（`package.json#pi.extensions`），可作为 pi 包分享：
+
+```bash
+# 从本地目录或 git 仓库安装
+pi install local:E:/custom-provider        # 或 git:... / npm:...
+```
+
+运行时无任何第三方依赖（只用 Node 内置模块），`@earendil-works/pi-coding-agent` 仅做类型引用，由 pi 运行时捆绑，声明在 `peerDependencies`。
+
+## 命令总览
+
+```
+/custom-provider add [名称] [flags]          添加（交互引导或参数化添加）
+/custom-provider remove <名称> [--yes]       删除（--yes 跳过确认）
+/custom-provider refresh [名称]              重新拉取模型列表
+/custom-provider list                        列出所有 provider（含启用状态）
+/custom-provider test <名称> | --base-url    测试连接（已配置项或临时端点）
+/custom-provider config [edit|path|<名称>]   查看 / 编辑配置
+/custom-provider enable|disable <名称>       启用 / 禁用 provider
+/custom-provider prune <名称> [--keep/--drop 关键词]  修剪模型列表（避免全量保留）
+/custom-provider help                        显示帮助
+```
+
+Tab 键可自动补全子命令与 provider 名（大小写不敏感）。
+
+## add 详解
+
+### 交互模式
+
+```
+/custom-provider add
+```
+
+按向导依次输入：名称 → 端点 URL → API Key → 协议类型 → 是否自动拉取模型 → 自定义请求头 → 高级配置 → 模型列表。自动拉取成功后**会询问如何过滤模型**（按关键字保留/排除），避免把渠道全量模型写入配置。
+
+### 参数模式（非交互）
+
+```
+/custom-provider add deepseek \
+    --base-url https://api.deepseek.com/v1 \
+    --api-key $DEEPSEEK_API_KEY \
+    --models deepseek-chat,deepseek-reasoner
+```
+
+| flag | 说明 |
+|---|---|
+| `--name` / 位置参数 | provider 名称（字母/数字/-/_，≤32 字符） |
+| `--base-url` / `--url` | API 端点（自动清理 `/v1/models` 尾巴并补全 `/v1`） |
+| `--api-key` / `--key` | 支持 `$ENV` / `!命令` / 字面量 / `local`（默认） |
+| `--api` | `auto`（默认，按 URL 推断）\| `openai-completions` \| `openai-responses` \| `anthropic-messages` \| `google-generative-ai` |
+| `--models` | 逗号分隔的模型 ID 列表 |
+| `--model` | 单个模型 ID，可多次累加 |
+| `--header "K: V"` | 自定义请求头，可多次 |
+| `--headers '{"k":"v"}'` | 以 JSON 形式设置请求头 |
+| `--auth-header` | 开启 `Authorization: Bearer <key>`（非标准 API 用） |
+| `--compat '{...}'` | 协议兼容选项（如 `supportsDeveloperRole`） |
+| `--overrides '{"模型id":{...}}'` | 按模型覆盖：`reasoning` / `input` / `contextWindow` / `maxTokens` / `cost` / `api` / `baseUrl` |
+| `--model-api "模型id:协议"` | 让单个模型走另一协议，可多次（见下文双协议） |
+| `--model-base-url "模型id:url"` | 让单个模型使用另一端点，可多次 |
+| `--force` / `-f` | 已存在时直接覆盖（不加则交互确认 / 报错） |
+| `--json '{...}'` | 完整配置 JSON（跳过所有 flag） |
+| `--ua <预设\|原始UA>` | 预设 User-Agent（见下），或直接给自定义字符串 |
+| `--profile <模板键>` | 应用完整请求头模板（`claude-code` / `codex` / `opencode` / `browser` 等，含 UA + 客户端典型头集合） |
+| `--proxy <URL>` | HTTP/SOCKS 代理地址（支持 `$ENV`） |
+
+### JSON 参数
+
+```
+/custom-provider add --json '{
+  "name": "gw",
+  "baseUrl": "https://gw.example.com/v1",
+  "apiKey": "$MY_KEY",
+  "api": "openai-completions",
+  "enabled": true,
+  "authHeader": false,
+  "headers": { "X-Custom": "v" },
+  "models": ["gpt-4o", { "id": "claude-x", "api": "anthropic-messages" }]
+}'
+```
+
+## 双协议混用（同一 Provider 内 OpenAI + Anthropic）
+
+协议决定优先级：**模型 `api` 字段 > provider 级 `api` > 按 URL 自动推断（默认 `openai-completions`）**；模型 `baseUrl` 同理可覆盖端点。
+
+三种配置方式：
+
+**① flags：**
+```
+/custom-provider add gw --base-url https://gw.example.com/v1 --api-key $K \
+    --models gpt-4o,claude-x \
+    --model-api claude-x:anthropic-messages \
+    --model-base-url claude-x:https://api.anthropic.com
+```
+
+**② 高级配置（交互向导 → 高级配置）：**
+```json
+{
+  "authHeader": false,
+  "compat": {},
+  "modelOverrides": {
+    "claude-x": { "api": "anthropic-messages", "baseUrl": "https://api.anthropic.com" }
+  }
+}
+```
+
+**③ JSON 参数：** 见上文 `--json` 示例。
+
+### User-Agent 预设
+
+部分中转/反代服务会按 UA 指纹拦截非浏览器/SDK 请求。除浏览器默认外，内置以下预设（反代一般只校验前缀关键字，版本号仅供参考，可自行改源码 `UA_PRESETS`）：
+
+| 预设键 | 行为示例 |
+|---|---|
+| `browser`（默认） | `Mozilla/5.0 ... Chrome/131.0.0.0 Safari/537.36` |
+| `claude-code` | `claude-code/2.1.237` |
+| `codex` | `codex_cli_rs/0.148.0 (cli)` |
+| `opencode` | `opencode/1.18.19` |
+| `cursor` | `Cursor/3.16.0 (Windows; 64bit)` |
+| `windsurf` | `Windsurf/2.0.0 (Windows)` |
+| `openwebui` | `OpenWebUI/0.11.0` |
+| `chatgpt` | `Mozilla/5.0 ... ChatGPT-Desktop/1.2025.0` |
+
+使用：
+
+```
+/custom-provider add my --base-url https://gw.example.com/v1 --api-key $K \
+    --models gpt-4o --ua claude-code                # 预设键
+/custom-provider add my --base-url ... --ua "MyApp/1.0"   # 直接给原始字符串
+```
+
+交互向导在「自定义请求头」后会询问 UA 预设（选「自定义」可自己输入）。若请求头里已显式写入 `User-Agent`，则以你写的为准，不覆盖。
+
+### 请求头模板
+
+`--ua` 只预设一个 `User-Agent` 头。`--profile` 预设**整组请求头**（UA + 客户端典型头集合），对 Claude Code、Codex 等不同客户端各自携带的头集合不同：
+
+| 模板键 | 包含的头 |
+|---|---|
+| `browser`（默认） | 仅 UA（浏览器） |
+| `claude-code` | UA + `anthropic-version` + `x-app` + `content-type` + `anthropic-dangerous-direct-browser-access` |
+| `codex` | UA + `accept` |
+| `opencode` | UA |
+| `cursor` | UA |
+
+```
+/custom-provider add my --base-url ... --api anthropic-messages \
+    --models claude-sonnet-4 --profile claude-code
+```
+
+> 优先级：`--header`/`--headers` 显式头 > `--profile` 模板 > `--ua` > 默认浏览器 UA
+
+请求头值支持 `$ENV` / `!cmd` 插值（pi 请求时动态解析），支持 JSON 对象或逐行 `"Key: Value"` 两种格式输入。敏感头（`authorization`、`x-api-key`、`anthropic-beta` 等）允许设置但会给出警告提示。
+
+### 代理
+
+`--proxy` 支持 HTTP/SOCKS 代理地址，配置后注册时会设置 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` 环境变量：
+
+```
+/custom-provider add my --base-url https://api.deepseek.com/v1 \
+    --api-key $KEY --models deepseek-chat --proxy http://127.0.0.1:7890
+```
+
+> ⚠️ Node.js 的 `fetch` 需要 `NODE_USE_ENV_PROXY=1` 才会读取代理环境变量（Vite/Tauri 等桌面应用的内置 fetch 也类似）。传统 `http.request` / `https.request` 不读取这些变量；如需在 Node 底层走代理，请用 `global-agent` 等库或升级到 Node ≥ 22 并设置该环境变量。
+## prune：模型修剪
+
+添加时自动拉取后已提供关键字过滤；对已有 provider 可用 `prune` 事后修剪：
+
+```
+/custom-provider prune cpa                       # 交互：列出并按关键字筛选
+/custom-provider prune cpa --keep "deepseek,glm" # 只保留 ID 含任一关键字的模型
+/custom-provider prune cpa --drop "qwen,mini"    # 排除 ID 含任一关键字的模型
+/custom-provider prune cpa --keep "deepseek" --drop "4.1"
+```
+
+- 大小写不敏感子串匹配；`--keep` / `--drop` 可组合
+- 过滤结果为空或未命中时不修改并提示；保留原有模型的详细配置（contextWindow 等）
+- 支持 Tab 补全 provider 名
+
+## enable / disable
+
+`disable` 写入 `"enabled": false` 并立即注销（`/model` 中消失，配置保留）；`enable` 恢复并重新注册。
+
+```
+/custom-provider disable cpa    # 对应配置: "enabled": false
+/custom-provider enable cpa
+```
+
+启动注册、`refresh`、`test`、`prune` 都会跳过 / 拦截已禁用项；`add` 覆盖已禁用 provider 时会保留其禁用状态。
+
+## config / list / test / refresh
+
+```
+/custom-provider config              # 配置摘要（含文件路径与启用状态）
+/custom-provider config cpa          # 单个 provider 的完整 JSON
+/custom-provider config edit         # 编辑器修改，保存即校验并全量重注册
+/custom-provider config path         # 配置文件路径
+/custom-provider list                # 全部 provider：状态 / 协议 / 端点 / 模型预览
+/custom-provider test cpa            # 用配置测试连接（拉取 /models 验证端点与 Key）
+/custom-provider test --base-url http://localhost:8080/v1 --api-key local   # 测临时端点，不保存
+/custom-provider refresh cpa         # 重新拉取模型列表（保留已有模型详细配置）
+```
+
+## 配置文件
+
+默认位置（Windows 示例）：
+
+```
+C:\Users\<你>\.pi\agent\custom-providers.json
+```
+
+```jsonc
+{
+  "providers": [
+    {
+      "name": "cpa",                  // 名称，唯一
+      "baseUrl": "https://cpa.example.com/v1",
+      "apiKey": "$CPA_API_KEY",       // 见下方取值语法
+      "api": "openai-completions",    // 可选：协议类型
+      "enabled": true,                // 可选：false = 禁用（不注册）
+      "headers": { "X-Custom": "v" }, // 可选：请求头，值支持 $ENV
+      "authHeader": false,            // 可选：非标准 API 用
+      "compat": {},                   // 可选：协议兼容选项
+      "models": [
+        "gpt-4o",                                             // 字符串 = 走 provider 默认协议
+        { "id": "claude-x", "api": "anthropic-messages" },    // 对象 = 按模型覆盖
+        { "id": "vision-1", "input": ["text", "image"], "reasoning": true,
+          "contextWindow": 200000, "maxTokens": 16384,
+          "cost": { "input": 0, "output": 0 } }
+      ]
+    }
+  ]
+}
+```
+
+`apiKey` 与 header 值的取值语法（pi 原生支持，请求时动态解析）：
+
+| 写法 | 含义 |
+|---|---|
+| `sk-xxx` 字面量 | 直接使用 |
+| `$ENV_VAR` / `${ENV_VAR}` | 环境变量插值 |
+| `!command` | 执行命令，以输出作为值（如 `!cat ~/.key`） |
+| `local` | 无认证的本地服务（默认） |
+
+模型规格（`contextWindow` / `maxTokens`）未显式配置时，自动按 OpenRouter 公开目录（24h 磁盘缓存）→ 内置已知规格 → 保守默认（128K / 16K）填充。
+
+## 安全注意事项
+
+- `apiKey` 与 header 值**明文存储**在 `custom-providers.json`，请勿把该文件同步进公开仓库；Linux 下可考虑收紧权限
+- `!command` 特性会执行配置中的命令，仅编辑你信任的配置文件
+- 自定义请求头建议使用 `$ENV` 引用而非字面量，避免密钥落盘
+
+## 开发
+
+```bash
+npm install          # 安装 devDependencies（typescript / @types/node）
+npm run typecheck    # tsc --noEmit 类型检查
+```
+
+类型依赖只用于本地检查：运行时零第三方依赖，pi 通过 jiti 直接加载 `.ts`。
+
+## 发布为 pi 包
+
+```bash
+npm pack             # 打包（files: custom-provider.ts, README.md, LICENSE）
+```
+
+或推送到 git 仓库后 `pi install git:...`。包已带 `pi-package` 关键字，便于在 pi 包目录被发现。