dsh-daily-context-budget

安装与配置

# dsh 配置示例
- id: context-budget
  name: dsh-daily-context-budget
  config:
    enabled: true
    warnAt: 0.7        # 水位 ≥ 70% 告警（每会话每档一次，回落到 warnAt 以下后重新武装）
    criticalAt: 0.85   # 水位 ≥ 85% 临界告警，附明确建议
    contextWindows:    # 适配器不上报窗口时的兜底表
      deepseek-chat: 128000
      "openrouter/*": 200000
    fallbackWindow: 128000

告警行为

• 每会话、每档（warn / critical）只报一次；水位回落到 warnAt 以下（例如压缩之后）两档重新武装，再次越线会再次告警。
• 告警双通道：会话自定义事件 context-budget/warning（含水位、窗口、模型、窗口来源、建议文案）+ 插件 logger 警告。
• 越过 critical 时 warn 档一并锁存，避免"仍处临界却补报 warn"的噪音。

工具

• context_status：返回结构化 JSON（估算占用、窗口、比例、档位、模型、窗口来源、当前阈值），render 为可读摘要。当前会话还没有带 usage 的调用时返回 tracked: false。
• context_config：查看或临时调整 warnAt / criticalAt（需 0 < warnAt < criticalAt ≤ 1），reset=true 恢复插件配置。调整仅进程内存中生效，重启后丢失——工具机制允许改内存状态，但不写配置文件，这是刻意为之。

权限透明

本插件对宿主环境的影响面，逐条交代清楚：

• 读写位置：无（不读不写任何文件；会话事件 context-budget/warning 由 dsh 会话日志机制持久化，属正常会话记录）
• 网络域名：无
• 凭证：不持有任何凭证
• 确认点：无（只读监听 + 告警，不拦截任何调用）
• 日志内容：告警日志含水位的 token 数与 provider/model，不含任何对话内容

已知限制

• 水位是启发式估算（见上节），不能替代精确的上下文计量。
• 阈值告警是事后通知（调用完成后才看到 usage），无法在调用前拦截阻止超限。
• context_config 的阈值调整不持久化，重启恢复插件配置。
• 窗口解析依赖适配器上报质量；适配器不报且配置未覆盖时使用 fallbackWindow，可能与真实窗口不符。

手动验证

本仓库的 CI 只覆盖类型检查与纯函数单测。接入真实 dsh 后请手动验证：

1. 在 dsh 配置中启用本插件，确认启动日志出现 context-budget: loaded。
2. 进行若干轮对话后调用 context_status 工具，确认返回水位、窗口来源（adapter/config/fallback）与档位。
3. 将 warnAt 调低（如 context_config 设 warnAt: 0.01），再发一条消息，确认出现警告日志且会话事件流中追加了 context-budget/warning（tier=warn）。
4. 继续设低 criticalAt 复验 critical 档的建议文案；确认同一档不重复告警。
5. 触发一次压缩（或等待自动压缩），下次调用后确认水位回落、档位重置。

许可

MIT