truetime

确保跨 UTC、服务器时间、NTP 源时间、用户本地时间和任意时区的实时准确调度和规划。用于计时器、提醒、cron 计划、X 分钟或月或年计算、绝对时间戳转换、中国农历日期感知和跨时区协调。强制执行精确的持续时间保真度，以便用户值永远不会被示例值替换，首先计算 UTC 中的目标时间，并在执行前验证增量。

## 概述（中文）

确保跨 UTC、服务器时间、NTP 源时间、用户本地时间和任意时区的实时准确调度和规划。用于计时器、提醒、cron 计划、X 分钟或月或年计算、绝对时间戳转换、中国农历日期感知和跨时区协调。强制执行精确的持续时间保真度，以便用户值永远不会被示例值替换，首先计算 UTC 中的目标时间，并在执行前验证增量。

## 原文

# TrueTime

Use this skill to avoid time mistakes caused by stale examples, wrong units, timezone drift, or DST confusion.

## Non-Negotiable Rules

- Treat user-provided duration values as authoritative.
- Never copy numeric values from examples into real execution.
- Read current time from the runtime clock before calculating.
- Compute canonical target time in UTC first.
- Convert for display second (server timezone, user timezone, other timezone).
- Ask for clarification when timezone context is missing and outcome can change.

## Required Workflow

1. Extract timing intent exactly.
   - Capture literal phrase, value, unit, timezone hint, and target date/time.
   - Keep the original requested value unchanged (for example `1 minute` stays `1 minute`).
2. Read current real time.
   - Use the bundled script for deterministic calculations:
     - Relative: `node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai`
     - Relative (calendar units): `node {baseDir}/scripts/true_time.mjs --plus 1month2weeks --user-tz America/New_York --calendar-tz America/New_York`
     - Absolute: `node {baseDir}/scripts/true_time.mjs --target 2026-02-17T09:30:00 --target-tz Asia/Shanghai --user-tz America/Los_Angeles`
     - NTP time source: `node {baseDir}/scripts/true_time.mjs --plus 1h --time-source ntp`
3. Parse the expression into one precise delta or one precise absolute timestamp.
4. Compute UTC target first.
5. Convert UTC target to server/user/other requested timezone for presentation.
6. Verify the result before execution.
   - Confirm `target_utc - now_utc` equals requested delta.
   - Confirm timezone offset conversion is consistent.
7. Execute schedules using UTC unless the target scheduler explicitly needs local timezone.
8. Report both absolute and relative interpretation in the final response.

## Relative Time Guardrails

- Accept explicit units only:
  - milliseconds: `ms`, `msec`, `msecs`, `millisecond`, `milliseconds`
  - seconds: `s`, `sec`, `second`, `seconds`
  - minutes: `m`, `min`, `minute`, `minutes`
  - hours: `h`, `hr`, `hour`, `hours`
  - days: `d`, `day`, `days`
  - weeks: `w`, `week`, `weeks`
  - months: `mo`, `mon`, `month`, `months`
  - years: `y`, `yr`, `year`, `years`
  - decades: `decade`, `decades`
  - centuries: `century`, `centuries`
- Reject ambiguous units instead of guessing.
- All units support decimal values, including calendar units.
  - Examples: `1.5m`, `0.25h`, `2.5day`, `250.5ms`, `1.5month`, `0.1year`, `0.5decade`, `0.01century`.
  - Decimal separator `.` is preferred; `,` is accepted as input and normalized.
- Fixed-unit decimals are computed to millisecond precision.
- Calendar-unit policy:
  - `month/year/decade/century` are calendar-aware, not fixed seconds.
  - Calendar arithmetic uses `--calendar-tz` (fallback: user timezone -> server timezone).
  - Decimal calendar values are split into integer and fractional parts.
  - Integer months use calendar shift; fractional months use the shifted month length to compute milliseconds.
  - End-of-month handling clamps to the last valid day (for example Jan 31 + 1 month -> Feb 28/29).
- Keep verification examples explicit:
  - `1.5m = 90s`
  - `250ms = 0.25s`
  - `1m = 60s`
  - `1h30m = 5400s`
  - `2d = 172800s`
  - `1.5year = 18 months`
  - `1decade = 10 years`
  - `0.5decade = 5 years`
  - `1century = 100 years`
  - `0.01century = 1 year`

## Absolute Time Guardrails

- Prefer IANA timezone names (`Asia/Shanghai`, `America/Los_Angeles`, `UTC`).
- Avoid ambiguous abbreviations (`CST`, `IST`) unless user confirms meaning.
- If user gives a naive datetime with no timezone, ask once or apply an explicit assumption.
- For DST transition windows, state that the chosen timezone rules were applied.

## Timezone Catalog and Customization

- List all available runtime timezones:
  - `node {baseDir}/scripts/true_time.mjs --list-timezones`
- Filter common choices quickly:
  - `node {baseDir}/scripts/true_time.mjs --list-timezones | rg -i '^(UTC|Asia/(Shanghai|Tokyo|Kolkata)|America/(Los_Angeles|New_York)|Europe/(London|Paris|Berlin))$'`
- User custom timezone:
  - Accept any valid IANA timezone from `--list-timezones`.
  - Pass user timezone via `--user-tz <IANA>`.
  - If user timezone is unknown, ask before executing time-sensitive actions.

Common timezones to use in examples and user-facing confirmations:

- `UTC` (no DST)
- `Asia/Shanghai` (Beijing time, UTC+08:00, no DST)
- `Asia/Tokyo` (Tokyo time, UTC+09:00, no DST)
- `Asia/Kolkata` (India time, UTC+05:30, no DST)
- `America/Los_Angeles` (US West: PST UTC-08:00 / PDT UTC-07:00, DST applies)
- `America/New_York` (US East: EST UTC-05:00 / EDT UTC-04:00, DST applies)
- `America/Chicago` (US Central: CST UTC-06:00 / CDT UTC-05:00, DST applies)
- `America/Denver` (US Mountain: MST UTC-07:00 / MDT UTC-06:00, DST applies)
- `America/Phoenix` (Arizona: MST UTC-07:00, typically no DST)
- `America/Anchorage` (Alaska: AKST UTC-09:00 / AKDT UTC-08:00, DST applies)
- `Pacific/Honolulu` (Hawaii: HST UTC-10:00, no DST)
- `Europe/London` (UK: GMT UTC+00:00 / BST UTC+01:00, DST applies)
- `Europe/Paris` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
- `Europe/Berlin` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
- `Europe/Amsterdam` (CET UTC+01:00 / CEST UTC+02:00, DST applies)

## DST and Standard-Time Rules

- Never assume fixed offsets for DST regions (`America/*`, many `Europe/*`).
- Always compute with the actual target date, not "current offset."
- For DST fall-back overlaps (ambiguous local time), require explicit offset:
  - `2026-11-01T01:30:00` in `America/Los_Angeles` is ambiguous.
  - Ask user to choose `-07:00` (before fallback) or `-08:00` (after fallback), or provide explicit offset in `--target`.
- For DST spring-forward gaps (invalid local time), require correction:
  - `2026-03-08T02:30:00` in `America/Los_Angeles` does not exist.
  - Ask user to use a valid local time (for example `01:30` or `03:30`).
- Prefer explicit-offset absolute targets when DST risk is high:
  - `--target 2026-11-01T01:30:00-07:00`
  - `--target 2026-11-01T01:30:00-08:00`

## Chinese Lunar Calendar

- This tool outputs Chinese lunar datetime fields by default:
  - `lunar_timezone` (default `Asia/Shanghai`, configurable via `--lunar-tz`)
  - `now_lunar`
  - `target_lunar`
- Use these fields when the user asks for Chinese lunar context.
- For execution/scheduling, still use Gregorian UTC fields as canonical.
- If a user gives only lunar date text and no Gregorian equivalent, ask for confirmation or a Gregorian target before execution.

## Time Source Policy (Server vs NTP)

- Default time source is server clock (`--time-source server`).
- If user explicitly requests "do not use server time", switch to public NTP:
  - `--time-source ntp`
- Optional NTP controls:
  - `--ntp-server <host>` (repeatable or comma-separated)
  - `--ntp-timeout-ms <ms>`
- NTP mode example:
  - `node {baseDir}/scripts/true_time.mjs --plus 30m --time-source ntp --ntp-server time.google.com`
- If all NTP servers fail, stop and report failure instead of silently falling back to server time.

## Mandatory Integration Points

Use TrueTime calculations before any of the following:

- Cron operations (`cron add`, `cron update`, `cron wake`, `cron run`) when time or schedule is involved.
- Calendar operations (create/update events, convert invite times, multi-timezone meeting planning).
- Reminder operations (in X minutes/hours, tomorrow at HH:mm, next weekday, repeating reminders).
- Planning tasks that include ETA, deadline conversion, or cross-timezone commitments.

## Server Execution Policy

- Persist canonical time as UTC (`target_utc_iso` and optionally epoch seconds).
- Include human-facing fields for user timezone and server timezone.
- If the scheduler supports timezone-aware execution, pass t