dsh-date-calc

DeepSeek Harness 日期计算插件：date_arith 做日期加减（月运算月末钳制），workdays_between 统计/推算工作日（可配置周末、节假日区间/文件与调休），date_diff 给出两日期差值（年月日 / 总天数 / 总小时），format_date 按 locale 与时区格式化并支持自定义 Intl 选项。零运行时依赖，除只读导入节假日表外为纯计算。

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

安装

npm install dsh-date-calc

使用说明

date_arith —— 日期加减

用户：1 月 31 号往后推一个月是几号

起始：2024-01-31（周三）
运算：+1 月
结果：2024-02-29（周四）
ISO ：2024-02-29T00:00:00.000Z
本地：2024年2月29日 08:00（Asia/Shanghai）
Unix：1709164800 秒

参数：date（支持 now/today、YYYY-MM-DD、ISO 日期时间）、years、months、days、hours、minutes、seconds（均可为负）、timezone（默认 Asia/Shanghai）、locale（默认 zh-CN）。

月末钳制：1-31 加一个月得到 2-28（平年）或 2-29（闰年），不会溢出到下个月。

workdays_between —— 工作日统计与推算

统计模式（给出 start + end）：

区间：2024-01-01 ~ 2024-01-07（含首尾）
工作日：4 天
日历天：7 天
周末：2 天
节假日（落在工作日）：1 天
规则：周末=0,6，节假日 1 天

推算模式（给出 start + days）：

起始：2024-01-05（周五）
推算：+1 个工作日
结果：2024-01-08（周一）

参数：start、end、days、holidays（逗号/换行分隔的 YYYY-MM-DD，v0.2 支持区间 2024-10-01~2024-10-07）、holiday_file（节假日表文件，每行一个日期或区间，支持 # 注释）、makeup_workdays（调休上班日：把周末日计为工作日，支持区间）、weekend（视为周末的星期，0=周日…6=周六，默认 6,0；空字符串表示无周末）、inclusive（统计是否含结束日，默认 true）。

调休（v0.2）：makeup_workdays 把指定周末日计为工作日（优先级高于周末/节假日判定），统计与推算两个模式都生效：

workdays_between(start="2024-09-28", end="2024-09-29", makeup_workdays="2024-09-28")
→ 工作日：1 天（周六调休上班）

format_date —— 日期格式化

用户：把 2024-06-15 按中文格式输出

日期：2024-06-15（周六）
格式化：2024年6月15日（zh-CN / Asia/Shanghai）
ISO ：2024-06-15T00:00:00.000Z
周数：ISO 第 24 周
相对：2 年前
Unix：1718409600 秒 / 1718409600000 毫秒

参数：date、locale（默认 zh-CN）、timezone（默认 Asia/Shanghai）、style（date/full/long/medium/short/time，默认 long）、options（v0.2：自定义 Intl.DateTimeFormat 选项，JSON 字符串，提供后额外输出一行自定义结果）。

format_date(date="2024-05-01", options='{"year":"numeric","month":"2-digit","day":"2-digit","weekday":"short"}')
→ 自定义：2024/05/01 周三

date_diff —— 日期差值（v0.2 新增）

给出两日期的年月日差（月末钳制逐月累计）、总天数、总小时，并附工作日天数。口径为 end − start（不含起始日当天、含结束日）。

用户：1 月 15 号到 3 月 20 号差多久

date_diff(start="2024-01-15", end="2024-03-20")

区间：2024-01-15 ~ 2024-03-20（end 晚于 start）
年月日差：0 年 2 个月 5 天
总天数：65 天
总小时：1560 小时
工作日：46 天（周末 19 天，节假日 0 天）
规则：周末=6,0，节假日 0 天

参数：start、end（均必填）、holidays、holiday_file、makeup_workdays、weekend（同 workdays_between）。逆序区间会标注 end 早于 start，天数取绝对值。

典型场景

1. 合同/账期推算

用户：1 月 31 号签的一年期合同，到期日是几号

date_arith 传 months=12，月末自动钳制，避免出现 2 月 31 日这种无效日期。

2. 计算项目剩余工作日

用户：从现在到月底还有几个工作日

workdays_between 传 start=today、end=月末，并可用 holidays 排除法定假日。

3. 排期顺延

用户：这个任务需要 5 个工作日，从周五开始什么时候完成

workdays_between 传 days=5，自动跳过周末与节假日。

4. 多语言/多时区展示

用户：把这个时间按英文和美国时区显示

format_date 传 locale=en-US、timezone=America/New_York。

5. 长假/调休排期

用户：国庆后第一个工作日是哪天，这周实际要上几天班

holidays="2024-10-01~2024-10-07" 一次导入整段假期，makeup_workdays 把调休的周六算作工作日。

6. 两日期差值

用户：这个项目周期到底有多少天、多少工作日

date_diff 同时给出年月日差、总天数、总小时与工作日，不用多个工具拼结果。

7. 自定义日期格式

用户：按 yyyy/MM/dd 这种紧凑格式输出

format_date 传 options 自定义 Intl.DateTimeFormat 选项，如 {"year":"numeric","month":"2-digit","day":"2-digit"}。

8. 相对时间描述

用户：这个时间戳是多久以前

format_date 输出"相对"行，基于 Intl.RelativeTimeFormat 本地化。

安全边界

• 只读/纯计算：四个工具均不写入任何文件、不访问网络、不修改任何外部状态；唯一例外是 holiday_file 会只读读取你指定的节假日表文件。测试含"重复调用结果一致"的确定性与无副作用断言。
• 解析确定：无时区的日期时间一律按 UTC 解释，避免因运行环境时区不同导致结果漂移。
• 范围上限：工作日统计与推算的区间/步数上限 20 万天，超出即报错，防止超长循环。
• 非法输入显式报错：2024-13-01、2024-02-30 等无效日期会抛出明确错误，不会静默返回错误结果。
• 不引入外部数据：节假日需由调用方显式提供，插件不联网抓取（避免隐式网络依赖与数据时效问题）。
• 时区数据：使用 Node 内置的 ICU 时区库，不做额外下载。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-plugin-timer | date-calc 负责"算"日期，timer 负责"到点提醒"，配合做排期提醒 | | dsh-cron-toolkit（二期 D12） | cron 表达式解释出下次触发时间后，用 format_date 做本地化展示 | | dsh-workspace-journal | 工作日志的日期戳可用 format_date 统一格式化 | | dsh-table-render | 把工作日统计结果整理成表格渲染输出 | | dsh-fs-inspector | recent_files 的时间过滤与 date-calc 的日期推算可互相校验 |

版本说明

• 0.2.0（2026-10-17）：按 RoadMap v0.2 迭代。
  • 节假日表区间导入（2024-10-01~2024-10-07，支持 ..、逆序、# 注释）与 holiday_file 文件导入（每行一个日期/区间）
  • 新增 date_diff：年月日差（月末钳制逐月累计）+ 总天数 + 总小时 + 工作日
  • 工作日调休 makeup_workdays：把周末日计为工作日（统计与推算均生效）
  • format_date 新增 options：自定义 Intl.DateTimeFormat 选项
• 0.1.0（2026-09-24）：初始版本。
  • date_arith：年/月/日/时/分/秒加减，月运算月末钳制
  • workdays_between：工作日统计（周末与节假日可配置、含端点可切换）+ 工作日推算
  • format_date：Intl 多预设格式化 + ISO + ISO 周数 + 相对时间 + Unix 时间戳
  • UTC 确定性解析、范围上限、纯计算保证

RoadMap

v0.2（已落地于 0.2.0）

• 支持节假日表文件/区间导入（如 2024-10-01~2024-10-07）
• 新增 date_diff：两日期差值（年月日 / 总天数 / 总小时）
• 支持工作日调休（把某周末日设为工作日）
• format_date 支持自定义 Intl.DateTimeFormat 选项

v0.3（展望）

• 可选农历/二十四节气转换（需引入数据表，评估体积后决定）
• 支持持续时间解析（如 1y2m3d、ISO 8601 Duration）
• 时区转换助手（date_convert_tz）

FAQ

Q：为什么 2024-01-31 加一个月是 2-29 而不是 3-02？ 采用"月末钳制"语义：目标月没有该日时取当月最后一天。这与常见的账期、合同到期日算法一致。

Q：无时区的日期时间怎么解释？ 一律按 UTC。带 Z 或 +08:00 等偏移的输入则按给定偏移解析，保证结果可复现。

Q：节假日需要我自己提供吗？ 是。插件不联网获取节假日，需通过 holidays（支持区间与换行分隔）或 holiday_file（节假日表文件）传入。这样避免隐式网络依赖，也让你完全掌控口径。

Q：调休的周六怎么算？ 用 makeup_workdays 指定后，该日即使落在周末也计为工作日（优先级高于周末/节假日判定），workdays_between 与 date_diff 的工作日统计都生效。

Q：weekend 传空字符串是什么意思？ 表示没有周末，所有日期都按工作日计（仅受 holidays 影响）。适合 7×24 排班场景。

Q：workdays_between 的统计包含起止当天吗？ 默认含首尾。传 inclusive=false 则不含结束日。date_diff 的差值口径是 end − start（不含起始日当天、含结束日），与「总天数」保持一致。

Q：能直接修改系统时间或创建提醒吗？ 不能。本插件是纯计算工具，不产生副作用；提醒请使用 dsh-plugin-timer。

源码与发布地址

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

许可证

MIT