@isdk/proxy 0.1.1 → 0.1.2

package/docs/functions/isAllowed.md

@@ -6,16 +6,19 @@
 
 # Function: isAllowed()
 
-> **isAllowed**(`key`, `config?`): `boolean`
+> **isAllowed**(`key`, `config?`, `defaultAllowed?`): `boolean`
 
-Defined in: [utils/isAllowed.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/utils/isAllowed.ts#L15)
+Defined in: [utils/isAllowed.ts:37](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/utils/isAllowed.ts#L37)
 
 判断给定的键是否允许参与缓存指纹计算。
 
-优先级逻辑：
-1. 如果配置了 `include` (白名单)，则只有存在于 `include` 中的键才会被允许。
-2. 否则，如果配置了 `exclude` (黑名单)，则存在于 `exclude` 中的键将被拒绝。
-3. 如果都没有配置，默认允许所有键。
+**优先级逻辑**：
+1. `exclude` 命中 → 返回 `false`（优先级最高，会覆盖前面的结果）
+2. `include` 存在且命中 → 返回 `true`
+3. `include` 存在但不命中 → 返回 `false`
+4. 都没有配置 → 使用 `defaultAllowed`（未传则返回 `undefined`）
+
+**注意**：`include` 和 `exclude` 可以同时配置，此时 `exclude` 优先级更高。
 
 ## Parameters
 
@@ -29,10 +32,34 @@ Defined in: [utils/isAllowed.ts:15](https://github.com/isdk/proxy.js/blob/bed37f
 
 [`KeyFilterConfig`](../interfaces/KeyFilterConfig.md)
 
-过滤配置
+过滤配置，支持 `include`（白名单）和 `exclude`（黑名单）
+
+### defaultAllowed?
+
+`boolean`
+
+当没有配置或配置未命中时的默认值（可选）
 
 ## Returns
 
 `boolean`
 
-是否允许
+是否允许。返回 `boolean` 或 `undefined`（当没有配置且未传 defaultAllowed 时）
+
+## Example
+
+```typescript
+// 无配置
+isAllowed('key'); // undefined
+
+// 白名单
+isAllowed('id', { include: ['id', 'name'] }); // true
+isAllowed('email', { include: ['id', 'name'] }); // false
+
+// 黑名单
+isAllowed('password', { exclude: ['password'] }); // false
+isAllowed('name', { exclude: ['password'] }); // undefined
+
+// 设置默认值
+isAllowed('name', { exclude: ['password'] }, true); // true
+```

package/docs/functions/isGlob.md

@@ -0,0 +1,23 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / isGlob
+
+# Function: isGlob()
+
+> **isGlob**(`str`): `boolean`
+
+Defined in: [utils/matcher.ts:7](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/utils/matcher.ts#L7)
+
+判断一个模式是否为 Glob 模式
+
+## Parameters
+
+### str
+
+`string`
+
+## Returns
+
+`boolean`

package/docs/functions/isMatch.md

@@ -0,0 +1,44 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / isMatch
+
+# Function: isMatch()
+
+> **isMatch**(`pattern`, `value`, `usePrefix`): `boolean`
+
+Defined in: [utils/matcher.ts:25](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/utils/matcher.ts#L25)
+
+通用匹配函数
+
+逻辑优先级：
+1. 如果 pattern 是数组，遵循：(匹配任一正向模式) 且 (不匹配任一负向模式)。
+2. 如果 pattern 是 RegExp 对象，直接使用 regex.test(value)。
+3. 如果 pattern 是 "/regex/flags" 格式的字符串，转为 RegExp 后使用 test。
+4. 如果 pattern 是 Glob 字符串，使用 picomatch 进行匹配。
+5. 否则，根据 usePrefix 参数进行前缀匹配或精确匹配。
+
+## Parameters
+
+### pattern
+
+匹配模式 (RegExp 或 字符串 或 数组)
+
+`string` | `RegExp` | (`string` \| `RegExp`)[]
+
+### value
+
+`string`
+
+要匹配的值
+
+### usePrefix
+
+`boolean` = `false`
+
+是否在普通字符串匹配时启用前缀匹配 (默认为 false，即精确匹配)
+
+## Returns
+
+`boolean`

package/docs/globals.md

@@ -10,8 +10,10 @@
 
 ## Interfaces
 
+- [BodyFilterConfig](interfaces/BodyFilterConfig.md)
 - [CacheEntry](interfaces/CacheEntry.md)
 - [CacheMetadata](interfaces/CacheMetadata.md)
+- [CacheRule](interfaces/CacheRule.md)
 - [FetchWithCacheContext](interfaces/FetchWithCacheContext.md)
 - [FetchWithCacheOptions](interfaces/FetchWithCacheOptions.md)
 - [KeyFilterConfig](interfaces/KeyFilterConfig.md)
@@ -26,4 +28,7 @@
 - [extractData](functions/extractData.md)
 - [fetchWithCache](functions/fetchWithCache.md)
 - [generateCacheKey](functions/generateCacheKey.md)
+- [getSiteConfig](functions/getSiteConfig.md)
 - [isAllowed](functions/isAllowed.md)
+- [isGlob](functions/isGlob.md)
+- [isMatch](functions/isMatch.md)

package/docs/interfaces/BodyFilterConfig.md

@@ -0,0 +1,77 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / BodyFilterConfig
+
+# Interface: BodyFilterConfig
+
+Defined in: [types.ts:13](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L13)
+
+缓存键过滤配置
+
+用于定义在生成缓存指纹时，哪些字段应该被包含或排除。
+
+## Extends
+
+- [`KeyFilterConfig`](KeyFilterConfig.md)
+
+## Properties
+
+### exclude?
+
+> `optional` **exclude**: (`string` \| `RegExp`)[]
+
+Defined in: [types.ts:10](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L10)
+
+排除（黑名单）：用于排除像 `timestamp`、`nonce` 等干扰缓存命中的动态字段。支持字符串、Glob 模式或正则表达式。
+
+#### Inherited from
+
+[`KeyFilterConfig`](KeyFilterConfig.md).[`exclude`](KeyFilterConfig.md#exclude)
+
+***
+
+### extract?
+
+> `optional` **extract**: `string` \| `RegExp`
+
+Defined in: [types.ts:18](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L18)
+
+用于非 JSON (文本) Body 的提取正则表达式。
+如果包含捕获组，则提取捕获组内容作为指纹；否则提取整个匹配部分。
+
+***
+
+### include?
+
+> `optional` **include**: (`string` \| `RegExp`)[]
+
+Defined in: [types.ts:8](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L8)
+
+仅包含（白名单）：如果设置，只有这些字段会参与 Key 的计算。支持字符串、Glob 模式或正则表达式。
+
+#### Inherited from
+
+[`KeyFilterConfig`](KeyFilterConfig.md).[`include`](KeyFilterConfig.md#include)
+
+***
+
+### maxLength?
+
+> `optional` **maxLength**: `number`
+
+Defined in: [types.ts:25](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L25)
+
+用于正则匹配/提取 Body 时的最大长度限制，默认 1024 (1KB)
+
+***
+
+### sort?
+
+> `optional` **sort**: `boolean`
+
+Defined in: [types.ts:23](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L23)
+
+是否对提取出的捕获组进行排序。
+开启后可解决 Body 中参数顺序不一致导致的指纹失效问题。

package/docs/interfaces/CacheEntry.md

@@ -6,7 +6,7 @@
 
 # Interface: CacheEntry
 
-Defined in: [types.ts:55](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L55)
+Defined in: [types.ts:137](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L137)
 
 完整的缓存条目
 
@@ -20,7 +20,7 @@ Defined in: [types.ts:55](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **body**: `any`
 
-Defined in: [types.ts:57](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L57)
+Defined in: [types.ts:139](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L139)
 
 响应体数据：小文件为 Buffer，大文件为可读流
 
@@ -30,7 +30,7 @@ Defined in: [types.ts:57](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **headers**: `Record`\<`string`, `string`\>
 
-Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L39)
+Defined in: [types.ts:121](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L121)
 
 响应头对象
 
@@ -44,7 +44,7 @@ Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **method**: `string`
 
-Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L45)
+Defined in: [types.ts:127](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L127)
 
 原始请求方法
 
@@ -58,7 +58,7 @@ Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **policy**: `any`
 
-Defined in: [types.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L41)
+Defined in: [types.ts:123](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L123)
 
 http-cache-semantics 策略对象，包含 TTL 和缓存指令
 
@@ -72,7 +72,7 @@ http-cache-semantics 策略对象，包含 TTL 和缓存指令
 
 > **size**: `number`
 
-Defined in: [types.ts:49](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L49)
+Defined in: [types.ts:131](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L131)
 
 Body 的字节长度，用于精确区分“空响应”与“未入内存的大响应”
 
@@ -86,7 +86,7 @@ Body 的字节长度，用于精确区分“空响应”与“未入内存的大
 
 > **status**: `number`
 
-Defined in: [types.ts:37](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L37)
+Defined in: [types.ts:119](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L119)
 
 HTTP 状态码
 
@@ -100,7 +100,7 @@ HTTP 状态码
 
 > **timestamp**: `number`
 
-Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L47)
+Defined in: [types.ts:129](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L129)
 
 缓存写入时的时间戳
 
@@ -114,7 +114,7 @@ Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **url**: `string`
 
-Defined in: [types.ts:43](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L43)
+Defined in: [types.ts:125](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L125)
 
 原始请求 URL
 

package/docs/interfaces/CacheMetadata.md

@@ -6,7 +6,7 @@
 
 # Interface: CacheMetadata
 
-Defined in: [types.ts:35](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L35)
+Defined in: [types.ts:117](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L117)
 
 缓存元数据
 
@@ -23,7 +23,7 @@ Defined in: [types.ts:35](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **headers**: `Record`\<`string`, `string`\>
 
-Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L39)
+Defined in: [types.ts:121](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L121)
 
 响应头对象
 
@@ -33,7 +33,7 @@ Defined in: [types.ts:39](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **method**: `string`
 
-Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L45)
+Defined in: [types.ts:127](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L127)
 
 原始请求方法
 
@@ -43,7 +43,7 @@ Defined in: [types.ts:45](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **policy**: `any`
 
-Defined in: [types.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L41)
+Defined in: [types.ts:123](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L123)
 
 http-cache-semantics 策略对象，包含 TTL 和缓存指令
 
@@ -53,7 +53,7 @@ http-cache-semantics 策略对象，包含 TTL 和缓存指令
 
 > **size**: `number`
 
-Defined in: [types.ts:49](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L49)
+Defined in: [types.ts:131](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L131)
 
 Body 的字节长度，用于精确区分“空响应”与“未入内存的大响应”
 
@@ -63,7 +63,7 @@ Body 的字节长度，用于精确区分“空响应”与“未入内存的大
 
 > **status**: `number`
 
-Defined in: [types.ts:37](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L37)
+Defined in: [types.ts:119](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L119)
 
 HTTP 状态码
 
@@ -73,7 +73,7 @@ HTTP 状态码
 
 > **timestamp**: `number`
 
-Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L47)
+Defined in: [types.ts:129](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L129)
 
 缓存写入时的时间戳
 
@@ -83,6 +83,6 @@ Defined in: [types.ts:47](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe
 
 > **url**: `string`
 
-Defined in: [types.ts:43](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/types.ts#L43)
+Defined in: [types.ts:125](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L125)
 
 原始请求 URL

package/docs/interfaces/CacheRule.md

@@ -0,0 +1,80 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / CacheRule
+
+# Interface: CacheRule
+
+Defined in: [types.ts:35](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L35)
+
+精细化缓存匹配规则
+
+用于在 `methods` 过滤的基础上，进一步限定哪些具体的请求路径或参数需要被缓存。
+多个规则之间是 **OR (逻辑或)** 关系，即请求只需匹配其中一条规则即可。
+在单个规则对象内部，各字段之间是 **AND (逻辑与)** 关系。
+
+## Properties
+
+### body?
+
+> `optional` **body**: `string` \| `RegExp` \| (`string` \| `RegExp`)[]
+
+Defined in: [types.ts:75](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L75)
+
+Body 内容匹配。
+仅当 Body 为文本或 JSON 时有效。
+- 字符串: 支持 Glob 模式匹配。
+- 正则表达式: 检查 Body 内容是否匹配。
+- 数组: 支持传入多个模式。
+
+***
+
+### bodyType?
+
+> `optional` **bodyType**: `"json"` \| `"text"` \| `"binary"`
+
+Defined in: [types.ts:67](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L67)
+
+强制指定 Body 类型。
+如果不指定，则根据 `Content-Type` 自动判断。
+
+***
+
+### method?
+
+> `optional` **method**: `string`
+
+Defined in: [types.ts:40](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L40)
+
+匹配的方法 (如 "POST")。
+如果指定，则必须方法完全一致；如果不指定，则匹配所有 `methods` 中允许的方法。
+
+***
+
+### path?
+
+> `optional` **path**: `string` \| `RegExp` \| (`string` \| `RegExp`)[]
+
+Defined in: [types.ts:52](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L52)
+
+路径匹配。
+- 字符串: 默认进行 Glob 模式匹配（支持 `!` 否定），若非 Glob 且非正则字符串则退化为前缀匹配。
+- 正则表达式: 检查 `url.pathname` 是否匹配。
+- 数组: 支持传入多个模式（含否定模式），只要其中一个匹配即可。
+
+***
+
+### query?
+
+> `optional` **query**: `Record`\<`string`, `string` \| `boolean` \| `RegExp`\>
+
+Defined in: [types.ts:62](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/types.ts#L62)
+
+Query 参数匹配规则。
+- 键名: 支持字符串、Glob 或正则。
+- 值:
+  - 字符串: 支持 Glob 模式匹配。
+  - 正则表达式: 检查参数值是否匹配。
+  - `true`: 要求该参数必须存在于 URL 中。
+  - `false`: 要求该参数必须 **不** 存在于 URL 中。

package/docs/interfaces/FetchWithCacheContext.md

@@ -6,7 +6,7 @@
 
 # Interface: FetchWithCacheContext
 
-Defined in: [core/fetchWithCache.ts:31](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L31)
+Defined in: [core/fetchWithCache.ts:32](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L32)
 
 内部流水线上下文，合并了入参和计算出的关键状态
 
@@ -20,7 +20,7 @@ Defined in: [core/fetchWithCache.ts:31](https://github.com/isdk/proxy.js/blob/be
 
 > **activeCacheWrites**: `Map`\<`string`, `Promise`\<`void`\>\>
 
-Defined in: [core/fetchWithCache.ts:35](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L35)
+Defined in: [core/fetchWithCache.ts:36](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L36)
 
 并发写入任务追踪器
 传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
@@ -36,7 +36,7 @@ Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
 
 > `optional` **backgroundUpdate**: `boolean`
 
-Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L17)
+Defined in: [core/fetchWithCache.ts:18](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L18)
 
 是否启用后台异步更新 (SWR)
 
@@ -50,7 +50,7 @@ Defined in: [core/fetchWithCache.ts:17](https://github.com/isdk/proxy.js/blob/be
 
 > **cache**: [`SmartCache`](../classes/SmartCache.md)
 
-Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L13)
+Defined in: [core/fetchWithCache.ts:14](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L14)
 
 混合缓存实例
 
@@ -64,7 +64,7 @@ Defined in: [core/fetchWithCache.ts:13](https://github.com/isdk/proxy.js/blob/be
 
 > **cacheKey**: `string`
 
-Defined in: [core/fetchWithCache.ts:34](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L34)
+Defined in: [core/fetchWithCache.ts:35](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L35)
 
 ***
 
@@ -72,7 +72,7 @@ Defined in: [core/fetchWithCache.ts:34](https://github.com/isdk/proxy.js/blob/be
 
 > **config**: [`SiteCacheConfig`](SiteCacheConfig.md)
 
-Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L15)
+Defined in: [core/fetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L16)
 
 站点级缓存配置
 
@@ -86,7 +86,7 @@ Defined in: [core/fetchWithCache.ts:15](https://github.com/isdk/proxy.js/blob/be
 
 > **fetcher**: (`req`) => `Promise`\<`Response`\>
 
-Defined in: [core/fetchWithCache.ts:33](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L33)
+Defined in: [core/fetchWithCache.ts:34](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L34)
 
 #### Parameters
 
@@ -102,13 +102,28 @@ Defined in: [core/fetchWithCache.ts:33](https://github.com/isdk/proxy.js/blob/be
 
 ### generateKey()?
 
-> `optional` **generateKey**: (`req`, `config`) => `string`
+> `optional` **generateKey**: (`req`, `config`) => `Promise`\<`string`\>
 
-Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L21)
+Defined in: [core/fetchWithCache.ts:22](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L22)
 
 自定义缓存键生成函数
 
-根据 Request 和配置生成唯一的缓存键
+根据 Request 对象和站点配置生成唯一的缓存指纹 (异步)
+
+该函数是缓存系统的核心组件，用于将复杂的 HTTP 请求对象转换为唯一的 SHA-256 字符串。
+它实现了高度可定制的提取逻辑，允许通过配置排除掉请求中不稳定的因素（如时间戳、Nonce 等）。
+
+### 生成指纹包含的要素：
+1. **Method**: 请求方法（统一转为大写）。
+2. **Host & Path**: 请求的域名和路径。
+3. **Query Params**: URL 查询参数，受 `config.query` 过滤影响。
+4. **Headers**: 请求头信息，受 `config.headers` 过滤影响。默认排除 `cookie` 头。
+5. **Cookies**: 特别提取的 Cookie 字段，受 `config.cookies` 过滤影响。
+6. **Request Body**:
+   - 对于 `POST`, `PUT`, `PATCH` 请求，会自动尝试读取 Body。
+   - **JSON 类型**: 如果 `Content-Type` 包含 `application/json`，则解析为对象并应用 `config.body` 过滤。
+   - **非 JSON/流类型**: 回退到对原始 Body 字节流进行 SHA-256 哈希计算。
+   - **安全性**: 使用 `req.clone()` 读取 Body，确保不影响后续真实的 Fetch 请求流消费。
 
 #### Parameters
 
@@ -116,13 +131,28 @@ Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/be
 
 `Request`
 
+原始 Web 标准 Request 对象。
+
 ##### config
 
 [`SiteCacheConfig`](SiteCacheConfig.md)
 
+站点级缓存配置，决定了哪些字段参与指纹计算。
+
 #### Returns
 
-`string`
+`Promise`\<`string`\>
+
+返回一个 64 位十六进制的 SHA-256 哈希字符串作为缓存键。
+
+#### Example
+
+```typescript
+const cacheKey = await generateCacheKey(request, {
+  query: { exclude: ['timestamp'] },
+  body: { include: ['id', 'action'] }
+});
+```
 
 #### Inherited from
 
@@ -134,7 +164,7 @@ Defined in: [core/fetchWithCache.ts:21](https://github.com/isdk/proxy.js/blob/be
 
 > `optional` **onBackgroundUpdate**: (`promise`) => `void`
 
-Defined in: [core/fetchWithCache.ts:19](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L19)
+Defined in: [core/fetchWithCache.ts:20](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L20)
 
 后台更新 Promise 触发时的回调
 
@@ -158,4 +188,4 @@ Defined in: [core/fetchWithCache.ts:19](https://github.com/isdk/proxy.js/blob/be
 
 > **request**: `Request`
 
-Defined in: [core/fetchWithCache.ts:32](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L32)
+Defined in: [core/fetchWithCache.ts:33](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L33)