前言¶
DeepSeek Harness（DSH）的默認側欄往往把面板圖標、工作區與會話列表擠在同一列裏：工作區被壓到下半區，會話標題拿不到整列寬度，也很難從視覺上區分「工作區層級」和「會話層級」。若還想在桌面端順便看到賬號餘額與今日消費，多半要切到瀏覽器或另開頁面。
dsh-rail（倉庫名 xiaoxiaolelang-ai/dsh-rail，npm 包名 dsh-rail）是維護者 xiaoxiaolelang-ai 提交的 客戶端 類插件，定位是「給 DeepSeek Harness 的側邊欄做減法」：圖標收進 40px 窄欄、用線條和字重拉出層次，並在側欄底部欄上方常駐一條 DeepSeek 餘額與消費摘要。它不替換宿主 slot、不重排 React 樹，主要依賴注入樣式與少量數據屬性，卸載時可還原。
下面按定位、功能、安裝、用法與邊界說明如何接入。
這是什麼¶
- 名稱：dsh-rail（中文產品介紹裏常寫作「窄軌」）
- 分類：客戶端（
dsh.client，platform: web，immediately: true） - 引擎要求：
engines.dsh >= 0.2.2-rc.1（README 寫明在0.2.2-rc.1上驗證）；Node>= 20 - 當前包版本（
package.json）：0.3.1 - 許可證：MIT
- 社區目錄：SkillHub 插件頁（獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）
- 源碼：GitHub - xiaoxiaolelang-ai/dsh-rail
插件向 @deepseek-ai/dsh-client-ui-sidebar、dsh-client-ui-workspace 等客戶端模塊注入補丁（cordis.patch.yml），在瀏覽器側改側欄柵格與樣式，在 Host 側通過 /api/dsh-rail/balance 等路由提供已算好的餘額 JSON。
核心功能¶
圖標窄欄（40px + 內容列）¶
側欄改爲「40px 圖標列 + 內容列」兩列柵格：所有面板圖標進左側豎欄；品牌、新建會話、工作區與會話列表佔右側整列。工作區不再被擠在下半欄，會話標題可使用完整寬度。
- 圖標懸停有原生
title提示；當前面板左側有一條 2px 強調條。 - 原生類名從注入的 CSS Module（
style[data-plugin-css="…"]）運行時解析，宿主升級換哈希時仍可對上類名；解析不到的規則會跳過，窄欄與餘額條仍可工作。
側欄層次與會話標題¶
用細線、字重和強調色區分層級，顏色全部走 --dsw-alias-* 主題令牌（含線條 alpha），淺色 / 深色跟隨宿主，無硬編碼色值。
- 工作區之間：1px、強調色淡染的圓頭分隔線。
- 組內會話之間：1px 中性發絲線；每個工作區標題下有一條淡豎線，括住其下會話。
- 選中會話左側 2px 強調條；鍵盤聚焦時未選中行也顯示同一條。
- 工作區標題字重 500，文件夾圖標提到二級色。
- 會話標題：普通會話用次級色；選中 / 懸停 / 鍵盤聚焦升到主色，選中再加一檔字重；相對時間保持三級色。
- 會話列表右緣按原生滾動條寬度加偏移內縮，行 hover 底色與滾動條對齊。
工作區會話數¶
工作區行末尾顯示其下會話個數（11px、三級色、等寬數字）；懸停時讓位給行操作按鈕。
計數邏輯（README 說明）：
- 展開時：數屏幕上真實的會話行。
- 摺疊時：宿主不渲染那些行，使用上次展開時記在
localStorage的值（鍵dsh-rail:session-counts:v2）。 - 首次啓動且工作區一直摺疊：不顯示數字（插件不猜測、不讀宿主內部狀態）。
- 別處增刪會話後，摺疊態可能顯示舊值，下次展開會糾正。
計數寫在行自身的 data 屬性上，由 CSS content: attr() 渲染，不插 DOM 節點。
餘額條與今日 / 累計消費¶
側欄底部欄正上方一行，典型展示包括：狀態圓點、餘額（如 ¥ 23.41）、今日消費、累計消費（小標籤 + 數值，右對齊分組，中間豎線分隔）。
狀態圓點與數字顏色（閾值在 client.js 頂部：WARN_AT = 50、LOW_AT = 10）：
- 正常：中性灰
- 餘額低於 50：琥珀
- 低於 10：紅
- 未登錄：暗灰
刷新：平時約每 60 秒自動刷新；切回窗口時也會刷新。
點擊行爲（0.2.2 起）：
- 單擊：在新窗口打開平臺充值頁，地址來自宿主賬號狀態
deepseekAccount.getState().links.topUpUrl，非插件寫死。 - Shift + 單擊：立即刷新余額。
- 宿主未提供充值地址時，單擊退回爲刷新。
- 懸停可查看充值 / 贈金分項、更新時間、今日與累計消費（含累計起始日）、今日充值 / 今日贈金等。
今日花費算法（README 強調與舊版不同）：
- 右側今日數值是今日累計消費，不是「當前餘額相對早晨的差值」。
- 已移除讀寫
DSH_HOME/dsh-usage/usage-ledger.json的「賬本優先」路徑；改爲只用分錢包採樣（充值餘額、贈金餘額分別跟蹤）。 - 任一錢包餘額下降 → 記入今日消費；充值錢包上升 → 今日充值；贈金錢包上升 → 今日贈金；充值不會把今日消費衝成負數或抹掉。
- 狀態落在
DSH_HOME/dsh-rail/day-spend.json（狀態文件v: 3），重啓當天接着算，跨天自動歸零。 - 精度受 60 秒輪詢影響：同一分鐘內先充後花可能被當成淨漲，README 認爲不必爲此做更復雜記賬。
- 今天尚未消費則不顯示今日數字；懸停仍可見今日花費與今日充值。
累計消費口徑（重要）：
- 不是賬號官方歷史總消費；官方接口只給三個餘額，反推不出全歷史。
- 只覆蓋插件持續運行期間觀察到的餘額下降；DSH 關閉或插件禁用期間的消耗會漏記。
餘額數據來源¶
- 優先使用宿主內置 DeepSeek 賬號（
deepseekAccount服務）；已登錄即可顯示，不需要 API Key。 - 不可用時回退
DEEPSEEK_API_KEY（先環境變量，再宿主憑據）；請求帶 10 秒超時，避免餘額條長期停在「讀取中」。明文僅在 Host 進程使用，不下發到瀏覽器。 - 瀏覽器通過
connection的精確 fetch 路由/api/dsh-rail/balance取 JSON。 - 兩條都拿不到時顯示「未登錄」，不編造數字。
安裝與啓用¶
在 DSH 插件管理器中添加包名 dsh-rail，或命令行：
dsh plugin install dsh-rail
安裝後刷新頁面；首次安裝或升級客戶端代碼時，正常退出 Desktop 再啓動更穩妥。
插件以當前 DSH 進程權限運行，安裝前宜自行查看倉庫源碼與 MIT 許可證，確認可接受其 Host 側讀賬號 / API Key、寫 DSH_HOME/dsh-rail/ 等行爲。
典型用法¶
dsh-rail 無單獨「配置文件」面向終端用戶；啓用後隨側欄自動生效。日常使用可按下述理解交互即可。
- 在側欄左側豎欄點圖標切換面板；右側整列瀏覽工作區與會話。
- 展開工作區後，摺疊時纔會穩定顯示該工作區的會話數；若從未展開過，摺疊態不顯示數字。
- 看底部餘額條：顏色反映餘額檔位；需要充值時單擊餘額條（新窗口打開宿主給出的
topUpUrl）；需要馬上更新數字時用 Shift + 單擊。 - 懸停餘額條查看分項與今日 / 累計消費說明；理解「累計」僅爲插件運行期觀測值，不等同平臺賬單全量。
開發者本地校驗（倉庫 README）：
node --check client.js
node _smoke.mjs
node _smoke-host.mjs
適用場景與注意¶
適合誰
- 長期在 DSH Desktop / Web 客戶端裏維護多工作區、多會話，希望側欄更寬、層次更清晰。
- 希望在側欄底部附近看到 DeepSeek 餘額，並粗略跟蹤「今日花了多少」（分錢包採樣），而不是頻繁切網頁。
兼容與邊界
- 側欄摺疊到 56px 時，宿主會隱藏整個底部區，餘額條一併隱藏——原生行爲，插件不覆蓋。
- 未實現工作區吸頂：
position: sticky與宿主行容器的overflow裁剪衝突，README 明確不做。 - 與修改側欄結構或全局主題的其他皮膚插件可能樣式互蓋；與側欄外觀類插件 繁界（fanframe） 建議二選一。
- 深色主題下線條 alpha 會略調高，便於辨認。
安全與信任
- 餘額與消費邏輯在 Host 側執行；客戶端只拿算好的 JSON。仍建議在可信環境安裝，並知悉其會讀寫本機
DSH_HOME/dsh-rail/下狀態文件。
結尾¶
dsh-rail 把 DSH 側欄收成「圖標窄軌 + 內容列」，用輕量樣式補層次與會話數，並在底部提供可點擊充值的餘額與今日 / 累計消費摘要；實現上儘量不碰 React 結構，卸載可清理注入內容。
