dsh-openrouter-provider-advisor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhuxiaofeng
+
+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,163 @@
+# dsh-openrouter-provider-advisor
+
+同一个模型，不同 OpenRouter 供应商的价格、缓存费用、速度和稳定性可能相差很大。这个插件帮助 DeepSeek Harness 用户自动找到**更省钱、更合适的供应商**，并一键切换当前会话。
+
+插件综合量化、速度、缓存重度价格、上下文与可用率，为当前模型给出 Top 5 供应商。你不需要逐个查价格、建 preset：点击一行即可同步切换当前会话与默认模型。
+
+> **核心价值：在不更换模型的前提下，减少不必要的调用成本，并在价格、速度和可靠性之间找到更适合当前工作负载的线路。**
+
+🌏 **中文** · [English](./README_EN.md)
+
+![OpenRouter 供应商推荐与实时切换](./docs/images/provider-panel.png)
+
+## 功能
+
+- **帮助省钱**：比较同一模型在不同供应商的输入、输出和缓存读取价格，避免只看单一标价。
+- **找到更合适的供应商**：价格不是唯一标准；速度、量化、上下文和可靠性一起参与排序。
+- **当前模型推荐**：自动对齐 DSH 模型与 OpenRouter `author/slug`，不推荐无关模型。
+- **四种策略**：综合最佳、价格优先、速度优先、上下文优先。
+- **Code Agent 价格模型**：默认按输入 2%、输出 8%、缓存读取 90% 计算价格得分。
+- **可靠性保护**：过滤不可用 endpoint，并按 OpenRouter 近 30 分钟 uptime 温和降权。
+- **点击实时切换**：创建或更新 OpenRouter preset，切换当前会话并保存默认模型。
+- **完整 DSH 模型目录**：复用 DSH 已有配置，不写死模型列表。
+- **联动权重 UI**：滑块、百分比输入和锁定按钮协同调整，总和始终为 100%。
+- **复用 DSH 凭据**：读取 OpenRouter provider 的 `apiKeyEnv`，API Key 不进入浏览器。
+- **Agent 工具**：只读推荐免审批；Agent 发起切换时必须经过 DSH 原生审批。
+- **中英文界面**：跟随 DSH 当前语言实时切换。
+
+## 界面
+
+| 供应商推荐与切换 | 权重与凭据状态 |
+| --- | --- |
+| 同一模型的供应商价格与性能放在一张表里，快速找到更省钱且适合当前任务的线路；点击一行立即切换。 | 联动滑块配置综合权重与缓存重度价格模型；顶部只展示 credential reference，不展示密钥。 |
+| <img src="./docs/images/provider-panel.png" alt="供应商推荐面板" width="100%"> | <img src="./docs/images/settings-weights.png" alt="OpenRouter 权重设置" width="100%"> |
+
+> 可用率来自 OpenRouter 近 30 分钟统计。刚发生的故障、限流和恢复可能存在检测延迟；它不是主动健康探测。
+
+## 安装
+
+前置条件：DSH `0.1.1-rc.2` 或更新版本、Node.js `^22.19.0` 或 `>=24`，并已在 **DSH 设置 → 模型** 中配置 OpenRouter provider/API Key。
+
+```bash
+dsh plugin --profile web add dsh-openrouter-provider-advisor@latest
+```
+
+安装后硬刷新浏览器：macOS 使用 `Cmd + Shift + R`，Windows/Linux 使用 `Ctrl + Shift + R`。若 Host 部分已在运行，重启一次 `dsh web`。
+
+更新与卸载：
+
+```bash
+dsh plugin --profile web add dsh-openrouter-provider-advisor@latest
+dsh plugin --profile web remove dsh-openrouter-provider-advisor
+```
+
+## 使用
+
+1. 在 DSH 中打开普通会话。
+2. 点击左侧栏底部的 **OpenRouter 供应商**。
+3. 选择要分析的 DSH 模型和推荐策略。
+4. 查看分数与可用率，点击供应商完成切换。
+5. 下一次请求将使用新的 `@preset/<model>-<provider>`。
+
+切换按顺序执行：
+
+```text
+创建/更新 OpenRouter preset
+        ↓
+写入 DSH OpenRouter 模型条目
+        ↓
+session.selectModel 切换当前会话
+        ↓
+保存为 DSH 默认模型
+```
+
+已经组装完成的请求不会被中途改写；切换从下一次请求开始生效。
+
+## 推荐策略
+
+综合最佳默认使用：量化 30%、速度 30%、价格 30%、上下文 10%。设置页中的“综合最佳评分权重”只影响综合最佳；价格、速度和上下文策略使用内置权重。
+
+如果目标是优先降低费用，可以直接选择“价格优先”；如果希望控制成本但不牺牲太多速度和稳定性，使用默认“综合最佳”。推荐结果是决策辅助，不保证每次请求都落在绝对最低价线路。
+
+默认价格模型针对 Code Agent 的高缓存流量：
+
+```text
+价格成本 = 输入价 × 2% + 输出价 × 8% + 缓存读取价 × 90%
+```
+
+### 可用率安全带
+
+`status != 0` 的 endpoint 直接排除。其余 endpoint 使用温和的通用降权：
+
+| OpenRouter 近 30 分钟 uptime | 保留分数 |
+| --- | ---: |
+| ≥99.5% | 100% |
+| 99–99.5% | 85% |
+| 97–99% | 60% |
+| 90–97% | 30% |
+| <90% | 5% |
+| 无数据 | 70% |
+
+用户设置可以让惩罚更严格，但不能绕过安全带。
+
+## Agent 工具
+
+- `recommend_openrouter_providers`：读取当前模型的推荐列表。
+- `switch_openrouter_provider`：切换供应商；属于写操作，始终请求 DSH 用户审批。
+
+人类在面板里点击供应商时视为明确操作，会直接执行切换。
+
+## 凭据与安全
+
+- 优先复用当前 DSH OpenRouter provider 的 `apiKeyEnv`，兼容回退 `OPENROUTER_API_KEY` reference。
+- API Key 只在 Host 端解析，不进入 Client bundle、HTTP 响应或插件设置。
+- Host 写接口只接受同源 JSON，请求体上限 64KB。
+- OpenRouter 查询超时 15 秒，preset 写入超时 30 秒。
+- Controller 不持久保存密钥；执行写操作前重新解析凭据。
+- 插件不读取或传输会话正文、历史消息和用户文件。
+
+## 数据来源与限制
+
+插件只调用 OpenRouter 官方 API：
+
+```text
+GET  /api/v1/models
+GET  /api/v1/models/{author}/{slug}/endpoints
+POST /api/v1/presets/{slug}/chat/completions
+```
+
+不抓取产品页 HTML。OpenRouter 统计可能滞后于即时 `429`、超时和恢复；点击供应商会创建或更新真实 preset；切换上游可能使 KV cache 失效。
+
+## 常见问题
+
+| 现象 | 处理方式 |
+| --- | --- |
+| 找不到 `web` profile | 先运行一次 `dsh web`，再安装插件。 |
+| 插件已安装但界面没变化 | 硬刷新浏览器；Host 有改动时重启 DSH。 |
+| 未检测到 OpenRouter 凭据 | 在 DSH 设置 → 模型中配置 OpenRouter provider/API Key。 |
+| 某供应商分数高但请求 429 | uptime 有统计延迟，临时切换到其他供应商。 |
+| `minimum release age` | 等待 profile 安全策略允许该版本后重试。 |
+| DSH 拒绝 `.env` 中的 `DEEPSEEK_BASE_URL` | 从项目 `.env` 移除，并在启动 DSH 的终端中 `export`。 |
+
+## 本地源码开发
+
+```bash
+git clone https://github.com/xuanfengtechx/dsh-openrouter-provider-advisor.git
+cd dsh-openrouter-provider-advisor
+npm install
+npm run verify
+dsh plugin --profile web add -w "$PWD"
+```
+
+发布预演：
+
+```bash
+npm pack --dry-run
+npm publish --dry-run --access public
+```
+
+自动测试不会点击真实供应商，因为切换会在用户 OpenRouter 账号中创建或更新 preset。
+
+## License
+
+[MIT](./LICENSE)

package/README_EN.md

@@ -0,0 +1,116 @@
+# dsh-openrouter-provider-advisor
+
+The same model can have very different prices, cache-read costs, throughput, and reliability across OpenRouter providers. This plugin helps DeepSeek Harness users find a **more cost-efficient, better-fit provider** and switch in one click.
+
+It combines quantization, speed, cache-heavy pricing, context, and uptime into a Top 5 for the current model. You no longer need to compare providers or create presets by hand: clicking a row updates both the active session and default model.
+
+> **Core value: reduce avoidable inference spend without changing models, while finding a practical balance between cost, speed, and reliability.**
+
+[中文](./README.md) · **English**
+
+![OpenRouter provider ranking](./docs/images/provider-panel.png)
+
+## Highlights
+
+- Compare input, output, and cache-read prices to help reduce spend.
+- Find the best fit rather than blindly choosing the cheapest endpoint.
+- Model-aware ranking without a hard-coded model catalog.
+- Best overall, price-first, speed-first, and context-first strategies.
+- Code Agent price blend: 2% input, 8% output, 90% cache-read by default.
+- Gentle 30-minute uptime safety bands and hard filtering for unavailable endpoints.
+- One-click switching for the active session and deployment default.
+- Linked percentage sliders with locks; each group always totals 100%.
+- Reuses DSH credential references; API keys never reach the browser.
+- Read-only recommendation tool and approval-gated agent switching tool.
+- Live Chinese/English UI following the DSH locale.
+
+## Screenshots
+
+| Provider ranking | Settings and credential status |
+| --- | --- |
+| Compare provider cost and performance for the same model, then click a row to switch. | Linked scoring weights and a cache-heavy global price model. |
+| <img src="./docs/images/provider-panel.png" alt="Provider advisor panel" width="100%"> | <img src="./docs/images/settings-weights.png" alt="Provider advisor settings" width="100%"> |
+
+> Uptime is OpenRouter's trailing 30-minute statistic. Fresh failures, rate limits, and recoveries may be detected with a delay; this is not an active health probe.
+
+## Install
+
+Requirements: DSH `0.1.1-rc.2` or newer, Node.js `^22.19.0` or `>=24`, and an OpenRouter provider/API key configured in **DSH Settings → Models**.
+
+```bash
+dsh plugin --profile web add dsh-openrouter-provider-advisor@latest
+```
+
+Hard-refresh (`Cmd/Ctrl + Shift + R`). Restart `dsh web` if its Host half was already running.
+
+```bash
+# Update
+dsh plugin --profile web add dsh-openrouter-provider-advisor@latest
+
+# Remove
+dsh plugin --profile web remove dsh-openrouter-provider-advisor
+```
+
+## Use
+
+Open a normal DSH session, click **OpenRouter Providers** in the left footer, pick a model and strategy, then click a provider. The next request uses `@preset/<model>-<provider>`.
+
+```text
+create/update OpenRouter preset
+        ↓
+upsert DSH OpenRouter model entry
+        ↓
+session.selectModel
+        ↓
+save the DSH default model
+```
+
+An already assembled request is not rewritten mid-flight.
+
+## Ranking
+
+Best overall defaults to 30% quantization, 30% speed, 30% price, and 10% context. Cache-heavy cost is:
+
+```text
+cost = input price × 2% + output price × 8% + cache-read price × 90%
+```
+
+| OpenRouter trailing 30-minute uptime | Score retained |
+| --- | ---: |
+| ≥99.5% | 100% |
+| 99–99.5% | 85% |
+| 97–99% | 60% |
+| 90–97% | 30% |
+| <90% | 5% |
+| Missing | 70% |
+
+Endpoints with nonzero status are excluded. User settings may make penalties stricter, never looser.
+
+## Credentials and security
+
+- Reuses the selected DSH OpenRouter profile's `apiKeyEnv`, with `OPENROUTER_API_KEY` as a compatibility fallback reference.
+- Credential values stay Host-only and never appear in client code, HTTP responses, or settings.
+- Mutation routes accept same-origin JSON only and cap bodies at 64KB.
+- Reads time out after 15 seconds; preset writes after 30 seconds.
+- Agent-initiated switching always uses native DSH approval.
+- The plugin does not read conversation messages, history, or workspace files.
+
+## Data sources and limits
+
+Only official OpenRouter APIs are used: `/models`, `/models/{id}/endpoints`, and `/presets/{slug}/chat/completions`. The plugin does not scrape product pages. OpenRouter statistics may lag fresh upstream failures and recoveries.
+
+## Development
+
+```bash
+git clone https://github.com/xuanfengtechx/dsh-openrouter-provider-advisor.git
+cd dsh-openrouter-provider-advisor
+npm install
+npm run verify
+npm pack --dry-run
+```
+
+Automated tests stop before a real provider click because switching creates or versions an actual OpenRouter preset.
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: openrouter-providers
+      name: dsh-openrouter-provider-advisor
+      config: {}

package/dsh.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "dsh-external/dsh-openrouter-provider-advisor",
+  "version": "0.1.0",
+  "main": "./lib/index.js",
+  "description": "OpenRouter 供应商推荐与安全切换：按质量、速度、缓存价格、上下文和可用率排序",
+  "engines": {
+    "dsh": ">=0.1.1-rc.2"
+  },
+  "contributes": {
+    "tools": ["recommend_openrouter_providers", "switch_openrouter_provider"],
+    "skills": []
+  },
+  "client": {
+    "main": "./lib/client.js"
+  }
+}