前言¶

在 DeepSeek Harness (DSH) 的开发或智能体编排场景中，模型往往无法直观感知当前会话的 token 消耗、上下文窗口剩余量或预算进度。这容易导致在上下文撑满或预算耗尽后才被动止损。dsh-plugin-quota 解决了这个问题，它通过实时仪表和预测算法，让模型在每一回合都能“看见”自身的资源消耗，并支持自我刹车。

插件简介¶

这是一个客户端插件，旨在为每个回合提供实时的 token/花费仪表，并给出下一步预估与预算/上下文窗口的消耗预测。模型自身可见这些信息，从而自主控制输出节奏。该插件由 121212165 维护，采用 MIT 许可证。

核心功能¶

• 实时追踪：监听 session/event（assistant/message usage），每次模型回复后实时累计本会话的输入/输出/缓存命中 token。如果配置了价格表，同时估算花费（微单位累计）。
• 注入系统提示：每回合给模型一行实时仪表（例如 实时用量：13.8k tok / 50k ▰▰▰▱… · 5 步 · ≈0.0153 USD），预算超限时模型能直接看见。
• /qm 面板：输入 /qm 查看本会话 + 今日全部会话合计，含预算进度条（需配置 budgetTokens）和超预算警告。
• 下步预估：基于历史数据给出下一回合的 token 和花费区间，以及撑满上下文或烧完预算所需的步数。
• quota_meter 工具：模型可调用此工具自查，结果渲染为 generic 卡片。
• 跨插件契约：通过 ~/.dsh/quota/summary.json 向家族其他插件（如 task-forge）发布预算和上下文状态，无需关心会话 ID 结构。

安装与启用¶

通过命令行安装插件。安装后需重启 dsh，默认配置即可工作（仪表注入 + /qm 面板）。

dsh plugin --profile <你的profile> add github:121212165/dsh-plugin-quota

重启 dsh 后，在对话中输入 /qm 即可查看面板。如果需要预算进度条或估算花费，需配置 budgetTokens 和 prices。

配置说明¶

• 零配置即用：不配置价格和预算时，仅显示 token 数量和步数。
• 价格配置：需配置 prices 才能估算花费。
• 预算配置：需配置 budgetTokens 才能显示进度条。
• 上下文窗口：contextWindow 必须是正有限数，否则启动即报错。

示例配置（放入 profile 的 cordis.patch.yml）：

budgetTokens: 0      # 单会话 token 预算，0 = 不显示进度条
inject: true         # 实时仪表注入系统提示
prices:              # 按模型 id 子串匹配，命中才估花费
  - match: space-bunny
    currency: USD
    perMillion: { input: 1, output: 2, cacheRead: 0.1 }
    contextWindow: 128000   # 撑满预测的根据；缺省则该模型只报下步预估，不算撑满点

数据落盘与契约¶

插件在 ~/.dsh/quota/（或 dataPath 所在目录）下维护三个文件，全原子写：
- totals.json：本插件的内部账，格式为 { <sessionId>: UsageTotals }。
- history.json：每会话最近 64 步的 StepUsage[]，用于预测。
- summary.json：家族契约文件，包含 budgetTokens、contextWindow、stepsUntilFull、stepsUntilBudget 等字段。其他插件读取此文件即可获知会话状态。

测试与维护¶

该插件包含 34 个测试，覆盖纯函数（折算、定价、格式化、预测模型、契约字段）和装配层测试（真实 apply() 挂 mock ctx，真实 usage 事件驱动）。代码库遵循 MIT 许可证。

适用场景¶

适合需要精细化控制成本和上下文窗口的 DSH 用户或开发者。插件以当前 dsh 进程权限运行，安装前建议检查源码与许可证。

结尾¶

通过引入 dsh-plugin-quota，开发者可以在智能体开发中实现“模型自我监控”，避免资源浪费。更多详情与源码，请参考 GitHub 仓库。