@dsh-external/dsh-openrouter-provider-badge

Readme

# dsh-openrouter-provider-badge

在 DeepSeek Harness (DSH) 的会话统计行上方显示 **OpenRouter 实际供应商**（如 StreamLake / DeepInfra）。

```
⬆ 实际: StreamLake   ·   通道: openrouter/deepseek-v4-flash-0731
17:08 · 用时 4分25秒 · 首token 23秒 · 78 tok/s
```

> 纯客户端插件 + 两个 DSH 补丁。安装分三步：**装插件 → 打补丁 → 加配置头**，缺一步都不会显示实际供应商。

---

## 它解决什么

OpenRouter 是聚合平台，同一个模型（如 `deepseek/deepseek-v4-flash-0731`）会由多家供应商托管，DSH 请求时 OpenRouter 自动选一家（如 StreamLake、DeepInfra、Novita…）。DSH 原生只显示「走的是 openrouter 通道 + 模型名」，**不显示实际是哪家**。

本插件让 DSH 请求 OpenRouter 时带上 `X-OpenRouter-Metadata: enabled` 头，把响应里的 `openrouter_metadata`（实际供应商）写进会话消息，并在每条消息的统计行上方渲染出来。

## 与相关插件的区别

DSH 生态里已有几个"显示 provider 信息"的插件，容易混淆，这里明确区分：

| 插件 | 显示什么 | 与本插件的区别 |
|---|---|---|
| [dsh-chat-tweaks](https://github.com/haiyoucuv/dsh-chat-tweaks)（前身 [dsh-model-provider-label](https://github.com/haiyoucuv/dsh-model-provider-label)，已归档） | 模型选择器里显示**配置的 provider 显示名**（如 `DeepSeek · DeepSeek V4 Flash`） | 显示的是配置文件里的静态 provider 名；本插件显示的是 OpenRouter 为本次请求**动态选中的实际上游供应商**（StreamLake / DeepInfra / Novita…） |
| [dsh-plugin-model-provider-readout](https://github.com/jxdang/dsh-plugin-model-provider-readout) | 模型按钮左侧显示 `DeepSeek \|` 标签 | 同上，显示配置的 provider 名；不消费 `openrouter_metadata`，看不到实际服务商 |
| [landtml/openrouter-dsh](https://github.com/landtml/openrouter-dsh) | 钉选 OpenRouter 供应商、关闭 reasoning 的控制工具 | 定位是**控制路由**（pin 供应商）；本插件是**观测展示**（显示实际服务商）。两者都补丁支持 `openRouterRouting`，功能互补而非重复 |

> 一句话：**别的插件告诉你"配置的是谁"，本插件告诉你"这次请求实际是谁在服务"。**

## 安装

### 1. 安装插件

```bash
dsh plugin --profile web add /path/to/dsh-openrouter-provider-badge
```

（或使用你现有的插件管理器/注入器。）

### 2. 打补丁（必须）

DSH 默认配置层不接受 OpenRouter 路由参数，且会丢弃响应里的供应商元数据。运行脚本自动打两个补丁：

```bash
bash patch.sh
# 或指定 DSH 安装目录:
# bash patch.sh /usr/local/lib/node_modules/@deepseek-ai/dsh
```

补丁内容（适配 DSH **0.1.1-rc.2+**）：
| 文件 | 改动 |
|---|---|
| `@earendil-works/pi-ai/dist/api/openai-completions.js` | 流式 chunk 解析 `openrouter_metadata` → `output.openrouterMetadata` |
| `@deepseek-ai/dsh-llm-pi-ai/lib/index.js` | ① compat gate 开放 `openRouterRouting`（`withhold`→`offer`）② schema 增加该字段 ③ `toPiReplayState` 透传 openrouterMetadata ④ replay 还原时带回 |

> ⚠️ **升级 DSH 会覆盖补丁**，升级后重跑 `bash patch.sh` 即可。
> ⚠️ patch.sh 会自动检测 `dsh-llm-pi-ai` 版本：低于 0.1.1-rc.2 会拒绝并提示先升级。

### 3. 配置请求头

编辑 `~/.dsh/settings.yaml`（Windows: `C:\Users\<你>\.dsh\settings.yaml`），给 openrouter provider 加：

```yaml
llm-pi-ai:
  providers:
    openrouter:
      apiKeyEnv: OPENROUTER_API_KEY
      headers:
        X-OpenRouter-Metadata: enabled
      models:
        - id: deepseek/deepseek-v4-flash-0731
          name: "DeepSeek: DeepSeek V4 Flash 0731"
          contextWindow: 1048576
          maxTokens: 384000
          reasoningEfforts:
            off: null
            low: low
            high: high
            max: max
          compat:
            openRouterRouting:
              quantizations: [bf16, fp8]
              sort: price
              allow_fallbacks: true
```

`compat.openRouterRouting` 是**可选项**（配合补丁生效）：
- `quantizations: [bf16, fp8]` —— 排除 fp4 量化供应商
- `sort: price` —— 在允许的供应商里选最便宜
- `allow_fallbacks: true` —— 首选失败时回退

### 4. 重启 DSH

重启 DSH 服务后刷新网页，发一轮 OpenRouter 模型对话即可看到供应商徽标。

## 效果与降级

- **有元数据** → 显示 `⬆ 实际: <供应商>` + 通道/模型名
- **无元数据**（没打补丁 / 没加 header / Key 限额被拒） → 降级只显示 `通道: openrouter/<模型>`
- 插件静默失败，不影响会话本身

## 目录结构

```
dsh-openrouter-provider-badge/
├── lib/
│   ├── index.js     # 服务端入口（空骨架）
│   └── client.js    # 客户端插件（turnTail slot）
├── patch/
│   ├── pi-ai-openai-completions.patch
│   └── dsh-llm-pi-ai-index.patch
├── patch.sh         # 一键打补丁（含版本检测）
├── src/client/index.ts  # 客户端源码
├── tests/test-patch.sh  # patch.sh 行为测试（red/green）
└── package.json
```

## 兼容性

- DSH **0.1.1-rc.2+**（patch.sh 会检测版本，旧版 0.1.0-rc.x 会拒绝并提示升级）
- 仅 OpenRouter 通道
- 服务端补丁对 WSL / Windows 安装均适用
- 补丁针对 0.1.1-rc.2 的代码结构编写（compat gate 表驱动机制）；未来 DSH 版本若改动相关代码，重跑 patch.sh 时若失败请反馈更新补丁

## License

MIT