dsh-toolkit

一句话定位

DSH 零依赖工具集合，把时间、编码、JSON、计算器、CSV、正则、Markdown、Diff、统计、Schema 这 10 个确定性小工具一次性挂载到 DSH，让 AI 在对话里直接调用而无需再装 10 个独立插件。

核心能力

• 注册 10 个常用确定性工具（time / encoding / json / calculator / csv / regex / markdown / diff / stat / schema），供 AI 在工具调用时直接选用
• 提供 collection 形态：通过 catalog.json + scripts/install-*.sh 一次性把全部子包安装到 web 或 headless profile，脚本幂等可重复执行
• meta 包原子挂载：通过相对路径动态导入聚合 10 个子包，任一子包失败时逆序回滚已注册工具，不留下半成品状态
• 子包可独立安装：每个 dsh-tool-* 都是独立 bundle，可单独装/启/卸，例如只装 csv 或只装 diff
• 跨环境离线运行：所有子包零依赖、纯函数实现，不联网、不读文件、不写文件、不调 git
• 安全护栏：每个工具都设置 timeoutMs 兜底与单侧输入/输出字节上限，regex 用 worker 硬超时

技术实现

• 语言: TypeScript（ESM 模式，tsc 编译到 lib/）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-invariants
• 架构模式: 根 meta 包通过相对路径动态 import 10 个子包（../packages/dsh-tool-*/lib/index.js），调用其 apply() 向 ctx.tools.register 注册工具；patch 通过 package.json#dsh.bundle.patch 指向 cordis.patch.yml，DSH 加载时把 tool-kit 插入 profile layer 栈
• 入口文件: src/index.ts（meta 包聚合入口）、packages/dsh-tool-*/src/index.ts（10 个子包各自入口）

适用场景

日常对话或自动化任务里需要做 JSON 路径查询、CSV 解析、正则匹配、Markdown↔HTML 转换、文本/JSON/CSV/Markdown Diff、描述统计、JSON Schema 校验等"小而确定"的操作时，挂一次本集合就能让 AI 直接调用，避免为每个工具单独搜装插件。适合不需要写脚本、只用 AI 工具调用就能解决的场景。

前置依赖与兼容性

安装方式

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

也可使用仓库自带脚本批量安装到 web/headless：

./scripts/install-web.sh       # 全部 10 工具 → web profile
./scripts/install-headless.sh  # 全部 10 工具 → headless profile
./scripts/install-all.sh       # 两个 profile 都装

配置项

本插件无需额外配置。所有子工具均通过 ctx.tools.register 注册为 DSH 工具调用，参数（如 regex 的 pattern、csv 的分隔符、schema 的 schema）由每次工具调用时传入，不读取任何 config / env 变量。

常见问题

Q: meta 包和独立 bundle 模式有什么差别？我该用哪种？

A: 推荐独立 bundle 模式——每个子包都是独立插件，可以单独装/启/卸，配合 scripts/install-*.sh 也能一键批量装。只有当业务上需要一次性原子挂载全部工具（即"装就全装、卸就全卸"）时，才用 meta 包（dsh plugin --profile web add github:omdsh-dev/dsh-toolkit）。

Q: 我之前单独装过 tool-csv，再装 meta 包会不会冲突？

A: 会。10 个子包注册的 DSH 工具名（time/encoding/json/calculator/csv/regex/markdown/diff/stat/schema）会与 profile 中已存在的同名工具冲突，导致注册报错。遇到这种情况，请先移除已单独装的同名工具再装 meta，或改用独立 bundle 模式（推荐）。

Q: 装到 web 之后，dsh run 能直接用到这些工具吗？

A: 不能。web 与 headless 是 DSH 中两个独立的 profile，web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。脚本里也分别提供了 install-web.sh / install-headless.sh / install-all.sh 三种入口。

Q: 这 10 个工具能离线用吗？需要联网或读本地文件吗？

A: 可以。所有子包都是零依赖、纯函数实现，diff 模块的源码注释也写明不读文件、不联网、不写文件、不调 git。JSON Schema、CSV、正则等工具完全基于输入字符串工作；encoding 工具只处理 UTF-8 文本。

Q: regex 工具会不会因为灾难性回溯把进程卡死？

A: 不会。regex 子包用 worker 硬超时做兜底；其他子包也各自有 timeoutMs 上限（time 1000ms、diff 2000ms、schema 3000ms，pattern worker 另加 1000ms），每个工具同时设了单侧输入/输出字节上限，避免大输入阻塞。

Q: 不想用 meta 包，只想要其中一个工具，怎么装？

A: 每个子仓库都是独立 bundle，可单独安装，例如 dsh plugin --profile web add github:omdsh-dev/dsh-tool-csv、dsh plugin --profile headless add github:omdsh-dev/dsh-tool-diff，不必依赖本 collection 仓库。

Q: meta 包 apply 失败时会不会留下"装了一半"的状态？

A: 不会。src/index.ts 在 apply 期间临时包装 ctx.tools.register 捕获每个工具的 disposer，任一子包注册失败时按逆序调用 disposer 回滚已注册工具，最后抛出包含"已回滚数量"信息的错误，不残留部分注册。

上手难度

入门 — 安装一行命令即可生效，AI 在对话中按需调用，无需写配置或脚本；理解各工具的 action 含义后即可直接使用。

已知问题与限制

• 命名冲突：meta 包的 10 个子工具名（time/encoding/json/calculator/csv/regex/markdown/diff/stat/schema）与同名独立 bundle 冲突，profile 中若已存在同名工具，装 meta 包会注册失败（README.md:107-109）
• encoding 工具的 hash 仅供非安全用途（md5/sha1/sha256/sha512），工具参数会被记入会话日志，禁止用来传密钥或 token（packages/dsh-tool-encoding/src/index.ts:21-27）
• encoding 工具只支持 UTF-8 文本；非 UTF-8 输入不会被自动转码
• diff 工具单侧输入上限 256KB、输出上限 64KB、Myers diagonal 预算 2000、行数 50K 上限，超出会按 maxChanges 与字节预算截断并注明（packages/dsh-tool-diff/src/index.ts:1-9）
• schema 工具 strictSchema 默认 true，maxErrors 默认 100、范围 1..1000，输出上限 1 MiB（packages/dsh-tool-schema/src/index.ts:1-12）
• time 工具只接受严格 ISO 8601 时间戳（YYYY-MM-DD 或 YYYY-MM-DDTHH:mm:ssZ，可选 .SSS 与 ±HH:MM 偏移），其他格式会被拒绝
• csv 工具按 RFC 4180 严格引号解析，query 为精确匹配（非子串），列名在第一行为 header 时使用，否则用 1-based 索引
• regex 工具为避免长耗时匹配，pattern/输入都有硬性大小上限与 worker 超时
• 仓库内未发现 TODO/FIXME/HACK/XXX 注释

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