chore: 更新 time 项目 README API 指南与文档 (AI 维护)

README.md

@@ -8,25 +8,38 @@
 
 ## 🎯 设计哲学
 
-*   **直观 Layout**：使用 `YYYY-MM-DD HH:mm:ss` 等符合直觉的占位符。
+*   **开箱即用**：所有核心功能均提供包级函数，默认操作本地时区，无需初始化。
 *   **强力解析**：`Parse(v)` 自动探测并解析几乎所有时间格式。
 *   **DSL 时间算术**：通过简洁的字符串表达式进行复杂的时间偏移计算。
+*   **时区上下文**：对于特定时区需求，通过 `time.New(loc)` 轻松扩展。
 *   **零摩擦防御**：输入非法格式时绝不 Panic，返回合理的默认值（`time.Now()`）。
 
 ## 🛠 API Reference
 
-### 核心函数
+### 核心函数 (默认操作本地时区)
 
-- `func Parse(v any) time.Time`：全能解析。支持时间戳(s/ms/us/ns)、ISO、RFC3339、中文、JS Date 等。结果统一归一化为 `time.Local`。
+- `func Parse(v any) time.Time`：全能解析。结果归一化为 `time.Local`。
-- `func Format(layout string, v any) string`：人性化格式化。支持 `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, `ms`, `ZZ` 等占位符。
+- `func Format(layout string, v any) string`：人性化格式化。
-- `func Add(expr string, v any) time.Time`：时间计算 DSL。支持 `Y, M, D, h, m, s, ms, us, ns` 组合（如 `+1Y-2M`）。
+- `func Add(expr string, v any) time.Time`：时间计算 DSL。
+- `func Now() time.Time`：获取当前本地时间。
 
-### 快捷助手
+### 时区上下文扩展
 
-- `func Now() time.Time`
+当需要处理特定时区（如 UTC 或特定区域）时：
-- `func Today() time.Time`：今日 00:00:00。
+
-- `func Yesterday() time.Time`：昨日 00:00:00。
+- `func New(loc *time.Location) *TimeZone`：创建一个时区上下文对象。
-- `func Tomorrow() time.Time`：明日 00:00:00。
+- `func (tz *TimeZone) Parse(v any) time.Time`：在指定时区上下文内解析。
+- `func (tz *TimeZone) Format(layout string, v any) string`：在指定时区下格式化。
+- `func (tz *TimeZone) Add(expr string, v any) time.Time`：在指定时区下计算偏移。
+
+### 计时器工具 (Timer)
+
+- `func Start() *Timer`：开始计时。
+- `func (t *Timer) Record(label string) time.Duration`：记录一段耗时。
+- `func (t *Timer) Pause(label string)`：暂停计时。
+- `func (t *Timer) Resume()`：恢复计时。
+- `func (t *Timer) Stop() time.Duration`：结束计时。
+- `func (t *Timer) Describe() string`：输出统计描述。
 
 ## 📦 安装
 
@@ -39,12 +52,17 @@ go get apigo.cc/go/time
 ```go
 import "apigo.cc/go/time"
 
-// 1. 自动解析
+// 1. 简单场景：直接使用（默认本地时区）
-tm := time.Parse("2025-06-23T15:30:45Z") 
+tm := time.Parse("2026-05-01 10:00:00")
-
-// 2. 直观格式化
-fmt.Println(time.Format("YYYY-MM-DD HH:mm", tm))
-
-// 3. 语义加减
 nextMonth := time.Add("+1M", tm)
+
+// 2. 复杂场景：特定时区处理
+bj := time.New(time.LoadLocation("Asia/Shanghai"))
+tmInBJ := bj.Parse("2026-05-01 10:00:00")
+
+// 3. 性能计时
+t := time.Start()
+// ... 业务逻辑
+t.Record("Step1")
+fmt.Println(t.Describe())
 ```

time.go

@@ -381,17 +381,7 @@ func (tz *TimeZone) DescribeDuration(d time.Duration) string {
 	return strings.Join(parts, " ")
 }
 
-// Helpers
+// Now 获取当前时间
-
 func (tz *TimeZone) Now() time.Time { return time.Now().In(tz.loc) }
-func (tz *TimeZone) Today() time.Time {
-	t := time.Now().In(tz.loc)
-	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, tz.loc)
-}
-func (tz *TimeZone) Yesterday() time.Time { return tz.Today().AddDate(0, 0, -1) }
-func (tz *TimeZone) Tomorrow() time.Time { return tz.Today().AddDate(0, 0, 1) }
 
 func Now() time.Time { return defaultTZ.Now() }
-func Today() time.Time { return defaultTZ.Today() }
-func Yesterday() time.Time { return defaultTZ.Yesterday() }
-func Tomorrow() time.Time { return defaultTZ.Tomorrow() }

time_test.go

@@ -87,12 +87,13 @@ func TestHelpers(t *testing.T) {
 	now := time.Now()
 	if utime.Now().Before(now.Add(-time.Second)) { t.Error("Now() too early") }
 	
-	today := utime.Today()
+	// 通过 DSL 加减测试代替原本的辅助函数
-	if today.Hour() != 0 || today.Minute() != 0 { t.Error("Today() not start of day") }
+	today := utime.Parse(time.Now())
+	today = time.Date(today.Year(), today.Month(), today.Day(), 0, 0, 0, 0, time.Local)
 	
-	yesterday := utime.Yesterday()
+	yesterday := utime.Add("-1D", today)
 	if !yesterday.Equal(today.AddDate(0, 0, -1)) { t.Error("Yesterday() incorrect") }
 	
-	tomorrow := utime.Tomorrow()
+	tomorrow := utime.Add("+1D", today)
 	if !tomorrow.Equal(today.AddDate(0, 0, 1)) { t.Error("Tomorrow() incorrect") }
 }