dsh-token-budget-tools

Token 预算工具插件（v0.3.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 标题提取章节	只处理文档中某一部分
split_by_headings	按标题层级把文档切成若干节	先按章节拆，再对超长章节按 token 细分
budget_overview	多文件 token 预算看板	盘点一批文档的上下文占用，找出最占预算的文件

零 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 } }

split_by_headings

按 Markdown 标题层级把文档切成若干节：level 及更高级别的标题都作为切分点，因此 H2 不会脱离所属 H1 被重复计入，每节保留自己的标题行。

参数	类型	必填	说明
level	number	否	切分级别（1–6，默认 2）；level 及更高级别的标题都是切分点
budget	number	否	单节 token 预算，用于标出超预算的节（不改变切分结果）
text / file	string	二选一	源内容

输出每节的标题、行号范围、估算 token 与占比；传 budget 时超预算节标注 ⚠ 并给出汇总提示。文档没有标题时退化为单节 (全文)；首个标题之前的正文作为 (前言) 节。

按标题切分完成: 共 3 节（切分级别 ≤ H2，合计 ~404 tokens），单节预算 150 tokens
1. [H1] 总览 | 第 1~3 行 | ~2 tokens (0.5%)
2. [H2] 安装 | 第 4~9 行 | ~100 tokens (24.8%)
3. [H2] 使用 | 第 10~11 行 | ~300 tokens (74.3%)  ⚠ 超预算

提示: 1 节超出预算 150 tokens，可对超预算节调用 split_text（先 extract_section 取出该节内容）继续按 token 切块。

budget_overview

汇总多个文件的估算 token，按占用从大到小排列，并给出总预算占用比例与最占预算的文件。

参数	类型	必填	说明
files	string	是	文件路径列表（工作目录内，逗号或换行分隔，最多 50 个）
budget	number	否	总 token 预算，用于计算占用比例与超出量

不存在的路径会跳过并在结果末尾列出；全部不可读时报错。

Token 预算看板: 2 个文件，合计 ~102 tokens / 408 字符
总预算 50 tokens → 占用 204.0%（超出 52 tokens）
1. b1.md | ~76 tokens (74.5%) | 304 字符
2. b2.md | ~26 tokens (25.5%) | 104 字符
最大占用: b1.md（~76 tokens，占 74.5%）

典型工作流

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

1. split_by_headings 一次看清全文各节的 token 分布，定位超预算的节
2. 需要细节时用 extract_section 带 title 提取目标章节
3. 章节过长时，count_tokens 确认总量 → split_text 按预算切块（可加 overlap）
4. 将各分块按顺序喂给模型处理
5. 处理多份文档前，用 budget_overview 盘点整体占用，决定处理顺序

split_by_headings(file, level=2, budget=3000) → 各节 token 分布 + 超预算标注
extract_section(file, title)   → 章节正文 + token 估算
split_text(章节, budget=3000)  → 分块列表
budget_overview(files, budget) → 多文件占用看板
逐块调用模型                    → 汇总结果

兼容性

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

限制

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

测试

npm test

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

相关插件

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

版本历史

0.3.0（2026-09-30）

• 新增 split_by_headings 工具：按 Markdown 标题层级切分，level 及更高级别标题为切分点，输出每节行号范围、估算 token 与占比，支持 budget 标注超预算节
• 新增 budget_overview 工具：多文件（最多 50 个）token 预算看板，按占用降序排列，给出总预算占用比例、超出量与最大占用文件，不可读路径跳过并提示
• 测试断言 31 → 54

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.4 候选）

• 真实 tokenizer 可选接入（tiktoken，可插拔）
• 目录级预算看板（传目录自动展开 Markdown 文件）
• 与 dsh-text-stats 统一估算口径与入口

安全边界

• 只读：不写任何文件；file / files 参数只读取工作目录内的文件，路径越界会被拒绝。
• 估算非精确：token 数为估算值，预算控制请留安全余量。
• 切分不丢内容：split_text 的重叠窗口设计保证相邻片段在边界处有重叠，降低"关键信息正好被切断"的风险。
• 标题切分依赖结构：extract_section 按 Markdown 标题切分，非结构化文本可能只得到整体一段。

FAQ

Q：切分会不会把内容切丢？ 不会。split_text 支持重叠窗口（overlap），相邻片段在边界处重复一部分内容，避免关键信息落在切点上。

Q：tailTokens 是什么？ 按目标 token 数从尾部反推应保留的文本长度，用于"保留最近 N token 上下文"的场景。

Q：估算值和实际计费差多少？ 取决于文本类型，通常同量级但非精确值。预算敏感场景建议留 10%~20% 余量。

Q：能按章节切分吗？ 可以，extract_section 按 Markdown 标题结构提取指定章节。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-token-budget-tools
• npm：https://www.npmjs.com/package/dsh-token-budget-tools

License

MIT