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)

*   **✅ 推荐**:
    ```go
    // 解析与偏移
    tm := time.Parse("2025-06-23")
    nextMonth := time.Add("+1M", tm)

    // 格式化输出
    str := time.Format("YYYY-MM-DD HH:mm:ss", time.Now())
    ```