time/AI.md

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