[KuramiWan]

Summary

这套设计回答一个问题：一个失败从产生到用户看见，要过六条边界（领域 → Remote 出口 → 子进程 / 运行时插件 → IPC → 渲染层），怎么让它不丢语义，同时让三个读者各读到该读的东西——用户读一句话，开发者读一行日志，程序读一个码。

今天的问题正好相反：失败在第二条边界上就只剩一句话。用户看到开发者写的中文句，程序拿不到码、只能比字符串，日志里没有能回去查的东西。所以这套设计做四件事，外加一个执行者。

一个失败的一生

① 领域抛出        DesktopError(码, 开发者诊断, 参数化详情)
                    │  码与详情从这里开始存在
② Remote 出口      原样过网关：失败自己就是合法载体，不被折成 gateway/internal
③ 子进程 fatal 帧   带码、详情、栈；子进程挂了也有码，不是一句 message
④ 运行时插件出口    同一个出口：一行日志（动作键 + 码 + 文案 + 详情）
⑤ Electron IPC     失败作为对象返回，不跨进程抛（Error 跨进程只剩 message）
⑥ 渲染层           唯一解析点：码 → 用户句；通道 → 就地 or 对话框
                    │  用户读 text，开发者读 diagnostic，程序读 code
                    ▼
              「找不到预设。」+ 可复制的码与详情

一、用户可见文案只有一个来源，而且不在抛出点。
抛出点保留原中文句，但它是开发者诊断——进日志，可以带 id 和路径。用户读的那句话由渲染层按码给：

- throw new Error('找不到这个预设：' + id)                        // 用户会读到这句话
+ throw new DesktopError(ELECKOI_FAILURE_CODES.agentPresetNotFound,
+                       `找不到这个预设：${id}`, { what: '预设' }) // 日志读到这句；用户读「找不到预设。」

好处有三个：同一个失败在聊天窗口和设置面板不会出现两种说法；改文案只改一处；「用户读到开发者诊断」这种事故在结构上不会再发生。这是对仓库「文案就地写中文」惯例的明确例外。

二、码表是内部枚举，不是对外契约。
29 条码 + 一个兜底码，形态 eleckoi/<域>/<原因>：加码自由，改名要一次全局替换；不承诺第三方或 Android 按码实现——实测生产代码里按 eleckoi/* 分支的地方是 0 处，没有消费者就不该有承诺。兜底码的规则是不猜：认不出的失败折成 eleckoi/internal，把原码记进 details.what。猜成某个域码，等于给调用方一个假的可判别失败。

三、严重度是场景的属性，不是失败的属性。
同一个 io/failed，在读一张角色卡时是功能内失败，在启动读配置时是整个应用的失败。所以通道默认由码给（5 条应用级码：plugin/load-failed、db/schema-mismatch、storage/corrupt、sender/untrusted、lifecycle/disposed），调用点只能上调——解析函数的参数里根本没有下调方向，「只能上调」是结构保证。两条通道：inline 就地失败面 + 重试；app 对话框 / 窗口级提示。

四、日志一行读完，不用回查码表。
一行是「动作键 + 码 + 开发者诊断 + 参数化详情 + 时间」：

动作 conversations.delete 失败：[eleckoi/lookup/not-found] 找不到这个会话：abc（what: 会话）

动作键是有语义的操作名，不是随机 id。启动写一行、正常退出写一行——有 start 没 end，就是崩溃或强杀。日志自己写不了就降级 stdout + 一条 stderr，不让日志成为应用起不来的原因。

两条硬约束撑住上面这些：失败按形状识别，不用 instanceof（dsh-product-data 把契约包内联了，跨 bundle 副本原型不同，instanceof 必假，码与详情会整条丢掉）；过边界不重新包信封，客户端拆 Remote 结果时直接 throw result.error，保留官方失败实例。明确不做：冻结公开契约、按失败原因决定恢复策略、给副窗口补 toast、引入 lint / 格式化链、全面 Result 化、运行时错误服务。

闸是这套设计的执行者。 check:error-contract 四条规则：禁止丢码、契约违例必须带 issues、空 catch 必须具名（failureAlreadyPublished / rejectionIsAwaitedElsewhere / bestEffort）、不许裸抛。四条都是绝对值，不建豁免账本；只看代码位置，作者脚本示例里出现的 throw new Error 不会被误判。

这份 diff 里是什么。 373 个文件：55 个是新地基（契约、折叠、闸、失败面组件、日志）；180 个是把裸抛换成带码抛出——同一句式替换，其中 127 个文件只做这一件事；77 个是接线（preload、IPC、窗口失败面、日志挂点），用户可见行为的变化在最后这一桶；43 个是既有测试的断言更新；18 个是闸 / 生成物 / 文档 / 配置。其中 8 个文件不是本线的改动，是并入的上游 PR eleckoi#16（Windows CI 基线修复）：0.2.13 在 windows-latest 上本来就红 7 条，不并它，本 PR 的 Windows CI 看不出错误处理改动的真实结果。想读的话按这个顺序：packages/shared/src/contracts/errors/ → 任选一条边界（ipc.ts + desktopIpcHandler.ts）→ apps/web/src/utils/failureText.js。

Evidence

闸：四条规则从基线收到绝对值。 同一脚本分别跑基线 a5bb881（696 个源文件）与 tip ab4e437（725 个）：

                基线    现在
禁止丢码        38      0
契约违例 issues  0       0
空 catch        71      0
裸抛            1184    0

Windows 真机（并入 eleckoi#16 后，C:\Users\15985\Desktop\code\ElecKoi-eh13，Node 24.20.0 / pnpm 10.32.1）：unit 10 文件 / 84 用例 · ui 174 / 1256 · host 63 / 497 · tooling 9 / 43 · integration 关键 2 文件 27 用例——共 258 文件 / 1907 用例，0 失败；闸测试在真实 CRLF 检出下 8/8。GUI 组（desktop / browser 与应用窗口）在这台机器上起不来：Electron 44 启动即 APPCRASH 0x80000003（最小窗口脚本、交互式计划任务、--no-sandbox 都一样），与本次改动无关，故未纳入。

Windows CI（windows-latest）：tip 3ba241f —— pnpm test 326 文件 / 2260 用例全过；pnpm build（含四条契约规则与全部生成物校验）、Electron SQLite ABI、DSH 握手三步也全过，整条 19m17s。这一轮 CI 抓出并修掉 3 个只在 Windows 出现的问题：闸测试的 CRLF + shebang、契约文档生成器读 details.ts 的正则、码表生成器把 D:\ 裸路径当 ESM 导入。

用户看到的是按码的句子，不是开发者诊断。

• Before: 渲染层 103 处把 error?.message 当文案；主窗口写着 页面加载失败：{error?.message}
• After: 全部走 resolveFailure(...).text。renderer-failure-text-wiring.test.jsx 喂 DesktopError(lookupNotFound, '开发者诊断：找不到 x', { what: '角色卡' })，断言界面显示 找不到角色卡。 且不含「开发者诊断」；裸 Error 仍用它的 message

应用级码真的走应用级通道。

• Before: channel 只被当成 CSS class，storageCorrupt 在设置面板里就地显示成开发者诊断
• After: failure-alert-escalation.test.jsx：storageCorrupt 升级到窗口级对话框，lookup/not-found 仍就地，无订阅者时退回就地兜底

IPC 不再跨进程抛异常。

• Before: ipcMain.handle 的 handler 抛错，跨进程只剩 message
• After: 主进程 9 处 handler 返回结构化失败，preload 11 处解包；ipc-failure.test.ts 断言码与详情原样过结构化克隆

全量门禁（bash eh13-final-gates.sh，合并前 tip ab4e437；并入的 eleckoi#16 提交另由上游 CI 与上面的 Windows 真机验证）

fast               EXIT=0     12 步快闸 + typecheck
test               EXIT=1     326 文件 / 2260 用例 → 2254 通过 · 4 skipped · 2 失败（均为环境红）
electron-dsh       EXIT=0     5 个探针全过
dsh-runtime        EXIT=0     16 bundle / 288 pinned
desktop-build      EXIT=0
dsh-renderer       EXIT=0
built-preload      EXIT=0
native-frame       EXIT=0

两个环境红：android-apk-resources（缺 Pillow，本机 python3 没有 pip）、updater-network（Windows autoUpdater 用例，Linux 平台不匹配——补上 X server 后仍红在同一断言）。

Merge Danger

Door: one-way（对约定）/ two-way（对代码）

合并即把「抛码 + 渲染层出文案」定成基线：规则 4 现在默认判失败，新写的裸抛当场红。代码可以整体 revert，但 revert 会连带撤掉闸、生成的契约文档与 ADR 0040，回退成本高于一般重构。上游 PR 已开：#17（本分支 head 相同）。并进来的 eleckoi#16 是上游已开的那条 Windows CI 修复：本 PR 需要它，Windows CI 才能反映错误处理改动的真实结果；eleckoi#16 合入后这些提交自动变成 no-op。

Blast Radius: repo-wide

• 领域 / 宿主 / 运行时插件 / 客户端 bundle 的抛出形态都变了；依赖 error.message 或 instanceof 的外部代码要改读 .code（仓库内已扫干净）。
• 失败过边界复用 isDSHRemoteError 标记：拿到 IPC 失败对象的 DSH 代码会把它当 RemoteError，这是有意为之；代价与退路写在 packages/shared/src/contracts/errors/ipc.ts 文件头。
• 三个生成物进入「改源要重渲」的约束：客户端码表、docs/error-contract.md、插件 API 参考。
• 已发布的迁移文件被改成带码抛出（行为等价），审阅时值得看一眼。
• 并入 修复 Windows 桌面 CI 基线：Pillow、工具结果鉴权与三处测试环境 eleckoi/ElecKoi#16 的 8 个文件：改的是测试 / CI 配置与工具结果的 Windows 鉴权；与本线改动没有冲突，等 修复 Windows 桌面 CI 基线：Pillow、工具结果鉴权与三处测试环境 eleckoi/ElecKoi#16 上游合并后这些提交是 no-op。
• 剩余未做：25 处功能内失败面仍是 <p role="alert"> 直显（关键窗口先接，组件与接线已就绪）。

请求维护者

这套写法只有在后续改动里被使用才算成立。合入后请按错误处理协作声明写新的失败，要点六条：

1. 抛出带码：DesktopError / productFailure；message 写开发者诊断（日志用），不是给用户看的句子；
2. 不拆失败信封：RemoteResult 走 unwrapOrFail 或 throw result.error，不写 new Error(result.error.message)；
3. 用户可见文案只在渲染层：resolveFailure(...).text；宿主、领域、运行时插件不拼用户句子；
4. 空 catch 必须具名（failureAlreadyPublished / rejectionIsAwaitedElsewhere / bestEffort）或写非空处理体；
5. 新码按 codes.ts → details.ts → 文案表 → 重生成 → 测试的顺序加；生成物不手改；
6. 提交前跑 pnpm check:error-contract：四条规则都是绝对值，不建豁免账本。

哪条做不到或有异议，请在合并前说——合入后这几条由闸执行，不再是建议。

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a1c81800-ca64-4ae1-b0cf-ba4cb16b3bc5

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}