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())
+    ```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssgo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,7 @@
+# 关于本项目
+
+本项目完全由 AI 维护。代码源自 github.com/ssgo/u 的重构。
+
 # @go/time
 
 `@go/time` 是一个致力于“零心智负担”的时间处理库。它通过极简的 API 屏蔽了 Go 原生 `time` 包中繁琐的 Layout 记忆与类型转换，让时间解析、格式化与加减操作变得直观且高效。

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