用途
本工具面向使用 kotlinx-datetime 的 Kotlin 多平台项目，提供一组具名包装函数，把 instant（时间线上的一个点）与 local date-time（不带时区的墙钟字段）之间每次都要指定时区的转换收敛为少量可复用的辅助函数，同时整理在与时间处理相关的常见陷阱与核查手段。
主要能力（据资料中的示例）
资料给出的辅助函数形态包括：
now()：取系统默认时区下的当前LocalDateTime。epochMillisToLocalDateTime(epochMillis)：从 epoch 毫秒构造LocalDateTime。LocalDateTime.plusSeconds(seconds)：转成 instant、在 instant 上做算术、再转回本地时间。LocalDateTime.isBefore(other)：基于墙钟字段的比较。
资料强调 plusSeconds 这种“转到 instant、运算、再转回”的写法应当被复制到其他辅助函数中。
使用方式
资料未提供安装命令、依赖坐标或具体 API 清单，暂未提供。示例代码以 Kotlin 源码片段形式出现，涉及 TimeZone.currentSystemDefault()、Clock.System.now()、Instant.fromEpochMilliseconds、toLocalDateTime、toInstant、DateTimeUnit 等 kotlinx-datetime 类型与函数。
适用场景
适用于需要统一“瞬时值与本地时间”转换规则的 Kotlin 多平台代码，以及需要审查时区一致性、时钟读取入口、共享源集可移植性的工程。
资料中列出的陷阱与限制
- 时区不一致导致存储偏移：辅助函数读取设备时区，而持久化类型转换器按固定 UTC 写入时，值会整体偏移；设备偏移变化（旅行、夏令时切换）后暴露为过期判断提前或延后、“最近 7 天”窗口漂移。建议统一规则：以 epoch 毫秒存储 instant，仅在展示时转本地。
- 墙钟比较不是时间点比较：
LocalDateTime上的<是按年、月、日、时等字段的字典序比较，仅当两个值出自同一时区时才正确；命名容易让人误以为是时间线比较。 - 日历运算与经过时间运算不同：
this.date.minus(x, DateTimeUnit.DAY).atTime(this.time)表示“同一钟点、x 天前”，不是 x×24 小时；二者在时钟切换时每年差一小时，规则变更的时区差更多。 - 相对时间格式化器写成 composable 的局限：无法脱离组合做单元测试，无法在 view model、通知构建器或小组件中使用；且在组合期间读时钟没有可失效来源，标签会冻结。建议拆成接收
(from: Instant, to: Instant)的纯函数返回小型 sealed 结果，再由薄 composable 映射为字符串资源，并用计时状态驱动to参数。 - Period 的 hours 是分量不是总数：25 小时间隔分解为 days=1、hours=1，而非 hours=25；日期相减得到的纯日期 Period 没有时间分量，hours 恒为零。建议月份与天数取自 Period，单个“几小时前”取自两个 instant 之间的 duration，并按由粗到细排序、明确边界。
- 解析失败返回 0 与成功不可区分：0 是合法值（纪元起点、整点），调用方无法据此分支；建议返回 null 由调用方决定。
- 直接调用系统时钟导致不可测试：模块内部直接读取系统时钟只能靠等待来测试；应通过辅助集读取时钟，并让时钟可替换。
- 共享源集中的 Java 运行时类型：并发时间单位枚举、locale 类型、平台格式化函数均属 Java 运行时类型，共享源集文件引用它们时只能为 Android 与桌面编译，静默排除 native 目标；应放入平台源集，或改用多平台库自身的格式化与普通算术。
核查方法（资料提供）
- 用
grep -rn "TimeZone.UTC" --include='*.kt' .与grep -rn "TimeZone.currentSystemDefault()" --include='*.kt' .找出两套时区规则的冲突点。 - 用
grep -rn "Clock.System.now()" --include='*.kt' .查找绕过辅助集的时钟读取，理想情况只在辅助集内部出现一次。 - 用
find . -path '*/commonMain/*' -name '*.kt' -exec grep -l '^import java\.' {} +查找共享源集中的 Java 运行时导入。 - 用
grep -rn "return 0.0\|return 0L\|return 0$" --include='*.kt' .检查解析器中返回合法零值的位置。 - 将设备时钟跨夏令时边界前移后重新读取已存储行，验证过期判断与日窗口查询是否变化。
限制
资料为经验性说明与代码片段，未给出完整 API、发布状态、支持版本、平台矩阵、许可证或安装方式，这些内容暂未提供。