dsh-base64-codec

dsh-base64-codec

DeepSeek Harness 编解码插件（已定位为兼容薄壳）：base64 / base64url / hex / url 百分号编码互转，多字符集（GBK/Big5/Shift_JIS/EUC-KR 等）解码与自动嗅探，编码格式识别，JWT 解码（不验签）。

⚠️ deprecated：编解码能力已并入 dsh-hash-checksum

自 0.3.0 起，本包的 encode_text / decode_text / detect_encoding 直接转调 dsh-hash-checksum（数据工具箱）的同名实现，输出口径与原实现完全一致，下游解析脚本无需改动；工具描述已附 deprecated 提示。

• 新项目请直接使用 dsh-hash-checksum：哈希/校验/编解码一处维护，另有 encode_hash（编码+摘要）、hash_dir（目录批量摘要）等能力。
• decode_jwt 保留在本包并持续维护：验签与安全边界是独立话题，混进通用工具箱会稀释「不验签、不可用于鉴权决策」的声明。
• 本包不再新增同类编解码（base32 / base58 等），避免越堆越薄；能力收敛的依据与迁移策略见仓库决策记录。

安装

npm install dsh-base64-codec

使用说明

encode_text —— 文本编码

把 UTF-8 文本编码为四种格式之一：

用户：把 "Hello 世界" 编码成 base64

原文 10 字节 → base64（20 字符）：
SGVsbG8g5LiW55WM

参数：text（必填）、encoding（base64 | base64url | hex | url，默认 base64）。结果超过 4000 字符自动截断展示并标注总长。

decode_text —— 文本解码

把编码文本还原为文本，自动处理常见脏输入：

• 空白与换行：base64/hex 输入中的空白、换行自动忽略（支持邮件式折行粘贴）。
• 字母表兼容：base64url 的 - _ 自动映射回 + /，两种字母表互相可解。
• 二进制兜底：解码结果不是合法 UTF-8 时，提示 U+FFFD 替换符数量，说明「可能不是文本」。
• 多字符集（v0.2 新增）：解出的字节可按 GBK/Big5/Shift_JIS 等转成文本，或 auto 自动嗅探。

用户：解码这段 GBK 的 base64

解码结果（10 字节）：
Hello 世界
（字符集：GBK（简体中文），自动嗅探，置信度 高；…）

参数：text（必填）、encoding（同上，默认 base64）、charset（默认 utf-8，见下表）。

charset	说明
utf-8	默认，与 0.1.0 行为完全一致
auto	自动嗅探后解码，并标注所用字符集与置信度
gbk / gb18030	简体中文（gb18030 为超集）
big5	繁体中文
shift_jis / euc-jp	日文
euc-kr	韩文
latin1	ISO-8859-1（严格按字节→U+00XX）
windows-1252	西欧，含 0x80–0x9F 区间的可打印字符
utf-16le	UTF-16 小端

detect_encoding —— 编码识别（v0.2 新增）

判断一段文本最可能是哪种传输编码，并按需追加字符集嗅探：

用户：这段乱码是什么编码

传输编码识别（按可能性排序）：
  1. base64（得分 0.78）—— 符合 base64 字母表，长度 16（%4 = 0）；无 -/_/= 时与 base64url 结果等价
  2. plain（得分 0.00）—— 未发现编码特征

字符集嗅探（按 base64 解出的 12 字节取样）：
  1. UTF-8（得分 2.5，置信度 中）—— 合法 UTF-8 且含多字节序列（8 字符 / 12 字节，CJK 2）——这是强特征
  说明：合法 UTF-8，但取样不足 32 字节，建议结合上下文确认

识别范围：base64 | base64url | hex | url（百分号编码）| plain（自然文本）。文本呈 header.payload.signature 三段结构时会提示改用 decode_jwt。

参数：text（必填）。

decode_jwt —— JWT 解码（不验签）

拆解 JWT 三段结构，展示 header/payload 的 JSON，自动把 iat/nbf/exp 时间戳转为 ISO 时间并标注是否过期；v0.3 起附 alg 风险提示（none / HS 与 RS 混淆）与 aud/iss/sub 字段语义标注。

用户：帮我看看这个 token 里存了什么、什么时候过期

⚠ 本工具不校验签名，结果不可用于鉴权决策，仅用于查看内容。

header：{ "alg": "HS256", "typ": "JWT" }

payload：{ "sub": "user-123", "exp": 1779000000, ... }

算法风险：
  alg=HS256（共享密钥签名）：若服务端本应使用 RS*/ES*/PS*（非对称），存在「算法混淆」攻击面…；务必在服务端按白名单校验 alg。

字段语义：
  sub = "user-123" —— 主体：通常为用户/客户端唯一标识。

时间字段：
  iat = 1778996400 → 2026-09-18T01:00:00.000Z
  exp = 1779000000 → 2026-09-18T02:00:00.000Z（未过期）

signature：sig_nature…（11 字符，未校验）

参数：token（必填，三段式 JWT）。

大输入分块处理（v0.2 新增）

输入上限由 1MB 提升到 16MB，编解码按 64K 字符 / 块 流式进行：

• 编码：base64 / base64url 按 3 字节对齐切块（拼接结果与整块编码逐字符一致），hex 按字节切块，url 编码不切断代理对。
• 解码：base64 忽略空白并按 4 字符分组、hex 按 2 字符分组、url 保证 %XX 与代理对不跨块。
• 输出：展示仍截断到 4000 字符，并给出总字节/总字符数。

因此大输入不会构造超大中间串，也不会把整份解码结果塞进输出。

统计口径

• 字节数按 UTF-8 编码计（Hello 世界 为 10 字节：5 ASCII + 2 汉字 × 3 字节）。
• 位置/长度展示均为字符数（UTF-16 码元）。
• url 编码按 encodeURIComponent 语义（空格 → %20）；解码时 + 视为字面加号而非空格。
• latin1 严格按 ISO-8859-1（字节 → U+00XX）处理，与 windows-1252 分列（WHATWG 把 latin1 标签映射到 windows-1252，本插件不这么做）。
• 输入上限 16MB；base64 长度非法（去掉空白后 %4 === 1）、填充 = 位置非法、hex 长度为奇数、百分号序列非法均会拒绝。
• url + utf-8 组合沿用 decodeURIComponent 语义：解出的字节不是合法 UTF-8 直接报错（而非给替换符）。

字符集嗅探的原理与边界

charset=auto 与 detect_encoding 的嗅探按以下顺序判定，属启发式、非权威：

• 全是 ASCII → 任何兼容编码结果一致，直接按 utf-8。
• 是合法 UTF-8 且含多字节序列 → 判为 utf-8（其他编码碰巧产出合法 UTF-8 且含正确连续字节的概率极低）。
• 否则对 gb18030 / big5 / shift_jis / euc-kr / windows-1252 打分排序，得分由四部分组成：
  • 文字正常度：非 ASCII 里正常文字的占比；
  • 语种强特征：假名占比 ≥ 80% 判日文、谚文占比 ≥ 80% 判韩文；
  • 常用字区占比：多数编码把高频字排在前面的字节区间（GB2312 一级字 0xB0–0xD7、Big5 常用字 0xA4–0xC6、Shift_JIS 假名 0x82/0x83），用领字节落区作为字频代理，无需内嵌字频表；
  • 结构合法性：领/尾字节必须落在该编码的合法区间（如 Shift_JIS 领字节只能是 0x81–0x9F/0xE0–0xFC）。

边界：gbk 与 gb18030 对常见汉字等价；gbk / big5 / shift_jis 在短文本上可能同分，无法仅凭字节完全区分，此时输出会列出前 3 名候选与理由，请结合来源系统判断或显式指定 charset。

安全边界

decode_jwt 不校验签名，也不做 alg 混淆等攻击检测。它只回答「这个 token 里写了什么」，绝不回答「这个 token 是否可信」。鉴权决策必须在服务端用密钥验签后作出。

版本历史

• 0.3.0：
  • 定位调整为兼容薄壳：encode_text / decode_text / detect_encoding 转调 dsh-hash-checksum（数据工具箱）同名实现，输出口径零变化，工具描述附 deprecated 提示；decode_jwt 留在本包持续维护；
  • decode_jwt 新增 alg 风险提示：alg=none/空签名、HS 与 RS 算法混淆、非对称算法验签提醒、缺 alg 声明；
  • decode_jwt 新增 iss/aud/sub 字段语义标注（含多受众数组提示）。
• 0.2.0：
  • decode_text 新增 charset 参数：gbk / gb18030 / big5 / shift_jis / euc-jp / euc-kr / latin1 / windows-1252 / utf-16le，以及 auto 自动嗅探；
  • 新增 detect_encoding：传输编码识别（base64 / base64url / hex / url / plain）+ 判定成功后追加字符集嗅探，输出排序候选与判断依据，天然歧义显式提示；
  • 大输入分块编解码：输入上限 1MB → 16MB，编解码按 64K 字符分块，展示仍截断到 4000 字符；
  • 嗅探算法：UTF-8 合法性优先 + 语种占比判据 + 编码布局（常用字区）先验 + 双字节结构合法性校验。
• 0.1.0：初始版本——encode_text / decode_text（四编码互转、空白容忍、字母表兼容、二进制兜底）、decode_jwt（时间标注、不验签声明）。

FAQ

Q：为什么 base64url 的结果和 base64 有时一样？ 只有当编码结果含 + / 或填充 = 时两者才不同；纯字母数字内容（如 Hello 世界 的编码）两者恰好一致。

Q：解码出来是乱码怎么办？ 两种情况：一是原文是二进制（图片/压缩包等），看输出末尾的 ⚠ 提示（本插件只提示替换符数量，不做二进制预览）；二是字符集不对，用 charset=auto 重试，或按来源系统显式指定 gbk/big5 等。

Q：charset=auto 一定准吗？ 不一定。UTF-8 的判定很可靠，但 gbk / big5 / shift_jis 对短文本可能同分。输出会列出前 3 名候选、得分与理由（含常用字区占比、非法字节序列占比），请结合来源系统判断。

Q：能帮我验证 token 是否有效吗？ 只能看 exp 是否过期（会标注）。签名校验涉及密钥，本插件不做也不应做。

Q：为什么 latin1 和 windows-1252 要分两个？ 两者只在 0x80–0x9F 区间不同：latin1（ISO-8859-1）把它们当控制符，windows-1252 当可打印字符（如 é 之外的 “”）。混用会造成细微乱码，故不合并。

源码与发布地址

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

典型场景

1. 接口返回的 base64 图片/文件头排查

用户：这段 base64 是什么内容

用 decode_text 解码，若提示替换符则说明是二进制，可用 detect_encoding 的字节取样辅助判断；需要看具体魔数时再交给 hex 工具。

2. 排错时粘贴二进制安全的文本

用户：把这段含换行和引号的日志编码成一行，方便贴到工单里

encode_text 传 encoding=base64（或 base64url），得到无空白单行文本。

3. 日志/URL 参数还原

用户：这个 %E4%B8%AD%E6%96%87 是什么

decode_text 传 encoding=url，还原百分号编码内容。

4. 调试 JWT 内容与过期时间

用户：这个 token 什么时候过期、里面有哪些字段

decode_jwt 展示 header/payload 并把 exp 标注为已过期/未过期。

5. 跨系统传输前确认编码兼容

用户：这段 base64 用 URL 传输安全吗

用 encoding=base64url 重新编码，得到不含 + / = 的 URL 安全形式。

6. 老系统导出的 GBK 乱码排查

用户：这个接口返回的 base64 解出来是乱码

decode_text 传 charset=auto，若嗅探出 gbk/gb18030 即可正确还原中文，并给出置信度与候选列表。

7. 分不清是 base64 还是 hex

用户：这串 48656c6c6f 是什么编码

detect_encoding 给出排序候选与判断依据，并指出「hex 与 base64 天然歧义」的边界。

其他插件集成说明

协作插件	集成方式
dsh-hash-checksum	编码后的内容可用 hash_text 取摘要，用于比对传输完整性；v0.2 起该插件按「数据工具箱」方向吸收编解码能力
dsh-regex-lab	用 test_regex 校验 base64/JWT 文本格式是否符合预期模式
dsh-json-yaml-toolkit	JWT payload 解码出的 JSON 可交给 query_json 提取字段
dsh-http-client	请求体需要 base64/url 编码时，先用本插件编码再发起请求
dsh-table-render	批量解码多行结果可整理后用 render_table 输出对齐表格

RoadMap

v0.3（已落地于 0.3.0）

• JWT 扩展：alg 风险提示（none/HS 与 RS 混淆）、aud/iss/sub 字段语义标注 ✅
• 编解码能力并入 dsh-hash-checksum，本包降级为兼容薄壳（deprecated） ✅
• 「编码 + 摘要」一体化输出 → 已在 dsh-hash-checksum 落地为 encode_hash ✅

不再新增

• base32 / base58：同类编解码越堆越薄（Agent 内几行代码即可替代），能力价值在确定性与识别难度而非编码数量；
• 短文本 gbk/big5 嗅探增强：归入 dsh-hash-checksum 的字符集嗅探演进，不在本薄壳内继续投入。

decode_jwt 后续（留在本包）

• 验签能力评估（接入公钥/JWKS，明确「验签失败」与「不验签」的边界）；
• 常见 claim 的过期/受众/时钟偏移综合风险结论。

能力去向：编解码与字符集嗅探已并入 dsh-hash-checksum（数据工具箱）统一维护，decode_jwt 保持独立。

许可证

MIT