前言¶
在 DeepSeek Harness（DSH）裏跑多路由、多模型時，token 消耗往往分散在單次請求裏；若還要切到單獨報表或控制台覈對花費，上下文會被打斷。下面介紹社區插件 dsh-api-ledger（維護者 LAwLi3tCoding）：在對話內、設置頁、Composer 下方和側欄彙總用量，並按路由/模型做可解釋的估價，支持 CNY/USD 展示切換。
這是什麼¶
dsh-api-ledger 的定位是：爲 DSH 記錄 API token 用量，並給出估算費用（非發票、非賬戶餘額）。數據與偏好在插件本地處理；README 明確說明不讀取 API Key 明文、也不把賬本上傳到插件自有服務。
- 倉庫：LAwLi3tCoding/dsh-api-ledger
- 社區目錄：SkillHub 插件頁
- 分類：admin-security
- 當前 package 版本：0.4.0（MIT 許可證）
- 環境要求：Node.js 20+；README 註明在 DSH Desktop 2.0.13 / bundled DSH 0.1.5-rc.2 上測試，無構建步驟、無運行時 npm 依賴
四個視圖分別回答什麼¶
| 視圖 | 作用 |
|---|---|
| 對話 → API Ledger | 本會話花了多少：近期調用、模型費用、token 構成與趨勢 |
| Settings → API Ledger | 跨會話支出分佈：日期範圍、今昨對比、定價偏好 |
| Composer 下方 | 當前會話累計用量/花費 |
| 側欄頁腳 | 今日一行彙總；點擊可進入設置頁完整報表 |
CNY/USD 爲展示換算（固定 1 CNY = 0.14 USD），不是實時匯率。調用在結束時寫入 usage；可見視圖約每 10 秒刷新；「今日」按客戶端日曆。
定價與路由¶
定價按路由（account）+ 模型分開配置，同一模型在不同路由可以不同價，避免官方端點與網關互相污染估算。
- 路由默認分開統計；可爲多條路由設置相同 billing group 合併報表。共享 Key 引用不會靜默合併賬戶或暗示共享餘額。
- 每條路由可爲多個模型分別定價；未配置時默認 Usage only（只記 token，不虛構費用）。
- 三種模式（Settings → API Ledger → Accounts and pricing）：
- Price-book estimate：綁定價目表（含可選峯谷時段；按價目表時區在請求開始時判斷）。
- Custom price estimate：按百萬 token 設 uncached input、output、cache read、cache write；貨幣與單價可設，0 合法。
- Usage only：僅記錄用量。
內置價目表 deepseek-public-2026（README 標註 verified 2026-09-21）覆蓋 deepseek-flash、deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-v4-pro，含上海時區峯谷與 2026 節假日規則；任意賬戶都可綁定，官方 DeepSeek 端點僅是在識別爲官方 URL 時默認綁定。價目隨插件發佈更新，無 live pricing API。
高級用戶可在 $DSH_HOME/api-ledger/config.json 的 tariffs 段添加自定義價目（UI 暫無編輯器），例如：
"tariffs": {
"acme-gateway": {
"label": "ACME gateway", "currency": "CNY", "timeZone": "Asia/Shanghai",
"verifiedAt": "2026-10-01", "source": "https://intranet.example/pricing",
"peak": { "days": "mon-fri", "windows": ["09:00-12:00"], "multiplier": 1.5 },
"holidays": { "2026": [["01-01", "01-03"]] },
"models": { "deepseek-v4-pro": { "inputPerM": 4, "outputPerM": 12, "cacheReadPerM": 0.4 } }
}
}
綁定示例：
"pricing": { "corporate-gateway/deepseek-v4-pro": { "mode": "tariff", "tariff": "deepseek-public-2026", "window": "auto" } }
歷史調用保留當時使用的費率；改價隻影響後續請求。未知價格保持「未計價」，不會顯示爲 0 元。
安裝與啓用¶
插件以當前 DSH 進程權限運行；安裝前建議閱讀倉庫源碼與 MIT 許可證。SkillHub 爲社區目錄站點，與 DeepSeek / 幻方無官方從屬關係。
DSH Desktop（GitHub 安裝）¶
README 給出的步驟如下。安裝會鏈接到克隆目錄，需保留該目錄；更新用 git pull 後重啓。
git clone https://github.com/LAwLi3tCoding/dsh-api-ledger.git
cd dsh-api-ledger
node scripts/install.mjs
重啓 DSH Desktop 後，打開 Settings → API Ledger，或在對話中的 API Ledger 標籤頁使用。卸載鏈接安裝：
node scripts/install.mjs --uninstall
DSH CLI（profile 管理）¶
將 web 換成你實際管理的 profile。DSH 0.1.5-rc.2 保留 desktop 給 Electron，dsh plugin --profile desktop add ... 會被拒絕；Desktop 請用上節方式或等 marketplace 上架。
# From GitHub
dsh plugin --profile web add github:LAwLi3tCoding/dsh-api-ledger
# From npm
dsh plugin --profile web add dsh-api-ledger
典型用法¶
- 完成安裝並重啓 DSH。
- 在 Settings → API Ledger → Accounts and pricing 爲各路由/模型選擇價目表或自定義單價，Save route 保存。
- 正常對話發請求；在 Composer 下看會話累計，側欄看今日一行。
- 打開對話內 API Ledger 查看本會話明細；在設置頁 API Ledger 做跨會話對比與貨幣展示切換。
近期調用會標明定價來源，便於覈對估算依據。
適用場景與注意¶
適合：需要在 DSH 工作流內持續看到 token 與估算成本、多路由/多網關分別計價、希望 CNY/USD 統一展示的開發者或團隊。
務必知曉：
- 數字是估算，不是服務商賬單、剩餘額度或訂閱費；部分計價時合計只含已知項。
- 展示匯率固定，不代表實際結算幣種。
- Reset/delete 僅清除該路由的 ledger 偏好，不刪 DSH 模型設置或歷史調用記錄。
結尾¶
dsh-api-ledger 把用量捕獲和偏好留在本地插件裏，用四個入口把「這場對話、這個會話、今天、全局」串起來，並按路由/模型讓估價可解釋。更多細節見倉庫 README 與 README.zh.md；安裝與分類信息也可在 SkillHub 目錄頁 查閱。
