前言¶
如果要把任务安排在谷时跑、峰时到来前收尾，就得随时清楚现在是峰时还是谷时、下一次切换在几点。已有的做法是自己记一份时段表、靠手动核对，麻烦也容易忘；想确认 DeepSeek API 还剩多少余额，同样要放下手头的事去查。
dsh-tool-tariff 是一个 DSH（DeepSeek Harness）插件，把这几件事收进会话：模型可以直接回答时段问题，峰时来临前自动提醒，Web GUI 顶部栏还常驻一块实时状态徽标。DSH 的理念是「一切皆插件」，这类能力适合以插件形式挂载。下面按功能、安装、配置、用法、注意事项的顺序介绍。
这是什么¶
dsh-tool-tariff 由 omdsh-dev 维护，MIT 许可证，当前版本 0.0.2，npm 包名 @deepseek-ai/dsh-tool-tariff。一句话定位：峰谷电价时段查询 + DeepSeek API 余额查询 + 峰时切换提醒 + 顶部栏状态徽标。
拆开看，插件做四件事：
1、注册 tariff、api_balance 两个工具，供模型在对话中调用；
2、内置提醒调度器，按配置的时刻触发峰时切换提醒；
3、开放 /tariff RPC 通道（status、balance 两个动作），供浏览器侧取数；
4、向 Web GUI 顶部栏注入一个状态徽标组件。
代码结构上，时段逻辑（src/tariff.ts）、余额查询（src/balance.ts）、提醒调度（src/reminder.ts）是三个独立模块，src/index.ts 负责接线，client/client.js 是浏览器侧的徽标组件。
核心功能¶
tariff 工具：峰谷时段查询¶
调用后返回三类信息：当前处于峰时还是谷时、完整时段表、下一次切换时刻。
默认时段表如下：
00:00 – 09:00 谷时
09:00 – 12:00 峰时
12:00 – 14:00 谷时
14:00 – 18:00 峰时
18:00 – 24:00 谷时
边界按「到达即切换」处理：09:00 整点即进入峰时。时段逻辑带时区换算，时区可用配置项 timezone 指定（IANA 名称，如 Asia/Shanghai），默认取宿主本地时区。
api_balance 工具：余额查询¶
查询 DeepSeek API 账户余额。端点默认 https://api.deepseek.com，可用环境变量 DEEPSEEK_BASE_URL 覆盖，与 DSH 内置 llm-deepseek 适配器一致。余额结果在 host 侧缓存 60 秒，缓存期内重复查询不会重复请求接口。
实现上依赖全局 fetch（Node 22+ 自带），插件的 engines 要求 node ^22.19.0 || >=24.0.0。若走非官方网关且该网关未实现 /user/balance 端点，会返回明确的 HTTP 错误信息。
峰时切换提醒¶
默认每天 08:50、13:50 各触发一个提醒窗口（提前 10 分钟），提示「10 分钟后进入峰时」，对应窗口 08:50–09:00 与 13:50–14:00，每个窗口每天提醒一次。时刻与窗口长度都可配置。
reminderWake 为 true（默认）时，唤醒 agent 一轮、由模型播报提醒；设为 false 则仅注入 next-step 上下文，不产生模型调用。
Web GUI 顶部栏状态徽标¶
徽标挂在会话头部右侧（conversation.session.header.utilities 插槽，条目 id 为 tariff-status），显示三段内容：时间 | 当前时段与切换倒计时 | 账户余额。时间与倒计时每秒刷新，且为本地计算，不走网络；峰时显示橙色，谷时绿色。
余额不自动轮询：点击余额徽标才查询一次，host 侧另有 60 秒缓存，频繁点击不会反复打余额接口。查询中显示「查询中…」，连接不可用或未配置 Key 时显示「余额不可用」，悬停可见原因，可点击重试。
数据经专用 /tariff RPC 通道走 host 侧，API Key 只存在于 host 侧，浏览器不接触。这里有一个设计前提值得注意：插件不应占用 /api 通道——那是 DSH 网关（Typert Remote）独占的共享通道，第三方插件抢占会导致插件列表、命令执行等 Remote 功能静默失效，所以本插件使用了独立的 /tariff 通道。
安装与验证¶
先安装，再验证。以 Profile Bundle 方式安装到 web profile：
dsh plugin --profile web add github:omdsh-dev/dsh-tool-tariff
一次性任务或 headless 环境也要用时，安装到 headless profile：
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-tariff
安装后验证插件已挂载：
dsh --profile web --dump-config | grep tool-tariff
命令有输出即说明挂载成功。注意：前端徽标需要重启 Web GUI 后才生效，因为 web profile 的 HMR 处于关闭状态。
配置¶
配置项全部可选，写在 cordis.yml 的 plugins.tool-tariff 下，文件位置为 $DSH_HOME/profiles/web/cordis.yml，或通过 --patch 传入。
| 字段 | 默认值 | 说明 |
|---|---|---|
timezone |
宿主本地时区 | IANA 时区名，如 Asia/Shanghai |
baseURL |
$DEEPSEEK_BASE_URL 或 https://api.deepseek.com |
余额查询端点 |
apiKeyEnv |
DEEPSEEK_API_KEY |
凭据引用名 |
reminderTimes |
["08:50", "13:50"] |
每天提醒时刻列表（HH:MM） |
reminderWindowMinutes |
10 |
每个提醒的窗口长度（分钟） |
reminderTickMs |
20000 |
提醒调度轮询间隔（毫秒） |
reminderWake |
true |
true 唤醒 agent 由模型播报；false 仅注入 next-step 上下文 |
balanceCacheMs |
60000 |
余额结果缓存毫秒数 |
配置示例：
plugins:
tool-tariff:
timezone: Asia/Shanghai
reminderTimes: ['08:50', '13:50']
reminderWake: true
典型用法¶
经过上面的安装与配置，在对话中直接提问即可：
- 问「现在是什么时段？」或「什么时候进入峰时？」——模型会调用
tariff工具； - 问「查一下 API 余额」——模型会调用
api_balance工具； - 每天 08:50、13:50 自动收到峰时切换提醒，默认会唤醒模型用一句话播报。
余额查询有一个前提：先配置 DeepSeek API Key，两种方式任选其一：
1、在 DSH 设置页（模型/凭据页）配置凭据 DEEPSEEK_API_KEY；
2、或导出环境变量 DEEPSEEK_API_KEY。
适用场景与注意事项¶
适合两类使用者：需要按峰谷时段安排任务节奏、希望在峰时到来前收到提醒的人；想在会话里直接查 DeepSeek API 余额、并让顶部栏常驻显示的人。
使用前有几点需要注意：
- 插件以当前 dsh 进程的权限运行，安装第三方插件前应先阅读其源码并确认许可证。dsh-tool-tariff 采用 MIT 许可证，源码在 GitHub 仓库公开。
- 提醒的「每日一次」语义仅存在于进程内存：进程在提醒窗口中途重启，当天会再次触发（符合预期）；提醒只投递给当前存活的顶层 agent，没有存活 agent 时静默跳过。
- headless profile 没有 connection 服务，RPC 通道会自动跳过，两个工具与提醒功能不受影响。
小结¶
dsh-tool-tariff 把「现在什么时段、还有多久切换、API 还剩多少余额」这几件高频查询收进了 DSH：模型可答、顶部栏可见、到点会提醒，API Key 全程留在 host 侧。源码与文档见 GitHub 仓库 https://github.com/omdsh-dev/dsh-tool-tariff，也可以在社区插件目录查看它的条目：https://www.skillhub.cn/plugins/omdsh-dev/dsh-tool-tariff。
