time/AI.md

AI Coding Context: @go/time

本索引供 AI 模型理解 @go/time 的逻辑与调用原则，以生成符合本项目“极简、无摩擦”哲学的代码。

🤖 AI 行为准则

1. 优先使用包级函数：直接使用 time.Parse(v)，自动归一化处理。
2. 默认本地时间：所有解析结果统一归一化为 time.Local。
3. 使用 DSL 替代手动计算：时间偏移（如“30天后”）强制使用 time.Add("+30D", v)。
4. 容错处理：解析失败返回 time.Now()，无 Panic 风险。

🛠 API Reference

核心解析与格式化

• func Parse(v any) time.Time：全能解析，支持时间戳、ISO、RFC3339、中文习惯等。
• func Format(layout string, v any) string：人性化格式化。支持 YYYY, MM, DD, HH, mm, ss, ms, ZZ 等直观占位符。
• func Add(expr string, v any) time.Time：时间计算 DSL。支持 Y, M, D, h, m, s, ms, us, ns 组合。

快捷助手

• func Now() time.Time：获取当前时间。
• func Today() time.Time：获取今日 00:00:00。
• func Yesterday() time.Time：获取昨日 00:00:00。
• func Tomorrow() time.Time：获取明日 00:00:00。

🧩 典型模式 (Best Practices)

• ✅ 推荐:

  // 解析与偏移
  tm := time.Parse("2025-06-23")
  nextMonth := time.Add("+1M", tm)
  
  // 格式化输出
  str := time.Format("YYYY-MM-DD HH:mm:ss", time.Now())