@zooique/memora 2.0.0 → 3.0.0

package/dist/utils/fileSafe.js

@@ -0,0 +1,56 @@
+/**
+ * 文件安全访问原语（读取 / stat / 存在性）——收口两侧重复的私有实现
+ *
+ * 背景：全局技能（SkillManager）与角色包内嵌技能（RolePackManager）各自在文件访问上
+ * 长出了私有辅助函数，且**能力不对等**：
+ * - 角色包侧 `readContentSafe` 有**长度上限**（防超大文件膨胀），全局侧 `readFile` 裸读无上限；
+ * - 角色包侧 `getSkillScriptPath` 有**存在性校验**，全局侧无。
+ * 按「差异点取更全面形态」的收敛原则，把**更全面的一侧**提升为共享原语，两侧同时受益。
+ *
+ * 边界：本模块只提供**能力**，不替调用方决定失败语义——
+ * 读取失败返回 null，由调用方决定是降级为空串（角色包内容文件）还是向上报 null（L3 资源）。
+ * 失败语义是对外契约，统一它会造成破坏性变更，故不在本模块收口。
+ */
+import { readFile } from 'node:fs/promises';
+import { statSync, existsSync } from 'node:fs';
+/**
+ * 内容文件读取长度上限（字符）——防超大文件撑爆上下文
+ *
+ * SSOT 说明：角色包侧原以 `MAX_CONTENT_FILE_LEN` 使用本值；提升为共享原语后，
+ * 全局技能读取 L3 资源与 validateFile 也获得同等级保护。
+ */
+export const DEFAULT_MAX_CONTENT_LEN = 200_000;
+/**
+ * 读取文本文件内容，超限截断；失败返回 null（不告警，由调用方决定语义）。
+ *
+ * @param filePath 文件绝对路径
+ * @param maxLen 最大长度（字符），超限截断
+ */
+export async function readFileCapped(filePath, maxLen = DEFAULT_MAX_CONTENT_LEN) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return content.length > maxLen ? content.slice(0, maxLen) : content;
+    }
+    catch {
+        return null;
+    }
+}
+/** 安全的 stat 同步调用：不可访问返回 null，不抛异常（返回完整 `Stats`，调用方按需取字段） */
+export function statSyncSafe(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** 安全的存在性同步调用：不可访问按不存在处理，不抛异常（实现即 `existsSync`，名字与之一致） */
+export function existsSyncSafe(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fileSafe.js.map

package/dist/utils/fileSafe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSafe.js","sourceRoot":"","sources":["../../src/utils/fileSafe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAc,MAAM,SAAS,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAgB,EAChB,SAAiB,uBAAuB;IAExC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,OAAO,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/utils/frontmatter.d.ts

@@ -1,9 +1,8 @@
 /**
  * Frontmatter 通用解析/序列化工具
  *
- * 直接消费者为 memory/store.ts 和 utils/scanner.ts
- * （scanner 间接供 personaManager / skillManager 使用），非 persona/skill 直接 import。
- * 详见 ADR-004 · 记忆统一为"类型 + 永久性标记"模型
+ * 直接消费者为 utils/scanner.ts、skill/skillManager.ts、role-pack/rolePackManager.ts（frontmatter 解析），
+ * 并经 index.ts 导出供宿主复用。
  */
 /**
  * 解析 frontmatter 块为键值对

package/dist/utils/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAsBA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAKhF"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAwBA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAKhF"}

package/dist/utils/frontmatter.js

@@ -1,9 +1,8 @@
 /**
  * Frontmatter 通用解析/序列化工具
  *
- * 直接消费者为 memory/store.ts 和 utils/scanner.ts
- * （scanner 间接供 personaManager / skillManager 使用），非 persona/skill 直接 import。
- * 详见 ADR-004 · 记忆统一为"类型 + 永久性标记"模型
+ * 直接消费者为 utils/scanner.ts、skill/skillManager.ts、role-pack/rolePackManager.ts（frontmatter 解析），
+ * 并经 index.ts 导出供宿主复用。
  */
 /**
  * 解析 frontmatter 块为键值对
@@ -18,8 +17,10 @@
  * @returns `{ frontmatter, body }`——frontmatter 为键值对对象，body 为 frontmatter 之后的内容
  */
 export function parseFrontmatter(raw) {
-    const normalized = raw.replace(/\r\n/g, '\n');
-    const match = normalized.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    const normalized = raw.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+    // 结束 `---` 后允许可选换行（\n?），兼容"以 --- 收尾无尾随换行"的合法文件；
+    // 已先规整掉末尾换行（\n+$），避免"文件以 --- 结尾"被误判为不匹配而整体落入 body。
+    const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     // 仅当结构不匹配时返回 fallback；空 frontmatter 块和空 body 块为合法输入
     if (!match) {
         return { frontmatter: {}, body: raw };

package/dist/utils/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAI1C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACpE,oDAAoD;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACxC,CAAC;IAED,mEAAmE;IACnE,8CAA8C;IAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,WAAW,GAA2B,EAAE,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,GAAG,CAAC;YAAE,SAAS;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC;YAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmC;IACtE,OAAO,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAI1C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClE,gDAAgD;IAChD,mDAAmD;IACnD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACrE,oDAAoD;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACxC,CAAC;IAED,mEAAmE;IACnE,8CAA8C;IAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,WAAW,GAA2B,EAAE,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,GAAG,CAAC;YAAE,SAAS;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC;YAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmC;IACtE,OAAO,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/utils/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 计算字符串的 SHA-256 指纹（hex 格式）
+ *
+ * 用途：
+ *   - "模型看到了什么"可追溯：对系统提示 / 记忆 ID 集合生成轻量指纹，
+ *     让宿主在调试时能对比"本轮注入的内容是否变化"，而不必存储全量内容
+ *
+ * @param input 输入字符串
+ * @returns 64 位小写 hex 哈希
+ */
+export declare function sha256Fingerprint(input: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/utils/hash.js

@@ -0,0 +1,27 @@
+/**
+ * 通用哈希工具 — 内容指纹生成
+ *
+ * 职责：
+ *   - 提供纯函数 sha256Fingerprint，对任意字符串生成 SHA-256 hex 指纹
+ *   - 供可观测性埋点（系统提示指纹、记忆集合指纹）复用，
+ *     避免在 agent/ 层各自重复实现 createHash 逻辑
+ *
+ * 设计约束：
+ *   - 纯函数：无状态、无副作用、同输入同输出
+ *   - 复用 node:crypto（Node.js 内置），零第三方依赖
+ */
+import { createHash } from 'node:crypto';
+/**
+ * 计算字符串的 SHA-256 指纹（hex 格式）
+ *
+ * 用途：
+ *   - "模型看到了什么"可追溯：对系统提示 / 记忆 ID 集合生成轻量指纹，
+ *     让宿主在调试时能对比"本轮注入的内容是否变化"，而不必存储全量内容
+ *
+ * @param input 输入字符串
+ * @returns 64 位小写 hex 哈希
+ */
+export function sha256Fingerprint(input) {
+    return createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+//# sourceMappingURL=hash.js.map

package/dist/utils/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC"}

package/dist/utils/http.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP 网络工具：浏览器 User-Agent 常量 + 带超时控制的 fetch。
+ * web-search / web-fetch 默认实现共享，避免同语义逻辑双处维护（SSOT 下沉）。
+ */
+/** 通用浏览器 User-Agent（避免被目标站当作爬虫拒绝） */
+export declare const BROWSER_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+/**
+ * 带超时控制的 fetch：手动 AbortController + setTimeout（兼容性优于 AbortSignal.timeout），
+ * 防不可达端点挂起调用方；成功/失败均清理定时器。
+ *
+ * @param url 目标 URL
+ * @param timeoutMs 超时毫秒
+ * @param userAgent 可选 UA 头（缺省不发送）
+ * @returns fetch Response（调用方负责检查 ok 与 body 读取）
+ */
+export declare function fetchWithTimeout(url: string, timeoutMs: number, userAgent?: string): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/dist/utils/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qCAAqC;AACrC,eAAO,MAAM,UAAU,oHAC4F,CAAC;AAEpH;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/dist/utils/http.js

@@ -0,0 +1,29 @@
+/**
+ * HTTP 网络工具：浏览器 User-Agent 常量 + 带超时控制的 fetch。
+ * web-search / web-fetch 默认实现共享，避免同语义逻辑双处维护（SSOT 下沉）。
+ */
+/** 通用浏览器 User-Agent（避免被目标站当作爬虫拒绝） */
+export const BROWSER_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+/**
+ * 带超时控制的 fetch：手动 AbortController + setTimeout（兼容性优于 AbortSignal.timeout），
+ * 防不可达端点挂起调用方；成功/失败均清理定时器。
+ *
+ * @param url 目标 URL
+ * @param timeoutMs 超时毫秒
+ * @param userAgent 可选 UA 头（缺省不发送）
+ * @returns fetch Response（调用方负责检查 ok 与 body 读取）
+ */
+export async function fetchWithTimeout(url, timeoutMs, userAgent) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, {
+            headers: userAgent ? { 'User-Agent': userAgent } : undefined,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/utils/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qCAAqC;AACrC,MAAM,CAAC,MAAM,UAAU,GACrB,iHAAiH,CAAC;AAEpH;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,SAAiB,EACjB,SAAkB;IAElB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE;YACtB,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS;YAC5D,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/utils/json.d.ts

@@ -1,7 +1,7 @@
 /**
  * JSON 工具函数
  *
- * 从 InsightExtractor 和 WorkProjectionManager 提取的公共 JSON 解析函数，
+ * 从多个 Manager（如 WorkProjectionManager）提取的公共 JSON 解析函数，
  * 统一 LLM 输出的 JSON 解析策略。
  */
 /**

package/dist/utils/json.js

@@ -1,7 +1,7 @@
 /**
  * JSON 工具函数
  *
- * 从 InsightExtractor 和 WorkProjectionManager 提取的公共 JSON 解析函数，
+ * 从多个 Manager（如 WorkProjectionManager）提取的公共 JSON 解析函数，
  * 统一 LLM 输出的 JSON 解析策略。
  */
 /**

package/dist/utils/math.d.ts

@@ -1,5 +1,38 @@
 /**
  * 数学工具函数
  */
-export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * 将数值四舍五入到指定小数位数
+ *
+ * 替代 `Math.round(x * 10^n) / 10^n` 惯用法，消除 4 处重复。
+ *
+ * @param value - 待四舍五入的数值
+ * @param decimals - 保留的小数位数（0~20，默认 2）
+ * @returns 四舍五入后的数值；value 为 NaN/Infinity 时原样返回
+ */
+export declare function roundTo(value: number, decimals?: number): number;
+/**
+ * 正整数解析（单一真源）：缺省 / 非法 / ≤0 → undefined，否则返回 parseInt 结果。
+ *
+ * 供 `builtinToolHandlers`（read_file 分段 offset/limit）与 `toolResultCache`（去重主体）
+ * 共用——两处语义一致（「缺省 / 非法 / <1 一律视为缺省，默认值交给调用方」），
+ * 避免同一规则散落两处（legacy-contract-audit 重复实现）。
+ *
+ * @param v 输入（string | number 之外一律归 undefined；`"12px"` 这类前导数字按 parseInt 语义解析）
+ * @returns 正整数，或 undefined
+ */
+export declare function positiveInt(v: unknown): number | undefined;
+/**
+ * 工具 limit 参数解析 + 上限钳制（单一真源）
+ *
+ * 收口 builtinToolHandlers 三个工具（search_memories / trace_summary / list_sessions）
+ * 各自手写的「parseInt + NaN/负→默认值 + 超上限钳制」三份。语义与 positiveInt 一致：
+ * 非法输入回退默认值；合法但超上限则钳制到上限（各工具上限是自身契约，由调用方传入）。
+ *
+ * @param value 参数原始字符串（undefined 时直接回退默认值）
+ * @param defaultValue 非法 / 缺失时的回退值
+ * @param max 上限（钳制，应 ≥ defaultValue）
+ * @returns 解析后的 limit 值
+ */
+export declare function parseLimit(value: string | undefined, defaultValue: number, max: number): number;
 //# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAajE"}
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAK3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/F"}

package/dist/utils/math.js

@@ -1,19 +1,52 @@
 /**
  * 数学工具函数
  */
-export function cosineSimilarity(a, b) {
-    if (a.length !== b.length)
-        return 0;
-    let dot = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        // QC-17 移除非空断言：循环条件保证索引有效，用 ?? 0 兜底（数学上 0 不影响点积）
-        dot += (a[i] ?? 0) * (b[i] ?? 0);
-        normA += (a[i] ?? 0) * (a[i] ?? 0);
-        normB += (b[i] ?? 0) * (b[i] ?? 0);
-    }
-    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
-    return denominator === 0 ? 0 : dot / denominator;
+/**
+ * 将数值四舍五入到指定小数位数
+ *
+ * 替代 `Math.round(x * 10^n) / 10^n` 惯用法，消除 4 处重复。
+ *
+ * @param value - 待四舍五入的数值
+ * @param decimals - 保留的小数位数（0~20，默认 2）
+ * @returns 四舍五入后的数值；value 为 NaN/Infinity 时原样返回
+ */
+export function roundTo(value, decimals = 2) {
+    // NaN/Infinity 不参与运算，避免 Math.round 返回意外结果
+    if (!Number.isFinite(value))
+        return value;
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * 正整数解析（单一真源）：缺省 / 非法 / ≤0 → undefined，否则返回 parseInt 结果。
+ *
+ * 供 `builtinToolHandlers`（read_file 分段 offset/limit）与 `toolResultCache`（去重主体）
+ * 共用——两处语义一致（「缺省 / 非法 / <1 一律视为缺省，默认值交给调用方」），
+ * 避免同一规则散落两处（legacy-contract-audit 重复实现）。
+ *
+ * @param v 输入（string | number 之外一律归 undefined；`"12px"` 这类前导数字按 parseInt 语义解析）
+ * @returns 正整数，或 undefined
+ */
+export function positiveInt(v) {
+    const n = Number.parseInt(String(v), 10);
+    return Number.isNaN(n) || n < 1 ? undefined : n;
+}
+/**
+ * 工具 limit 参数解析 + 上限钳制（单一真源）
+ *
+ * 收口 builtinToolHandlers 三个工具（search_memories / trace_summary / list_sessions）
+ * 各自手写的「parseInt + NaN/负→默认值 + 超上限钳制」三份。语义与 positiveInt 一致：
+ * 非法输入回退默认值；合法但超上限则钳制到上限（各工具上限是自身契约，由调用方传入）。
+ *
+ * @param value 参数原始字符串（undefined 时直接回退默认值）
+ * @param defaultValue 非法 / 缺失时的回退值
+ * @param max 上限（钳制，应 ≥ defaultValue）
+ * @returns 解析后的 limit 值
+ */
+export function parseLimit(value, defaultValue, max) {
+    if (value === undefined)
+        return Math.min(defaultValue, max);
+    const n = positiveInt(value);
+    return Math.min(n ?? defaultValue, max);
 }
 //# sourceMappingURL=math.js.map

package/dist/utils/math.js.map

@@ -1 +1 @@
-{"version":3,"file":"math.js","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,iDAAiD;QACjD,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACjC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,WAAW,CAAC;AACnD,CAAC"}
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,QAAQ,GAAG,CAAC;IACjD,0CAA0C;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,MAAM,GAAG,EAAE,IAAI,QAAQ,CAAC;IAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,KAAyB,EAAE,YAAoB,EAAE,GAAW;IACrF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC5D,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,YAAY,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC"}

package/dist/utils/objects.d.ts

@@ -1,14 +1,13 @@
 /**
  * 对象类型守卫工具函数
  *
- * 从 lockManager / projectRegistry / spriteConfig 提取的公共对象类型校验函数，
- * 消除跨模块重复的类型守卫代码（ADR-017 枝叶层 2 次提取原则）。
+ * 从多个模块提取的公共对象类型校验函数，
+ * 消除跨模块重复的类型守卫代码。
  */
 /**
  * 判断值是否为普通对象（非 null、非数组）
  *
  * 用于校验 JSON.parse 的结果，避免对非对象类型执行展开或属性访问。
- * 三处原私有实现完全一致（lockManager / projectRegistry / spriteConfig）。
  *
  * @param value 待校验的值
  * @returns true 表示是普通对象（类型收窄为 Record<string, unknown>）

package/dist/utils/objects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../src/utils/objects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E"}
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../src/utils/objects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E"}

package/dist/utils/objects.js

@@ -1,14 +1,13 @@
 /**
  * 对象类型守卫工具函数
  *
- * 从 lockManager / projectRegistry / spriteConfig 提取的公共对象类型校验函数，
- * 消除跨模块重复的类型守卫代码（ADR-017 枝叶层 2 次提取原则）。
+ * 从多个模块提取的公共对象类型校验函数，
+ * 消除跨模块重复的类型守卫代码。
  */
 /**
  * 判断值是否为普通对象（非 null、非数组）
  *
  * 用于校验 JSON.parse 的结果，避免对非对象类型执行展开或属性访问。
- * 三处原私有实现完全一致（lockManager / projectRegistry / spriteConfig）。
  *
  * @param value 待校验的值
  * @returns true 表示是普通对象（类型收窄为 Record<string, unknown>）

package/dist/utils/objects.js.map

@@ -1 +1 @@
-{"version":3,"file":"objects.js","sourceRoot":"","sources":["../../src/utils/objects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"objects.js","sourceRoot":"","sources":["../../src/utils/objects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/utils/recallDefaults.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 召回默认值——单一真理源（记忆层与 agent 层共享）。
+ *
+ * 召回不设保底下限（无 `DEFAULT_MIN_FALLBACK`）——保底仅在「检查点恢复的温记忆召回」
+ * 场景有意义，该链路不在实现内。
+ */
+/**
+ * 召回排除 source 默认值（空数组）——设定记忆（persona/rule/skill）归角色包、
+ * 记忆库不写入，不参与召回排除（memory-role-pack-boundary），此处为空默认。
+ *
+ * **唯一活性消费者 = `MemoryAdvisor.suggest()`**（关联推荐的 `excludeSources` 本地参数缺省值）；
+ * 不存在同名配置管道 `config.recallExcludeSources`（ContextPreparer 侧）——`assembleContext`
+ * 从不读取该配置（死配置），勿因「两处同名」而误以为是一根链。
+ */
+export declare const DEFAULT_RECALL_EXCLUDE_SOURCES: readonly string[];
+//# sourceMappingURL=recallDefaults.d.ts.map

package/dist/utils/recallDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recallDefaults.d.ts","sourceRoot":"","sources":["../../src/utils/recallDefaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAAO,CAAC"}

package/dist/utils/recallDefaults.js

@@ -0,0 +1,16 @@
+/**
+ * 召回默认值——单一真理源（记忆层与 agent 层共享）。
+ *
+ * 召回不设保底下限（无 `DEFAULT_MIN_FALLBACK`）——保底仅在「检查点恢复的温记忆召回」
+ * 场景有意义，该链路不在实现内。
+ */
+/**
+ * 召回排除 source 默认值（空数组）——设定记忆（persona/rule/skill）归角色包、
+ * 记忆库不写入，不参与召回排除（memory-role-pack-boundary），此处为空默认。
+ *
+ * **唯一活性消费者 = `MemoryAdvisor.suggest()`**（关联推荐的 `excludeSources` 本地参数缺省值）；
+ * 不存在同名配置管道 `config.recallExcludeSources`（ContextPreparer 侧）——`assembleContext`
+ * 从不读取该配置（死配置），勿因「两处同名」而误以为是一根链。
+ */
+export const DEFAULT_RECALL_EXCLUDE_SOURCES = [];
+//# sourceMappingURL=recallDefaults.js.map

package/dist/utils/recallDefaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recallDefaults.js","sourceRoot":"","sources":["../../src/utils/recallDefaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAsB,EAAE,CAAC"}

package/dist/utils/safeTimer.d.ts

@@ -1,45 +1,17 @@
 /**
- * 安全定时器工具 — 提供可追踪的生命周期管理
- *
- * 原生 setTimeout / setInterval 不跟踪定时器 ID，
- * 如果忘记清理可能导致内存泄漏。本模块提供轻量包装，
- * 统一管理定时器的创建和清理。
- */
-/**
- * 安全的 setTimeout 包装
- * 返回的 timer ID 可用于 clearSafeTimeout 清理
+ * 安全定时器工具——原生 setTimeout/setInterval 不跟踪 ID，忘记清理会内存泄漏；
+ * 本模块统一登记创建与清理，提供可追踪的生命周期管理。
  */
+/** 安全 setTimeout：触发后自动从注册表移除；返回 timer ID */
 export declare function safeSetTimeout(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
-/**
- * 安全的 setInterval 包装
- * 返回的 timer ID 可用于 clearSafeInterval 清理
- */
+/** 安全 setInterval：周期定时器，返回 timer ID */
 export declare function safeSetInterval(callback: () => void, ms: number): ReturnType<typeof setInterval>;
-/**
- * 清理安全的 setTimeout
- */
+/** 清理安全 setTimeout（同时从注册表移除） */
 export declare function clearSafeTimeout(id: ReturnType<typeof setTimeout> | null): void;
-/**
- * 清理安全的 setInterval
- */
+/** 清理安全 setInterval（同时从注册表移除） */
 export declare function clearSafeInterval(id: ReturnType<typeof setInterval> | null): void;
-/**
- * 获取活跃定时器数量（仅供测试 + 调试用，验证 activeTimers 注册表清理）
- *
- * 场景：safeSetTimeout 触发后应自动从注册表移除；clearSafeTimeout/clearSafeInterval
- * 应立即从注册表移除。此函数用于直接断言注册表状态，而非仅通过回调触发间接验证。
- *
- * @returns 当前活跃定时器数量
- */
+/** 获取活跃定时器数量（测试 + 调试用，验证注册表清理） */
 export declare function getActiveTimerCount(): number;
-/**
- * 清理所有活跃定时器（兜底清理机制）
- *
- * 场景：
- *   - 测试隔离：每个测试 beforeEach 调用，确保 activeTimers 注册表无残留
- *
- * 注意：此函数会清理所有通过 safeSetTimeout/safeSetInterval 创建的定时器，
- *       包括尚未触发的 timeout 和正在重复的 interval。
- */
+/** 清理所有活跃定时器（兜底，用于测试隔离，清理含未触发 timeout 与运行中 interval） */
 export declare function clearAllSafeTimers(): void;
 //# sourceMappingURL=safeTimer.d.ts.map

package/dist/utils/safeTimer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safeTimer.d.ts","sourceRoot":"","sources":["../../src/utils/safeTimer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,GACT,UAAU,CAAC,OAAO,UAAU,CAAC,CAO/B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,IAAI,EACpB,EAAE,EAAE,MAAM,GACT,UAAU,CAAC,OAAO,WAAW,CAAC,CAIhC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,GAAG,IAAI,CAK/E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,GAAG,IAAI,CAKjF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC"}
+{"version":3,"file":"safeTimer.d.ts","sourceRoot":"","sources":["../../src/utils/safeTimer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAO9F;AAED,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAIhG;AAED,gCAAgC;AAChC,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,GAAG,IAAI,CAK/E;AAED,iCAAiC;AACjC,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,GAAG,IAAI,CAKjF;AAED,kCAAkC;AAClC,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC"}

package/dist/utils/safeTimer.js

@@ -1,16 +1,10 @@
 /**
- * 安全定时器工具 — 提供可追踪的生命周期管理
- *
- * 原生 setTimeout / setInterval 不跟踪定时器 ID，
- * 如果忘记清理可能导致内存泄漏。本模块提供轻量包装，
- * 统一管理定时器的创建和清理。
+ * 安全定时器工具——原生 setTimeout/setInterval 不跟踪 ID，忘记清理会内存泄漏；
+ * 本模块统一登记创建与清理，提供可追踪的生命周期管理。
  */
-/** 定时器注册表，用于跟踪所有活跃定时器 */
+/** 所有活跃定时器注册表（供统一清理与调试断言） */
 const activeTimers = new Set();
-/**
- * 安全的 setTimeout 包装
- * 返回的 timer ID 可用于 clearSafeTimeout 清理
- */
+/** 安全 setTimeout：触发后自动从注册表移除；返回 timer ID */
 export function safeSetTimeout(callback, ms) {
     const id = setTimeout(() => {
         activeTimers.delete(id);
@@ -19,53 +13,31 @@ export function safeSetTimeout(callback, ms) {
     activeTimers.add(id);
     return id;
 }
-/**
- * 安全的 setInterval 包装
- * 返回的 timer ID 可用于 clearSafeInterval 清理
- */
+/** 安全 setInterval：周期定时器，返回 timer ID */
 export function safeSetInterval(callback, ms) {
     const id = setInterval(callback, ms);
     activeTimers.add(id);
     return id;
 }
-/**
- * 清理安全的 setTimeout
- */
+/** 清理安全 setTimeout（同时从注册表移除） */
 export function clearSafeTimeout(id) {
     if (id !== null) {
         clearTimeout(id);
         activeTimers.delete(id);
     }
 }
-/**
- * 清理安全的 setInterval
- */
+/** 清理安全 setInterval（同时从注册表移除） */
 export function clearSafeInterval(id) {
     if (id !== null) {
         clearInterval(id);
         activeTimers.delete(id);
     }
 }
-/**
- * 获取活跃定时器数量（仅供测试 + 调试用，验证 activeTimers 注册表清理）
- *
- * 场景：safeSetTimeout 触发后应自动从注册表移除；clearSafeTimeout/clearSafeInterval
- * 应立即从注册表移除。此函数用于直接断言注册表状态，而非仅通过回调触发间接验证。
- *
- * @returns 当前活跃定时器数量
- */
+/** 获取活跃定时器数量（测试 + 调试用，验证注册表清理） */
 export function getActiveTimerCount() {
     return activeTimers.size;
 }
-/**
- * 清理所有活跃定时器（兜底清理机制）
- *
- * 场景：
- *   - 测试隔离：每个测试 beforeEach 调用，确保 activeTimers 注册表无残留
- *
- * 注意：此函数会清理所有通过 safeSetTimeout/safeSetInterval 创建的定时器，
- *       包括尚未触发的 timeout 和正在重复的 interval。
- */
+/** 清理所有活跃定时器（兜底，用于测试隔离，清理含未触发 timeout 与运行中 interval） */
 export function clearAllSafeTimers() {
     for (const id of activeTimers) {
         clearTimeout(id);

package/dist/utils/safeTimer.js.map

@@ -1 +1 @@
-{"version":3,"file":"safeTimer.js","sourceRoot":"","sources":["../../src/utils/safeTimer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yBAAyB;AACzB,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkE,CAAC;AAE/F;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAoB,EACpB,EAAU;IAEV,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;QACzB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxB,QAAQ,EAAE,CAAC;IACb,CAAC,EAAE,EAAE,CAAC,CAAC;IACP,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAoB,EACpB,EAAU;IAEV,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAwC;IACvE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,CAAC;QACjB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAyC;IACzE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,CAAC,IAAI,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC9B,YAAY,CAAC,EAAE,CAAC,CAAC;QACjB,aAAa,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IACD,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"safeTimer.js","sourceRoot":"","sources":["../../src/utils/safeTimer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,6BAA6B;AAC7B,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkE,CAAC;AAE/F,4CAA4C;AAC5C,MAAM,UAAU,cAAc,CAAC,QAAoB,EAAE,EAAU;IAC7D,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;QACzB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxB,QAAQ,EAAE,CAAC;IACb,CAAC,EAAE,EAAE,CAAC,CAAC;IACP,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,eAAe,CAAC,QAAoB,EAAE,EAAU;IAC9D,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,gBAAgB,CAAC,EAAwC;IACvE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,CAAC,CAAC;QACjB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,iBAAiB,CAAC,EAAyC;IACzE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,mBAAmB;IACjC,OAAO,YAAY,CAAC,IAAI,CAAC;AAC3B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,kBAAkB;IAChC,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC9B,YAAY,CAAC,EAAE,CAAC,CAAC;QACjB,aAAa,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IACD,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}