确定性工具箱 ax2/dsh-deterministic-tools

dsh-deterministic-tools

确定性、离线、有界的本地工具箱 —— 一个 DeepSeek Harness 插件，向模型注册 29 个可复现的格式/数据/文本/编码/检查工具。

MIT License · DSH 0.2.0-rc.2 验证通过 · Node ≥ 20.10

纯本地 · 零网络 · 零凭据 · 无时钟无随机 · 每次调用都带字节回执

快速开始

dsh plugin --profile web add dsh-deterministic-tools

装完重启应用（bundle 列表是启动时读的）。想一次装齐四个插件（含 jvm-doctor / py-doctor / win-native）用 @ax2zicode/dsh-dev-toolbox；别和单独安装混用（会重复注册同名工具）。

家族总览：zicode.com/software 是四个插件、合装包与桌面软件的统一入口。

15 秒看效果 —— 说「校验 {"a":1,}，要精确行列」，模型调用 json_validate，拿回（实测输出）：

{ "valid": false,
"error": { "message": "expected a double-quoted property name but found '}'", "line": 1, "column": 9, "position": 8 },
"top_level_type": "unknown" }

为什么不让模型自己写 pwsh？ 实测里它确实写得出（ConvertFrom-Json 也能报错），但：
- 一次就对：固定实现 + 35 个测试，而不是每次和引号、编码、PowerShell 版本搏斗；
- 边界明确：结构化输入超预算拒绝（INPUT_TOO_LARGE），文本截断按 code point 并标 truncated；
- 可组合：{ result, meta } 回执直接进下一步，不用模型解析自由文本。

相邻插件：dsh-jvm-doctor（JVM 生产报告）· dsh-py-doctor（Python/Django）· dsh-win-native（Windows 编码/路径/netstat）· dsh-dev-toolbox（一条命令装齐，共 46 个工具）

为什么需要它

智能体在需要「把这段 JSON 格式化」「这段文本里有什么不可见字符」「这个 CIDR 覆盖哪些地址」「这个 base64 解出来是不是 UTF-8」时，目前只能：

1. 调用 pwsh / bash 硬凑 —— Windows 上引号、GBK/UTF-16 编码、控制台代码页全是坑，一次失败要烧掉好几轮 token；
2. 或者在回答里心算 —— 不可复现，也无法验证。

而生态里的供给几乎为空：收录的 4,508 个 DSH 插件条目里，正则类全网只有 2 个包、编码类 1 个包，没有任何「确定性工具箱」形态的插件；官方 profile 自带的 200+ 个 @deepseek-ai/ 包里也只有文件、终端、搜索这类能力，没有格式与数据处理。

本项目把这些操作变成模型可见的工具：结构化入参、结构化出参、有界、可复现。

设计契约：每个结果都是回执

每个工具的规范返回值固定为：

{
"result": "…工具自己的载荷…",
"meta": {
"bytesIn": 15,
"bytesOut": 45,
"truncated": false,
"notes": []
}
}

模型看到的内容就是 result（字符串直接给，对象/数组给格式化 JSON），只有当发生截断或需要解释时才会追加一行页脚：

[bounded] input=262144B output=262144B
[note] object keys sorted recursively

干净的调用不花额外 token；有问题的调用一定说清楚。

边界行为（三种，绝不混淆）

| 情况 | 行为 |
| 结构化输入超预算 | 抛错拒绝：报出实际字节、上限，并明确「没有任何截断或部分处理」 |
| 文本输出超预算 | 截断 + truncated: true + note，截断发生在 code point 边界 |
| 结构化/编码结果超预算 | 整体返回 + 标记：规范值无法部分裁剪，就明确说出来而不是悄悄弄坏它 |
| 不支持的语法/选项 | 显式拒绝并列出允许值（不猜、不降级、不静默忽略） |
| 无法保证最小/精确 | 返回诚实标记（如 text_diff 的 coarse: true、解析器的 unknown_lines/confidence） |

安装

npm（推荐）：

dsh plugin --profile web add dsh-deterministic-tools

预构建 tarball（与 npm 上是同一份产物，无需构建步骤，也避开 pnpm 的 allowBuilds 授权）：

dsh plugin --profile web add https://github.com/ax2/dsh-deterministic-tools/releases/latest/download/dsh-deterministic-tools.tgz

要固定版本就把 latest/download/dsh-deterministic-tools.tgz 换成 download/v<version>/dsh-deterministic-tools-<version>.tgz。

本地开发：不安装，直接挂载构建产物。

pnpm install && pnpm build
dsh --profile web --patch ./cordis.local-overlay.yml --dump-config # 先验证层合成
dsh --profile web --patch ./cordis.local-overlay.yml # 再启动

cordis.local-overlay.yml（仓库内已提供，等价的 patch 也可手写）：

- insert:
- id: deterministic-tools-local
name: 'D:/dsh/dsh-deterministic-tools/lib/index.js'

配置

apply(ctx, config) 接受以下配置（全部可选，含默认值）：

| 字段 | 默认 | 作用 |
| maxInputBytes | 262144 | 结构化输入的硬上限（UTF-8 字节），超过即拒绝 |
| maxOutputBytes | 262144 | 结果渲染的软上限，超过即截断或标记 |
| maxMatches | 1000 | 查询/正则返回的匹配数上限 |
| maxDiffEntries | 2000 | diff 报告的差异条数上限 |
| maxPatternChars | 1000 | 正则表达式长度上限 |
| regexInputBytes | 65536 | 正则堆栈上限（JS 回溯无法抢占，所以单独收紧） |
| maxRecords | 20000 | CSV 解析/生成的记录数上限 |
| toolPrefix | '' | 工具名前缀，例如 zidev → zidev__json_format |
| only | [] | 只注册指定工具（空 = 全部） |

工具清单（29 个）

JSON（5）

| 工具 | 说明 |
| json_format | 严格解析 + 固定缩进 + 可选递归键排序 |
| json_minify | 压成单行 |
| json_validate | 校验并给出精确的 line / column / position（自带扫描器，不依赖引擎错误文案）；语法错误是成功结果，不是异常 |
| json_query | 受限 JSONPath：$、.a、['a']、[0]、[]、..a，返回规范化路径 |
| json_diff | 结构化差异（JSON Pointer + add/remove/replace），标量数组可按多重集比较 |

文本（6）

| 工具 | 说明 |
| text_stats | 字节 / UTF-16 / code point / 行 / 词 / CJK / 非 ASCII / EOL 风格 |
| lines_process | dedupe、trim、drop_empty、compact、sort、sort_desc、reverse、number；保留输入的结尾换行、报告输入 EOL 风格（输出统一 LF） |
| case_convert | camel / pascal / snake / upper_snake / kebab / dot / title / lower / upper |
| text_diff | 行级统一格式 hunk（带行号）；超出 LCS 单元格预算时降级并标 coarse: true |
| regex_find | 编号/命名捕获组、字符偏移、1-based 行号，匹配数有界 |
| regex_replace | $1 / $<name> / $$ / $& 替换，替换次数有界 |

数据（4）

| 工具 | 说明 |
| yaml_to_json | YAML → JSON；报出精确行列；限制 anchor/alias 展开（防 billion laughs） |
| json_to_yaml | JSON → YAML，固定缩进、可选键排序 |
| csv_to_json | RFC 4180（引号、字段内换行）、分隔符自动探测、ragged 行统计 |
| json_to_csv | 对象/数组数组 → CSV，列顺序取键的首次出现顺序或显式指定 |

编码（8）

| 工具 | 说明 |
| base64_encode / base64_decode | 标准与 URL-safe 字母表；解码前先校验字母表和 padding；非法 UTF-8 明确上报 |
| hex_encode / hex_decode | 可选大小写与分隔符；容忍 :/-/,/空白 |
| url_encode / url_decode | component / form / path / full 四种模式；畸形 % 序列计数上报；孤立代理项（unpaired surrogate）显式拒绝并给出下标 |
| url_inspect | 拆解 scheme/host/port/path/query/fragment + 解码参数 + 风险提示（内嵌凭据、明文 HTTP、IDN） |
| hash_text | sha256 / sha512 / sha1 / md5，hex 或 base64，支持 base64 二进制输入 |

检查（6）

| 工具 | 说明 |
| unicode_inspect | 逐 code point：U+XXXX、UTF-8 字节、类别、文字系统、显示宽度、标志（控制/不可见/bidi/同形字混淆）；支持 NFC/NFD/NFKC/NFKD 对比 |
| number_base | 2–36 进制精确互转（BigInt），支持 0x/0b/0o 前缀，越界数字拒绝 |
| color_convert | #rgb/#rrggbb/#rrggbbaa/rgb()/hsl() → hex/RGB/HSL/HSV + 相对亮度 + WCAG 对比度 |
| cidr_inspect | IPv4/IPv6 网段：网络地址、掩码、广播、首末地址、地址总数、可用主机数、私有/回环/链路本地/CGNAT/组播/ULA 分类 |
| jwt_inspect | 解出 header/payload/alg/kid/签名字节数/exp/iat/nbf，判断是否过期 —— 明确声明不验签 |
| timestamp_convert | epoch（s/ms/µs/ns 或按量级自动）与 ISO 8601 互转，含偏移渲染、星期、闰年、分解 |

开发

pnpm install
pnpm typecheck # tsc --noEmit，0 错误
node --test test/ # 35 个用例，覆盖全部 29 个工具的组装路径
pnpm build # 产出 lib/（ESM + .d.ts，导入已改写为 .js）
pnpm smoke # 用 lib/ 产物 + stub registry 验证 29 个工具全部注册

测试分三类：

1. 组装路径：definition.execute(args, exec) → definition.output.render()，断言 result / meta / 页脚；
2. 契约：每个工具的 schema、描述长度、注册表参数校验（非法 enum 由 registry 在 execute 之前拒绝）；
3. 性质测试（test/properties.test.ts，固定种子可复现）：自写 JSON 扫描器与 JSON.parse 的差分对照（400 组含随机变异的语料）、格式化的幂等性与值保持、base64/hex/百分号编码/CSV/进制/时间戳的往返、行操作幂等性。

这组性质测试在 v0.1 期间抓到过一个真实缺陷：lines_process 会丢掉输入结尾的换行（"a\nb\n" → "a\nb"）。现在它的结果里带 trailing_newline 与 eol_in，输出忠实复现结尾换行，跨平台换行会说清「输出统一为 LF」。

兼容性与风险

- 官方插件 API 自称 pre-stable，无冻结承诺；本插件只依赖最稳定的两个面：ctx.tools.register(defineTool(...)) 与 apply(ctx, config)。
- 验证到什么程度（不夸大）：tsc --noEmit 0 错误；35 个用例在真实 @deepseek-ai/dsh-tools 上跑通组装路径（含 registry 的参数校验）；lib/ 产物被 scripts/smoke-built.mjs 加载并注册全部 29 个工具；dsh --profile web --patch ./cordis.local-overlay.yml --dump-config 在 dsh 0.2.0-rc.2 上合成成功；npm 上的版本用 dsh plugin --profile <scratch> add 装进一个临时 profile 后，真实 dsh 启动把包括本包 29 个在内的全部工具 schema 发给了模型（会话日志里逐个核对过）。真实对话也跑通了：同一个临时 profile 接上本机 desktop profile 用的那条 LLM 路由（tencent-token-plan）后，模型在一个真实回合里主动调用了 json_format（indent: 2、sort_keys: true），拿回递归排序后的 JSON 与 [note] 页脚并原样复述（会话 session-0a4eb911）。尚未做：跨多个真实会话的调用统计（这属于 M3）。
- 正则工具无法中断 JS 回溯 ⇒ 用 regexInputBytes（默认 64 KiB）与 maxPatternChars 把风险框住，并在描述里写明。
- text_diff 的精确匹配有单元格预算，超出会给出 coarse: true，不假装最小差异。

Roadmap

1. Rust/WASM 核心：把 zi-devtools 的 zi-json-core / zi-text-core / zi-regex-core / zi-diff-core 编到 wasm32-unknown-unknown，用 Node 内置 WebAssembly 加载，把逐字节对照向量（121/174/174 组）直接变成 golden tests。
2. 更多工具：JSON Schema 子集校验、cron 表达式解析、SQL 格式化/参数提取、TOML/INI、JWT 签名校验（需显式密钥入参）、tar/zip 清单读取。
3. output.presentCall/presentResult 卡片化，让 Web UI 展示 diff/表格而不是纯文本。

License

MIT © ax2

Deterministic, offline, bounded local toolbox for DeepSeek Harness — 29 model-visible tools for JSON, YAML/CSV, text, encodings, hashes and inspection.

- Pure and reproducible: no network, no credentials, no filesystem, no clock, no randomness.
- 每次调用都返回回执：{ result, meta: { bytesIn, bytesOut, truncated, notes } }。模型看到的文本就是 result；只有内容被截断或需要说明时，才会出现页脚。
- 显式失败，绝不静默降级：结构化输入超出预算时直接拒绝，同时给出两个大小，并保证没有做任何部分处理；文本输出在码点边界处截断并标记；无法截断的值整体返回并打上标记；不支持的语法直接拒绝，并列出允许的集合；非最小化的结果带上诚实的标记（coarse、unknown_lines、confidence）。
- 安装：dsh plugin --profile web add dsh-deterministic-tools，或者用 dsh --profile web --patch ./cordis.local-overlay.yml 在本地挂载构建产物入口。
- 已针对 DSH 0.2.0-rc.2 验证；只用到 ctx.tools.register(defineTool(...)) 和 apply(ctx, config)，因为官方插件 API 明确处于 pre-stable 阶段。

工具：json_format json_minify json_validate json_query json_diff text_stats lines_process case_convert text_diff regex_find regex_replace yaml_to_json json_to_yaml csv_to_json json_to_csv base64_encode base64_decode hex_encode hex_decode url_encode url_decode url_inspect hash_text unicode_inspect number_base color_convert cidr_inspect jwt_inspect timestamp_convert。