dsh-tool-encoding/packages/dsh-tool-encoding

本页文档对应子包 dsh-tool-encoding（meta 包 dsh-toolkit 下属 10 个独立工具之一）。

一句话定位

在 DSH 会话里为 UTF-8 文本做编码与摘要：base64、base64url、URL、hex 编解码，加上 md5/sha1/sha256/sha512 哈希和 UUID v4 生成。一次工具调用、毫秒级返回字符串，免去 AI Agent 起 bash 跑 base64/md5sum 时的引号转义与跨平台命名不一致问题。

核心能力

• 标准 base64 与 base64url 互转（编码无空白、严格校验、canonical unused bits 检查）
• URL component 语义编解码（区别于表单编码）
• UTF-8 字节 hex 编解码，fatal 解码拒绝非法序列
• md5/sha1/sha256/sha512 哈希（hex 输出）
• UUID v4 字符串生成（基于 crypto.randomUUID()）
• 统一输入校验：拒绝孤立 surrogate、字节上限 1MB、UTF-8 解码非法序列立即报错

技术实现

• 语言: TypeScript（ESM，type: module）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-invariants（均为 peerDependency，运行时零业务依赖）
• 架构模式: 通过 cordis.patch.yml 以 tool-encoding row id 插入 profile layer stack；apply(ctx) 注册到 ctx.tools，由 cordis 依赖注入；核心逻辑是纯函数 executeAction(action, params)，无 eval / new Function
• 入口文件: packages/dsh-tool-encoding/src/index.ts（导出 apply / name / inject）
• 运行时安全: Buffer / node:crypto / TextDecoder('utf-8', { fatal: true }) / encodeURIComponent 纯函数组合，错误统一带 encoding: 前缀

适用场景

当 AI Agent 在会话中遇到 base64 字段（JWT payload、API 响应片段）、要构造 URL 查询参数、想快速生成 UUID，或者要给一段文本做摘要（文件完整性校验、自增 ID 派生、缓存键）时使用。以前 Agent 只能 bash -c "echo ... | base64"，进程开销 + 引号嵌套 + md5 / md5sum / shasum -a 256 跨平台不一致这三类坑要自己处理；现在直接调用 encoding 工具即可拿到规范字符串结果。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit/packages/dsh-tool-encoding

配置项

本插件无需额外配置。安装即注册到 DSH 工具系统。工具参数（调用时传入）如下，供参考：

注：参数超长（>1MB）或解码输出超 4MB 时工具直接报错并终止，不会截断输出。

常见问题

Q: 这个插件能做加解密或签名吗？

A: 不能。插件只做单向摘要（md5/sha1/sha256/sha512）和对称编解码，没有 HMAC、加盐、密钥派生、对称加密这些能力，机密材料也不要用它处理（参数会进会话日志）。

Q: 能不能处理任意二进制（图片、压缩包这类）？

A: 当前 v1 是 UTF-8 文本工具：二进制内容只能先转成 hex 字符串再传给 base64_encode / hash。任意二进制编解码（带 output: "utf8" | "hex" 模式）需 v2。

Q: base64url 编码会输出带 = 填充的字符串吗？

A: 默认无 padding（JWT 风格，例如 "\uFEFF" → "77u_"），但解码端兼容带 padding 的输入。带 padding 时必须完整（残缺会拒绝），无 padding 时按数据长度自动补齐再解码。

Q: 输入有大小限制吗？

A: 有的。输入上限 1MB（1,000,000 UTF-8 字节），输出上限 4MB（按最坏膨胀率预检，超了直接拒绝不截断），单次工具调用超时 1000 毫秒。

Q: URL 编码用的是 application/x-www-form-urlencoded 那种语义吗？

A: 不是。url_encode / url_decode 用 component 语义（encodeURIComponent）：空格变 %20 而不是 +，!'()* 不被转义，+ 解出来还是 +。表单编码（空格 → +）需 v2 独立 action。

Q: 如何卸载这个工具？

A: 与 DSH profile bundle 卸载一致：dsh plugin --profile web remove tool-encoding，web 与 headless 是两个独立 profile，需各自卸载。

Q: 报 encoding: invalid base64 input 是什么意思？

A: base64 输入不满足严格校验。可能原因：包含空白字符、= 没出现在末尾或超过 2 个、长度不是 4 的倍数、或者尾量子的 unused bits 不是 0（如 Zh== 这种非 canonical 编码）。多数 base64 工具输出的是标准编码，遇到此错通常是上游加白/换行的痕迹，或字符串被截断。

上手难度

入门 — 一次性添加命令即可使用，没有配置项，工具参数表里就 3 个字段，普通用户调一两次就明白 action + input 的组合规律。

已知问题与限制

• 二进制（不可打印字节）内容需 v2 的 output: "utf8" | "hex" 模式；当前 v1 仅支持 UTF-8 文本
• hash 仅摘要，无 HMAC/加盐/密钥派生；MD5 与 SHA-1 仅作兼容性/非安全完整性校验
• url_encode / url_decode 是 component 语义（encodeURIComponent），表单编码（空格 → +）需 v2 独立 action
• uuid action 拒绝任何额外参数（含拼写错误字段），多传参数会直接报错
• 工具参数与返回会进入会话日志；切勿传入密钥、token、密码等机密材料

English

DSH 零依赖工具包 collection —— time / encoding / json / calculator / csv / regex / markdown / diff / stat / schema 十个确定性工具，统一入口一键安装。

为什么

DSH 生态仓库持续增长，单插件在 hub 中容易被淹没；collection 分类是辨识度最高的形态。本仓库把 10 个工具插件 vendored 冻结为 pack artifact 快照（各子仓库独立演进，当前源位于 omdsh-dev 组织下），统一工程、统一测试、统一维护。

定位（官方 Profile Bundle 生态方向）：本仓库是 collection 与安装辅助仓库——每个子包都是可独立安装/启用/禁用/卸载的 bundle（dsh plugin --profile <p> add <子包>）；collection 提供目录、清单与批量安装脚本。meta 包 @deepseek-ai/dsh-toolkit 保留为可选的原子挂载模型（见下文两种运行模型）。

分发边界：根 meta 包保持 private: true，用于 Git/collection 分发，不代表会发布到 npm registry。根目录已提交由当前 src 构建出的 lib/index.js 与 lib/types/index.d.ts，因此从 Git 安装时不依赖消费端 lifecycle；prepack 仍会在生成 pack artifact 前执行完整构建。

工具一览

架构

dsh-toolkit/
├── src/index.ts          # meta 包：相对路径动态导入 10 个子包 apply()，聚合注册
├── packages/dsh-tool-*   # vendored 子包（pack artifact 快照，name 保持 @deepseek-ai/dsh-tool-*）
├── scripts/
│   ├── link-deps.sh      # 构建期 junction（cordis → vendor/cordis，dsh-tools → packages/core/tools）
│   ├── build-all.sh      # 一键构建 10 子包 + meta 包（tsc）
│   ├── test-all.sh       # 一键跑 10 子包 vitest（合计用例数）
│   ├── install.sh        # meta / 逐包两种挂载模式（含 dry-run）
│   ├── install-web.sh    # 独立 bundle 批量安装 → web profile
│   ├── install-headless.sh # 独立 bundle 批量安装 → headless profile
│   └── install-all.sh    # web + headless 都装
├── catalog.json          # collection 清单（hub collection 分类识别依据）
└── tsconfig.base.json    # 共享编译配置（固化踩坑经验）

与实施文档方案 A 的工程化适配：子包为私有 Git/collection 包，peer 名解析在 profile 内不可行， 故 meta 包采用相对路径动态导入（零解析魔法、打包自足）；子包 runtime 依赖 （@deepseek-ai/dsh-tools）在 npm 独立模式（默认）下不依赖 DSH monorepo，monorepo 模式经子包构建期 junction 解析。

安装

仓库位于 omdsh-dev/dsh-toolkit（public）。

独立 bundle 模型（推荐）

每个子包独立安装、启用、禁用、卸载：

# 安装单个工具到 web profile
dsh plugin --profile web add github:omdsh-dev/dsh-tool-csv
# 一次性任务（headless）profile
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff

批量安装（collection 辅助脚本，幂等——重复执行不会重复添加）：

./scripts/install-web.sh       # 全部 10 工具 → web profile
./scripts/install-headless.sh  # 全部 10 工具 → headless profile（dsh run 使用面）
./scripts/install-all.sh       # 两个 profile 都装

验证与运行：

dsh --profile web --dump-config | grep tool-csv     # 行存在即安装成功
dsh run "使用 csv 工具解析 'a,b\n1,2'"               # headless 端到端

⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless。 Windows 路径使用正斜杠（C:/...）。

npm pack tarball 安装

本地构建后用 tarball 路径安装（不依赖 GitHub）：

# tarball 方式（web 为例；headless 同）
npm pack
dsh plugin --profile web add <npm pack 产物 tarball 路径>

meta bundle 模型（可选）

需要一次原子挂载全部工具时，挂载根 meta 包：

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit
dsh --profile web --dump-config | grep tool-kit

⚠️ 若 profile 已单独挂载过同名插件（tool-time/.../tool-diff/tool-stat/tool-schema），挂 meta 包会注册重名报错—— 此时先移除旧插件，或用独立 bundle 模型。meta apply 具备原子性（任一子插件失败时 逆序回滚已注册工具，不残留部分状态）。

手动安装与旧版本兼容

旧场景（monorepo 集成、不支持 Profile Bundle 的旧快照或插件开发调试环境——本地 junction/symlink、手动编辑 profile 层）。

构建与测试

npm 独立模式（默认，推荐）：无需 DSH monorepo；npm install（devDependencies 自包含）后即可：

npm run build:all           # 10 子包 + meta 包 tsc + 产物完整性验证（无 .ts 残留导入、10+1 个 lib/index.js）
bash scripts/test-all.sh    # 10 子包 vitest 全量（723 用例）；任一失败整体非零退出
npm pack                    # prepack 自包含（build:all），tarball 含 lib + 10 个子包

monorepo 模式（可选：源码贡献/旧 snapshot）：显式提供 DSH monorepo 根：

export DSH_MONOREPO=<DSH 0.1.0-rc.8（npm）安装路径>   # 或作为第一个参数
bash scripts/build-all.sh   # link-deps + 10 子包 + meta 包 tsc + 产物完整性验证
bash scripts/test-all.sh

prepack 已指向 build:all（完整构建 10 子包 + meta），保证 pack artifact 含全部运行入口；根 Git 入口由当前 src 预构建并提交。 本仓库只在本地验证构建、测试与 pack artifact；不要将这些结果解读为 npm registry 发布或未实际执行的 consumer/profile 验证。

同步 vendored（子仓库有更新时）

把 packages/<name> 与源仓库重新同步（src/tests/package.json/tsconfig/cordis.patch.yml/LICENSE/README.md），并在 README 标注子包版本。

新增工具

见 docs/CONTRIBUTING.md：复制模板子包 → 实现 → 测试 → build-all 验证 → 更新 catalog.json。

许可

MIT