AI: 更新文档索引至 v1.0.3

AI.md

@@ -1,27 +1,35 @@
 # AI Coding Context: @go/time
 
-本索引供 AI 模型理解 `@go/time` 的设计逻辑与调用原则，以生成符合本项目“极简、无摩擦”哲学的代码。
+本索引供 AI 模型理解 `@go/time` 的逻辑与调用原则，以生成符合本项目“极简、无摩擦”哲学的代码。
 
 ## 🤖 AI 行为准则
 
-1.  **优先使用包级函数**：在处理时间转换时，直接使用 `time.Parse(v)`，不要手动编写复杂的 Layout 探测逻辑。
+1.  **优先使用包级函数**：直接使用 `time.Parse(v)`，自动归一化处理。
-2.  **默认本地时间**：理解 `time.Parse` 总是返回 **`time.Local`**。如果需要生成展示代码，无需再手动调用 `.In(time.Local)`。
+2.  **默认本地时间**：所有解析结果统一归一化为 `time.Local`。
-3.  **推荐直观 Layout**：在调用 `time.Format()` 时，优先推荐使用 `YYYY-MM-DD HH:mm:ss` 等直观占位符。
+3.  **使用 DSL 替代手动计算**：时间偏移（如“30天后”）强制使用 `time.Add("+30D", v)`。
-4.  **使用 Add DSL 替代手动计算**：在需要进行时间偏移（如“30天后”、“下个月”）时，推荐使用 `time.Add("+30D", v)` 或 `time.Add("+1M", v)`。
+4.  **容错处理**：解析失败返回 `time.Now()`，无 Panic 风险。
 
-## 🛠 关键 API 逻辑约定
+## 🛠 API Reference
 
-| 函数 | 逻辑特征 |
+### 核心解析与格式化
-| :--- | :--- |
+- `func Parse(v any) time.Time`：全能解析，支持时间戳、ISO、RFC3339、中文习惯等。
-| `Parse(v any)` | **全能解析 & 归一化**。支持 timestamp (s/ms/us/ns), RFC3339, JS Date, 中文等。解析结果统一转为 `time.Local`。失败返回 `time.Now()`。 |
+- `func Format(layout string, v any) string`：人性化格式化。支持 `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, `ms`, `ZZ` 等直观占位符。
-| `Format(layout, v)` | **人性化 Layout**。将 `YYYY-MM-DD` 等自动转为 Go Layout。 |
+- `func Add(expr string, v any) time.Time`：时间计算 DSL。支持 `Y, M, D, h, m, s, ms, us, ns` 组合。
-| `Add(expr, v)` | **DSL 计算**。支持 `Y, M, D, h, m, s, ms, us, ns`。 |
-| `Today() / Yesterday()` | 返回对应日期 **00:00:00** (Local) 的 `time.Time`。 |
 
-## 🧩 支持的字符串模式 (Pattern Reference)
+### 快捷助手
+- `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。
 
-AI 在推荐代码时可以放心使用以下格式：
+## 🧩 典型模式 (Best Practices)
-- **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分"`
+    ```go
-- **Timestamp**: `1713753600`, `1713753600000`
+    // 解析与偏移
+    tm := time.Parse("2025-06-23")
+    nextMonth := time.Add("+1M", tm)
+
+    // 格式化输出
+    str := time.Format("YYYY-MM-DD HH:mm:ss", time.Now())
+    ```

go.mod

@@ -2,6 +2,6 @@ module apigo.cc/go/time
 
 go 1.25.0
 
-require apigo.cc/go/cast v1.0.2
+require apigo.cc/go/cast v1.0.3
 
 require gopkg.in/yaml.v3 v3.0.1 // indirect