truetime-cn 真正时间（中国）

truetime-cn 是一个中文优先、跨平台的时间精确处理工具。它支持 Claude.ai 沙箱、Claude Code、OpenClaw 及任意 Python ≥ 3.9 环境，且无外部依赖。

本工具会在请求中出现以下任意信号时触发：现在、今天、明天、昨天、刚才、一会儿、稍后等时间词；相对时间：X 分钟/小时/天/周/月/年后、X 个月零 X 天后、半年后；绝对时间：2026 年 9 月 25 日 9 点、中秋节那天；跨时区：北京 X 点在纽约几点、我们和欧洲同事开会；中国节假日：春节、国庆、调休、补班、下周一是不是工作日；农历：农历几号、中秋是几号、春节倒计时、今年闰几月；节气：立春、夏至；长任务规划检查点：这个 deadline 还有多久、按目前进度能赶上吗。

不触发的情况包括：纯历史问题（"1949 年发生了什么"）、已知绝对日期且无需运算（"圣诞节是 12 月 25 日"）。

本工具遵循以下规则：用户给的数值原样保留，不替换成其他单位；必须用脚本读真实时间，绝不基于系统注入日期"估算"；UTC 优先，脚本输出的 target_utc 是规范值；本地时区只用于显示；DST 不猜，脚本会硬错，把错误信息原样转给用户并要求显式 offset；农历仅作显示，执行调度仍用公历 UTC；节假日数据缺失要明示，脚本返回 holiday_data_year_available: false 时，告诉用户"我没有该年节假日数据，仅按周末规则判断"。

调用脚本的方法包括：Claude.ai（用户上传 skill 后）：python3 /mnt/skills/user/truetime-cn/scripts/truetime_cn.py [选项]；Claude Code / OpenClaw / 本地：在 SKILL.md 所在目录运行 python3 ./scripts/truetime_cn.py [选项]。

脚本仅需 Python ≥ 3.9 标准库，农历库 cnlunar（MIT，OPN48 作）已 vendor 到 vendor/cnlunar/，运行时自动加载，无需 pip install 任何东西。

核心命令包括：当前时间（默认北京）python3 ...truetime_cn.py；当前 + 中文摘要 python3 ...truetime_cn.py --human；1.5 个月后 python3 ...truetime_cn.py --plus 1.5month；1 小时 30 分后 python3 ...truetime_cn.py --plus 1h30m；250.5 毫秒后 python3 ...truetime_cn.py --plus 250.5ms；北京 X 点在纽约 python3 ...truetime_cn.py --target 2026-09-25T09:00:00 --target-tz Asia/Shanghai --user-tz America/New_York；用户在洛杉矶时区加 --user-tz America/Los_Angeles；列所有时区 python3 ...truetime_cn.py --list-timezones。

单位约定包括：固定单位：ms、s、m、h、d、w（含全拼 milliseconds、seconds…）；日历单位：mo（month）、y（year）、decade、century；全部支持小数：1.5month、0.1year、0.01century；复合 token：1h30m、1month2weeks；月末钳位：1/31 + 1mo = 2/28 或 2/29。

脚本输出 JSON，必含以下字段：now_utc / target_utc、now_user_tz / target_user_tz、target_server_tz、now_lunar / target_lunar、now_zh_holiday / target_zh_holiday、now_is_workday / target_is_workday、target_holiday_source、delta_milliseconds / delta_seconds、delta_human_zh、holiday_data_year_available、assumptions。

长会话时间漂移检测包括：距上次调脚本超过 15 分钟；用户消息里出现"现在""此刻""当前"等词，且当前是时间敏感任务；任何"还有多久""倒计时""到点没"类问题；用户表达不确定："是吗？""真的？""我感觉时间不对"；跨午夜：上次调用后用户讨论了 30+ 分钟，可能跨日。

DST 错误处理包括：脚本对模糊或不存在的本地时间硬错，原文转给用户；用户："2026年11月1日凌晨1点半的航班，洛杉矶起飞"；脚本错误："DST 模糊时间: 2026-11-01T01:30:00 在 America/Los_Angeles 存在两次..."；你应回复："洛杉矶 11月1日凌晨1:30在夏令时回拨当晚出现两次。请确认航班是回拨前 (PDT, -07:00) 还是回拨后 (PST, -08:00)。"

纯对话兜底（无任何工具时）包括：明确告诉用户："我此刻没有工具能取真实时间，只能基于系统注入的日期 <注入值>。"；时分秒未知，故不要编造："现在大概是下午"；若任务对精度敏感（订票、deadline），反问用户当前精确时间，再做计算；不做跨时区运算（Claude 心算时区不可靠）；让用户提供本地时间；提示用户："启用 Code Execution 后，本 skill 可提供精确时间、农历、中国节假日。"

节假日数据维护包括：data/cn_holidays.json 来自国务院办公厅每年 11 月发布的次年通知；当前内置 2026 年；脚本检测到 holiday_data_year_available: false 时，主动告知用户： "2027 年节假日表尚未内置（国务院办公厅一般在 2026 年 10-11 月发布），目前仅按周末规则判断。"

完整工作流包括：意图提取：从用户文本里抓时间词、单位、时区线索、目标日；调脚本：用上面命令拿 JSON；优先用 UTC 推理：所有比较、排序、调度逻辑都基于 target_utc；回复用本地表达：给用户看 target_user_tz 和 target_lunar.display；节假日要点提示：若 target_zh_holiday 非空或 target_is_workday: false，明确指出；DST 失败要透传：把错误原文给用户，要求显式 offset；跨长对话主动重测：详见上面的"漂移检测"。

触发短语示例（提高自动激活率）包括：verify time accuracy、calculate utc target、set precise reminder、convert to utc、handle timezones、中文时间、农历日期、中国节假日、调休、春节倒计时、跨时区会议、deadline 还有多久、现在几点。