AI.md

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

@@ -1,21 +0,0 @@
-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,32 +1,38 @@
-# 关于本项目
-
-本项目完全由 AI 维护。代码源自 github.com/ssgo/u 的重构。
-
 # @go/time
 
 `@go/time` 是一个致力于“零心智负担”的时间处理库。它通过极简的 API 屏蔽了 Go 原生 `time` 包中繁琐的 Layout 记忆与类型转换，让时间解析、格式化与加减操作变得直观且高效。
 
 ## 🎯 设计哲学
 
-*   **直观 Layout**：使用 `YYYY-MM-DD HH:mm:ss` 等符合直觉的占位符。
+*   **直观 Layout**：不再需要记忆 `2006-01-02 15:04:05`。使用 `YYYY-MM-DD HH:mm:ss` 等符合直觉的占位符。
-*   **强力解析**：`Parse(v)` 自动探测并解析几乎所有时间格式。
+*   **强力解析**：`Parse(v)` 几乎能吞下任何你丢给它的时间数据（时间戳、ISO、RFC3339、中文、JS Date 字符串等），并自动归一化为本地时间。
-*   **DSL 时间算术**：通过简洁的字符串表达式进行复杂的时间偏移计算。
+*   **DSL 时间算术**：通过简洁的字符串表达式（如 `+1Y-2M`）进行复杂的时间偏移计算。
-*   **零摩擦防御**：输入非法格式时绝不 Panic，返回合理的默认值（`time.Now()`）。
+*   **零摩擦防御**：即使输入非法格式，也绝不 Panic，而是返回合理的默认值（如 `time.Now()`），确保服务高可用。
 
-## 🛠 API Reference
+## 🚀 核心特性
 
-### 核心函数
+### 1. 强力解析 `Parse(v any)`
+不再需要 layout，`Parse` 会自动探测以下格式并返回 `time.Time`。
 
-- `func Parse(v any) time.Time`：全能解析。支持时间戳(s/ms/us/ns)、ISO、RFC3339、中文、JS Date 等。结果统一归一化为 `time.Local`。
+**支持格式清单：**
-- `func Format(layout string, v any) string`：人性化格式化。支持 `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, `ms`, `ZZ` 等占位符。
+- **时间戳**: 10位(秒)、13位(毫秒)、16位(微秒)、19位(纳秒) 自动识别。
-- `func Add(expr string, v any) time.Time`：时间计算 DSL。支持 `Y, M, D, h, m, s, ms, us, ns` 组合（如 `+1Y-2M`）。
+- **标准日期**: `YYYY-MM-DD`, `YYYY/MM/DD`, `YYYY.01.02` (支持短年份如 `24-01-02`)。
+- **标准时间**: `YYYY-MM-DD HH:mm:ss`, `YYYY-MM-DDTHH:mm:ss.SSS` (支持空格或 `T` 分隔)。
+- **ISO/RFC3339**: `2024-01-01T00:00:00Z`, `2024-01-01T00:00:00+08:00`。
+- **紧凑格式**: `20240101153045`, `20240101`。
+- **中文格式**: `2024年01月01日 15点30分`, `下午3点`, `15时30分` (缺失部分自动补全)。
+- **常见 Web 格式**: JS Date 字符串, HTTP Header (RFC1123)。
 
-### 快捷助手
+**时区处理规则：**
+- **归一化**: 所有带时区信息的输入（如 UTC 或 +08:00）在解析后都会自动转换为当前服务器的 **`time.Local`**。
+- **无时区输入**: 默认视为 `time.Local`。
 
-- `func Now() time.Time`
+### 2. 语义化格式化 `Format(layout, v)`
-- `func Today() time.Time`：今日 00:00:00。
+支持直观占位符：`YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, `ms`, `ZZ` (时区偏移)。
-- `func Yesterday() time.Time`：昨日 00:00:00。
+
-- `func Tomorrow() time.Time`：明日 00:00:00。
+### 3. 时间加减 DSL `Add(expr, v)`
+- **单位**: `Y`(年), `M`(月), `D`(天), `h`, `m`, `s`, `ms`, `us`, `ns`。
+- **示例**: `+1Y-2M` (加一年减两个月), `-1D` (昨天), `+1h30m` (90分钟后)。
 
 ## 📦 安装
 
@@ -39,12 +45,12 @@ go get apigo.cc/go/time
 ```go
 import "apigo.cc/go/time"
 
-// 1. 自动解析
+// 自动探测并转为本地时间
 tm := time.Parse("2025-06-23T15:30:45Z") 
 
-// 2. 直观格式化
+// 直观格式化
 fmt.Println(time.Format("YYYY-MM-DD HH:mm", tm))
 
-// 3. 语义加减
+// 语义加减
 nextMonth := time.Add("+1M", tm)
 ```

go.mod

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

go.sum

@@ -1,5 +1,7 @@
-apigo.cc/go/cast v1.0.2 h1:L9cbD6gOxQdUTwLJz8aJlV7L1df7CH11N80qKhb1QTk=
+apigo.cc/go/cast v0.0.0-20260421175230-2d8130855c03 h1:TsZ8lqMhSJfvp7bAX6gAfSlr7zNNz5zb5wU8rX2Jhng=
-apigo.cc/go/cast v1.0.2/go.mod h1:vh9ZqISCmTUiyinkNMI/s4f045fRlDK3xC+nPWQYBzI=
+apigo.cc/go/cast v0.0.0-20260421175230-2d8130855c03/go.mod h1:vh9ZqISCmTUiyinkNMI/s4f045fRlDK3xC+nPWQYBzI=
+apigo.cc/go/cast v1.0.0 h1:MhkWBDMq8ewAxn5PYHUlIuwpfsW5bQS6ueptBkim5hc=
+apigo.cc/go/cast v1.0.0/go.mod h1:vh9ZqISCmTUiyinkNMI/s4f045fRlDK3xC+nPWQYBzI=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=