前言¶
如果要把任務安排在谷時跑、峯時到來前收尾，就得隨時清楚現在是峯時還是谷時、下一次切換在幾點。已有的做法是自己記一份時段表、靠手動覈對，麻煩也容易忘；想確認 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。
