From 7d17b20a190ed35be93d1e9b2ab8e067edbf319f Mon Sep 17 00:00:00 2001
From: AI Engineer <ai@apigo.cc>
Date: Thu, 23 Apr 2026 21:48:38 +0800
Subject: [PATCH] docs(crypto-sm): update API reference and AI guidelines for
 crypto-sm

---
 AI.md     | 65 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 README.md |  5 +++--
 2 files changed, 60 insertions(+), 10 deletions(-)

diff --git a/AI.md b/AI.md
index e66ab38..da78a9d 100644
--- a/AI.md
+++ b/AI.md
@@ -2,12 +2,61 @@
 
 本索引供 AI 模型理解 `@go/crypto-sm` 的逻辑，以确保代码与 `@go/crypto` 行为一致。
 
-## 🤖 AI 行为准则
-1. **接口对齐**：SM2/SM4 必须实现 `@go/crypto` 定义的非对称与对称加密接口。
-2. **内存闭环**：所有算法构造必须默认支持 `AndEraseKey` 范式。
-3. **静默原则**：解密函数推荐使用 `DecryptBytesN`（静默模式）。
+## 🛠 API Reference
 
-## 🛠 关键算法约定
-- SM2 签名强制使用 `sm2` 特有的签名接口。
-- SM4 CBC/GCM 使用 `gmsm` 底层包，但 API 必须完全遵循 `Symmetric` 的设计。
-- 所有输出不得包含调试日志。
+### SM2 (国密非对称)
+- `func NewSM2(priv, pub *safe.SafeBuf) (*crypto.Asymmetric, error)`
+- `func NewSM2AndEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
+- `func NewSM2WithOutEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
+- `func GenerateSM2KeyPair() ([]byte, []byte, error)`
+- *注：SM2 继承 `crypto.Asymmetric` 接口，支持该结构下所有加解密、签名及 Must/Try 方法。*
+
+### SM3 (国密摘要)
+- `func Sm3(data ...[]byte) []byte`
+- `func Sm3ToHex(data []byte) string`
+- `func Sm3ToBase64(data []byte) string`
+- `func Sm3ToUrlBase64(data []byte) string`
+
+### SM4 (国密对称)
+- `func NewSM4CBC(key, iv *safe.SafeBuf) (*crypto.Symmetric, error)`
+- `func NewSM4CBCAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
+- `func NewSM4CBCWithOutEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
+- `func NewSM4GCM(key, iv *safe.SafeBuf) (*crypto.Symmetric, error)`
+- `func NewSM4GCMAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
+- `func NewSM4GCMWithOutEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
+- *注：SM4 继承 `crypto.Symmetric` 接口，支持该结构下所有加解密及 Must/Try 方法。*
+
+## 🤖 AI 行为准则
+
+1.  **内存安全优先**：**首选 `SafeBuf` 接口**。在处理敏感数据（如密钥、明文）时，强制优先使用 `SafeBuf` 避免明文在内存中暴露。
+2.  **接口对齐**：必须实现 `@go/crypto` 定义的非对称与对称加密接口。
+3.  **闭环义务**：任何构造的 `Asymmetric` 或 `Symmetric` 对象必须由 AI 生成 `defer obj.Close()` 代码。
+4.  **鲁棒性优先**：处理配置或业务数据解密时，优先使用 `Must` 或 `Try` 系列 API。
+
+## 🛠 关键 API 逻辑约定
+
+| 任务 | 推荐 API | 逻辑特征 |
+| :--- | :--- | :--- |
+| **敏感数据处理** | `Xxx(safe.SafeBuf)` | **首选**，直接在内存受控空间操作。 |
+| **错误容忍** | `MustXxx` / `TryDecrypt` | `Must` 用于忽略错误；`TryDecrypt` 解密失败时回退明文。 |
+| **国密合规** | `SMx` 系列 | 完全遵循 @go/crypto 的架构设计。 |
+
+## 🧩 典型模式 (Best Practices)
+
+*   **✅ 安全处理 (SafeBuf 优先)**:
+    ```go
+    // 使用 SafeBuf 保护敏感数据
+    sb := safe.NewSafeBuf(sensitiveData)
+    encrypted, _ := sm4.Encrypt(sb)
+    // 解密回受保护的 SafeBuf
+    decSb, _ := sm4.Decrypt(encrypted)
+    defer decSb.Close()
+    ```
+
+*   **✅ 鲁棒性业务 (Must/Try 模式)**:
+    ```go
+    // 解密配置信息，失败时自动返回原明文
+    config := sm4.TryDecrypt(configData)
+    // 必须执行签名
+    sig := sm2.MustSign(data)
+    ```
diff --git a/README.md b/README.md
index 344c656..9960d18 100644
--- a/README.md
+++ b/README.md
@@ -17,17 +17,18 @@
 - `func NewSM2AndEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
 - `func NewSM2WithOutEraseKey(priv, pub []byte) (*crypto.Asymmetric, error)`
 - `func GenerateSM2KeyPair() ([]byte, []byte, error)`
-- *注：SM2 继承 `Asymmetric` 接口，支持 `Sign`/`Verify`/`Encrypt`/`Decrypt`。*
+- *注：SM2 继承 `Asymmetric` 接口，支持所有 `crypto.Asymmetric` 方法 (含 `Must` 和 `Try` 系列)。*
 
 ### SM3 (国密摘要)
 - `func Sm3(data ...[]byte) []byte`
 - `func Sm3ToHex(data []byte) string`
 - `func Sm3ToBase64(data []byte) string`
+- `func Sm3ToUrlBase64(data []byte) string`
 
 ### SM4 (国密对称)
 - `func NewSM4CBCAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
 - `func NewSM4GCMAndEraseKey(key, iv []byte) (*crypto.Symmetric, error)`
-- *注：SM4 继承 `Symmetric` 接口，支持 `EncryptBytes`/`DecryptBytes`。*
+- *注：SM4 继承 `Symmetric` 接口，支持所有 `crypto.Symmetric` 方法 (含 `Must` 和 `Try` 系列)。*
 
 ## 📦 安装
 ```bash