dsh-context-toolkit

dsh plugin --profile web add dsh-context-toolkit

上下文工具箱（dsh-context-toolkit）

简体中文 | [English](./README.md) | [更新说明](./CHANGELOG.zh.md)

一个给 DeepSeek Harness 用的插件：让大块输出不进对话。

它的做法是把"原始字节"和"结论"分开——命令在子进程里跑、文件在沙箱里分析、网页与长材料归档进本地知识库，对话里只留下结论、片段和计数。另有一道路由门禁，在工具调用前挡掉那些注定会灌满对话的操作。

零第三方运行时依赖：知识库用 Node 自带的 node:sqlite（含 FTS5），跑码用系统已有的解释器，安装后不需要再拉任何包。

它有什么用

问题 · 这个插件的做法

跑个命令，输出几千行，只想知道"有几个" · ctk_execute 在子进程里跑，只把结论带回来

读大文件做统计，不想把全文塞进上下文 · ctk_execute_file 让文件留在沙箱里

一次要问很多条命令 · ctk_batch_execute 一条调用跑完，逐条报状态

网页/长文档看完就废，下次还要重看 · ctk_index 归档，ctk_search 按需取片段

curl / wget 直接把整页灌进对话 · 路由门禁硬拦，并给出替代方案

不知道到底省了多少 · ctk_stats 报台账；设置页有实时占用面板

工具

工具 · 用途

ctk_execute · 在沙箱子进程里跑代码（javascript / esm / typescript / shell），只回结论

ctk_execute_file · 对某个文件跑代码做统计或抽取，文件原文不出沙箱

ctk_batch_execute · 一次跑多条命令，逐条状态，输出只有结论

ctk_index · 把文本或文件存进本地 FTS5 知识库

ctk_search · 多查询检索知识库，返回围绕命中词的片段

ctk_retrieve · 取回被瘦身压缩掉的原文（逐字节，按 [ctk_retrieve id=…] 标记的 id）

ctk_retrieve · 取回被瘦身压缩掉的原文（逐字节，按 [ctk_retrieve id=…] 标记的 id）

ctk_fetch_and_index · 抓网页 → 去标签转文本 → 直接入库

ctk_purge · 删除已归档内容（必须 confirm: true）

ctk_stats · 节约台账：拦截次数、沙箱保留字节、归档字节、调用计数

ctk_doctor · 自检：解释器能否真启动、临时目录可写、知识库能否往返

ctk_context_report · 当前会话的上下文占用与构成

安装

从 npm 安装（推荐）：

dsh plugin --profile desktop add dsh-context-toolkit

从 GitHub 安装：

dsh plugin --profile desktop add github:chimneyQ/dsh-context-toolkit

本地 checkout 时可直接指定目录：

dsh plugin --profile desktop add D:\path\to\dsh-context-toolkit

装完确认 <DSH_HOME>/profiles/desktop/package.json 的 dsh.profile.bundles 里出现 dsh-context-toolkit。

卸载：

dsh plugin --profile desktop remove dsh-context-toolkit

怎么用更划算

**默认就该走 ctk_***。尤其是要分析、计数、过滤、看摘要的场合——直接把输出读进对话是这套插件要解决的原始问题。

// 想知道一个大目录里有多少 .log 文件、总共多大
await ctk_execute({
  language: 'javascript',
  code: `
    const fs = require('fs');
    const dir = process.argv[2];
    let n = 0, bytes = 0;
    for (const f of fs.readdirSync(dir)) {
      if (!f.endsWith('.log')) continue;
      n++; bytes += fs.statSync(dir + '/' + f).size;
    }
    console.log(n + ' files, ' + bytes + ' bytes');
  `
});

长材料先归档，之后按需取：

await ctk_index({ path: 'D:/specs/api.md' });          // 全文留在库里
await ctk_search({ queries: ['rate limit', 'auth'] });  // 只取相关片段

代理拦截网络下的 TLS

如果每次 ctk_fetch_and_index 都失败于 UNABLE_TO_VERIFY_LEAF_SIGNATURE，说明本机处在 TLS 中间人检查

的环境里，Node 内置根证书无法验证代理出示的证书链。caPemPath 用来指定一份要信任的 PEM。

auto（默认）指向 <DSH_HOME>/context-mode/ca/windows-roots.pem。本包不附带这个文件 —— 它是

本机自己根证书库的一份快照，所以在全新机器上它根本不存在，抓取会退回 Node 默认根证书。

设置 → 上下文工具箱，caPemPath 下方有一行：

• 一个徽标，显示该文件是否存在（以及大小）—— 打开页面时只做一次 stat，不会为了渲染页面去读整份证书包；
• 一个按钮，按下时才从系统根证书库（tls.getCACertificates('system')，约 500 张证书、约 820 KB）写出它。

已存在的证书包不会被一次点击覆盖：首次点击只是询问，只有明确确认才会覆盖。

这个按钮不做什么： 它导出的是系统证书库。若代理的根证书从未被装进该系统库（例如 IT 通过组策略推送），

导出的包仍然无法验证该代理。请先安装根证书，再导出。

配置

键 · 默认 · 含义

routing · true · 路由门禁总开关

denyCurlWget · true · 硬拦 curl / wget

bashNudgeMinCommandBytes · 4096 · 超长命令的引导阈值（0 = 关闭）

maxReadBytesBeforeAsk · 51200 · 大文件整读的引导阈值（0 = 关闭）

nudgeFetchTools · true · 把宿主取网页工具（web_fetch / read_page）也纳入整页引导

trustedReadBasenames · package.json 等 · 不受整读门禁限制的文件名

compressNudgeTokens · 120000 · 占用提示阈值（tokens）

searchLimit · 5 · ctk_search 每次查询的片段数上限

snippetChars · 900 · 每个片段的字符上限

fetchMaxBytes · 2000000 · 单页抓取上限

caPemPath · auto · ctk_fetch_and_index 的 TLS 信任链：auto = <DSH_HOME>/context-mode/ca/windows-roots.pem；也可填 PEM 绝对路径；留空 = Node 默认根证书。企业代理拦截 HTTPS 导致每次抓取都报证书错误时配它。

storageDir · 空 · 知识库根目录，空 = <DSH_HOME>/context-toolkit

tools.* · 见下 · 逐个工具的开关

工具开关：tools.execute、tools.executeFile、tools.batchExecute、tools.index、tools.search、tools.fetchAndIndex、tools.purge、tools.stats、tools.contextReport、tools.doctor，默认全部开启。

校验

离线套件不依赖 DSH 运行时：

node smoke.mjs        # 104 项：契约、运行时探测、工具、门禁（分段匹配 + 路径基准对齐 + script_path 与取网页工具覆盖）、输出瘦身与可逆取回及保留期、证书包存在性与导出、资源释放、知识库、观测、版本自述
node test-client.mjs  # 27 项：浏览器半体契约与双语字典一致性
node test-package.mjs # 20 项：发布清单与零依赖约束
node release-check.mjs # 34 项：发布就绪（清单/依赖/工具数/门禁匹配/版本/SHA 覆盖/无硬编码路径）

输出瘦身（工具执行后）

门禁在入口拦下次就会灌满对话的调用；瘦身则处理已经进来的输出——两者抓的是不同流量：门禁只能看调用的参数，瘦身看的是真实回来的字节（来自门禁不认识的工具、它没覆盖的入口，或本来就无法从调用预判的输出）。

在 tools/post-execute 处按形态选择策略：

形态 · 做法

同构 JSON 数组 · 无损表化重编码：键只写一次，信息零损失

表格 · 保留表头 + 首尾，中段按原始行号步进采样（模型拿到的是带坐标的地图）

grep/search · 按文件折叠，每文件保留前若干命中

日志 · 折叠普通行，诊断行逐字保留

长散文 · 头尾窗口 + 显式省略标记

代码 / 键值对 · 不压（模型可能正要按精确字节编辑）

双重门：候选必须同时满足「字节 ≤ 72%」且「估算 token 严格下降」，否则放弃——压不动就不压，台账绝不虚报节省。

可逆红线：任何有损路径先把原文逐字节存好并注入 [ctk_retrieve id=…] 标记，用 ctk_retrieve 取回。原文与 FTS5 索引同在同一个数据库（一个文件两个职责：FTS5 找段落，blob 逐字节还原）。

• 原文保留期：slimOriginalTtlMinutes（默认 1440 = 一天，0 = 永久）由插件在每次加载时执行一次清理；标记投递失败时按 id 精确回滚，不会牵连其他原文。

已知边界

• 出站抓取受本机网络影响：若本机把域名解析到回环地址，ctk_fetch_and_index 会失败并明确说明原因（而不是只报 "fetch failed"）；此时改用 ctk_index 归档本地材料。
• ctk_execute 的超时是硬杀：超时会终止子进程并把 timedOut 标出来。
• 单次捕获上限 256 KB，超出部分只计数不保留；回给对话的文本另有 4000 字符硬帽，因此 1 MB 的单行输出也不会整段进入上下文。
• 知识库按路径去重：同一路径再次归档是替换，不是追加。
• 已被上游截断的输出不再压缩：上游工具自行截断并落盘的产物（[output truncated; full output: …]）与沙箱捕获上限的收尾（独立的 ~~~ 行）都视为已完成的工作，本层跳过并在台账「跳过原因」中计数。
• 门禁精确而非穷尽：只有当洪水工具是某个分段的「命令词」时才拒绝（会先剥掉 sudo/exec 等前缀、归一化路径与 .exe 等扩展名），script_path 最多读取前 256 KB。程序内部发起的调用（如 python -c 'import wget'）不在其职责内。
• 路径基准与宿主一致：门禁读取 script_path 与 read 的 file_path 时，按会话工作目录解析相对路径（与宿主实际打开文件的基准相同）；否则「宿主能跑、门禁看不见」就是一条现成的绕过路径。

许可

MIT