合并 master 并保留 GPT Image 2.5 与外置提示词行为

保留编辑器图片工具使用 gpt-image-2.5 业务模型名

保留工具参数说明从 prompts 外置文件读取

同步外置模型与尺寸文案并完成冲突验证

docs/README.md

@@ -27,28 +27,32 @@
 
 - [AGC 资源 kind 枚举化契约](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-09-15-gamecreationapp-资源-kind-枚举化当前权威口径)：GameCreationApp 资源 kind 的 Rust enum、ts-rs 绑定、Unknown 可观测性和 shell 内重构边界。
 
-- [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：实施中；以自由协作原型为行为基线，复用生产基建，采用阶段审批与用户工作区文件浏览。无旧 V2 会话的策划入口切换到新设计 Agent。
+- [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：已完成；当前策划入口统一使用 Design Agent，采用阶段审批与用户工作区文件浏览。旧 V1/V2 会话、命令、专用展示和测试不再作为兼容目标。
 
 - [LLM 累计额度结算](./technical/【技术方案】LLM累计额度结算-2026-09-05.md)：Router 累计额度、首次基线与原子钱包结算。
+- [Responses API 与 Agents SDK 迁移评估](./technical/【技术评估】Responses%20API与Agents%20SDK迁移评估-2026-09-07.md)：评估 AGC 核心 Runtime 是否迁移到外部 Agent SDK 及其边界。
 
 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
+- [AGC 后端框架整理与演进路线](./technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)：共享 Runtime、本地执行宿主、云端控制面、领域/平台适配器及分阶段收口边界。
 - [AGC 异步操作可恢复闭环](./【技术方案】AGC异步操作可恢复闭环-2026-09-14.md)：认证响应体、最近项目检查和首页自动创建的超时、逐项恢复与跨页防重合同。
 - [AGC 客户端稳定版生命周期大切换](./【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md)：统一 operation、认证/Runner、项目入口、本地恢复和 dev-stack 身份边界。
-- [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：新单 Agent 策划会话、GDD 策略、未来 MCP/Skill 兼容插槽、阶段任务与退役验收合同。
+- [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：历史方案，仅用于追溯 V2 的实现与退役过程，不作为当前实现依据。
 - [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。
 - [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
 - [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
 - [AGC Unity 编辑器插件接入](./technical/【技术方案】AGC Unity编辑器插件接入-2026-09-18.md)：DotCraft Attach 来源、Windows Mono 接入、项目身份、执行回执和分发边界。
+- [AGC Godot 编辑器插件接入](<./technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)：GDExtension 聚焦加载、安装资源、受管描述文件、UID 归属、GDScript 回执与 Runner 边界。
 - [AGC Cocos Creator 编辑器桥接模块](<./technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md>)：独立 crate、feature 开关、目标校验与 Windows 注入边界。
-- [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、OSS 清单格式和下载约定。
+- [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、固定 dev 服务、OSS 清单与官网最新客户端下载。
+- [AGC 总版本号与发号](./technical/【技术方案】AGC总版本号与发号-2026-09-20.md)：客户端版本号收口到 OSS `agc/global-version.json`，统一构建一次发号供各渠道共用，渠道高水位降级为断言。
 - [AGC 模板库与模板建项](./technical/【技术方案】AGC模板库与模板建项-2026-09-17.md)：`templates/` 前缀的模板库契约、下载安装与「用模板建项目」链路。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
 - [Direct 回合行为审计账本](./technical/【技术方案】Direct回合行为审计账本-2026-08-31.md)：Direct GUI 回合把 native 读 / MCP / 写文件落成项目内有界时间线，用于判断有没有打开本轮附件。
 - [项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)：当前工作台页面和验收边界。
 - [AGC 错误报告与诊断上传](./technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md)：当前进程错误事件、应用级日志和管理员查看器合同。
-- [立项策划 Agent（Fast GDD）](<./technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md>)：旧 `project-supervisor-plan` / `project-planning` 历史会话的入口、审批和恢复合同；V2 切换时未完成旧会话强制失败。
+- [立项策划 Agent（Fast GDD）](<./technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md>)：历史 V1 方案，仅用于追溯；旧 `project-supervisor-plan` / `project-planning` 入口、审批、恢复和测试均已删除。
 - [GameAgent 资源自由画板与快速编辑](./technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md)
 - [AGC 栏目画布底部工具栏入口矩阵](./technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)：栏目画布底部工具栏的入口矩阵、可用条件与验收口径。
 - [AGC 资源工作台三处交互收口改动前对照图](./technical/assets/agc-resource-workbench-ui-before-20260914/README.md)：任务侧栏两个关闭入口、左侧贴边折叠把手、顶部播放按钮居中悬浮三张改动前截图与问题说明。

docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md

@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-09-14`（同步功能画布图片类生成后台化的当前事实：入口 IPC 改为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板，见 §3.10 / §7.9；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
+更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**（验收现场两条修正：任务锚点改挂画布那一格、展开后开关让位），见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
 
 ## 1. 产品定位
 
@@ -151,26 +151,28 @@
 
 ### 3.10 功能画布底部工具栏（入口矩阵）
 
-实现状态（2026-09-13；2026-09-14 图片类生成后台化：提交即返回 + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板）：功能画布 = 资源栏目页（`resourceBookState.view === 'child'`）。栏目页左下角的底部工具栏按 manifest 资产的**功能分类** `category` 分流，矩阵由用户 2026-09-13 拍板，工具项顺序即下表顺序（最右一项为「上传」）。
+实现状态（2026-09-13；2026-09-14 图片类生成后台化：提交即返回 + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-20 音频生成并入同一条后台任务账本）：功能画布 = 资源栏目页（`resourceBookState.view === 'child'`）。栏目页左下角的底部工具栏按 manifest 资产的**功能分类** `category` 分流，矩阵由用户 2026-09-13 拍板，工具项顺序即下表顺序（最右一项为「上传」）。
 
-| 栏目 | 工具栏里的生成入口 |
-| --- | --- |
-| UI 与交互 `ui-interaction` | 生成图片 ｜ 生成规范（二级：图标规范 / 自定义规范）｜ 生成图标素材 ｜ 生成 UI 设计图 ｜ 上传 |
-| 角色与对象 `character` | 生成图片 ｜ 生成规范（二级：角色规范 / 自定义规范）｜ 生成角色形象 ｜ 上传 |
-| 场景与环境 `scene` | 生成图片 ｜ 生成规范（二级：自定义规范）｜ 上传 |
-| 音频 `audio` | 生成背景音乐 ｜ 生成音效 ｜ 上传 |
-| 文档 `document`、待归类 `unclassified`、项目版本 `version`、「所有资源」展开态、资源总览 | **不渲染工具栏** |
+| 栏目                                                                                     | 工具栏里的生成入口                                                                           |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| UI 与交互 `ui-interaction`                                                               | 生成图片 ｜ 生成规范（二级：图标规范 / 自定义规范）｜ 生成图标素材 ｜ 生成 UI 设计图 ｜ 上传 |
+| 角色与对象 `character`                                                                   | 生成图片 ｜ 生成规范（二级：角色规范 / 自定义规范）｜ 生成角色形象 ｜ 上传                   |
+| 场景与环境 `scene`                                                                       | 生成图片 ｜ 生成规范（二级：自定义规范）｜ 上传                                              |
+| 音频 `audio`                                                                             | 生成背景音乐 ｜ 生成音效 ｜ 上传                                                             |
+| 文档 `document`、待归类 `unclassified`、项目版本 `version`、「所有资源」展开态、资源总览 | **不渲染工具栏**                                                                             |
 
 - 位置与层级：画布左下角（`left: 14px; bottom: 14px; z-index: 40`）。右下角是既有的缩放 / 撤销 Dock（`right: 14px; bottom: 14px`），左下角是画布上唯一两者都不占的稳定空位。工具栏是管理区 `.game-resource-book-manager` 的**直接子节点**、与画本场景并列，不进带 `scale()` 的场景层；二级菜单与「入口不可用原因」都贴着工具栏上沿弹出，不做内嵌内容。
 - 外壳用共享 chrome（`packages/image-canvas-react` 的 `CanvasToolbar / CanvasToolbarGroup / CanvasChromeButton`），样式落在 AGC 的 `resourceCanvasChrome.css`；共享包只承接通用表现，不含业务规则。
-- 接线：图片类入口走本地 IPC `start_local_project_asset_generation`（`kind` ∈ `image / character / spec / icon-spec / ui-prototype / art-spritesheet`；**提交即返回任务记录**，生成由 Rust 后台任务跑完写回项目，进度用 `list_local_project_asset_generations` 读回项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`）；音频入口复用既有的无源生成链路 `derive_local_project_resource`（`generationMode: 'create'`、`editKind` = `sound-effect` / `background-music`）；「上传」复用 `upload_local_asset`。生成 / 上传成功后一律用「配对读 `(revision, manifest)`」交给 `onManifestChange`，走既有 manifest 刷新与资源投影链路，不重算依赖图、不另写布局。
-- 本地排队与进度可见：AGC 本地 durable 输出槽已按**精确动作指纹**分槽（不同 prompt / 素材名各自独立成槽，具备并行能力），但本批前端仍按「同一时刻只派发一条」排队——真并行派发需要并发收口设计（配对读 + manifest CAS + 聚焦意图互不覆盖），留待下一批；所以第一条未终态时第二条提交停在**前端本地队列**里（不调用提交 IPC，显示本地排队的「排队中。」），前一条终态后自动补发；任务状态与阶段文案（后端 `phaseDetail`）由任务账本提供，前端不拼阶段、不做百分比。进度面是**画布上常驻的可折叠任务侧栏**（形态对齐网页端美术画布的任务侧栏）：展开是两个分栏「排队/生成中」与「已完成」（各带条数，「已完成」封顶 20 条 + 列表滚动 + 高度有界），关闭入口只保留头部那一枚 ×（底部重复的关闭按钮与其分割线已删除）、折叠即整块让出画布且不留贴边把手，开合只走工具条上常驻的「生成任务 · N」按钮（两个页签下都在）；每项显示状态徽标 / 阶段文案 / 已耗时 / 素材名，可「定位到素材」。侧栏非模态（不铺全屏遮罩、不做焦点陷阱、不参与模态遮挡判据），位置在画布左侧标题栏之下、**覆盖式**（不 reflow 挤窄画布视口），提交受理后自动展开。定位动作**每次点击都终局化**：能定位就定位并选中；素材在别的栏目先切栏目；不在投影里给「素材已不在项目里 / 已登记但尚未同步」的结论；3 秒内有界兜底，不允许提示条永久停在「正在定位生成的素材…」。
+- 接线：图片类入口走本地 IPC `start_local_project_asset_generation`（`kind` ∈ `image / character / spec / icon-spec / ui-prototype / art-spritesheet`；**提交即返回任务记录**，生成由 Rust 后台任务跑完写回项目，进度用 `list_local_project_asset_generations` 读回项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`）；音频入口也走 `start_local_project_asset_generation`（同一份项目内任务账本；`kind` = `sound-effect` / `background-music`，并额外携带该次生成的请求身份 `idempotencyKey`，任务 id 即该次生成的 operation id；生成仍复用既有音频无源生成链路，`generationMode: 'create'`、`editKind` = `sound-effect` / `background-music`，不新增平台路由与请求体口径）；「上传」复用 `upload_local_asset`。生成 / 上传成功后一律用「配对读 `(revision, manifest)`」交给 `onManifestChange`，走既有 manifest 刷新与资源投影链路，不重算依赖图、不另写布局。
+- 本地排队与进度可见：AGC 本地 durable 输出槽已按**精确动作指纹**分槽（不同 prompt / 素材名各自独立成槽，具备并行能力），但本批前端仍按「同一时刻只派发一条」排队——真并行派发需要并发收口设计（配对读 + manifest CAS + 聚焦意图互不覆盖），留待下一批；所以第一条未终态时第二条提交停在**前端本地队列**里（不调用提交 IPC，显示本地排队的「排队中。」），前一条终态后自动补发；任务状态与阶段文案（后端 `phaseDetail`）由任务账本提供，前端不拼阶段、不做百分比。进度面是**画布上常驻的可折叠任务侧栏**（位置与开合形态照抄网页端美术画布的任务侧栏的右上角锚点，颜色与外形仍走 AGC 平台 token；2026-09-21 由「左侧贴边 + 工具条入口」改为「右上角锚点 + 常驻开关」）：展开是两个分栏「排队/生成中」与「已完成」（各带条数，「已完成」封顶 20 条 + 列表滚动 + 高度有界），关闭入口只保留头部那一枚 ×（底部重复的关闭按钮与其分割线已删除）、折叠即整块让出画布、只留那一枚右上角开关（工具条上不再有重复入口），开合只走画布右上角那一枚「生成任务 · N」开关（两个页签下都在；**展开后开关让位、只留面板**，收起走面板头部 × 或点画布外部）；锚点是画布那一格网格里的条目（不是写死 `top` 的绝对定位），工具条换行变高也不会压上去；每项显示状态徽标 / 阶段文案 / 已耗时 / 素材名，可「定位到素材」。侧栏非模态（不铺全屏遮罩、不做焦点陷阱、不参与模态遮挡判据），位置在画布右上角锚点里（照抄美术画布那一处）、**覆盖式**（不 reflow 挤窄画布视口），提交受理后自动展开。锚点按工作面分档：资源栏目画布与 UI 编辑器用画布顶边那一档，运行表现层下移让开右上角的版本入口；锚点是**画布那一格网格里的条目**（不是写死 `top` 的绝对定位），所以工具条换行变高也不会压上去。定位动作**每次点击都终局化**：能定位就定位并选中；素材在别的栏目先切栏目；不在投影里给「素材已不在项目里 / 已登记但尚未同步」的结论；3 秒内有界兜底，不允许提示条永久停在「正在定位生成的素材…」。
 - 面板形态：独立浮层（`ThemedModal`），**不在当前面板下面追加内容**；面板内不写功能说明或规则解释文案。**点「生成」即同步关闭面板**（不等 IPC、不等排队、不等生成），面板里**不出现**「排队中。」「正在生成。」「提交中…」这类阶段文案——阶段文案的唯一去处是任务侧栏与工具栏提示条。**只有「点击瞬间就失败」**（校验不过、权限拒绝、start IPC 立即报错）才自动重开面板并带回草稿与原因；**受理之后才失败**只在侧栏把该任务收口为失败 + 原因，不重开面板。关闭 ≠ 取消请求（请求挂在任务与账本上，不挂在面板生命周期上）。
 - 参数口径：比例 / 尺寸选项来自网页端美术画布的纯模型（`src/components/image-editor/ImageCanvasGenerationModel.ts`），并按本地 IPC 白名单收窄（本地通道明确拒绝 `4:3`）；默认档 `1:1 · 1K`，生成 UI 设计图沿用网页端 UI 设计面板的默认 `16:9 · 1K`。本地 IPC 没有 `model` 入参，因此面板**不渲染模型选择器**（渲染一个改不了请求的控件就是假控件）。
 - 规范类和固定档：生成规范下的图标规范 / 角色规范 / 自定义规范都是固定档——只读展示当前规格，不给点了不生效的比例控件。本地 IPC 只有一条规范通道（`spec` 在 Rust 侧收口到 `icon-spec`），**没有 `specType` 入参**，因此角色规范与自定义规范共用该通道，靠素材名与提示词区分。
 - 前置规范图：`start_local_project_asset_generation` 的 `ui-prototype` 与 `art-spritesheet` 要求项目里已有登记并绑定当前账号的 `assets/art-spec.png`（`kind: icon-spec`、图片媒体类型、来源为画布）。**后台化没有改这条前置判据**：Rust 侧仍是同一口径，前端 `projectHasIconSpecReference` 仍与它逐字对齐，缺前置时对应入口**保持可点击**并给出可执行的原因与指路（仓库口径：视觉不可用但可点击说明原因，不用原生 `disabled`），原因文案包含 `assets/art-spec.png` 与「生成规范 → 图标规范」。
 - 权威规范图由工具栏自身可满足：「图标规范」入口在项目尚无权威规范图时按 `assets/art-spec.png` 落盘；已有权威规范图时**不再传 `outputPath`**（Rust 侧 `replace_existing` 固定为 `false`，指向已存在文件会被硬拒绝「outputPath 已存在，禁止静默覆盖」），改为生成一张新的普通图标规范资产。这条前端策略不扩接口。
 - 音频入口收敛：音频画布的「生成背景音乐 / 生成音效」由工具栏承载，既有「生成素材」浮层入口**只保留生成视频**（视频能力不删，只是不出现在工具栏里）。
+- 派生/修改类任务并入同一侧栏（2026-09-20）：快速编辑、生成动画、视频 / 音效 / 背景音乐与抠图这类走**资源编辑链路**的任务也进「生成任务」侧栏。数据源 = 原生资源编辑账本 `list_pending_local_project_resource_edits` + **本会话的本地提交记录**，按 `operationId` 合并去重：本地那份负责「按下提交当帧可见」，原生那份负责「重开项目、别处提交也看得见，阶段文案以后端为首」。这类任务不写图片类生成账本（`.agent/runtime/asset-generation-tasks/tasks.json`），也不改原生资源编辑账本 schema。
+- 卡片浮层同一条「提交即关」（2026-09-21）：快速编辑 / 生成动画这类挂在资源卡上的浮层只负责**把任务交出去**，点提交当帧即关面板（不等 IPC），进度、阶段与结果都在「生成任务」侧栏里跟；面板内不出现「修改中 / 生成中」这类等待态。只有**点击瞬间就失败**（名称预检、源素材不在画布上、没有客户端）留在面板里可见；**受理之后才失败**只把侧栏那条收口为失败 + 提示条，不重开面板，草稿回落成「未完成编辑」等用户重开。因此原有的「生成中的卡片浮层不参与清焦点」判据一并退役（浮层不会带着进行中的任务留在画布上）。身份跟着资源走：按「入口 + 资源路径」记住最后一次派生请求，重开面板再提交时提示词没变就沿用同一 `operationId` / 幂等键，命中同一 operation 账本；派生成成功即清掉。同一张素材仍有在途提交时，再提交会被拦下并给出原因。
 - 本轮明确不做：生成视频（保留在既有浮层入口）、宣发素材、生成游戏场景、画布级「选择工具 / 抓手工具」（AGC 现无画布级工具模式）。这五类都**不得**出现在工具栏里。
 - 本地 IPC 边界（前端只做本地收窄，不改接口）：提示词上限 `32000` 字符、素材名上限 `120` 字符、比例白名单 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`、尺寸白名单 `0.5K / 1K / 2K`。
 
@@ -364,7 +366,7 @@ type UpdateProjectResourceCanvasLayoutResult =
   1. **查找素材**：关键词，就是画布搜索本身，与筛选条件共用同一份状态，只有一个入口读写它，不得各存一份；判据沿用搜索既有的名称、路径、媒体类型、任务名四字段与大小写不敏感口径。
   2. **所在区域**：取值为「全部区域」加上现行分区栏目（`PROJECT_RESOURCE_CANVAS_SECTIONS` 的 6 类资产分类与末尾独立的「项目版本」栏），显示名沿用 `@` 面板资源筛选那份唯一中文口径，不另建译名表。
   3. **自定义标签**：从 manifest `assets[].tags` 派生的标签库，多选且为 AND 语义（已选标签必须全部命中，空选择不过滤），复用共享判据 `assetTagsMatchSelection`。
-  不提供「状态」字段：manifest 资产与资源投影都没有状态事实源，候选的任务状态与附件导入状态在资源投影里已被上游过滤，任何取值都恒为同一结果，因此不渲染该字段，也不保留占位下拉。
+     不提供「状态」字段：manifest 资产与资源投影都没有状态事实源，候选的任务状态与附件导入状态在资源投影里已被上游过滤，任何取值都恒为同一结果，因此不渲染该字段，也不保留占位下拉。
 - 「所在区域」**既是筛选维度也是画布当前栏目**，两者必须是同一份状态：区域取值由画布栏目状态派生，切换区域走与栏目切换完全相同的那一条路径，因此用户用滚轮、总览卡片或下一页切换栏目时区域显示随之变化，不需要双向同步逻辑，也不会出现两处状态互相漂移。
 - 区域取值与其它维度叠加时，筛选只作用于当前区域内的资源；「全部区域」作用于全部资源。两种语义共用同一份过滤实现，不为「只筛当前区域」另写一套裁集合逻辑。
 - 筛选浮层是画布唯一的搜索与筛选入口：Dock 上的放大镜按钮与 `Ctrl/Cmd+F` 叫出的是同一个浮层，不存在第二个浮层，因此也不存在「两个浮层互斥」这一说。
@@ -446,7 +448,7 @@ type ProjectVersionResourceReplacement = {
 - **失败即拒绝**：硬门禁任一项不等、源版本不存在、源版本未绑定该素材、替换素材未登记、替换素材与源素材相同、`expectedProjectId` / `expectedProjectRevision` CAS 冲突，都必须在写入前拒绝并说明原因；拒绝时 manifest、`versions` 与项目 revision 都不变，投影里不得出现新的版本卡或新的"当前使用"高亮。
 - **落盘与留痕**：改绑定属于 `versions` 变化，写入后推进一次 `projectRevision`；并追加一条 `asset.version_binding.replace` 审计（`versionId / sourceResourceId / replacementResourceId / projectRevision`）。**没有可回溯的替换历史**：替换前的身份只有这条审计与 manifest 的 `.previous` 恢复副本。
 - **入口与可见效果**：入口在资源卡选中工具条，只对「manifest 资产 + 被当前版本绑定」的素材放行；候选弹窗列出全部候选，命中硬门禁的项渲染但禁用并给出原因，只有尺寸规格差异的项仍可选但带提示。成功后**不切换版本**（没有新版本可切），只重读 manifest；可见变化是资源卡"当前使用"高亮移到替换素材、`@` 面板"当前版本素材"更新。按 §7.4 的口径，改绑定不做运行时资源重映射，运行画面本身不会因改绑定而变化；也不自动重载 / 重启运行中的预览（§3.2 末条）。
-- **点选替换（2026-09-13 补充）**：候选弹窗 footer 提供「点选替换」，用于"目标就在画布上、不想在面板里筛"的场景。点它**必须关闭弹窗**（弹窗外壳是全屏遮罩，留着它画布上的卡点不到）并进入画布点选态，画布上出现提示条（「在画布上点选要替换成的素材；点击空白处不会退出」+「取消」）。点中合法候选直接走**同一条**写入链路（载荷与弹窗确认逐字一致，不产生第二套替换口径），成功后自动退出点选态；点中非法目标（分类 / 类型不同、不在后端给出的权威候选里、源素材本身、未登记资源）**不写入**，在提示条上说明原因（与候选弹窗同一条翻译口径）并**留在**点选态。退出只有三条路：Esc（在 `document` 阶段截断，画布全局 Esc 的清选中不随之触发）、提示条「取消」、替换成功；**空白点击不退出、也不清画布选中**。点选态下卡片左键只用于点选（不起拖拽、不换选中，靠一次性抑制而不是全局关掉单击），滚轮平移与 `Ctrl/Cmd` 缩放照常可用。
+- **替换面板在画布上点选目标（2026-09-21；2026-09-13 的「点选替换」由此取代）**：候选面板是画布右上角的**非模态浮层**（无全屏遮罩、不做焦点陷阱，面板自身限高 + 内部滚动），面板开着的时候画布照常可点——在画布上点目标素材即把它落成**面板里的当前选择**（面板随之高亮；用户在面板里已输入的搜索与分类筛选不被重置），写入仍然只由面板「确认」发起（载荷与旧弹窗确认逐字一致，不产生第二套替换口径）。点中非法目标（分类 / 类型不同、不在后端给出的权威候选里、源素材本身、未登记资源）**不写入**，在面板里说明原因（同一条翻译口径）并保留原选择。退出只有两条路：面板「取消」/ 头部 ×、Esc（在 `document` 阶段截断，画布全局 Esc 的清选中不随之触发）；替换成功即关闭面板。面板开着时卡片左键只用于点选（不起拖拽、不换画布选中，靠一次性抑制而不是全局关掉单击），滚轮平移、`Ctrl/Cmd` 缩放与空白处框选照常可用。
 - **替换血缘标注（2026-09-13 补充）**：替换成功后只改绑定、光环本来就会从源素材移到替换素材，光靠光环说明不了"谁换成了谁"，所以在卡面补一层**关系标注**：源素材卡标「已被 <替换素材显示名> 替换」，替换素材卡标「替换自 <源素材显示名>」，两处分别给出稳定 DOM 判据 `data-resource-replaced-by` / `data-resource-replacement-of`，值是对面资源的 **manifest 资产 id**（不是显示名）。这份关系是**宿主会话内状态**：同一会话里再次替换**整条覆盖**上一条（只保留当前有效的一条 A→B，不做历史链，与 §7.8「只展示当前有效关系」同口径）；**切换项目 / 关闭工作台 / 重新加载 manifest 都不保留**——客户端没有替换关系的读侧事实源（写入结果只回 `versionId` / `committedProjectRevision`，审计 `asset.version_binding.replace` 只有写侧），manifest 的 `.previous` 只是原子安装的崩溃兜底副本、安装成功即删，不能当数据源，所以本标注**只在本次会话有效，不假装持久**。
 
 ### 5.4 游戏迭代版本（P1）
@@ -655,7 +657,7 @@ type ProjectAgentMudPointAttribution = {
 5. 硬门禁任一为 false、源版本不存在、源版本未绑定该素材、替换素材未登记、替换素材与源素材相同、`expectedProjectId` / `expectedProjectRevision` 冲突，都必须在写入前拒绝；拒绝时 manifest、`versions` 与项目 revision 都不变，投影里不得出现新的"当前使用"高亮或版本卡变化。
 6. 成功后重读 manifest 并**不切换版本**（没有新版本可切）；**不**自动重载或重启运行中的预览（§3.2 末条），也不做运行时资源重映射。可见变化只有：资源卡"当前使用"高亮移到替换素材、`@` 面板"当前版本素材"更新。
 7. 替换成功后追加一条 `asset.version_binding.replace` 审计（`versionId / sourceResourceId / replacementResourceId / projectRevision`）；**替换历史不可回溯**——替换前身份只有这条审计与 manifest 的 `.previous` 副本，不得声称能查到"某版本历史上换过什么"。
-8. 候选弹窗提供「点选替换」（2026-09-13）：点它关闭弹窗进入画布点选态，并把「在画布上点选要替换成的素材；点击空白处不会退出」与「取消」放在画布提示条上；点中合法候选按第 3~7 条**同一条**链路提交并自动退出点选态，点中非法目标（分类 / 类型不同、不在权威候选里、源素材本身、未登记资源）零写入、留在点选态并在提示条上说明原因。退出只有 Esc（`document` 阶段截断，不清画布选中）/ 提示条「取消」/ 替换成功三条路，空白点击不退出；点选态下滚轮平移与缩放照常，卡片单击的既有语义在非点选态下不变。
+8. 替换面板在画布上点选目标（2026-09-21；取代 2026-09-13 的「点选替换」）：候选面板是非模态浮层，面板开着时画布保持可点，点画布上的候选即落进面板的当前选择（搜索与分类筛选不被重置），写入仍由面板「确认」按第 3~7 条**同一条**链路发起；点中非法目标（分类 / 类型不同、不在权威候选里、源素材本身、未登记资源）零写入并在面板里说明原因。退出只有面板「取消」/ × 与 Esc（`document` 阶段截断，不清画布选中）两条路，成功后自动关闭；面板开着时滚轮平移、缩放与空白框选照常，卡片单击的既有语义在面板关闭后不变。
 9. 替换血缘标注（2026-09-13）：替换成功后，源素材卡带「已被 <替换素材显示名> 替换」、替换素材卡带「替换自 <源素材显示名>」，稳定 DOM 判据 `data-resource-replaced-by` / `data-resource-replacement-of` 的值为对面资源的 manifest 资产 id；未参与替换的资源卡两个属性都不出现。同一会话内再次替换时**只保留当前有效的一条 A→B**（旧标注从卡上消失，不做历史链）。这份标注**只在本次会话有效**：切换项目 / 关闭工作台 / 重新加载 manifest 都不保留，也不得声称可回溯（第 7 条仍成立）。
 
 ### 7.9 P1 功能画布底部工具栏验收
@@ -665,9 +667,10 @@ type ProjectAgentMudPointAttribution = {
 3. 每个图片类入口一次提交**一条** `start_local_project_asset_generation`，载荷字段逐字为 `{ projectPath, projectId, taskId, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`——**原同步命令的生成载荷字段名与取值口径逐字不变**（`kind / prompt / aspectRatio / imageSize / assetName / outputPath` 全部原样搬过来），只多了任务身份 `projectId` 与前端每次提交新铸的本地 `taskId`；`kind` 映射：生成图片 `image`、生成角色形象 `character`、图标规范 `icon-spec`、角色规范 / 自定义规范 `spec`、生成图标素材 `art-spritesheet`、生成 UI 设计图 `ui-prototype`。命令**提交即返回**一条任务记录，生成在 Rust 后台任务里跑，状态与阶段由 `list_local_project_asset_generations` 从项目内账本读回。
 4. 比例 / 尺寸选项**不含**本地通道拒绝的 `4:3`；比例与尺寸的切换都进入载荷；固定档规范入口只读展示当前规格（如 `1:1·1K`），不渲染可点比例控件。
 5. 缺权威规范图时「生成图标素材 / 生成 UI 设计图」保持可点击、给出含 `assets/art-spec.png` 的原因说明，且**不发出任何生成请求**；「图标规范」此时把 `outputPath` 指向 `assets/art-spec.png`；项目已有权威规范图时 `outputPath` 为 `null`（两种状态各一条用例）。
-6. 生成 / 上传成功后走既有刷新路径：`get_local_game_project_revision` + `get_local_game_manifest` 的配对读发生在**该任务收口之后**（提交命令不再等待生成，配对读由任务终态驱动，顺序仍在写入之后），结果交给 `onManifestChange`；音频入口提交的是 `derive_local_project_resource`（`editKind` = `sound-effect` / `background-music`、`generationMode: 'create'`、`sourceMediaType: 'audio/mpeg'`）。
+6. 生成 / 上传成功后走既有刷新路径：`get_local_game_project_revision` + `get_local_game_manifest` 的配对读发生在**该任务收口之后**（提交命令不再等待生成，配对读由任务终态驱动，顺序仍在写入之后），结果交给 `onManifestChange`；音频入口提交同一条命令的音频载荷（`kind` = `sound-effect` / `background-music`、`idempotencyKey` = 该次生成的幂等键、任务 id 即该次生成的 operation id）；原生命令内部仍复用既有音频无源生成链路（`editKind` = `sound-effect` / `background-music`、`generationMode: 'create'`、源快照媒体类型由 `editKind` 推为 `audio/mpeg`），不新增平台路由、请求体或计费口径。
 7. 既有「生成素材」浮层入口只呈现视频：面板不再渲染音效 / 背景音乐类型选择器（单类型入口没有类型选择器），音频入口只出现在音频栏目工具栏。
-8. 生成期间可退出与本地排队（2026-09-14）：提交后点 × / 遮罩 / Esc /「后台运行并关闭」任一都能关面板，画布立即恢复可交互，关闭不取消请求；面板关闭后任务仍在「生成任务」面板（非模态浮层，无 `aria-modal`）里显示后端 `phaseDetail`；第一条未终态时提交第二条 → 第二条显示「排队中。」且生成提交 IPC 次数仍为 1，第一条终态后自动补发（次数为 2）；两条各自完成后各走一次「配对读 + 落卡」，manifest revision 单调、不被后到者覆盖。
+8. 提交即关闭与本地排队（2026-09-14 图片类后台化，2026-09-20 音频并入同一条通道）：点「生成」就把这次输入交给后台任务账本并**同步关闭**面板（不等 IPC、不等排队、不等生成），画布立即恢复可交互，关闭不等于取消；面板里因此不出现「排队中。」「正在生成。」「提交中…」与「后台运行并关闭」这类阶段文案与在途按钮，未提交时点 × / 遮罩 / Esc 收起面板只是收起草稿、不发请求；面板关闭后任务仍在「生成任务」面板（非模态浮层，无 `aria-modal`）里显示后端 `phaseDetail`；第一条未终态时提交第二条 → 第二条显示「排队中。」且生成提交 IPC 次数仍为 1，第一条终态后自动补发（次数为 2）；两条各自完成后各走一次「配对读 + 落卡」，manifest revision 单调、不被后到者覆盖。
+9. 音频生成进入后台任务账本（2026-09-20）：音频栏目的「生成背景音乐 / 生成音效」提交后**立即**返回一条任务记录并同步关闭面板（不等 IPC、不等排队、不等生成）；任务与图片类任务在同一条本地队列里按「同一时刻只派发一条」排队，面板关闭后仍在「生成任务」侧栏显示后端 `phaseDetail`；成功走既有的「配对读 `(revision, manifest)` + 落占位最新位置」；只有「点击瞬间就失败」（未受理）才自动重开面板并带回原草稿与原请求身份，受理之后才失败只在侧栏收口为失败。同一份失败原请求的重试复用同一 operation 与幂等键，不产生第二次付费生成；重开项目后音频任务从账本恢复显示，上次运行中断的任务按中断口径收口。
 
 ## 8. 非目标
 

docs/project-memory/plans/【实施计划】AGC音频生成进入后台任务账本-2026-09-20.md

@@ -0,0 +1,51 @@
+# 【实施计划】AGC 音频生成进入后台任务账本
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC音频生成进入后台任务账本-2026-09-20.md` |
+| Status | implemented-awaiting-runtime-acceptance |
+| Owner | 主 Agent（自审；本运行没有独立评审人） |
+
+## 修改边界
+
+- 允许修改：
+  - 主规范：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`。
+  - AGC 原生：`apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`、`commands.rs`、`project.rs`、`project/resource_editor.rs`（仅新增收口入口，不改既有派生语义）。
+  - AGC 前端：`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`、`resourceCanvasAssetGenerationQueue.ts`、`view/project-development/index.tsx`。
+  - 定向测试：`apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx`、`resourceCanvasAssetGenerationQueue.test.ts`、`appSurface/project-development.suite.ts`（仅音频相关断言）。
+- 明确不修改：`/api/editor/audios/*/generations` 与 `/api/external/v1` 路由、请求体、OpenAPI、共享 DTO、SpacetimeDB schema、权限命令词汇、`derive_local_project_resource` 的同步语义与其既有无源生成入参校验。
+
+## 实现顺序
+
+1. 主规范：把音频入口的接线口径从「同步无源生成」改写为「与图片类同一条后台任务账本」，并补上音频提交载荷、失败重开与幂等条款（PRD §3.10 / §7.9，AGC 工具栏入口矩阵文档）。
+2. 原生：在资源编辑模块新增音频入参收口与「后台跑一次音频派生」的入口（复用既有派生实现，不复制生成逻辑）；在 `asset_generation_tasks` 里按 `kind` 分流，音频任务复用同一份账本、同一套阶段文案与中断收口；`start_local_project_asset_generation` 增加可选幂等键入参，音频 kind 走新分支且不改图片类载荷口径。
+3. 原生测试：音频任务入参收口（kind / 提示词上限 / 幂等键 / 未知 kind 拒绝）、账本记录 kind 为音频、图像载荷口径不回归。
+4. 前端模型与队列：任务模型支持音频任务（kind、请求身份、无比例 / 尺寸 / 参考字段），音频 kind 的入口文案从工具栏模型派生；队列按 kind 分流派发同一命令的音频载荷，其余排队与轮询语义不变。
+5. 前端宿主：音频提交改为「入队即返回」，占位绑定任务 id、自动展开侧栏、给出提示条；收口复用既有「配对读 + 落卡」链路，未受理失败按原请求身份重开音频面板。
+6. 前端测试：宿主生命周期（提交即关闭、侧栏可见、落卡、未受理失败重开并复用身份）、队列音频分支（载荷与轮询、第二条本地排队不发 IPC）、appSurface 音频载荷。
+7. 验证与证据矩阵：跑定向测试、类型检查、编码 / 文档索引 / `git diff --check`，按里程碑逐条填写证据。
+
+## 验证命令
+
+1. `npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationQueue.test.ts apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx`
+2. `npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`
+3. `cargo test -p genarrative-ai-game-creator-shell asset_generation_task`
+4. `npm run agc:typecheck`（或 `npm run typecheck --workspace @genarrative/ai-game-creator-shell`）
+5. `npm run check:encoding && npm run check:doc-index && git diff --check`
+
+## 执行结果
+
+1. 主规范：PRD（§3.10 / §7.9 / §7.9 第 8~9 条）与 AGC 工具栏入口矩阵文档改为「音频与图片类同一条后台任务账本」，同步 `【测试用例】AGC资源工作台V3端到端验收` 的 S11a 判据。
+2. 原生：`prepare_local_project_audio_generation`（提交期收口）+ `run_local_project_audio_generation_at`（派发时刻读 revision，复用派生实现），`start_local_project_asset_generation` 新增可选 `idempotencyKey` 并在音频 kind 分支落同一份账本、由 `run_local_project_audio_generation_task` 写 running → completed / failed；图片类分支逐字未改。
+3. 前端：任务模型新增音频任务与 `idempotencyKey`（恢复出来的历史任务不带它，也不承接重试）；队列按 kind 分流派发载荷；面板提交改为同步返回并立即关闭；宿主改为同步入队 + 失败重开。
+4. 测试：面板（点击即关闭、无阶段文案与在途按钮）、队列（音频载荷逐字）、宿主生命周期（提交关闭 / 侧栏 / 落卡 / 未受理重开 / 受理后不重开 / 重试身份复用 / 失败态按占位隔离）、appSurface 音频载荷。
+5. 验证命令与结果：9 个定向 vitest 文件 73 项通过；`appSurface.test.ts` 552 项通过（17 项跳过）；`cargo test asset_generation_task` 14 项通过；`npm run agc:typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
+6. 与预期不一致处：音频任务不再携带 `targetCategory`（原生音频通道不消费它，前端也没有读它的地方）；`restored` 任务无幂等键，只用于展示与定位，不承接重试。
+7. 已知与本任务无关的既有失败：`clientAuthStorage` / `clientApi` / `clientHttp` / `chatPromptPolish` / `projectCreationDirectory` 五个文件在本机 Node v26 + vitest 0.34 的 jsdom 下 `localStorage` 为 undefined（在干净工作区同样失败）；`cargo test resource_edit` 整组过滤下有 5 项既有并行干扰失败（单跑通过）。
+
+## 风险与回滚点
+
+- 音频任务与图片类任务共用队列：若音频任务未终态会挡住后续派发（本地排队是既有语义，接受）。回滚点是前端提交分支与原生 `kind` 分流，各自可独立回退。
+- 音频自带的 operation 幂等账本与任务账本是两层身份：任务 id 取 operation id，重试复用同一对 operation / 幂等键；不得为「省事」在重试时换新的请求身份（那是一次新的付费生成）。
+- 账本 `kind` 为音频时，`restore` 的入口文案若查不到工具栏模型会退化成素材名：入口文案必须由工具栏模型派生，避免恢复后文案漂移。
+- 后台跑生成会让「项目 revision CAS」窗口从提交前移到派发时刻：冲突时按失败收口（不静默重试），避免把生成写到非预期基线。

docs/project-memory/plans/【实施计划】DirectProject聊天真相源收敛-2026-09-16.md

@@ -28,8 +28,8 @@
 
 1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_thread -- --nocapture`
 2. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 `src/features/project-workspace/generated/`），随后用 `prettier --write` 格式化生成目录，避免未格式化的 ts-rs 输出混进提交
-3. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts`
-4. `npx vitest run apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`
+3. `npm run test -- apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts apps/ai-game-creator-shell/tests/directHistoryAnchorGate.test.ts`
+4. `npm run test -- apps/ai-game-creator-shell/tests/appSurface.test.ts`（`project-development.suite.ts` 由该入口注册，不能作为独立测试入口；同时验证现役 Design Agent 的会话恢复与审批界面。）
 5. TypeScript 类型检查与 ESLint（范围同前次 DirectProject 迁移）。
 6. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
 

docs/project-memory/plans/【实施计划】Mac本机构建节点接入-2026-09-18.md

@@ -0,0 +1,14 @@
+# Mac 本机构建节点接入实施计划
+
+- Version: 1
+- Status: preparing-network-required
+- Date: 2026-09-18
+- Parent Spec: `【里程碑】Mac本机构建节点接入-2026-09-18.md`
+
+1. 本地准备 universal 依赖预备、CI 打包脚本和 Jenkinsfile，运行离线单测、配置门禁及编码检查。
+2. 恢复内网后只读核对 Jenkins 版本、既有节点/Job、Git 凭据标识与插件；已存在对象优先核对，不重复创建。
+3. 从同一控制器取得 agent.jar，以当前已有 Java 21 运行专用 inbound Agent；secret 保存在用户私有目录，LaunchAgent 参数只引用 secret 文件，不保存控制器 API Token。
+4. 建立单 executor、EXCLUSIVE 的专用 Mac 节点与手动 archive-only Job。源码必须是可追溯 Git 提交，未推送改动需另行确认源码交付方式，不能默认推送。
+5. 初次构建核对独立工作目录、空间、目标与依赖；在 Jenkins 实际 SUCCESS 后确认 DMG、SHA-256 和两架构 smoke 证据。
+
+失败边界：网络不可达不启动重试服务；节点/Job 修改前保留原配置；不更改其它节点、Job 或调度。禁止把 CLI 日志、认证文件和私有路径提交 Git。未获得真实 SUCCESS 前保留活动计划。

docs/project-memory/plans/【实施计划】Mac通用安装包-2026-09-18.md

@@ -0,0 +1,16 @@
+# Mac 通用安装包实施计划
+
+- Version: 1
+- Status: awaiting-user-acceptance
+- Date: 2026-09-18
+- Parent Spec: `【里程碑】Mac通用安装包与构建管线-2026-09-18.md`
+
+1. 等待当前 Intel 编译结束，避免共用 staging 并发写。
+2. macOS build.rs 按白名单分别 stage 两套原生资源；共享 Layout 使用架构子目录，运行时原有 hash/版本校验不变。
+3. Tauri macOS 映射双目录，发布入口接受 universal 并生成两个清单键；更新配置门禁与定向测试。
+4. 安装包 smoke 支持显式选择主程序切片，验证 universal 主程序与该切片对应原生依赖。
+5. 用 Tauri universal 构建 app，分别做 arm64/Rosetta smoke，hdiutil 生成新 universal DMG，校验并交付。
+
+不发布、不使用私钥；依赖仅从锁定 npm tarball 下载并对照 lockfile integrity。磁盘不足停止，不擅自删除其它 target/cache。保留单架构 DMG。Jenkins 配置作为后续门禁，不混入本地包构建。
+
+本地构建与双架构隔离验证完成，证据见对应里程碑。更新 master 时先停止旧构建，保护并恢复改动后重建；未进行 Jenkins 写操作，待确认 Mac Agent 再制定管线实施计划。

docs/project-memory/plans/【实施计划】策划Agent回合模型选择生效-2026-09-20.md

@@ -0,0 +1,45 @@
+# 策划 Agent 回合模型选择生效实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [回合模型选择生效里程碑](./【里程碑】策划Agent回合模型选择生效-2026-09-20.md) |
+| Status | implemented（待验收） |
+| Owner | 当前任务 Agent |
+
+## 修改边界与顺序
+
+1. 在本地 `DesignTurn` 中追加可缺省的模型/推理档选择快照，仅存两个非敏感字段。现有 UI 只投影会话摘要，无需扩展前端 DTO。
+2. 策划普通发送、澄清回答、用户重试和批准阶段实际开始执行时，从现有配置加载结果获取全局模型和推理档，覆盖上一轮选择；重复命令、拒绝审批和纯读取不重新采样。
+3. Provider 请求使用当前回合快照，工具循环与自动重试期间不随全局选择变化。保留其它连接配置的原解析，策划专属配置不能覆盖这两个用户选择字段。
+4. 自动恢复沿用活动回合快照；旧记录缺快照时保留已有会话模型，并从当前全局配置补推理档，再由原检查点保存。保持工具幂等和审批流程。
+5. 补充既有 Rust 测试，验证请求字段、新旧会话、重试、审批/澄清和恢复；更新主规范与稳定项目记忆。
+
+## 非目标
+
+不改两个前端控件、GameAgent、模型目录、默认值、供应商适配；不新增模型可用性检查、自动换模型或提交门禁。不保存凭据或完整配置，不引入通用快照框架。
+
+## 验证
+
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml design_runtime::tests -- --test-threads=1`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml design_session -- --test-threads=1`
+- 改动文件 Rust 格式检查；文档索引、编码检查和 `git diff --check`。
+- 优先本地 HTTP fixture 核对发送给 Provider 的模型与推理档，真实 Provider 未运行时明确记录。
+
+## 风险与回滚
+
+模型选择快照必须在首个副作用前持久化，配置读取失败不能改变既有持久状态；旧记录自动恢复不推断历史推理档。新增可缺省字段支持现有会话读取，回滚不删除会话或产物。
+
+时间盒：先完成最小采样/请求闭环和定向测试，再核对恢复与文档。仅在影响本里程碑判据时扩大范围。
+
+## 验证记录
+
+| 验证 | 结果 |
+| --- | --- |
+| 改动文件 Rust 格式检查、diff 检查 | 通过 |
+| 文档索引、编码检查 | 通过 |
+| Rust 定向测试 | 已尝试编译，未执行测试用例；不记为通过 |
+| 本地 HTTP fixture | 已补充真实请求字段断言，尚未执行 |
+| 桌面/真实 Provider smoke | 未运行 |
+| 独立静态审查 | 已检查采样入口、重放/恢复边界、请求循环和测试辅助函数可见性，无可操作发现 |
+
+新增用例验证回合快照与旧数据读取，以及普通消息、跨工具请求、澄清回答、用户重试、审批批准、重复审批的配置生效边界。已有恢复用例继续覆盖不确定文件操作不重复执行。控件和 GameAgent 无本步修改。

docs/project-memory/plans/【实施计划】策划Agent模型与推理档控件接入-2026-09-20.md

@@ -0,0 +1,49 @@
+# 策划 Agent 模型与推理档控件接入实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [控件接入里程碑](./【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) |
+| Status | accepted |
+| Owner | 当前任务 Agent |
+
+## 修改边界
+
+- 在 `ProjectSupervisorView.tsx` 扩展既有控件排的适用范围，直接复用 `ConversationModelSelect` 与 `ComposerReasoningEffortSelect`。素材引用、语音、消息队列和停止按钮仍按原 GameAgent 条件显示。
+- 策划发送、澄清、审批和重试回调保持原样，不新增模型校验和提交门禁；GameAgent 的原校验保持不变。
+- 必要时局部调整策划宿主 CSS，避免控件换行或弹层裁切。组件内部逻辑保持不变。
+- 在现有前端测试体系补齐策划集成场景，回归已有 GameAgent 控件用例。
+- 不修改 Rust、模型生效逻辑、配置默认值、Provider 或 GameAgent 组件算法。
+
+## 实现顺序
+
+1. 核对共享对话容器，接入同一组控件，保留原提交路径。
+2. 补充策划控件读写、保存失败和忙态测试，回归原策划和 GameAgent 行为。
+3. 运行定向测试和类型检查，检查宽窄布局，回写证据与未验证项。
+
+## 验证命令
+
+- `npm test -- apps/ai-game-creator-shell/tests/appSurface.test.ts`，先按用例名称过滤控件及相关策划场景。
+- 策划宿主集成用例使用现有 Vitest / Testing Library，按实际测试文件定向运行。
+- `npm run ai-game-creator-shell:typecheck`
+- `npm run check:doc-index`
+- `npm run check:encoding`
+- `git diff --check`
+
+## 风险与回滚点
+
+- 防止扩大 `directCodex` 条件时带入语音、队列或改变 GameAgent 行为：仅共享控件排，保留其它分支。
+- 模型目录失败通过原选择器反馈，不给策划宿主增加前置检查，也不改造控件已有逻辑。
+- 本次回滚仅撤回前端接入、相关用例和文档，不涉及持久化数据迁移。
+- 时间盒：一个工作时段内先完成接入与定向测试，随后检查类型和布局；仅影响里程碑验收的发现纳入修复。
+- 当前已知限制：策划旧会话仍可能使用创建时模型；本次不将控件读写成功视为运行时已切换模型。
+
+## 验收证据
+
+| 项目 | 结果 |
+| --- | --- |
+| 源码边界核对 | 两个控件文件、策划动作回调、GameAgent 提交校验及 Rust 均无修改；仅扩展控件排适用条件与策划布局 |
+| 定向 ESLint | `ProjectSupervisorView.tsx`、`design-agent.suite.ts`、`harness.ts` 通过 |
+
+定向测试命令：`npm test -- apps/ai-game-creator-shell/tests/appSurface.test.ts -t 'Design Agent|design session|clarification free text|reasoning effort control|selecting the model|model dropdown|chat composer an inset|current turn reasoning|historical reasoning'`。
+
+用户已授权提交第一步、进入第二步。

docs/project-memory/plans/【实施计划】退役策划Agent V1V2解耦清理-2026-09-15.md

@@ -0,0 +1,92 @@
+# 【实施计划】退役策划 Agent V1/V2 解耦清理
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】退役策划Agent V1V2解耦清理-2026-09-15.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 一句话交付结果
+
+删除退役策划 V1/V2 及其耦合的 Supervisor 产品残留，让当前 Design Agent 独立运行、做游戏走 DirectCodex 并恢复仓库编译；保留通用 Supervisor 和做游戏 16 Agent DAG。
+
+## 验收判据
+
+当前分支能够通过 AGC 前端 typecheck 和受影响定向测试；Design Agent 的新建、恢复、澄清、阶段审批和 reasoning 展示仍由当前 Design Agent 链路完成；旧 V2 IPC、旧 GDD 类型和旧前端测试契约不再存在。
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src/App.tsx` 中旧 V2 状态、helper、IPC 分支和旧 UI props。
+- `apps/ai-game-creator-shell/src/app/types.ts` 中旧 GDD 类型。
+- `apps/ai-game-creator-shell/src/features/project-workspace/planningSessionV2.ts` 及其直接调用方。
+- `apps/ai-game-creator-shell/tests/appSurface/harness.ts`、`home.suite.ts`、旧策划事件测试。
+- `apps/ai-game-creator-shell/src/styles.css` 中只属于旧 Plan GDD / planning lane 的样式。
+- 没有现役调用方的旧策划身份 fixture、注释和文档索引。
+- 为通过编译所需的最小共享残留删除或改名。
+
+明确不修改：
+
+- `directCodex` 主链路和当前 Design Agent。
+- 16 Agent DAG、`supervisor-swarm` 测试和通用 Runtime 编排；只处理删除策划耦合后直接造成的编译错误。
+- 当前 Design Agent Rust runtime、Design Agent 资源包和 Design Agent IPC 协议。
+- 公开 API、SpacetimeDB schema、迁移和历史持久化数据格式。
+
+## 实现顺序与提交拆分
+
+### 提交一：解耦 Design Agent 状态命名
+
+- 将新版 Design Agent 实际使用的 `planningV2*` transient reply、reasoning、active ref 和相关 lane 控制改成 Design Agent 专属状态。
+- 保持行为不变，不删除旧 V2 会话代码。
+- 验证：AGC typecheck、`git diff --check`。
+
+### 提交二：删除 App 旧 V2 会话控制流
+
+- 删除仅服务旧策划的 Supervisor 产品入口、恢复、轮询和聊天提交分支。
+- 删除旧 V2 session/GDD 状态和 helper。
+- 删除项目打开、消息发送、问询回答、审批和旧流式事件分支。
+- 将“做方案”只连接到当前 Design Agent hydrate/continue/decide 路径，将“做游戏/做素材”只连接到 DirectCodex。
+- 保留 `planningStartMode` 作为入口路由字段，避免无关扩大重命名。
+- 验证：AGC typecheck；必要时运行 App 启动相关定向 suite。
+
+### 提交三：删除旧 TypeScript 适配层和类型
+
+- 删除 `planningSessionV2.ts`。
+- 删除 `PlanGddDecisionAction`、`PlanGddStateViewV1` 及所有直接导入。
+- 重新执行旧符号检索，确认没有残留调用方。
+- 验证：AGC typecheck、`npm run check:encoding`、`git diff --check`。
+
+### 提交四：清理测试、事件契约和 CSS
+
+- 精确删除 harness 中旧 V2/GDD 工厂、mock、调用记录和导出。
+- 精确删除首页 suite 中旧 V2 IPC 断言。
+- 删除旧 `planning-session-v2-stream` 事件测试。
+- 删除 Plan GDD、GDD 审批卡和 planning lane 专属 CSS 及过时说明。
+- 验证：appSurface 定向测试、事件订阅定向测试、AGC typecheck、编码和 diff 检查。
+
+### 提交五：收口确定失效的身份残留和文档入口
+
+- 只处理因 V1/V2 退役而确定失效的旧身份展示、测试 fixture、注释和文档索引。
+- 不扫描或重构做游戏 DAG；共享代码只在其旧策划用途已确定死且删除能直接解决编译/测试问题时处理。
+- 验证：旧策划符号定向检索、相关测试、编码和 diff 检查。
+
+## 验证命令
+
+1. `npm --prefix apps/ai-game-creator-shell run typecheck`
+2. `npm run check:encoding`
+3. `git diff --check`
+4. `npm --prefix apps/ai-game-creator-shell exec vitest run tests/appSurface.test.ts`
+5. 受影响 Rust 文件变化后运行 `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
+6. 完成全部提交后再次执行旧策划符号检索，并核对 `git status` 与提交边界
+
+## 风险与回滚点
+
+- 最大风险是新版 Design Agent 复用了旧变量名；必须先完成提交一，再删除旧 helper。
+- `ProjectSupervisorView` 已经移除旧 GDD props，App 传参残留会在提交二中一并删除。
+- 测试 harness 同时服务通用总控和 Design Agent，必须局部删除旧 mock，不能整段重写。
+- 若某次提交导致 Design Agent 测试失败，只回滚该独立提交，不恢复旧 V2 兼容层。
+
+## 完成后的临时文档处理
+
+全部里程碑验收通过后，删除本里程碑和实施计划两份临时文档；把仍然有效的长期边界同步回现行 Design Agent 技术方案和项目记忆，不保留阶段性提交步骤。

docs/project-memory/plans/【实施计划】退役策划V2 Rust Runtime清理-2026-09-14.md

@@ -0,0 +1,21 @@
+# 关联里程碑
+
+`【里程碑】退役策划V2 Rust Runtime清理-2026-09-14.md`
+
+# 修改顺序
+
+1. 从 `runtime_protocol.rs` 移除 V2 模块声明与导出。
+2. 从 `main.rs` / `commands.rs` 移除 V2 command 注册和仅供 V2 的导入。
+3. 删除 V2 Rust 模块及其专属单元测试；保留共享 GDD 模型或新版设计会话仍使用的类型。
+4. 用 `rg` 检查 V2 Rust 符号残留，修复编译引用。
+
+# 验证命令
+
+- `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
+- `npm run check:encoding`
+- `git diff --check`
+
+# 风险与回滚
+
+- 风险：V2 类型可能被共享测试或前端桥接代码引用。处理方式是按编译错误逐项判断，保留真正共享类型。
+- 回滚：按提交粒度回退本里程碑提交，不触碰前序 V1 清理提交。

docs/project-memory/plans/【实施计划】项目自动上传与后台工程下载-2026-09-19.md

@@ -0,0 +1,32 @@
+# 项目自动上传与后台工程下载实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md` |
+| Status | implemented-awaiting-runtime-validation |
+| Owner | 当前任务 Agent |
+
+## 修改边界
+
+- 客户端 project_snapshot 与实际窗口生命周期、相关定向测试。
+- shared-contracts 快照清单及后台 DTO、platform-oss 的受控清单枚举、api-server 管理员列表与 ZIP 下载、后台权限映射。
+- api-server 快照存储配置解析：默认目标与素材 bucket 分离，只有凭据可回退；不变更部署配置或搬迁对象。
+- admin-web 项目列表、现有路由/导航/API client 与相应测试。
+- 主规范、运维说明及必要共享约定。不修改 SpacetimeDB、External API、用户会话权威或线上配置。
+
+## 实现顺序
+
+1. 评审主规范与本里程碑，复现客户端项目枚举故障。
+2. 并行实现后台列表/ZIP、后台 UI；客户端只修已证实上传缺陷并补清单元数据。
+3. 集成契约、运行定向测试和 UI smoke，核查真实清单可还原目录；按证据更新验收状态。
+
+## 验证命令
+
+- `cargo test --locked -p platform-oss`、`cargo test --locked -p api-server project_snapshot`、`cargo test --locked -p shared-contracts`（server-rs）。
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot`。
+- `npm run admin-web:typecheck`、`npm run admin-web:build`、后台相关 Vitest。
+- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+## 风险与回滚
+
+旧清单无完整性声明，只能标记未知；完整工程含项目源码、素材和配置，排除依赖/构建缓存、凭据、会话与运行日志。下载失败不修改 OSS 或清单。本轮按用户授权提交推送，不部署；代码可独立回退。

docs/project-memory/plans/【里程碑】AGC macOS渠道更新落地-2026-09-17.md

@@ -3,7 +3,7 @@
 | 字段        | 值                                                                 |
 | ----------- | ------------------------------------------------------------------ |
 | Version     | 1.0                                                                |
-| Status      | deferred                                                           |
+| Status      | in-progress                                                           |
 | Date        | 2026-09-17                                                         |
 | Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |
 
@@ -30,7 +30,9 @@
 - macOS 签名证书与公证凭据可用；若不满足，本里程碑只能交付构建与清单能力，并明确标注未验证项。
 - macOS 通用包所需的双架构工具链（两个 darwin 目标）在构建机上可用。
 
-本里程碑暂缓执行：macOS 构建机与签名 / 公证凭据尚未就绪，改由后续独立变更承接；暂缓期间 dev-mac 渠道不发布。
+构建与发布能力已落地：专用 macOS Jenkins 节点（label `genarrative-agc-macos`）+ `Jenkinsfile.ai-game-creator-shell-macos-build` + `scripts/build-macos-ci.mjs` 负责 universal 构建、双架构隔离 smoke、universal DMG、渠道清单 `latest.json`、更新包验签门禁与 OSS 上传（`AGC_RELEASE_DRY_RUN` 默认开启）。
+
+仍未就绪：Apple 代码签名与公证凭据（产物保持未签名 + 未公证，构建清单显式记录 `appleSigned=false` / `notarized=false`，首装需手动放行 Gatekeeper）；「安装 → 重启接管新版本」的实机更新闭环、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）尚未验收。
 
 ## 验收标准
 

docs/project-memory/plans/【里程碑】AGC总版本号落地-2026-09-20.md

@@ -0,0 +1,37 @@
+# 里程碑：AGC 总版本号落地
+
+状态：进行中（主规范已定稿，代码与 CI 已实现，等待首次真实统一构建验收）
+
+## 关联文档
+
+- 主规范：`docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md`
+
+## 交付物
+
+1. 发号模块与入口：`agc-global-version.mjs`、`issue-global-version.mjs`、`agc-global-version.test.mjs`。
+2. 构建侧改动：`build-release.mjs` 的 `prepareReleaseVersion()` 采用总号，高水位降级为断言。
+3. CI：发号 Job（`Jenkinsfile.agc-global-version-issue` + job config）、调度管线与手动管线接入发号 Job。
+4. 文档与项目记忆更新。
+
+## 实现顺序与门禁
+
+| 步骤 | 内容 | 门禁 |
+| --- | --- | --- |
+| 1 | 发号模块 + 单元测试 | `node --test apps/ai-game-creator-shell/scripts/agc-global-version.test.mjs` 全绿 |
+| 2 | 构建侧接入总号与断言 | `build-release.test.mjs` / `release-oss.test.mjs` / `cargo-features.test.mjs` 全绿 |
+| 3 | 发号 Job 与管线接入 | `npm run check:production-ops`、`npm run check:encoding` 通过 |
+| 4 | 一次性播种 | 发号 Job 勾选 `SEED_ONLY` 写入基线，回读一致 |
+| 5 | 首次统一构建 | dev-win 与 dev-mac 清单版本相同且等于总号 |
+| 6 | 单渠道热修回归 | 只有该渠道清单变化，总号 +1 |
+
+## 当前证据
+
+- `agc-global-version.test.mjs`：7/7 通过（播种基线、首发、递增、dry-run 不烧号、回退断言、并发写后回读失败关闭、patch 递增）。
+- AGC 相关脚本合跑：32/32 通过。
+- 真实 OSS 只读预览：`--dry-run --channel unified` 输出 `AGC_GLOBAL_VERSION=0.1.77`（基线 0.1.76，未写回）。
+- `npm run check:production-ops`、`npm run check:encoding` 通过。
+
+## 未完成项
+
+- 首次真实播种与统一构建尚未执行（避免在功能未合并前烧号）。
+- `feat/jenkins-mac-build` 分支上的 macOS 管线仍用旧的自增高水位逻辑；该分支合并 master 后才继承本方案的模块与断言，合并前 dev-mac 必须由发号 Job 显式传入 `AGC_RELEASE_VERSION`。

docs/project-memory/plans/【里程碑】AGC音频生成进入后台任务账本-2026-09-20.md

@@ -0,0 +1,51 @@
+# 【里程碑】AGC 音频生成进入后台任务账本
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented-awaiting-runtime-acceptance |
+| Date | 2026-09-20 |
+| Parent Spec | `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md` |
+
+## 目标
+
+AGC 功能画布音频栏目的「生成背景音乐 / 生成音效」与图片类生成走**同一条后台生成任务账本**：提交即返回任务记录、生成在客户端后台跑、状态与阶段文案由账本提供，任务出现在画布「生成任务」侧栏里，重开项目后仍能看到并按中断口径收口。
+
+## 范围
+
+- 音频无源生成（`create`）的提交、排队、状态读回、成功落卡、失败收口与重试幂等。
+- 音频任务与图片类任务共用同一份项目内任务账本、同一个前端本地排队与同一个「生成任务」侧栏。
+- 音频任务的阶段文案、状态与耗时来源与图片类一致（后端账本拥有阶段文案）。
+
+## 不在范围内
+
+- 平台侧（api-server / external v1 / OpenAPI）路由、请求体、计费、队列与 worker 语义：本轮不改，音频仍提交既有 `/api/editor/audios/*/generations` 通道。
+- 音频波形级编辑、多轨、时长 / 循环等音频参数入口：仍按现状不做。
+- 视频入口、上传入口、图片类生成的参数与前置判据：行为不变。
+- 真并行派发（并发收口设计）：本轮仍保留「同一时刻只派发一条」的本地排队。
+
+## 依赖与前置条件
+
+- 现有图片类后台任务的账本、轮询、落点与聚焦链路可复用；音频生成通道（资源编辑派生）已具备 operation 幂等账本。
+- 音频提交需要携带请求身份（operation 与幂等键），否则重试会变成一次新的付费生成。
+
+## 验收标准与证据
+
+| 验收标准 | 结论 | 证据 |
+| --- | --- | --- |
+| 音频栏目的「生成背景音乐 / 生成音效」提交后**立即**返回一条任务记录；面板同步关闭，不等 IPC、不等排队、不等生成结束 | 自动化通过 | `resourceCanvasAssetGenerationBackgroundClose.test.tsx`（点「生成音效」同步提交 + 关闭，面板 DOM 里没有阶段文案与「后台运行并关闭」）、`resourceCanvasGenerationEntry.test.tsx`、`resourceCanvasGenerationHostLifecycle.test.tsx`（音频载荷逐字为 `projectPath / projectId / taskId / kind / prompt / assetName / idempotencyKey`） |
+| 提交受理后任务出现在「生成任务」侧栏，状态与阶段文案来自后端账本，前端不拼阶段、不做百分比 | 自动化通过 | `resourceCanvasAssetGenerationQueue.test.ts`（音频收口复用同一份账本记录）、`resourceCanvasAssetGenerationTasksPanel.test.tsx`、`resourceCanvasGenerationHostLifecycle.test.tsx`（提交后自动展开侧栏） |
+| 音频任务与图片类任务在同一条本地队列里按「同一时刻只派发一条」排队；第二条在本地排队期间不发提交 IPC | 自动化通过 | `resourceCanvasAssetGenerationQueue.test.ts`（音频载荷逐字断言 + 既有本地排队用例） |
+| 成功：走既有的「配对读 `(revision, manifest)`」交给 `onManifestChange`，结果落到该占位的最新位置并定位新卡 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`（账本收口为 completed 后新卡落在占位坐标、占位被撤掉） |
+| 失败：只有「点击瞬间就失败」（未受理）才自动重开面板并带回原草稿与原请求身份；受理之后才失败只在侧栏收口为失败并给出原因，不重开面板 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`「未受理的即时失败」（重开 + 草稿还原；同一用例里受理后不再重开）与「失败后用同一份请求重试」 |
+| 幂等：同一份失败原请求的重试复用同一 operation 与幂等键，不产生第二次付费生成 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`（重试的 `taskId` = operation id 与 `idempotencyKey` 与首次逐字相同）、`resourceCanvasGenerationLanding.test.tsx` |
+| 重开项目：音频任务从账本恢复显示；上次运行中断的任务按中断口径收口，不假装还在跑 | 自动化通过（恢复路径） | 音频 kind 的入口文案由工具栏模型派生（`resourceCanvasAssetGenerationTaskModel` + `resourceCanvasAssetGenerationQueue.test.ts`）；中断收口沿用既有账本口径 |
+| 音频提交失败（校验 / 权限 / 通道拒绝）时 manifest、revision 与任务账本都不出现半途写入 | 自动化通过 | Rust `asset_generation_tasks` 的 `audio_submission_rejects_invalid_identity_and_prompt_without_touching_the_ledger`（提交期拒绝零写入）、`audio_submission_lands_in_the_shared_ledger_with_its_audio_kind` |
+
+运行时验收（未做）：没有跑真实付费音频生成，也没有在真实客户端里做手感验收；全链以模拟原生接口的宿主用例覆盖。
+
+## 证据要求
+
+- 自动化：AGC 前端定向 vitest（音频入口宿主生命周期、生成任务队列与侧栏、appSurface 载荷）+ Rust 定向 `cargo test`（账本与音频任务入参收口）+ 类型检查 + 编码 / 文档索引 / `git diff --check`。
+- 运行时：无真实付费生成；以模拟原生接口的宿主用例覆盖提交 → 排队 → 收口 → 落卡全链。
+- 边界：未受理失败的即时重开与身份复用、账本读不到 / 记录缺失的收口、跨项目切换不串任务。

docs/project-memory/plans/【里程碑】Mac本机构建节点接入-2026-09-18.md

@@ -0,0 +1,50 @@
+# Mac 本机构建节点接入
+
+- Version: 1
+- Status: accepted-with-open-items
+- Date: 2026-09-18
+- Parent Spec: `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+
+## 交付与边界
+
+用户已确认使用当前 Mac，允许配置本机后台 Agent、创建 Jenkins 节点与构建 Job，并触发一次验证构建。复用已有 universal 产物合同与 Windows 管线的仓库访问凭据，仅手动构建和归档，无 OSS 上传、更新签名、Apple 签名/公证或定时调度。远程 Git 推送不在本次确认内。
+
+节点仅运行明确匹配 `genarrative-agc-macos` 的可信构建，单 executor；Job 禁止并发。Agent 根、workspace、原生 staging 与 target 均独立于开发 checkout，禁止在开发目录执行 npm ci、git clean/reset 或 Cargo 构建。登录用户 Agent 不等于安全沙箱，Jenkins 管理员与获准运行此 Job 的人必须受信任。登出、休眠或脱离内网将影响节点可用性。
+
+## 验收
+
+1. 从 Jenkins 当前控制器下载匹配的 agent.jar，Java 21 兼容检查通过，凭据留在仓库外、权限受限，不输出 secret。
+2. 节点实际 online，专用标签、EXCLUSIVE、单 executor；本地 LaunchAgent 可重启、可卸载。
+3. SCM 构建固定源码 commit，依赖从 lockfile 安装，两种原生 Codex 包 integrity 校验通过。
+4. universal Release、两架构 smoke、DMG verify 通过；归档只有安装包、摘要和非敏感来源信息。
+5. 真实 Jenkins build 为 SUCCESS 且归档存在。不以 XML 创建或本地单测冒充远端运行成功。
+
+## 初始检查与风险
+
+2026-09-18 当前机器具备 Java 21、两种 Rust Apple target 与 Rosetta；剩余磁盘约 11 GiB，独立 checkout 构建前须检查空间，不清理用户缓存。控制器地址连续连接超时，属于网络阶段，尚未使用认证凭据或创建后台服务。必须先恢复内网可达性；不修改本机网络路由或代理规避此限制。
+
+## 编码前评审
+
+只扩展现有 Jenkinsfile/应用打包脚本，不新增发布系统。用专用工作区且保持不发布，是当前明确授权内的最小闭环。代码未推送前不可把远端 master 当作已具备 universal 双资源实现；首跑源码来源必须明确记录，不能暗用开发工作树。
+
+## 当前证据与阻塞
+
+Jenkinsfile、锁定双架构依赖预备脚本与 archive-only CI 打包入口已在本地准备。定向 Node 测试 37 项通过，类型/配置、编码、文档索引、定向 ESLint 与 diff 检查通过；未执行完整 Jenkins 构建或在线 Groovy 校验。
+
+控制器直连多次超时，经当前代理请求返回 502；Java 21 已存在，无需安装新 JDK。尚未注册节点、创建 Job、保存 Agent secret、安装 LaunchAgent 或触发远端构建。需先恢复内网连接，再按本规范验收真实节点及构建状态；不把本地代码准备描述为已经接入成功。
+
+## 验收结果（2026-09-20）
+
+| 验收项 | 结果 |
+| --- | --- |
+| 控制器匹配的 agent.jar + 已有 Java 21 | 通过（未安装新 JDK） |
+| 节点实际 online、专用标签、EXCLUSIVE 单 executor | 通过（`genarrative-agc-macos-01`） |
+| LaunchAgent 可重启/卸载、凭据在仓库外且权限受限 | 通过 |
+| 固定 commit、锁文件装依赖、两种 macOS 原生包 integrity | 通过 |
+| universal Release + 双架构 smoke + DMG verify | 通过（arm64 原生、x86_64 走 Rosetta） |
+| 归档仅含安装包/摘要/非敏感来源信息 | 通过 |
+| 真实 Jenkins build SUCCESS 且归档存在 | 通过（build #3，43 分钟） |
+
+同期修复：Mac 入口误传 `--no-sign` 导致更新包无签名；复用 workspace 的残留产物导致 DMG 重建失败、旧签名可能让验签误通过；并行度由写死 4 改为 Job 参数（默认 6）。
+
+仍未验收：Apple 代码签名与公证（当前 `adhoc`，首装需 Gatekeeper 手动放行）、macOS 安装后重启接管新版本的实机闭环、Intel 真机 smoke、真实（非 dry-run）发布与渠道清单上线。

docs/project-memory/plans/【里程碑】Mac通用安装包与构建管线-2026-09-18.md

@@ -0,0 +1,36 @@
+# Mac 通用安装包与构建管线
+
+- Version: 1
+- Status: awaiting-user-acceptance
+- Date: 2026-09-18
+- Parent Spec: `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`
+
+## 当前交付门禁
+
+当前仅交付 AGC 0.1.67 universal 本地 DMG，版本、Codex 0.147.0 与 macOS 15.0 下限不变。不生成私钥、不签名公证、不发布、不推送。
+
+主程序含 arm64/x86_64 两个切片；macOS 资源分 `darwin-arm64` 与 `darwin-x64`，两套原生依赖保持上游相对路径和独立清单。运行切片只读取对应目录。构建必须校验两套锁定包身份、目标、版本与完整性；Windows 路径和资源不变。不合并原生 Codex 二进制，不改写其上游元数据。
+
+## 验收
+
+- 发布上下文接受 universal，dev-mac 的两个平台键同 URL/签名。
+- 主程序 lipo 两切片，资源检查两套原生架构、摘要和可执行位。
+- Apple Silicon 与 Rosetta 各做隔离 HOME/PATH 的真实 app-server 握手、正式程序查找与缺组件拒绝；Rosetta 不代替 Intel 真机。
+- 生成独立 universal DMG，不覆盖已有单架构 DMG；镜像校验、类型/配置/定向测试与编码检查通过。
+
+## 后续管线边界
+
+用户要求安装包完成后接入 Jenkins。先只读检查节点与现有 Job；创建/修改 Job、凭据或触发构建前额外确认。只有当前安装包门禁完成后再形成管线实现计划；不把凭据保存进源码、日志、计划或打包资源。
+
+## 编码前评审
+
+采用分架构资源而非 lipo Codex，避免破坏原生包元数据及 code-mode host、zsh 的资源寻址。macOS 共用配置明确列举两套文件，必须失败关闭，单架构诊断包也携带完整资源。现有 single-arch 选择逻辑改为同架构子目录，不涉及持久化数据迁移。
+
+## 验收证据
+
+- 同步至 master `9a21690fe`，本地 universal 修改无冲突恢复；未推送。
+- Tauri universal Release 构建通过，主程序 lipo 显示 arm64/x86_64，Info.plist 版本 0.1.67、最低 macOS 15.0。
+- `check-macos-bundle.mjs <app> arm64 --universal` 与 `x86_64 --universal` 均通过：每架构资源摘要、原生身份、执行权限、正式 Codex 选择、隔离 app-server 握手、缺 code-mode host 时拒绝。x86_64 在 Rosetta 执行，尚非 Intel 真机。
+- 发布/feature/上传定向 Node 测试 33 项通过，共享 Codex 布局模块在隔离 Cargo harness 的 2 项测试通过；类型/配置、定向 ESLint、编码/文档和 diff 检查通过。
+- universal `.app` 约 672 MiB，DMG 约 290 MiB；hdiutil 完整性校验通过。未做 GUI、账号/Provider、Intel 真机或签名公证验收。
+- Jenkins 只读检查确认现有节点为 Linux 与 Windows，尚无 macOS Agent；创建管线前需用户指定并授权接入 Mac 节点。本地凭据不进入源码或验证产物。

docs/project-memory/plans/【里程碑】策划Agent回合模型选择生效-2026-09-20.md

@@ -0,0 +1,48 @@
+# 策划 Agent 回合模型选择生效
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented（待验收） |
+| Date | 2026-09-20 |
+| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择) |
+
+## 目标
+
+策划已有会话在后续执行时真正采用控件保存的模型和推理档，执行途中保持选择稳定，恢复不破坏既有工具副作用边界。
+
+## 范围
+
+- 新会话、旧会话后续消息、回答澄清、阶段审批继续和用户主动重试的选择生效。
+- 同一次执行中的工具循环、自动重试固定使用开始时的选择。
+- 活动回合自动恢复所需的最小模型、推理档快照及旧会话缺字段读取。
+- 模型切换保留策划上下文、阶段、审批和产物。
+
+## 不在范围内
+
+- 不改变 GameAgent Runtime 或既有配置控件算法。
+- 不调整模型目录、默认档位、供应商协议、提示词和阶段规则。
+- 不建立 Agent 专属设置、通用快照框架、历史转换器或平行账本。
+
+## 依赖与前置条件
+
+- [控件接入里程碑](./【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) 已验收。
+- 主规范和本里程碑已评审，实施前编写仅覆盖本步的实现计划。
+- 生效时机、主动重试与自动恢复的区分遵循主规范，不通过重建会话实现切换。
+
+## 验收标准
+
+- [ ] 新策划会话和旧策划会话下一次执行都使用当前已保存选择；旧模型不再永久覆盖新选择。
+- [ ] 发送、澄清、审批继续与主动重试的实际 Provider 请求使用新选择。
+- [ ] 执行中改配置不影响本次后续工具请求或瞬态自动重试，下一次用户执行才生效。
+- [ ] 自动恢复优先使用已有活动回合快照；旧记录缺推理档时按主规范补齐，不重复已执行工具副作用。
+- [ ] 切换后上下文、阶段、产物和审批身份保留，纯读取不改历史模型信息。
+- [ ] 配置/Provider 失败沿用可见错误，不静默降级、换模型或清空历史。
+- [ ] GameAgent 既有选择和运行行为通过兼容回归，没有借机修正其本征不足。
+
+## 证据要求
+
+- 自动化：本地 Provider fixture 捕获请求模型和推理档；覆盖跨工具调用、自动重试、用户重试、审批/澄清继续及旧会话恢复；运行相关 Rust 定向测试、必要类型检查、编码和文档索引检查。
+- 运行时：在现有策划项目选择另一模型及推理档，触发下一次执行核对实际请求；真实供应商是否接受跨模型历史需按环境记录实测或未验证。
+- 边界：验证恢复幂等和凭据不进入新增快照；无需新增通用权限或供应商测试体系。
+- 全部验收后将主规范提案改为当前行为，更新稳定项目记忆并删除本次已完成临时计划。

docs/project-memory/plans/【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md

@@ -0,0 +1,53 @@
+# 策划 Agent 模型与推理档控件接入
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | accepted（用户已授权提交、进入第二步） |
+| Date | 2026-09-20 |
+| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择) |
+
+## 目标
+
+策划对话复用已有模型和推理档控件，能够读取和保存全局选择，保持 GameAgent 兼容性。
+
+## 范围
+
+- 输入区域中控件的显隐、位置、策划面板布局与必要的宿主接线。
+- 复用原有目录、默认模型、保存和错误提示，不复制逻辑。
+- 策划发送、澄清、审批继续和主动重试保持原流程；不新增模型可用性检查或提交门禁。
+- 重新进入策划时显示保存值；执行中可以调整后续选择，但原输入与提交忙态维持不变。
+
+## 不在范围内
+
+- 不修改策划 Provider 的模型选择和推理档采样逻辑，不声称旧会话已能切模型。
+- 不检查、修复或重构 GameAgent 组件本征不足，不引入通用缓存、同步、保存、下拉或配置框架改造。
+- 不为策划引入队列、语音或素材引用，不更改默认推理档。
+
+## 依赖与前置条件
+
+- 主规范本节与本里程碑完成评审。
+- 实施前仅为本里程碑编写实现计划，确认现有 GameAgent 对应回归用例与策划宿主入口。
+- 本步作为内部接入结果；第二步完成前不单独发布为完整可切模型功能。
+
+## 验收标准
+
+- [ ] 策划入口显示原模型及推理档控件，没有重复实现或第二份设置。
+- [ ] 选择走原保存通道；重新进入显示已保存值；保存失败显示原有错误反馈。
+- [ ] 策划提交和报错流程保持原样，没有新增模型检查；原控件内部行为不改造。
+- [ ] 策划忙态、待审批/澄清行为保持；新增布局在宽/窄面板可操作。
+- [ ] GameAgent 原控件的显示、选择、发送校验、忙态和运行行为通过相关回归。
+- [ ] 交付明确记录旧策划会话仍沿用旧模型，留待下一里程碑解决。
+
+## 证据要求
+
+- 自动化：现有界面测试中增加策划入口的集成场景，复用 GameAgent 回归；运行 AGC 类型检查、文档索引、编码和 diff 检查。
+- 运行时：桌面与窄面板选择、保存、重新进入和一次策划发送 smoke；缺失环境如实标注。
+- 边界：只验证接入所需的失败和忙态，不扩展为现有组件全量审计。
+- 通过本步验收后，才准备并执行模型生效里程碑的实现计划。
+
+## 当前交付
+
+已接入原控件及策划布局，按用户最终要求保留策划提交、审批、澄清、重试与报错流程，没有新增模型检查。原控件与 GameAgent 的提交逻辑未修改；旧策划会话固定模型的限制仍由第二步解决。
+
+新增三条控件集成用例（保存重进、运行中选择、保存失败反馈）。用户已授权提交第一步、进入第二步。

docs/project-memory/plans/【里程碑】退役策划Agent V1V2解耦清理-2026-09-15.md

@@ -0,0 +1,49 @@
+# 【里程碑】退役策划 Agent V1/V2 解耦清理
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md` |
+
+## 目标
+
+移除旧版策划 Agent V1、V2 的前端会话、审批、数据适配、测试契约和确定失效的展示残留；仅在删除策划链路时遇到已退役 Supervisor 功能耦合时一并删除该耦合，使“做方案”只使用当前 Design Agent、做游戏只使用 DirectCodex。
+
+## 范围
+
+- 解除当前 Design Agent 与旧 `planningV2` / `PlanGdd` 状态命名和控制流的耦合。
+- 删除仅服务旧策划的 Supervisor 产品入口、会话恢复、Runtime 轮询和聊天提交分支；保留通用 Supervisor 与做游戏 DAG。
+- 删除旧 V2 会话 hydrate、start、continue、审批和用户问询分支。
+- 删除旧 V2 TypeScript 会话适配层、旧 GDD 前端类型、测试 mock、旧事件契约和专属样式。
+- 清理确定没有现役调用方的旧策划身份说明、测试 fixture 和文档当前入口。
+- 保留当前 Design Agent 的会话、澄清、阶段审批、工作区浏览和 reasoning 展示行为。
+
+## 不在范围内
+
+- 不主动扫描、重构或整体删除做游戏 Agent 的 16 Agent DAG；只有策划删除直接造成编译或测试失败时才做最小修复。
+- 不删除 DirectCodex 或当前 Design Agent；必要时保留被两者复用的中性聊天表现组件。
+- 不为旧项目新增兼容层、迁移器、墓碑注释或退役行为测试。
+- 不修改 SpacetimeDB schema、公开 API、持久化迁移和现役 Design Agent 协议。
+
+## 依赖与前置条件
+
+- PR #159 的合并提交 `3d8e0211` 代表旧 Fast GDD / 策划 V1 的引入。
+- PR #305 的合并提交 `04128eb6` 同时包含 V1 大范围退役、策划 V2 会话链路和后续 Design Agent 迁移。
+- 当前分支已经删除 Rust V1/V2 Runtime 模块和旧审批组件，但前端仍残留旧 V2 调用方；实现前须保持工作树干净。
+
+## 验收标准
+
+- [ ] “做方案”入口和已有 Design Agent 项目只调用当前 Design Agent IPC，不再调用旧 `planning_*_v2` IPC。
+- [ ] 当前 Design Agent 的消息、reasoning、澄清、阶段审批和重试行为不依赖旧 V2 状态变量。
+- [ ] 源码中不再存在旧 V2 TypeScript 会话适配层、旧 `PlanGdd` 类型和旧前端审批契约。
+- [ ] 旧前端测试、事件测试和样式残留被删除或改为当前 Design Agent 契约。
+- [ ] 不主动修改做游戏 Supervisor + 16 Agent DAG；因共享退役代码删除产生的编译错误得到最小修复。
+- [ ] 前端 typecheck、相关定向测试、编码检查和 diff 检查通过；触及 Rust 时对应 cargo check 通过。
+
+## 证据要求
+
+- 自动化：`npm --prefix apps/ai-game-creator-shell run typecheck`、相关 appSurface 定向测试、`npm run check:encoding`、`git diff --check`。
+- 运行时：至少验证“做方案”新项目进入 Design Agent、已有 Design Agent 会话恢复、澄清/审批回合可继续。
+- 边界：确认 DirectCodex 和做游戏既有入口未被旧策划清理改动；确认旧 V2 IPC 字符串和旧事件契约不再进入现役前端。

docs/project-memory/plans/【里程碑】退役策划V2 Rust Runtime清理-2026-09-14.md

@@ -0,0 +1,38 @@
+# Version
+
+V2-RUST-RETIRE-1
+
+# Status
+
+in-progress
+
+# Date
+
+2026-09-14
+
+# Parent Spec
+
+`docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
+
+# 目标
+
+删除已经被独立 Design Agent 取代的旧策划 V2 Rust Runtime、Tauri 命令注册和仅服务 V2 的模块导出，使桌面壳继续编译并保留做游戏 Agent 与新版 Design Agent。
+
+# 边界
+
+- 删除 `planning_policy_v2`、`planning_session_v2` 及仅供这两者使用的 V2 注册和调用。
+- 删除 V2 专属的 Tauri command 注册、模块导出和测试入口。
+- 保留 `design_runtime`、`design_tools`、`design_session`、通用 runtime、DirectProject 和做游戏 Agent。
+- 本里程碑不处理前端 V2 数据层、UI、文档索引和共享运行时中的可选清理。
+
+# 验收标准
+
+1. Rust 源码不再编译 `planning_policy_v2.rs` 或 `planning_session_v2.rs`。
+2. `main.rs`、`commands.rs` 和 runtime protocol 不再注册或导出 V2 命令。
+3. 新版 Design Agent 与做游戏 Agent 的 Rust 编译路径保持可用。
+4. 相关定向 Rust 测试和 `cargo check` 通过。
+
+# 依赖
+
+- 当前分支已包含 PR159 的 V1 清理。
+- 前端 V2 调用暂时保留，待后续里程碑同步删除。

docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md

@@ -0,0 +1,55 @@
+# 项目自动上传与后台工程下载
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented-awaiting-runtime-validation |
+| Date | 2026-09-19 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的项目快照上传与后台工程下载合同 |
+
+## 目标与范围
+
+修复实际项目自动上传的已证实故障，并让有权限的后台管理员按项目查看远端快照、一键下载按原始目录还原的工程 ZIP。
+
+## 不在范围内
+
+客户端上传 UI、跨设备恢复、版本历史、数据库 schema、线上部署、自动补传全部未打开项目。
+
+## 依赖与前置条件
+
+延续现有私有 OSS 项目快照、平台会话与后台权限。真实 bucket 已只读确认只有两份历史模板清单；上传根因必须经确定性复现后修正。
+
+## 验收标准
+
+- [ ] 正式项目窗口可被同步调度识别；周期与关闭触发保持有界，失败有项目级诊断。
+- [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
+- [ ] 后台列表显示项目名/ID、用户 ID、同步时间、文件数、体积和完整性，支持刷新与分页。
+- [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
+- [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
+- [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。
+- [ ] 无后台权限不能读取项目或 ZIP；不泄漏凭据；ZIP 构建有体积、并发和临时文件清理边界。
+- [ ] 定向 Rust 测试、后台类型检查/构建、UI smoke、编码、文档索引和 diff 检查完成，运行时证据与未验证部分分别列出。
+
+## 证据要求
+
+自动化覆盖窗口身份、上传零字节、清单统计、目录还原、路径与校验和校验、后台路由权限。运行时优先只读现有 OSS 清单；测试不上传真实用户工程、不修改线上数据。
+
+## 已取得证据
+
+| 层次 | 结果 |
+| --- | --- |
+| 客户端 Rust `project_snapshot` | 22 通过、1 忽略（写入式真实上传 smoke 未运行）；含排队退出等待回归 |
+| 客户端前端生命周期与启动器 | 3 文件、10 测试通过；完整 AGC typecheck、skill-pack、check-config 通过 |
+| 后台页面、API client、路由与样式 | 44 测试通过；admin-web typecheck/build 通过 |
+| 后端快照与权限 | 14 定向测试通过；未认证路由矩阵与页签映射 2 测试通过 |
+| 默认存储目标 | 真实 AppConfig::from_env 配置回归 1 通过 |
+| OSS 存储层 | 全量 55 测试通过，含签名、特殊字符路径、读取上限与零字节 |
+| 真实 OSS 只读导出 | `project_snapshots_live_readonly_list_and_archive` 通过；limit=1 分页、2 清单、12 文件、73,424 字节，ZIP 解压路径/长度/摘要全匹配、临时文件清理通过；两份均为历史 unverified |
+| 浏览器 smoke | 模拟 API 的 1280 桌面与 390 窄屏通过；下载按钮可见，无整页横向溢出；中文 ZIP 文件名、Authorization、409 错误呈现通过 |
+| 通用门禁 | 编码、文档索引、production-ops、Rust 格式、客户端 Prettier 与 diff 检查通过 |
+
+## 剩余验证与环境边界
+
+`npm run dev:api-server -- --api-port 4198 --bgfilter-worker-port 4199 --api-timeout-seconds 600` 编译成功，但当前工作区配置的本地数据库 `xushi-p4wfr` 在 `127.0.0.1:3101` 返回 404，启动认证投影无法完成，故 `/healthz` 及完整 HTTP smoke 未通过。仅本任务启动的 API/worker 已停止；没有清库、迁移数据库、改 `.env` 或替换其它项目的验证目标。
+
+尚未替换安装版、构建新客户端发布包或部署；提交推送按用户本轮授权执行。当前条款已有上述自动化与只读存储证据，最终验收仍等待当前工作区数据库就绪后的 HTTP 联调，以及新客户端的隔离实机自动上传验证；完成后再关闭里程碑并清理两份计划。

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

@@ -1,7 +1,101 @@
 # 决策记录
 
+## 2026-09-21 图集切片上限：客户端结果门从 64 对齐到平台契约的 256
+
+- 背景：现场（项目 `gameagent-6e53c9e8`，2026-09-21 07:54）「AI 生成图标素材」失败：`platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个`。任务账本（`.agent/runtime/asset-generation-tasks/tasks.json`）显示它跑了 99 秒、`assetId` 为空、没有落任何素材；对应的持久化请求（`canvas-generation-requests/manual-canvas-asset-generate/slot-560175669f….json`）是 `sliceMode: connected-components` + `sliceCount: null`（自动切分）。也就是**平台已经生成并切完图了，是客户端在绑定结果这一步把整条结果判失败**，付费产物被丢弃。
+- 根因：同一条链路里存在两个不同的切片上限。平台切分是 256（`server-rs/crates/api-server/src/editor_project_icon.rs` 的 `EDITOR_ICON_SPRITESHEET_MAX_SLICES`），Agent 工具 schema 的 `sliceCount` 是 1..256（`agent_native_tools.rs` / `direct_tool_bridge.rs`），持久化产物批次也是 1..256，公开契约（`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`）写的更是「最多 256 个输出」；唯独客户端**两处结果绑定门**还是 `> 64` 就拒（`agent/generation/external_generation_state.rs` 与 `agent/generation/canvas_generation.rs`，由 `602723ea0` 于 2026-08-03 引入）。自动切分落在这个窗口里（65~256 片）时，客户端比平台更严，于是把合法产出整条丢掉。
+- 决策：两处门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，并抽成同一条判据 `platform_art_spritesheet_slice_count_exceeds_limit` 与同一句拒绝文案 `platform_art_spritesheet_slice_limit_error`（数字由常量插值，不再手写）。注释里点名三处同值权威（平台切分常量、工具 schema `sliceCount`、公开契约），客户端不得比平台更严。
+- 原因：客户端这两处门的作用是「防止把不可信/超预算的结果写进本地」，不是产品上限；真正的产品上限属于平台切分契约。两处各写一个字面量就会再次漂移，所以值只留一份、判据只留一条。
+- 验证：新增 `canvas_generation_tests::spritesheet_slice_limit_matches_platform_and_tool_contract`（上限值、边界判据与文案）与 `external_generation_state_tests::legacy_result_accepts_slice_counts_up_to_platform_limit_and_rejects_beyond`（64/65/256 片必须能持久化且切片一条不少、257 片必须按同一句文案拒绝），两条都用**变异验证**确认过：把常量改回 64，回归用例立刻变红。定向执行 `cargo test -- spritesheet`（22 passed）、`cargo test -- external_generation_state_tests::`（10 passed）与两条新用例；`cargo fmt --check` 干净。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/{canvas_generation.rs,external_generation_state.rs}`（+用例）。未动平台切分、OpenAPI、数据库或前端。
+- 已知未覆盖：真实客户端复验（重新生成一次图标素材）与远程 CI 未跑；256 片时的累计下载/像素预算未实测——平台自己的总像素上限是 2048×2048，客户端预算是 4096²，按切片是整图互不重叠子矩形推算不会先撞预算，且真撞了也只是给出明确错误而不是损坏数据。
+## 2026-09-21 本批自查（PR #441）：三处修正
+
+- 背景：推 PR 后按「局部到整体」自查这一批（三需求 + 验收修正），查出三条：①拖动到对话的落点在 `pointermove` 上每帧都 `setState` 一个新对象；②替换面板相对 **stage** 写死 `top: 8.5rem`（与刚修的任务开关同一类隐患：工具条换行会压上去），且它和「生成任务」面板抢画布右上角同一个位置；③替换面板不显示「在替换哪张源素材」，而非模态化之后那点线索（画布上的源素材光环）会被一次空白点击清掉。
+- 决策①：落点状态改为**逐值比较**（`sameResourceCardReferenceDrop`：条数 + 对话栏矩形四值），只有真的变了才落 state——指针在对话栏上移动不再每帧重渲染整个工作台。
+- 决策②：面板从 stage 顶层移进**画布容器** `.game-resource-book-manager`（它本身就是 `position: relative`，与左下角工具栏、右下角 Dock 同一套锚定口径），`top: 3.2rem` 排在任务开关下方；并在打开替换会话时**收起「生成任务」面板**——画布右上角同一时刻只留一块浮层（任务照旧在账本里推进，收起只影响这个视图）。
+- 决策③：面板上方补一行「替换源素材：<显示名>」（投影显示名优先、manifest 资产名回落），源身份不再只靠画布光环。
+- 验证：`resourceVersionReplacement.test.tsx` 20 passed（新增「面板锚在画布容器里、写明源素材、并与任务面板互斥」）、`resourceCardReferenceDropModel.test.ts` 6 passed（新增逐值比较）、`resourceCanvasChatReferenceDrop.test.tsx` 4 passed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
+- 影响范围：`apps/ai-game-creator-shell/src/view/project-development/{index.tsx,resourceCardReferenceDropModel.ts}`、`.../features/resource-canvas/resourceCanvasChrome.css`、用例 3 个文件、验收用例 C9 注脚。未动 Rust / SpacetimeDB / 共享组件行为（只新增了宿主的源素材行）。
+- 已知未覆盖：仍无真机目视；替换会话与任务面板的互斥是新行为，客户端需要复看一次（若产品希望两者能同时看，把这一句收紧即可）。
+
+## 2026-09-21 验收现场修正：任务开关压在工具条上、开关与面板并排
+
+- 背景：客户端验收截图两条：①画布右上角那枚「生成任务 · N」开关与工具条（打开项目目录 / 资源面板 / 整理画布 / 管理未完成编辑 / 依赖 · 类型）**重叠**；②「生成任务」面板展开时，开关与面板**并排**摆着，产品口径是「这俩不应该并排，出来详情以后入口就应该隐藏」。
+- 决策（重叠）：锚点不再用 `position: absolute` + 写死的 `top: 3.5rem`（工具条是 stage 第一行，高度随按钮换行变化，写死的偏移迟早压上去），改成 **stage 网格里与工作面同一个单元格的另一个条目**：`grid-row` 按 `placement` 分档（资源画布 3 / UI 编辑器 2 / 运行表现层 `2 / -1`）+ `grid-column: 1` + `justify-self: end` + `align-self: start` + `margin: 0.85rem`（运行那档上边距 3.5rem 让开右上角版本入口）。为此把同格的三处容器也显式钉住第 1 列（`.game-workbench-stage > .game-resource-manager`、`.…[data-resource-view-state='resources.ui-editor'] > .game-workbench-editor-shell`、`.game-run-surface`）——锚点是显式定位条目，画布若走自动列放置会被挤进隐式第二列、画布直接压窄一半。
+- 决策（并排）：开关只在**完全收起**时渲染（`!open && phase === 'idle'`，收起动画期间也不画，否则那 160ms 又会同框）；展开态画布右上角只有面板，收起走面板头部那枚 × 或点画布外部。原来「点画布外部自动收起」的判据里对开合按钮的排除保留（收起态仍靠它开合）。
+- 原因：验收口径优先于「照抄美术画布」——美术画布把开关常驻在面板旁边，但产品要的是「入口与详情不同时出现」。重叠那条的根因是**猜了一个绝对偏移量**：工具条高度不是常量，锚点必须由布局自己推导。
+- 验证：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 12 passed（新增「展开时开关让位：同一时刻只有面板那枚 ×」；计数用例改为收起态查开关、展开态查面板头部）、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed（锚点改成网格条目坐标：`grid-row` / `grid-column` / `justify-self` / `align-self` / `margin` 与运行档上边距；窄屏改判 `justify-self: stretch`）、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed（收起改走面板 ×、收起后开关回来能再打开、锚点仍在 stage 里）、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；`appSurface.test.ts` 538 passed / 17 skipped / 0 failed。
+- 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{ResourceCanvasAssetGenerationTasksPanelView.tsx,resourceCanvasAssetGenerationTasksSidebar.css}`、`apps/ai-game-creator-shell/src/styles.css`、三个同场景用例文件、PRD §3.10 与更新时间。
+- 已知未覆盖：仍无真机目视（网格落点在 Tauri 里的实际观感、工具条换行时锚点是否仍贴画布顶边需要现场复核）。
+
+## 2026-09-21 AGC 替换面板改为非模态浮层，支持在画布上点选目标
+
+- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「在替换面板中支持画布点选目标」。2026-09-13 那版做的是「候选弹窗 footer 一个『点选替换』按钮 → 关掉弹窗 → 进画布点选态 → 点中即提交」：面板与画布互斥（弹窗外壳是全屏遮罩，留着它画布上的卡点不到），用户要么在面板里筛、要么离开面板。
+- 决策：候选面板改成**非模态浮层**（共享组件新增 opt-in `nonModal`：不铺遮罩、不做焦点陷阱、面板自身限高 + 内部滚动、Esc 在 `document` 阶段截断后取消；网页端美术画布不传，弹窗行为逐字不变）。AGC 把它锚在画布**右上角、任务开关下方**（`.game-resource-replacement-panel` → `top: 8.5rem; right: 0.85rem`，壳样式在共享样式表里，宿主只负责锚定）。**面板开着时画布照常可点**：点中合法候选即落成面板里的当前选择（面板里随之 `aria-selected`），写入仍然只由面板「确认」发起；点中非法目标在面板里说明原因、零写入。旧的「点选替换」入口、画布提示条 `.game-resource-canvas-pick-hint` 与 `resourceReplacementPickMode` 随之退役（同一个功能不留两条 UI 路径）。
+- 决策（同步口径）：`selectedAssetIds` 的**数组引用不能当同步信号**（调用方每次渲染都会重建它，放进依赖会清掉用户在面板里的选择——组件里原本就为此写过一段注释），所以新增显式序号 `initialSelectionRevision`：只有宿主真的换了目标才重同步选择，搜索词与分类筛选保持原样。`confirmResourceVersionReplacement` 另外拿 `resourceReplacementPick` 兜底：点完画布当帧就按确认时不该报「请选择一个替换素材」。
+- 原因：面板与画布是同一屏的两半——目标本来就在画布上，「先把面板关掉再点」是弹窗外壳带来的妥协，不是产品意图。换成非模态之后，合法性判据仍是同一条 `resolveResourceReplacementPick`、写入仍是同一个 `confirm` 函数（载荷逐字一致），所以这是**外壳**的改动，不是第二套替换实现。
+- 已知取舍（相对旧口径的行为变化，均已随测试钉住）：面板开着时空白处点击不再被吞——画布恢复正常的清焦点 / 框选 / 平移语义（源身份在打开面板时就已冻结，替换不依赖画布选中）；「点中即提交」不再存在，提交一律由「确认」触发；关闭面板后卡片单击语义原样（一次性抑制照旧收尾）。
+- 验证：`resourceVersionReplacement.test.tsx` 19 passed（4 条旧点选用例改写为：非模态判据 + 点画布候选落进面板且零写入、面板确认才写入且载荷逐字一致+血缘、四类非法目标面板内报因零写入、Esc 只收面板不清选中；新增「画布点选不清掉面板搜索/分类」）、`projectAssetPickerDialogShellStyle.test.tsx` 7 passed（新增 nonModal 形态与浮层壳样式声明，含关掉即卸载）、`src/components/image-editor/ImageCanvasEditorView.test.tsx` 64 passed、`ImageCanvasEditorGenerationIntegration.test.tsx` 44 passed（网页端弹窗行为未变）；连同 `appSurface.test.ts`、`projectResourceLiveIntegration.test.tsx` 共 6 个文件 694 passed / 17 skipped / 0 failed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
+- 影响范围：`src/components/image-editor/ImageCanvasProjectAssetPickerDialog.tsx`、`packages/shared/src/components/styles.css`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`.../features/resource-canvas/resourceCanvasChrome.css`、`apps/ai-game-creator-shell/tests/{resourceVersionReplacement.test.tsx,projectAssetPickerDialogShellStyle.test.tsx}`、PRD §5.3 / §7.8 第 8 条、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md` 的 S15a。未动 Rust、SpacetimeDB、external v1。
+- 已知未覆盖：真机观感（面板在画布右上角的落点、与任务开关同时打开时的间距）未在 Tauri 目视确认；面板里不显示「本次替换的是哪张源素材」，源身份只靠画布上那张卡的选中光环表达——点空白清掉选中后就只剩面板自己的候选列表。
+
+## 2026-09-21 AGC 资源卡拖到对话实现批量 @ 引用
+
+- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「聊天拖拽批量引用」。改前只有两条入口：聊天输入框里输入 `@` 或点 `@` 按钮开素材选择面板，以及资源卡选中工具条上那枚「引用」按钮——都要先把素材找出来再点，多选批量引用没有一次成型的路径。
+- 决策：资源卡**按住拖到右侧 Agent 对话栏、松手即批量引用**。落点判据是「指针是否在对话栏矩形内」：pointermove 在对话栏上时语义从排版切成引用（卡片不再跟着指针走，改铺一层虚线落点浮层 + 「松手即可 @ 引用 N 项素材」），拖回画布内松手仍然是原来的排版语义（照旧写手动坐标）。批量范围与拖动位移**同一集合**（`drag.moves`）：多选后拖任意一张 = 整批引用，拖未选中的卡 = 只引用它自己。
+- 决策（引用构造与派发）：引用构造收敛成纯函数 `resourceCardReferenceDropReferences`，口径与工具条「引用」按钮**逐字一致**——只认已登记 manifest 的素材（`manifestAssetId`）、`source: 'resource-card'`、kind / 分类 / 标签取自资源投影，于是同一素材从两处进来是同一枚引用（去重键同样一致）。派发走新增的批量事件 `RESOURCE_REFERENCE_INSERT_MANY_EVENT`（`dispatchResourceReferenceInsertMany`）：N 条引用一次事务插进草稿、只聚焦一次，不逐条重建草稿。一条也构造不出来时（选中的素材都未登记）不静默：提示条说明原因。
+- 原因：拖动本来就在指针捕获下走，指针跑到画布外仍回到卡片 handler，因此「落点」只能自己量；不落盘是因为对话栏那一段没有画布坐标可言（写下去会得到跑到画布外的坐标），而且用户在对话栏上松手的意图本来就不是排版。`0 x 0` 的对话栏矩形必须判成「没有落点」：零面积矩形会让任何点都命中，画布内正常拖动会被整段跳过。
+- 验证：`resourceCardReferenceDropModel.test.ts` 5 passed（矩形/命中/构造/提示文案）、`resourceCanvasChatReferenceDrop.test.tsx` 4 passed（单卡拖到对话 → 1 条引用且零坐标写入、多选整批 → 2 条、拖回画布 → 照旧写手动坐标且零引用、pointercancel 收干净）、`resourceReferenceInput.test.tsx` 30 passed（新增批量事件一次派发且空批次不派发、一次 insertReferences 按序插入整批 chip）；连同 `appSurface.test.ts` 在内 7 个用例文件 660 passed / 17 skipped / 0 failed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
+- 影响范围：`apps/ai-game-creator-shell/src/view/project-development/{index.tsx,resourceCardReferenceDropModel.ts}`、`.../features/project-workspace/resourceReferences.ts`、`apps/ai-game-creator-shell/src/App.tsx`、`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/tests/{resourceCardReferenceDropModel.test.ts,resourceCanvasChatReferenceDrop.test.tsx,resourceReferenceInput.test.tsx}`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`。未动 Rust、SpacetimeDB、`packages/`、共享弹窗组件。
+- 已知未覆盖：真实客户端里的手感（拖到对话栏的触发距离、提示条位置、多选整批的视觉反馈）未在 Tauri 目视确认；「复制对话保留有效引用」属于同一条后续需求里的另一半，本轮未做。
+
+## 2026-09-21 AGC「生成任务」侧栏移到画布右上角（照抄美术画布，保留 AGC 样式）
+
+- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「生成任务列表移到画布右上角，进行中/已完成分组、失败可见、限高滚动及自动开合」。改前状态：侧栏本体是 `position: fixed; top: 4rem; bottom: 6rem; left: 0.75rem` 的左侧贴边面板，开合口只有工具条上那一枚「生成任务 · N」按钮（资源 / 运行两个页签各渲染一次），折叠态不留任何常驻入口；分组、失败可见、限高滚动、提交后自动展开这四条当时已经具备。
+- 决策：侧栏改挂**画布右上角的锚点**（`.game-resource-generation-tasks-anchor`），形态照抄网页端美术画布的任务侧栏（`ImageCanvasTaskSidebarView.tsx` + `src/index.css:6072+` 的 `.image-canvas-editor__task-sidebar*`）：**开关常驻右上角、面板在开关左侧展开**，收起态只剩那一枚开关；工具条上那两处重复入口删掉——同一个功能两个入口本身就是两处随时会漂移的状态。锚点是覆盖式的，仍然不 reflow 画布视口。颜色、圆角、字重、阴影**全部继续走 `--platform-*` token**，不照搬网页端的固定色值（该 CSS 文件头既有的口径）。
+- 原因：右上角是画布上唯一「不被右侧『智能创作』对话面板占、也不与左下角栏目工具栏 / 右下角缩放 Dock 打架」的稳定空位；折叠态仍留一枚开关以后，用户不必先想起工具条在哪一行，也不再需要「关掉以后打不开」的兜底（原设计正是靠工具条入口常驻来解决这个问题）。
+- 决策（分档坐标）：锚点由 view 的 `placement`（`canvas | run | editor`）落成 `data-generation-tasks-placement`，坐标在样式里分档：资源栏目画布与 UI 编辑器用画布顶边那一档（`top: 3.5rem; right: 0.85rem`），**运行表现层下移到 `top: 7rem`**——它右上角 `top: 20px; right: 20px` 被 C7 版本入口 `game-run-version-picker` 占着，不去抢那一块。
+- 实现要点：开关改由 view 自己渲染（`data-resource-generation-task-toggle` 与计数属性原样保留，可访问名 `生成任务` 唯一），在途计数只在 view 内算一次、开关与面板头部同源（宿主原先那份 `resourceAssetGenerationInFlightCount` 因此删除）；面板改由 `max-height: min(30rem, calc(100vh - 12rem))` 封顶 + 内部滚动，自己不再定位（坐标只由锚点一处决定）；进场 / 退场动画位移方向跟着锚点翻到正 X。宿主的「点外部收起」判据（排除侧栏本体与 `data-resource-generation-task-toggle`）与「提交受理后自动展开」均未改。
+- 验证：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 11 passed（新增「折叠只剩右上角开关」「开关计数与面板头部同源」「锚点按工作面分档」）、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed（锚点坐标 / 运行档下移 / 面板不再自定位 / 开关走 token 且无硬编码色 / 窄屏占满宽度）、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed（入口位置改为右上角锚点、工具条不再有生成任务按钮）、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；`appSurface.test.ts` 538 passed / 17 skipped / 0 failed（与既有基线逐条一致）；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
+- 影响范围：`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）只有声明级断言。
+
+## Unity 与 Godot 常用操作指导
+
+两种编辑器的操作指导复用客户端审核 Skill pack：DirectProject 通过原生 Skill 或既有审核资源读取入口按需取得，Agent Runtime 的对应执行工具说明嵌入同源参考。指南不改变插件可用性、执行授权或 Runner 回执；只读说明不能证明编辑器已连接。常用示例与执行失败/部分修改、保存、撤销边界在同一参考中维护，避免提示词和文档各存一份代码。
+
+## 2026-09-20 Godot 编辑器执行接入
+
+原生引导采用固定版本的官方 `godot-cpp` 和 MSVC x64 构建，绑定及 C++ runtime 静态链接。依赖归档和缓存源码须核验，安装目录仍只分发原生载荷及许可。EDITOR 阶段动态加载/卸载时显式清理 C++ 实例绑定与单例包装，保留纯 GDScript 的异步执行和原有协议；执行权限、项目身份与缓存归属继续由现有宿主处理。
+
+可用性边界按引擎区分：Cocos/Unity 保持不按工程类型过滤，Godot 仍绑定当前 Godot 项目，切项目撤销旧插件上下文；前端统一根据宿主投影启动插件。Runtime 工具目录只对 Godot 追加项目条件，编辑器说明沿用外置提示词及审核 Skill 参考。
+
+Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和不确定执行回执合同，编辑器实现留在 `plugins/agc-godot-editor`。用户选择 DLL 原件随 AGC 安装资源分发，并确认按编辑器实例在 AGC 私有缓存准备临时加载副本，以满足 Godot Windows 加载器的同目录 `~DLL` 写入要求；项目内不复制 DLL，只用受管 `.gdextension` 引导。Godot 自动 UID 伴生文件必须记录归属并在确认卸载后按内容匹配清理。工作区根不迁移到 Godot 子目录，原始项目配置与场景只通过明确编辑操作修改。完整合同及验证范围见 [Godot 编辑器插件接入](<../../technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)。
+
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
-> 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+> 当前口径（2026-09-18）：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据。策划 Agent V1/V2 的 Runtime、专用命令、审批卡、展示适配和旧测试已删除；当前策划入口统一使用 Design Agent。如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+
+## 2026-09-20 DirectProject 工具并行与交付收敛
+
+- 所有工具具备有界并行调度能力，MCP 每入口在途上限 8；独立图片在客户端进程内最多 2 个。只保留同资源冲突、编辑器实例、canonical 美术包和短提交事务的必要串行边界。同一付费动作必须在容量排队前取得原 durable 槽锁，不重写幂等算法。
+- Web 工程由客户端提供经完整性校验的 Node/npm 和浏览器健康预检，保留隔离 HOME；缺失或损坏不能静默退回项目或系统中的另一份 Node。
+- Direct 回合的合同、证据和预算以宿主私有账本为准，项目侧记录只作展示。GUI/CLI 共用入口；首次副作用前冻结非空验收合同，可信新 Web 工程由宿主补充构建和双端验证底线。普通无副作用聊天不强制构建。
+- 视觉、固定玩法和托管命令分层；`validation.maxRuns` 按执行/返修批次管理，正常开发命令共享批次；累计执行时间与整轮墙钟分别受 `maxExecutionSeconds` / `maxTurnSeconds` 约束，显式配置与 Provider 重试独立。源码、构建输出、环境输入与证据文件摘要分别复核，项目可编辑记录不能抬高预算或伪造成功。
+- 原生工具使用已验证的捆绑版本逐次审批能力，第三方 MCP 显式逐调用询问；所有 Direct 入口接受宿主同一状态，未知远端结果不得以本地进程退出代替。独立客户端 HTTP MCP 使用明确的 ExternalClient 来源，保留其既有边界，不借用另一 Direct 回合的预算。
+- 交付必须先封口、排空和取得执行器退出证明，再核对当前文件并提交完成；Windows 用自有 Job 约束进程树，托管命令在恢复主线程前绑定。完整退出证明不足时保持未完成，不把模型最终回复当作验收。非阻塞扩项进入新的用户回合。
+- 模型配置、实际请求标识和流分段耗时写入现有审计账本；统计采用并发区间并集，有界后台写入，详细条目截断后仍聚合。上游内部排队和推理耗时不可见时保持未知。
+- Direct 工具集中 SDK 原生 `apply_patch` / `update_plan` 是全局串行单例，按回合为每个 Direct 连接导出一份只把 `apply_patch_tool_type` 置空的完整模型目录即可移除该注册；其余 metadata、匹配与 fallback 不变，不得伪造 `readOnlyHint` 或改造 SDK。等价能力由宿主 MCP 的 `agc_apply_patch`（官方 parser、当前回合 Write 许可、受控进程树、短项目事务）与 `agc_update_plan`（宿主计划状态，不作为验收证据）提供；缺少合法回包通道的原生问答工具一并关闭。
+- 捆绑 Codex 固定版本只在 `build_support/codex_bundle.rs` 声明一次（当前 0.155.1），构建期侧车清单、宿主补丁执行器身份、逐次审批协议允许列表和模型目录捕获共同引用；升级原生依赖时同步重取同一 tag 的 vendor 解析源码与 UPSTREAM 证据，并复跑真实目录、补丁往返与并发夹具。0.155 起原生执行入口改为统一 exec（`exec_command` + `write_stdin`，旧 `shell_command` 不再注册），宿主许可与预算照常覆盖。
+- 付费许可按原回合原租约绑定并传递到实际提交点：容量与同动作锁等待可取消，每次新增 POST 前与封口共用短锁复核，封口/终止/耗尽后零新增提交；已越过提交边界的请求不丢弃，保留 operation ID 与不确定状态走 GET 对账。本地写入同理，等待项目锁后必须复核原许可，未结算或失败的写入围栏未恢复前不得封口。
+- 权威合同：[AI 游戏创作智能体 App 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
+
+## 2026-09-20 最近项目检查保持项目级隔离
+
+- 背景：最近项目刷新会重新检查所有路径。若其中一个目录损坏、超时或不可读，清空整张状态表会让已确认正常的项目暂时全部显示“检查中”，用户只能移除坏项目后看到列表恢复。
+- 决策：最近项目状态按路径独立投影；刷新时保留仍在列表中的最后一次结果，只有新增或尚未检查的项目进入“检查中”。检查代次或列表成员变化后，迟到结果不得写回，单个项目的失败不能改变其它项目的可打开状态。
+- 验证：`recentProjectsHook.test.tsx` 覆盖“新增慢/坏项目刷新时保留正常项目”；`recentProjectsModel.test.ts`、`unityProjectOpen.test.tsx` 与前端类型检查一并执行。
+
 ## 2026-09-17 GameCreationApp 资源 kind 只保留一份词汇表：严格解析 + `app_log!` 留痕
 
 - 背景：kind 曾经有三份实现——Rust 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `canonical_game_creation_app_asset_kind()`（带 legacy 别名表与 `font → document` 特例）、TS 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `GAME_CREATION_APP_LEGACY_ASSET_KINDS` + `canonicalGameCreationAppAssetKind()`、以及 ts-rs 生成的 TS union。两份手写表互相引用又各自收口，判据直接分叉（同一个 `"UI"` 一边归一成 `ui-design`、一边收口成 `unknown`），跨语言一致性只能靠正则解析源码的测试来钉。
@@ -22,7 +116,6 @@
 - 决策（无写副作用）：只在生成本轮 prompt 时展开该上下文；历史 item 回读走 `direct_codex_user_item_to_response_item` 的纯投影，不得触发 UI 代码导出或任何项目写入。
 - 验证：`agent::direct_codex_user_item` 定向 16 条通过，覆盖成功注入、生成失败保留引用摘要、非 UI 文档不触发与历史回读不产生 `ui/generated-*.js`。
 
-
 ## 2026-09-19 AGC Direct 删除每回合四项媒体资源请求上限
 
 - 背景：2026-08-24 引入的单回合四项上限以「整个 agent run（一条用户消息到回合结束）」为窗口，计数只增不减、请求完成不释放额度；autonomous 游戏构建要求 agent 不停下跑完整局，额度耗尽后的报错实际是终态，与技能的三次重试纪律冲突，现场表现为长时间无效重试。2026-09-18 先将不计费的抠图豁免，但付费 create/derive 仍受同一窗口问题影响。
@@ -36,6 +129,24 @@
 - 决策：`agc_remove_background` 不再经过 `resource_request_ids` 计数，直接按回合身份与请求指纹确定性派生 operation/idempotency id（与 map 复用结果一致），同指纹重试与 pending 对账语义不变。付费的 create/derive（含 `agc_edit_image` 委托）维持四项上限与原有报错文案，且抠图请求不再挤占其额度。
 - 验证方式：`cargo check`（ai-game-creator-shell src-tauri）与 `git diff --check` 通过；未新增测试。
 
+## 2026-09-18 AGC 未提交快速编辑草稿按资源路径归属，正式恢复账本不动
+
+- 背景：画布验收项 AGC-006/023 要求「点外部 / Esc 收起面板、或换素材卡」不再无条件丢弃用户刚写的提示词与 `@` 引用，于是宿主内存里多了一份未提交草稿表（`resourceCanvasQuickEditModel.ts` 的 `ResourceQuickEditDraftStore`），与原生 `list_pending_local_project_resource_edits` / `resume_local_project_resource_edit` 那条正式可恢复账本**并存**。
+- 决策：草稿键是投影的稳定身份 `ProjectResource.path`，不是投影 id。资源投影本来就按 path 去重（`resourceProjectionModel` 的 `uniqueByPath`），而 id 会变——任务产物经 `normalize_local_project_raster_resource` 登记成正式素材后，同一张卡从 `task:<任务>:<路径>` 变成 `asset:<id>`。用 id 当键时，任何**不是打开中这一笔快速编辑自身触发**的重投影（换素材卡收起面板、Agent 或外部编辑器把同一路径登记成资产）都会让草稿落到再也点不到的键上：恢复入口按 id 过滤后静默丢弃、重开面板按新 id 查不到。按路径归属后不需要任何「跟着投影搬家」的换键逻辑，那条逻辑本身就是搬丢的来源。
+- 决策：本地草稿是**会话内存态**——不落盘、不进账本、不参与对账；共享入口「管理未完成编辑」同时列出来源不同的两种条目，草稿条目显式标注「本会话未提交，关闭客户端不保留」，账本读取失败时仍报出本会话草稿条数，避免用户把两者当成同一种持久事实。
+- 决策：`ResourcePromptPolishSlot` 与共享聊天输入区（`ResourceReferenceInput`）共用 `usePromptPolish`；「与原文相同」以**规范化之后要写回宿主的文本**为准（回包被长度上限截回原文同样算没变化），此时不落原文快照、不回填宿主，只给提示，避免出现点了等于没点的「恢复原文」假入口。
+- 边界：发送前提醒面板里「AI 润色并发送」遇到原样回包仍按用户意图直接提交，本轮按产品取舍保留（记录在 `docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md`）。
+- 落地：`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasQuickEditModel.ts`（工厂空表 / 按路径写入读取丢弃 / `listResourceQuickEditDraftEntries`）、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`（草稿接线与恢复入口）、`apps/ai-game-creator-shell/src/features/resource-canvas/ResourcePromptPolishSlot.tsx`、`apps/ai-game-creator-shell/src/features/project-workspace/{usePromptPolish.ts,ResourceReferenceInput.tsx}`；回归见 `tests/resourceCanvasQuickEditModel.test.ts`、`tests/resourceCanvasQuickEditDraft.test.tsx`（含「面板收起后旁路重投影」用例，改回 id 作键即红灯）、`tests/usePromptPolish.test.tsx`、`tests/resourcePromptPolishSlot.test.tsx`、`tests/chatPromptPolish.test.tsx`。
+
+## 2026-09-18 派生资源名称在前端镜像 Rust 门禁，宁可按原话拦下也不截断
+
+- 背景：快速编辑（`-编辑版`）与角色动画（`-角色动画`）的派生资源名由前端按源资源 label 拼出，直接进 `derive_local_project_resource` 的 `input.assetName`；Rust `normalize_resource_edit_name`（`resource_editor.rs:802-808`）要求 `trim` 后非空、码点数 1..=120 且不含控制字符，任一不满足即整条请求失败。源 label 取任务标题（Agent 回执）或长生成文件名时，用户必须提交一次才看到「派生资源名称必须在 1..=120 字符内且不能包含控制字符」。这是画布验收遗留项 AGC-025 的成因之一。
+- 决策：前端只做镜像，不另造中文语义——上限 120、`Cc` 控制字符判定（C0 / DEL / C1，`Cf` 继续放行）、`trim` 后判空、按 Unicode 码点计长（Rust `chars().count()`，不是 JS UTF-16 `.length`）四条与 Rust 逐条对齐，提示文案与 Rust 返回串逐字相同；两份判定由跨语言测试直接读 Rust 源码对表。
+- 决策：名称不合法时**阻止并提示**，不截断。截到 120 会让同前缀的两个长源名塌成同一个名字，把一次可见失败换成一次静默重名；默认名函数因此保持返回不合法原名，由检查结果里的 `error` 让调用方先停下。
+- 落地：`apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts` 的 `RESOURCE_EDIT_NAME_MAX_LENGTH` / `RESOURCE_EDIT_NAME_INVALID_NOTICE` / `resolveResourceEditNameCheck` / `resolveDerivedResourceNameCheck(resource, 'edit' | 'character-animation')`，纯函数与跨语言对表见 `tests/resourceEditModel.test.ts`；两种后缀共用同一张后缀表，避免「-编辑版」与「-角色动画」再次分叉。
+- 接线：`index.tsx` 的 `submitResourceQuickEdit` 与 `submitResourceCharacterAnimation` 都在**调 `resolveResourceDeriveSource` 之前**做检查（正规化写盘发生在那一步之后），不合法时只把 `status: 'failed'` 与 Rust 原话写进各自的浮层面板并 return，不发派生请求；`assetName` 用检查结果里的 `name`。回归见 `tests/projectResourceLiveIntegration.test.tsx` 的两条「源名超 120 码点」用例与既有的合法名校验 `source-art-编辑版` / `hero-角色动画`。
+- 边界：资源画布的图片类生成走另一条门禁（`commands.rs` 的 `LOCAL_PROJECT_ASSET_MAX_ASSET_NAME_CHARS`，文案「素材名称超出安全边界」），不在本条口径内；提示词上限仍是 `resourceEditPromptMaxLength` 那一份，本决策不动它。
+
 ## 2026-09-18 Provider 瞬态重试次数严格按设置执行（游戏开发 Agent 与策划 Agent 不再被档位收进区间）
 
 - 背景：AGC 客户端此前把 `agentLlm.<agent>.maxRetries` 按运行档位重新收进固定区间——`autonomous-game-build` 档位（自主构建的游戏开发 Agent 及其继承档位的专业子 Agent）被抬到 12~16，`standard` 档位（含立项策划入口的策划 Agent 与普通 Agent 对话）被压到最多 3；瞬态分类里的上游 400 还在同一预算上再收窄到 2 次。现场把 `maxRetries` 设成 5 时，游戏开发与策划两条链路都不按设置执行。
@@ -49,6 +160,7 @@
 - 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
 - 决策：抠图请求及工具回执统一使用 `prepare_external_canvas_generation_context` 返回的远端 `context.project_id`；本地 manifest 项目 ID 只用于绑定键和本地状态，不得作为主站业务请求的 `projectId`。
 - 验证：客户端定向 Rust 测试、格式、编码和 diff 检查通过；未修改主站路由或 BgFilter。
+
 ## 2026-09-17 图集切分模式改为显式声明
 
 ## 2026-09-17 DirectProject 首屏历史锚点只认订阅回执的 lastCompletedItemId
@@ -70,6 +182,7 @@
 - 标准美术包：客户端显式声明 `sliceMode=connected-components` + `sliceCount=4`，本地按用途位置写四张 canonical 切片前再次校验数量正好为四，数量不符时失败关闭，禁止截断或补位。
 - 测试环境：在提权 shell 的 Windows 主机上，`%TEMP%` 下新建目录的默认所有者是 `BUILTIN\Administrators` 而不是当前 TokenUser，AGC 的所有者校验会拒绝测试自己创建的项目根；测试构建对该情形（仅限 `%TEMP%` 内、且失败原因为所有者不匹配）先按“本调用创建的对象”初始化所有者后重试，临时目录之外的越权所有者继续失败关闭。
 - 权威合同：[画板图标素材生成入口设计](../../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
+
 ## 2026-09-17 `agc_tools` 媒体资源提示词上限收敛为单一口径，并按 kind 暴露给模型
 
 - 背景：有人反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。核查后工具本身都在（`agc_edit_image` / `agc_create_or_derive_resource`），图片快速编辑在 2026-09-14 的真实项目日志里也有成功记录；但存在三类真实缺陷：① `agc_create_or_derive_resource` 的 `prompt` 在 schema 里只声明 4000，真实上限却是按 kind 分的（背景音乐 140、音效 1900、视频/角色动画 4000、图片 32000），MCP 层还额外写死了一条 140 判断，模型从 schema 与 skill 都看不出 140/1900，写一句正常长度的背景音乐描述就当场被拒；② 客户端 UI 用同一口径但会截断并提示，agent 侧却只有硬拒，形成「UI 能做、agent 调不动」的观感；③ `sourceLocalAssetId` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
@@ -167,7 +280,7 @@
 - 决策（槽身份 = 精确动作身份）：`run_id = slot-<sha256(动作身份材料)>`，材料为 `prompt / output_path / aspect_ratio / image_size / asset_kind / asset_label / replace_existing / require_slices`（`canvas_generation.rs`）。不同 prompt 或素材名 → 不同槽 → 不同进程锁键与不同 `.lock` 文件 → 可同时在途。**不用随机 uuid**：随机身份会让「同一精确动作重放」落到新路径，必须再造一层 action→ledger 索引才能保幂等；用动作指纹让「槽身份 ≡ 精确动作身份」，路径查找即幂等查找。
 - 决策（幂等不变）：同一精确动作 → 同一路径 → 命中已有 prepared/accepted 账本并复用原 `idempotencyKey` / `operationId`，不二次 POST；相同动作并发仍被拒的既有语义保持。
 - 决策（旧槽账本最小懒迁移）：旧槽账本形状可读、不 panic、不 fail-closed；在 durable guard 之后、任何远端 POST 之前，**仅当**旧槽账本的 `agentId / runId / actionFingerprint` 与本次精确动作一致时，把它迁移到新路径（保留 `idempotencyKey` / `operationId` / 状态）并删除旧文件；属于其他动作的旧账本一律不动。旧「固定槽」（`run_id == agent_id`）账本的 fail-closed 拒绝保持原样。
-- 已知边界：`slice_count` **不进**身份（保留升级前粒度，也是旧账本迁移可行的前提）→ 仅切片数不同的两条图集请求仍共槽、第二条失败关闭；当前所有 standalone 槽的生产调用方都把 `slice_count` 传成 `None`（唯一能传 sliceCount 的是 agent 工具通道，它不走 standalone 槽），该边界当前不可达，但**缺负向用例**。
+- 当前身份边界：精确动作指纹包含 `slice_count`，Agent 图片工具同样使用 standalone 动作槽；不同精确动作可并行，同一动作在容量排队前持有原跨进程槽锁。不得再依据早期“Agent 不走 standalone 槽”的说明拆除幂等或重复提交。
 - 前端口径：本批**仍保留单条在途的前端排队**（提交节流），真并行派发需要并发收口设计（配对读 + manifest CAS + 聚焦意图互不覆盖），留待下一批。
 - 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`、`.../external_generation_state.rs`。**未改** `/api/external/v1` 契约 / OpenAPI / DTO，未改 `recovery_scan.rs`（身份白名单与孤儿清理语义不变），账本 schema 仍是 v3、字段集不变，只改 `runId` 取值来源。
 - 验证方式：新增 `standalone_generation_binds_each_exact_request_to_its_own_stable_slot`、`distinct_standalone_actions_hold_independent_durable_output_slots`、`concurrent_distinct_standalone_generations_both_succeed_with_one_post_each`（端到端：两条 `outputPath=None` 的不同动作要求两条 POST 同时到达，各自 poll → read-url → 下载 → 落盘）、`legacy_output_slot_ledger_is_adopted_by_the_same_exact_action_only`。变异验证（已实测）：把 `run_id` 退回旧公式 → 4/4 红（含「durable 输出槽身份必须等于该精确动作的身份」与并发用例的「任何远端 POST 前拒绝并发请求」）；把懒迁移短路 → 旧账本用例红。定向 `agent::generation::` + `recovery_scan` 95 passed、`direct_runtime media` 195 passed。
@@ -188,6 +301,7 @@
 - 决策：图片类生成接线改为 `start_local_project_asset_generation` + `list_local_project_asset_generations` 后，同步命令 `generate_local_project_asset` **已无生产调用方**，只剩 `src-tauri/src/tests/project.rs` 的三条集成用例与 `commands.rs` 的自身单测在调它；因此登记进 `scripts/check-config.mjs` 的 native-only 白名单（该门禁有「App invoke 与白名单互斥」断言，谁重新给它接调用方就必须同时删掉这条白名单项）。
 - 待办：它是**注册中的可调用 IPC**，一旦被将来代码调用就是一条绕过任务账本、单次阻塞最长 35 分钟的并行生成路径。下一批次应删除它，或改为转调 `start_local_project_asset_generation`（连带迁移那三条集成用例）。
 - 关联文档：[栏目画布底部工具栏入口矩阵](../../technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)。
+
 ## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，客户端 Rust 关键路径压到 7 分钟以内
 
 - 背景：`AI game creator shell Rust tests` 是客户端 CI 的关键路径（run 2097 实测 15 分 27 秒）。拆开来看：前置 5 分 30 秒（checkout 10s + `npm ci` 2m45s + Cargo fetch 2m35s）、编译 1m39s、**AGC 壳 bin target 的 2466 条单测串行 507s**、`agent-run` smoke 51s。这 2466 条全在 `apps/ai-game-creator-shell/src-tauri` 的 bin target 里，一条 `cargo test … -- --test-threads=1` 跑完。
@@ -200,6 +314,13 @@
 - 影响范围：`.gitea/workflows/project-ci.yml`（十一个 job）、`scripts/check-native-shells.mjs`（分组由五个到十个：新增 `agc-rust-crates`、`agc-rust-shard-1..4`、`agc-rust-smoke`，移除 `agc-rust` 与随后的 `agc-rust-shell`）、根 `package.json`、`scripts/project-ci-workflow.test.ts`（新增纯 cargo job 免 `npm ci`、分片运行器覆盖校验、crate 级 job 预热顺序断言）、开发运维文档与共享记忆。本仓库不把 Project CI 的 context 配成 `master` 分支保护的合并必需检查（2026-09-14 复核），合并前由人工确认结果，因此 job 拆分/改名不需要同步分支保护设置。
 - 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`；分片运行器本地以 `agent-runtime-core`（7 条 → 2/2/2/1）与 `platform-llm`（146 条 → 49/49/48）验证分片、`--exact` 与片 TMPDIR 隔离，负例 `--shard-index=5` 立即失败；`node scripts/check-native-shells.mjs --groups=contract` 回归。预期每个分片 job 收敛到 5 分钟以内（前置约 1 分 30 秒 + 编译约 1 分 39 秒 + 约 617 条用例）。
 - 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-20 AGC Rust 分片收敛为两条 lane，匹配 runner 有效并发
+
+- 背景：四个独立 shard job 让每个 job 重复 checkout、Cargo 依赖预热和测试二进制编译；Gitea run 2105 的 11 个 job 时长合计约 39 分钟，而整轮 wall-clock 为 20 分 23 秒，反推有效并发约 1.9 个 job。继续按「一片一 job」拆分已经把新增 job 开销和排队时间重新放回关键路径。
+- 决策：保留 4 片名单、`--test-threads=1`、独立 `TMPDIR` 和每片的全集/互斥校验，但把 workflow 收敛为两条 Rust lane；lane 1 顺序运行 shard 1/4、2/4，lane 2 顺序运行 shard 3/4、4/4。每条 lane 只预热一次 AGC 壳 manifest，lane 之间仍保持 job 级并发；不在同一 job 内并行多个测试进程。
+- 影响范围：`.gitea/workflows/project-ci.yml`、`scripts/project-ci-workflow.test.ts`、`scripts/check-native-shells.mjs` 与 Rust 分片说明文档。job 名称改为 `AI game creator shell Rust lane 1/2`、`lane 2/2`；分组脚本与 4 片测试名单保持不变。
+- 验证方式：运行 `npx vitest run scripts/project-ci-workflow.test.ts`、`node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`、`npm run check:encoding` 和 `git diff --check`；真实 Gitea run 需要确认两条 lane 均覆盖两片且 smoke、crates、Backend、Native、Frontend、Repository job 仍全部上报。
 ## 2026-09-14 AGC 资源画布改为「手动整理」：新素材不再自动重排，整张重排只由「整理画布」发起
 
 - 背景：生成一张新素材会让整张资源画布重排。两个 layout hook 都把 `rederiveAutomaticPositions` 打开（type 侧无条件 `true`，dependency 侧长期等于 `resourceGraphReady`），而该开关的语义是「每次资源协调签名变化就丢掉全部 `manuallyPlaced=false` 坐标、按当前资源与拓扑整体重算」；新增一张素材必然改签名，于是既有自动卡全部跟着挪位，用户刚记住的位置就没了。画布上也没有任何显式整理入口（`复位资源视图` 只复位视口）。
@@ -223,7 +344,7 @@
 
 - 决策：待实施的生产迁移以自由协作策划原型为行为基线，仅复用 Provider、恢复、文件操作、审计和 UI 通信；不继承旧 Planning V2 的强制工具、问询轮数、GDD 内容校验和版本审批。保留五阶段与顾问态、当前阶段资源注入和产物存在性检查，系统阶段空必需清单不增加解析或登记功能。
 - 交互边界：正式审批由 ✅/❌ 决定；❌ 只取消待审批、不唤醒 Agent，等待审批时禁止发送消息但允许浏览工作区。用户可直接查看工作区，编辑可暂不做，不引入用户与 Agent 协同编辑锁或冲突合并。
-- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；实施中。无旧 Planning V2 会话的策划项目走新设计 Agent，已有 V2 会话仍走原链路。
+- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；迁移已完成。当前入口统一使用新 Design Agent，旧 Planning V2 会话不再继续运行。
 - 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
 
 ## 记录格式
@@ -8855,11 +8976,12 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（423 passed，含新增 6 条：栏目分流与总览不渲染、UI 栏 5 个入口载荷、前置缺失可点击说明且零请求、角色栏 2 个入口、音频入口走既有链路、上传 + 配对读清单，另 1 条工具栏与 Dock 的 CSS 几何契约）；`resourceCanvasBottomToolbar.test.tsx` 15 passed（新增）；`resourceCanvasGenerationEntry.test.tsx` 11 passed（新增单类型用例 1 条）；`projectResourceLiveIntegration.test.tsx` 25 passed（「生成素材」面板改名断言同步更新）；`npm run agc:typecheck` 全绿（**其中的 `check-config.mjs` 报错已因本轮落地调用方而消失**）、`npm run check:encoding`、`git diff --check` 干净。未 commit。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9 / §8）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11 / S11a / §7.3）。
 
-## 2026-09-13 Cocos 插件按当前项目类型暴露
+## 2026-09-20 Cocos 与 Unity 插件独立于工程类型
 
-- 决策：`agc-cocos-editor` 只有在当前受控项目通过 Cocos Creator 根目录识别（`package.json.creator.version` + 普通 `assets/`）时才暴露插件、面板和 Cocos 工具；无项目或其它项目类型均隐藏并失败关闭。
-- 决策：项目切换离开 Cocos 时立即停止已运行的插件实例；启动、面板读取、插件 RPC、Runtime execute 和 DirectProject MCP 工具目录/执行入口全部再次校验项目类型。Cocos 编辑器操作优先经内置插件入口，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
-- 验证：新增 builtin/plugin host 项目级门禁测试，Direct MCP fixture 补最小 Cocos 工程结构；Rust 定向测试、显式 `cocos-editor-execute` feature 编译、编码检查和 `git diff --check` 已执行。
+- 决策：`agc-cocos-editor` 与 `agc-unity-editor` 的插件列表、启动、面板、插件 RPC、Runtime 与 DirectProject 工具暴露不按当前工程类型过滤；无项目、普通 AGC、Godot、Cocos、Unity 上下文遵循同一套 enable、原生适配器、平台与 feature 规则。前端根据宿主列表中各插件状态分别自动启动，不按项目类型二选一，也不自动展开面板。
+- 决策：跨工程类型切换保留插件实例及管理能力，继续更新受控项目上下文、失效旧连接并隔离旧请求回执。实际编辑器操作仍要求当前受控项目匹配真实引擎工程与编辑器目标；显式跨项目路径、缺失项目、无目标进程、身份或握手不匹配均在派发前失败，权限、并发、期限与执行不确定阻断保持有效。
+- 边界：插件可见和工具可调用不能证明任意非引擎目录可成为编辑器执行目标；不改变项目类型、导入或持久数据。Cocos 编辑器操作继续使用内置插件，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
+- 验收口径：分别取得宿主/内置开关、工具目录、前端启动投影与真实目标拒绝证据；真实编辑器、安装包和 CI 与定向测试分层报告。
 
 ## 2026-09-14 DirectProject Codex 取消路径白名单并启用完整 sandbox
 
@@ -8886,7 +9008,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 影响范围：新增 `apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`（+ `main.rs` 注册）、`src/features/resource-canvas/{resourceCanvasAssetGenerationTaskModel.ts,resourceCanvasAssetGenerationQueue.ts,ResourceCanvasAssetGenerationTasksPanelView.tsx}`；改动 `ResourceCanvasAssetGenerationPanelView.tsx` / `ResourceCanvasGenerationPanelView.tsx` / `src/view/project-development/index.tsx`；测试改动 `tests/{resourceCanvasAssetGenerationBackgroundClose.test.tsx,resourceCanvasAssetGenerationQueue.test.ts,resourceCanvasAssetGenerationTasksPanel.test.tsx}`（新增）与 `tests/appSurface/project-development.suite.ts`（把「每个入口一次 `generate_local_project_asset`」改成 `start_local_project_asset_generation` + `list_...` 轮询桩，载荷断言逐字不变）。**未动**：external v1 / OpenAPI、`packages/`、SpacetimeDB、音频入口的 pending-edit 账本语义、生成参数与 IPC 载荷字段名。
 - 关联文档：`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（§4 / §4a / §8）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11a / §7.3）。
 
-
 ## 2026-09-15 非 Suno 的 VectorEngine 能力切换到 Tiantoken
 
 - 决策：新增本地私密环境变量 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`（图片 timeout 可独立配置），承载原 VectorEngine 的文本和图片；`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 仅保留给 Suno 背景音乐与 Suno 音效。编辑器 SFX V2 继续走 ElevenLabs。
@@ -8911,6 +9032,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：平台会话拆成身份（`userId + api origin + identity generation`）与凭据（当前 access token）。identity generation 只在登录、切号、登出或新的 GUI authority epoch 推进；同账号续期只更新凭据并推进只用于拒绝迟到写入的 revision。冻结会话校验、MCP 会话身份与 Runner attach 统一按身份判定，换号 / 退出仍然失败关闭。刷新失败只在服务端明确 401/403 且一次收敛重试后仍失败时清会话；`/api/auth/refresh` 的轮换失败不再下发清空 refresh cookie 的响应。
 - 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-16 平台会话身份与凭据分离”；开发期计划见 `docs/project-memory/plans/【里程碑】平台会话身份与凭据分离-2026-09-16.md` 与对应实施计划。
 - 验证：AGC `platform_session::tests`、`runner::tests`、`assets::tests` 定向通过；AGC `appSurface` 前端套件 468 项通过；网站 `src/services/apiClient.test.ts` 33 项通过；`cargo test -p api-server refresh_session` 通过。项目夹具类 Rust 用例受本机临时目录属主为 `BUILTIN\Administrators` 的环境限制，未计入本次证据。
+
 ## 2026-09-15 Direct 回合跨页面继续运行与活动项目面板
 
 - 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
@@ -9009,3 +9131,51 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：`pick_local_project_directory` 增加可选 `title`（限 24 字符、无控制字符，其余回退默认标题），使「选择项目创建目录」不再冒用「选择游戏项目目录」文案。
 - 关联规范：`docs/project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`。
 - 验证：`cargo test --bin genarrative-ai-game-creator-shell creation_root`（2 项）、模板库定向单测 14 项、偏好模型 3 项、`appSurface` 472 项（含设置页「工作区」选择/恢复目录与「设置里选目录后建项带 `projectsRoot`」两条场景）、`tsc`、`check:encoding` 与 `check-doc-index` 通过。
+
+## 2026-09-20 Rust 工具链升到 1.98.1：仓库侧四处同步 + runner 镜像必须重建
+
+- 背景：macOS 27（CLT for Xcode 27.0）冷构建时 proc-macro dylib 被链接成畸形 Mach-O（`mis-aligned LINKEDIT string pool`），上游 rust-lang/rust#157750 已修复，而仓库锁的 stable `1.96.0` 仍复现（Issue #431）。
+- 决策：根 `rust-toolchain.toml` 的 channel 由 `1.96.0` 改为 `1.98.1`；`deploy/container/gitea-ci-job.Dockerfile` 的 Rust stage 由 `rust:1.96-bookworm@sha256:19817ead…` 换成 `rust:1.98-bookworm@sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`（按 registry 配置实测该 digest 的 `RUST_VERSION=1.98.1`，与 channel 逐字一致）。
+- 决策（版本标签）：镜像 tag / label 一并从 `20260807.1`、`2026.08.07.1` 升为 `20260920.1`、`2026.09.20.1`（同一次核对发现 Dockerfile 里有两处 `org.opencontainers.image.version`：一处 `2026.07.23.1`、一处 `2026.08.07.1`，后写的覆盖先写的，本次一并统一为 `2026.09.20.1`）（`scripts/gitea-ci-job-image.sh`、`deploy/container/gitea-ci-job.Dockerfile`），`deploy/container/README.md` 与开发运维文档同步 digest、Rust 版本和归档示例名。镜像内容变了却沿用旧 tag，排障和回滚都会认错版本。
+- 不变口径：镜像继续 `RUSTUP_AUTO_INSTALL=0`，job 现场不下载工具链；`scripts/check-gitea-ci-job-image.sh` 仍按 `rust-toolchain.toml` 的 channel 逐字校验镜像内工具链名，所以基础镜像的 `RUST_VERSION` 必须与 channel 完全相同。`std::os::windows::fs::MetadataExt::number_of_links`（rust-lang#63010）在 `1.98.1` 上实测仍未稳定，`#[cfg(windows)]` 侧继续使用自行声明 `ByHandleFileInformation` 的实现。
+- 新增护栏：`scripts/project-ci-workflow.test.ts` 增加一条一致性用例——Dockerfile 的 `ARG RUST_IMAGE` 版本段必须等于 `rust-toolchain.toml` 的 channel 主次版本、其 digest 必须同时出现在两份运维文档里、镜像 tag 日期戳必须与 Dockerfile 的 `org.opencontainers.image.version` 一致，避免本次这种「改了 Dockerfile 忘了文档」的漂移。
+- 待办（不在本次仓库改动内）：在 station 上执行 `build / verify / export / load-runner`，备份 runner config 后把 `genarrative-ci` 映射切到新 Image ID 并 `docker restart --timeout 660 gitea-runner`；内层只有 1.96 时 PR 的 job 必然失败。macOS 与 Windows AGC 构建机（`jenkins/Jenkinsfile.ai-game-creator-shell-build`，preflight 只校验 rustc/cargo 是否存在）需确认已装 `1.98.1`，macOS 冷构建是本次问题的原始验证目标。`deploy/container/api-server.Dockerfile` 的 `FROM rust:1.93-bookworm` 是另一处未加 digest 的 Rust 版本 pin，本次未动。
+- 验证：分支 `chore/rust-toolchain-1-98` / PR #432；`npx vitest run scripts/project-ci-workflow.test.ts`、`npm run check:encoding`、`git diff --check` 通过。Windows：`1.98.1` 下 `npm run agc:build -- --debug` 的前端构建、Rust 编译与 NSIS 安装包生成成功（见 PR 描述记录）；macOS 与镜像重建后的 CI 结果仍待验证。
+
+## 2026-09-20 AGC 客户端版本号收敛为单一发号源
+
+- 客户端版本号唯一事实源改为 OSS `agc/global-version.json`；渠道清单只写本次拿到的号，仓库里 5 个版本文件只作构建输入参考。
+- 发号顺序固定「先写总号 → 再构建 → 再发渠道清单」，失败不回滚只烧号；统一构建发一次号供 `dev-win` / `dev-mac` 共用，单渠道热修只作用于该渠道。
+- 发号收口到 Jenkins Job `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()`；集群无 `lockable-resources`，以写后回读不一致即失败关闭兜底并发）。
+- 原渠道高水位逻辑降级为断言：请求号低于本渠道清单版本即失败关闭；`AGC_RELEASE_DRY_RUN` 只预览不烧号。
+
+## 2026-09-20 AGC 音频生成并入图片类那份后台任务账本
+
+- 背景：音频栏目的「生成背景音乐 / 生成音效」原先走同步派生通道（`derive_local_project_resource`），提交后前端一直等到生成结束（最长 35 分钟），所以它不出现在画布「生成任务」侧栏里，也没有本地排队；图片类早已改成「提交即返回 + 项目内任务账本」。
+- 决策：音频改走**同一条命令** `start_local_project_asset_generation`（新增可选入参 `idempotencyKey`，音频 kind 必带）；原生在 `kind` 上分叉一次（`is_audio_asset_generation_kind` 只放行 `sound-effect` / `background-music`），音频分支落**同一份**项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`，生成由 `run_local_project_audio_generation_task` 在后台跑并写 running → completed / failed。图片类载荷与分支逐字未改。
+- 决策：音频的**任务 id 就是这次生成的 operation id**，请求身份 = 面板铸造的 `operationId` + 幂等键。重试（含失败后点占位重开）必须复用同一对，否则会同一次生成变成第二次付费请求。账本不存幂等键，所以重开项目恢复出来的音频任务只用于展示与定位，不承接重试。
+- 决策（UI 口径）：音频面板与图片类一致——点「生成」**同步关闭**，面板里不存在「排队中。」「正在生成。」「提交中…」与「后台运行并关闭」这类阶段文案与在途按钮，阶段文案的唯一来源是后端账本、唯一去处是「生成任务」侧栏。只有「点击瞬间就失败」（校验 / 权限 / 提交 IPC 立即报错，即后端从未受理）才由宿主把面板连原草稿与原请求身份带回来；受理之后才失败只在侧栏收口为失败。
+- 决策（时机）：项目 revision 的 CAS 由「提交前读」改为「派发时刻读」（`run_local_project_audio_generation_at`）；冲突按失败收口，不静默重试，避免把生成写到用户没预期的基线上。
+- 不变口径：平台侧 `/api/editor/audios/*/generations` 路由、请求体、计费与 `/api/external/v1`、OpenAPI、共享 DTO、SpacetimeDB schema 一律未动；音频仍复用既有资源编辑派生实现，不复制生成逻辑。
+- 关联规范：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/project-memory/plans/【里程碑】AGC音频生成进入后台任务账本-2026-09-20.md`。
+- 验证：9 个定向 vitest 文件 73 项、`appSurface.test.ts` 552 项（17 跳过）、`cargo test asset_generation_task` 14 项、`npm run agc:typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 全部通过；未跑真实付费生成。
+
+## 2026-09-20 派生/修改类任务并入「生成任务」侧栏（AGC-039 / AGC-040）
+
+- 背景：客户端验收现场，快速编辑提交后画布右上角「生成任务」全程是「还没有生成任务」，同一条草稿又还挂在「管理未完成编辑」里，用户据此判断「点了没生成」；随后同一次修改被重复提交，同一张源图派生了两份一模一样的「-编辑版」。
+- 决策（取数）：派生/修改类任务（快速编辑、生成动画、视频 / 音效 / 背景音乐、抠图）进图片类生成任务**同一个**「生成任务」侧栏，数据源 = 原生资源编辑账本 `list_pending_local_project_resource_edits`（重开项目、别处提交、阶段文案以后端为首）+ 本会话**本地提交记录**（按下提交当帧即可见），两边按 `operationId` 合并去重。**不改**原生资源编辑账本 schema，也**不**把派生任务写进图片类生成账本 `.agent/runtime/asset-generation-tasks/tasks.json`——两套账本各管各的事实，只在视图层合并。
+- 决策（草稿口径）：提交进行中的那一笔不再列进「管理未完成编辑」；失败回落自动把它还回未完成列表，提示词与 `@` 引用不丢。
+- 决策（重复提交）：同一张素材存在在途提交时，重新打开面板再提交会被拦下（可见原因），不重铸 operation 身份。**未做**「同提示词成功后再提交」的去重——那是用户显式重复的付费动作，本批只消除误触来源。
+- 理由：用户对「生成」的心智是「交出去就得能看见它在跑」，而不是必须区分两条账本；而防重复必须在**身份重铸之前**拦，等到原生账本判重时已经派生过一次。
+- 验证：新增模型用例 9 条、快速编辑两组宿主用例（提交当帧进侧栏并收口 / 在途重复提交被拦），两处新判据做过变异验证；定向 7 个文件 97 条全绿。
+- 口径更正（2026-09-21）：当时记的「`appSurface` 16 条既有失败」是**从 `apps/ai-game-creator-shell` 目录跑**造成的 cwd 假红（`resolve(process.cwd(), 'apps/…')` 路径翻倍 → ENOENT），不是用例本身红。规范跑法是仓库根 `npm test`；现已用 `tests/repoPath.ts`（按 `import.meta.url` 反推仓库根）修掉 19 个文件的同类写法，从仓库根跑 `appSurface` 为 0 失败。远程 CI 与真实客户端验收仍未跑。
+
+## 2026-09-21 卡片浮层改为「提交即关」：快速编辑 / 生成动画只负责交任务
+
+- 背景：客户端验收反馈——「生成动画」这类卡片浮层在失焦时不会收起，而且这块的关闭判据一直是东一处西一处拼的（点画布空白、换选中卡、Esc、点画布以外各有一条）；动画面板在生成中还会被「生成中不关」判据锁在画布上。产品口径澄清：生成都归「生成任务」侧栏，**卡片浮层只用于提交任务，提交完生命周期就结束**。
+- 决策（提交即关）：快速编辑 / 生成动画点提交当帧即关面板，不等 IPC、不留等待态；阶段与结果只由「生成任务」侧栏承载（本地提交记录 + 原生待办按 `operationId` 合并，见 2026-09-20 那条）。只有**点击瞬间就失败**留在面板里；**受理之后才失败**把侧栏收口为失败 + 提示条并回落草稿，不重开面板。
+- 决策（身份跟着资源走）：按「入口 + 资源路径」记最后一次派生请求（`resourceEditRequestKey`）。重开面板再提交时提示词没变就沿用同一 `operationId` / 幂等键，重试仍命中同一 operation 账本；派生成成功即清掉，下一次编辑是新的一笔。原「按上次打开的 sourceLayerId 复用」在提交即关之后不再成立（面板重开时层 id 可能已被重投影换掉）。
+- 清理：`canDismissResourceCanvasQuickEdit`（生成中的浮层不参与清焦点）与宿主里两个只为它服务的面板状态 ref 一并删除；`clearResourceCanvasFocus` 恢复成「清选中 + 关两块浮层」的直线逻辑。
+- 影响面：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`.../features/resource-canvas/resourceCanvasFocusModel.ts`、`tests/{projectResourceLiveIntegration,resourceCanvasQuickEditDraft,resourceCanvasFloatingDismiss}.test.tsx`、PRD §3.10。
+- 验证：定向 `projectResourceLiveIntegration`（32 条，三条断言面板留在失败态的用例按新口径改写为「重开面板再重试，身份不变」）、`resourceCanvasQuickEditDraft`（10 条）、`resourceCanvasFloatingDismiss`（18 条）全绿；`npm --prefix apps/ai-game-creator-shell run typecheck` 通过。
+- 合并前复核（2026-09-21）：合并 master 后按**仓库根**跑全量 `npx vitest run`，**373 个测试文件全过、4512 通过 / 34 跳过 / 0 失败**；PR #419 显示 `No Conflicts`。真实客户端观感与远程 CI 未复验（后者按用户要求不追，runner/镜像问题见 Issue #431）。

docs/project-memory/shared-memory/development-workflow.md

@@ -20,46 +20,54 @@
 
 完整规则和模板见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。小型局部修改仍直接使用下方轻量流程；执行中若触及公开行为，立即升级到 SDD。
 
-任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。
+任务开始时先写清一句话交付结果、验收判据和修改范围，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，其余记录为后续事项。
 
 ## 开始前
 
-- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码，不能经依赖软链接读取另一工作树的共享包。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，不用给组件补全局变量来掩盖错误来源。
+- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，修复错误的依赖解析。
 
 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
 - 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
 - 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
-- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 不从未挂载模块推导。
+- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 按实际挂载路由核对。
 - External v1 以 `docs/openapi/genarrative-external-v1.openapi.json` 与 `modules/external_api.rs` 为准。
 - 本地端口的默认值只用于启动配置；实际运行端口以 `.app/dev-stack.json` 和启动日志为准。
-- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本，不依赖仓库中已不存在的旧表目录或基线文件。
+- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本。
 
 ## 修改边界
 
 - 后端路线固定为 `server-rs + Axum + SpacetimeDB`，访问 SpacetimeDB 统一经 `spacetime-client` facade。
 - `module-*` 放领域规则，`spacetime-module` 放表和事务，`api-server` 放 HTTP/SSE/BFF，`platform-*` 放外部副作用，`shared-contracts` 放 DTO 与公开契约。
-- 前端不承接正式业务真相；页面状态必须来自后端投影、API 或持久化合同。
-- 旧模板、旧公开作品、旧运行态、旧 Node/Express/PostgreSQL/Go/maincloud 路线和人工 `spacetime --root-dir` 命令不作为新实现目标。
-- 已退役对象没有现役 caller、公开契约、持久化迁移或活跃实例时，不添加兼容代码、兼容测试、墓碑注释或墓碑文档。
-- 修改中文文件优先局部补丁，保持 UTF-8；不把中文文案替换成英文。
+- 前端负责表现与交互；页面正式状态来自后端投影、API 或持久化合同。
+- 本地 SpacetimeDB 数据隔离使用项目脚本或 `--data-dir`，发布目标显式传 `--server` / `--server-url`。
+- 已退役对象没有现役 caller、公开契约、持久化数据、活跃实例或迁移要求时，清理实现、专属测试和说明，权威文档保持当前状态；公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
+- 修改中文文件优先局部补丁，保持中文与 UTF-8。
 
 ## 文档维护
 
 - 当前稳定合同进入 `docs/`；长期决策、通用流程、排障经验进入 `shared-memory/`。
 - 文档现行、历史、待复核、开放事项和活动计划的分类以 [`docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`](../../【协作规范】文档生命周期与现状索引-2026-09-12.md) 为准；`historical` 和 `review` 文件开头保留状态头，不能直接作为实现依据。
 - `plans/` 只保存正在执行且有明确下一门禁的计划；`todos/` 只保存真实开放且有关闭条件的事项。完成或作废后删除或融合。
-- 不把分支名、一次性测试轮次、提交流水账和个人路径写成长期规则。
+- 长期规则记录可复用的当前合同与验证方法，执行历史由 Git 保存。
 - H5 HostBridge 真实调用链的临时替身词扫描必须覆盖生产调用链；宿主壳真实能力以现行 HostBridge 协议与代码为准。
 
 ## 验证路由
 
+提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。
+
+提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。
+
+AGC 预览快捷操作的界面测试按独立命令或有状态短流程注册，每例重新建立 fixture、原生调用 mock 和页面，并等待项目打开后再记录调用计数。预览启停、导出确认与取消等连续行为保留在同一用例；互不依赖的只读命令不串成一条长对话，也不共享 DOM 或提高超时来容纳整组流程。
+
+Rust 分片失败日志保留有界的失败详情，包括 panic 位置、断言和最终通过/失败数量；分片选中数量标为 selected，避免误读为失败数量。修改分片日志时运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`，用最小 Rust fixture 验证失败详情和成功摘要。
+
 AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
 
 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
 
 SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。
 
-按改动范围选择定向门禁，不以无关全量扫描代替契约验证：
+按改动范围选择定向门禁：
 
 | 范围                | 至少运行                                                                                                                           |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -82,8 +90,8 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 
 ## Jenkins 定时版本调度
 
-定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，保证两条管线构建同一个版本。`Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build` 不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 传给 `Genarrative-Full-Build-And-Deploy`，并先经 `Genarrative-Agc-Global-Version-Issue` 发号、再把同一个总版本号透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，保证两个客户端的平台分区发布同一个版本。这三个下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。macOS 节点是日常办公机，调度触发它时置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## Gitea CI 依赖闭合
 
-`.gitea/workflows/project-ci.yml` 的客户端门禁拆成八个 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust shard 1/4` 到 `4/4` 各只预取 AGC 壳 manifest 并各跑一片（AGC 壳那份 `Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与两个独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。AGC 壳的 4 个分片 job、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译一次后按 `--list` 名单分 4 片：CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并各自使用独立 `TMPDIR`，片与片之间靠 job 级并发摊开；本地不传 `--shard-index` 时仍是同一条命令把 4 片放进程里并行。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
+`.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。两条 Rust lane、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译后按 `--list` 名单分 4 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。

docs/project-memory/shared-memory/document-map.md

@@ -24,10 +24,10 @@
 AI 游戏创作 / DirectProject / UI workflow：
 
 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
-2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
+2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`（历史方案，仅供追溯）
 3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
-5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（仅存量旧链路）
+5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（历史 V1 方案，仅供追溯）
 2. `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`
 3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`

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

@@ -1,5 +1,48 @@
 # 踩坑与排障记录
 
+## copyArtifacts 报「Unable to find project for artifact copy」的用户触发构建差异
+
+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，只改仓库文件不生效。
+
+## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃
+
+- 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
+- 成因：图集切片上限在链路里存在两份字面量——平台切分、Agent 工具 schema `sliceCount` 与持久化产物批次都是 256，客户端结果绑定门写着 64（`agent/generation/{canvas_generation.rs,external_generation_state.rs}`）。自动切分（`connected-components` + `sliceCount=null`）切出 65~256 片是合法产出，客户端比平台更严就会把结果整条判失败。
+- 处理：客户端门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，判据与文案各只留一份（数字由常量插值），并在注释里点名三处同值权威（平台切分常量、工具 schema、公开契约）。
+- 复用判据：凡是「平台产出 → 客户端校验后落盘」的链路，客户端门只能表达**安全 / 预算**约束，不得比平台的产品上限更严；两边上限要引同一个常量或同一份文档，改一边时必须同时改另一边，并补一条「上限之内必须能落盘」的回归用例。
+
+## Jenkins Windows 节点的 PATH 白名单决定 Godot 原生扩展能否构建
+
+`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 不必另装。
+
+## 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` 实测记录，不能硬编码。
+
+## 复用 workspace 的构建必须显式清理本次要写的产物
+
+Jenkins workspace 跨构建保留：上一轮失败留下的同名 `陶泥儿_<version>_universal.dmg` 会让 `hdiutil create` 以「文件已经存在」失败，而上一轮遗留的 `*​.app.tar.gz.sig` 更危险——本轮即使没签出签名，验签门禁也会读到旧签名而误判通过。构建入口必须在构建前删除本次将写出的确切路径（更新包、签名、同版本 DMG 及其校验文件、`latest.json`、`release-notes.txt`），`hdiutil create` 同时用 `-ov`，让「归档里的产物来自本次构建」成为结构性事实而非假设。
+
+## AGC macOS 单次构建耗时集中在主 crate 重复编译
+
+AGC 主 crate（`genarrative_ai_game_creator_shell`）单架构 codegen 约 15–20 分钟，而每次 Tauri 构建都会重新生成前端 `dist`，`build.rs` 对 `dist` 目录的 `rerun-if-changed` 因此每次都判定变化，导致两个架构各重编一次主 crate。实测：`CARGO_BUILD_JOBS=4` 时首次 Jenkins 构建 78 分钟，提到 6 后为 41–43 分钟且成功；依赖 crate 走 sccache 与 target 缓存，首轮 0 命中属预期。剩余优化空间在「不必要地重建 dist」这一层，需单独设计（例如按内容摘要决定是否重跑前端构建），不要在发布入口里用假缓存换取速度。
+
+## Godot C++ 扩展构建与对象生命周期
+
+- 原生引导通过官方 `godot-cpp` 管理 Variant、String 和 Ref，不自行维护 ABI 存储。Godot 类型必须在扩展终止回调内释放，不能依赖 DLL 静态对象析构；桥节点可能已经退出，应按实例 ID 核验存活再回调。
+- 正式 Windows 构建使用 CMake 的 Visual Studio x64 generator，并实际验证 MSVC 编译；不能用 GCC 成功替代 MSVC 验收。固定官方归档按 SHA256 校验，缓存源码被修改时拒绝构建并保留证据。
+
+## Rust 同步回调的测试记录按线程隔离
+
+- `shared-contracts` 的资源 kind reporter 是进程级回调。仅给注册和断言加锁，无法阻止其他并行 manifest 测试触发该回调，导致日志数量和内容断言偶发混入其他测试记录。
+- kind 解析与回调在调用线程同步执行，测试收集器使用线程局部存储，各用例开始时清空本线程记录；生产 reporter 保持不变。保留完整记录断言，并用两个线程分别解析和核对记录，验证隔离；不要通过全局串行测试或放宽断言掩盖干扰。
+
+## AGC 自动同步必须绑定真实项目生命周期
+
+- 正式客户端在单窗口中用 React 状态打开/切换工程，窗口 URL 不代表当前工程。原生后台同步应读取由当前窗口显式登记的活动工程；首次打开、离开、切换、关窗及退出等待分别验证，不能只用携带 `projectPath` 的独立测试窗口证明正式入口可用。
+- 增量文件没有变化不等于远端清单没有变化。项目名和完整性元数据也参与提交判据，避免临时跳过恢复后永久停留在 partial，或新出现超限文件后仍显示 ready。历史清单缺少完整性字段属于未知，不能默认成完整。
+- ZIP 导出按一次冻结清单恢复相对路径并逐文件核验；直接下载内容寻址的 OSS 目录不能得到可用工程。源码/素材归档不包含依赖缓存、凭据和 AGC 对话运行状态。
+
 ## 2026-09-19 资源 kind 词汇收敛后，前端判据与 fixture 必须一起按 canonical 成员重写
 
 - **现象**：工具栏入口的 `assetKind` 换成共享 `GameCreationAppAssetKind`（图集从平台词 `art-spritesheet` 改成 `icon-spritesheet`）后，「图集不接受用户参考」的判据仍写在旧的 `['art-spritesheet']` 字符串清单里，判据恒假：生成面板重新给图集渲染参考图选择器，原生提交再按合同显式拒绝多余参考。
@@ -12,6 +55,11 @@
 - **现象**：`GameCreationAppAssetKind` 的 ts-rs `export_to` 从 `apps/ai-game-creator-shell/src/contracts/generated/` 换到 `packages/shared/src/contracts/generated/` 后，任何 `cargo build` / `cargo test` 都会重写生成文件；若新目录没进 `.prettierignore` 与 `.eslintrc.cjs` 的 `ignorePatterns`，lint-staged / prettier 会把生成物重新格式化，于是每次提交都出现「生成物被改」，`cargo test export_bindings` 也不再幂等（跑完 `git diff` 不为空）。
 - **处理（现行口径）**：生成目录一律成对登记 `.prettierignore` + eslint `ignorePatterns`；改 `export_to` 时同步改这两处，并用 `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml` 后 `git diff` 为空来验证幂等。
 - **易错点**：旧的 `apps/ai-game-creator-shell/src/contracts/generated/` 目录下的同名文件不会自动删除，换目录后必须显式删除旧文件，否则会出现「两个同名 union，改动只落在一个目录」的假绿。
+
+## universal 主程序必须配套双架构原生依赖
+
+AGC macOS 主程序可合并为 universal，但 Codex 原生包的 `codex-package.json`、code-mode host 和 zsh 仍有架构身份。两套包应各自保留上游布局与摘要，放入 `coding-agent/mac-native/darwin-arm64/`、`darwin-x64/`，由正在运行的主程序切片选择；不能只把主程序用 lipo 合并后复用最后一次构建的单架构资源。Tauri universal 两次 Cargo 构建共用 staging，每次都必须 stage 完整的两套资源。发布清单两个平台键同 URL/签名，只在 universal 产物上成立；Rosetta 隔离 smoke 不代替 Intel 真机验收。
+
 ## 生成草稿与异步展示边界必须按身份隔离
 
 非模态生成浮层切换占位时按 draftId 分实例，卸载保留未提交/失败草稿，成功提交不再复活草稿；旧项目占位不存在时丢弃其保存回调。失败重试保留原请求输入和引用身份，引用失效不能静默过滤；修改已绑定输入须明确另起请求，不伪装成原请求重试。
@@ -119,7 +167,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 
 - **现象**：`AI game creator shell Rust tests` 一直是客户端 CI 的关键路径。run 2097 实测 15 分 27 秒，其中 `apps/ai-game-creator-shell/src-tauri` 的 bin target 单测（2466 条）一条 `cargo test -- --test-threads=1` 串行占 507 秒。
 - **为什么原本是整个 suite 串行**：2026-07-21 `a273377b1` 的判据是「共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰」，即**同进程内**的全局后台锁、异步终态与进程级 static 被交叉触发；另有少数用例自身 spawn 当前测试二进制（`std::env::current_exe()`）跑 fixture，会碰容器里共享的 target 与固定临时路径。
-- **处理（现行口径）**：新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译一次后用 `--list` 名单把用例按 `index % shards` 切成 4 片，CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片（`--exact <名单> --test-threads=1`，片内串行），片与片之间靠 **job 级并发**摊开。配套把 `ai-game-creator-shell:check:rust` 拆成 `:rust:crates` 与 `:rust:shell`，AGC 相关门禁在 CI 里共 6 个 job（4 个分片 + smoke + crates）。
+- **处理（现行口径）**：新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译后用 `--list` 名单把用例按 `index % shards` 切成 4 片，CI 的每次分片调用用 `--shard-index=<i>` 只跑自己那片（`--exact <名单> --test-threads=1`，片内串行）；两条 Rust lane 各顺序运行两片，lane 之间靠 **job 级并发**摊开，避免每片重复依赖预热。配套把 `ai-game-creator-shell:check:rust` 拆成 `:rust:crates` 与 `:rust:shell`，AGC 相关门禁在 CI 里由两条 lane、smoke 和 crates job 承载。
 - **反面实验（run 2102，勿重做）**：起先把 4 片放进**同一个 job** 内的 4 个进程并行，结果门禁步骤跑满 18 分钟仍未结束，比整套串行的 507 秒还慢——同一容器内这几片共享 `HOME`、target 目录与固定临时路径，会互相拖慢。因此 `--shard-index` 是 CI 的唯一入口；不带 `--shard-index` 的「单命令内多片并行」只留给本地全量自测。
 - **易错点**：① 分片规则必须自校验「片并集等于 `--list` 全集且互斥」，否则改分片方式会静默漏跑门禁；② 每片要拿独立 `TMPDIR`，`tempfile::tempdir()` 默认落在它下面（测试里的硬编码 `/tmp/...` 多是「必须拒绝」的负向断言，不是真实读写）；③ 不要给分片 job 装 `npm ci`——AGC 壳 Rust 门禁与 `agent-run` smoke 只用 cargo 与 node 内建模块，那些 `npm ci` 正是达标 7 分钟的主要障碍；④ 片 job 只需预热 AGC 壳自己的 manifest（其 `Cargo.lock` 的 path 依赖已覆盖 `platform-llm` / `platform-agent` / `agent-runtime-core` / `shared-contracts`），`server-rs` 那份预热属于 crate 级 job；⑤ 分片后 `--test-threads=1` 不再出现在 workflow 里，但它是分片运行器的片内参数，别再往 workflow 里补整套串行命令。
 - **不要做的事**：不要退回「整套 `--test-threads=1`」（507 秒长尾回来了），不要放开成整套并行（同进程内后台锁与异步终态会再互相干扰），也不要在单个 job 内多进程并行多个片（实测比串行还慢）。
@@ -146,7 +194,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 
 - **现象**：把 `Native shell tests` 拆成客户端三个 job 后，如果只跑 `npm run check:native-shells:release`，静态契约和壳运行时门禁都不会执行；如果只跑 `--groups=contract`，`desktop-release-binary-artifact` 又会因为缺少 `build/native/desktop/` 产物而失败。
 - **原因**：分组是执行范围，不是"额外检查"。`desktop-release-binary-artifact` 断言依赖同 job 内的 `desktop-shell-stage-release-binary` 步骤，所以它归 `release` 组，不能放进 `contract`；反过来，任何"只跑一组"的命令都不能被当成完整门禁。
-- **处理**：分组与 job 的对应关系固定为 `contract`+`shells`+`release` → `Native shell tests`，`agc-web` → `AI game creator shell web tests`，`agc-rust-shard-1..4` → `AI game creator shell Rust shard 1/4 .. 4/4`，`agc-rust-smoke` → `AI game creator shell Rust smoke`，`agc-rust-crates` → `AI game creator shell Rust crates`；`scripts/project-ci-workflow.test.ts` 校验"每个分组恰好被一个 job 调用一次"和"CI 不再调用全量 `npm run check:native-shells`"，新增分组必须同步门禁脚本、根脚本与 workflow 三处。
+- **处理**：分组与 job 的对应关系固定为 `contract`+`shells`+`release` → `Native shell tests`，`agc-web` → `AI game creator shell web tests`，`agc-rust-shard-1..2` → `AI game creator shell Rust lane 1/2`，`agc-rust-shard-3..4` → `AI game creator shell Rust lane 2/2`，`agc-rust-smoke` → `AI game creator shell Rust smoke`，`agc-rust-crates` → `AI game creator shell Rust crates`；`scripts/project-ci-workflow.test.ts` 校验"每个分组恰好被一个 lane/job 调用一次"和"CI 不再调用全量 `npm run check:native-shells`"，新增分组必须同步门禁脚本、根脚本与 workflow 三处。
 - **易错点**：① 拆 job / 改 job 名后要确认分支保护里没有残留已不再上报的旧 job 名（本仓库现在不配 required context，只需人工确认 CI 结果，见置顶条目的「分支保护口径」）；② 每个 job 只预热自己会构建的 Cargo 依赖，`agent-run:smoke` 因为会 spawn `cargo` 必须与 AGC 壳的依赖预热同 job；③ 本地全量 `npm run check:native-shells` 仍会串行跑完所有分组，用它作为本地完整门禁，不要用单组脚本冒充。
 - **关联**：`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`、`scripts/project-ci-workflow.test.ts`、`.gitea` 分支保护设置。
 
@@ -349,7 +397,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 ## 2026-08-15 `#[cfg(windows)]` 里的代码不参与 Linux CI 编译，CI 绿不代表能构建
 
 - 现象：把 master（`9f5c84ee7`）合进 `feat/five_min_design` 后，`cargo check --all-targets` 在 Windows 上直接 `error[E0658]: use of unstable library feature 'windows_by_handle'`，位置是 `apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs` 的 `metadata.number_of_links()`。该文件与 `origin/master` **逐字节相同**，即 master 自身在 Windows 上就构建不过。
-- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010），而 `rust-toolchain.toml` 锁的是 stable `1.96.0`。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
+- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010）；当时 `rust-toolchain.toml` 锁的 stable 是 `1.96.0`，2026-09-20 升到 `1.98.1` 后在同一台 Windows 机器上用该 stable 实测仍报 `error[E0658]: use of unstable library feature 'windows_by_handle'`（见 decision-log 同日条），因此本条的处置口径不变。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
 - 更普遍的形状：只要一段代码只在某个 `#[cfg(target_os)]` 下编译，它就完全绕过了其它平台的 CI——不只是 unstable feature，还包括类型错误、借用错误、缺失 import。跨平台分支是「双写」，两侧都得有人真的编译过。
 - 处理：本仓库对「文件是不是无硬链接普通文件」统一自行声明 `ByHandleFileInformation` 并调用 `GetFileInformationByHandle`，见 `runner/endpoint.rs`、`tool_plan_handoff/storage_windows.rs`、`project/agent_db.rs`、`git_inspect.rs`、`image_inspect.rs`、`agent/generation/canvas_generation.rs`。`manifest.rs` 当前已采用同一实现，并保留 fail-closed 语义：无法取得句柄信息或确认存在硬链接时均拒绝，同时拒绝 directory / reparse point。
 - 验证：改后 `cargo check --offline --all-targets` 通过、`cargo fmt --check` 通过、`project::manifest` 与 godot 相关定向测试 65 passed / 0 failed。判断「是不是本次合并引入」的通用手法：`git diff origin/master -- <file>` 为空即说明该文件就是 master 原样，问题不在合并。
@@ -4619,7 +4667,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - 现象：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 都从全新 job 容器开始，apt、setup-node、rustup 和原生系统库在不同 job 里重复安装；后端与原生壳的安装时间可达数分钟，并把软件源和代理瞬时失败放大为四份。
 - 原因：Gitea Actions job 彼此隔离，上一个 job 在容器内安装的包不会自动进入下一个 job；把同一套不随 PR 变化的工具链写在 workflow step 中，必然每次重做。
-- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
+- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.98.1、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
 - 依赖边界：每个 job 仍必须各自执行 `npm ci`，让当前 lockfile 和 PR 依赖在干净环境中验证；区别是命中镜像 cache 时只做本地解包，锁新增依赖时才走受控网络。不要把 `node_modules` 或 Cargo `target` 烘进镜像，也不要向不受信任 PR 挂载跨 job 可写 cache。
 - 锁漂移边界：runtime 校验输出任一 `*_cache_lock=partial` 说明镜像内 lock 与当前 checkout 不同，不代表新增依赖已经缓存；必须同时输出 Actions warning，提示可信分支落地后刷新镜像。必须在新镜像中对 server-rs、桌面壳和 AI 游戏创作壳当前 lock 执行真实 `cargo fetch --locked --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
 - 构建网络边界：`CARGO_NET_RETRY` 只覆盖部分 crate 下载，registry `config.json` / index TLS 握手仍可能直接终止整次 fetch。Dockerfile 对每个 `cargo fetch --locked` 再做最多 5 次整命令级有界重试，最终仍执行断网 fetch，不能降低为无锁重试或省略离线闭合验证。