前言¶

在 DeepSeek Harness (DSH) 生态中，智能体常需要处理格式校验、文本统计、编码转换等任务。目前通用的做法是让模型调用 shell（如 PowerShell 或 Bash）来执行 pwsh 或 jq，但这在 Windows 环境下容易受编码、引号和版本差异影响，且不可复现。

下面介绍 dsh-deterministic-tools。这是一个本地工具箱插件，向模型注册了 29 个可复现的格式与数据处理工具。它不依赖网络，不消耗凭据，每次调用都返回结构化的回执，解决了 Agent 在处理结构化数据时的不确定性和边界问题。

安装与启用¶

安装插件需要使用官方 CLI 命令。请确保 DeepSeek Harness 进程已安装且配置了 web profile。

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

安装完成后，需要重启应用。因为插件列表是在启动时加载的。

注意：不要将此插件与单独安装的组件混用，否则会重复注册同名工具。

核心功能¶

该插件提供了以下几类工具，均以 _ 开头，便于识别：

• 格式与校验：_format（格式化）、_minify（压缩）、_validate（校验）、_query（查询）、_diff（差异）。
• 文本处理：text_stats（文本统计）、lines_process（行处理）、case_convert（大小写转换）、text_diff、regex_find、regex_replace。
• 数据转换：yaml_to_、_to_yaml、csv_to_、_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。

使用示例¶

模型在对话中可以通过自然语言或工具调用指令来使用这些功能。

校验 JSON 语法
当指令要求校验 JSON 并精确到行列时，模型会调用 _validate。例如，输入 {"a":1,}，工具会返回验证结果和精确的错误位置：

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

格式化输出
使用 _format 时，可以指定缩进和排序方式。例如设置 indent: 2 和 sort_keys: true，模型可以获取格式化后的 JSON。

统一回执格式
每个工具的返回值都遵循统一规范，包含载荷和元数据：

{
  "result": "...",
  "meta": {
    "bytesIn": 15,
    "bytesOut": 45,
    "truncated": false,
    "notes": []
  }
}

设计与约束¶

• 纯本地运行：插件在本地执行，零网络请求，零凭据消耗。
• 有界性：结构化输入有硬上限，超出直接拒绝（非截断）；文本输出有软上限，超出会标记截断。
• 确定性：不依赖随机数，不依赖系统时钟。明确声明不验签。
• 验证状态：通过 tsc --noEmit 检查，无类型错误；包含 35 个测试用例。

总结¶

dsh-deterministic-tools 通过将常用的格式化、编码和检查操作转化为确定性工具，降低了 Agent 处理结构化数据的门槛。它适合需要在本地安全、快速地处理数据，且对结果的可复现性有较高要求的场景。

更多细节和源码可参考：GitHub