言时：日期与时间

言时（yanxu-datetime）以不可变值对象表示公历日期、日内时间、固定偏移时区、毫秒精度日期时间和固定时长。稳定版 1.0.0 还提供结构化无异常解析、稳定排序、定时器和可注入时钟，适合编写可重复测试的业务时间逻辑。

版本与安装

yanbao add 言时 \
  --git https://github.com/yanxulang/yanxu-datetime.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言时 = { git = "https://github.com/yanxulang/yanxu-datetime.git", 修订 = "v1.0.0", 版 = "^1.0" }

提交生成的 言序.lock，不要把临时分支或移动修订用作发布依赖。

核心能力：值对象

解析、换区与输出

引「包:言时」为 言时；

定 上海 为 言时.解析RFC3339（「2026-07-16T09:30:00+08:00」）；
定 UTC时刻 为 上海.转UTC（）；

言 上海.转RFC3339（）；
言 UTC时刻.转RFC3339（）；
言 上海.是同一时刻（UTC时刻）；
言 上海.Unix毫秒（）；

解析RFC3339要求 T或t分隔符和明确偏移。解析ISO还允许空格分隔，但同样必须带 Z或 ±HH:mm。转换时区保持 Unix 毫秒不变，只改变本地日期、时间和偏移显示。

不可信文字应使用无异常入口：

定 结果：典 为 言时.尝试解析日期（「2026-02-30」）；

若 结果【「成功」】 则
    言 结果【「值」】；
否则
    言 结果【「错误」】【「代码」】；
终

日期、时间、时区、ISO、RFC 3339、自定义格式和时间段均有对应的 尝试解析…入口。

历法运算与固定时长

定 月末 为 言时.日期（2024，1，31）.加月（1）；
言 月末.转ISO（）；                 # 2024-02-29

定 持续 为 言时.时段（2）.相加（言时.分段（30））；
言 持续.转ISO（）；

定 往返 为 言时.解析时间段（「P1DT2H30M」）；
言 往返.转ISO（）；

加日、加月和加年是历法运算；目标月份没有原日号时会收敛到月末。日期时间的加时间段是固定毫秒运算。时间段语法为 [-]P[nD][T[nH][nM][n[.fff]S]]，明确不接受依赖上下文的年、月和周单位。

自定义格式

定 格式：文 为 「YYYY/MM/DD HH:mm:ss.SSS Z」；
定 文本：文 为 上海.格式化（格式）；
定 往返 为 言时.解析格式（文本，格式，言时.UTC（））；

支持 YYYY、MM、DD、HH、mm、ss、SSS和Z。解析必须包含完整年月日时分秒；SSS和Z可选，缺少Z时使用调用者给出的默认时区。同一令牌不得重复。

排序与资源上限

定 已排：列 为 言时.排序日期时间（来源，真）；
定 小批：列 为 言时.排序日期时间受限（来源，真，200）；

排序按 Unix 毫秒比较，对同一时刻保持输入顺序，并返回新列。默认最多 4096 项；受限入口只能收紧，不能超过库硬上限。

可测试时钟与超时

定 时钟 为 言时.虚拟时钟（0）；
定 定时 为 言时.一次定时器（言时.秒段（5），时钟）；

定时.等待（）；
言 时钟.毫秒（）；                # 5000

法 作业（截止）：文 则
    截止.检查（）；
    # 长循环可在安全点重复检查
    归 「完成」；
终

言 言时.限时（言时.秒段（2），作业，时钟）；

重复定时器会按原计划推进节拍，并以常数步跨过漏失周期，不会把所有遗漏回调集中触发。限时是协作式检查：它不会创建线程，也不能强制中断阻塞中的同步 I/O；需要硬取消时必须结合驱动自身的取消接口。

权限与安全边界

言时是纯言序、零第三方依赖库。清单拒绝文件、网络、TCP、UDP、环境、进程和原生扩展权限；系统时钟只使用言序标准时间 API 读取时间和阻塞等待。

主要边界如下：

• 年份为 1–9999，固定时区偏移为 -14:00–+14:00；
• 时间戳、时钟和时间段使用绝对值不大于 9007199254740991的安全整数毫秒；
• 所有公开解析器与格式器的单个文本上限为 4096 字符；
• RFC 3339 小数秒只接受 1–3 位，并归一化到毫秒；
• 错误使用稳定 YANSHI_代码；完整诊断中的位置和踪迹应先过滤再返回客户端。

已知限制

• 只建模 UTC 与固定偏移，不内置 IANA 时区数据库，也不推测夏令时或历史政策。东八区()不等同于完整的 Asia/Shanghai规则。
• 不表示闰秒，最高精度为毫秒。
• 固定时长不支持年、月、周；这些单位必须在明确的日期上下文中用历法操作处理。
• 虚拟时钟不是安全时间源；鉴权、凭据过期和账务截止应比较可信时钟下的 Unix 时刻。
• 计时、定时器和断点仍是同步进程内能力，不提供跨进程调度。

项目链接

• GitHub 仓库
• 言时 1.0.0 Release