dsh-msi-icons

Readme

# dsh-msi-icons

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform: DeepSeek Harness](https://img.shields.io/badge/Platform-DeepSeek%20Harness-blue)](https://github.com/deepseek-ai)

DeepSeek Harness（DSH）Web GUI 的**模型选择器美化插件**：给每个模型行戴上厂商官方图标，按「置顶 → 原生 → 插件 → 视觉」四区平铺重排，爱心点击置顶；附带一套**置顶主力超时路由**——主力模型超时/报错时自动切换下一个置顶模型重试。

> A DeepSeek Harness plugin that beautifies the model selector with official vendor icons, a pinned-first four-zone layout, and automatic failover between pinned models on first-token timeout.

## 功能

### 🎨 厂商官方图标

- **内置识别**：智谱（官方 Z 标）/ 千问（官方符号）/ DeepSeek（官方鲸鱼）/ 超算聚合（红算牌）/ 小米 MiMo（渐变艺术字）/ 免费模型（绿徽章）
- **预留图标库**：OpenAI / Claude / Gemini / Meta / Mistral / Perplexity / Ollama / HuggingFace / NVIDIA / OpenRouter / Groq / 硅基流动 / MiniMax / 文心 / Kimi / Anthropic 共 16 家开箱即用
- **配置化厂商表**：接入全新厂商只需放一个 SVG + 一行 JSON，无需改代码、无需重启

### 📌 平铺四区布局（不渲染组标题，纯按图标 + 彩色后缀区分）

```
📌 置顶区   ♡ 点击置顶，localStorage 持久 + 同步 Host（超时路由的降级链）
──────────
原生区      普通模型排最上、保持原顺序，免费模型垫底（保留免费徽章）
插件区      (modlens vision) 模型合并一区，行内紫色 -mv 后缀
视觉区      「+ 自动识图」/ Vision Chain 模型合并，行内黄色 -视觉 后缀
```

- 同名去重（置顶的不去重）；置顶 key 用装饰前原始文本计算，模型改名/搬家不断链

### ⚡ 置顶主力超时路由

- 置顶模型**首 token 45 秒超时**或未产出内容即报错 → 自动切换下一个置顶模型重试
- 全部置顶不可用 → 抛错停止；用户主动中止不路由；视觉链模型不路由
- 降级链持久化在 Host 侧（`pins.json`），重启不丢

## 安装

```bash
dsh plugin --profile web add github:hun1315/dsh-msi-icons
```

然后重启 DSH 使 Host 半生效（client 半刷新页面即见）。装完打开模型选择器即可看到四区布局与图标。

> 无硬依赖：不依赖 modlens / vision-router 或任何其他插件，缺谁就少显示对应分区，其余一切照常。

## 配置：接入新厂商（三步）

1. 把厂商官方 SVG 放到 `~/.dsh/msi-icons/icons/`（若是预留库已有的 16 家之一则跳过）
2. 在 `~/.dsh/msi-icons/vendors.json` 的 `vendors` 数组加一行（模板见 [vendors.example.json](vendors.example.json)）：

   ```json
   { "match": "硅基流动|siliconflow", "rank": 6, "icon": "siliconflow.svg" }
   ```

   - `match`：正则关键词，对组名/模型名匹配（不区分大小写）
   - `rank`：排序权重，数字越小越靠前（可省略，默认 8）
3. 刷新页面即生效（`vendors.json` 是实时读取）

**加新模型的三种场景**：老厂商新模型 = 零成本（图标/分类/路由全自动跟上）；换老厂商图标 = 改内置表；全新厂商 = 上面三步。

## HTTP 接口

| 路由 | 方法 | 说明 |
|---|---|---|
| `/msi-icons/pins` | POST | 同步置顶降级链：`{"pins":[{"title":"组名","model":"模型id"}]}` |
| `/msi-icons/state` | GET | 调试：当前置顶 + 超时阈值 |
| `/msi-icons/vendors` | GET | 当前厂商配置表（live 读取） |
| `/msi-icons/icon?file=x.svg` | GET | 图标服务：`~/.dsh/msi-icons/icons/` → 插件 `assets/icons/` 两级查找，文件名白名单防穿越 |

## 数据文件

| 路径 | 用途 |
|---|---|
| `~/.dsh/msi-icons/pins.json` | 置顶降级链（重启不丢，浏览器会自动同步） |
| `~/.dsh/msi-icons/vendors.json` | 自定义厂商表（可选，实时读取） |
| `~/.dsh/msi-icons/icons/` | 自定义图标目录（优先于内置库） |

## 排障与维护

完整维护指南（架构、接口契约、类名哈希兼容、超时路由机制、排障手册）见 [skills/msi-icons/SKILL.md](skills/msi-icons/SKILL.md)。

常见问题速查：

- **图标全消失 / 前端错乱** → F12 看页面有无 "Failed to load plugins"（DSH 插件引导链崩，全体回退，先定位是哪个插件报错）
- **图标部分消失** → DSH 升级换了 CSS-module 类名哈希，更新 `lib/client.js` 的类名映射
- **超时路由不生效** → `GET /msi-icons/state` 看 `pinned` 是否为空；为空 = 浏览器未同步（刷新页面）

## 兼容性说明

- 插件通过 DSH 构建产物的 CSS-module 类名定位选择器 DOM，**DSH 大版本升级可能使类名哈希变化**——届时插件静默失效（有护栏，不报错不干扰），更新类名映射即可修复
- 本插件不修改任何 DSH 官方文件，全部效果通过运行时装饰实现，卸载即恢复原样

## License

[MIT](LICENSE)