上下文占用计 ecbob/dsh-ctx-meter

dsh-ctx-meter

DSH 会话的上下文占用读数：/ctx 按需打印数字（零模型 token），占用越过 25% / 50% / 75% 时，每个档位各发一条简短报告。纯宿主插件——没有 client.js，不占 UI 位置。

仓库：<https://github.com/ecbob/dsh-ctx-meter> · 变更记录：CHANGELOG.md / CHANGELOG.zh-CN.md（两份同步维护）兼容 dsh >= 0.2.1-rc.2（已在 0.2.1-rc.3 上测试）

你能得到什么

/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
数字与界面右上角的占用计同源；本命令不写入会话日志之外的东西，也不消耗模型 token。

（命令输出跟随会话语言——上面是中文会话打印的读数；档位报告读法相同）

📊 上下文越过 50%：现在 50.0% · 131,197/262,144 tokens · 剩余 130,947 tokens

到最高档时，报告会追加 · 需要时可在步骤安全点 compact_now（「在下一个安全点 compact」）；用 hint: false 关掉。

两个入口，都不花钱

| 入口 | 触发方式 | 模型 token 开销 |
| /ctx 读数 | 你在输入框里敲 | 0——命令的发现、执行和 UI 输出都不会变成模型消息，系统提示词里也不会多出任何工具 schema |
| 档位报告 | 占用越过 bands 里的某个百分比 | 约 35–45 token：一条 form: 'notice' 宿主旁注（UI 里折叠，模型可见，所以它能决定要不要 compact） |

报告不会唤醒智能体——这正是关键。agent.followup() 会烧掉一整次模型调用；旁注只在下一步真正被接纳时才计费，所以只要你不说话，它就一直是 0。

数字从哪来

直接取自 dsh 自己的会话投影（contextPressure / contextBreakdown / tokenUsage，由 @deepseek-ai/dsh-token-meter 注册）——和 Web UI 里的占用计同源：

- 分子 = 提示词侧最新的服务商用量采样，再按该采样之后界面的带符号变化量修正（token-meter 自己的 projectedTokens 公式），因为单看用量采样看不到压缩；
- 分母 = 最新 request/context 的 contextWindow，也就是本会话实际路由到的模型的限制——不硬编码任何模型或窗口大小；
- 还没有用量采样时，退化为界面估算，读数和报告都会标明（估算 = estimated）。

订阅走 ctx.sessionProjections.onChanged，读取走 stateOf() / snapshot()：O(1) 表查找，不做轮询，从不调用 tokenMeter.measure()。

档位怎么触发

* 只在向上越过时触发，每个档位一次；继续增长不会重复触发。
* 2 个百分点的滞后：只有占用率降到 band - 2 以下，区间才会重新触发，所以压缩之后会自动进入新一轮 25 / 50 / 75。
* 一次跳跃跨过多个区间时，合并成一条报告。
* 挂载插件只取基线——它从不重放此前发生的历史。
* 区间状态存在进程内的 WeakMap 里，按会话分别判定；重启后从新基线开始。

配置

bundle 自带 config: {}。在配置档自己的 cordis.patch.yml 里用相同 id 覆盖它（覆盖会整体替换 config）：

- id: ctx-meter
name: 'dsh-ctx-meter'
config:
bands: [30, 60, 90] # percentages to report, 0 < b <= 100, de-duplicated and sorted
notice: true # false: nothing is written to the session log at all — 0 tokens, /ctx only hint: false # omit the compact_now hint on the top band

设成 notice: false 后，插件面向用户的唯一入口就是 /ctx（v0.1 不带 UI 组件）。

安装

1. 打包：npm pack → dsh-ctx-meter-0.1.1.tgz，放进 <DSH_HOME>\.plugin-sources\。
2. 加到配置档：

pnpm --dir <DSH_HOME>\profiles\<profile> add file:..\..\.plugin-sources\dsh-ctx-meter-0.1.1.tgz

3. 把 "dsh-ctx-meter" 加进配置档 package.json 的 dsh.profile.bundles——pnpm 只写 dependencies，bundles 列表要手动改；两者都必需。
4. 重启应用。bundle 一激活，斜杠命令就随之注册（实际表现：改完 bundles 后，运行中的会话立刻挂载了 bundle 并发出第一条报告）；如果 / 菜单里还没有 /ctx，刷新页面或重启。

唯一的运行时依赖是宿主提供的 @deepseek-ai/dsh-llm（用于 createUserMessage）；peerDependencies 只是声明，永远不会被安装。不要给配置档新增运行时依赖：在 autoInstallPeers: false 下，一个解析不了的运行时依赖会把 Cordis 拖垮，整个配置档都起不来。

自测

node scripts/selftest.mjs # or: npm test

看最后一行有没有 ALL PASS（38 条断言）。这些断言跑在假的 ctx 和假会话上：逐区间跨越、滞后、压缩后重新触发、多区间合并、会话间独立、notice: false、非法 bands 回退到 25/50/75、disposer 注销命令与订阅，以及 /ctx 的每条错误路径（多余参数、没有智能体、缺少投影、窗口未知）。解析不到真实宿主包时（裸克隆，或直接从已安装副本里跑脚本），测试回退到仓库内提交的替身 scripts/fixtures/dsh-llm.mjs——所以它能离线跑，也从不碰真实配置档。

与 smart-compaction 的关系

smart-compaction 提供模型侧的 context_status 和 compact_now 工具，并在安全点自动压缩；这个插件补上用户侧的免费读数，以及「跨过某个区间时让我说一声」的报告。两者读的是同一份投影，所以数字对得上。再加一个工具，会往系统提示词里永久塞进大约 150 个 token，并在那个位置打断前缀缓存——所以做成 /ctx 命令，而不是工具。

限制

* 会话没有活跃智能体时，没有东西可读；/ctx 会直接说明这一点。
* 报告写进会话日志（user/message + surfaceOp: append），因此计入占用：每条约 35–45 个 token。
* v0.1 没有 UI 组件：notice: false 时屏幕上什么都不留——想要常驻小标签，用 dsh-plugin-usage-meter 或内置的占用计量器。

许可证

MIT © ecbob