@zooique/memora 2.0.3 → 3.0.0

package/dist/utils/errors.d.ts

@@ -1,43 +1,38 @@
 /**
- * 统一错误类型
+ * 统一错误类型——把"系统 Error + 英文 stack"包装成"分类清晰 + 中文友好 + 有下一步建议"。
+ * 展示：标题（一眼看出问题）+ 详情（排查用）+ 建议（怎么修复）。
  *
- * 把"系统 Error + 英文 stack trace"包装成"分类清晰 + 中文友好 + 有下一步建议"的错误
- * 详见 ADR-006 · 安全模型
+ * **形态**：错误类只有 `MemoraError` 一个（承载 title/detail/suggestions/category）；
+ * 分类不靠子类，靠 `category` 字段 —— 工厂函数按分类建实例：
+ * `configError` / `networkError` / `llmError` / `toolError` / `securityError`，
+ * 另有统一文案模板 `chatBusyError`（对话繁忙，内部走 configError）。
+ * ⚠️ 旧注释曾写「4 大类 ConfigError/NetworkError/…」——**本文件不存在这些 PascalCase 类名**
+ * （既非类也非工厂名），且实为 **6 个 category 值**：`security` 由 securityError 产出、
+ * 被 security/pathGuard 生产消费 4 处；`unknown` 为兜底值（当前无工厂产出，供直接构造保留）。
+ * 勿按旧注释去改分类集合。
  *
- * 4 大类：
- *   - ConfigError      配置错误（apiKey 缺失、provider 不支持等）
- *   - NetworkError     网络错误（连接超时、DNS 失败、限流等）
- *   - LlmError         LLM 错误（4xx/5xx、返回异常 JSON）
- *   - ToolError        工具错误（路径越界、参数无效等）
- *
- * 错误展示原则：
- *   1. 标题（中文）—— 一眼看出什么问题
- *   2. 详情（原文）—— 排查用
- *   3. 建议（下一步）—— 怎么修复
+ * ⚠️ 与宿主 `LlmErrorCategory`（'connection'|'timeout'|'unknown'）**不是同一个联合**：
+ * 后者是**流式 error chunk** 的分类（见 hosts shared/protocol.ts），本文件只管 MemoraError。
  */
-export { toError } from '../utils/toError.js';
 type ErrorCategory = 'config' | 'network' | 'llm' | 'tool' | 'security' | 'unknown';
 /**
- * 工具错误码 — 用于 AgentLoop 的 Reflection（反思/自修正）逻辑
- *
- * 每个错误码关联一个 retryable 标记：
- *   - retryable：LLM 可以调整参数后重试（如文件路径错误、参数类型错误）
- *   - non-retryable：重试无意义（如权限拒绝、用户拒绝写入）
+ * 工具错误码——供 AgentLoop 的 Reflection（自修正）判断是否可重试：
+ * retryable 表示 LLM 调整参数后可重试；non-retryable 重试无意义。
  */
 export declare const ToolErrorCode: {
     /** 路径不在白名单内（不可重试） */
     readonly PATH_NOT_ALLOWED: "PATH_NOT_ALLOWED";
-    /** 文件不存在（可重试 — LLM 可能用错了路径） */
+    /** 文件不存在（可重试） */
     readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
     /** 权限不足（不可重试） */
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    /** 工具参数错误（可重试 — LLM 可以修正参数格式） */
+    /** 参数错误（可重试） */
     readonly ARGUMENT_ERROR: "ARGUMENT_ERROR";
     /** 用户拒绝写入（不可重试） */
     readonly WRITE_REJECTED: "WRITE_REJECTED";
-    /** 目录不存在（可重试 — LLM 可能用错了路径） */
+    /** 目录不存在（可重试） */
     readonly DIR_NOT_FOUND: "DIR_NOT_FOUND";
-    /** 未知工具（不可重试 — 工具未注册） */
+    /** 未知工具（不可重试） */
     readonly UNKNOWN_TOOL: "UNKNOWN_TOOL";
     /** 自定义工具执行失败（可重试） */
     readonly CUSTOM_TOOL_FAILED: "CUSTOM_TOOL_FAILED";
@@ -47,17 +42,11 @@ export declare const ToolErrorCode: {
 export type ToolErrorCodeValue = (typeof ToolErrorCode)[keyof typeof ToolErrorCode];
 export declare function isRetryableErrorCode(code: ToolErrorCodeValue): boolean;
 interface FriendlyErrorOptions {
-    /** 用户能看懂的简短标题（中文） */
     title: string;
-    /** 详细原因（可含原文） */
     detail?: string;
-    /** 下一步建议（数组，按优先级） */
     suggestions: string[];
-    /** 错误分类 */
     category: ErrorCategory;
-    /** 工具错误码（用于 AgentLoop Reflection 判断是否可重试） */
     errorCode?: ToolErrorCodeValue;
-    /** 原始错误（保留 stack） */
     cause?: Error;
 }
 export declare class MemoraError extends Error {
@@ -65,60 +54,46 @@ export declare class MemoraError extends Error {
     readonly detail: string | undefined;
     readonly suggestions: readonly string[];
     readonly category: ErrorCategory;
-    /** 工具错误码（用于 AgentLoop 反思判断是否可重试） */
     readonly errorCode: ToolErrorCodeValue | undefined;
     readonly cause: Error | undefined;
     constructor(opts: FriendlyErrorOptions);
-    /**
-     * 格式化为用户可读的展示字符串
-     */
+    /** 格式化为用户可读的展示字符串 */
     format(): string;
 }
-/**
- * 工厂：配置错误
- */
+/** 工厂：配置错误 */
 export declare function configError(title: string, detail: string | undefined, suggestions: string[], cause?: Error): MemoraError;
-/**
- * 工厂：对话繁忙错误
- *
- * 用于 chat() 进行中时拒绝其他需要独占 Agent 的操作（切换项目/Provider/会话/重载配置等）。
- * 12 处调用点统一使用此工厂，消除 `configError('对话繁忙', ...)` 的重复模板（ADR-017 枝叶层 2 次提取）。
- *
- * @param action 被拒绝的操作描述（如"切换项目"），拼接到"请等待其结束后再"之后
- * @returns MemoraError（config 类别）
- */
+/** 工厂：对话繁忙错误——chat() 进行中拒绝其他需独占 Agent 的操作，统一模板用此工厂 */
 export declare function chatBusyError(action: string): MemoraError;
-/**
- * 工厂：网络错误
- */
+/** 工厂：网络错误 */
 export declare function networkError(title: string, detail: string | undefined, suggestions: string[], cause?: Error): MemoraError;
-/**
- * 工厂：LLM 错误
- */
+/** 工厂：LLM 错误 */
 export declare function llmError(title: string, detail: string | undefined, suggestions: string[], cause?: Error): MemoraError;
-/**
- * 工厂：工具错误
- */
+/** 工厂：工具错误 */
 export declare function toolError(title: string, detail: string | undefined, suggestions: string[], cause?: Error, errorCode?: ToolErrorCodeValue): MemoraError;
-/**
- * 工厂：安全错误（路径越界、黑名单命中、权限不足等）
- */
+/** 工厂：安全错误（路径越界、黑名单命中、权限不足等） */
 export declare function securityError(title: string, detail: string | undefined, suggestions: string[], cause?: Error): MemoraError;
+/** 判断是否为 AbortError（用户主动取消或超时中断）——统一基于 err.name === 'AbortError'，
+ *  兼容原生 DOMException / 普通 Error 子类 / toError() 规范化后对象。 */
+export declare function isAbortError(err: unknown): boolean;
+/** 判断 AbortSignal 是否为「超时中断」（chat 锁超时 / LLM 无响应超时统一以 TimeoutError reason 标识）。
+ *  与用户取消（abort() 无 reason / AbortError reason）区分——锁超时中断不能谎报成用户取消。 */
+export declare function isTimeoutAbortSignal(signal: AbortSignal | undefined): boolean;
 /**
- * 判断错误是否为 AbortError（用户主动取消或超时中断）
+ * 判断**抛出的错误**是否为「超时」（非 abort 路径的载体）。
  *
- * AbortError 可能源于：
- *   - AbortController.abort() 触发的 fetch 取消（DOMException with name='AbortError'）
- *   - 超时机制（setTimeout + abort）触发的 AbortError
- *   - 用户主动取消（停止生成按钮）
+ * 与 `isTimeoutAbortSignal` 是**同一语义的两种载体**（同判 `name === 'TimeoutError'`）：
+ * 前者看 `signal.reason`（signal 被 abort 的路径），本函数看**被抛出的错误对象**——
+ * 典型场景 = `openaiCompatible.parseSseStream` 的 SSE 停摆看门狗（`Promise.race` 竞速闸
+ * reject `DOMException('…','TimeoutError')`），它不经过 abort signal，故被归类为「失败」
+ * 而非「中断」，最终由 `consumeExecutionStream` 的通用 catch 收口。
  *
- * 统一基于 `err.name === 'AbortError'` 判定，兼容：
- *   - 原生 DOMException（modern Node 18+ / 浏览器中 DOMException 是 Error 子类）
- *   - 普通 Error 子类（name 字段被设为 'AbortError'）
- *   - toError() 规范化后的 Error
+ * **用途（否则宿主文案不可达）**：把超时归入 `error.category = 'timeout'`，让宿主
+ * `chatPanel` 的 `friendlyByCategory.timeout`（「对话处理超时，请稍后重试」）真正生效；
+ * 缺该分类时宿主只能回退**原始技术文案**（DOMException message），用户读到的是侦探材料。
  *
- * @param err 未知类型的错误对象
- * @returns 是否为 AbortError
+ * 注：`toError()` 对 Error 实例原样返回（实测 `DOMException instanceof Error === true`），
+ * 故经 `llmCaller` 的 `toError(err)` 再 rethrow 后 `name` 不丢，本判据在链路末端依然成立。
  */
-export declare function isAbortError(err: unknown): boolean;
+export declare function isTimeoutError(err: unknown): boolean;
+export {};
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEpF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;IACxB,qBAAqB;;IAErB,+BAA+B;;IAE/B,iBAAiB;;IAEjB,iCAAiC;;IAEjC,mBAAmB;;IAEnB,+BAA+B;;IAE/B,yBAAyB;;IAEzB,qBAAqB;;IAErB,iBAAiB;;CAET,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAYpF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAEtE;AAGD,UAAU,oBAAoB;IAC5B,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,IAAI,EAAE,oBAAoB;IAWtC;;OAEG;IACH,MAAM,IAAI,MAAM;CAYjB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,CAAC,EAAE,KAAK,GACZ,WAAW,CAEb;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAMzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,CAAC,EAAE,KAAK,GACZ,WAAW,CAEb;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,CAAC,EAAE,KAAK,GACZ,WAAW,CAEb;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,CAAC,EAAE,KAAK,EACb,SAAS,CAAC,EAAE,kBAAkB,GAC7B,WAAW,CAEb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,CAAC,EAAE,KAAK,GACZ,WAAW,CAEb;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.js

@@ -1,53 +1,44 @@
 /**
- * 统一错误类型
+ * 统一错误类型——把"系统 Error + 英文 stack"包装成"分类清晰 + 中文友好 + 有下一步建议"。
+ * 展示：标题（一眼看出问题）+ 详情（排查用）+ 建议（怎么修复）。
  *
- * 把"系统 Error + 英文 stack trace"包装成"分类清晰 + 中文友好 + 有下一步建议"的错误
- * 详见 ADR-006 · 安全模型
+ * **形态**：错误类只有 `MemoraError` 一个（承载 title/detail/suggestions/category）；
+ * 分类不靠子类，靠 `category` 字段 —— 工厂函数按分类建实例：
+ * `configError` / `networkError` / `llmError` / `toolError` / `securityError`，
+ * 另有统一文案模板 `chatBusyError`（对话繁忙，内部走 configError）。
+ * ⚠️ 旧注释曾写「4 大类 ConfigError/NetworkError/…」——**本文件不存在这些 PascalCase 类名**
+ * （既非类也非工厂名），且实为 **6 个 category 值**：`security` 由 securityError 产出、
+ * 被 security/pathGuard 生产消费 4 处；`unknown` 为兜底值（当前无工厂产出，供直接构造保留）。
+ * 勿按旧注释去改分类集合。
  *
- * 4 大类：
- *   - ConfigError      配置错误（apiKey 缺失、provider 不支持等）
- *   - NetworkError     网络错误（连接超时、DNS 失败、限流等）
- *   - LlmError         LLM 错误（4xx/5xx、返回异常 JSON）
- *   - ToolError        工具错误（路径越界、参数无效等）
- *
- * 错误展示原则：
- *   1. 标题（中文）—— 一眼看出什么问题
- *   2. 详情（原文）—— 排查用
- *   3. 建议（下一步）—— 怎么修复
+ * ⚠️ 与宿主 `LlmErrorCategory`（'connection'|'timeout'|'unknown'）**不是同一个联合**：
+ * 后者是**流式 error chunk** 的分类（见 hosts shared/protocol.ts），本文件只管 MemoraError。
  */
-// re-export toError 供混合 import 场景使用（如 import { securityError, toError }）
-// 单独需要零 logger 依赖的 toError 时应直接 import from '../utils/toError.js'（浏览器友好）。
-export { toError } from '../utils/toError.js';
 /**
- * 工具错误码 — 用于 AgentLoop 的 Reflection（反思/自修正）逻辑
- *
- * 每个错误码关联一个 retryable 标记：
- *   - retryable：LLM 可以调整参数后重试（如文件路径错误、参数类型错误）
- *   - non-retryable：重试无意义（如权限拒绝、用户拒绝写入）
+ * 工具错误码——供 AgentLoop 的 Reflection（自修正）判断是否可重试：
+ * retryable 表示 LLM 调整参数后可重试；non-retryable 重试无意义。
  */
 export const ToolErrorCode = {
     /** 路径不在白名单内（不可重试） */
     PATH_NOT_ALLOWED: 'PATH_NOT_ALLOWED',
-    /** 文件不存在（可重试 — LLM 可能用错了路径） */
+    /** 文件不存在（可重试） */
     FILE_NOT_FOUND: 'FILE_NOT_FOUND',
     /** 权限不足（不可重试） */
     PERMISSION_DENIED: 'PERMISSION_DENIED',
-    /** 工具参数错误（可重试 — LLM 可以修正参数格式） */
+    /** 参数错误（可重试） */
     ARGUMENT_ERROR: 'ARGUMENT_ERROR',
     /** 用户拒绝写入（不可重试） */
     WRITE_REJECTED: 'WRITE_REJECTED',
-    /** 目录不存在（可重试 — LLM 可能用错了路径） */
+    /** 目录不存在（可重试） */
     DIR_NOT_FOUND: 'DIR_NOT_FOUND',
-    /** 未知工具（不可重试 — 工具未注册） */
+    /** 未知工具（不可重试） */
     UNKNOWN_TOOL: 'UNKNOWN_TOOL',
     /** 自定义工具执行失败（可重试） */
     CUSTOM_TOOL_FAILED: 'CUSTOM_TOOL_FAILED',
     /** 通用错误（不可重试） */
     UNKNOWN: 'UNKNOWN',
 };
-/**
- * 判断错误码是否可重试
- */
+/** 可重试错误码集合 */
 const RETRYABLE_ERROR_CODES = new Set([
     ToolErrorCode.FILE_NOT_FOUND,
     ToolErrorCode.ARGUMENT_ERROR,
@@ -62,7 +53,6 @@ export class MemoraError extends Error {
     detail;
     suggestions;
     category;
-    /** 工具错误码（用于 AgentLoop 反思判断是否可重试） */
     errorCode;
     cause;
     constructor(opts) {
@@ -75,9 +65,7 @@ export class MemoraError extends Error {
         this.errorCode = opts.errorCode;
         this.cause = opts.cause;
     }
-    /**
-     * 格式化为用户可读的展示字符串
-     */
+    /** 格式化为用户可读的展示字符串 */
     format() {
         const lines = [];
         lines.push(`❌ ${this.title}`);
@@ -92,66 +80,61 @@ export class MemoraError extends Error {
         return lines.join('\n');
     }
 }
-/**
- * 工厂：配置错误
- */
+/** 工厂：配置错误 */
 export function configError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'config', cause });
 }
-/**
- * 工厂：对话繁忙错误
- *
- * 用于 chat() 进行中时拒绝其他需要独占 Agent 的操作（切换项目/Provider/会话/重载配置等）。
- * 12 处调用点统一使用此工厂，消除 `configError('对话繁忙', ...)` 的重复模板（ADR-017 枝叶层 2 次提取）。
- *
- * @param action 被拒绝的操作描述（如"切换项目"），拼接到"请等待其结束后再"之后
- * @returns MemoraError（config 类别）
- */
+/** 工厂：对话繁忙错误——chat() 进行中拒绝其他需独占 Agent 的操作，统一模板用此工厂 */
 export function chatBusyError(action) {
-    return configError('对话繁忙', `上一轮对话尚未完成，请等待其结束后再${action}`, ['等待上一轮 chat() 的 AsyncGenerator 耗尽（收到 done 事件）']);
+    return configError('对话繁忙', `上一轮对话尚未完成，请等待其结束后再${action}`, [
+        '等待当前对话完成后重试',
+    ]);
 }
-/**
- * 工厂：网络错误
- */
+/** 工厂：网络错误 */
 export function networkError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'network', cause });
 }
-/**
- * 工厂：LLM 错误
- */
+/** 工厂：LLM 错误 */
 export function llmError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'llm', cause });
 }
-/**
- * 工厂：工具错误
- */
+/** 工厂：工具错误 */
 export function toolError(title, detail, suggestions, cause, errorCode) {
     return new MemoraError({ title, detail, suggestions, category: 'tool', cause, errorCode });
 }
-/**
- * 工厂：安全错误（路径越界、黑名单命中、权限不足等）
- */
+/** 工厂：安全错误（路径越界、黑名单命中、权限不足等） */
 export function securityError(title, detail, suggestions, cause) {
     return new MemoraError({ title, detail, suggestions, category: 'security', cause });
 }
+/** 判断是否为 AbortError（用户主动取消或超时中断）——统一基于 err.name === 'AbortError'，
+ *  兼容原生 DOMException / 普通 Error 子类 / toError() 规范化后对象。 */
+export function isAbortError(err) {
+    return err instanceof Error && err.name === 'AbortError';
+}
+/** 判断 AbortSignal 是否为「超时中断」（chat 锁超时 / LLM 无响应超时统一以 TimeoutError reason 标识）。
+ *  与用户取消（abort() 无 reason / AbortError reason）区分——锁超时中断不能谎报成用户取消。 */
+export function isTimeoutAbortSignal(signal) {
+    return (signal?.aborted === true &&
+        signal.reason instanceof DOMException &&
+        signal.reason.name === 'TimeoutError');
+}
 /**
- * 判断错误是否为 AbortError（用户主动取消或超时中断）
+ * 判断**抛出的错误**是否为「超时」（非 abort 路径的载体）。
  *
- * AbortError 可能源于：
- *   - AbortController.abort() 触发的 fetch 取消（DOMException with name='AbortError'）
- *   - 超时机制（setTimeout + abort）触发的 AbortError
- *   - 用户主动取消（停止生成按钮）
+ * 与 `isTimeoutAbortSignal` 是**同一语义的两种载体**（同判 `name === 'TimeoutError'`）：
+ * 前者看 `signal.reason`（signal 被 abort 的路径），本函数看**被抛出的错误对象**——
+ * 典型场景 = `openaiCompatible.parseSseStream` 的 SSE 停摆看门狗（`Promise.race` 竞速闸
+ * reject `DOMException('…','TimeoutError')`），它不经过 abort signal，故被归类为「失败」
+ * 而非「中断」，最终由 `consumeExecutionStream` 的通用 catch 收口。
  *
- * 统一基于 `err.name === 'AbortError'` 判定，兼容：
- *   - 原生 DOMException（modern Node 18+ / 浏览器中 DOMException 是 Error 子类）
- *   - 普通 Error 子类（name 字段被设为 'AbortError'）
- *   - toError() 规范化后的 Error
+ * **用途（否则宿主文案不可达）**：把超时归入 `error.category = 'timeout'`，让宿主
+ * `chatPanel` 的 `friendlyByCategory.timeout`（「对话处理超时，请稍后重试」）真正生效；
+ * 缺该分类时宿主只能回退**原始技术文案**（DOMException message），用户读到的是侦探材料。
  *
- * @param err 未知类型的错误对象
- * @returns 是否为 AbortError
+ * 注：`toError()` 对 Error 实例原样返回（实测 `DOMException instanceof Error === true`），
+ * 故经 `llmCaller` 的 `toError(err)` 再 rethrow 后 `name` 不丢，本判据在链路末端依然成立。
  */
-export function isAbortError(err) {
-    return err instanceof Error && err.name === 'AbortError';
+export function isTimeoutError(err) {
+    return err instanceof Error && err.name === 'TimeoutError';
 }
-// toError 实现位于 ./toError.ts（纯逻辑，零依赖），此处 re-export 保持向后兼容
 //# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,yEAAyE;AACzE,yEAAyE;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAK7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,qBAAqB;IACrB,gBAAgB,EAAE,kBAAkB;IACpC,+BAA+B;IAC/B,cAAc,EAAE,gBAAgB;IAChC,iBAAiB;IACjB,iBAAiB,EAAE,mBAAmB;IACtC,iCAAiC;IACjC,cAAc,EAAE,gBAAgB;IAChC,mBAAmB;IACnB,cAAc,EAAE,gBAAgB;IAChC,+BAA+B;IAC/B,aAAa,EAAE,eAAe;IAC9B,yBAAyB;IACzB,YAAY,EAAE,cAAc;IAC5B,qBAAqB;IACrB,kBAAkB,EAAE,oBAAoB;IACxC,iBAAiB;IACjB,OAAO,EAAE,SAAS;CACV,CAAC;AAIX;;GAEG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAqB;IACxD,aAAa,CAAC,cAAc;IAC5B,aAAa,CAAC,cAAc;IAC5B,aAAa,CAAC,aAAa;IAC3B,aAAa,CAAC,kBAAkB;CACjC,CAAC,CAAC;AAEH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAkBD,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,KAAK,CAAS;IACd,MAAM,CAAqB;IAC3B,WAAW,CAAoB;IAC/B,QAAQ,CAAgB;IACjC,oCAAoC;IAC3B,SAAS,CAAiC;IAC1C,KAAK,CAAoB;IAElC,YAAY,IAA0B;QACpC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,MAA0B,EAC1B,WAAqB,EACrB,KAAa;IAEb,OAAO,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,WAAW,CAChB,MAAM,EACN,qBAAqB,MAAM,EAAE,EAC7B,CAAC,8CAA8C,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAa,EACb,MAA0B,EAC1B,WAAqB,EACrB,KAAa;IAEb,OAAO,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACrF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAa,EACb,MAA0B,EAC1B,WAAqB,EACrB,KAAa;IAEb,OAAO,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,KAAa,EACb,MAA0B,EAC1B,WAAqB,EACrB,KAAa,EACb,SAA8B;IAE9B,OAAO,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,MAA0B,EAC1B,WAAqB,EACrB,KAAa;IAEb,OAAO,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;AAC3D,CAAC;AAED,yDAAyD"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}