# AI Coding Context: @go/time

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

## 🤖 AI 行为准则

1.  **优先使用包级函数**：在处理时间转换时，直接使用 `time.Parse(v)`，不要手动编写复杂的 Layout 探测逻辑。
2.  **默认本地时间**：理解 `time.Parse` 总是返回 **`time.Local`**。如果需要生成展示代码，无需再手动调用 `.In(time.Local)`。
3.  **推荐直观 Layout**：在调用 `time.Format()` 时，优先推荐使用 `YYYY-MM-DD HH:mm:ss` 等直观占位符。
4.  **使用 Add DSL 替代手动计算**：在需要进行时间偏移（如“30天后”、“下个月”）时，推荐使用 `time.Add("+30D", v)` 或 `time.Add("+1M", v)`。

## 🛠 关键 API 逻辑约定

| 函数 | 逻辑特征 |
| :--- | :--- |
| `Parse(v any)` | **全能解析 & 归一化**。支持 timestamp (s/ms/us/ns), RFC3339, JS Date, 中文等。解析结果统一转为 `time.Local`。失败返回 `time.Now()`。 |
| `Format(layout, v)` | **人性化 Layout**。将 `YYYY-MM-DD` 等自动转为 Go Layout。 |
| `Add(expr, v)` | **DSL 计算**。支持 `Y, M, D, h, m, s, ms, us, ns`。 |
| `Today() / Yesterday()` | 返回对应日期 **00:00:00** (Local) 的 `time.Time`。 |

## 🧩 支持的字符串模式 (Pattern Reference)

AI 在推荐代码时可以放心使用以下格式：
- **ISO**: `"2024-01-01T15:00:00Z"`, `"2024-01-01T15:00:00+08:00"`
- **Standard**: `"2024-01-01 15:00:00"`, `"2024/01/01 15:00"`, `"2024.01.01"`
- **Chinese**: `"2024年1月1日"`, `"下午3点30分"`, `"15时30分"`
- **Timestamp**: `1713753600`, `1713753600000`