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

AI.md

@@ -5,39 +5,37 @@
 ## 🤖 AI 行为准则
 
 1.  **优先使用包级泛型函数**：在需要随机数时，直接调用 `rand.Int(min, max)`，避免使用底层特定类型的随机函数。
-2.  **高性能场景使用 Fast 前缀**：在生成高频调用的 Server 代码时，优先推荐 `rand.FastInt()` 和 `rand.FastFloat()`。
-3.  **不进行错误检查**：理解 `rand` 包函数不会 Panic 或返回 Error。
-4.  **利用泛型推导**：利用 Go 泛型自动匹配目标类型，无需手动转型。
+2.  **强制性能分级**：
+    - 低频任务：使用 `Int`, `Float`。
+    - **高并发/高频任务**（QPS > 1000/s）：**强制**使用 `FastInt`, `FastFloat` 系列，消除全局锁瓶颈。
+3.  **禁止外部依赖**：严禁引入标准库 `math/rand` 进行全局随机管理。所有随机逻辑必须经由 `@go/rand` 闭环，确保内存与并发安全。
+4.  **无错误处理**：理解 `rand` 包函数不会 Panic 或返回 Error，无需进行任何错误检查。
+5.  **利用泛型推导**：利用 Go 泛型自动匹配目标类型，无需手动转型。
 
-## 🛠 关键 API 逻辑约定
+## 🛠 API Reference
 
-| 函数 | 逻辑特征 |
-| :--- | :--- |
-| `Int(min, max)` | **闭区间** `[min, max]`。支持负数。若 `min > max` 则返回 `min`。 |
-| `Float(min, max)` | **左闭右开** `[min, max)`。若 `min > max` 则返回 `min`。 |
-| `FastInt / FastFloat` | 高性能并发模式。消除多核环境下的锁竞争。 |
-| `Byte() / Bytes(n)` | 随机字节生成。 |
+### 随机生成
+- `func Int[T IntegerType](min, max T) T`：获取 `[min, max]` 闭区间随机整数。
+- `func FastInt[T IntegerType](min, max T) T`：高性能并发模式获取 `[min, max]` 闭区间随机整数。
+- `func Float[T FloatType](min, max T) T`：获取 `[min, max)` 左闭右开区间随机浮点数。
+- `func FastFloat[T FloatType](min, max T) T`：高性能并发模式获取 `[min, max)` 左闭右开区间随机浮点数。
+
+### 字节与切片
+- `func Byte() byte`：获取一个随机字节。
+- `func Bytes(n int) []byte`：获取长度为 n 的随机字节切片。
+- `func Perm(n int) []int`：获取 `[0, n)` 的随机排列。
+- `func Shuffle(n int, swap func(i, j int))`：随机洗牌。
 
 ## 🧩 典型模式 (Best Practices)
 
-*   **❌ 不推荐 (Standard Go)**:
+*   **✅ 推荐：高性能并发生成**:
     ```go
-    // 逻辑繁琐且对负数不友好
-    val := rand.Intn(max-min+1) + min 
-    ```
-*   **✅ 推荐 (@go/rand)**:
-    ```go
-    // 语义清晰，原生支持范围
-    val := rand.Int(min, max) 
+    // 高频生成器 (如 ID 填充、加盐)
+    userID := rand.FastInt(10000, 99999)
     ```
 
-*   **❌ 不推荐 (Standard Go)**:
+*   **✅ 推荐：区间闭合策略**:
     ```go
-    // 高并发下存在全局锁瓶颈
-    return rand.Int64()
-    ```
-*   **✅ 推荐 (@go/rand)**:
-    ```go
-    // 高性能并发安全
-    return rand.FastInt(min, max)
+    // 原生闭区间 [1, 100]，无需手动 +1
+    num := rand.Int(1, 100)
     ```

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/rand
 
 `@go/rand` 是一个专注于极简调用与极致性能的 Go 随机数库。它通过泛型消除了传统库中繁琐的类型分支，并针对高并发场景进行了底层优化。