dsh-tool-time/packages/dsh-tool-time

一句话定位

dsh-tool-time 是 dsh-toolkit 工具集中的时间子包，让 DSH Agent 用一次本地函数调用完成"现在几点""UTC 转北京时间""3 天后是哪天"等时间问题；不弹 bash 进程、不让模型心算闰年和 DST。

核心能力

• 查询当前时间：默认返回 UTC 毫秒时间戳和结构化字段，可指定 IANA 时区显示墙钟
• 时区转换：把任意严格 ISO 8601 时间戳投到指定 IANA 时区，返回 ISO、unix 毫秒、当地墙钟和带偏移的字符串
• 日历加减：按 UTC 对时间戳做 seconds/minutes/hours/days/weeks/months/years 加减，月末日期自动钳制（如 1 月 31 日加 1 个月 = 2 月 28 日）
• 时长差计算：算两个时间戳之间的固定毫秒差，输出带符号总量和各单位的带符号分量，加非负余数分解
• 严格输入校验：拒绝非 ISO 8601 形式（包括 RFC 2822、自然语言日期、不带时区的日期时间）和日历溢出（如 2026-02-30）
• 时区名校验：交给 Intl.DateTimeFormat 验证，非法时区抛 time: unknown timezone 并被前端清晰提示

技术实现

• 语言: TypeScript (ESM)
• 关键依赖: @deepseek-ai/cordis ^4.0.1（插件容器）、@deepseek-ai/dsh-tools ^0.0.1-rc.1（工具注册 API）、@deepseek-ai/dsh-invariants ^0.0.1-rc.1（包标识伴生）
• 架构模式: 通过 cordis.patch.yml 用 - insert: 把 tool-time 插入 profile 的 layer stack；apply 阶段调用 ctx.tools.register(defineTool(...)) 注册名为 time 的单一工具，内部按 action 字段分发到 4 个独立函数
• 入口文件: packages/dsh-tool-time/src/index.ts（Cordis 插件 apply）、packages/dsh-tool-time/src/time.ts（action 分发与纯函数实现）、packages/dsh-tool-time/cordis.patch.yml（profile 注入声明）

适用场景

Agent 接到"现在几点""把 2026-01-01 转成北京时间""3 天后是几号""这两次事件间隔多久"这类高频时间问题时，过去要么弹 bash 进程调 date（macOS 和 GNU 语法不一致、还要手工拼 TZ），要么让模型心算闰年和 DST 偏移，都容易出错。dsh-tool-time 用纯函数替代上述路径，统一输出毫秒精度 ISO + unix + 当地墙钟 + 格式化串四个字段，模型只需读字段无需做心算。

前置依赖与兼容性

安装方式

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

配置项

本插件对终端用户没有运行时配置（无 dsh profile config、无环境变量），所有行为由工具调用时的参数决定：

常见问题

Q: 这个插件会起 bash 进程跑 date 命令吗？

A: 不会。全部逻辑由 Node 内置 Date 与 Intl.DateTimeFormat 实现，纯函数、零进程，性能稳定且不依赖 GNU/BSD date 的差异。

Q: 时区转换和"加一天"是按哪个时区算的？

A: 转换（convert）按 IANA 时区展示墙钟；日历加减（add）始终按 UTC 运算，timezone 字段只影响结果里的 local/formatted 显示字段，不会影响实际加减后的 instant。

Q: 支持自然语言日期如"next week"或"下周三"吗？

A: 不支持。只能接受严格 ISO 8601 子集（YYYY-MM-DD 或带时分秒/偏移），RFC 2822 和自然语言一律拒绝，避免歧义和模型心算误差。

Q: 年份范围有限制吗？

A: 输入和计算结果年份都必须在 1000 到 9999 之间；1000 之前 JavaScript Date 有 1900+ 映射的历史坑，超过 9999 则偏移计算与 Intl era 会失真。

Q: diff 能输出"几个月""几年"吗？

A: 不能。diff 只输出固定时长（毫秒/秒/分/时/天/周），因为月和年无法从毫秒唯一推导；如果需要日历月差请用 add 加减后再减。

Q: 安装到 web profile 后 dsh run 也能用吗？

A: 不能直接用。web 与 headless 是两个独立 profile，需要分别安装；dsh run 默认走 headless profile，记得用 --profile headless 也加一次。

Q: 卸载会改 dsh 本体或我的 API Key 吗？

A: 不会。插件卸载只移除工具注册，不动 dsh 安装、凭据、provider 配置；同理重装 dsh 也不会自动回带本插件。

Q: 执行超时怎么办？

A: 工具声明的超时时间是 1 秒。四个 action 都是本地纯函数，正常毫秒级完成；如果真触发 timeoutMs 几乎一定是 Node ICU 数据异常或系统时钟异常，需要重启环境。

上手难度

入门 — 装上插件即可调用，无需任何额外配置或凭据；唯一需要学习的是 ISO 8601 时间戳的写法（带不带 Z、要不要时分秒），对于写过 JSON 接口的人都很自然。

已知问题与限制

• 只接受年份 1000-9999 之间的输入与计算结果；该范围外会被工具拒绝（src/time.ts:140-146, 216-219, 309-314）
• add 的月份/年份加减有业务上限 3,000,000（约 25 万年），超出会被前置拒绝以避免触达 Date 边界（src/time.ts:188-190）
• add 的 timezone 仅影响 local/formatted 展示字段，不影响实际运算；想要"墙钟加减"语义需要等 v2（README.md:168）
• diff 不支持日历月/年差，只能输出固定时长（毫秒/秒/分/时/天/周）（src/time.ts:214-240）
• 字符串参数限制为 200 字符以内，超长会被前置拒绝（src/time.ts:256-259）
• 时区数据来自 Node 内置 ICU，"跨平台一致"等价于"相同 Node/ICU 数据版本下一致"；历史时区（<1900）的秒级 offset 会被截断到分钟（README.md:170-173）
• local / formatted 字段是秒精度展示字段；毫秒精度仅保留在 iso / unix 上（README.md:172）

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