前言¶
在 DSH 里跑长会话时，上下文窗口会逐渐被 system、工具 schema 和消息堆满。界面右上角虽有占用计，但想在输入框里随手查一次「用了多少、还剩多少、构成如何」，若每次都靠模型侧工具，往往要在 system prompt 里常驻额外 schema，还会打断 prefix 缓存。下面介绍社区插件 dsh-ctx-meter：用 /ctx 斜杠命令按需打印占用，并在占用越过 25% / 50% / 75% 时各发一条可折叠的 host 通知；命令本身不消耗模型 token，插件无 client.js，不占 UI 槽位。
这是什么¶
dsh-ctx-meter 由维护者 ecbob 发布，分类为客户端插件（实际实现为 Host-only：仅宿主侧逻辑，无前端组件）。它读取 DSH 会话投影（与 @deepseek-ai/dsh-token-meter 及 Web UI 占用计同源），提供两种面向用户的表面：
| 表面 | 触发方式 | 模型 token 成本 |
|---|---|---|
/ctx 读数 |
在 composer 输入 /ctx |
0 — 命令发现、执行与 UI 输出不会进入模型消息，也不向 system prompt 追加工具 schema |
| 档位报告 | 占用越过 bands 中的百分比 |
约 35–45 tokens：一条 form: 'notice' 的 host aside（UI 折叠，模型可见以便决定是否 compact） |
兼容 DSH >= 0.2.1-rc.2（README 注明在 0.2.1-rc.2 上测试）。当前包版本 0.1.1，许可证 MIT。仓库：https://github.com/ecbob/dsh-ctx-meter；社区目录页：https://www.skillhub.cn/plugins/ecbob/dsh-ctx-meter。
核心功能¶
/ctx 按需读数¶
输入 /ctx 后，输出与界面右上角占用计同源的数字，例如中文会话下可能类似：
/ctx
上下文占用 50.8% · 133,170 / 262,144 tokens · 剩余 128,974
档位：已越过 25% / 50% · 下一个 75%（还差 63,438 tokens）
构成（启发式）：system 34,120 · tools 2,880 · messages 96,170
计费累计：输入(未缓存) 210,110 · 输出 8,120 · 缓存读 1,020,000 · 缓存写 40,000
README 说明：该命令不写入会话日志之外的内容，也不消耗模型 token。尚无 usage 样本时会降级为表面估算，读数与报告会标明「估算」。
档位 crossing 通知¶
默认在占用向上越过 25%、50%、75% 时各报告一次（每个档位仅一次；继续升高不会重复）。示例形态：
📊 上下文越过 50%：现在 50.0% · 131,197/262,144 tokens · 剩余 130,947 tokens
机制要点（均来自 README）：
- 仅向上穿越时触发，每档一次。
- 2 个百分点滞回：占用需落到
band - 2%以下才重新武装该档，compact 后可再走一轮 25 / 50 / 75。 - 一次跳跃跨多档时合并为一条报告。
- 挂载插件只建立基线，不会回放挂载前的历史。
- 档位状态在进程内
WeakMap中按会话维护；重启后从新基线开始。
最高档报告可附带「需要时可在步骤安全点 compact_now」提示；配置 hint: false 可关闭。报告用 notice 而非 agent.followup()，目的是不主动唤醒 agent；在你保持沉默时，notice 的 token 成本为 0，直到下一步真正被接纳时才计费。
数字从哪来¶
数据来自 DSH 的 contextPressure / contextBreakdown / tokenUsage 等会话投影：分子基于最新 provider usage 样本并按 surface 的有符号变动调整（以反映 compact）；分母为最新 request/context 的 contextWindow，不硬编码模型或窗口大小。订阅 ctx.sessionProjections.onChanged，经 stateOf() / snapshot() 读取，O(1) 查找、无轮询，且不调用 tokenMeter.measure()。
与 smart-compaction 的关系：后者提供模型侧 context_status、compact_now 及安全点自动 compact；本插件补充用户侧免费读数与跨档短提醒，二者读同一投影，数字一致。README 指出再增加一个工具会在 system prompt 中常驻约 150 tokens 并破坏 prefix 缓存，因此采用 /ctx 命令而非工具。
配置¶
包内默认 config: {}。在 profile 的 cordis.patch.yml 中用相同 id 覆盖（整段替换 config）：
- id: ctx-meter
name: 'dsh-ctx-meter'
config:
bands: [30, 60, 90] # 报告档位，0 < b <= 100，去重排序
notice: true # false：不写会话日志，0 tokens，仅保留 /ctx
hint: false # 最高档省略 compact_now 提示
notice: false 时，v0.1 无 UI 组件，屏幕上不会常驻任何内容；若需要常驻 chip，README 建议 dsh-plugin-usage-meter 或内置占用计。
安装与启用¶
官方 README 的安装步骤如下（勿向 profile 随意增加新的 runtime 依赖；autoInstallPeers: false 时无法解析的依赖会导致 Cordis 无法启动）：
- 打包：
npm pack得到dsh-ctx-meter-0.1.1.tgz，放入<DSH_HOME>\.plugin-sources\。 - 在 profile 中加入本地包：
pnpm --dir <DSH_HOME>\profiles\<profile> add file:..\..\.plugin-sources\dsh-ctx-meter-0.1.1.tgz
- 在 profile 的
package.json里把"dsh-ctx-meter"写入dsh.profile.bundles（pnpm 会写dependencies，bundles需手工编辑，两者都要有）。 - 重启应用。斜杠命令随 bundle 激活注册；若
/菜单里还没有/ctx，刷新页面或再重启。
运行时仅依赖宿主提供的 @deepseek-ai/dsh-llm（用于 createUserMessage）；peerDependencies 仅为声明。Node >= 22。
典型用法¶
- 长对话中在 composer 输入
/ctx，核对占用、剩余、构成与计费累计，无需发起模型轮次。 - 占用升高时留意折叠 notice，在合适时机配合 smart-compaction 或手动 compact；最高档可看
compact_now提示（除非hint: false）。 - 若只希望静默查数、不向日志写入 notice，设置
notice: false，仅使用/ctx。
自测（在插件源码目录）：
node scripts/selftest.mjs # 或: npm test
末行应出现 ALL PASS（38 条断言）。
适用场景与注意¶
适合：需要在 DSH 会话里低成本查看上下文占用、并在 25/50/75（或可配置档位）收到提醒的开发者；与 smart-compaction 搭配时，用户侧读数与模型侧 compact 工具互补。
限制与注意（README）：
- 无 live agent 的会话无法读数，
/ctx会明确说明。 - 报告写入会话日志（
user/message+surfaceOp: append），每条约 35–45 tokens，本身也计入占用。 - 插件在当前 DSH 进程权限下运行；安装前请自行审阅源码与 MIT 许可证，社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-ctx-meter 用 Host-only 的 /ctx 与可选档位 notice，在同源会话投影上提供零 token 的按需读数和跨档提醒，避免为查占用常驻模型工具。进一步了解可访问目录页 https://www.skillhub.cn/plugins/ecbob/dsh-ctx-meter 与 GitHub https://github.com/ecbob/dsh-ctx-meter。
