前言¶
在 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
