dsh-client-ui-model-clock

Readme

# dsh-client-ui-model-clock · 模型优惠时钟

> DeepSeek Harness 插件 —— 把「各家大模型的时间维度优惠」汇总成一张**以时间轴为主视图**的决策面板。
> 实时回答一个问题：**现在这个点，我该调哪家最省？**

---

## 它解决什么问题

同一份代码、同一个模型，在不同时刻调用，成本可以相差 **2 到 5 倍**：

| 平台 | 机制 | 窗口（北京时间） |
|---|---|---|
| DeepSeek 官方 | 峰谷定价，闲时半价 | 高峰 09:00–12:00 / 14:00–18:00，其余半价 |
| 智谱 Coding Plan | 非高峰按基础积分 50% 抵扣 | 高峰仅周一至周五 14:00–18:00 |
| 百度千帆 | 全时段梯度折扣 | 白天 2 折 / 夜间低至 0.5 折 / 周末 1 折 |
| 阿里云百炼 | Token Plan 夜间五折 | 22:00–08:00 |
| 硅基流动 | 分时段计价 | 02:00–08:00 闲时 |
| 火山方舟 | Auto 模式夜间路由至更强模型 | 00:00–08:00 |

**但没有人把这张表放在你面前。** 这些信息散落在 10 家以上平台的官方文档站，格式各异，且大量优惠带渠道门槛（仅指定工具可用、仅套餐内、仅积分抵扣）。要做出「现在用谁」的判断，需要人工巡检十余个页面；而这些活动**以周为单位上下线**——过期一天，判断就是错的。

---

## 三个设计立场

### 1. 时钟优先，日历为辅

国内主流优惠中**超过一半是「每日循环的时段折扣」**（夜间、峰谷），不是「某个日期」。用月历格子无法表达「22:00 至次日 08:00」，只有 24 小时时间轴能表达。因此主视图是**成本热力带**，日历只用来承载有限时起止日的活动。

### 2. 只横比可横比的对象

**按量计费**的模型可以直接比价；**套餐 / 积分 / 倍率制**平台（百炼、千帆、腾讯、火山）需要按不透明的系数二次折算。把它们混在同一张价格榜上，给出的是**错误对比**。

所以「此刻推荐」榜只收按量计费模型；套餐类平台只展示**折扣深度**，不展示绝对单价。

### 3. 每条优惠必须可溯源，过期信息必须可见

- 每条记录强制携带**官方来源链接**与**人工核实时间**
- 「已核实」与「待官方核实」在界面上**明确区分**，不含糊
- **已结束的活动不删除**——「昨天还有五折」本身就是决策信息
- 超过 14 天未复核的条目自动降级提示

---

## 安装

```bash
dsh plugin --profile web add zhanghao3693/dsh-client-ui-model-clock
```

或从源码安装：

```bash
git clone https://github.com/zhanghao3693/dsh-client-ui-model-clock
dsh plugin --profile web add ./dsh-client-ui-model-clock
```

> ⚠️ `--profile web` 是 dsh CLI 的**必需参数**，省略会直接报
> `required option '--profile <name>' not specified`。
> 任何来源给出的 `dsh plugin add <目标>`（无论仓库名还是本地路径）都不可用。
>
> 该命令会把本插件并入 profile 的 layer 栈（依赖 `package.json` 的 `dsh.bundle.patch`
> 指向 `cordis.patch.yml`；缺了它插件只会被当成普通依赖装进去，**进程不会加载它**，
> 表现为「装成功但没反应」）。装完若未生效，重启 dsh 即可。

安装后在对话视图的标签页中选择「🕐 模型优惠时钟」即可。

## 你会看到什么

| 区块 | 作用 |
|---|---|
| **此刻推荐** | 叠加当前生效优惠后的实际单价排序，一眼看出现在该用谁 |
| **全天成本热力带** | 24 小时时间轴，颜色表示各平台折扣深度，竖线为当前时刻 |
| **「等一等更省」** | 可执行的调度建议：把可延迟的批处理任务挪到低成本窗口，最多能省多少 |
| **注册专属福利（广告）** | 已决定长期用某家平台时，从专区入口注册可另得新用户福利。**含推广链接，可一键关闭**（见下节） |
| **限时活动** | 有明确起止日的活动及剩余天数，已结束的保留标记 |
| **资源包特惠** | 一次性买断的资源包（与「几点用」无关）：按官方专区分组，含规格、现价/原价、折率、限购次数与有效期 |
| **数据溯源** | 可信度统计、核实时间，可展开查看每条优惠的来源链接与状态 |

**北京时间处理**：时段判断强制按 `Asia/Shanghai` 计算，不依赖本机时区——否则开发者不在 UTC+8 时会得到完全错误的结论。

---

## 注册专属福利（广告专区）与中立性承诺

这个插件里有一段**商业内容**，必须说清楚。

### 它是什么

「注册专属福利」专区展示作者持有推广关系的平台注册入口。通过这些链接注册，**作者可获得佣金或奖励**，你则额外拿到该平台的新用户福利——两边都不吃亏，但作者确实有经济动机，所以它被明确标注为广告。

### 中立性承诺：推广关系不影响排序

这是本插件最不可妥协的一条约束：

> **返利数据在任何时刻都不能影响模型推荐结果。**

而且这不是口头承诺，是**可复现验证**的架构约束：

- `recommend()` / `priceAt()` / `windowMult()` / `schedulingAdvice()` 的函数签名里**根本没有返利参数**——它们物理上读不到推广数据；
- `verify-neutrality.mjs` 会穷举全部 7×24 = 168 个时刻，先记录基准排序，再把推广数据**投毒式替换**（只留返利平台、塞入虚假高返利条目），然后断言两次排序**逐条完全相同**；
- 该脚本还会静态检查上述核心函数体内不含任何返利相关标识符。

另有一个天然保障：**DeepSeek 官方没有推广计划**，而它恰是最常被推荐的平台（闲时半价最便宜）。最省钱的那个不带任何商业动机。

### 合规做法

| 要求 | 本插件的做法 |
|---|---|
| 显著标明"广告" | 专区标题带高对比「广告」标识（法定字样是"广告"，"推广/返利/佣金"均不可替代） |
| 设置专门区域 | 采用独立区块 + 打包标注，符合《互联网广告可识别性执法指南》第七条 |
| 明示推广关系 | 底部披露语句 + 广告发布者身份 |
| 保障用户选择权 | 提供「关闭广告」按钮，选择持久化到本地 |
| 不强制建立推广关系 | 跳转使用平台原始链接，**不注入、不改写任何 URL 参数**（阿里云云大使规范 3.1.2、腾讯云 CPS 第 3 项均禁止以插件方式强制建立关系） |
| 不夸大优惠 | 折扣数据独立于推广专区，每条单独标注核实状态 |

### 推广数据的两份与同步

推广链接配置有两份：权威源 `config/affiliate.json`（host 侧读取并对客户端提供），与 `lib/client.js` 里的离线兜底副本。这是刻意的——客户端要能在离线或 host 未注册路由时照常工作。代价是可能漂移，所以 `verify-affiliate-sync.mjs` 会把漂移变成**可检测的失败**：逐条逐字段比对，并断言披露文案含法定字样「广告」、跳转无参数注入、存在可关闭入口。

---

## 与模型调度的配合（dsh-llm-router）

若同时安装了 `dsh-llm-router`，它会在**选中某个 backend 之后**附加一条返利提示：

```
llm-router: [sess-xxx] 提示：智谱 BigModel 是作者有推广关系的平台（2000万Tokens）。仅为展示提示，未参与本次选择。
```

该提示通过 `/api/llm-router/routes` 的 `affiliate` 字段透出，供界面展示。

**它不影响模型选择，而且是结构上的不可能，不是靠自觉：**

- 查询点在 `decide()` 与 fallback 循环**定论之后**（`adopted = true` 之后），时序上参与不了选择
- `decide()` / `estimateInputChars()` / `requestHasImage()` 等选择逻辑的函数体内**无任何返利标识符**
- `affiliate` 字段不含 `weight`/`score`/`priority` 之类排序语义

router 侧用的是**内联查表**（不调本插件的 HTTP 路由），因为它也要能在 `tui`/`headless` profile 下工作——那里没有 `webServer`。代价是可能与 `config/affiliate.json` 漂移，因此有校验脚本强制两边一致：

```bash
node verify-router-hint-sync.mjs          # 44 项：一致性 + 中立性 + 时序 + 端到端集成
DSH_ROUTER_PATH=/path/to/dsh-llm-router node verify-router-hint-sync.mjs
```

**改 `config/affiliate.json` 的 `routerProviderIds` 后，必须同步改 router 的 `AFFILIATE_HINTS` 并重跑该脚本**，否则 router 里会残留过时提示。

---

## 数据说明（请务必阅读）

- 插件**内置一份人工核实的数据集**，离线可用，随插件版本更新。
- 数据集包含 **11 家平台、21 条优惠记录**，其中一部分已从**官方一手来源**核实（如 DeepSeek 官方定价页正文、智谱官方文档 `.md`、国家超算活动页），另一部分来自二手汇总、**尚未取得官方一手来源**，在界面上标注为「待官方核实」。
- **厂商活动以周为单位变动，请以官方页面为准。** 界面上每条记录都可点击跳转到官方来源。
- 价格单位为「元 / 百万 token（输出）」。

### 为什么不自动抓取

调研发现 11 家平台中 10 家存在可程序化入口（智谱/Kimi/MiniMax 提供逐页 `.md` 纯文本、火山提供官方文档 JSON 接口、硅基流动定价页 SSR 内嵌结构化字段）。技术可行，但**准确性与可维护性优先于覆盖率**：活动起止日往往只在公告正文里、而不在定价页，自动抓取极易把「已撤入口但仍返回 200 的过期活动页」当成有效信息。

当前选择：**人工核实 + 显式溯源 + 过期自动降级**。采集管道在覆盖率扩张到 30+ 平台后再评估。

---

## 准确性已知边界

诚实标注，不做过度承诺：

1. **DeepSeek「周末全天按低谷价」** 仅见权威媒体报道，官方定价页正文未载 —— 界面标为「待官方核实」。
2. **套餐/积分类平台**只展示折扣深度，不展示折算后单价（折算口径不透明）。
3. 部分平台存在**阶梯计价**（按输入长度分档），本插件按单一标价处理，长上下文任务的真实成本可能更高。
4. **火山 Auto 夜间路由**是「价格不变、模型更强」的隐性优惠，不体现在单价表中，单独用紫色标识。

若发现数据错误，欢迎提 Issue —— 错误的价格信息比没有信息更糟。

---

## 包结构（双入口，勿改动）

dsh 在**服务端** boot profile 时会 import 每个 bundle 的 `main` 入口来组装 plugin tree。**如果 `main` 指向浏览器侧代码，服务端会 `ReferenceError: window is not defined` 并导致整个 dsh 服务无法启动。**

因此本包严格分离两个入口：

| 文件 | 角色 | 约束 |
|---|---|---|
| `lib/index.js` | **host 入口**（`main`） | 服务端安全，**代码中不得出现任何 `window.` / `document.` 引用** |
| `lib/client.js` | **client 入口**（`exports["./client"]`） | 顶层调用 `window.__ModuleLoader__.load(...)`，由 dsh 依 `dsh.client.platform = "web"` 在浏览器中单独拾取 |

`cordis.patch.yml` 的 `insert.id` 必须与 `lib/index.js` 的 `export const name` 一致；`name` 填 npm 包名。

## 兼容性

- Node.js ≥ 18（推荐 ≥ 22.19）
- 依赖 `@deepseek-ai/dsh`（peer）
- 无构建步骤，两个入口均为可直接加载的产物

## 开发与验证

```bash
# ① 加载 / 协议 / 引擎 / 渲染 四层验证（93 项）
node verify-plugin.mjs

# ② 服务端安全性 + 双入口清单结构（15 项）
node verify-hostsafety.mjs

# ③ ★ 中立性：返利不得影响排序（12 项，含投毒式穷举验证）
node verify-neutrality.mjs

# ④ 推广配置同步与合规底线（14 项）
node verify-affiliate-sync.mjs

# ⑤ host 路由行为（45 项，含 DeepSeek 无返利的关键断言）
node verify-host-routes.mjs
```

共 **179 项断言**。验证覆盖：`__ModuleLoader__` 加载与协议导出、**服务端 import 安全性（含反证：client 入口当 main 用会 `ReferenceError`）**、时间窗匹配（含跨天与各家不同高峰口径）、折扣换算、推荐排序、调度建议、活动状态机、可信度统计、Cordis 槽位注册、真实 React 服务端渲染内容断言、**返利投毒下的排序不变性**、以及 host 侧 HTTP 路由的完整行为。

### host 侧接口（供 dsh 模型调度侧可选接入）

| 端点 | 用途 |
|---|---|
| `GET /api/model-clock/affiliate` | 推广条目（客户端取权威源） |
| `GET /api/model-clock/affiliate/resolve?provider=<id>` | 查询某 provider 是否有推广关系 |
| `POST /api/model-clock/affiliate/click` | 点击归因（进程内计数） |
| `GET /api/model-clock/affiliate/stats` | 归因统计 |

`resolve` 的返回**只描述商业关系，不含任何可用作排序的权重**。任何消费方只允许在**已选定 backend 之后**用它做展示提示，不得据此选择模型。

⚠️ **但 `dsh-llm-router` 实际并不调用这些接口** —— 它用的是内联查表，理由见上一节：它也要能在没有 `webServer` 的 `tui`/`headless` profile 下工作，而查表没有失败模式。这几个接口主要服务于本插件自己的浏览器侧客户端（取权威配置源）与归因。

## License

MIT