前言¶
在 DeepSeek Harness（DSH）裏跑會話，token 用量和 API 成本往往有日誌可查，但「這次開發大概排了多少 CO₂」通常沒有現成答案。通用 SaaS 碳計算器很少按 input / output / cache read 這類 LLM 調用結構拆分，也不一定會標註因子來源和置信區間。
dsh-carbon 是社區維護的 DSH 客戶端插件，在終端和 Web 側欄裏給出基於 token 計數的本地估算，並附帶可覈對的方法論與 plausible range。下面介紹它做什麼、如何安裝，以及 CLI 與 GUI 的典型用法。
這是什麼¶
- 名稱：dsh-carbon（npm 包名
dsh-carbon，GitHub：ValenscoA/dsh-carbon） - 維護者：ValenscoA
- 分類：客戶端（向 Harness 注入 Web 側欄頁面，並附帶 CLI）
- 許可證：MIT（README 與 package.json 一致）
插件跟蹤 DeepSeek Harness 會話的估算碳足跡。思路參考 claude-carbon（本地估算、token 驅動、有來源的方法論），但數字並非從 Anthropic 因子直接移植；README 說明 DeepSeek 公開證據更薄，借 Anthropic 因子會得到「看起來確定、背後無依據」的數字，因此採用單獨推導的因子與分級。
當前 package.json 版本爲 0.3.1；README 標明獨立 CLI 需 Node 22.15+，插件本體在應用內運行。
核心功能¶
估算與置信區間¶
報告給出點估計和 plausible range（低—高區間），並在 CLI 示例中按 session、model 拆分，同時展示 input、output、cache read 等 token 種類及佔比。README 強調：輸出 token 佔比很小，但在 grams 側可能佔大頭；cache read 佔 token 絕大多數時，grams 往往約爲其十分之一——因此 GUI 用兩根 bar 分別展示「token 份額」與「CO₂ 份額」。
因子與方法學¶
因子有來源、分級（tier）、區間與 caveat；dsh-carbon methodology 可列出完整方法論。GUI 提供 Method 標籤頁：公式、部署假設、因子表與 cross-checks。可在 DeepSeek 自有 fleet 與 Azure 部署假設之間切換（--infra china|azure|aws，環境變量 DSH_CARBON_INFRA=azure），該切換作用於頁面與 CLI 上的全部讀數。
本地持久歷史¶
數據在本地 store 中與 session 日誌同步（dsh-carbon sync），支持按時間窗重算（recompute）。GUI 以日/周/月條紋展示歷史，顏色相對中位週期而非最大值，工具欄支持 7 天、30 天、90 天、12 個月與全部，並在可比較時顯示相對上一等長窗口的變化。
Web GUI（Carbon 側欄）¶
安裝並在 Harness 重啓一次後，側欄會出現 Carbon 行（README 說明位於 Automation tasks 與 More 之間）。主面板包含：
- 以顏色反映讀數的 whale（與導出卡片共用
lib/core/whale.mjs字符圖） - 估計值 + 區間帶 + 條紋時間線
- 等價換算（如駕車公里、燒水壺次數等，與 CLI 使用相同世界平均因子）
- Download card（1200×630 PNG，瀏覽器內渲染）、Copy badge（shields.io markdown）
- 頁面可見時每 30 秒刷新，聚焦窗口時刷新；刷新按鈕可跳過宿主 5 秒緩存
README 說明：宿主會緩存包是否含 dsh.client 半部；首次安裝或 browser 半部 declaration 變更後需重啓 Harness（或 relaunch），僅 rebuild bundle 可熱更新，宿主側變更需下次重組後生效。
CLI 命令¶
| 命令 | 作用 |
|---|---|
dsh-carbon |
彙總報告：總量、區間、按 session/model、按 token 種類 |
dsh-carbon timeline |
條紋塊、總量、中位週期、四類 token 佔比 |
dsh-carbon sync |
將會話日誌同步到 store |
dsh-carbon recompute |
按 token 計數重算已存 session |
dsh-carbon card |
輸出可分享 SVG（--out、--stdout） |
dsh-carbon badge |
輸出 shields.io badge（--svg） |
dsh-carbon pr |
自分支點起倉庫足跡並關聯 PR（--dry-run、--pr N） |
dsh-carbon sessions |
每 session 一行 |
dsh-carbon json |
機器可讀輸出 |
dsh-carbon methodology |
因子、來源、區間與 caveat |
讀數普遍支持：--range 7d|30d|90d|12mo|all、--since YYYY-MM-DD、--until YYYY-MM-DD、--infra china|azure|aws；report 另有 --limit N。
安裝與啓用¶
要求：DeepSeek Harness 0.2.1-rc.3 或更新（在 dsh.engines.dsh 中聲明）；獨立 CLI 另需 Node 22.15+。
作爲 DSH 插件（含 GUI）¶
desktop 是 profile 名稱，以你本機爲準：
ls ~/.dsh/profiles
誤寫 profile 不會報錯，但會在一個 Harness 不會讀取的空 profile 裏安裝插件；側欄沒有 Carbon 時應先覈對這一點。
安裝命令（README 原文）：
dsh plugin --profile desktop add dsh-carbon
該命令在 profile 內轉發 pnpm add，並把包寫入 dsh.profile.bundles。剩餘手動步驟是重啓 Harness 一次，以便發現 browser 半部。
若 dsh 不在 PATH，macOS 應用內路徑示例：
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
plugin --profile desktop add dsh-carbon
無 npm 時，可使用 GitHub releases 附帶的 tarball：dsh plugin --profile desktop add <tarball URL>。手工方式則爲在 profile 目錄 pnpm add dsh-carbon，並在 dsh.profile.bundles 中加入 "dsh-carbon"。
僅 CLI¶
npx dsh-carbon report
典型用法¶
- 安裝插件並重啓 Harness，在側欄打開 Carbon，選擇時間窗與 infra 假設，查看估計值、區間與 token/CO₂ 雙 bar。
- 在終端同步並重算本地歷史：
dsh-carbon sync
dsh-carbon recompute
dsh-carbon --range 30d
- 導出分享素材：
dsh-carbon card --out footprint.svg
dsh-carbon badge
dsh-carbon json --range 7d
- 覈對方法論與置信說明：
dsh-carbon methodology
適用場景與注意¶
適合：希望在 DSH 開發流程中持續查看會話級、模型級碳足跡估算；需要帶來源與區間、而非單點「精確數字」的開發者；需要在 README 或 PR 中附帶 badge/card 的團隊。
注意：
- 讀數是估算，README 明確 DeepSeek 側公開能耗測量較少；Confidence 區會標出無公開能耗測量的 model session 比例。
- 插件以當前 DSH 進程權限運行，會讀取本地 session 日誌與 store；安裝前請閱讀源碼與 MIT 許可證，確認符合你的環境與合規要求。
- DSH 生態強調「一切皆插件」；社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-carbon 把 DeepSeek Harness 會話的 token 用量轉成帶來源因子、置信區間和本地歷史的碳足跡視圖，終端與 Web 側欄共用同一套核心邏輯。若要進一步瞭解實現與因子表，可直接閱讀倉庫 README 與 methodology 輸出。
- 目錄頁：https://www.skillhub.cn/plugins/ValenscoA/dsh-carbon
- GitHub：https://github.com/ValenscoA/dsh-carbon
