dsh-hash-checksum

dsh-hash-checksum

DeepSeek Harness 哈希与校验和插件：文本/文件 md5/sha1/sha256/sha512 摘要，校验和比对验证。文件采用流式读取，内存占用恒定。零运行时依赖。

安装

npm install dsh-hash-checksum

使用说明

hash_text —— 文本哈希

用户：算一下 "abc" 的 sha256

sha256：ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  (256 bit, 32 字节摘要)
输入：3 字节

参数：text（必填，上限 5MB）、algorithm（md5 | sha1 | sha256 | sha512，默认 sha256）、upper（大写输出，默认 false）。

hash_file —— 文件哈希（流式）

按 1MB 分块流式读取，任意大小文件（上限 512MB）内存占用恒定，不会把整个文件读进内存。

用户：算一下下载的安装包的 sha256，和官网对一下

sha256：9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  (256 bit, 32 字节摘要)
文件：E:\downloads\setup.exe（48214456 字节，流式读取）

参数：path（必填）、algorithm、upper、format（text 默认 | sha256sum）。format: "sha256sum" 时输出 "<hash> <path>" 兼容行，可直接存 .sha256 文件：

hash_file { path: "setup.exe", format: "sha256sum" }
9f86d081…a08  setup.exe
（sha256sum 兼容格式：<hash>  <path>；算法 sha256，48214456 字节，流式读取）

verify_checksum —— 校验和比对

计算实际哈希并与期望值比对，输出 ✅/❌ 结论，期望值与实际值都完整展示便于人工复核。

用户：这个文件的 sha256 应该是 9f86d081...a08，帮我验证一下

✅ 校验一致
算法：sha256
期望：9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
实际：9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
对象：文件 E:\downloads\setup.exe（48214456 字节）

参数：

• expected（与 checksum_file 二选一）：期望校验和，支持 sha256:abc... 前缀（大小写不敏感）或裸 hex
• checksum_file（v0.2 新增，与 expected 二选一）：校验文件路径（.sha256 / .md5 等），内容为 "<hash> <path>" 行或纯 hash，按文件名匹配条目，算法按摘要长度自动识别
• text / path：二选一
• algorithm：默认 sha256；expected 带前缀时以前缀为准，两者冲突会报错

期望值长度与摘要长度不符时（如拿 md5 值验 sha256），会提示「可能复制错了算法的校验和」。

encode_hash —— 编码 + 摘要一步完成（v0.2 新增）

先把原文按 base64 / base64url / hex / url 编码，再对编码结果字符串计算摘要，输出「编码结果 + 校验和」，用于传输完整性比对。输入上限 1MB。

encode_hash { text: "Hello 世界", encoding: "base64", algorithm: "sha256" }
原文 11 字节 → base64（16 字符）：
SGVsbG8g5LiW55WM
sha256（基于编码结果字符串的 UTF-8 字节）：…

参数：text、encoding（默认 base64）、algorithm（默认 sha256）。

hash_dir —— 目录批量摘要（v0.2 新增）

递归扫描目录（跳过符号链接），对文件逐个流式取摘要，按相对路径排序输出 "<hash> <相对路径>" 列表，可直接存为 sha256sum 校验文件。

hash_dir { path: "dist", include: "**/*.js", format: "sha256sum" }

参数：path（必填）、algorithm、include（glob，按相对路径匹配，如 **/*.js）、ignore（忽略名单，默认 ["node_modules", ".git"]，传 [] 不忽略）、format（text | sha256sum）、max_files（默认 500，上限 5000）、upper。

encode_text / decode_text / detect_encoding —— 编解码与字符集嗅探（v0.2 新增）

从 dsh-base64-codec 并入的编解码能力（输出口径与原包完全一致）：四种传输编码互转、11 种字符集解码（含 auto 嗅探）、传输编码识别。参数与行为详见该文档；新项目请统一用本插件调用。

统计口径

• 字节数按 UTF-8 编码计（Hello 世界 = 12 字节）。
• 摘要输出为 hex：md5/sha1/sha256/sha512 分别为 32/40/64/128 字符。
• 文件哈希对 0 字节文件同样有效（空文件也有确定摘要）。
• hash_dir / hash_file 的 sha256sum 格式为 <hash> <相对路径>（两空格），与 GNU coreutils 的 sha256sum 输出及 sha256sum -c 校验文件兼容（算法非 sha256 时需用对应 md5sum 等工具校验）。

安全边界

• md5 / sha1 已被证实存在碰撞攻击，仅适用于下载校验和、去重、缓存键等非对抗场景；本插件在输出中自动附提示。
• 完整性防篡改、签名、密码存储请分别使用 sha256/HMAC/argon2 等方案，本插件不提供。
• verify_checksum 的比对在本地完成，期望值来源（官网、作者公布）的可信性需自行判断。

版本历史

• 0.1.0：初始版本——hash_text / hash_file（流式）/ verify_checksum（前缀解析、大小写不敏感、长度不匹配提示）。
• 0.2.0：按 v0.2 RoadMap 迭代为「数据工具箱」——并入编解码三件套（encode_text / decode_text / detect_encoding，与 dsh-base64-codec 同源同口径）、新增 encode_hash（编码+摘要）、hash_dir（目录批量摘要、glob 过滤、忽略名单）、hash_file/hash_dir 支持 sha256sum 兼容格式、verify_checksum 支持从 .sha256 校验文件读取期望值。

FAQ

Q：大文件会撑爆内存吗？ 不会。文件按 1MB 分块流式读取，内存占用与文件大小无关（上限 512MB）。

Q：为什么 md5 结果带警告？ md5/sha1 存在已知碰撞攻击，用于校验和场景没问题，但不可用于防篡改。警告只是提醒，不影响计算。

Q：能算 CRC32 吗？ 不能。CRC32 不是密码学哈希且 Node 内置 crypto 不支持，本插件限定四种 SHA 系算法。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-hash-checksum
• npm：https://www.npmjs.com/package/dsh-hash-checksum

典型场景

1. 下载文件校验

用户：这个安装包的 sha256 和官网给的对得上吗

verify_checksum 传 path 与官网校验和，得到 ✅/❌ 结论；不一致时还会提示长度是否匹配（识别"拿错算法的值"）。

2. 大文件摘要

用户：这个 4GB 镜像的 sha256 是多少

hash_file 流式读取，内存占用恒定，不会把文件读进内存。

3. 内容一致性确认

用户：这两个文件内容真的一样吗

分别取哈希比对；与 dsh-text-diff 的文本差异互为补充（二进制场景哈希更直接）。

4. 去重预筛

用户：这两个目录里有没有重复文件

先按 size 分组（dsh-fs-inspector），再对同 size 文件取哈希确认。

5. 变更前后校验

用户：改完之后文件有没有被意外动过

改动前后各取一次摘要比对。

其他插件集成说明

协作插件	集成方式
dsh-fs-inspector	先定位大文件/最近改动文件，再对目标计算摘要
dsh-base64-codec	编码内容可取摘要用于比对；JWT 原始串校验同理。其编解码能力按下方 v0.2 计划并入本插件，decode_jwt 保持独立
dsh-diff-writer	补丁前后取摘要，确认改动范围符合预期
dsh-git-helper	提交前后摘要比对，确认只有预期文件变化
dsh-http-client	下载内容先落盘再校验摘要，形成"下载→校验"闭环

RoadMap

v0.2（已落地于 0.2.0）：演进为「数据工具箱」

定位调整：哈希/校验与编解码本质都是“对一段数据取一个可校验的表示”，拆成两个插件每个都薄。v0.2 把 dsh-base64-codec 的编解码能力并入本插件，统一维护；decode_jwt 保持独立（安全边界与验签是独立话题）。

吸收编解码能力：

• 新增 encode_text / decode_text：base64 / base64url / hex / url 百分号编码互转，沿用其 64K 字符分块处理（输入上限 16MB）与脏输入容错（空白容忍、字母表兼容、二进制替换符提示）
• 新增 charset 参数与 detect_encoding：gbk / gb18030 / big5 / shift_jis / euc-jp / euc-kr / latin1 / windows-1252 / utf-16le 多字符集解码，以及 auto 自动嗅探（UTF-8 合法性优先 + 常用字区先验 + 双字节结构合法性校验）
• 新增 encode_hash（暂定）：编码 + 摘要一步完成，输出「编码结果 + 校验和」，用于传输完整性比对

原有哈希能力：

• 新增 hash_dir：目录批量摘要（支持 glob 过滤与忽略名单）
• 支持输出 sha256sum 兼容格式（<hash> <path>），可直接喂给系统校验工具
• verify_checksum 支持从 .sha256 校验文件读取期望值

迁移策略：

• 迁移期间两个包的工具输出口径保持一致，避免下游解析脚本改写
• dsh-base64-codec 编解码部分迁出后降级为薄壳转调本插件并在 README 标记 deprecated；decode_jwt 留在原包
• 合并后包名与主入口不变（dsh-hash-checksum），对外只新增工具不删旧工具

v0.3（展望）

• 重复文件检测（size 预筛 + 前缀哈希 + 全量确认的三级策略）
• 多算法并行计算（一次读取同时产出 md5/sha256）
• 与 dsh-fs-inspector 联动做"大文件 + 摘要"体检报告

许可证

MIT