dsh-adaptive-max-tokens

Readme

# Adaptive Max Tokens for DeepSeek Harness

**把固定的 384K 输出预留变成动态额度，让长对话能使用原本被过量预留占住的上下文空间。**

减少“输入已经很长，仍为输出预留过大额度”导致的上下文超限。插件在后台工作，无界面，不需要额外 API Key。

Adaptive output-token budgeting for DeepSeek Harness. Adjusts request `maxTokens` to estimated remaining context, preserves usage calibration across interrupted replies and resumes, and makes one budget-only retry for recognized overflow errors. Official compaction remains enabled.

| 项目 | 说明 |
| --- | --- |
| 当前版本 | **v0.1.0**，首次独立打包发布 |
| 包名 | `dsh-adaptive-max-tokens` |
| 支持的 DSH 版本 | **`0.1.6-alpha.1`、`0.1.7-rc.2`**，按本地实际使用的版本限定 |
| 使用环境 | Web profile，提供标准 `llm`、`tokenMeter` 服务 |
| 安装方式 | GitHub 或 Release 安装包；直接运行 JavaScript，无需构建 |
| 开源协议 | [MIT](LICENSE) |

[下载 v0.1.0](https://github.com/3289192-bot/dsh-adaptive-max-tokens/releases/tag/v0.1.0) · [安装](#安装) · [兼容性依据](docs/compatibility.md) · [反馈](https://github.com/3289192-bot/dsh-adaptive-max-tokens/issues)

## 使用说明图

![Adaptive Max Tokens 使用说明：动态输出额度、收缩起点、后台流程、中断续聊与生效检查](docs/assets/usage-guide.png)

> 图示说明：**插件不会增加模型真实上下文容量，也不会修改官方压缩策略。** 583,232 是图示参数推导出的收缩起点，不是独立配置项；只有可识别且可恢复的超限错误才会缩小输出、最多重试一次。图中日志与请求字段是示意，以实际请求记录为准。

## 为什么做这个插件：究竟多出多少空间

起因是实际遇到过 **输入约 692K，却仍预留 384K 输出，导致服务端拒绝请求**。`maxTokens` 表示允许的最大输出，不代表模型一定会输出这么多；固定预留很大的值，会让输入和输出预算提前相撞。

以本地使用的 **1,000,000 上下文、384,000 最大输出**计算：

| 比较口径 | 数值 | 含义 |
| --- | ---: | --- |
| 不计安全余量的输出让位起点 | `1,000,000 − 384,000 = 616,000` | 输入超过它后，需要逐步缩小输出额度 |
| 本包实际收缩起点 | `1,000,000 − 32,768 − 384,000 = 583,232` | 提前留出安全余量 |
| 本地另行配置的压缩目标 | 约 `900,000` | 由 `compaction-instant` 的 0.9 阈值决定 |
| 达到该输入估算时的输出额度 | `67,232` | 仍可保留数万 token 输出空间 |

**忽略安全余量时，从 616K 到 900K 的动态调节区间约为 284K。** 它表示输出预算逐渐让位给输入的区间，不是模型容量变大，也不是保证额外获得 284K 输入。

还有另一种对比：本地 `0.1.7-rc.2` 的官方 basic 压缩，在默认 80% 阈值、384K 输出和 65,536 额外余量下，实际阈值为 `min(800,000, 1,000,000 − 384,000 − 65,536) = 550,464`。本地组合方案的约 900K 目标比它晚约 **349,536 token**。

**这约 350K 的阈值差来自“动态输出预算 + 配套压缩策略”共同作用。** 本插件自身不修改压缩策略；单独安装后，官方 basic 仍可能先触发压缩，不能承诺直接用到 900K。

[完整计算、当时故障与不同版本的区别](docs/budget-explained.md)

## 解决什么问题

- **输入增长时收缩输出预留。** 根据当前输入估算、上下文容量和安全余量计算 `maxTokens`。
- **压缩后恢复额度。** 重新按配置和当前模型的输出上限计算，避免一直沿用之前缩小的数值。
- **中断、续聊保持校准。** 使用已有 usage 记录辅助估算，不因一次没有 usage 的回复就丢失最近的有效校准点。
- **已知超限错误先尝试缩小输出。** 仅对能解析且有足够剩余空间的错误重试一次，其余情况交回宿主处理。
- **切换模型时遵守当前路由。** 输出额度同时受当前适配器和显式 agent 上限约束。

插件只调整输出额度，不增加模型上下文容量，不改变 reasoning effort，也不修改官方压缩阈值、摘要参数或会话历史。配套压缩插件不包含在本发行包内。

## 安装

先运行 `dsh --version`，确认使用 **`0.1.6-alpha.1` 或 `0.1.7-rc.2`**。其他版本暂未声明兼容；请在实际启动该实例的 DSH 环境中执行命令。

```sh
dsh plugin --profile web add github:3289192-bot/dsh-adaptive-max-tokens#v0.1.0
```

也可从 [Release 下载](https://github.com/3289192-bot/dsh-adaptive-max-tokens/releases/download/v0.1.0/dsh-adaptive-max-tokens-0.1.0.tgz)，替换为自己的本地路径：

```sh
dsh plugin --profile web add file:/path/to/dsh-adaptive-max-tokens-0.1.0.tgz
```

在任务空闲时重启对应 DSH Web 实例，再开始新会话。默认安装对该 profile 的 agent 请求生效。

**已经手动装过旧版的用户：** 先从自定义预设中移除或禁用原来的 `adaptive-max-tokens.mjs` 插件行，再启用本包，避免同一请求经过两份插件。无需删除旧文件。仅希望特定预设使用时，见[按预设启用](docs/configuration.md#按预设启用)。

卸载：

```sh
dsh plugin --profile web remove dsh-adaptive-max-tokens
```

在任务空闲时重启对应实例。若曾手动增加预设插件行，也需移除该行。

## 默认参数与效果

安装包沿用本地日常使用参数：

| 参数 | 值 | 含义 |
| --- | ---: | --- |
| `effectiveContextWindow` | 1,000,000 | 配置的上下文预算上限，取它与适配器声明值中的较小值 |
| `maxOutputTokens` | 384,000 | 配置的输出上限，同时受当前适配器和 agent 上限约束 |
| `safetyTokens` | 32,768 | 为估算误差保留的空间 |
| `minOutputTokens` | 16,384 | 期望最低额度，空间不足时仍会继续收缩 |
| `pendingWeight` | 1 | 待接收输入的最低估算权重 |
| `log` | `true` | 输出预算变化日志；设为 `false` 后仍保留警告 |

简化计算：`输出额度 = max(1, min(输出上限, 上下文预算 − 安全余量 − 输入估算))`。

在上下文预算 1,000,000、输出上限 384,000 时：

| 输入估算 | 本次输出额度上限 |
| ---: | ---: |
| 500,000 | 384,000 |
| 600,000 | 367,232 |
| 700,000 | 267,232 |
| 800,000 | 167,232 |
| 900,000 | 67,232 |

以上是公式示例，表示允许的最大输出长度，不代表模型一定输出这么多，也不代表已经完成这些长度的实机测试。

[修改参数与作用范围](docs/configuration.md)

## 边界与隐私

- token 用量包含估算，附件、新工具及大段新输入可能产生误差；无法保证每次请求都不会超限。
- 输入本身已经超过容量时，缩小输出也不能让它放得下，仍需官方恢复机制处理。
- 重试仅支持代码中识别的上下文超限错误格式；未知格式直接交回宿主。
- 插件读取宿主内存中的请求元数据、usage 和会话事件，用于估算；不主动联网、不写入文件、不读取凭据。
- 启用日志后会记录会话标识、路由、预算数值及错误信息，由宿主处理日志保存。分享诊断日志前请自行检查内容。
- 此仓库只包含插件、内置校准模块和说明文档，不包含私人会话、原始运行日志、密钥或本机路径配置。

兼容性来自本地已使用实例与现有运行记录；本次发布做了独立打包和静态检查，未新增真实模型请求或长上下文压力测试。详情见[兼容性说明](docs/compatibility.md)。