Merge remote-tracking branch 'origin/master' into fix/web-preflight-browser-recovery

docs/project-memory/shared-memory/decision-log.md

@@ -1,4 +1,22 @@
 # 决策记录
+## 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>`；每处 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`，不再往主文件里塞类型定义。
+- 决策（工具层承载）：`RemoteGenerationFailed` 不能到工具层又被压回一句字符串。共用载体放 `agent/tool/error.rs` 的 `RemoteResourceEditFailure { serverMessage }`（两个工具共用的文案只写一份），`CreateOrDeriveResourceError` / `RemoveBackgroundError` 各加 `RemoteGenerationFailed(RemoteResourceEditFailure)` 变体；翻译用显式 `from_resource_edit_error`，不用 `impl From<ResourceEditError>`，远端终态进 `RemoteGenerationFailed`、其余 `Other` 仍落回各工具原有的「失败：<文案>」变体。这样诊断 sidecar 的 `error` 字段（typed enum 整体序列化）天然带上平台原文，LLM 侧拿到的 `message` 也带上。
+- 决策（前缀归属，2026-10-02 追加）：叶子错误只给事实，不给「谁失败了」的总结前缀。`RemoteResourceEditFailure::to_user_msg` 与 `ResourceEditError::to_user_msg` 都只返回平台 `error` 原文；平台没给就回「服务器未返回错误信息」，不再说「资源编辑生成失败」这种没有信息量的总结。typed 错误新增 `phaseDetail` 字段，但它只作为结构化字段进诊断 sidecar（开发者/LLM 侧看原始值），**不参与用户文案**。前缀由使用者自己加：`agc_create_or_derive_resource` 用「生成或派生资源失败：」、`agc_remove_background` 用「抠图失败：」、桌面命令面用「资源编辑生成失败：」。同一份 typed 错误因此可以同时服务工具面（前缀各随其工具）与桌面面（保留原有文案）。
+- 决策（HTTP 兜底与叶子前缀，2026-10-02 追加）：叶子只给「服务端 message / code / 原始传输事实」这类事实，不把操作名写进叶子。`game_package_upload/runtime.rs` 三处 `let (_, message)` 把服务端 `code` 丢掉、再拼「读取上传状态失败（HTTP 503）」这类前缀，改成 `message` → `code` → `HTTP {status}`（操作名交给调用方的话术）。`game_distribution_publish.rs` 的 `response_data`（2xx + `ok:false`）同样用上被丢掉的 `error.code`，`account_api.rs` 的 envelope 分支补 `error.code`；服务端没给任何原因时统一回「服务器未返回错误信息」。错误类型自身的单测不再断言 `to_user_msg()` 的字面量（文案是给用户的话术，不是契约），只保留「typed 字段原样序列化进诊断」的结构断言。
+- 决策（凭据作用域的 error 类型）：`with_direct_editor_api_credentials` 原本把操作限定成 `Result<_, String>`，会把 typed 错误提前压掉。新增 `with_direct_editor_api_credentials_as(operation, credentials_error)` 保留调用方 error 类型，凭据解析失败由调用方显式翻译（这里传 `ResourceEditError::Other`），旧名保持 `String` 语义、零改动。
+- 决策（future 装箱）：`handle_direct_tool_bridge` 的状态机在调试测试线程的默认栈上已经贴着上限，资源编辑 arm 直接内联会顶穿（`bridge_write_file_waits_on_the_blocking_pool_instead_of_a_runtime_worker` 栈溢出）。桥里四个资源编辑 await 点用 `Box::pin` 只留指针进外层状态机；这是体积问题，不是错误用 `Box`。
+- 决策（同类兜底，2026-10-02 追加）：`agent/generation/canvas_generation.rs` 的远端 `failed` 分支原来在平台没给 `error` 时兜底成「生成任务失败」，与句首的「平台图片生成任务失败：」重复，改成「服务器未返回错误信息」；`phaseDetail` 不再参与用户文案（只作结构化字段）。
+- 改动范围：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`、`project/resource_editor/error.rs`（新）、`agent/tool/error.rs`、`agent/tool/create_or_derive_resource/error.rs`、`agent/tool/remove_background/error.rs`、`agent/direct_tool_bridge.rs`、`assets.rs`、`docs/project-memory/shared-memory/pitfalls.md`。
+- 验证：`cargo check --bin genarrative-ai-game-creator-shell --tests` 通过；`cargo test --bin genarrative-ai-game-creator-shell -- project::resource_editor --test-threads=1` 66 passed（并行跑会有一批 TCP fixture 用例因争用超时，串行全绿，与本次改动无关）；`-- agent::tool:: agent::direct_tool_bridge` 47 passed；`npm run check:encoding` 5111 files；`git diff --check` 干净；`cargo fmt` 已跑。
+- 关联：`pitfalls.md`「远端资源编辑终态必须指出唯一出口」。
 
 ## 2026-10-02 DirectProject 对话：更早历史自动加载、前插锚定与回到底部胶囊
 

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），工具层经 `RemoteResourceEditFailure` 转发时保留 `error` 与 `phaseDetail` 两个原始字段（`phaseDetail` 只进诊断，不当用户文案）；`to_user_msg` 只给 `error` 原文，平台没给就说「服务器未返回错误信息」。前缀由使用它的工具/命令自己加（不再统一压成「资源编辑生成失败」一句，也不再多一层无信息前缀）；第一句失败文案不再带 `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 签名
@@ -6269,3 +6269,15 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **注意**：日志脱敏标记包含 `credential`、`x-api-key`、`bearer `、`token=`、`api_key`，命中即整行替换成 `<sensitive diagnostic details redacted>`。诊断行只能写 `source=`/`host=`/`auth=` 这类自查过的字段（第一版写成 `credential=bearer`，整行被吃掉过一次）。
 - **验证**：`cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute --bin genarrative-ai-game-creator-shell claude_code_cli::tests::` 11 passed，覆盖平台优先、自定义端点保留配置、未登录时不回落本机环境且报「先登录」、baseUrl `/v1` 归一化、主机名诊断、sidecar 环境隔离（`USERPROFILE`/`CLAUDE_CONFIG_DIR` 指向隔离目录且不带本机 `ANTHROPIC_*`）；另用本地假 Anthropic 端点跑通真 sidecar：`REQ HEAD /api/hello` → `REQ POST /v1/messages?beta=true auth=bearer` → `result=PROBE_OK`。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`、`apps/ai-game-creator-shell/agent-sidecar/src/index.mjs`、[`【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`](../../technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)。
+
+## 2026-10-03 cc 回合"模型已回复却报宿主任务提前结束"：缺终态 + 缺落盘 + 工具被拒
+
+- **现象**：Router 渠道恢复后，cc 回合能拿到真实回复（日志 `stage=claude-parse-done chars=176/208/289`），但紧接着就是 `runtime-unclassified` +「DirectProject 宿主任务提前结束（panic、future 被丢弃或被取消）」，用户看到的仍是失败；项目对话历史里只有用户消息、没有助手消息；模型还会回一句「读项目文件的工具没有权限」。
+- **根因 1（缺终态）**：终态 `turn.completed` 的"深层出口"只在 codex app-server 那条路径里（`DirectTurnTerminalContext::write` → `complete_turn`）。cc 执行器（`direct_game_creator_claude_code_chat_at`）整轮成功返回后没有任何人写终态，于是 `thread_manager::dispatch` 里占用对象的兜底把一轮已经拿到回复的回合收成 `HostDropped`。诊断行 `agent.direct_turn.host_dropped … panicking=false` 且**没有** `agent.direct_turn.panic` 行，就是这条（不是 panic，是"没写终态就结束"）。
+- **根因 2（缺落盘）**：assistant 回复只存在于 SDK 事件流里。codex 路径由 `finish_direct_project_collect_history` 写进 `.agent/conversations/project.jsonl`，cc 没有对应步骤，所以即使回合收口成功，UI 也读不到回复。
+- **根因 3（工具被拒）**：sidecar 用 `permissionMode: 'dontAsk'` 且没有 `allowedTools`，宿主 MCP 工具（`mcp__agc__*`）一律被直接拒绝，模型只能回"没有权限"。
+- **根因 4（界面看不到回复）**：聊天区是按 `item.completed` 事件流投影的（codex 路径在 `rawResponseItem/completed` 时下发 `ThreadItem::Message`），只把回复落进 `project.jsonl` 不会让本轮出现在界面上——用户看到"用户气泡 + 本轮结束于 … · 耗时"，回复只在重进项目时从历史读出来。
+- **现行口径**：cc 成功出口由放行侧补写 `DirectTurnTerminal::completed()`（`finish_if_unfinished` 幂等，codex 已写过终态时是空操作）；cc 解析成功后必须①把回复按 `{"type":"message","role":"assistant","id":"direct-codex:<clientTurnId>:assistant","content":[{"type":"output_text","text":…}]}` 落进项目历史，②用**同一个 id** 下发 `ThreadEvent::item_completed(ThreadItem::Message{role:"assistant"})`（落盘失败按回合失败收口）；sidecar 按 `mcp__<server>` 前缀整体放行请求里声明的 MCP 服务器（权限策略在宿主侧执行）。
+- **诊断口径**：`agent.direct_turn.host_dropped` / `agent.direct_turn.panic` 里的令牌字段必须写 `tt=`，写 `turnToken=` 会命中脱敏标记，整行变成 `<sensitive diagnostic details redacted>`，离线只剩"说不出原因"的 HostDropped。
+- **验证**：dev 栈里用 CDP 注入真实回合（`node %TEMP%\agc-cdp.mjs <expr>`）：①读文件轮 `claude-parse-done chars=108`，`.agent/conversations/project.jsonl` 出现 `direct-codex:cdp-…:assistant` 条目，回复内容与 `game/index.html` 前两行（`<!doctype html>` / `<html lang="zh-CN">`）逐字一致（证明宿主工具真的执行了）；②聊天视图打开时注入 `只回三个字：收到了`，DOM 断言（`document.body.innerText`）同时出现用户气泡 `11:40:05`、助手回复 `收到了` 与 `本轮结束于 11:40:16 · 耗时 10.7秒`（证明 `item.completed` 实时投影生效，不必重进项目）；同一日志不再出现新的 `host_dropped`。`cargo test … -- claude_code_cli::tests direct_turn_failure::tests` 19 passed。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_turn_failure.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`、`apps/ai-game-creator-shell/agent-sidecar/src/index.mjs`。