fix: doc corrections, release prep and changelog restructure

- Fix CacheLike interface docs: remove non-existent generic, mark
  optional methods (getStats?/destroy?/invalidateByTag? etc)
- Fix MultiLevelCacheOptions.remote: optional not required
- Fix readThrough signature: CacheLike<V> -> CacheLike (no generic)
- Update test count in README: 440 -> 470
- Restructure CHANGELOG.md into index + changelogs/v1.0.0.md per RULES §7
- Add changelogs/TEMPLATE.md for future versions
- Fix package.json exports: move 'types' condition before import/require
- Add changelogs/ to npm files array
- Add statements:100 coverage threshold in vitest.config.ts
- Export SetOptions type from main entry (src/index.ts)
- Fix api-reference.md: remove false Redis SHA-256 key compress claim
- Fix getting-started.md: multiple API usage corrections
- Fix rspress.config.ts: update GitHub URL

Author: rockyshi1993

CHANGELOG.md

@@ -5,85 +5,15 @@ All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+> 📖 每个版本的完整变更详情位于 [`changelogs/`](./changelogs/) 目录。
+
 ---
 
 ## [1.0.0] - 2026-03-22
 
-首个正式发布版本。零运行时依赖的 Node.js 多层缓存库，统一工作区所有项目的缓存基础设施。
-
-### Added（新增）
-
-#### 核心类型与接口（`cache-hub`）
-- 新增 `CacheLike` 接口：定义统一缓存契约，覆盖 `get / set / del / exists / has / clear / keys / getMany / setMany / delMany / delPattern / getStats / destroy` 共 13 个方法
-- 新增 `CacheStats` 类型：统一统计信息结构（`hits / misses / sets / deletes / evictions / memoryUsage / hitRate`）
-- 新增 `MemoryCacheOptions` 配置类型
-
-#### MemoryCache（`cache-hub`）
-- 基于 ES6 `Map` 实现的 O(1) LRU 淘汰引擎
-- TTL 支持：惰性过期（`get` 时判断）+ 可选周期清理（`cleanupInterval`）
-- 双重容量限制：`maxEntries`（条目数）+ `maxMemory`（字节估算）
-- 批量操作：`getMany / setMany / delMany`
-- 模式删除：`delPattern(pattern)`（`*` 通配符 → 正则）
-- 统计信息：`hits / misses / evictions / hitRate` 等，可通过 `enableStats` 开关
-- 标签索引：`enableTags=true` 时维护 `tagIndex`，支持 `invalidateByTag(tag)`
-- `enabled` 开关：`false` 时 `get` 返回 `undefined`，`set` 不写入
-- `destroy()`：清理周期定时器并清空缓存
-
-#### stableStringify（`cache-hub/stringify`）
-- `stableStringify(value, options?)`：对象键字母排序、`NaN` 固定输出 `"__NaN__"`、循环引用输出 `"[CIRCULAR]"`
-- `RegExp` / `Date` 特殊处理，数组保序
-- `customSerializer` 插件钩子：支持 BSON ObjectId 等自定义类型扩展
-
-#### readThrough（`cache-hub/read-through`）
-- `readThrough(cache, ttlMs, key, fetcher)`：缓存命中直返，未命中执行 fetcher 并写缓存
-- 并发去重（in-flight map）：相同 key 的并发请求共享同一 Promise
-- `ttl ≤ 0` 时直接执行 fetcher 不写缓存
-- 内置溢出保护（INFLIGHT_MAX_SIZE = 10000，超限清理最旧 10%）
-- 内置超时清理（INFLIGHT_TIMEOUT_MS = 300000ms，防止内存泄漏）
-- `undefined` 不写缓存，`null` 视为有效空值
-
-#### MultiLevelCache（`cache-hub/multi-level`）
-- L1（本地）+ L2（远端）双层缓存，均接受 `CacheLike` 接口
-- 写策略：`'both'`（同步双写）/ `'local-first-async-remote'`（本地优先异步写远端）
-- 远端命中回填本地（`backfillOnRemoteHit`，默认开启，可关闭）
-- 远端操作超时保护（`remoteTimeoutMs`，默认 50ms，超时降级不报错）
-- 可选分布式失效广播回调（`publish?: (keys: string[]) => void`）
-
-#### RedisCacheAdapter（`cache-hub/redis`）
-- `createRedisCacheAdapter(urlOrInstance)`：将 ioredis 实例包装为 `CacheLike`
-- 支持 URL 字符串初始化（自动创建 ioredis 连接）或传入已有实例
-- `delPattern / keys` 使用 SCAN 游标迭代，禁止 `KEYS` 命令（防阻塞）
-- `close()`：仅关闭自己创建的连接（外部传入的连接不关闭）
-- 超长 key（> 512 字节）自动 SHA-256 压缩，`pattern` 超长时截断并 `console.warn`
-- JSON 序列化存储，支持 `null` 作为有效缓存值
-
-#### FunctionCache / withCache（`cache-hub/function-cache`）
-- `withCache(fn, options)`：装饰器，自动缓存异步函数返回值
-- 键生成：`namespace:fnName:stableStringify(args)`，超长键自动 SHA-256 压缩
-- 并发去重：相同参数的并发调用共享同一 Promise
-- 条件缓存：`condition(result)` 返回 `false` 时不写缓存
-- `FunctionCache` 类：支持 `register / execute / invalidate / getStats`，适合多函数统一管理
-- Per-function TTL / keyBuilder / condition 配置，可覆盖全局默认值
-
-#### DistributedCacheInvalidator（`cache-hub/distributed`）
-- `DistributedCacheInvalidator`：基于 Redis Pub/Sub 的跨实例缓存失效广播
-- 自动过滤自身发出的消息（`instanceId` 隔离）
-- 支持监听多个本地缓存实例（`watchedCaches`）
-- 支持 `redisUrl` 字符串或已有 ioredis 连接两种初始化方式
-- `invalidate(keys)` / `close()` 生命周期管理
-- `getStats()` 返回发布/接收消息计数
-
-### Build（构建）
-- ESM + CJS 双格式产出（`dist/esm/` + `dist/cjs/` + `dist/types/`）
-- 多入口按需导入：`cache-hub`、`cache-hub/redis`、`cache-hub/multi-level`、`cache-hub/function-cache`、`cache-hub/distributed`、`cache-hub/stringify`、`cache-hub/read-through`
-- CJS 产物兼容性修补：`import.meta.url` → `__filename`（`scripts/build-cjs.mjs`）
-- 零运行时依赖（`dependencies: {}`），ioredis 为可选 peerDependency（`>=5.0.0`）
+🎉 首个正式发布版本。零运行时依赖的 Node.js 多层缓存库，统一工作区所有项目的缓存基础设施。
 
-### Tests（测试）
-- 440 个单元测试，全部通过，全维度覆盖率 100%（Statements / Branches / Functions / Lines）
-- 30 个集成测试（`test/integration/redis.integration.test.ts`），需本地 Redis 连接
-- 支持 `npm test`（单元）、`npm run test:integration`（集成，需 Redis）
-- 支持 `REDIS_URL` 环境变量自定义 Redis 地址，`SKIP_INTEGRATION=true` 跳过集成测试
+[→ 查看完整变更详情](./changelogs/v1.0.0.md)
 
 ---
 

README.md

@@ -46,7 +46,7 @@ import { MemoryCache } from 'cache-hub';
 
 const cache = new MemoryCache({
     maxEntries: 1000,       // 最多 1000 条
-    ttl: 60_000,            // 默认 TTL 60 秒
+    defaultTtl: 60_000,     // 默认 TTL 60 秒
     enableStats: true,
 });
 
@@ -63,7 +63,7 @@ console.log(stats.hitRate);  // 0~1 命中率
 import { MemoryCache } from 'cache-hub';
 import { readThrough } from 'cache-hub/read-through';
 
-const cache = new MemoryCache({ ttl: 30_000 });
+const cache = new MemoryCache({ defaultTtl: 30_000 });
 
 // 缓存命中直返，未命中执行 fetcher 并写缓存
 // 相同 key 的并发请求共享同一 Promise（并发去重）
@@ -102,7 +102,7 @@ import { MemoryCache } from 'cache-hub';
 import { MultiLevelCache } from 'cache-hub/multi-level';
 import { createRedisCacheAdapter } from 'cache-hub/redis';
 
-const local = new MemoryCache({ maxEntries: 500, ttl: 30_000 });
+const local = new MemoryCache({ maxEntries: 500, defaultTtl: 30_000 });
 const remote = createRedisCacheAdapter('redis://localhost:6379');
 
 const cache = new MultiLevelCache({
@@ -130,12 +130,12 @@ const local = new MemoryCache({ maxEntries: 1000 });
 // 多个服务实例各自持有本地缓存，通过 Redis Pub/Sub 广播失效
 const invalidator = new DistributedCacheInvalidator({
     redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',
-    watchedCaches: [local],
+    cache: local,
     channel: 'app:cache-invalidation',
 });
 
-// 发布失效事件，其他实例收到后自动清除本地缓存
-await invalidator.invalidate(['user:1', 'user:2']);
+// 广播失效事件（支持通配符 *），其他实例收到后自动对本地缓存执行 delPattern
+await invalidator.invalidate('user:*');
 
 // 应用退出时关闭连接
 await invalidator.close();
@@ -158,11 +158,11 @@ import type { CacheLike, CacheStats, MemoryCacheOptions } from 'cache-hub';
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `maxEntries` | `number` | `Infinity` | 最大条目数，超限 LRU 淘汰 |
-| `maxMemory` | `number` | `Infinity` | 最大内存（字节估算），超限 LRU 淘汰 |
-| `ttl` | `number` | `0`（不过期）| 默认 TTL（毫秒） |
+| `maxEntries` | `number` | `10000` | 最大条目数，超限 LRU 淘汰 |
+| `maxMemory` | `number` | `0` | 最大内存（字节估算），超限 LRU 淘汰；`0` 表示无内存限制 |
+| `defaultTtl` | `number` | `0`（不过期）| 默认 TTL（毫秒） |
 | `cleanupInterval` | `number` | `0`（不清理）| 周期清理间隔（毫秒） |
-| `enableStats` | `boolean` | `false` | 开启命中率统计 |
+| `enableStats` | `boolean` | `true` | 开启命中率统计 |
 | `enableTags` | `boolean` | `false` | 开启标签索引，支持 `invalidateByTag` |
 | `enabled` | `boolean` | `true` | `false` 时禁用缓存 |
 
@@ -171,20 +171,24 @@ import type { CacheLike, CacheStats, MemoryCacheOptions } from 'cache-hub';
 所有缓存实现均满足此接口，可互相替换：
 
 ```typescript
-interface CacheLike<V = unknown> {
-    get(key: string): V | undefined | Promise<V | undefined>;
-    set(key: string, value: V, ttl?: number): void | Promise<void>;
-    del(key: string): void | Promise<void>;
+interface CacheLike {
+    get<T = any>(key: string): T | undefined | Promise<T | undefined>;
+    set(key: string, value: any, ttl?: number): void | Promise<void>;
+    del(key: string): boolean | Promise<boolean>;
     exists(key: string): boolean | Promise<boolean>;
     has(key: string): boolean | Promise<boolean>;         // exists 的同步别名
     clear(): void | Promise<void>;
-    keys(): string[] | Promise<string[]>;
-    getMany(keys: string[]): Map<string, V> | Promise<Map<string, V>>;
-    setMany(entries: Map<string, V>, ttl?: number): void | Promise<void>;
-    delMany(keys: string[]): void | Promise<void>;
-    delPattern(pattern: string): void | Promise<void>;   // 支持 * 通配符
-    getStats(): CacheStats;
-    destroy(): void | Promise<void>;
+    keys(pattern?: string): string[] | Promise<string[]>;
+    getMany(keys: string[]): Record<string, any> | Promise<Record<string, any>>;
+    setMany(entries: Record<string, any>, ttl?: number): boolean | Promise<boolean>;
+    delMany(keys: string[]): number | Promise<number>;
+    delPattern(pattern: string): number | Promise<number>;   // 支持 * 通配符
+    // 可选扩展
+    invalidateByTag?(tag: string): void | Promise<void>;
+    getStats?(): CacheStats;
+    resetStats?(): void;
+    destroy?(): void;
+    setLockManager?(lm: LockManager): void;
 }
 ```
 
@@ -196,7 +200,7 @@ interface CacheLike<V = unknown> {
 import { readThrough } from 'cache-hub/read-through';
 
 function readThrough<V>(
-    cache: CacheLike<V>,
+    cache: CacheLike,
     ttl: number,
     key: string,
     fetcher: () => Promise<V>
@@ -220,11 +224,11 @@ new MultiLevelCache(options: MultiLevelCacheOptions)
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `local` | `CacheLike` | 必填 | L1 本地缓存 |
-| `remote` | `CacheLike` | 必填 | L2 远端缓存 |
+| `remote` | `CacheLike` | — | L2 远端缓存（可选，未传时作为单级本地缓存运行）|
 | `writePolicy` | `'both' \| 'local-first-async-remote'` | `'both'` | 写策略 |
 | `backfillOnRemoteHit` | `boolean` | `true` | L2 命中时回填 L1 |
 | `remoteTimeoutMs` | `number` | `50` | 远端超时（毫秒），超时降级不报错 |
-| `publish` | `(keys: string[]) => void` | — | 分布式失效广播回调 |
+| `publish` | `(msg: { type: string; pattern: string; ts: number }) => void` | — | `delPattern` 时触发的分布式失效广播回调 |
 
 ---
 
@@ -270,13 +274,13 @@ const cachedFn = withCache(asyncFn, {
 #### `FunctionCache` 类
 
 ```typescript
-const fc = new FunctionCache({ cache, ttl: 30_000 });
+const fc = new FunctionCache(cache, { ttl: 30_000 });
 
 fc.register('getUser', async (id: number) => db.findUser(id));
 fc.register('getProduct', async (id: number) => db.findProduct(id), { ttl: 10_000 });
 
-const user = await fc.execute('getUser', [1]);
-await fc.invalidate('getUser', [1]);  // 使指定参数的缓存失效
+const user = await fc.execute('getUser', 1);
+await fc.invalidate('getUser', 1);  // 使指定参数的缓存失效
 
 const stats = fc.getStats();  // { getUser: { hits, misses, ... } }
 ```
@@ -293,19 +297,19 @@ new DistributedCacheInvalidator(options: DistributedInvalidatorOptions)
 
 | 选项 | 类型 | 说明 |
 |------|------|------|
-| `redisUrl` | `string` | Redis URL，与 `redis` 二选一 |
+| `cache` | `CacheLike` | 必填，接收失效消息时对该实例执行 `delPattern` |
+| `redisUrl` | `string` | Redis URL，与 `redis` 二选一，均未提供时默认 `redis://localhost:6379` |
 | `redis` | `ioredis` | 已有 Redis 连接，与 `redisUrl` 二选一 |
-| `watchedCaches` | `CacheLike[]` | 接收到失效消息时清除这些缓存 |
-| `channel` | `string` | Pub/Sub 频道名，默认 `'cache-hub:invalidation'` |
+| `channel` | `string` | Pub/Sub 频道名，默认 `'cache-hub:invalidate'` |
 | `instanceId` | `string` | 实例唯一 ID，用于过滤自身消息（默认随机生成） |
 
 ```typescript
-// 发布失效事件
-await invalidator.invalidate(['key1', 'key2']);
+// 广播失效事件（支持通配符 *）
+await invalidator.invalidate('user:*');
 
 // 查看统计
 const stats = invalidator.getStats();
-// { published: 5, received: 12, selfFiltered: 5 }
+// { messagesSent: 5, messagesReceived: 12, invalidationsTriggered: 7, errors: 0, instanceId: '...', channel: '...' }
 
 // 关闭连接
 await invalidator.close();
@@ -341,7 +345,7 @@ stableStringify(value, {
 ## 测试
 
 ```bash
-# 单元测试（440 个，无需外部依赖）
+# 全量测试（470 个，集成测试在无 Redis 时自动跳过）
 npm test
 
 # 单元测试 + 覆盖率报告

bugs/发布前配置与文档修复/01-需求定义.md

@@ -0,0 +1,78 @@
+# 需求定义 — 发布前配置与文档修复
+
+**Bug ID**: BUG-发布前配置与文档修复
+**发现于**: 会话20（2026-03-22）audit 工作流（全面体检）
+**修复于**: 会话21（2026-03-22）fix 工作流
+**严重程度**: 🔴 高（B01 虚假 API 声明）+ 🟡 中（W01~W05 发布配置缺陷）
+
+---
+
+## 问题描述
+
+audit 全面体检（会话20，5轮收敛）发现以下 6 项问题，分为两类：
+
+### B01 — 虚假 API 声明（🔴 高优先级）
+
+`website/docs/guide/api-reference.md` 和 `CHANGELOG.md` 均声称 `RedisCacheAdapter` 会对超过 512 字节的 key 自动进行 SHA-256 哈希压缩。
+
+**实际情况**：`redis-adapter.ts` 中**不存在**任何 key 哈希压缩逻辑。SHA-256 压缩仅存在于 `function-cache.ts`（阈值为 1024 字节，约束 A09）。Redis 适配器仅对 `pattern` 超过 512 字符时做截断并打印 `console.warn`（约束 A10），key 无任何长度限制。
+
+用户若按文档描述假设 key 会被自动压缩，将对存储行为产生错误认知，导致调试困难。
+
+### W01~W05 — 发布配置缺陷（🟡 中优先级）
+
+| # | 问题 | 风险 |
+|---|------|------|
+| W01 | `package.json` 缺少 `prepublishOnly` 脚本 | 发布时无安全门禁，可能发布未通过测试或构建失败的版本 |
+| W02 | `package.json` 缺少 `main` / `types` 顶层字段 | 旧版 TypeScript（`moduleResolution: node`）和部分 bundler 无法正确解析包入口 |
+| W03 | `SetOptions` 类型未从主入口 `cache-hub` 导出 | 消费者无法通过 `import type { SetOptions } from 'cache-hub'` 使用标签写入类型 |
+| W04 | `CHANGELOG.md` 中 `CacheStats` 描述缺少 `entries` 和 `memoryUsageMB` 两个字段 | 更新日志与实际类型不一致，读者误以为这两个字段不存在 |
+| W05 | `package.json` 的 `files` 数组未包含 `CHANGELOG.md` | npm publish tarball 不含更新日志，消费者无法在离线包中查阅变更历史 |
+
+---
+
+## 影响范围
+
+| 文件 | 问题 |
+|------|------|
+| `website/docs/guide/api-reference.md` | B01：虚假"超长 key SHA-256 压缩"行 |
+| `CHANGELOG.md` | B01：虚假 Redis key 压缩描述；W04：CacheStats 字段列表不完整 |
+| `package.json` | W01：缺 prepublishOnly；W02：缺 main/types；W05：files 不含 CHANGELOG.md |
+| `src/index.ts` | W03：缺 SetOptions re-export |
+
+---
+
+## 根因分析
+
+- **B01**：会话16 自动生成文档时，将 `function-cache.ts` 的 SHA-256 key 压缩行为误归属到 `RedisCacheAdapter`，未与 `redis-adapter.ts` 源码交叉验证。
+- **W01**：会话16 生成 `package.json` 时未参照 profile/05-发布规范.md 的发布前检查项。
+- **W02**：会话16 采用现代 `exports` 字段配置，未补充传统兼容字段。
+- **W03**：`SetOptions` 为 `MemoryCache.set()` 的扩展参数类型，会话16 仅导出了核心类型，遗漏了此类型。
+- **W04**：会话16 手写 CHANGELOG 时 `CacheStats` 字段列表未与 `src/types.ts` 对齐，`entries` 和 `memoryUsageMB` 两个字段被遗漏。
+- **W05**：会话16 配置 `files` 时仅考虑产物目录，未将 `CHANGELOG.md` 纳入发布清单。
+
+---
+
+## 期望行为
+
+- `api-reference.md` 和 `CHANGELOG.md` 中 `RedisCacheAdapter` 的描述与源码一致：仅 pattern 截断，key 无限制
+- 执行 `npm publish` 前自动运行 typecheck + 测试 + 构建
+- 旧版 TypeScript 和 bundler 可通过顶层 `main`/`types` 字段解析包
+- 消费者可通过 `import type { SetOptions } from 'cache-hub'` 使用标签写入 API
+- `CacheStats` 的 `entries` 和 `memoryUsageMB` 字段在 CHANGELOG 中有记录
+- npm tarball 包含 `CHANGELOG.md`
+
+---
+
+## 验收标准
+
+- [x] `api-reference.md` 删除虚假"超长 key SHA-256 压缩"行
+- [x] `CHANGELOG.md` Redis 描述修正为仅 pattern 截断
+- [x] `CHANGELOG.md` CacheStats 补充 `entries` / `memoryUsageMB`
+- [x] `package.json` 添加 `prepublishOnly` 脚本
+- [x] `package.json` 添加顶层 `main` / `types` 字段
+- [x] `src/index.ts` 导出 `SetOptions` 类型
+- [x] `package.json` `files` 添加 `"CHANGELOG.md"`
+- [x] `npm test` 470 tests 全部通过
+- [x] `npm run typecheck` 无错误
+- [x] `docs:build` 构建成功