omdsh-dev/dsh-tool-time

dsh-tool-time

English

DSH 时间工具插件 —— 严格 ISO 解析、IANA 时区转换、UTC 日历运算、固定时长差。零依赖、零进程、纯函数。

动机

Agent 处理时间信息是最高频需求之一——"现在几点"、"3 天后是几号"、"把 UTC 转成北京时间"。当前做法 bash date 的问题：每次起进程、跨平台语法不一致（macOS 与 GNU date -d 完全不同）、时区转换靠 TZ=... 手动拼。模型心算时区偏移和闰年/DST 边界是错误高发区。

安全模型

无 eval、无 new Function。输入只经过严格校验：

• 严格 ISO 8601 子集：仅接受 YYYY-MM-DD（UTC 零点）、YYYY-MM-DDTHH:mm:ssZ、YYYY-MM-DDTHH:mm:ss±HH:MM（±14:00 内，可选 .SSS 毫秒）；不带时区的日期时间、RFC 2822、自然语言日期一律拒绝；2026-02-30 等日历溢出由查表校验拒绝（不依赖 Date 的静默归一化）
• 时区名：IANA 名交给 Intl.DateTimeFormat 校验，非法即抛 time: unknown timezone
• 数值：amount 必须是安全整数；unit 枚举白名单；所有字符串 ≤200 字符
• Intl 环境固定：'en-CA' + hourCycle: 'h23'（避免午夜 24:00 与本地化数字）

架构

DSH Agent
    │ ctx.tools.register()
    ▼
src/index.ts（Cordis 插件入口 + action 分发 + 独立校验）
    │
    ▼
src/time.ts
    ├── parseStrictISO() — 严格 ISO 解析（正则 + 查表校验）
    ├── formatInTimezone() — Intl formatToParts 组装（时钟可注入）
    ├── addMonthsClamped() — 先置 1 日 → 目标年月 → 天数钳制
    └── diffBetween() — 固定时长（sign + absolute 分解）

工具声明

ctx.tools.register(defineTool({
  name: 'time',
  parameters: {
    action: { type: 'string', required: true, enum: ['now', 'convert', 'add', 'diff'] },
    value:  { type: 'string', description: 'Strict ISO 8601 timestamp' },
    timezone: { type: 'string', description: 'IANA timezone (default UTC; display only)' },
    from:   { type: 'string', description: 'diff start' },
    to:     { type: 'string', description: 'diff end' },
    amount: { type: 'integer', description: 'Signed safe integer' },
    unit:   { type: 'string', enum: ['seconds','minutes','hours','days','weeks','months','years'] },
  },
  output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 2) }] },
  execute: (args) => Promise.resolve(executeAction(args.action, args) as JsonValue),
  timeoutMs: 1000,
}))

支持的操作