前言¶

在 DeepSeek Harness（DSH）的 composer 底部，上下文用量环（context-usage ring）与会话统计胶囊同处一行，用来反映当前会话的 contextPressure 投影。当模型调用因限流、超时或传输错误失败，并由 @deepseek-ai/dsh-llm-retry 自动重试时，宿主仍可能收到一个「全零」的 usage chunk；投影把它当作最新样本，环会短暂显示 0%，尽管上下文并未清空。与此同时，随包样式表里 meter trigger 与 StatsPills 的字号差 1px，环上的百分比比同行数字略大，视觉上像另一套字体。下面介绍社区插件 dsh-context-usage-guard（维护者 icrefin），如何在宿主与浏览器两侧各做一处最小修补，且不新增页面或持久化配置以外的负担。

这是什么¶

dsh-context-usage-guard 是面向 DSH 0.2.0-rc.2 的客户端类 Cordis 插件（npm 包名 dsh-context-usage-guard，当前发布版本 v0.2.0，MIT 许可证）。它修复 composer 上下文用量环的两处问题：重试风暴期间环不再被空 usage 样本压成 0%；环上百分比与 footer 里其他数字同字号。插件不替换 meter 组件、不改投影注册表，也不编造用量数字。

两个症状与修复思路¶

重试期间环塌到 0%¶

环渲染会话投影 contextPressure，其中：

pressureTokens  = usage.inputTokens + cacheReadTokens + cacheWriteTokens
projectedTokens = max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens)

失败尝试在 provider 未报告有效计量时，仍可能以如下流结束（示例为 RATE_LIMIT）：

[ { "type": "chunk", "chunk": { "type": "usage",  "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 } } },
  { "type": "chunk", "chunk": { "type": "finish", "reason": { "kind": "error",
      "failure": { "code": "RATE_LIMIT", "message": "429: token_capacity_exceeded" } } } } ]

该样本计数全为零，却被当作「最新样本」，未加防护时 pressureTokens 与 projectedTokens 都会变成 0，环显示 0%。README 中针对真实会话回放（test/fold.spec.ts）的对照：最后一次成功调用后环为 6%；失败尝试未拦截时为 0%，拦截后仍为 6%。

百分比比同行数字大 1px¶

@deepseek-ai/dsh-client-ui-chat 的 StatsPills 与 @deepseek-ai/dsh-client-ui-conversation 的 ContextMeter trigger 对 secondary 字号的处理差 1px（前者 calc(... - 1px)，后者直接用变量）。环上的 30% 因此比 182 steps、Cache hit 94% 等略大约 8%（约 13px 对 12px cap height）。

核心功能¶

插件分两半，均不增加路由、设置页或落盘文件（配置仅通过 Cordis patch 中的 config 字段）：

宿主侧声明 inject: ['llm']，在 ctx.effect 中注册 listener，卸载或关闭配置行时由 cordis 清理。规则要点：

• 成功完成（stop、tool-calls、max-tokens 等）报告的 usage 原样通过，即使为零；
• 失败但已有非零计数的 partial 调用不丢弃；
• 流顺序与终止 finish chunk 保持不变，仅可能 withheld 那一个 usage chunk。

浏览器侧使用结构选择器（不依赖 content-hashed 类名）：

button[aria-haspopup="dialog"]:has(> svg > circle) {
  font-size: calc(var(--dsh-content-font-size-secondary,13px) - 1px);
}

上游若统一字号，仓库中的 test/meter-typography.spec.ts 会失败，届时应移除该 workaround。

环境要求¶

构建产物已提交在 lib/，安装插件本身不需要在目标机器上执行 pnpm build。

安装与启用¶

官方 README 给出的安装步骤如下。先克隆仓库并执行安装脚本，脚本会生成 tarball 并打印路径：

git clone https://github.com/icrefin/dsh-context-usage-guard.git
cd dsh-context-usage-guard
sh scripts/install.sh

scripts/install.sh 会打出 dist/dsh-context-usage-guard-0.2.0.tgz。桌面 profile 归 Electron 应用所有，不能对该 profile 使用 dsh plugin add；应在 Settings → Plugins 中安装该 tarball（或使用插件管理器工具），然后重启 harness。装进正在运行的 profile 的 bundle 时，当前进程无法 import；浏览器侧还需刷新页面。

运维上需注意：同一版本号重装时 pnpm 可能复用已解压包，若需强制更新 tarball，应先移除 bundle 再安装或 bump 版本。宿主侧 listener 在进程启动时加载，后续仅改客户端 bundle 可热更新浏览器半侧，但宿主半侧改动需重启后生效。

卸载：从 Settings → Plugins 移除 bundle 并重启；插件不写额外持久状态。

配置¶

在 profile 的 cordis.patch.yml 对应插件行的 config 中写入：

- id: dsh-context-usage-guard
  config:
    enabled: true
    logHeldSamples: false

两项均为 volatile，下一请求即生效，无需重载 profile。

典型用法与验证¶

日常使用中无需额外操作：enabled: true 时，限流重试等场景下环应维持失败前的百分比，而非长时间显示 0%。若需确认宿主侧是否拦截，可将 logHeldSamples 设为 true，日志示例形态为：

[dsh-context-usage-guard] held an empty usage sample from a failed request
  (example-provider/example-model-v1, RATE_LIMIT); the context reading stays at its last value

开发者在仓库内自检可执行（需 pnpm，仅用于开发本插件）：

pnpm install
pnpm check

pnpm check 会对宿主与客户端两半做 TypeScript 检查，并运行 5 个套件共 40 个测试。

适用场景与注意¶

适合在 DSH composer 中依赖上下文用量环判断「是否接近窗口上限」的开发者：尤其在频繁触发 retry（429、超时等）的长会话里，避免误读 0% 而做出不必要的压缩或新开对话。

务必知晓：

• 插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 源码 与 MIT 许可证，自行评估信任边界。
• 宿主侧只覆盖经 LLM 服务 llm/stream 的调用；绕过该服务直连 provider 的路径不受此插件影响。
• 浏览器侧字号修复是随上游声明差异而存在的 workaround；上游合并后应删除注入规则。
• 若环仍为 0%，先查 enabled；成功完成且 provider 报告全零的 usage 不会被拦截——那是随包语义，而非 guard 失效。

插件不会冻结读数：下一次成功调用上报真实 usage 后，环会正常推进；不会在没有可测量数据时显示虚构百分比（无数据时环保持隐藏，与随包行为一致）。

结尾¶

dsh-context-usage-guard 用一条流过滤规则与一条 CSS 声明，分别稳住重试期间的 context 读数，并对齐 footer 排版。DSH 生态强调「一切皆插件」；社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。源码、Issue 与发布说明见：https://github.com/icrefin/dsh-context-usage-guard。