文档先行：AGC 命令错误结构化与错误报告口径
- 新增 ADR：命令错误按具体变体结构化（ts-rs 导出）、报告池只收没人处理的错误、前端按 type 分流不匹配文案 - 更新【技术方案】AGC错误报告与诊断上传：采集口径改为"只收没有调用方处理的错误"，补命令变体分流与 clientApi 边界 - 更新共享记忆 decision-log：记录本次口径与影响范围 - 更新共享记忆 pitfalls：记录"输错密码被当成客户端缺陷上报"的现象、根因与判据 - 修正 DirectTurnError 模块注释中"命令边界只给字符串"的过期描述，改为结构化拒单载荷 - docs/README.md 登记新 ADR
This commit is contained in:
@@ -51,6 +51,7 @@
|
||||
- [DirectProject 命令接单化](./adr/【ADR】DirectProject命令接单化-2026-09-23.md)：命令只负责接单、事件流回答整轮结果；拒单前置、失败后置。
|
||||
- [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 导出，前端按变体分流、不匹配文案；报告池只收没人处理的错误。
|
||||
- [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 拆分、命名、启用和启动时注入边界。
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
# 【ADR】AGC 命令错误结构化与错误报告口径
|
||||
|
||||
状态：已接受（2026-10-01 落地，实施顺序见同日的决策记录与
|
||||
[`【技术方案】AGC错误报告与诊断上传-2026-08-31`](../technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md)）
|
||||
|
||||
## 背景
|
||||
|
||||
用户在登录页把密码输错一次，报告面板就出现两条"错误事件"并弹出「发现问题」：
|
||||
|
||||
```text
|
||||
登录失败：密码长度需要在 6 到 128 位之间 — auth · 1 次
|
||||
手机号或密码错误 — auth · 1 次
|
||||
```
|
||||
|
||||
根因不是文案，而是两件事叠加：
|
||||
|
||||
1. 登录已经下沉到 Rust（`login_client_with_password` 等命令），命令失败以 `Err(String)` 返回；
|
||||
Tauri 把 `String` 原样交给 JS，`invoke` 以**裸字符串**拒绝，前端拿到的东西没有任何类型信息。
|
||||
2. WebView 侧的 `shouldCaptureClientError` 对"非 object"值走默认 `return true`，于是
|
||||
`handleLoginSubmit` 的 catch 把"用户输错密码"当成缺陷事件报进了错误池。
|
||||
|
||||
这与 [`【技术方案】AGC错误报告与诊断上传-2026-08-31`](../technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md)
|
||||
已写明的"预期的 4xx 登录/鉴权失败不进入错误报告池"直接冲突——口径早就定了，是错误通道的实现方式违背了它。
|
||||
|
||||
DirectProject 已经解决过同一类问题（[`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md) §4）：
|
||||
命令返回结构化 typed error，前端按变体分流，"认不得的变体或非结构化错误"原样抛出走上报链路。
|
||||
本 ADR 把这套口径推广成 AGC 命令错误的通用约定，并同时收窄错误报告池的入口。
|
||||
|
||||
## 决策
|
||||
|
||||
### 1. 命令错误按具体变体建模，不按文案匹配
|
||||
|
||||
- Rust 侧定义具体变体枚举（auth 首个落地：`ClientAuthError`），`#[derive(Serialize, TS)]` +
|
||||
`#[serde(tag = "type", rename_all = "camelCase")]`，用 ts-rs 导出到
|
||||
`apps/ai-game-creator-shell/src/services/generated/`；生成物不手改。
|
||||
- `#[tauri::command]` 的 `Err` 直接携带该枚举（Tauri 2 的 `InvokeError(pub serde_json::Value)` 支持结构化错误）。
|
||||
这是 DirectProject 已有的做法（`enqueue_direct_codex_turn -> Result<(), DirectTurnEnqueueFailure>`），不是新约定。
|
||||
- 变体按**可判定的事实**命名。服务端 400 只提供 `status + message`（`AppError.code` 仍是通用
|
||||
`BAD_REQUEST`），所以 400 变体按"哪条请求的输入被拒"命名（如 `passwordEntryInputRejected`），
|
||||
不假装能区分密码长度/手机号格式；**任何地方都不允许对错误文案做判断**。
|
||||
- 每个变体带一份可展示 `message`，文案仍只在 Rust 生成一次；前端不拼文案。
|
||||
|
||||
### 2. 报告池只收"没有任何调用方处理"的错误
|
||||
|
||||
谁抛出、谁判定。分层规则：
|
||||
|
||||
- **预期业务拒绝**（用户输入、前置条件、预期 4xx）：由调用方消化并给用户反馈，**永不进池**。
|
||||
- **真故障**（网络不可达、5xx、写盘/运行时安装失败、agent 终态失败）：由调用方带上文重抛，
|
||||
经 `window.onerror` / `unhandledrejection` 入池；Rust 侧 agent 终态失败仍由失败投影入池。
|
||||
- **WebView 全局 handler 是兜底**：任何没人 catch 的错误都进池。
|
||||
- **API 客户端（`clientApi`）在抛出前判定 408/5xx/网络为缺陷**：它是 `fetch` 的调用方，
|
||||
这一判定就发生在它这一层；4xx 一律不报，交给上层调用方。这条边界保持现状，不放宽也不收紧。
|
||||
|
||||
### 3. 前端按变体分流，认不出就抛
|
||||
|
||||
- `isClientAuthError` 只做形状读取（`type` 是稳定判别键），`clientAuthErrorNotice` 用
|
||||
`switch (error.type)` 给出可展示文案；`default → null` 表示"认不出"。
|
||||
- 认不出、系统类、非结构化拒绝 → `throw new ClientActionError(message, context, cause)`；
|
||||
`ClientActionError` 只承载 `source/action/page` 上下文与 `cause`，由全局 handler 用
|
||||
`instanceof` 解包后入池（指纹/展示字段与今天一致）。
|
||||
- 删除 `shouldCaptureClientError`：不再存在"叶子自己判定要不要报"的口径。
|
||||
|
||||
### 4. 报告面板与通知行为不变
|
||||
|
||||
默认选中快照中的全部事件、只由通知中的「查看并报告」打开、poisoned 快照用 fallback 等承诺保持不变；
|
||||
本次只保证"不该进池的东西不再进池"。
|
||||
|
||||
## 后果与边界
|
||||
|
||||
- auth 三命令（`login_client_with_password`、`login_client_with_phone_code`、`send_client_phone_login_code`）
|
||||
及其共用链路（`request_auth` / `map_auth_failure` / `response_data` / `network_error_message`）全量改为
|
||||
`Result<_, ClientAuthError>`；`read_client_auth_state`、`refresh_client_auth_session`、
|
||||
`logout_client_session` 的失败面同步结构化（会话 401/403 仍是"未登录"路径，不是错误）。
|
||||
- 未识别变体上调是**故意**的：Rust 与 TS 同包发布，"认不出"意味着有人加了变体忘了接界面，属于缺陷。
|
||||
- 仍保留的显式采集点（`captureAgentRuntimeError`、`ResourceReferenceInput` 偏好写盘、`invokeDiagnostic`）
|
||||
在后续变更里按同一口径重抛/删除，本 ADR 不改它们的行为。
|
||||
|
||||
## 验收
|
||||
|
||||
```text
|
||||
npm run ai-game-creator-shell:typecheck
|
||||
npx vitest run apps/ai-game-creator-shell/tests/errorReporting.test.ts apps/ai-game-creator-shell/tests/ErrorReportDialog.test.tsx apps/ai-game-creator-shell/tests/ErrorReportNotice.test.tsx
|
||||
cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings
|
||||
npm run ai-game-creator-shell:check:rust:shell
|
||||
npm run check:generated-bindings
|
||||
npm run check:doc-index
|
||||
npm run check:encoding
|
||||
git diff --check
|
||||
```
|
||||
@@ -1,5 +1,13 @@
|
||||
# 决策记录
|
||||
|
||||
## 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>`），不是新机制。
|
||||
- 决策：错误报告池只收**没有任何调用方处理**的错误。预期业务拒绝（用户输入 / 前置条件 / 预期 4xx）由调用方消化并给反馈，永不进池；真故障由调用方带上下文重抛（`ClientActionError` 承载 `source/action/page`），经 `window.onerror` / `unhandledrejection` 入池；`clientApi` 作为 `fetch` 的调用方在抛出前判定 408/5xx/网络为缺陷（4xx 一律不报）；Rust agent 终态失败仍由失败投影入池。删除 WebView 侧 `shouldCaptureClientError`。
|
||||
- 边界：变体按**可判定的事实**命名——服务端 400 只给 `status + message`（`AppError.code` 仍是通用 `BAD_REQUEST`），所以 400 变体按"哪条请求的输入被拒"命名（如 `passwordEntryInputRejected`），不假装能区分密码长度/手机号格式。报告面板默认全选、只由通知打开的既有承诺不变。`captureAgentRuntimeError`、`ResourceReferenceInput` 偏好写盘、`invokeDiagnostic` 三处显式采集点保持原行为，按同一口径重抛/删除留在后续变更。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/{auth_error.rs,auth_session.rs}`、`apps/ai-game-creator-shell/src/services/{clientAuthError.ts,clientActionError.ts,errorReporting.ts,clientApi.ts,clientAuth.ts}`、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`、`apps/ai-game-creator-shell/src/services/generated/ClientAuthError.ts`（ts-rs 生成）。
|
||||
- 验证：见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md) 的验收清单；关键判据是"登录 400/401 业务变体不产生 `report_client_error`、不弹「发现问题」"。
|
||||
|
||||
## 2026-09-30 release 渠道移除产品名与包名后缀
|
||||
|
||||
- 决策：`release` 渠道的正式产品名统一为 `陶泥儿`，Windows NSIS、macOS DMG / updater 归档等由 Tauri `productName` 派生的包名不再包含 `Release` 文本；`identifier=world.genarrative.ai-game-creator.release` 与 `release-win` 更新分区保持不变。
|
||||
|
||||
@@ -2,6 +2,14 @@
|
||||
|
||||
这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
|
||||
|
||||
## 2026-10-01 用户输错一次密码被当成"客户端出问题了"引导上报
|
||||
|
||||
- **现象**：登录页密码输错（或密码长度不合规）后弹出「发现问题」，报告面板「错误事件（2）」列出 `密码长度需要在 6 到 128 位之间 — auth · 1 次` 与 `手机号或密码错误 — auth · 1 次`，默认全选，与 react-render / 5xx / agent-runtime 终态失败视觉等价。
|
||||
- **原因**：① 登录已下沉 Rust，`login_client_with_password` 等命令失败返回 `Err(String)`，Tauri 以**裸字符串**拒绝 `invoke`，前端拿不到任何类型信息；② `shouldCaptureClientError` 对非 object 值走默认 `return true`，`handleLoginSubmit` 的 catch 把预期业务拒绝报进了错误池。技术方案里"预期 4xx 登录/鉴权失败不进池"的口径早就成立，是错误通道的实现方式违背了它。
|
||||
- **处理（现行口径）**：命令错误一律按具体变体结构化（`Result<_, ClientAuthError>` + ts-rs 导出），UI 调用方按 `type` 分流：认得的业务变体只给用户反馈，系统变体/未识别变体/非结构化拒绝原样抛出走上报链路；删除 `shouldCaptureClientError`。详见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md)。
|
||||
- **判据/取证**：`npx vitest run apps/ai-game-creator-shell/tests/errorReporting.test.ts`——登录返回结构化业务变体时 `report_client_error` 不被调用；系统变体经 `unhandledrejection` 只上报一次且 `source=auth`。Rust 侧 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml auth_error` 钉住变体 `type` 与 400/401/429/5xx/网络映射。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/auth_session.rs`、`apps/ai-game-creator-shell/src/services/errorReporting.ts`、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`。
|
||||
|
||||
## 2026-09-30 构建期 staging 撞上不装 npm 依赖的 Linux 门禁：AGC 壳 Rust lane 全红
|
||||
|
||||
- **现象**：`Project CI` 的 AGC 壳 Rust 三条 lane（`npm run check:native-shells:agc-rust-shard-*`）在 `fb130d184` 之后全部失败，日志只有 `error: failed to run custom build command for genarrative-ai-game-creator-shell` 与 `thread 'main' panicked at build.rs:65:28: Claude Agent SDK 缺失；请先执行 npm ci`（run 3083 / job 17521 实测，1 分钟即失败）。
|
||||
|
||||
@@ -8,10 +8,11 @@ AI Game Creator Shell 采用 IDEA 风格的当前进程错误报告：错误事
|
||||
|
||||
- 诊断 URL 保留可定位的 API 路由路径，隐藏 origin、URL 账号密码、查询参数、fragment 和路径中的敏感标识；普通资源 URL 与本地文件路径继续隐藏。网络错误、HTTP 错误与响应体超时均应带安全路由，不能只剩 `<url>`。历史已经脱敏的归档不推测或补造原路由。
|
||||
|
||||
- 捕获 React render error、`window.onerror`、`unhandledrejection` 以及显式标记的 Tauri/API/Agent 错误。Agent Runtime 的终态失败、预算耗尽和启动确认失败由 Rust 失败投影统一入池；Direct Codex 与专业 Agent 的前台裸 Tauri invoke catch 作为补充入口，重复事件由同一 fingerprint 合并，主动取消和“同一 turn 已在运行”不作为错误采集。
|
||||
- 报告池只收**没有任何调用方处理**的错误：React render error、`window.onerror`、`unhandledrejection`，以及调用方判定为真故障后带上下文重抛的错误。Agent Runtime 的终态失败、预算耗尽和启动确认失败由 Rust 失败投影统一入池；Direct Codex 与专业 Agent 的前台裸 Tauri invoke catch 作为补充入口，重复事件由同一 fingerprint 合并，主动取消和“同一 turn 已在运行”不作为错误采集。分层口径见 [`【ADR】AGC命令错误结构化与错误报告口径-2026-10-01`](../adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md)。
|
||||
- 事件字段包括 eventId、fingerprint、source、message、stack、时间和次数；重复事件合并。不再携带 severity、errorCode、page、action、requestId 等无法稳定关联的字段。
|
||||
- 指纹计算可使用调用方的 page/action 及脱敏后的首个调用点作为进程内区分输入，但这些上下文不会作为事件字段上传；消息与 stack 在入池前统一脱敏，WebCrypto 失败时降级为稳定可读指纹，采集本身不得产生新的未处理拒绝。
|
||||
- 客户端 API 自动采集只覆盖网络错误、408 和 5xx；预期的 4xx 登录/鉴权失败不进入错误报告池。
|
||||
- 命令失败按具体变体建模（Rust 枚举 + ts-rs 导出的 `type` 判别联合），前端按变体分流，**任何地方都不对错误文案做判断**：认得的业务变体（用户输入 / 前置条件 / 预期 4xx）由调用方消化并给用户反馈，永不进池；系统变体、未识别变体和结构化之外的拒绝原样抛出，走上面的兜底入口。
|
||||
- 客户端 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/<eventId>.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` 命中凭据标记时替换的是**整行**，自由文本因此只放详情行：详情行被吃掉也不影响身份行定位事件。
|
||||
- 报告面板只由自动诊断通知中的“查看并报告”打开，不提供聊天命令、崩溃页按钮或其他手动入口；默认选中当前快照中的全部事件，用户可取消不想提交的事件。允许填写最多 2,000 字中文描述并取消日志附件；本版本不支持截图或任意文件附件。
|
||||
|
||||
Reference in New Issue
Block a user