From ccff6cdceb659eea36f3b2250b717136c7125297 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 17:50:00 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AE=B0=E5=BD=95=E8=B5=84=E6=BA=90=E7=BC=96?= =?UTF-8?q?=E8=BE=91=E8=BF=9C=E7=AB=AF=E5=A4=B1=E8=B4=A5=E8=A6=81=E5=B8=A6?= =?UTF-8?q?=E5=87=BA=E5=B9=B3=E5=8F=B0=E5=8E=9F=E5=9B=A0=E7=9A=84=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E5=86=B3=E7=AD=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - decision-log 新增 2026-10-02 条目：ResourceEditError 造型、不用 blanket From、不按 terminal_failure_code 分支、前缀去留、原文边界、Other 命名与 error.rs 落点 - 条目里写清 terminal_failure_code 的清理前置条件：字段无 skip_serializing_if 且账本是 deny_unknown_fields，清掉会影响每个已落盘账本 - pitfalls「远端资源编辑终态必须指出唯一出口」补上处理与验证口径：轮询终态把平台 error 原文装进 typed 错误带出、不再压成一句，断言同时要求原文进文案且不进账本 --- docs/project-memory/shared-memory/decision-log.md | 12 ++++++++++++ docs/project-memory/shared-memory/pitfalls.md | 4 ++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 01fd611cd..558cf4e12 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,4 +1,16 @@ # 决策记录 +## 2026-10-02 资源编辑远端失败的原始原因穿出到工具错误，资源编辑错误通道补一层 typed + +- 背景：轮询到 `status=failed` 时客户端只读 `status`，丢掉平台在同一个响应里给的 `error`（契约 `ExternalEditorGenerationJobResponse.error`），统一写 `terminal_failure_code = remote-generation-failed` 并返回「remote-terminal-failed: 资源编辑生成失败」。平台的可行动原因就此消失：模型与用户卡片只看到一句「失败了」，重试路径（`ensure_resource_edit_phase_resumable`）也只有分类码。这违反 `pitfalls.md`「远端资源编辑终态必须指出唯一出口」里已写下的口径——「首次失败的原始拒绝说明继续由当次错误文案承担」；提交期 HTTP 400 分支（`editor_api_rejection_reason`）兑现了，轮询分支没有。另外 `remote-terminal-failed:` 只是文案前缀（全仓没有 `starts_with` 解析它），在第一句失败文案里与「失败」重复。 +- 决策（typed 承载）：新增 `ResourceEditError`（`project/resource_editor/error.rs`），只两个变体：`RemoteGenerationFailed { serverMessage }` 承载平台 `error` 原文，`Other(String)` 收尚未分类的失败（`// TODO refactor string-typed`）。两个入口 `derive_local_project_resource`、`resume_local_project_resource_edit` 返回 typed；旧名 `derive_local_project_resource_at` / `resume_local_project_resource_edit_at` 保留为 `Result<_, String>` 外观（映射 `to_user_msg()`），因此 33 个既有测试调用点与两个 Tauri 命令零改动。 +- 决策（不用 blanket From）：不提供 `impl From`；每处 String 错误显式 `.map_err(ResourceEditError::Other)`，让「还没 typed 化」的边界处处可见，而不是被一次隐式转换吞掉。 +- 决策（不按 code 分支）：不按 `terminal_failure_code` 分支。它两个写入点最终落到同一个 `phase`、唯一读者只做插值不比较，值域撑不起 policy；字段上加 `// TODO clean unnecessary`。清理前置条件已核实：该字段无 `skip_serializing_if`，`.agent/resource-edits/operations/*.json` 每个文件都带这个 key，而 `ResourceEditLedger` 是 `deny_unknown_fields`、扫描循环里一个文件解析失败会让整个「待恢复资源编辑」列表报错返回。 +- 决策（前缀去留）：删掉第一句失败文案里的 `remote-terminal-failed:`（轮询与提交期 400 两处）。`ensure_resource_edit_phase_resumable` 里那三个 token 保留：它们与三个 phase 一一对应，是那句重试文案里区分「确定失败 / 已归档 / 待对账」的唯一手段。 +- 决策（原文边界）：平台原文只进当次错误文案，仍不进账本（`terminal_failure_code` 的写入边界与既有断言不变）。平台 `user_visible_external_generation_error` 已对四种 kind 做 sanitize，图片/视频两种原样透出——与同 wire 的 `canvas_generation.rs` 口径一致，要收边界应改服务端。 +- 决策（命名与落点）：尚未 typed 化的变体叫 `Other`，不叫 `Message`（后者分不清是「已渲染文案」还是「原始消息」）；新错误单独放 `project/resource_editor/error.rs`，不再往主文件里塞类型定义。 +- 改动范围：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`、`project/resource_editor/error.rs`（新）、`agent/tool/create_or_derive_resource/error.rs`、`agent/tool/remove_background/error.rs`、`agent/direct_tool_bridge.rs`、`docs/project-memory/shared-memory/pitfalls.md`。 +- 验证：待补（`cargo test --bin genarrative-ai-game-creator-shell -- project::resource_editor` 与 `-- agent::direct_tool_bridge`；`npm run check:encoding`；`git diff --check`）。 +- 关联：`pitfalls.md`「远端资源编辑终态必须指出唯一出口」。 ## 2026-10-01 Web、后台与 AGC 一键联调 - 背景：Web、管理后台和 AGC 同时开发时，分别启动入口容易产生两套 API/worker/SpacetimeDB，以及重复后台 Vite。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 901bff371..8bc2f2cc3 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -340,8 +340,8 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只 - 现象：「生成背景音乐」再次提交 0.1 秒就失败，卡片只有 `remote-terminal-failed: 远端资源编辑已明确失败，不允许再次请求`，既没有原因也没有下一步。 - 原因：上一次同 `operationId` 的请求被平台确定性拒绝（HTTP 400 或任务 `failed`）后，账本落到 `remote-failed`，之后所有重试都在 `ensure_resource_edit_phase_resumable` 失败关闭；唯一出口是「待恢复资源编辑」里的移出恢复队列，但终态文案没有指向它。 -- 处理：终态文案带出稳定失败码，并明确「先在待恢复资源编辑中把它移出恢复队列」；上游失败原文仍不写入账本（只存分类码），首次失败的原始拒绝说明继续由当次错误文案承担。 -- 验证：`remote_failed_status_is_terminal_and_can_only_be_archived`、`submission_bad_request_is_terminal_while_gateway_failure_requires_reconciliation` 等资源编辑用例继续通过，账本序列化不含上游失败原文。 +- 处理：终态文案带出稳定失败码，并明确「先在待恢复资源编辑中把它移出恢复队列」；上游失败原文仍不写入账本（只存分类码），首次失败的原始拒绝说明继续由当次错误文案承担——轮询终态这条路由此改成把平台 `error` 原文装进 `ResourceEditError::RemoteGenerationFailed` 原样带出（2026-10-02），不再压成「资源编辑生成失败」一句；第一句失败文案不再带 `remote-terminal-failed:` 前缀。 +- 验证：`remote_failed_status_is_terminal_and_can_only_be_archived` 断言失败文案带出平台 `error` 原文、同时账本序列化不含原文；`background_removal_remote_failure_keeps_manifest_without_result` 覆盖平台没给 `error` 时的兜底文案；`submission_bad_request_is_terminal_while_gateway_failure_requires_reconciliation` 等资源编辑用例继续通过。 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`。 ## Tauri `--no-sign` 会连带跳过 updater 签名