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

简体中文 | English | 更新说明

一个给 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