前言¶
在 DSH 里跑 Agent 时，上下文窗口会随多轮对话、工具往返和缓存策略不断变化。开发者能看日志，但模型侧通常拿不到「当前已用多少 token、还剩多少、缓存命中率如何」这类读数，长任务里很难在合适时机收窄上下文或触发压缩。社区插件 dsh-context-usage-for-agent（维护者 dixieWithHeart）在宿主会话投影之上，把占用指标暴露给 Agent，并在每轮对话开头可选注入一行摘要；同时在设置里提供开关与模板预览。本文按安装、能力、数据来源与配置说明用法，事实以 GitHub README 为准。
这是什么¶
dsh-context-usage-for-agent（README 亦称「上下文自知」）归类为模型推理相关 DSH 插件，当前 package 版本为 0.6.0，许可证 MIT，要求 Node >= 20。它解决的是：Agent 与界面侧能一致地看到同一会话的上下文占用，而不是凭猜测控制 prompt 长度。
DSH 生态奉行「一切皆插件」；目录站点 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
插件在三处呈现上下文占用，三者相互独立又可组合使用。
context_usage 工具¶
Agent 可调用 context_usage 工具，查询：
- 占用百分比
- 已用 token、上下文窗口大小、剩余 token
- 缓存命中率
若在配置中设置了已知自动压缩阈值（compactAtRatio），工具还可回报距压缩还剩几个百分点。
每轮一行读数¶
在本回合首次工具调用之前，宿主可向对话注入一行格式化读数。默认形态类似：
[ctx 17.7%] 177k/1.00M · 缓存 99.4% · 余 823k
可通过总开关或模板控制是否注入、文案长什么样（见下文配置）。
设置页¶
路径：设置 → 上下文自知。提供注入开关、自定义模板与实时预览。设置页文案随 DSH 界面语言（设置 → 常规 → 语言）在中英文间切换，无需重启；插件清单名称与描述由 locale/zh.json、locale/en.json 提供。
占位符列表中的细字说明目前由宿主提供，且仅有中文；若宿主缺少 locale 服务（精简组合），界面会退回中文并在控制台输出一条 warn。
数据来源与状态¶
占用数字并非插件自行估算，而是对齐宿主事件与投影：
| 项 | 来源 |
|---|---|
pressureTokens |
assistant/message 的 usage：未缓存输入 + 缓存读 + 缓存写（不含输出） |
contextWindow |
request/context 的真实值；未到达前用配置兜底 |
| 回合号 | turn/start |
状态走会话投影（ctx.sessionProjections，key 为 contextUsage），不订阅 session/event。冷读或进程重启后，折叠日志即可得到当前值。
安装与启用¶
在已安装 DSH CLI 的环境中执行官方文档给出的命令：
dsh plugin add dsh-context-usage-for-agent
安装完成后刷新页面。context_usage 工具立即可用；每轮读数默认开启（injectPerTurn 默认为 true）。
插件以后台进程权限随当前 DSH 运行。安装前建议阅读 源码仓库 与 LICENSE，确认符合你的环境与合规要求。
配置¶
两层配置并存：
cordis.patch.yml中的config为启动默认值- 设置页写入
~/.dsh/dsh-context-usage.json，优先级更高
| 项 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关。关闭后只停止每轮读数，工具仍可用 |
injectPerTurn |
true |
是否在每轮注入一行 |
template |
[ctx {percent}%] {used}/{window} · 缓存 {cache}% · 余 {remaining} |
注入文案；留空即不注入 |
contextWindow |
1000000 |
仅兜底；provider 上报后以真实值为准 |
compactAtRatio |
null |
已知自动压缩阈值（0–1）时，工具可回报距压缩的百分点 |
模板占位符¶
| 占位符 | 含义 |
|---|---|
{percent} |
占用百分比，如 17.7 |
{used} / {usedRaw} |
已用 token（带单位 / 原始数字） |
{window} / {windowRaw} |
窗口大小（带单位 / 原始数字） |
{remaining} / {remainingRaw} |
剩余 token（带单位 / 原始数字） |
{cache} |
缓存命中率 |
{turn} |
回合号 |
{compact} |
距压缩百分点（需配置 compactAtRatio） |
未知占位符会原样保留，便于发现拼写错误；已知占位符但取不到值时显示 ?。
设置页通过下列 HTTP 路由读写状态（供 UI 使用，无鉴权）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET/HEAD | /api/dsh-context-usage/state |
设置与实时占用 |
| POST | /api/dsh-context-usage/set |
部分更新设置 |
典型用法¶
- 安装插件并刷新 DSH Web 界面。
- 在 Agent 流程中需要判断「是否接近窗口上限」时，调用
context_usage获取当前百分比与剩余 token。 - 若希望模型在每轮开场即看到占用，保持
enabled与injectPerTurn为true，或到 设置 → 上下文自知 调整模板并查看实时预览。 - 若你已知宿主会在某一占用比例触发自动压缩，将
compactAtRatio设为对应小数，工具与模板中的{compact}才有意义。
仓库内可用下列命令做契约与语法检查（维护者文档）：
node tools/test-context-usage.mjs # 61 条契约断言
node --check index.js client.js
浏览器端设置页渲染需刷新页面目视确认，脚本无法自动断言。
适用场景与注意¶
适合谁： 在 DSH 上开发或调试长链路 Agent、需要根据 token 与缓存命中率做 prompt 收窄、压缩或自我说明的场景；也适合希望在 UI 与模型侧看到一致读数的团队。
注意：
- 关闭
enabled不会禁用context_usage工具，只会停止每轮注入。 contextWindow配置项仅在 provider 尚未上报真实窗口前起兜底作用。- HTTP 状态接口无鉴权，部署在共享或公网环境时需结合整体 DSH 访问控制评估风险。
结尾¶
dsh-context-usage-for-agent 把会话投影里的上下文占用同时交给工具和可选的每轮读数，并在设置页提供模板化展示，减少 Agent 对窗口状态的盲区。进一步了解与安装：
