前言¶
在 DeepSeek Harness（DSH）里做智能体或工作流时，常见需求是：把 JSON、日志、堆栈、路径这类输入交给模型处理，并希望得到稳定、可复用的结构化结果。模型往往可以临时写脚本完成单次任务，但输出格式、边界行为（超大数据、截断、覆盖率）每次不一定一致，token 与步骤数也会波动。
dsh-zidev-toolbox 是维护者 ax2 发布的工作流类插件合装包：用一条安装命令，在 DSH 中注册四个独立插件、共 46 个工具，覆盖格式处理与 JVM、Python、Windows 侧的生产诊断。工具纯本地运行，无网络、无安装期脚本、无二进制依赖；实现带 214 个通过的测试，许可证为 MIT。
这是什么¶
dsh-zidev-toolbox（npm 包名 dsh-zidev-toolbox，当前资料中版本 0.1.0）本身不是 46 个工具的实现体，而是四个 DSH 插件的合装层：安装时通过 cordis.patch.yml 一次插入四行 bundle，四个插件仍各自独立版本。四个子插件分别对应 ax2 的 zi-devtools 工具箱在 DSH 上的 TypeScript 实现，契约包括统一回执信封、预算门禁与边界行为。
合装后不要与单独安装的那四个 npm 插件混用，否则会重复注册同名工具。
核心功能：四个插件与 46 个工具¶
下面按 README 中的划分说明各包职责（工具数量与测试数以资料为准）。
dsh-deterministic-tools（29 个工具，35 个测试）¶
面向 JSON/YAML/CSV/文本/编码/正则等「格式活」，例如：JSON 校验（精确行列偏移）、受限 JSONPath、结构化 diff、CSV↔JSON、YAML↔JSON、文本统计、正则捕获、base64/hex/URL 编解码、哈希，以及 Unicode、进制、颜色、CIDR、JWT、时间戳检查等。
dsh-jvm-doctor（5 个工具，47 个测试）¶
面向 JVM 诊断：thread dump（含 Java 级死锁环）、GC 日志、Maven/Gradle 依赖冲突、异常链（... N more 还原）、Spring 配置 diff（载荷前脱敏）。
dsh-py-doctor（6 个工具，75 个测试）¶
面向 Python 诊断：traceback 根因、pytest 摘要、Django migrations/N+1/checks、celery 报告；解析结果带覆盖率信息。
dsh-win-native（6 个工具，57 个测试）¶
面向 Windows 环境：编码检测与转换（GBK/Big5/Shift-JIS 置信度）、Windows 路径合法性、netstat 解读、只读磁盘巡检与重复文件查找。
设计要点（相对「让模型现场算」）¶
资料中强调的价值不在「模型算不出来」，而在于：固定实现提高一次做对的概率；同样输入同样输出；超预算拒绝（INPUT_TOO_LARGE），文本截断按 code point 并标注 truncated，解析覆盖率与未识别行明确上报；部分工具声明能力边界（例如 jwt_inspect 不验签、netstat_parse 不编造文本中不存在的进程名与 UDP 状态）；回执为 { result, meta } 结构，便于后续步骤消费。
46 个工具里仅 dir_usage、file_duplicates 会只读访问磁盘（有文件数/字节预算，软链接与 junction 跳过并上报，不跟随符号链接）；其余均为纯文本/纯字节分析，不提供数据则不会自行读取。不发网络请求、不装二进制、不写安装期脚本。
安装与启用¶
Node 引擎要求为 >=20.10（来自 package.json）。
Web 配置档安装：
dsh plugin --profile web add dsh-zidev-toolbox
装完后重启应用（bundle 列表在启动时读取）。桌面版将 web 换成 desktop：
dsh plugin --profile desktop add dsh-zidev-toolbox
离线或固定版本时，可使用 Release 预构建 tarball（资料中的示例为 latest）：
dsh plugin --profile web add https://github.com/ax2/dsh-zidev-toolbox/releases/latest/download/dsh-zidev-toolbox.tgz
四个子插件也可各自从 GitHub releases/latest/download/<repo>.tgz 单独安装；与合装包二选一，避免重复注册。
Token 与工具裁剪¶
工具 schema 随每次请求发送，安装后即使不用也会占用 input token。README 实测：干净 headless base 约 75 个工具名、首次约 11,931 inputTokens；加上这四个插件后约 121 个工具名、首次约 19,608 inputTokens（+7,677）。一次性小任务可能总 token 反而高于模型自写脚本；更适合输入大、输出小、或需要稳定解析与边界语义的场景。
若只需常用子集，可在 profile 中按插件 id 覆盖，例如只保留 deterministic-tools 中 5 个工具（资料示例）：
# profiles/<name>/cordis.patch.yml
- id: deterministic-tools
config:
only: [json_format, json_validate, json_query, text_diff, csv_to_json]
toolPrefix: zi
典型用法¶
安装并重启后，在对话中粘贴问题或日志片段，由模型选择合适的工具调用。README 给出若干可对照的预期行为。
Python traceback¶
输入示例：
Traceback (most recent call last):
File "svc.py", line 42, in handle
KeyError: 'user_id'
模型可调用 python_traceback，得到结构化字段（资料实测输出包括 exception_type、exception_message、deepest_frame、cause_hints、coverage 等）。
其他常见说法与工具对应¶
| 你说 | 它调用 | 你拿到 |
|---|---|---|
校验 {"a":1,}，要精确行列 |
json_validate |
line/column/position + 错误文案 |
C:\temp\CON.txt 这个路径能用吗 |
path_inspect |
如 reserved_name（error）及位置信息 |
| 贴上 jstack，有没有死锁 | java_thread_dump |
死锁环、锁竞争队列、状态直方图等 |
| 这是 GC 日志，p99 停顿多少 | java_gc_log |
停顿分位数、Young/Full 拆分等 |
netstat -ano 里谁在监听 8080 |
netstat_parse |
监听项与 PID/进程名（文本中没有的不编造） |
| D 盘哪个目录最占空间 | dir_usage |
总字节、最大文件、扩展名直方图（只读） |
适用场景与注意¶
适合：需要在 DSH 工作流中稳定处理 JSON/YAML/CSV/编码/正则；解析 JVM thread dump、GC 日志、构建依赖冲突；Python traceback、pytest、Django、celery 报告；Windows 路径、netstat、编码与磁盘只读巡检；且希望结果可复现、边界明确。
注意：
- 插件在当前 dsh 进程权限下运行；安装前请自行查看 GitHub 源码与 MIT 许可证，确认符合你的安全与合规要求。
- 合装包与四个子插件不要混装。
- 社区目录站点（SkillHub）与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文安装命令以仓库 README 为准。
- 子插件 npm 包：
dsh-deterministic-tools、dsh-jvm-doctor、dsh-py-doctor、dsh-win-native，均有独立仓库与 Release tarball。
链接¶
- 社区目录页：https://www.skillhub.cn/plugins/ax2/dsh-zidev-toolbox
- GitHub 仓库：https://github.com/ax2/dsh-zidev-toolbox
- npm：https://www.npmjs.com/package/dsh-zidev-toolbox
