OpenWhispr Bedrock 错误处理加固实战可中止请求、AWS 凭证诊断与真实粘贴回退状态【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/GitHub_Trending/op/openwhispr导读本文围绕 OpenWhispr 仓库中的 Bedrock 错误处理评审修复实现计划配套设计文档见 设计规格深入拆解其三大核心改造让 Bedrock 清理请求在重试退避期间可被用户取消、在 AI SDK 边界保留真实 AWS 凭证错误的类型/状态/请求 ID、以及让原稿已粘贴的回退状态只出现在真实粘贴之后。读完本文你将理解 OpenWhispr 如何用 TDD 方式落地这六项评审发现掌握可复用的中止信号传递、错误映射上下文携带和 IPC 显式结果契约等工程模式。一、评审背景与六项待关闭发现该计划源于对提交ddf983fd的一次只读评审目标是关闭六个与 Bedrock 错误处理相关的问题同时严格保持既有的 Bedrock 消息文案、重试次数、AWS 区域行为和回退 toast 层级不变。六项发现分别是取消必须真实生效取消不仅要丢弃渲染进程最终结果还要在主进程中止进行中的 Bedrock 清理请求及其重试退避等待。连接测试需要有界超时Check connection 必须使用一个有上限的应用层超时避免无限挂起。凭证提供器错误不得被吞掉凭证提供器抛出的错误穿过真实 AI SDK 边界时其类型、HTTP 状态、请求 ID、cause以及 managed/manual 上下文都不能丢失。托管 Bedrock 文案必须用解析后的运行时区域托管managed场景下错误提示中的区域应来自实际解析出的运行时配置而非渲染进程里可能过期的配置。粘贴 IPC 必须区分真实粘贴与引导无操作paste-text的隐式成功即已粘贴契约要改为显式的{ success, pasted }结果。安全网络错误白名单需补全ENETDOWN、EHOSTDOWN、UND_ERR_HEADERS_TIMEOUT、UND_ERR_BODY_TIMEOUT应进入安全网络错误集合其中两个 Undici 超时码还必须保留超时分类与文案。设计文档同时列出了十二条绑定需求Binding requirements其中最有约束力的几条包括仅对 503、429、超时与安全网络错误进行最多六次指数退避重试认证、权限、无效模型、配置与用户取消类失败永不自动重试绝不静默切换 AWS 区域分类前必须解包RetryError.lastError503/429/超时的主消息文案必须逐字节保持不变回退状态必须与主 AWS 错误视觉上分离且可展开/可复制。二、任务一可中止的 Bedrock 请求生命周期2.1 接口契约任务一以现有的AgentStreamRequestRegistrysrc/helpers/agentStreamRequestRegistry.js为基础为单次企业推理新建一个专用注册表实例消费begin(senderId, requestId)、complete(...)、cancelSender(senderId)产出runBedrockRequest(operation, { signal, ...retryOptions })其中signal可以在一次尝试之前以及退避等待期间中止产出window.electronAPI.cancelEnterpriseReasoning(): void转发为 IPC 通道enterprise-reasoning-cancel保留processEnterpriseReasoning(...)的结果形状以及所有非 Bedrock 请求路径。从注册表实现可以看到begin会为每个(senderId, requestId)维护一个AbortController同一请求 ID 再次 begin 时先中止旧控制器而cancelSender(senderId)会中止该 sender 下的全部请求并整体删除条目——这正是取消只影响发起请求的渲染进程的底层保障。2.2 让重试循环感知中止信号计划的 Step 13 采用严格的 TDD先加一个会失败的取消测试观察 RED再做最小生产改动。取消测试的核心形状如下源自 test/helpers/bedrockRequestPolicy.test.jsconst controller new AbortController(); let attempts 0; let releaseSleep; const sleeping new Promise((resolve) (releaseSleep resolve)); const request runBedrockRequest( async () { attempts 1; throw awsError({ name: ServiceUnavailableException, status: 503 }); }, { signal: controller.signal, random: () 0.5, sleep: async (_delay, signal) { releaseSleep(); await new Promise((resolve, reject) { signal.addEventListener(abort, () reject(signal.reason), { once: true }); }); }, } ); await sleeping; controller.abort(); await assert.rejects(request, (error) error?.name AbortError); assert.equal(attempts, 1);该测试断言重试遇到 503 后进入退避睡眠时中止控制器会让请求以AbortError拒绝且只发生过 1 次尝试、不再有后续重试。它能抓住的生产缺陷是重试延迟忽略了取消信号。随后生产实现把runBedrockRequest扩展为可选的signal参数在每次操作前throwIfAborted()在 catch 分类前再次检查并把 signal 传入延迟函数async function runBedrockRequest(operation, options {}) { const { signal, sleep sleepWithAbort, ...retryOptions } options; for (let attempt 1; attempt maxAttempts; attempt 1) { signal?.throwIfAborted(); try { return await operation(); } catch (error) { signal?.throwIfAborted(); // existing classification and six-attempt ceiling await sleep(delay, signal); } } }在真实源码 src/helpers/enterpriseProviderErrors.js 中sleepWithAbort的默认实现会在已中止时立即以signal.reason拒绝睡眠期间监听abort事件无论超时正常 resolve 还是被中止 reject都会移除监听器避免监听器泄漏。此外还提供了runAbortableOperation(operation, signal)用Promise.race把操作与中止 Promise 竞争实现尝试进行中也能被中止的能力。2.3 应用层超时与主进程取消注册Step 46 通过扩展 IPC 测试基建捕获ipcMain.on监听器、让 sender 假对象暴露整数id、once、removeListener、isDestroyed加入三组测试连接测试超时用较小的timeoutMs让假的generateText等待options.abortSignal并以该信号的超时原因拒绝断言恰好六次尝试且返回既有的精确超时消息清理请求取消在第一次尝试挂起或退避期间对同一 sender 触发enterprise-reasoning-cancel断言其 signal 被中止且不会发起第二次尝试preload 桥接断言cancelEnterpriseReasoning()会发送enterprise-reasoning-cancel。这些测试分别抓住四类生产缺陷应用超时缺失、主进程取消缺失、跨 sender 取消误伤、以及取消后仍然重试。生产实现见 src/helpers/ipcHandlers.js 中的enterprise-reasoning-cancel监听器为 Bedrock 清理单独实例化AgentStreamRequestRegistry用渲染进程 sender ID 加 UUID 开启请求把 sender 销毁事件挂到cancelSender将请求控制器信号与每次尝试的新鲜超时信号组合传给runBedrockRequest并在finally中只完成该控制器。IPC 取消监听器仅取消发起事件的 sender 的请求从而杜绝跨窗口误取消。ReasoningService.cancelAllRequests()在cancelCloudReason()旁边调用新的取消入口类型声明cancelEnterpriseReasoning?: () void加入 src/types/electron.ts。对于 Check connection每次 Bedrock 尝试都使用全新的有界超时AbortSignal.timeout(config?.timeoutMs || 30_000)同时保留maxRetries: 0与外层六次策略Azure、Vertex 的连接行为完全不变。对应测试可见 test/helpers/bedrockEnterpriseIpc.test.js 中的 Check connection retries timed-out Bedrock attempts with the existing timeout message 与 Bedrock cleanup cancellation aborts only the requesting renderer without retrying。2.4 任务一验证node --import tsx --test test/helpers/bedrockRequestPolicy.test.js \ test/helpers/bedrockEnterpriseIpc.test.js \ test/helpers/preloadAuthBridge.test.js \ test/helpers/audioManagerCancelLifecycle.test.js \ test/services/enterpriseInferenceErrors.test.js全部通过后运行npm run typecheck npm run lint并只提交计划中列出的任务文件提交信息为fix(enterprise): cancel Bedrock cleanup requests。三、任务二保留真实 AWS 凭证错误与解析后的区域3.1 问题本质AI SDK 边界的错误替换任务二针对的是凭证提供器错误在穿过ai-sdk/amazon-bedrock时被替换成普通Error这一事实。若把凭证提供器直接交给 SDKSDK 内部实例化版本会丢失原始的 AWS/Smithy 错误身份与元数据后续错误映射便无从分类。计划的接口契约消费解析后的企业运行时{ provider, model, apiKey, enterprise }产出异步getEnterpriseAIModel(provider, model, apiKey, enterprise): PromiseLanguageModel产出使用已解析的 access key、secret 与可选 session token 构造 Bedrock 模型profile 或托管凭证提供器场景保留手动静态密钥行为与 Azure/Vertex 模型构造语义。在真实源码 src/helpers/enterpriseAiProviders.js 中getEnterpriseAIModel已是异步分发createBedrockModel的实现正是先解析凭证、再构造 SDK 模型async function createBedrockModel(model, enterprise) { const { createAmazonBedrock } require(ai-sdk/amazon-bedrock); const region enterprise?.bedrockRegion || us-east-1; const credentials enterprise?.managedCredentialProvider ? await enterprise.managedCredentialProvider() : enterprise?.bedrockProfile ? await require(aws-sdk/credential-providers).fromNodeProviderChain({ profile: enterprise.bedrockProfile, })() : /* static credentials or null */ null; // 校验解析出的凭证必须包含非空 accessKeyId / secretAccessKey // 否则抛出 name 为 CredentialsProviderError 的错误 return createAmazonBedrock({ region, ...(credentials ? { accessKeyId: credentials.accessKeyId, secretAccessKey: credentials.secretAccessKey, sessionToken: credentials.sessionToken, } : {}), })(model); }这样托管凭证提供器抛出的原始错误在进入 SDK 前就被捕获getEnterpriseAIModel直接以同一个对象身份拒绝name、$metadata.httpStatusCode、$metadata.requestId、cause全部原样保留。手动静态密钥与环境变量回退路径保持不变ipcHandlers.js中的三处调用点都改为await模型创建。3.2 错误映射解包、分类与运行时区域上下文错误映射的核心逻辑位于 src/helpers/enterpriseProviderErrors.js。其分类管线可概括为解包重试错误unwrapRetryError(error)沿lastError链循环解包用Set防环拿到最底层错误后再分类构建错误链bedrockErrorChain沿cause链收集供状态/类型/请求 ID 提取复用归一化异常类型normalizeBedrockExceptionType会去掉 AWS 命名空间前缀#之后与冒号后缀例如com.amazon.identity#InvalidClientTokenId:client归一化为InvalidClientTokenId同时过滤掉Error、AI_APICallError、AI_RetryError等 SDK 包装名多来源提取HTTP 状态可来自status、statusCode、$metadata.httpStatusCode或response.status请求 ID 可来自$metadata.requestId、requestId或大小写不敏感的x-amzn-requestid/x-amz-request-id响应头。mapBedrockError(error, config)的分支覆盖了认证被拒401 /InvalidClientTokenId等签名类错误、权限拒绝403 /AccessDeniedException文案中带上区域、模型不存在ResourceNotFoundException、配置被拒400 /ValidationException、未配置CredentialsProviderError/ConfigError/ region missing等类别每类都带messageKey供渲染进程本地化并通过messageParams: { region }注入解析后的区域。运行时的关键改动每个已解析的运行时resolved runtime被保留在 handler 的try之外catch 时只把真正的bedrockRegion合并进映射上下文。这确保了托管场景下错误文案使用us-west-2这类实际解析区域而不是渲染进程配置里可能已过期的eu-west-1。测试 managed Bedrock failures use the resolved region in actionable copy 正是通过让渲染进程配置一个错误区域、运行时解析出us-west-2来断言文案只含us-west-2。过期令牌的双轨文案mapBedrockError对ExpiredTokenException依据config.managedContext分支——托管访问提示Sign out and sign back in to refresh company access, then retry且不暴露任何 CLI 命令手动 profile 访问保留既有aws sso login --profile profile指引。测试 managed Bedrock credential expiry keeps AWS diagnostics and gives no profile command 同时断言copyCommand undefined且technicalDetails完整保留状态 403、类型ExpiredTokenException、请求 ID 与底层错误消息。3.3 安全网络错误白名单扩充真实源码中的BEDROCK_SAFE_NETWORK_CODES集合已经包含计划要求的全部四个新码const BEDROCK_SAFE_NETWORK_CODES new Set([ EAI_AGAIN, ECONNREFUSED, ECONNRESET, EHOSTDOWN, EHOSTUNREACH, ENETDOWN, ENETUNREACH, ENOTFOUND, EPIPE, ETIMEDOUT, UND_ERR_CONNECT_TIMEOUT, UND_ERR_HEADERS_TIMEOUT, UND_ERR_BODY_TIMEOUT, UND_ERR_SOCKET, ]);isSafeBedrockNetworkError先确认错误链上没有 HTTP 状态避免把带状态的服务端错误误判为网络错误再检查错误码此外还会匹配TypeError且消息含fetch failed/network的链上节点。isBedrockTimeout则把UND_ERR_HEADERS_TIMEOUT、UND_ERR_BODY_TIMEOUT与ETIMEDOUT、UND_ERR_CONNECT_TIMEOUT一起归入超时分类从而命中精确的超时消息文案。测试 test/helpers/bedrockRequestPolicy.test.js 用表驱动方式验证了四类错误码在AI_APICallErrorcause 链上都会触发重试且两个 Undici 超时码映射到精确超时消息、两个主机/网络故障码映射到网络消息。该文件还固化了 503/429/超时三条主消息字符串的逐字节不变性以及六次尝试后延迟序列为[50, 100, 200, 400, 800]初始延迟 500ms、最大 8s、随机因子 0.5 时的指数退避。3.4 任务二验证node --import tsx --test test/helpers/enterpriseAiProviders.test.js \ test/helpers/bedrockRequestPolicy.test.js \ test/helpers/bedrockEnterpriseIpc.test.js \ test/services/enterpriseInferenceErrors.test.js \ test/services/managedEnterpriseRouting.test.js要求全部通过且原有的精确 503/429/超时字符串与 Azure 测试不变随后npm run typecheck npm run lint并提交fix(enterprise): preserve Bedrock credential diagnostics。四、任务三仅在真实粘贴后报告清理回退4.1 隐式成功契约的缺陷此前paste-textIPC 以处理器正常 resolve 即视为粘贴成功但在引导onboarding演示场景下焦点其实在应用自己的 textarea 上粘贴会重复追加同一句话因此主进程把这种场景当作成功的无操作直接返回。渲染进程却可能据此记录清理失败后已粘贴原稿的回退状态向用户展示从未真实发生的信息。任务三的接口契约产出paste-text/window.electronAPI.pasteText(...) Promise{ success: true; pasted: boolean }产出AudioManager.safePaste(...) Promiseboolean仅在pasted true时返回 true保留有意忽略粘贴结果的调用方以及 selection-edit 替换契约。4.2 显式结果实现在 src/helpers/ipcHandlers.js 的paste-text处理器中引导分支直接返回{ success: true, pasted: false }见源码中关于 onboarding demo 的注释只有clipboardManager.pasteText真正 resolve 之后才返回{ success: true, pasted: true }。src/types/electron.ts的声明从Promisevoid更新为结构化结果preload 保持透明转发。渲染进程侧src/helpers/audioManager.js 的safePaste改为要求肯定性结果const result await window.electronAPI.pasteText(text, options); return result?.pasted true;selection-edit 行为与 toast 渲染不做改动。4.3 测试矩阵新建的 test/helpers/ipcPasteOutcome.test.js 直接驱动真实paste-text处理器覆盖四个关键场景引导演示激活时返回{ success: true, pasted: false }且不调用clipboardManager.pasteText正常粘贴成功返回{ success: true, pasted: true }且恰好调用一次剪贴板allowClipboardFallback下仅剪贴板回退{ pasted: false }不算已粘贴剪贴板回退后不得调度 AutoLearn 文本监控textEditMonitor不启动。AudioManager 与 hook 层的测试audioManagerCleanupFallback.test.js、useAudioRecordingCleanupFallback.test.js断言safePaste对{ success: true, pasted: false }返回 false、不记录清理失败且{ success: true, pasted: true }是唯一会记录粘贴后回退的路径。4.4 任务三验证node --import tsx --test test/helpers/ipcPasteOutcome.test.js \ test/helpers/audioManagerCleanupFallback.test.js \ test/helpers/useAudioRecordingCleanupFallback.test.js \ test/helpers/cleanupFailureToast.test.js \ test/helpers/audioManagerCancelLifecycle.test.js要求全部通过引导无操作、禁用自动粘贴、粘贴失败均不得记录回退。随后npm run typecheck npm run lint并提交fix(dictation): report only completed fallback pastes。五、最终验证与验收清单三个任务全部落地后计划要求执行完整验证流水线运行所有聚焦的 Bedrock、企业、取消、粘贴、回退 toast 与托管路由测试npm run typecheck、npm run lint、npm run format:check、npm run build:renderernpm test对比基线失败清单失败时单独重跑受影响的完整文件对abfaf2ba010a7a122a70eb7ec4541324eebaf33d..HEAD范围与完整需求派发一次全新的整分支代码评审。验收时需要回归确认的不可变承诺包括503/429/超时主消息逐字节不变RetryError.lastError、HTTP 状态、AWS 异常类型、AWS 请求 ID 与底层错误保真完整Original dictation pasted without AI cleanup. 仅在清理失败且原稿真实粘贴后出现回退状态永不出现于连接测试、最终清理成功、禁用自动粘贴、失败/无操作粘贴、翻译、Agent 或 selection-edit 失败场景Azure、Vertex、Agent 流式、翻译、selection-edit 与非清理听写行为保持原样。六、工程启示三个可复用模式把本次改造放回 OpenWhispr 整体架构看有三条可独立迁移的工程经验取消要穿透到最内层等待仅丢弃渲染进程侧 Promise 是不够的。主进程用AbortControllerthrowIfAborted 可中止 sleep 的组合把取消信号同时注入尝试与退避等待配合AgentStreamRequestRegistry按(senderId, requestId)精确路由实现了取消只影响发起者、且在退避期间立即生效。错误保真要在 SDK 边界之前完成凡是要把错误映射为用户可行动文案的链路都应先自行解析凭证/配置并捕获原始错误而不是把解析逻辑交给会改写错误对象的第三方 SDK。unwrapRetryErrorbedrockErrorChain加上多来源响应头、$metadata、parsed data提取构成了一套对 AI SDK 包装层透明的诊断基础设施。IPC 结果要用显式状态表达真实语义把Promisevoid式的隐式成功改为{ success, pasted }结构化结果让请求已处理与动作已真实完成两个语义得以区分避免 UI 基于错误前提渲染状态。上述实现均可在仓库中对照阅读重试与错误映射、凭证前置解析的模型工厂、请求注册表、IPC 处理器、粘贴安全封装以及配套回归测试 bedrockRequestPolicy.test.js、bedrockEnterpriseIpc.test.js 与 ipcPasteOutcome.test.js。【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/GitHub_Trending/op/openwhispr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
