@isdk/proxy 0.1.1 → 0.1.2

package/docs/README.md

@@ -19,6 +19,8 @@ In high-concurrency environments—like **API Proxies**, **Web Scrapers**, or **
 ## Key Features
 
 - **🚀 Hybrid Multi-tier Cache**: Extreme speed with L1 (LRU Memory) and persistence with L2 (Content Addressable Disk via `cacache`).
+- **📥 HTTP POST & Method Support**: Full support for caching POST, PUT, and other methods with intelligent request body fingerprinting.
+- **🎯 Precision Filtering**: Fine-grained `cacheRules` to intercept specific paths or query parameters.
 - **🌊 Streaming Native**: Fully stream-based internal pipeline natively prevents Out-Of-Memory (OOM) issues when proxying large files.
 - **🧠 Intelligent Meta-Residency**: Metadata (Headers, Status, Policy) stays in memory regardless of body size, ensuring nanosecond cache policy evaluations.
 - **🔄 Stale-While-Revalidate (SWR)**: Serve stale content instantly while updating the cache silently in the background.
@@ -37,6 +39,8 @@ pnpm add @isdk/proxy
 
 The primary way to use `@isdk/proxy` is via the `fetchWithCache` function, which can wrap any HTTP request logic.
 
+### Basic Usage (GET)
+
 ```typescript
 import { SmartCache, createCachedFetch } from '@isdk/proxy';
 
@@ -46,28 +50,98 @@ const cache = new SmartCache({
   maxMemorySize: 1024 * 1024 // 1MB threshold
 });
 
-// 2. Create a pre-configured cached fetcher (automatically tracks concurrent requests)
+// 2. Create a pre-configured cached fetcher
 const myFetch = createCachedFetch({
   cache,
   config: {
     staleIfError: true,
-    forceCache: false // Set to true to cache everything (ignore no-store) for offline-first apps
   },
   backgroundUpdate: true // Enable SWR
 });
 
-// 3. Use it anywhere in your app!
-const request = new Request('https://api.example.com/data');
-const response = await myFetch(request, (req) => fetch(req));
+// 3. Use it!
+const response = await myFetch(new Request('https://api.example.com/data'), (req) => fetch(req));
+console.log(response.headers.get('x-proxy-cache'));
+```
+
+### Advanced Usage: Caching POST Requests
 
-console.log(response.headers.get('x-proxy-cache')); // "MISS", "HIT", "STALE", or "STALE_IF_ERROR"
-const data = await response.json();
+You can cache POST/PUT requests by enabling methods and defining body filters to ignore dynamic fields (like timestamps) in the request body.
+
+```typescript
+const myPostFetch = createCachedFetch({
+  cache,
+  config: {
+    methods: ['GET', 'POST'], // Enable POST caching
+    body: {
+      exclude: ['timestamp', 'nonce'] // Ignore these fields when generating cache keys
+    },
+    cacheRules: [
+      { method: 'POST', path: '/api/v1/query' } // Only cache specific POST endpoints
+    ],
+    forceCache: true // Often needed for POST if backend doesn't send Cache-Control
+  }
+});
+```
+
+## Configuration: `SiteCacheConfig`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `methods` | `string[]` | List of allowed HTTP methods. Default: `['GET', 'HEAD']`. |
+| `cacheRules` | `CacheRule[]` | Fine-grained rules. If set, a request must match at least one rule to be cached. |
+| `query` | `KeyFilterConfig` | Filters for URL search parameters (`include`/`exclude`). |
+| `headers` | `KeyFilterConfig` | Filters for request headers. |
+| `cookies` | `KeyFilterConfig` | Filters for cookies. |
+| `body` | `KeyFilterConfig` | Filters for JSON request body fields. |
+| `staleIfError`| `boolean` | Serve stale cache on network failure. |
+| `forceCache` | `boolean` | Ignore `no-store` and force caching (useful for offline support). |
+
+### `CacheRule` Object
+
+- `method`: HTTP method to match.
+- `path`: URL pathname matching (supports **RegExp**, **Glob**, **Array**, or **prefix match**).
+- `query`: Key-value pairs. Values can be `string` (exact/Glob match), `true` (must exist), `false` (must not exist), or `RegExp`.
+- `body`: Body content matching (supports **RegExp**, **Glob**, or **Array**).
+
+### Pattern Matching
+
+`@isdk/proxy` provides powerful pattern matching for all configurable fields:
+
+| Pattern Type | Example | Description |
+| :--- | :--- | :--- |
+| **RegExp** | `/api/v[12]/.*/i` | JavaScript RegExp (in JSON, use string like `"/api/v[12]/.*/i"`) |
+| **Glob** | `/**/*.json` | File path style wildcard matching |
+| **Negation** | `['!/api/private/**', '/api/**']` | Exclude patterns (prefixed with `!`, checked first) |
+| **Array** | `['/api/v1/*', '/api/v2/*']` | Multiple patterns (OR logic, negative takes precedence) |
+| **Boolean** | `true` / `false` | For query params: must/must not exist |
+
+**Example with advanced pattern matching:**
+
+```typescript
+const myFetch = createCachedFetch({
+  cache,
+  config: {
+    cacheRules: [
+      {
+        path: ['/api/v1/items/*', '!/api/v1/items/private/*'], // v1 items, exclude private
+        query: {
+          format: '/^(json|xml)$/',     // Regex for format param
+          'page*': true                  // Glob: any param starting with 'page' must exist
+        },
+        body: /\"action\"\s*:\s*\"query\"/ // Regex body match
+      }
+    ]
+  }
+});
 ```
 
 ## Adapters
 
 `@isdk/proxy` is designed to be framework-agnostic. While the core library is pure, you can find (or build) adapters for specific environments:
 
+- **HTTP Caching Proxy Server (Node.js)**: See [@isdk/proxy-server](https://www.npmjs.com/package/@isdk/proxy-server) (separate package) for running a standalone HTTP forward proxy.
+- **Crawlee Adapter**: See [@isdk/proxy-crawlee](https://www.npmjs.com/package/@isdk/proxy-crawlee) (separate package) for integrating with Crawlee web scraping lifecycle.
 - **MSW Adapter**: See `@isdk/proxy-msw` (separate package) to use this caching engine as an MSW interceptor.
 - **Axios Adapter**: Easily implemented by converting Axios config to Web `Request`.
 
@@ -120,9 +194,119 @@ The hybrid multi-tier storage engine.
 - **`options.maxMemorySize`**: Threshold (in bytes) for offloading bodies to disk (default `1048576`, i.e., 1MB).
 - **`options.storagePath`**: Disk storage path for the `cacache` engine (defaults to a system temp folder).
 
+### Utility Functions
+
+Exported from `@isdk/proxy` for advanced usage:
+
+#### `isMatch(pattern, value, usePrefix?)`
+
+Universal pattern matching function. Supports RegExp, Glob, array patterns (with negation), and string prefix/exact matching.
+
+- **`pattern`**: `string | RegExp | (string | RegExp)[]`
+- **`value`**: The string to test against
+- **`usePrefix`**: For plain strings, use prefix match instead of exact match (default: `false`)
+- **Returns**: `boolean`
+
+```typescript
+import { isMatch } from '@isdk/proxy';
+
+isMatch('/api/v[12]/.*', '/api/v1/users');     // RegExp
+isMatch('/api/**/*.json', '/api/v1/data.json'); // Glob
+isMatch(['!/private/**', '/api/**'], '/api/data'); // Negation
+```
+
+#### `isGlob(pattern)`
+
+Check if a pattern is Glob syntax.
+
+- **`pattern`**: `string`
+- **Returns**: `boolean`
+
+#### `getSiteConfig(urlString, proxyConfig)`
+
+Get the site-specific cache configuration for a given URL.
+
+- **`urlString`**: Full URL to match
+- **`proxyConfig`**: `ProxyConfig` object with `sites` and `default` config
+- **Returns**: `SiteCacheConfig`
+
+```typescript
+import { getSiteConfig } from '@isdk/proxy';
+
+const config = getSiteConfig('https://api.example.com/data', {
+  default: { methods: ['GET'] },
+  sites: {
+    'api.example.com': { methods: ['GET', 'POST'], forceCache: true },
+    '/internal/': { staleIfError: true } // prefix match
+  }
+});
+```
+
+#### `isAllowed(key, config, defaultAllowed?)`
+
+Check if a key is allowed to participate in cache key fingerprinting.
+
+- **`key`**: The key name to check
+- **`config`**: `KeyFilterConfig` with `include` (whitelist) or `exclude` (blacklist)
+- **`defaultAllowed`**: Optional. Default value when no config or no match
+- **Returns**: `boolean | undefined`
+
+**Priority Logic**:
+
+1. `exclude` hit → returns `false` (highest priority)
+2. `include` exists and hits → returns `true`
+3. `include` exists but no hit → returns `false`
+4. No config → uses `defaultAllowed` (returns `undefined` if not provided)
+
+```typescript
+import { isAllowed } from '@isdk/proxy';
+
+// No config
+isAllowed('key'); // undefined (falsy)
+
+// Whitelist
+isAllowed('id', { include: ['id', 'name'] }); // true
+isAllowed('email', { include: ['id', 'name'] }); // false
+
+// Blacklist
+isAllowed('password', { exclude: ['password'] }); // false
+isAllowed('name', { exclude: ['password'] }); // undefined (falsy)
+
+// Need defaultAllowed to set default
+isAllowed('name', { exclude: ['password'] }, true); // true
+```
+
+#### `extractData(source, config, defaultAllowed?)`
+
+Extract and normalize data from a source object based on filter config. Used for generating cache fingerprints.
+
+- **`source`**: Original data object (Query, Headers, Cookies, etc.)
+- **`config`**: `KeyFilterConfig` object
+- **`defaultAllowed`**: Optional. Whether to allow extraction when no config or no match (default `false`)
+- **Returns**: `Record<string, string[]>` normalized data with lowercase keys and sorted array values
+
+```typescript
+import { extractData } from '@isdk/proxy';
+
+const headers = { 'Content-Type': 'application/json', 'X-Request-Id': '123' };
+
+// No extraction by default
+extractData(headers); // {}
+
+// Extract all keys
+extractData(headers, undefined, true); // { 'content-type': ['application/json'], 'x-request-id': ['123'] }
+
+// Whitelist
+extractData(headers, { include: ['content-type'] }); // { 'content-type': ['application/json'] }
+
+// Blacklist
+extractData(headers, { include: ['*'], exclude: ['x-request-id'] }, true); // { 'content-type': ['application/json'] }
+```
+
 ### Cache Status Headers
 
 Every response processed by `@isdk/proxy` will include an `x-proxy-cache` header indicating its lifecycle:
+
 - `HIT`: Served entirely from L1 or L2 cache.
 - `MISS`: Bypassed cache and fetched from the origin server.
 - `STALE`: Served from stale cache while a background update was initiated (SWR).

package/docs/classes/SmartCache.md

@@ -6,9 +6,19 @@
 
 # Class: SmartCache
 
-Defined in: [core/SmartCache.ts:22](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L22)
+Defined in: [core/SmartCache.ts:39](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L39)
 
-智能混合缓存类 (Hybrid Cache)
+智能混合缓存类 (Hybrid Multi-tier Cache)
+
+该类实现了 L1 (内存) 和 L2 (磁盘) 的双层混合存储架构，旨在提供高性能且大容量的缓存能力。
+
+### 核心特性：
+- **双层架构**: L1 使用 LRU 内存缓存（基于 `secondary-cache` 的 LRUCache），L2 使用持久化磁盘缓存（基于 `cacache`）。
+- **大小感知存储**: 自动识别响应体大小。小于阈值的文件同时存于内存和磁盘；超过阈值的文件仅存于磁盘，但其元数据仍保留在内存中。
+- **元数据驻留 (Meta-Residency)**: 无论 Body 多大，Headers、Status、Policy 等信息始终优先从内存读取，确保缓存判定性能。
+- **流式支持**: 支持通过 `setStream` 和 `getStream` 直接操作大数据流，防止 OOM。
+- **一致性保障**: 在并发写入时自动清理内存，确保后续读取不会拿到被污染的旧数据。
+- **内存限制**: 通过 `maxTotalMemorySize` 控制 L1 缓存的总内存占用。
 
 ## Constructors
 
@@ -16,7 +26,7 @@ Defined in: [core/SmartCache.ts:22](https://github.com/isdk/proxy.js/blob/bed37f
 
 > **new SmartCache**(`options`): `SmartCache`
 
-Defined in: [core/SmartCache.ts:27](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L27)
+Defined in: [core/SmartCache.ts:44](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L44)
 
 #### Parameters
 
@@ -34,7 +44,7 @@ Defined in: [core/SmartCache.ts:27](https://github.com/isdk/proxy.js/blob/bed37f
 
 > **clear**(): `Promise`\<`void`\>
 
-Defined in: [core/SmartCache.ts:122](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L122)
+Defined in: [core/SmartCache.ts:193](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L193)
 
 #### Returns
 
@@ -46,7 +56,7 @@ Defined in: [core/SmartCache.ts:122](https://github.com/isdk/proxy.js/blob/bed37
 
 > **delete**(`key`): `Promise`\<`void`\>
 
-Defined in: [core/SmartCache.ts:117](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L117)
+Defined in: [core/SmartCache.ts:188](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L188)
 
 #### Parameters
 
@@ -64,10 +74,15 @@ Defined in: [core/SmartCache.ts:117](https://github.com/isdk/proxy.js/blob/bed37
 
 > **get**(`key`): `Promise`\<[`CacheEntry`](../interfaces/CacheEntry.md) \| `null`\>
 
-Defined in: [core/SmartCache.ts:41](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L41)
+Defined in: [core/SmartCache.ts:79](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L79)
 
 获取缓存条目
-如果是小文件，返回带 Buffer 的 Entry；如果是大文件，返回带 ReadStream 的 Entry。
+
+逻辑：
+1. 首先尝试从 L1 内存获取。
+2. 如果内存中有 Body，直接返回（Buffer 类型）。
+3. 如果内存中只有 Meta（大文件），则从 L2 磁盘创建并返回 ReadStream。
+4. 如果内存完全未命中，从磁盘 L2 检索，并根据大小决定是否回填 L1。
 
 #### Parameters
 
@@ -75,17 +90,25 @@ Defined in: [core/SmartCache.ts:41](https://github.com/isdk/proxy.js/blob/bed37f
 
 `string`
 
+缓存指纹键
+
 #### Returns
 
 `Promise`\<[`CacheEntry`](../interfaces/CacheEntry.md) \| `null`\>
 
+完整的缓存条目（带 Buffer 或 Stream 的 Body），未命中返回 null
+
 ***
 
 ### getStream()
 
 > **getStream**(`key`): `ReadableStream`
 
-Defined in: [core/SmartCache.ts:107](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L107)
+Defined in: [core/SmartCache.ts:159](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L159)
+
+获取磁盘读取流
+
+允许直接从 L2 磁盘层以流的形式读取数据，适用于大文件代理。
 
 #### Parameters
 
@@ -93,19 +116,25 @@ Defined in: [core/SmartCache.ts:107](https://github.com/isdk/proxy.js/blob/bed37
 
 `string`
 
+缓存指纹键
+
 #### Returns
 
 `ReadableStream`
 
+Node.js 可读流
+
 ***
 
 ### set()
 
 > **set**(`key`, `body`, `metadata`): `Promise`\<`void`\>
 
-Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L85)
+Defined in: [core/SmartCache.ts:129](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L129)
 
-写入缓存
+写入缓存条目 (原子写入)
+
+适用于已知长度的小型数据块。该操作会同时写入磁盘并回填内存（如果大小未超标）。
 
 #### Parameters
 
@@ -113,14 +142,20 @@ Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37f
 
 `string`
 
+缓存指纹键
+
 ##### body
 
 `Buffer`
 
+响应体数据 Buffer
+
 ##### metadata
 
 `Omit`\<[`CacheMetadata`](../interfaces/CacheMetadata.md), `"size"`\>
 
+响应元数据（不含 size，由本方法自动计算）
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -131,7 +166,14 @@ Defined in: [core/SmartCache.ts:85](https://github.com/isdk/proxy.js/blob/bed37f
 
 > **setStream**(`key`, `metadata`): `WritableStream`
 
-Defined in: [core/SmartCache.ts:111](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/SmartCache.ts#L111)
+Defined in: [core/SmartCache.ts:175](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/SmartCache.ts#L175)
+
+获取磁盘写入流 (流式缓存)
+
+该方法用于支持真正的流式代理。它会执行以下一致性操作：
+1. 立即清除 L1 内存中的对应键，防止读到旧数据。
+2. 返回一个可写流，数据将直接流入磁盘。
+3. **一致性修复**: 在流写入完成（finish）时再次清理内存，防止写入期间的并发读取将旧数据再次回填进内存。
 
 #### Parameters
 
@@ -139,10 +181,16 @@ Defined in: [core/SmartCache.ts:111](https://github.com/isdk/proxy.js/blob/bed37
 
 `string`
 
+缓存指纹键
+
 ##### metadata
 
 `Omit`\<[`CacheMetadata`](../interfaces/CacheMetadata.md), `"size"`\>
 
+响应元数据
+
 #### Returns
 
 `WritableStream`
+
+Node.js 可写流

package/docs/functions/createCachedFetch.md

@@ -8,7 +8,7 @@
 
 > **createCachedFetch**(`defaultOptions`): (`request`, `fetcher`, `overrideOptions?`) => `Promise`\<`Response`\>
 
-Defined in: [core/createCachedFetch.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/createCachedFetch.ts#L17)
+Defined in: [core/createCachedFetch.ts:17](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/createCachedFetch.ts#L17)
 
 缓存请求工厂函数 (针对终端用户的顶层高阶 API)
 

package/docs/functions/createFetchWithCache.md

@@ -8,7 +8,7 @@
 
 > **createFetchWithCache**(`activeCacheWrites?`): (`request`, `fetcher`, `options`) => `Promise`\<`Response`\>
 
-Defined in: [core/createFetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/createFetchWithCache.ts#L16)
+Defined in: [core/createFetchWithCache.ts:16](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/createFetchWithCache.ts#L16)
 
 单一职责高阶函数：专门用于封装和隔离 activeCacheWrites 并发追踪器。
 

package/docs/functions/extractData.md

@@ -6,18 +6,23 @@
 
 # Function: extractData()
 
-> **extractData**(`source`, `config?`): `Record`\<`string`, `string`[]\>
+> **extractData**(`source`, `config?`, `defaultAllowed?`): `Record`\<`string`, `string`[]\>
 
-Defined in: [utils/extractData.ts:17](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/utils/extractData.ts#L17)
+Defined in: [utils/extractData.ts:40](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/utils/extractData.ts#L40)
 
 从源对象中根据过滤配置提取数据并标准化。
 
 此函数主要用于生成缓存指纹。它会：
-1. 根据 `config` (include/exclude) 过滤键。
+1. 根据 `config` (include/exclude) 过滤键，调用 `isAllowed` 判断每个键是否允许。
 2. 对键进行排序以保证指纹的一致性。
 3. 将所有键转换为小写。
 4. 将值统一包装为数组并进行排序，消除数组项顺序差异。
 
+**关于 `defaultAllowed` 参数**：
+- 只有当没有配置 `include` 和 `exclude` 时，`defaultAllowed` 才会生效。
+- 如果配置了 `include`（即使为空数组），`defaultAllowed` 也不会生效。
+- 详见 `isAllowed` 函数的优先级逻辑。
+
 ## Parameters
 
 ### source
@@ -30,10 +35,34 @@ Defined in: [utils/extractData.ts:17](https://github.com/isdk/proxy.js/blob/bed3
 
 [`KeyFilterConfig`](../interfaces/KeyFilterConfig.md)
 
-过滤配置 (白名单或黑名单)
+过滤配置，支持 `include`（白名单）和 `exclude`（黑名单）
+
+### defaultAllowed?
+
+`boolean`
+
+当没有配置时的默认值（默认 `false`，即不提取任何键）
 
 ## Returns
 
 `Record`\<`string`, `string`[]\>
 
-标准化后的数据 Map，键为小写，值为字符串数组
+标准化后的数据 Map，键为小写，值为排序后的字符串数组
+
+## Example
+
+```typescript
+const headers = { 'Content-Type': 'application/json', 'X-Request-Id': '123' };
+
+// 默认不提取任何键
+extractData(headers); // {}
+
+// 提取所有键
+extractData(headers, undefined, true); // { 'content-type': ['application/json'], 'x-request-id': ['123'] }
+
+// 白名单
+extractData(headers, { include: ['content-type'] }); // { 'content-type': ['application/json'] }
+
+// 黑名单（需要 include 或 defaultAllowed）
+extractData(headers, { include: ['*'], exclude: ['x-request-id'] }, true); // { 'content-type': ['application/json'] }
+```

package/docs/functions/fetchWithCache.md

@@ -8,11 +8,13 @@
 
 > **fetchWithCache**(`request`, `fetcher`, `options`): `Promise`\<`Response`\>
 
-Defined in: [core/fetchWithCache.ts:244](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/fetchWithCache.ts#L244)
+Defined in: [core/fetchWithCache.ts:370](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/fetchWithCache.ts#L370)
 
 核心协调函数 (Fetcher Orchestrator)
 
 实现了基于流的混合缓存代理核心逻辑，主要机制包括：
+- **多方法支持与过滤**：支持通过 `allowedMethods` 配置可缓存的方法（如 POST, PUT），并通过 `cacheRules` 进行精细化的路径与参数匹配拦截。
+- **异步 Request Body 处理**：当缓存 POST/PUT 请求时，会自动读取 Body 并计算唯一指纹（支持 JSON 字段过滤）。
 - **大文件流式处理**：底层完全通过 Streams 实现，代理大文件时自动写入磁盘且防 OOM。
 - **SWR (Stale-While-Revalidate)**：后台静默更新机制。
 - **并发防击穿 (Request Coalescing)**：利用 `activeCacheWrites` 将并发请求合并。
@@ -26,14 +28,22 @@ Defined in: [core/fetchWithCache.ts:244](https://github.com/isdk/proxy.js/blob/b
 
 `Request`
 
+原始 Web 标准 Request 对象
+
 ### fetcher
 
 (`req`) => `Promise`\<`Response`\>
 
+实际执行网络请求的函数
+
 ### options
 
 [`FetchWithCacheOptions`](../interfaces/FetchWithCacheOptions.md)
 
+缓存配置选项
+
 ## Returns
 
 `Promise`\<`Response`\>
+
+带有缓存标识头和流式 Body 的 Response 对象

package/docs/functions/generateCacheKey.md

@@ -6,11 +6,26 @@
 
 # Function: generateCacheKey()
 
-> **generateCacheKey**(`req`, `config`): `string`
+> **generateCacheKey**(`req`, `config`): `Promise`\<`string`\>
 
-Defined in: [core/generateCacheKey.ts:8](https://github.com/isdk/proxy.js/blob/bed37fa43507dcbe5cdfa453876163571399d761/src/core/generateCacheKey.ts#L8)
+Defined in: [core/generateCacheKey.ts:36](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/core/generateCacheKey.ts#L36)
 
-根据 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
 
@@ -18,10 +33,25 @@ Defined in: [core/generateCacheKey.ts:8](https://github.com/isdk/proxy.js/blob/b
 
 `Request`
 
+原始 Web 标准 Request 对象。
+
 ### config
 
 [`SiteCacheConfig`](../interfaces/SiteCacheConfig.md)
 
+站点级缓存配置，决定了哪些字段参与指纹计算。
+
 ## Returns
 
-`string`
+`Promise`\<`string`\>
+
+返回一个 64 位十六进制的 SHA-256 哈希字符串作为缓存键。
+
+## Example
+
+```typescript
+const cacheKey = await generateCacheKey(request, {
+  query: { exclude: ['timestamp'] },
+  body: { include: ['id', 'action'] }
+});
+```

package/docs/functions/getSiteConfig.md

@@ -0,0 +1,39 @@
+[**@isdk/proxy**](../README.md)
+
+***
+
+[@isdk/proxy](../globals.md) / getSiteConfig
+
+# Function: getSiteConfig()
+
+> **getSiteConfig**(`urlString`, `proxyConfig`): [`SiteCacheConfig`](../interfaces/SiteCacheConfig.md)
+
+Defined in: [utils/getSiteConfig.ts:17](https://github.com/isdk/proxy.js/blob/76fee3a101f98e5bf29599fe7ea02ab06479cf70/src/utils/getSiteConfig.ts#L17)
+
+根据 URL 获取对应的站点缓存配置
+
+匹配逻辑：
+1. 遍历 sites 中的所有 key。
+2. 如果 key 是正则或 Glob 格式字符串，则对完整 URL 进行匹配。
+3. 如果 key 是普通字符串，则作为 URL 前缀进行匹配。
+4. 返回第一个匹配到的配置；若均未匹配，则返回 defaultConfig。
+
+## Parameters
+
+### urlString
+
+`string`
+
+请求的完整 URL
+
+### proxyConfig
+
+[`ProxyConfig`](../interfaces/ProxyConfig.md)
+
+全局代理配置
+
+## Returns
+
+[`SiteCacheConfig`](../interfaces/SiteCacheConfig.md)
+
+匹配到的站点配置