dsh-gateway-provider 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luck9Star
+
+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,234 @@
+# dsh-gateway-provider
+
+[![gitleaks](https://github.com/Luck9Star/dsh-gateway-provider/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/Luck9Star/dsh-gateway-provider/actions/workflows/gitleaks.yml)
+
+> 中文文档：[README.zh.md](README.zh.md)
+
+Bring any LLM gateway — **newapi, LiteLLM, Higress, or any OpenAI-compatible
+endpoint** — into DeepSeek Harness. The plugin discovers the gateway's model
+list automatically, enriches every model with real parameters from
+[models.dev](https://models.dev), and serves each model over its native wire
+protocol (OpenAI / Anthropic / Gemini) through the pi-ai SDK.
+
+## Why this exists
+
+DeepSeek Harness ships first-party adapters (`llm-deepseek`, `llm-pi-ai`) that
+each speak for one provider. If your models live behind a gateway, the
+alternative is a hand-maintained static model list with guessed context
+windows and output caps.
+
+This plugin mounts the gateway itself: **N gateways become N provider
+routes, with zero static model lists.** Every model keeps its true
+parameters, and adding a model on the gateway side is enough — nothing to
+re-deploy.
+
+## What you get
+
+- **Multiple gateways** — a default `newapi` route plus one `gateway:<id>`
+  route per extra gateway, each with its own catalog cache.
+- **Automatic discovery** — `GET {base}/v1/models` first (including each
+  model's supported request formats), management API fallback second.
+- **Real parameters** — models.dev data fills context window, output cap,
+  reasoning levels, and release date; config defaults are only a fallback.
+- **Every wire format** — each model routes to its own protocol
+  (`openai-completions` / `openai-responses` / `anthropic-messages` /
+  `google-generative-ai`); no hand-written SSE or request serialization.
+- **A settings page** — **Settings → Gateway Models**: add and edit gateways
+  from templates, test connections, hide / override / custom-add models —
+  no YAML editing required.
+- **A clean picker** — newest-first release-date sorting, chat-only filtering,
+  and regex excludes for non-chat models.
+
+## Requirements
+
+- A DeepSeek Harness installation with a profile (`dsh`)
+- A reachable gateway: newapi / LiteLLM / Higress / any OpenAI-compatible endpoint
+- An API key for that gateway
+
+## Quickstart
+
+1. Install the plugin into your profile — straight from GitHub, no clone needed:
+
+   ```bash
+   dsh plugin --profile web add git+https://github.com/Luck9Star/dsh-gateway-provider.git
+   ```
+
+   `dsh plugin add` forwards to `pnpm add` in the profile directory, so any
+   pnpm spec works (`github:Luck9Star/dsh-gateway-provider`, a local path, …).
+   The bundle patch (`cordis.patch.yml`) then mounts the `llm-newapi` loader
+   row automatically — no manual patch editing. The bare package name will
+   resolve once the package is published to npm.
+
+2. Store your gateway key in `$DSH_HOME/.credentials.yaml` (mode 0600,
+   hot-reloaded):
+
+   ```yaml
+   NEWAPI_API_KEY: sk-REPLACE_WITH_YOUR_KEY
+   ```
+
+   Or export `NEWAPI_API_KEY` in the launching environment.
+
+3. Restart the profile, then open **Settings → Gateway Models**.
+
+**Success looks like:** the gateway appears with a "synced N models" badge,
+and every chat-capable model is selectable with its real context window.
+The base URL resolves from `llm-newapi.baseURL` settings →
+`NEWAPI_BASE_URL` / `NEWAPI_API_URL` env → the public default
+`https://api.newapi.ai`.
+
+## Add more gateways
+
+Extra gateways live in the `gateways` array — each becomes its own
+`gateway:<id>` provider route:
+
+```yaml
+llm-newapi:
+  baseURL: https://your-newapi-instance.com
+  gateways:
+    - id: litellm-prod
+      label: LiteLLM Prod
+      baseURL: https://litellm.example.com
+      apiKeyEnv: LITELLM_API_KEY
+      flavor: litellm            # form template: newapi / litellm / higress / openai-compatible / custom
+
+    # Fully-custom gateway: complete per-protocol endpoint URLs, no shared
+    # base. A protocol left empty stays disabled.
+    - id: edge
+      label: Edge GW
+      flavor: custom
+      openaiURL: https://edge.example.com/openai/v1/chat/completions
+      responsesURL: https://edge.example.com/openai/v1/responses
+      anthropicURL: https://edge.example.com/anthropic/v1/messages
+      apiKeyEnv: EDGE_API_KEY
+```
+
+You can also add gateways from the settings page (with the same templates)
+instead of editing YAML.
+
+## Control the model list per gateway
+
+Hide models, fix wrong metadata, or add models the gateway does not list:
+
+```yaml
+llm-newapi:
+  models:
+    - id: glm-5.2
+      disabled: true              # hide from picker
+    - id: glm-5.2-highspeed
+      contextWindow: 1000000      # override discovered value
+      protocol: openai            # force protocol (openai/anthropic/gemini/openai-response)
+    - id: my-internal-model       # custom model the gateway does not list
+      name: My Internal Model
+      contextWindow: 200000
+```
+
+The **Gateway Models** page exposes the same operations with a UI: search,
+hidden/custom filters with counts, a per-model override editor (placeholders
+show discovered values), connection test, and save/cancel semantics.
+
+## Configuration reference
+
+Section `llm-newapi:` of `$DSH_HOME/settings.yaml`. The flat fields
+(`baseURL` / `apiKeyEnv` / …) seed the default `newapi` route; gateways in
+the `gateways` array support most of the same fields per gateway
+(`label` / `apiKeyEnv` / `flavor` / `catalogMode` / `endpointPriority` / …).
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `label` | `NewAPI` | Display name of the default gateway route |
+| `apiKeyEnv` | `NEWAPI_API_KEY` | Credential reference (environment variable name) |
+| `baseURL` | env `NEWAPI_BASE_URL` / `NEWAPI_API_URL` → `https://api.newapi.ai` | Gateway base URL (unused when protocol URLs are set) |
+| `flavor` | `newapi` | Gateway template: `newapi` / `litellm` / `higress` / `openai-compatible` / `custom` |
+| `openaiURL` | – | Full chat-completions endpoint URL (custom template; empty = protocol disabled) |
+| `responsesURL` | – | Full Responses endpoint URL (custom template; empty = protocol disabled) |
+| `anthropicURL` | – | Full Anthropic messages endpoint URL (custom template; empty = protocol disabled) |
+| `modelsUrl` | `https://models.dev/models.json` | models.dev source (`file:` URLs work offline) |
+| `useModelsDev` | `true` | Enrich gateway models with models.dev parameters |
+| `extendedReasoningLevels` | `false` | Widen the unknown-model reasoning fallback to off~max (default off/low/medium/high) |
+| `sortModelsByRelease` | `true` | Sort the picker newest-first by release date (unknown dates first) |
+| `catalogMode` | `auto` | Model-list source: `auto` / `v1` / `management` |
+| `catalogTtlMs` | `1800000` | Model-list cache freshness window |
+| `includeChatOnly` | `true` | Only expose chat-capable models to the picker |
+| `excludePatterns` | image/speech/embed/… | Regex patterns excluding models from the picker |
+| `endpointPriority` | `["openai-response","anthropic","openai","gemini"]` | Wire-format preference order (first match wins per model) |
+| `userId` | `1` | `New-Api-User` header for the management API |
+| `maxTokens` | `32768` | Output cap fallback when models.dev lacks data |
+| `defaultContextWindow` | `128000` | Context window fallback when models.dev lacks data |
+| `streamIdleTimeoutMs` | `300000` | Stream idle watchdog |
+| `retryPolicy` | standard | Same shape as `llm-deepseek` |
+
+## How it works
+
+All wire-format concerns are delegated to
+[`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
+— the same SDK the official `dsh-llm-pi-ai` adapter uses. Per request:
+
+```
+harness GenerateOptions
+  → toPiContext()          lib/pi-bridge.js   harness messages → pi-ai Context
+  → models.streamSimple()  pi-ai SDK          dispatches by each model's `api`
+  → toStreamChunks()       lib/pi-bridge.js   pi-ai events → harness chunks
+```
+
+Each discovered model is built with an `api` field mapped from the gateway's
+advertised `supported_endpoint_types`, honoring `endpointPriority`; the
+pi-ai provider receives an api *map*, so every model routes to its own
+protocol implementation. `sdkBaseURL()` appends `/v1` for OpenAI-protocol
+models and leaves Anthropic/Google bases untouched.
+
+```
+dsh-gateway-provider/
+├── index.js            # plugin entry: Config, provider registration, settings/credentials
+├── cordis.patch.yml    # dsh.bundle patch (auto-mounts via `dsh plugin add`)
+├── lib/                # adapter, pi-provider, pi-bridge, catalog, modelsdev, thinking, client
+├── test/               # smoke (live gateway) + offline units + settings-UI render
+└── scripts/link.sh     # link profile node_modules for local checkouts
+```
+
+## Develop from a checkout
+
+1. `bash scripts/link.sh` — symlink this package's `node_modules` to the
+   profile's so bare `@deepseek-ai/*` imports resolve to the exact module
+   instances the harness process uses (single-copy `instanceof` safety).
+2. Register the checkout as a profile link dependency and install:
+
+   ```bash
+   cd "$DSH_HOME/profiles/web"
+   # package.json dependencies: "dsh-gateway-provider": "link:/absolute/path/to/dsh-gateway-provider"
+   # and add "dsh-gateway-provider" to the bundles list in the same file
+   pnpm install
+   ```
+
+3. Restart the profile.
+
+> ⚠️ Do **not** also insert `id: llm-newapi` into the profile's own
+> `cordis.patch.yml` — the bundle layer already mounts it, and a duplicate
+> raises `duplicate loader entry id` at boot.
+
+Client-bundle edits hot-apply after a browser reload; host-half edits need a
+profile restart.
+
+### Tests
+
+```bash
+node test/smoke.mjs            # live gateway: catalog / openai × 2 / tools / anthropic / gemini / custom-urls
+node test/smoke.mjs --only custom-urls
+node test/protocol-urls.mjs    # offline: URL derivation + gateway resolution
+node test/client-render.mjs    # offline: settings-UI render tree (zh + en)
+```
+
+Smoke-test credentials resolve from: process environment → plugin `.env` →
+`$NEWAPI_ENV_FILE` (plus a legacy author-local fallback path).
+
+## Security
+
+- The API key is only resolved through `$DSH_HOME/.credentials.yaml` (0600)
+  or the environment — never written to logs, config, or chat.
+  Credential fields are edited masked on the web UI.
+- No runtime `dependencies`; `peerDependencies` reuse the harness-installed
+  `@deepseek-ai/*` packages and `@earendil-works/pi-ai`. Commits are gated
+  by gitleaks locally (pre-commit) and in CI.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,218 @@
+# dsh-gateway-provider
+
+[![gitleaks](https://github.com/Luck9Star/dsh-gateway-provider/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/Luck9Star/dsh-gateway-provider/actions/workflows/gitleaks.yml)
+
+> English: [README.md](README.md)
+
+把任意 LLM 网关 —— **newapi、LiteLLM、Higress 或任何 OpenAI 兼容端点** —— 接入
+DeepSeek Harness。插件自动发现网关的模型列表，用 [models.dev](https://models.dev)
+的真实参数补齐每个模型，并通过 pi-ai SDK 以模型原生协议（OpenAI / Anthropic /
+Gemini）分发请求。
+
+## 为什么需要它
+
+DeepSeek Harness 自带的适配器（`llm-deepseek`、`llm-pi-ai`）各自只服务一个官方
+provider。如果你的模型都在网关后面，就得手工维护一份静态模型清单，上下文窗口、
+输出上限全靠猜。
+
+本插件直接把网关挂进来：**N 个网关 = N 个 provider 路由，零静态清单。** 每个模型
+带着真实参数，网关侧加模型即可生效——无需重新部署。
+
+## 你能得到什么
+
+- **多网关** — 默认 `newapi` 路由 + 每个额外网关一条 `gateway:<id>` 路由，
+  各自独立 catalog 缓存。
+- **自动发现** — 首选 `GET {base}/v1/models`（含每个模型支持的请求格式），
+  管理 API 兜底。
+- **真实参数** — models.dev 补齐上下文窗口、输出上限、推理等级、发布日期；
+  配置默认值只是兜底。
+- **全协议覆盖** — 每个模型路由到自己的协议（`openai-completions` /
+  `openai-responses` / `anthropic-messages` / `google-generative-ai`），
+  无手写 SSE、无手写请求序列化。
+- **图形设置页** — **设置 → 网关模型**：按模板添加/编辑网关、测试连接、
+  隐藏/覆写/自定义添加模型——不用碰 YAML。
+- **干净的选择器** — 按发布日期新到旧排序、只保留对话模型、正则剔除。
+
+## 环境要求
+
+- 装有 profile 的 DeepSeek Harness（`dsh`）
+- 一个可达网关：newapi / LiteLLM / Higress / 任意 OpenAI 兼容端点
+- 该网关的 API Key
+
+## 快速开始
+
+1. 把插件装进 profile——直接从 GitHub 安装，无需 clone：
+
+   ```bash
+   dsh plugin --profile web add git+https://github.com/Luck9Star/dsh-gateway-provider.git
+   ```
+
+   `dsh plugin add` 会在 profile 目录里转发执行 `pnpm add`，因此任何
+   pnpm spec 都可用（`github:Luck9Star/dsh-gateway-provider`、本地路径等）。
+   bundle 补丁（`cordis.patch.yml`）随后自动挂载 `llm-newapi` 加载行——
+   无需手工改 patch。裸包名要等发布到 npm 之后才能解析。
+
+2. 把网关 key 写入 `$DSH_HOME/.credentials.yaml`（权限 0600，热加载）：
+
+   ```yaml
+   NEWAPI_API_KEY: sk-REPLACE_WITH_YOUR_KEY
+   ```
+
+   或在启动环境中导出 `NEWAPI_API_KEY`。
+
+3. 重启 profile，打开 **设置 → 网关模型**。
+
+**成功的样子：** 网关出现并带"已同步 N 个模型"徽标，全部对话模型可选、
+上下文窗口是真实值。基础地址解析顺序：`llm-newapi.baseURL` 设置 →
+`NEWAPI_BASE_URL` / `NEWAPI_API_URL` 环境变量 → 公共默认
+`https://api.newapi.ai`。
+
+## 添加更多网关
+
+额外网关写在 `gateways` 数组——每个成为独立的 `gateway:<id>` provider 路由：
+
+```yaml
+llm-newapi:
+  baseURL: https://your-newapi-instance.com
+  gateways:
+    - id: litellm-prod
+      label: LiteLLM 生产
+      baseURL: https://litellm.example.com
+      apiKeyEnv: LITELLM_API_KEY
+      flavor: litellm            # 表单模板：newapi / litellm / higress / openai-compatible / custom
+
+    # 完全自定义网关：各协议写完整端点地址，不共享基础地址；
+    # 留空的协议不启用。
+    - id: edge
+      label: 边缘网关
+      flavor: custom
+      openaiURL: https://edge.example.com/openai/v1/chat/completions
+      responsesURL: https://edge.example.com/openai/v1/responses
+      anthropicURL: https://edge.example.com/anthropic/v1/messages
+      apiKeyEnv: EDGE_API_KEY
+```
+
+也可以在设置页里用同样的模板添加网关，不必编辑 YAML。
+
+## 按网关控制模型清单
+
+隐藏模型、修正错误元数据、添加网关未列出的模型：
+
+```yaml
+llm-newapi:
+  models:
+    - id: glm-5.2
+      disabled: true              # 从选择器隐藏
+    - id: glm-5.2-highspeed
+      contextWindow: 1000000      # 覆盖发现值
+      protocol: openai            # 强制协议（openai/anthropic/gemini/openai-response）
+    - id: my-internal-model       # 自定义模型（网关未列出）
+      name: 我的内测模型
+      contextWindow: 200000
+```
+
+**网关模型**设置页提供同样的操作：搜索、带计数的已隐藏/自定义筛选、逐模型覆写
+编辑器（placeholder 显示发现值）、连接测试、保存/取消语义。
+
+## 配置参考
+
+`$DSH_HOME/settings.yaml` 的 `llm-newapi:` 节。扁平字段（`baseURL` /
+`apiKeyEnv` 等）构建默认 `newapi` 路由；`gateways` 数组里的每个网关支持
+大部分同名字段（`label` / `apiKeyEnv` / `flavor` / `catalogMode` /
+`endpointPriority` / …）。
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `label` | `NewAPI` | 默认网关路由的显示名 |
+| `apiKeyEnv` | `NEWAPI_API_KEY` | 凭据引用（环境变量名） |
+| `baseURL` | env `NEWAPI_BASE_URL` / `NEWAPI_API_URL` → `https://api.newapi.ai` | 网关地址（配置协议 URL 后不再使用） |
+| `flavor` | `newapi` | 网关模板：`newapi` / `litellm` / `higress` / `openai-compatible` / `custom` |
+| `openaiURL` | – | OpenAI 兼容完整端点地址（自定义模板；留空 = 不启用） |
+| `responsesURL` | – | Responses 完整端点地址（自定义模板；留空 = 不启用） |
+| `anthropicURL` | – | Anthropic messages 完整端点地址（自定义模板；留空 = 不启用） |
+| `modelsUrl` | `https://models.dev/models.json` | models.dev 数据源（`file:` URL 可离线） |
+| `useModelsDev` | `true` | 是否用 models.dev 参数增强模型 |
+| `extendedReasoningLevels` | `false` | 未知模型推理等级兜底放宽到 off~max（默认仅 off/low/medium/high） |
+| `sortModelsByRelease` | `true` | 选择器按发布日期新到旧排列（未知日期排最前） |
+| `catalogMode` | `auto` | 模型列表来源：`auto` / `v1` / `management` |
+| `catalogTtlMs` | `1800000` | 模型列表缓存时长 |
+| `includeChatOnly` | `true` | 仅把对话模型放进选择器 |
+| `excludePatterns` | image/speech/embed/… | 选择器剔除的正则列表 |
+| `endpointPriority` | `["openai-response","anthropic","openai","gemini"]` | wire 格式优先级（每模型取首个匹配） |
+| `userId` | `1` | 管理 API 的 `New-Api-User` 头 |
+| `maxTokens` | `32768` | 无 models.dev 数据时的输出上限兜底 |
+| `defaultContextWindow` | `128000` | 无 models.dev 数据时的上下文兜底 |
+| `streamIdleTimeoutMs` | `300000` | 流空闲看门狗 |
+| `retryPolicy` | 标准重试 | 与 `llm-deepseek` 同构 |
+
+## 工作原理
+
+所有 wire 格式细节都委托给
+[`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
+—— 官方 `dsh-llm-pi-ai` 适配器用的同一 SDK。每次请求：
+
+```
+harness GenerateOptions
+  → toPiContext()          lib/pi-bridge.js   harness 消息 → pi-ai Context
+  → models.streamSimple()  pi-ai SDK          按每个模型的 `api` 分发协议
+  → toStreamChunks()       lib/pi-bridge.js   pi-ai 事件 → harness chunk
+```
+
+每个发现的模型带一个 `api` 字段，由网关广告的 `supported_endpoint_types`
+映射而来，遵循 `endpointPriority`；pi-ai provider 收到的是 api *映射表*，
+所以每个模型路由到自己的协议实现。`sdkBaseURL()` 为 OpenAI 协议模型补
+`/v1`，Anthropic/Google 的基础地址保持不变。
+
+```
+dsh-gateway-provider/
+├── index.js            # 插件入口：Config 校验、provider 注册、设置/凭据接线
+├── cordis.patch.yml    # dsh.bundle 补丁（经 `dsh plugin add` 自动挂载）
+├── lib/                # adapter、pi-provider、pi-bridge、catalog、modelsdev、thinking、client
+├── test/               # 冒烟（直连网关）+ 离线单元 + 设置页渲染
+└── scripts/link.sh     # 本地检出时链接 profile 的 node_modules
+```
+
+## 从本地检出开发
+
+1. `bash scripts/link.sh` — 把本包 `node_modules` 软链到 profile 的，
+   保证 `@deepseek-ai/*` 裸导入解析到 harness 进程使用的同一份模块实例
+   （单实例 `instanceof` 安全）。
+2. 把检出注册为 profile 的 link 依赖并安装：
+
+   ```bash
+   cd "$DSH_HOME/profiles/web"
+   # package.json dependencies 追加："dsh-gateway-provider": "link:/本包绝对路径/dsh-gateway-provider"
+   # 再把 "dsh-gateway-provider" 加进同一文件的 bundles 列表
+   pnpm install
+   ```
+
+3. 重启 profile。
+
+> ⚠️ **不要**再往 profile 自己的 `cordis.patch.yml` 里插入 `id: llm-newapi`
+> ——bundle 层已挂载，重复会导致启动时报 `duplicate loader entry id`。
+
+客户端 bundle 改动刷新浏览器即生效；宿主侧改动需要重启 profile。
+
+### 测试
+
+```bash
+node test/smoke.mjs            # 直连网关：catalog / openai × 2 / 工具调用 / anthropic / gemini / custom-urls
+node test/smoke.mjs --only custom-urls
+node test/protocol-urls.mjs    # 离线：URL 派生 + 网关解析单元测试
+node test/client-render.mjs    # 离线：设置页渲染树（中/英）
+```
+
+冒烟测试凭据解析顺序：进程环境变量 → 插件目录 `.env` →
+`$NEWAPI_ENV_FILE`（另有一个作者本地遗留兜底路径）。
+
+## 安全说明
+
+- API Key 只经 `$DSH_HOME/.credentials.yaml`（0600）或环境变量解析，
+  绝不写入日志、配置或对话；凭据字段在 Web UI 中以掩码编辑。
+- 无运行时 `dependencies`；`peerDependencies` 复用 harness 已装的
+  `@deepseek-ai/*` 与 `@earendil-works/pi-ai`。提交在本地（pre-commit）
+  与 CI 双层接受 gitleaks 扫描把关。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-gateway-provider bundle patch: inserts the plugin row into the profile
+# roster. Applied as a profile bundle layer (the `dsh.bundle.patch` manifest
+# field) over dsh-base; activate with
+#   dsh plugin --profile <name> add dsh-gateway-provider
+#
+# The row is a bare plugin by package name: the host half (exports ".") runs
+# in the DSH process and registers the `newapi` provider route on ctx.llm.
+- insert:
+    - id: llm-newapi
+      name: 'dsh-gateway-provider'