From 9fe692ba874808ce40502df9513dd72932c6c4cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Fri, 2 Oct 2026 02:42:15 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9AAGC=E8=AE=A4?= =?UTF-8?q?=E8=AF=81=E9=94=99=E8=AF=AF=E6=94=B9=E4=B8=BA=E9=A1=B6=E5=B1=82?= =?UTF-8?q?=E7=B1=BB=E5=88=AB=E5=8A=A0=E7=B1=BB=E5=9E=8B=E5=8C=96reason?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 AGC 命令错误结构化 ADR：顶层只放调用方要分流的类别，可枚举细分收进类型化枚举 reason 字段，不再拆成几十个顶层变体、也不用字符串 - 更新 AGC 认证失败 JS 侧载体 ADR：带载荷分支先 as 取具名类型，reason 是枚举时再 switch(payload.reason)，两处 default 都用 expectNever - 同步错误报告技术方案、README 索引、决策记录与踩坑的拍平变体口径 --- docs/README.md | 2 +- ...GC命令错误结构化与错误报告口径-2026-10-01.md | 25 +++++++------ ...GC认证失败的JS侧载体与抛出时机-2026-10-01.md | 36 ++++++++++++------- .../shared-memory/decision-log.md | 6 ++-- docs/project-memory/shared-memory/pitfalls.md | 2 +- ...术方案】AGC错误报告与诊断上传-2026-08-31.md | 2 +- 6 files changed, 45 insertions(+), 28 deletions(-) diff --git a/docs/README.md b/docs/README.md index a62df7401..688cb4663 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,7 +52,7 @@ - [DirectProject 命令接单化实施计划](./technical/【实施计划】DirectProject命令接单化-2026-09-23.md)：四步落地顺序、每步不变式与验收；四步均已落地。 - [DirectProject 命令入队化与待发消息队列归宿主](./adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：命令只负责入队，放行归 Thread Manager；待发消息队列作为运行态事件归宿主、前端只投影；CLI 直连入口与调用身份守卫一并退役。 - [AGC 命令错误结构化与错误报告口径](./adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md)：AGC 命令失败按具体变体建模并用 ts-rs 导出，前端按变体分流、不匹配文案；报告池只收没人处理的错误。 -- [AGC 认证失败的 JS 侧载体与抛出时机](./adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)：认证命令统一经 `invokeClientAuth` 把拒绝装进 `ClientAuthErrorWrapper`（`error` 字段就是 ts-rs 生成的 `ClientAuthError` 判别联合），不新增手写错误类；判定只写在 catch 子句里，无字段变体用固定文案、带载荷分支先 `as` 取自己的具名载荷类型，系统变体原样抛出经 `unhandledrejection` 入池，`default: expectNever` 编译期挡住漏接变体。 +- [AGC 认证失败的 JS 侧载体与抛出时机](./adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)：认证命令统一经 `invokeClientAuth` 把拒绝装进 `ClientAuthErrorWrapper`（`error` 字段就是 ts-rs 生成的 `ClientAuthError` 判别联合），不新增手写错误类；判定只写在 catch 子句里，无字段变体用固定文案、带载荷分支先 `as` 取自己的具名载荷类型（可枚举细分再 `switch (payload.reason)` 在类型化枚举上分流），系统变体原样抛出经 `unhandledrejection` 入池，`default: expectNever` 编译期挡住漏接变体。 - [DirectProject 命令入队化与待发消息队列归宿主实施计划](./technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：五步落地顺序、每步不变式与验收；待实施。 - [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。 diff --git a/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md b/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md index 718d0e9cd..a6de13786 100644 --- a/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md +++ b/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md @@ -33,16 +33,21 @@ DirectProject 已经解决过同一类问题（[`【ADR】DirectProject命令接 - Rust 侧定义具体变体枚举（auth 首个落地：`ClientAuthError`），`#[derive(Serialize, TS)]` + `#[serde(tag = "type", rename_all = "camelCase")]`，用 ts-rs 导出到 `apps/ai-game-creator-shell/src/services/generated/`；生成物不手改。 -- **变体拍平在同一层，不嵌套子枚举**：可枚举的事实各自成一个变体，只有类型本身说不出来的事实才进载荷 - （服务端原文、HTTP 状态码、本机 IO 明细）。internally tagged 下无字段变体就是 `{ type: 'x' }`；带 - 载荷变体是 `{ type: 'x', ... }`，ts-rs 为它生成 `{ type: 'x' } & X` 与 `generated/X.ts`。例如服务地址 - 校验的 7 种失败各自成一个无字段变体，前端只按 `type` 选提示。 -- 前端 `switch (error.type)` 必须列全变体：无字段变体直接取本 catch 的固定文案；带载荷变体先 `as` - 取自己的具名载荷类型，再读它自己的字段（等价于 Java 的 `catch (X e)`）。`default` 用 `expectNever` - 让漏接变体变成**编译错误**。**不假设所有变体都有同一个字段**，也不做任何文案匹配。 -- Rust **不预拼用户可见文案**：载荷只装原始事实（服务端 400 的原文 `serverMessage`、HTTP 状态码、 - 本机 IO 的 `detail`），服务端没给原文就是 `None`；前缀与句式由前端调用方在自己的 catch 分支按当前 - 操作拼接。 +- **顶层只放调用方要分流的类别，可枚举的细分原因收进类型化 `reason` 字段**——既不拆成几十个顶层变体， + 也不用字符串。`reason` 自己也是 `#[derive(Serialize, TS)]` 的枚举。internally tagged 下无字段变体是 + `{ type: 'x' }`；newtype 变体是 `{ type: 'x' } & X`，ts-rs 为它生成 `generated/X.ts`。例如服务地址 + 校验是 `serverAddressRejected` + `ServerAddressReason`（`emptyOrTooLong` / `notAUrl` / `hasCredentials` / + `hasPathOrQueryOrFragment` / `notHttps` / `unsupportedScheme` / `outsideChannel`），网络失败是 + `authNetworkFailure` + `AuthNetworkReason`（`timeout` / `unreachable`），响应契约破损是 + `authResponseInvalid` + `AuthResponseInvalidReason`（`notJson` / `invalidBody` / `missingRefreshCookie` / + `missingUserIdentity` / `serverRejected`），而不是拆成 7 + 2 + 5 个顶层变体。 +- 前端 `switch (error.type)` 必须列全顶层变体：无字段变体直接取本 catch 的固定文案；带载荷变体先 `as` + 取自己的具名载荷类型，可枚举的细分再 `switch (payload.reason)` 在**类型化**的 `reason` 上分流（等价于 + Java 的嵌套 `switch`，仍不碰文案）。顶层与 `reason` 的 `default` 都用 `expectNever`，漏接变体或漏接 + `reason` 都是**编译错误**。**不假设所有变体都有同一个字段**，也不做任何文案匹配。 +- Rust **不预拼用户可见文案**：载荷只装原始事实（类型化的 `reason`、服务端 400 的原文 `serverMessage`、 + HTTP 状态码、本机 IO 的 `detail`），服务端没给原文就是 `None`；前缀与句式由前端调用方在自己的 catch + 分支按当前操作拼接。 - `#[tauri::command]` 的 `Err` 直接携带该枚举（Tauri 2 的 `InvokeError(pub serde_json::Value)` 支持结构化错误）。 这是 DirectProject 已有的做法（`enqueue_direct_codex_turn -> Result<(), DirectTurnEnqueueFailure>`），不是新约定。 - 变体按**可判定的事实**命名。服务端 400 只提供 `status + message`（`AppError.code` 仍是通用 diff --git a/docs/adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md b/docs/adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md index 2cacb44db..273ddb3a6 100644 --- a/docs/adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md +++ b/docs/adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md @@ -34,8 +34,10 @@ ts-rs 已经把 `ClientAuthError` 生成成判别联合（`src/services/generate 时的显式入参决定；catch 里 `error.error as ClientAuthError` 直接分流。 - 只有带载荷的变体才有具名载荷类型：无字段变体在 ts-rs 里就是 `{ type: 'x' }`，不生成文件； - 有字段的变体才生成 `X.ts`。这些具名类型是 §3 每个带载荷 `case` 里 `as X` 的目标，也正是 - "不要假设所有变体字段相同"的落点——没有字段可读的变体不需要、也不允许硬造一个空载荷类型。 + 有字段的变体才生成 `X.ts`（可枚举的细分 `reason` 字段自己也是生成的枚举，如 + `ServerAddressReason.ts` / `AuthNetworkReason.ts` / `AuthResponseInvalidReason.ts`）。这些具名类型是 §3 + 每个带载荷 `case` 里 `as X` 的目标，也正是"不要假设所有变体字段相同"的落点——没有字段可读的变体 + 不需要、也不允许硬造一个空载荷类型。 ### 2. 一个包装函数：`invokeClientAuth` @@ -82,23 +84,33 @@ catch (error) { break; } // ... 每个业务 / 会话变体一个分支 - case 'authNetworkTimeout': - case 'authNetworkUnreachable': - // ... 系统变体逐个列出后原样抛出 + case 'authNetworkFailure': { + const payload = failure as AuthNetworkFailure; + // 可枚举的细分在类型化 reason 上再分流，仍然不碰文案。 + switch (payload.reason) { + case 'timeout': + case 'unreachable': + break; + default: + expectNever(payload.reason); + } throw error; + } + // ... 其余系统变体逐个列出后原样抛出 default: expectNever(failure); } } ``` -- **每个带载荷的业务 / 会话 `case` 用 `as` 取自己的具名载荷类型**，再读它自己的字段；无字段的 - `case` 直接用本 catch 的固定文案。不写跨变体的通用读取，也不让 Rust 预拼上下文。前缀取自 - 当前 catch 的操作语义（登录、发码、启动检查各自可以不同），等价于 Java 的 `catch (PasswordLoginRejected e)`。 - 系统变体不读载荷（调用方只负责原样抛出），但变体名必须逐个列出，`default` 的 `expectNever` 才成立。 -- 业务 / 会话变体：Rust 只给可判定事实（无字段变体连字段都没有；带载荷变体给 `serverMessage` / - `status` / `detail`），调用方在自己的 catch 里补上本次操作的上下文前缀（例如「服务器地址非法: - 远程地址必须使用 https」、「登录失败: 密码长度需要在 6 到 128 位之间」）。 +- **每个带载荷的业务 / 会话 `case` 用 `as` 取自己的具名载荷类型**，再读它自己的字段；字段是可枚举的 + 细分 `reason` 时，再 `switch (payload.reason)` 在类型化枚举上分流。无字段的 `case` 直接用本 catch 的 + 固定文案。不写跨变体的通用读取，也不让 Rust 预拼上下文。前缀取自当前 catch 的操作语义（登录、发码、 + 启动检查各自可以不同），等价于 Java 的 `catch (PasswordLoginRejected e)`。系统变体不读载荷（调用方 + 只负责原样抛出），但变体名必须逐个列出，`default` 的 `expectNever` 才成立。 +- 业务 / 会话变体：Rust 只给可判定事实（无字段变体连字段都没有；带载荷变体给类型化 `reason` / + `serverMessage` / `status` / `detail`），调用方在自己的 catch 里补上本次操作的上下文前缀（例如 + 「服务器地址非法: 远程地址必须使用 https」、「登录失败: 密码长度需要在 6 到 128 位之间」）。 - 系统变体：调用方处理不了，**原样 `throw`**。`onSubmit` / `onClick` 这类 `void` 掉的 handler 抛出的拒绝最终以 `unhandledrejection` 结算，由全局 handler 交给错误池。 - `default: expectNever(failure)`（`expectNever(value: never)`）让"Rust 加了变体而这里 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index a0cfb2889..308b6512c 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -2,14 +2,14 @@ ## 2026-10-01 AGC 命令错误结构化与错误报告口径 -- 决策：AGC 命令失败按**具体变体**建模（Rust `#[derive(Serialize, TS)]` 枚举 + `#[serde(tag = "type", rename_all = "camelCase")]` + ts-rs 导出，生成物不手改），`#[tauri::command]` 的 `Err` 直接携带结构化枚举；前端只按 `type` 分流，**任何地方都不对错误文案做判断**。做法沿用 DirectProject 既有约定（`enqueue_direct_codex_turn -> Result<(), DirectTurnEnqueueFailure>`），不是新机制。 +- 决策：AGC 命令失败按**具体变体**建模（Rust `#[derive(Serialize, TS)]` 枚举 + `#[serde(tag = "type", rename_all = "camelCase")]` + ts-rs 导出，生成物不手改），`#[tauri::command]` 的 `Err` 直接携带结构化枚举；前端先按 `type` 选类别、可枚举细分再按类型化 `reason` 分流，**任何地方都不对错误文案做判断**。做法沿用 DirectProject 既有约定（`enqueue_direct_codex_turn -> Result<(), DirectTurnEnqueueFailure>`），不是新机制。 - 决策：错误报告池只收**没有任何调用方处理**的错误。预期业务拒绝（用户输入 / 前置条件 / 预期 4xx）由调用方消化并给反馈，永不进池；真故障由调用方带上下文交给错误池（`ClientAuthErrorWrapper` 承载 `source/action/page`，`captureClientError` 用 `instanceof` 解包），`window.onerror` / `unhandledrejection` 只兜底没人接手的错误；408/5xx/网络的判定由调用方在 catch 里做（4xx 一律不报）；Rust agent 终态失败仍由失败投影入池。删除 WebView 侧 `shouldCaptureClientError`。 - 边界：变体按**可判定的事实**命名——服务端 400 只给 `status + message`（`AppError.code` 仍是通用 `BAD_REQUEST`），所以 400 变体按"哪条请求的输入被拒"命名（如 `passwordLoginRejected`），不假装能区分密码长度/手机号格式。报告面板默认全选、只由通知打开的既有承诺不变。`captureAgentRuntimeError`、`ResourceReferenceInput` 偏好写盘、`invokeDiagnostic` 三处显式采集点保持原行为，按同一口径改造或删除留在后续变更。 - 影响范围：`apps/ai-game-creator-shell/src-tauri/src/{auth_error.rs,auth_session.rs}`、`apps/ai-game-creator-shell/src/services/{clientAuthErrorWrapper.ts,errorReporting.ts,clientAuth.ts}`、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`、`apps/ai-game-creator-shell/src/services/generated/`（ts-rs 生成：`ClientAuthError.ts` + 有字段变体的载荷文件）。 -- 决策（补充）：TS 形状**只有带载荷的变体才有具名载荷类型**——无字段变体在 ts-rs 里就是 `{ type: 'x' }`，有字段的变体是 newtype 变体持有同名 `#[ts(export)]` 结构体，生成 `{ type: 'x' } & X` 与 `src/services/generated/X.ts`；前端 `switch (error.type)` 的无字段分支用固定文案，带载荷分支先 `as X` 再读它自己的字段。不允许在前端手写这层类型，也不再包派生分类 / 提示文案函数（`clientAuthErrorKind`、`clientAuthErrorNotice`、`resolveClientAuthFailure` 已删除）。 +- 决策（补充）：TS 形状**只有带载荷的变体才有具名载荷类型**——无字段变体在 ts-rs 里就是 `{ type: 'x' }`，有字段的变体是 newtype 变体持有同名 `#[ts(export)]` 结构体，生成 `{ type: 'x' } & X` 与 `src/services/generated/X.ts`；可枚举的细分原因是类型化枚举字段（`ServerAddressReason` / `AuthNetworkReason` / `AuthResponseInvalidReason`），不是字符串、也不各拆一个顶层变体。前端 `switch (error.type)` 的无字段分支用固定文案，带载荷分支先 `as X` 再读它自己的字段，`reason` 是枚举时再 `switch (payload.reason)`（`default` 同样用 `expectNever`）。不允许在前端手写这层类型，也不再包派生分类 / 提示文案函数（`clientAuthErrorKind`、`clientAuthErrorNotice`、`resolveClientAuthFailure` 已删除）。 - 验证：见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md) 的验收清单；关键判据是"登录 400/401 业务变体不产生 `report_client_error`、不弹「发现问题」"。 - 决策（2026-10-01，JS 侧载体与抛出时机）：认证命令统一经 `invokeClientAuth(command, args)` 调用；拒绝值原样装进已有的 `ClientAuthErrorWrapper`（载体只有一个 `ClientAuthError` 类型的 `error` 字段，值就是 ts-rs 生成的判别联合；不读变体字段、不塞 `context`、`Error.message` 留空），**不新增手写错误类**（`ClientAuthFailure` 已删除），形状完全信任 tauri + ts-rs 映射、不做运行时嗅探。形状读取 / 文案回落 / 提示分类三层（`isClientAuthError`、`getClientAuthErrorMessage`、`presentAuthFailure`）全部删除。 -- 决策（2026-10-01，判定位置与出口）：要不要上报只由 catch 子句里的 `switch (failure.type)` 判，`failure = error.error`；无字段业务 / 会话变体用本 catch 的固定文案，带载荷变体先 `as` 取自己的具名类型、再用它自己的 `serverMessage` / `status` / `detail` 拼上本次操作的上下文前缀；Rust 不预拼用户可见文案、服务端原文缺失就是 `null`（无兜底文案）。系统变体原样 `throw` 经全局 `unhandledrejection` 入池（`captureClientError` 用 `instanceof` 解包 `error` 字段取原始错误），`default: expectNever(failure)` 让漏接变体编译失败。取代"未识别变体上调是故意的"。 +- 决策（2026-10-01，判定位置与出口）：要不要上报只由 catch 子句里的 `switch (failure.type)` 判，`failure = error.error`；无字段业务 / 会话变体用本 catch 的固定文案，带载荷变体先 `as` 取自己的具名类型、再用它自己的 `reason` / `serverMessage` / `status` / `detail` 拼上本次操作的上下文前缀（`reason` 是枚举时再 `switch (payload.reason)`）；Rust 不预拼用户可见文案、服务端原文缺失就是 `null`（无兜底文案）。系统变体原样 `throw` 经全局 `unhandledrejection` 入池（`captureClientError` 用 `instanceof` 解包 `error` 字段取原始错误），`default: expectNever(failure)` 让漏接变体编译失败。取代"未识别变体上调是故意的"。 - 决策（2026-10-01，Rust 侧不再降级）：`refresh_session_inner` 的非权威失败直接 `Err(ClientAuthError)`，`ClientAuthStateView` / `ClientAuthRefreshView` 删除 `errorMessage`，续期结果删除 `failed`；`ClientAuthState` 收敛为 `authenticated | unauthenticated`，`ClientAuthRefreshResult` 收敛为 `refreshed | unauthenticated | stale`。 - 影响范围（2026-10-01 第二轮）：`apps/ai-game-creator-shell/src/services/{clientAuth.ts,platformSession.ts}`（`clientAuthError.ts` 删除）、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`、`apps/ai-game-creator-shell/src-tauri/src/auth_session.rs`、对应 vitest 用例。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 8e6521e58..558560d9f 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -8,7 +8,7 @@ - **原因**：① 登录已下沉 Rust，`login_client_with_password` 等命令失败返回 `Err(String)`，Tauri 以**裸字符串**拒绝 `invoke`，前端拿不到任何类型信息；② `shouldCaptureClientError` 对非 object 值走默认 `return true`，`handleLoginSubmit` 的 catch 把预期业务拒绝报进了错误池。技术方案里"预期 4xx 登录/鉴权失败不进池"的口径早就成立，是错误通道的实现方式违背了它。 - **处理（现行口径）**：命令错误一律按具体变体结构化（`Result<_, ClientAuthError>` + ts-rs 导出），认证命令统一经 `invokeClientAuth` 调用：结构化拒绝原样装进已有的 `ClientAuthErrorWrapper`（只有一个 `error` 字段，值是判别联合），UI 在 catch 里按具体变体分流——认得的业务 / 会话变体只给用户反馈，系统变体原样 `throw` 经 `unhandledrejection` 入池，非结构化拒绝原样抛出；删除 `shouldCaptureClientError`。详见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md) 与 [`【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01`](../../adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)。 - **判据/取证**：`npx vitest run apps/ai-game-creator-shell/tests/authFailureReporting.test.tsx`——登录返回结构化业务变体时 `report_client_error` 不被调用；系统变体只上报一次（`source` 取全局 `unhandledrejection` handler 的显式入参；载体不再携带 `action`）。Rust 侧 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml auth_error` 钉住变体 `type` 与 400/401/429/5xx/网络映射。 -- **形状约定**：`ClientAuthError` 的变体拍平不嵌套——无字段变体在 TS 里就是 `{ type: 'x' }`；带载荷变体是 `{ type: 'x' } & X`，`X` 由 ts-rs 导出到 `src/services/generated/X.ts`（Rust 侧是 newtype 变体持有同名结构体）。**不要手写这些类型**，也不要在前端再加一层分类 / 提示文案派生函数——判别一律写在 catch 子句里：`const failure = error.error; switch (failure.type)`，无字段 `case` 用本 catch 的固定文案，带载荷 `case` 先 `as X` 再读自己的 `serverMessage` / `status` / `detail`，`default: expectNever(failure)` 保证漏接变体编译失败。改形状只能改 Rust 再跑 `cargo test` 重新导出，生成物随后交给 prettier；ts-rs 只写文件、不删文件，变体从有载荷改成无字段时要手动清掉孤立的 `X.ts`。 +- **形状约定**：`ClientAuthError` 顶层只放调用方要分流的类别，可枚举细分收进类型化枚举 `reason` 字段——无字段变体在 TS 里就是 `{ type: 'x' }`；带载荷变体是 `{ type: 'x' } & X`，`X` 由 ts-rs 导出到 `src/services/generated/X.ts`（Rust 侧是 newtype 变体持有同名结构体），细分原因枚举（`ServerAddressReason` / `AuthNetworkReason` / `AuthResponseInvalidReason`）同样由 ts-rs 生成。**不要手写这些类型**，也不要在前端再加一层分类 / 提示文案派生函数——判别一律写在 catch 子句里：`const failure = error.error; switch (failure.type)`，无字段 `case` 用本 catch 的固定文案，带载荷 `case` 先 `as X` 再读自己的字段，`reason` 是枚举时再 `switch (payload.reason)`，两处 `default` 都用 `expectNever` 保证漏接编译失败。改形状只能改 Rust 再跑 `cargo test` 重新导出，生成物随后交给 prettier；ts-rs 只写文件、不删文件，变体从有载荷改成无字段时要手动清掉孤立的 `X.ts`（本次 `AuthResponseServerRejected.ts` 就是这样删的）。 - **Rust 侧不得把结构化错误降级成字符串**：`refresh_session_inner` 的非权威失败直接返回 `Err(ClientAuthError)`，视图不带 `errorMessage`；一旦折成 `String`，前端就只能拿文案判断，变体信息永久丢失。 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/auth_session.rs`、`apps/ai-game-creator-shell/src/services/{clientAuth.ts,errorReporting.ts,platformSession.ts}`、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`。 diff --git a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md index c3995cf25..2930da8e5 100644 --- a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md +++ b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md @@ -11,7 +11,7 @@ AI Game Creator Shell 采用 IDEA 风格的当前进程错误报告：错误事 - 报告池只收**没有任何调用方处理**的错误：React render error、`window.onerror`、`unhandledrejection`，以及调用方判定为真故障后带上下文交给错误池（`ClientAuthErrorWrapper`）的错误。Agent Runtime 的终态失败、预算耗尽和启动确认失败由 Rust 失败投影统一入池；Direct Codex 与专业 Agent 的前台裸 Tauri invoke catch 作为补充入口，重复事件由同一 fingerprint 合并，主动取消和“同一 turn 已在运行”不作为错误采集。分层口径见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md) 与 [`【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01`](../adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)。 - 事件字段包括 eventId、fingerprint、source、message、stack、时间和次数；重复事件合并。不再携带 severity、errorCode、page、action、requestId 等无法稳定关联的字段。 - 指纹计算可使用调用方的 page/action 及脱敏后的首个调用点作为进程内区分输入，但这些上下文不会作为事件字段上传；消息与 stack 在入池前统一脱敏，WebCrypto 失败时降级为稳定可读指纹，采集本身不得产生新的未处理拒绝。 -- 命令失败按具体变体建模（Rust 枚举 + ts-rs 导出的 `type` 判别联合；变体拍平不嵌套，无字段变体生成 `{ type }`，带载荷变体生成 `{ type } & 载荷类型`），前端按变体分流，**任何地方都不对错误文案做判断**：认得的业务变体（用户输入 / 前置条件 / 预期 4xx）由调用方消化并给用户反馈，永不进池；系统变体、未识别变体和结构化之外的拒绝原样抛出，走上面的兜底入口。认证命令的封装形态：`invokeClientAuth` 只是薄包装，把结构化拒绝原样装进**已有**的 `ClientAuthErrorWrapper`（载体只有一个 `ClientAuthError` 类型的 `error` 字段，值就是 ts-rs 生成的判别联合；不读变体字段、不塞 `context`、`Error.message` 留空），不新增手写错误类；判定只写在 catch 子句里，无字段变体用本 catch 的固定文案，带载荷变体先 `as` 取自己的具名载荷类型、再用它自己的 `serverMessage` / `status` / `detail` 拼上本次操作的上下文前缀，`default` 用 `expectNever` 在编译期挡住漏接变体。 +- 命令失败按具体变体建模（Rust 枚举 + ts-rs 导出的 `type` 判别联合；顶层只放调用方要分流的类别，可枚举细分收进类型化枚举 `reason` 字段，无字段变体生成 `{ type }`，带载荷变体生成 `{ type } & 载荷类型`），前端按变体分流，**任何地方都不对错误文案做判断**：认得的业务变体（用户输入 / 前置条件 / 预期 4xx）由调用方消化并给用户反馈，永不进池；系统变体、未识别变体和结构化之外的拒绝原样抛出，走上面的兜底入口。认证命令的封装形态：`invokeClientAuth` 只是薄包装，把结构化拒绝原样装进**已有**的 `ClientAuthErrorWrapper`（载体只有一个 `ClientAuthError` 类型的 `error` 字段，值就是 ts-rs 生成的判别联合；不读变体字段、不塞 `context`、`Error.message` 留空），不新增手写错误类；判定只写在 catch 子句里，无字段变体用本 catch 的固定文案，带载荷变体先 `as` 取自己的具名载荷类型（`reason` 是枚举时再 `switch (payload.reason)`）、再用它自己的字段拼上本次操作的上下文前缀，`default` 用 `expectNever` 在编译期挡住漏接变体。 - 客户端 API 自动采集只覆盖网络错误、408 和 5xx（`clientApi` 作为 `fetch` 的调用方在抛出前判定）；预期的 4xx 登录/鉴权失败不进入错误报告池。 - Rust 侧通过 `app_log!` 将普通文本日志同时输出到 stderr 和 AppData `diagnostics/application.log`，超出 256 KiB 滚动到 `application.previous.log`；WebView 的 console 输出通过 `append_application_log` 镜像到同一 raw log，并在客户端桥接处再次脱敏；`read_diagnostic_logs` 只读取应用级日志。 - 这里有两套互不相干的东西，不要互相代入：**错误报告事件池**是进程内 `error_report` 的结构化事件（本次变更不动它，仍然只在内存里、提交时才生成 `events.jsonl`）；**统一 Agent Runtime 错误事件**是项目内 sidecar `.agent/runtime/errors/.json`，既不进事件池也不进报告包。因为报告包里的日志附件只有 AppData 应用日志，所以 sidecar 的同一份已脱敏诊断再作为**日志行**（不是报告事件）投影成两行：`agent.runtime.error`（身份行：eventId / source / stage / code / retryable / clientTurnId / elapsedMs / detailRef，全部是程序生成或调用方常量）与 `agent.runtime.error.detail`（详情行：hint / summary / detail / metadata，自由文本只出现在这里）。两行都由 `agent/runtime_error.rs` 从同一份 diagnosis 生成，不新增字段来源；落到日志前 summary 按 320 字符、detail / metadata 按（1200 / 200 字符）预算脱敏截断（summary 由调用方给，`direct_tool_bridge` 会传工具错误原文，而 `app_log!` 同时把整行写 stderr，那里没有 `sanitize_diagnostic_message` 兜底）。`sanitize_diagnostic_message` 命中凭据标记时替换的是**整行**，自由文本因此只放详情行：详情行被吃掉也不影响身份行定位事件。