dsh-base64-codec

DeepSeek Harness 编解码插件：base64 / base64url / hex / url 百分号编码互转，多字符集（GBK/Big5/Shift_JIS/EUC-KR 等）解码与自动嗅探，编码格式识别，JWT 解码（不验签）。零运行时依赖（字符集支持依赖 Node 内置 TextDecoder）。

安装

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 时间并标注是否过期。

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

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

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

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

时间字段：
  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 的嗅探按以下顺序判定，属启发式、非权威：

1. 全是 ASCII → 任何兼容编码结果一致，直接按 utf-8。
2. 是合法 UTF-8 且含多字节序列 → 判为 utf-8（其他编码碰巧产出合法 UTF-8 且含正确连续字节的概率极低）。
3. 否则对 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.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（计划）

• JWT 扩展：alg 风险提示（none/HS 与 RS 混淆）、aud/iss 字段语义标注
• 新增 base32 / base58 支持
• 嗅探增强：引入压缩/字频模型进一步区分 gbk 与 big5 短文本
• 与 dsh-hash-checksum 联动做「编码 + 摘要」一体化输出

v0.2 相关能力的去向：按 dsh-hash-checksum 的 v0.2 计划（数据工具箱），编解码与字符集嗅探能力后续将并入该插件统一维护；decode_jwt 保持独立。

许可证

MIT