dsh-token-budget-tools

Token 预算工具插件（v0.2.0）：估算 token、按预算分块长文本、按标题提取章节。

一个面向 DeepSeek Harness (dsh) 的插件。

• 源码地址：https://github.com/geeklei/dsh-plugins/tree/main/dsh-token-budget-tools
• 发布地址（npm）：https://www.npmjs.com/package/dsh-token-budget-tools

估算口径与 dsh-text-stats 完全一致（CJK 约 0.6 token/字，ASCII 约 0.25/字符）。

功能总览

| 工具 | 用途 | 典型场景 | |------|------|----------| | count_tokens | 估算文本 token 数 | 发送给模型前预估上下文占用 | | split_text | 按 token 预算分块长文本 | 长文超上下文窗口时切块喂给模型 | | extract_section | 按 Markdown 标题提取章节 | 只处理文档中某一部分 |

零 npm 运行时依赖，安装即用。

安装

npm install dsh-token-budget-tools

或在 dsh 插件配置中声明依赖 @deepseek-ai/[email protected] 后通过插件体系加载。

工具详细说明

count_tokens

估算文本 token 数。返回估算值、字符数、CJK 占比与口径说明。text / file 二选一。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | text | string | 二选一 | 直接传入文本内容 | | file | string | 二选一 | 文件路径（必须位于工作目录内） |

示例调用：

{ "name": "count_tokens", "args": { "text": "你好，世界！Hello world!" } }

输出说明：包含估算 tokens、总字符数、CJK 字符占比，以及估算口径注释，方便判断与真实 tokenizer 的偏差。

split_text

按 token 预算分块长文本。

参数：

| 参数 | 类型 | 说明 | |------|------|------| | budget | number | 每块预算（50–100000，默认 3000），过小自动钳制到下限 | | overlap | number | 重叠窗口 token 数（0–1000，默认 0，v0.2.0 新增），每块开头附加前一块尾部对应 token 量的文本，保持上下文连贯；自动 clamp 到 budget - 1 | | text / file | string | 源内容二选一 |

分块策略（逐级降级）：优先按段落（空行）边界 → 段落超预算退化按行 → 行超预算按句（。！？.!?）→ 无标点硬切。保证每块估算不超过预算（硬切留 1 token 头寸抵消浮点误差）。

单次最多返回 200 块，超过则提示调大 budget。输出为带编号的分块预览（每块标注估算 tokens + 前 60 字符预览）。

示例调用：

{
  "name": "split_text",
  "args": { "text": "<很长的文档>", "budget": 2000, "overlap": 100 }
}

使用建议：

• budget 建议留出回答所需的上下文余量，例如模型窗口 8k 时用 4000–6000
• 需要跨块语义连续（如翻译、摘要续写）时开启 overlap，一般 50–200 即可
• 返回结果超过 200 块时优先调大 budget，而不是分次重复切块

extract_section

从 Markdown 中按标题提取章节。

两种模式：

• 不带 title：返回全部标题目录（含层级缩进），用于先概览再定位
• 带 title：提取该标题到下一个同级/更高级标题之间的正文，附 token 估算与行号范围

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | title | string | 否 | 标题模糊匹配（包含即命中，大小写不敏感） | | level | number | 否 | 限定标题级别（1–6），用于目录过滤或精确提取 |

代码块内的 # 不计为标题，不会误判。

示例调用：

{ "name": "extract_section", "args": { "file": "docs/spec.md" } }
{ "name": "extract_section", "args": { "file": "docs/spec.md", "title": "安装", "level": 2 } }

典型工作流

处理一份超长 Markdown 文档的标准流程：

1. extract_section 不带 title，获取标题目录，了解文档结构
2. extract_section 带 title，提取目标章节（附带 token 估算，判断是否还需切块）
3. 章节过长时，count_tokens 确认总量 → split_text 按预算切块（可加 overlap）
4. 将各分块按顺序喂给模型处理

extract_section(file)          → 目录
extract_section(file, title)   → 章节正文 + token 估算
split_text(章节, budget=3000)  → 分块列表
逐块调用模型                    → 汇总结果

兼容性

• 依赖 @deepseek-ai/[email protected]（peer，安装时自动带上）
• Node.js ≥ 18（ESM）
• 零 npm 运行时依赖

限制

• 单次输入上限 50 万字符
• 文件路径必须在工作目录内
• token 估算为内置启发式（非真实 tokenizer），与真实 tokenizer 存在偏差，适合做预算规划而非精确计费

测试

npm test

覆盖估算口径、段落/行/句/硬切四级降级、预算钳制、重叠窗口、块数上限、标题目录、章节提取边界（不含同级/上级内容）、代码块跳过、路径越界等 31 项断言。

相关插件

• dsh-text-stats：文本统计（字数、行数、编码信息），本插件估算口径与其一致
• 更多插件见 dsh-plugins 仓库

版本历史

0.2.0（2026-09-13）

• split_text overlap 重叠窗口真实实现：每块开头附加前一块尾部对应 token 量的文本，est 同步更新，上限自动 clamp 到 budget-1

0.1.0

• 首个版本：count_tokens / split_text / extract_section 三大工具

Roadmap（v0.3 候选）

• 真实 tokenizer 可选接入（tiktoken，可插拔）
• 按 Markdown 标题层级智能切分
• 全局 token 预算看板（多文件汇总）

License

MIT