Merge remote-tracking branch 'origin/master' into feat/gptimage2to2.5

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

@@ -71,6 +71,15 @@
 - 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{ResourceCanvasAssetGenerationTasksPanelView.tsx,resourceCanvasAssetGenerationTasksSidebar.css}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/{resourceCanvasAssetGenerationTasksPanel.test.tsx,resourceCanvasAssetGenerationTasksSidebarStyle.test.ts,resourceCanvasGenerationTasksSidebarDismiss.test.tsx}`、PRD §3.10。未动 Rust、SpacetimeDB、`packages/`、共享弹窗组件。
 - 已知未覆盖：真实客户端观感（右上角坐标相对画布顶边的落点、与运行表现层版本入口的间距）未在 Tauri 里目视确认；窄屏（≤480px）只有声明级断言。
 
+## 2026-09-21 画布绑定前置查询收口为项目摘要，失败文案补因链
+
+- 背景：dev 上「AI 生成图片」连续失败，卡片显示 `解析读取外部画布项目响应失败：error decoding response body`，每条恰好 `1 分 00 秒`；同批的远端资源编辑终态只提示「已明确失败」，用户看不到原因也看不到下一步。（同批「图标素材切片超过 64 个」已由本文件「图集切片上限：客户端结果门从 64 对齐到平台契约的 256」条目决策，这里不再重复。）
+- 决策（项目列表视图）：`GET /api/editor/projects` 与 `GET /api/external/v1/editor/projects` 共用同一套 `view` 取值与摘要投影（缺省 `full` 保持兼容，未知取值失败关闭）；`summary` 只回传 `projectId / title / updatedAt / cover`，既不做内联媒体修复，也不带画布与全量资源。投影实现收敛到 `editor_project.rs` 一份，外部 API 与 MCP 复用同一份；AGC 画布绑定前置查询固定使用 `?view=summary`，它只需要 `projectId`。
+- 决策（错误文案与终态出口）：外部请求失败文案补 kind 语义与底层因链（`reqwest::Error` 的 `Display` 只有 kind，超时 / 正文截断 / 非法 JSON 显示成同一句话），且不拼接 URL；远端资源编辑终态文案带出稳定失败码并指向唯一出口「移出恢复队列」，上游原文继续不写入账本。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/external_editor_api.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`、`project/resource_editor.rs` 与对应夹具。
+- 验证方式：`cargo test --locked -p api-server -- summary`（含站内 `view=summary` 跳过媒体修复、未知 view 返回 400 的新用例）、AGC 壳 `agent::generation::`（99 项）与 `project::resource_editor::`（59 项）、`cargo fmt --check`、`npm run check:encoding`、`git diff --check`。
+
+
 ## Unity 与 Godot 常用操作指导
 
 两种编辑器的操作指导复用客户端审核 Skill pack：DirectProject 通过原生 Skill 或既有审核资源读取入口按需取得，Agent Runtime 的对应执行工具说明嵌入同源参考。指南不改变插件可用性、执行授权或 Runner 回执；只读说明不能证明编辑器已连接。常用示例与执行失败/部分修改、保存、撤销边界在同一参考中维护，避免提示词和文档各存一份代码。

docs/project-memory/shared-memory/pitfalls.md

@@ -14,6 +14,10 @@
 
 Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只有当被复制 Job 的 `CopyArtifactPermissionProperty`（仓库里由 Declarative 的 `copyArtifactPermission(...)` 维护）显式列出当前消费者，或者该 Job 对认证用户开放 Item.Read 时才放行；`ACL.SYSTEM2` 的定时构建会短路通过。因此会出现「定时调度一路成功、手动发布必挂」的现象（2026-09-21 手动发布 #6/#7 与同期的用户触发探测全部命中，定时调度 #104+ 正常）。`Genarrative-Agc-Global-Version-Issue` 生产权限模式的授权名单必须同时包含 `Genarrative-Scheduled-Revision-Trigger` 与 `Genarrative-Manual-Build-And-Deploy`；改完 `copyArtifactPermission` 后要先跑一次发号 Job 把 Job property 写回 Jenkins，只改仓库文件不生效。
 
+## 手工发布目标不会自动映射成 AGC 更新渠道
+
+`Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET=release` 只控制 Stdb / API / Web 全量发布，不会自动成为 AGC 的 `AGC_UPDATE_CHANNEL`。2026-09-21 的手工发布 #10 就因此让 Windows #107 与 macOS #16 使用默认 `dev`，把 `0.1.95` 上传到 `agc/dev-win`、`agc/dev-mac`，而 `agc/release-win/latest.json`、`agc/release-mac/latest.json` 保持 404。现行口径：手工入口按 `release -> release`、`development -> dev` 同时给 Windows 与 macOS AGC Build 传 `AGC_UPDATE_CHANNEL`；补发已烧号的同一版本时用相同 `AGC_RELEASE_VERSION` 直接重跑两条 AGC Job，不重新发号。OSS 发布对象是 `agc/<channel>-win|mac/`，不存在 `agc/release/` 这一层。
+
 ## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃
 
 - 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
@@ -42,6 +46,22 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只
 
 `Genarrative-Agc-Windows-Build` 在阶段里用 `AGC_WINDOWS_PATH` 整体替换 PATH、不继承节点机器的 PATH，所以 Godot C++ 引导需要的 CMake 与 Python 必须显式写进这份白名单，装在机器 PATH 上并不生效。2026-09-21 的 #97–#99 连续失败都停在 `Get-Command cmake.exe`（#93–#96 是更早的手写 C ABI 在 MSVC C 模式下的对齐问题）：节点只有 Visual Studio Build Tools（`C:\BuildTools`）自带的 CMake 3.31，缺 Python 3。修复后白名单包含 `C:\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`、`C:\Python312`、`C:\Python312\Scripts`，preflight 校验 CMake ≥3.25、Python 3 和 Visual Studio 17 2022 生成器；把 `cmake.exe` 单独复制到别的目录会丢掉 `share/cmake-*/Modules`，不能替代加入安装目录。新节点的 Python 用 `python-3.12.10-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python312 PrependPath=1 Include_launcher=1 InstallLauncherAllUsers=1` 静默安装即可，CMake 不必另装。
 
+## AGC 画布绑定前置查询不能取全量项目列表
+
+- 现象：dev 上「AI 生成图片」连续失败，卡片显示 `解析读取外部画布项目响应失败：error decoding response body`，每条恰好 `1 分 00 秒`（三条同因，各自独立计时）。
+- 原因：绑定前置的 `GET /api/(external/v1/)editor/projects` 缺省 `view=full`，会把账号下每个项目的画布与全量资源一起返回（19 个大项目的 fixture 就已超过 4 MiB）；客户端这条请求只有 60 秒预算，卡在读正文时被 reqwest 总超时打断。而 `reqwest::Error` 的 `Display` 只打印 kind，超时、正文被截断和非法 JSON 显示成同一句话，现场看不出根因。
+- 处理：只确认项目身份的消费者固定取 `view=summary`（站内与外部路由都支持，缺省 `full` 不变，未知取值失败关闭）；摘要视图不做内联媒体修复、不带画布与全量资源；外部请求失败文案补 kind 语义与 source 因链，且不拼接 URL。
+- 验证：站内路由用例断言 `view=summary` 不回传 `canvas / layers / resources` 且不触发媒体修复、`view=unknown` 返回 400；AGC 壳用例断言失败文案不再等于 `error decoding response body`、补出因链且不含绝对地址。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/external_editor_api.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`。
+
+## 远端资源编辑终态必须指出唯一出口
+
+- 现象：「生成背景音乐」再次提交 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` 等资源编辑用例继续通过，账本序列化不含上游失败原文。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`。
+
 ## Tauri `--no-sign` 会连带跳过 updater 签名
 
 AGC macOS 发布入口一度传入 `--no-sign`（目的是绕过没有 Apple 证书的代码签名），结果 Tauri 打印 `Warn Updater signing is skipped due to --no-sign flag.`，产物只有 `*​.app.tar.gz` 而没有 `.sig`，发布入口按设计在「缺少更新包签名」处失败关闭（2026-09-20 首次 Jenkins 实跑命中）。正确做法是不传 `--no-sign`，改为剥离 `APPLE_*` 凭据让 Tauri 跳过 Apple 签名——minisign 更新包签名与 Apple 代码签名这两个开关在 Tauri 里并不独立。Apple 签名状态要按 `codesign -dv` 实测记录，不能硬编码。

docs/project-memory/shared-memory/project-overview.md

@@ -51,6 +51,8 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 
 ## AGC DirectProject 与 UI workflow
 
+- AGC 模板库包含 Creator 3.8.8 的四个官方 Cocos 模板；Cocos 建项复用原生导入，重建项目 UUID 并保留场景与资源。发布使用内容地址保留历史对象，并在确认 Bucket 从未开启版本控制后获取排他锁；`--only` 在锁内合并最新清单，清单写入结果不明时留锁，同版本 ZIP 变化拒绝发布。详细合同见 [AGC 模板库与模板建项](../../technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)。
+
 - AGC 的本地 `llm.customEnabled` 默认关闭，只能手动修改配置文件；开启后设置支持自定义 Responses 端点、读取 `/models`、勾选和预览 `visibleModels`。对话下拉只显示勾选项，LLM 请求经客户端凭据代理直连自定义上游；不会回退官方中转，平台资源服务仍使用账号权限。详见 AGC 后台模型别名与对话选择规范。
 
 - DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。