Skip to content
dsh marketplace

dsh-token-budget-tools

Verified

dsh-token-budget-tools · v0.2.1 · MIT

Token budget tools for DeepSeek Harness: split long text into chunks within a token budget (paragraph-aware), extract sections by heading, count estimated tokens. Estimation matches dsh-text-stats.

Install

dsh plugin add dsh-token-budget-tools

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Creators

Readme

dsh-token-budget-tools

npm version license node

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

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

估算口径与 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 项断言。

相关插件

版本历史

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