Merge remote-tracking branch 'origin/master' into feat/ui-editor-v3

# Conflicts:
#	docs/project-memory/shared-memory/pitfalls.md

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

@@ -2,7 +2,54 @@
 
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+## 2026-09-16 图标图集自动拆图上限提高到 256
 
+- 背景：AGC 图标图集自动连通域识别在一次生成中识别出 86 个区域，原有 64 片上限在后处理阶段阻断了请求；该上限同时影响 api-server 自动 / 手动切片、SpacetimeDB 批量落库和统一生成结果 item 数量。
+- 决策：将可输出独立切片上限统一提高到 `256`；统一生成结果最多 `258` 个 item（256 个切片加 provider 原图和透明整图）。保持原始连通域 `4096`、总裁剪像素、CPU / 内存 admission、并发上传和处理时限不变。
+- 边界：超过 256 仍按现有 `output-slice-limit-exceeded` / `sliceWarning` 语义失败关闭切片写入；自动路径保留可信整图，手动路径继续在持久化前返回错误。
+- 验证：平台切片器、api-server 警告映射与 payload、SpacetimeDB 结果 / 批次校验均覆盖 256 成功边界和 257 溢出边界。
+
+## 2026-09-14 生成进度面收敛为「常驻可折叠任务侧栏」；提交即关面板、阶段文案只归侧栏；定位动作终局化
+
+- 背景（验收人在真机上连报三条）：① 提交按钮上渲染了后端 `phaseDetail`，「生成图片」的主按钮变成写着「排队中。」的状态胶囊；② 提交后提交面板不关、一直占着屏幕等生成，用户原话「不要显示排队中，点生成直接把窗口藏起来啊，你留个窗口意义何在」；③ 任务进度面是一个工具条按钮 + 非模态浮层，跟网页端美术画布的任务侧栏不是一个形态，用户原话「你把美术画布的照抄过来都不会吗」；④ 「定位到素材」点了没反应，提示条永久停在「正在定位生成的素材…」。
+- 决策（提交面板）：**点「生成」即同步关闭面板**——不等 IPC、不等排队、不等生成；面板内**不出现**任何阶段文案（主按钮文案恒为动作名）。**只有「点击瞬间就失败」**（后端校验 / 权限拒绝 / start IPC 立即报错）才自动重开面板并带回草稿与原因；**受理之后才失败**只在任务侧栏把该任务收口为失败 + 原因，不重开面板。关闭 ≠ 取消（请求挂在任务与项目内账本上，不挂在面板生命周期上）。
+- 决策（进度面形态）：改为**常驻画布的可折叠任务侧栏**（对齐网页端 `ImageCanvasTaskSidebarView`）——展开是两个分栏「排队/生成中」与「已完成」（各带条数，「已完成」封顶 20 条 + 提示「仅显示最近 N 条」），关闭入口只保留头部那一枚 ×（底部重复的关闭按钮与其 border-top 分割线已删除）；折叠即整块让出画布、**不留贴边把手**；每项显示状态徽标 / 后端阶段文案 / 已耗时（前端 1s 计时）/ 素材名 + 「定位到素材」；侧栏非模态（不铺遮罩、不做焦点陷阱、不进模态遮挡判据），工具栏入口按钮是**唯一**开合口、常驻（资源管理 / 运行两个页签都在）并显示 `生成任务 · N`，提交受理后自动展开。**原先的非模态浮层形态已删除，不留平行入口。**
+- 决策（侧栏失去焦点即收起）：展开时挂 document 级 `pointerdown` 捕获监听，点在侧栏内部与工具条那枚开合按钮以外的地方即收起。两处必须排除——**侧栏内部**（点任务卡、点「定位到素材」不能收起侧栏）与**开合按钮本身**（它自己负责 toggle，若也被判成「点外部」就会先收起再被 toggle 打开，表现为按钮失灵；按钮带 `data-resource-generation-task-toggle` 标记供排除）。用 `pointerdown` 而不是 `click`：画布空白处的左键 pointerdown 会 `preventDefault()`，document 上的 click 收不到那一次点击。
+- 决策（收起动画）：收起不能瞬间卸载——进场有动画而消失没有，观感上是"闪一下没了"。做法是**组件自己留一帧播退场**：`open` 变 false 后进入 `leaving`，根节点挂 `is-leaving` 播 `…-leave`（与进场同向反向，160ms，`pointer-events: none`），播完（或减动效偏好的 0ms 定时）才 `setPhase('idle')` 卸载。时长在组件与 CSS 两处各写一次，**必须一致**（组件导出 `RESOURCE_CANVAS_ASSET_GENERATION_TASKS_LEAVE_MILLIS` 并在用例里钉住）。退场期间**沿用收起前那一份列表**（`lastRenderedRef`）：宿主会在同一帧里收起侧栏并把在途任务收口成已完成，直接吃新 props 会让退场动画里的内容跳一下；空态分支也必须读这份冻结快照，不能读实时 `ordered`。
+- 决策（定位必须让素材真的可见）：`handleResourceSelect` 只改选中、不会移动画布，而这张画布是 **transform 平移**的、资源卡不在任何滚动容器里——`card.scrollIntoView()` 碰不到滚动祖先，卡在视口外时"定位过去了但依然见不到素材"。所以聚焦链在选中之后必须**显式把画布视口居中到该卡**（`centerResourceCanvasOnResource`：读该卡在当前位置表里的 `x/y` 与 `resourceCardSizeByResourceId` 的尺寸，按 `canvasSize / 2 − 卡中心 × scale` 求平移量，**缩放保持不变**，与 `ensureResourceBookContentVisible` 的既有口径一致：定位不改用户的缩放预期）。`scrollIntoView` 一并保留（栏目页仍有带滚动条的祖先）。
+- 决策（侧栏位置）：挂在画布**左侧、标题栏之下、工具栏之上**，宽 300px、**覆盖式**（不 reflow 挤窄画布视口）。理由：右侧已被「智能创作」对话面板占用、顶部是栏目标题栏、底部是栏目工具栏；覆盖式不触碰画布视口数学与资源卡排布，收起即完全让出画布。若产品要求「画布被挤窄」的 flex 兄弟列形态（网页端是那种），需要改 `game-resource-book-manager` 那段布局并单独排期。
+- 决策（定位终局化）：根因是聚焦 effect 的依赖全是画布自身状态，**手动点定位不改其中任何一项** → effect 不重跑、`pendingResourceFocusRef` 无人消费、提示条永久停在中转文案。修法：新增聚焦请求序号并加入 effect 依赖；handler 重写为「能定位就定位并选中；素材在别的栏目先切栏目；不在投影里给『素材已不在项目里 / 已登记但尚未同步』的结论；挂 intent 后推进序号 + **3 秒有界兜底**；intent 被判 invalid 时也给『定位请求已失效』」，并修掉「已聚焦过」提前返回分支不清提示的同类问题（自动落卡那条链同源）。
+- 影响范围：`src/features/resource-canvas/{ResourceCanvasAssetGenerationPanelView.tsx,ResourceCanvasGenerationPanelView.tsx,ResourceCanvasAssetGenerationTasksPanelView.tsx,resourceCanvasAssetGenerationTaskModel.ts,resourceCanvasAssetGenerationQueue.ts}`、`src/view/project-development/index.tsx`，测试 `tests/{resourceCanvasAssetGenerationBackgroundClose.test.tsx,resourceCanvasAssetGenerationTasksPanel.test.tsx,resourceCanvasBottomToolbar.test.tsx,appSurface/project-development.suite.ts}`。**未改** IPC 形状与 Rust 生成通道、未改本地排队语义（仍单条在途）、未改 `packages/**`。
+- 验证方式：`appSurface.test.ts` 439 passed、定向 7 文件 93 passed、侧栏用例 7 passed；变异验证（均已实测）：① 提交后不关闭面板 → 面板用例 `expected "spy" to be called 1 times, but got 0 times` 与 AppSurface `expected <section …> to be null` 红；② 去掉即时失败重开 → `Unable to find role="dialog" and name "生成 UI 设计图"` 红；③ 去掉提交后自动展开 → `Unable to find an accessible element with the role "region" and name "生成任务"` 红；④ 折叠顺手清空任务列表 → `expected '0' to be '1'` 红；⑤ 去掉聚焦请求依赖 → `expected null not to be null`（卡片从未被选中）与 `expected <span></span> to be null`（提示条仍停在中转文案，即用户报的现象）红。
+- 关联文档：[栏目画布底部工具栏入口矩阵](../../technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)、[项目开发工作台 PRD](../../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-14 放开 AGC 手工图片生成的本地并发：durable 输出槽身份改为「精确动作指纹」
+
+- 背景：AGC 手工图片生成的 durable 输出槽身份是 `run_id = slot-<sha256({outputPath, requireSlices})>`，而工具栏除「图标规范」首次外 `outputPath` 恒为 `null`、`requireSlices` 恒 false → 同项目所有图片类生成共用一个槽，第二条并发请求在任何远端 POST 之前就被拒（`external_generation_state.rs` 的 singleflight 报「durable 图片生成输出槽已有请求执行中」）。验收反馈里的高优问题（生图期间不能退出、也不能在生成 A 的过程中生成 B）既要前端可退出，也要后端具备并行能力。
+- 决策（槽身份 = 精确动作身份）：`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 槽），该边界当前不可达，但**缺负向用例**。
+- 前端口径：本批**仍保留单条在途的前端排队**（提交节流），真并行派发需要并发收口设计（配对读 + 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。
+- 关联文档：[栏目画布底部工具栏入口矩阵](../../technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-14 「素材类型」从「编辑素材标签」面板拆成独立入口
+
+- 背景：2026-09-11 的决策把类型选择器放进「编辑素材标签」面板（与标签同一次保存、同一条写入路径，不在工具条另开入口）。真机使用暴露两个问题：① 那排 chip 在弹窗里没有任何标题，读不出是什么；② 类型改动**没有自己的提交动作** —— 点 chip 只写本地 state，落盘发生在底部「添加」上（那是标签语义的按钮），只选类型后直接关弹窗会静默丢失。
+- 决策（入口独立）：新增 `ResourceTypePanel`（标题与 `ariaLabel` 均为「设置素材类型」），**选中即落盘**（一次动作一步完成），`category` 传用户选中值、`tags` 传 `gameCreationAppAssetTags(asset)` 的落盘原值。入口两处：选中卡浮动工具条「素材类型」按钮 + 信息浮层「分类」行的「设置」。
+- 决策（选项形态，真机反馈后修订）：选项区**必须是纵向单选列表**，一行一个（容器 `role="radiogroup"`、每项 `role="radio"` + `aria-checked`，选中态与读屏共用 `aria-checked` 并由 CSS 直接驱动；roving tabindex + 方向键移焦点、**Enter/Space 才落盘**）。真机上第一版用了共享 `PlatformSegmentedTabs`（`columns="threeToSix"`）→ 6 个选项挤成一行互相叠字，验收人原话「做成列表，而不是全都一条」。**有意偏离 APG**：方向键不顺手选中——本面板「选中 = 一次 CAS 写盘 + 宿主收窗」，方向键即选中会让浏览 6 个选项变成连环写盘、第一次按键就关窗。行骨架复用共享 `PlatformNavigableListItem`（未复制共享 UI、未改 `packages/**`）；列表 `max-height: min(320px, 40dvh)` + 独立滚动，标题/素材名/错误提示不滚，行高 44px 移动端优先。这一版值得后续抽成 `packages/shared` 的 `PlatformRadioList`（或给 `PlatformSegmentedTabs` 加 vertical 档），本批按边界未做。
+- 决策（标签面板去掉类型控件）：「编辑素材标签」面板删除 chip 与 `categoryChoice` 分叉，保存时 `category: gameCreationAppAssetPersistedCategory(asset)`；「没碰过分类就回传落盘原值」这条不变量改为**结构性保证**（面板里根本没有类型控件），两条对照用例迁到新面板并保留。
+- 影响范围：`src/view/project-development/{ResourceTypePanel.tsx,ResourceClassificationPanel.tsx,ResourceInfoPanelView.tsx,resourceCanvasInfoModel.ts,index.tsx}`、`src/features/project-workspace/resourceTypePanel.css`、`tests/{resourceTypePanel.test.tsx,resourceClassificationPanel.test.tsx,projectResourceLiveIntegration.test.tsx,appSurface/project-development.suite.ts}`。不改 `update_local_project_resource_classification` 的入参形状与 CAS 口径、不改读时自愈语义、无后端与 schema 变更。
+- 验证方式：`resourceTypePanel.test.tsx` 新 12 条 + `resourceClassificationPanel.test.tsx` 19 条 + `appSurface.test.ts` 431 passed。变异验证（已实测）：新面板 `category` 改回回传落盘原值 → 「改类型生效」用例红；标签面板改用显示口径 → 对照用例出现 `- "category": "unclassified" / + "category": "ui-interaction"`；去掉浮层判据里的新 state → 点外部串台用例红。
+- 关联文档：[AGC 资源工作台 V3 端到端验收用例](../../technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md) 的 S12。
+
+## 2026-09-14 同步命令 `generate_local_project_asset` 退役为「仅测试调用」
+
+- 决策：图片类生成接线改为 `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` 跑完。
@@ -15,6 +62,15 @@
 - 影响范围：`.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-14 AGC 资源画布改为「手动整理」：新素材不再自动重排，整张重排只由「整理画布」发起
+
+- 背景：生成一张新素材会让整张资源画布重排。两个 layout hook 都把 `rederiveAutomaticPositions` 打开（type 侧无条件 `true`，dependency 侧长期等于 `resourceGraphReady`），而该开关的语义是「每次资源协调签名变化就丢掉全部 `manuallyPlaced=false` 坐标、按当前资源与拓扑整体重算」；新增一张素材必然改签名，于是既有自动卡全部跟着挪位，用户刚记住的位置就没了。画布上也没有任何显式整理入口（`复位资源视图` 只复位视口）。
+- 决策一（默认口径）：两个 mode 的 `rederiveAutomaticPositions` 固定 `false`——画布默认只补新卡，不动任何既有坐标（`preserve`）。整张重排改为显式动作：资源工具条动作区新增**独立的**「整理画布」动作按钮（**不在**「资源排列方式」这个 `role="group"` 内——它是一键动作，不是第三种排列方式；真机上第一版塞进排序 tab 组里被验收人指出「整理画布的按钮独立出来，不要塞到那个里面」，已移出；第二轮又被指出「不要放在最右边」，所以**最终位置固定在「生成素材」之后、「管理未完成编辑」之前**（紧邻同类资源动作、在排序组左侧，不做这一行的行尾按钮——行尾会被读成「针对整个工具条」的动作）），调用 hook 新暴露的 `rederiveNow()`，复用既有写队列与 sidecar 写回链路，只把策略换成 `rederive`；用户可见反馈继续用既有 `resourceLayoutNotice`（成功即「布局已保存」）与 `resourceLayoutSaving`，不新增状态位。重算结果与当前坐标一致时**不落盘**（沿用既有 `changed` 门）：已经整齐的画布按一下不该白推进一次 CAS / revision，关系图 `producerMappingTruncated` 时更不该把一份来自不完整关系图的自动布局写进 sidecar——既有用例 `keeps trusted truncated-graph depths through the workbench without persisting a flat automatic layout` 就是钉这条。
+- 决策二（依赖图首次就绪的那一次）：`dependencyDepth` 仍要在关系图就绪后按最终拓扑排一次列。这一层不再靠「让布尔长期为真」，而是按**项目作用域的一次性 flag**（`dependencyRederiveScopeRef`）：关系图就绪且该侧 sidecar `ready` 的那一刻调用一次 `rederiveNow()`，之后一律 `preserve`；切排序 tab 不重新武装，切项目才重新记一次。
+- 决策三（生成后自动聚焦）：新增 `seenManifestAssetIdsRef` + effect，按 `manifest.assets` 的**新增 id**（不是 diff 位置、也不是文件名）把新卡交给既有 `pendingResourceFocusRef` + `advanceFocusGeneration()` 裁决链。首次打开项目 / 切项目只登记基线、不聚焦；重命名不改 id、天然不触发；已有指向同一资源的聚焦意图时不重复挂（显式生成链路在提交时就已挂好）。被搜索条件挡住时继续复用既有的「清除搜索并定位」提示与动作。
+- 影响范围：`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`（写意图增 `rederive` 标记、写策略分支、`rederiveNow`）、`.../index.tsx`（两个 hook 配置 + 一次性重派生 effect + 新素材聚焦 effect + 「整理画布」按钮）、`apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx`。不改 `manuallyPlaced` 语义、不改 sidecar 的 CAS / revision 协议与字段形状、不改卡片尺寸模型、不改「搜索不重排」合同、不改 Rust 资源图与 `dependencyDepth` 权威。
+- 验证方式：新增 `resourceCanvasManualLayout.test.tsx` 8 条：新素材入库后除新卡外坐标逐值不变、依赖侧首次就绪重算一次后同样不再重排、新素材自动聚焦、被搜索挡住走既有提示与动作、「整理画布」按 `rederive` 重算并保留手动坐标且给出一次可见反馈、已经整齐时再按一次不产生第二次落盘、首次打开与切项目都不聚焦。变异验证（均已实测）：① type 侧改回 `true`、dependency 侧改回 `resourceGraphReady` → 3 条红；② 去掉新素材基线的首次登记 → 3 条红（既有卡被当成"刚生成"选中）；③ 去掉 hook 里的 `rederive` 写策略分支 → 3 条红；④ 把显式整理改成强制写回（去掉 `changed` 门）→ 既有「截断关系图」用例红。
+- 关联文档：[踩坑记录](pitfalls.md)、[项目开发工作台 PRD](../../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)。
 
 ## 2026-09-14 客户端 CI 按门禁组拆成三个 job，AGC 的 web / rust 两段并行
 
@@ -56,7 +112,7 @@
 ## 2026-09-11 素材类型（功能分类）重新提供用户入口；资源卡角标改显示资源类型而非媒体类型
 
 - 背景：`6bdc8bbd9` 把「分类与标签」面板收敛为纯标签面板，并明确记下「随之的事实是：**「用户手动设置 `category`」这项能力就此移除**」（本文件 2026-09-11 那条以「用户给出的目标样式截图里，这个面板标题是「编辑素材标签」…」开头的条目，其决策一行即该结论）。用户随后要求「用户可以自己变更素材类型」，并追加要求把资源卡右上角角标从"文件/媒体类型"（图片 / 视频 / 文档 …）改成"资源类型"（功能分类中文名）。现状核实：写入链路本来就是完整的 —— `update_local_project_resource_classification`（`src-tauri/src/commands.rs:2162`）→ `update_manifest_asset_classification_at`（`src-tauri/src/project/manifest.rs:1112`）已接受任意合法 `category` 并校验 6 个合法值，**本次不需要改 Rust**；缺的只有 UI 入口与角标口径。本条**只回收「面板不再编辑分类」这一项**，「面板标题仍是「编辑素材标签」、删除资源入口仍在选中工具条」等其余结论不变。
-- 决策一（入口）：类型选择器加进**「编辑素材标签」面板**（与标签同一次保存、同一条写入路径，不新增第二条命令、不在工具条另开第二个入口）。选择器复用 `GAME_CREATION_APP_ASSET_CATEGORIES` × `resourceReferenceCategoryLabel`，不新造第二套中文译名。
+- 决策一（入口）【已被 2026-09-14「「素材类型」从「编辑素材标签」面板拆成独立入口」取代】：类型选择器加进**「编辑素材标签」面板**（与标签同一次保存、同一条写入路径，不新增第二条命令、不在工具条另开第二个入口）。选择器复用 `GAME_CREATION_APP_ASSET_CATEGORIES` × `resourceReferenceCategoryLabel`，不新造第二套中文译名。
 - 决策二（两个口径的分叉，本次核心不变量）：选择器**读显示口径** `gameCreationAppAssetCategory`（与画布栏目 `projectResourceAssetCategory` 同源，用户看到的选中项就是他看到的栏目）；**写回**用 `categoryChoice` 区分用户是否主动选过 —— `null`（没碰过控件）回传 `gameCreationAppAssetPersistedCategory` 的落盘原值，非 `null` 写用户选的值。这条分叉同时满足"只改标签不漂移分类"与"用户选了就写用户的值"，两个方向都有对照用例（见验证方式）。
 - 决策三（角标）：资源卡右上角角标改为**资源类型**，取值 `categoryLabels[resource.category]`（栏目与筛选共用的同一份文案），因此角标恒等于该卡所在栏目；媒体类型仍由卡面视觉（图片 / 视频 / 音频 / 文档摘要）表达。只改这一处渲染（`index.tsx` 的 `ResourceCard`），三处面（栏目画布卡、「所有资源」展开态卡、总览缩略摞上铺的卡）自动一致；`projectResourceTypeLabel` 保留给「资源管理面板」的「分类 · 类型」小字与总览摞分列，不再用于角标。
 - 画布跟随链（核实结论，**无需额外迁移代码**）：`useProjectResourceCanvasLayout` 的 `createResourceSignature` 已把 `resource.category` 计入签名，分类变化 → 签名变化 → `reconcileResourceCanvasLayout` 按新的 `section` 归并（`resourceCanvasSectionMapping.resolveResourceCanvasSection`：现行栏目值原样归到资源当前分类，x / y / `manuallyPlaced` 原样保留）→ 需要时写回 sidecar。卡片随分组落到新栏目。
@@ -156,6 +212,7 @@
 
 - 背景：#211 要求 sidecar 满足当前用户独占、禁止继承的 DACL。新建文件会先继承父目录 ACE，生产路径把这种短暂不合格送进 UAC；`project.lock` 还在独占句柄上 harden。含空格项目路径上提权 ArgumentList 被拆开，修复以 exit 1 失败。GDD 审批改意见因此弹权限，V1 锁创建不会。
 - 决策：`harden_new_game_creator_private_path` 只在本进程收紧 owner/DACL，失败则删除刚创建的对象，不 UAC 接管。项目锁先写再释放句柄再 harden，并用内容回读防换绑；UAC 仍只用于允许范围内的已有外人本对象。提权 helper 的 ArgumentList 改为一条按 Windows 规则加引号的字符串。
+- 补充：逐级创建 `.agent`、`runtime`、`locks` 等目录时，即使祖先已有 `manifest.json`，刚由本进程创建的目录也必须直接走 owner/DACL 初始化，不能因 managed-path 判定进入 UAC；自动项目根目录同样在创建成功后立即本地加固。
 - 影响范围：`config.rs` 的新建 harden 与提权命令行、`project/write_lock.rs` 的项目锁创建；不改变锁竞争、失效回收、Drop 删除，也不放宽 symlink / reparse / 外人本 fail-closed。
 - 验证方式：Windows 定向测试覆盖 `Genarrative GameAgent\gameagent-*` 取锁与私有 DACL，以及带空格路径的 quoted ArgumentList。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
@@ -307,6 +364,7 @@
 
 - 背景：立项策划 GDD 批准后需要给用户一个进入做游戏的自然出口，产品决策改为点击按钮后直接开始建造。
 - 决策：批准态 GDD 交付行提供“做成游戏”按钮。点击后读取当前项目的权威 `game/fast_gdd.md`，直接创建自动游戏工作区、导入 `text/markdown` 参考附件，并以固定建造指令自动启动 Direct Codex；不再回首页等待用户二次提交。该动作不复制原项目的 `approvedGddRef`、planning sidecar 或 approval receipt。
+- 补充：策划项目切换到 GameAgent 时，`design_artifacts` 的新增或登记信息实际变化必须与一次项目 revision 推进配对；重复切换不重复推进，避免 manifest 已变化而 revision 仍停留在旧值，触发前端同 revision 清单冲突提示。
 - 影响范围：AGC 前端 GDD 交付行与现有自动建项/附件导入/Direct Codex 链路；移除首页 RichInputArea 的 GDD 一次性预填链路；不新增 HTTP API、SpacetimeDB schema、迁移、OpenAPI 或正式构建绑定。
 - 验证方式：批准态按钮直接创建工作区、导入附件、携带固定首条指令进入项目工作台且重复点击不重复创建的 appSurface 回归；类型检查、编码检查和 `git diff --check` 通过。
 - 关联文档：`docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`。
@@ -8677,3 +8735,37 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：复用判据收窄为**同一条写调用链（同一线程）重入**——按锁路径登记真实持锁线程，只有当前线程就是持锁线程时才返回 advisory guard；本进程其它线程的争用继续走有界等待与终态占用。自主游戏构建流水线的并行专家动作豁免保持不变；跨进程占用、残留回收、权限分类、等待预算和错误文案不变。
 - 边界：锁定这些不变量的既有用例（`project_tools` / `command_runtime` / `parallel_actions` / `runtime_state` / `response_stream` / `direct_tool_bridge` / `ui_editor::persistence`）不得为了让锁语义通过而改写；用「同线程自持锁」模拟「另一个写者」的两条用例改为**在另一条线程持锁**，断言语义不变。同进程跨线程重入（持锁链在 `await` / `spawn_blocking` 后于其它线程再取锁）仍会等满预算，出现现场时按 2026-08-27 的既有处置改用 `*_locked` 入口，不放宽判据。
 - 关联文档：[项目客户端占用锁收敛里程碑](../plans/【里程碑】项目客户端占用锁收敛-2026-09-14.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-14 AGC 图片类生成后台化：提交即返回 + 项目内任务账本 + 本地排队
+
+- 背景：栏目画布图片类入口原先是一条同步 IPC `generate_local_project_asset`，一次调用最长等 35 分钟；提交期间两块生成浮层把 × / 遮罩 / Esc /「取消」全部锁死，用户既关不掉面板也看不到进度。远端图片类生成当时共用 single-flight 输出槽（`standalone_platform_art_generation_runtime_context` 按 `outputPath` 派生 `run_id`）——**同一批次内该槽身份已改为精确动作指纹，见本文件 2026-09-14「放开 AGC 手工图片生成的本地并发」条目。**
+- 决策（后台化）：新增 `start_local_project_asset_generation`（校验入参 → 落 `queued` 记录 → `tauri::async_runtime::spawn` 派发 → 返回任务记录）与 `list_local_project_asset_generations`（读回账本）。生成本身仍转调既有 `generate_platform_art_asset_with_options_at`（幂等账本、计费、下载校验、manifest/revision 登记、本地预览都不复制），同步命令 `generate_local_project_asset` **保留不动**。
+- 决策（账本落项目内）：`.agent/runtime/asset-generation-tasks/tasks.json`，复用既有 agent runtime sidecar 读写原语（临时文件 + rename）；非终态且不在本进程 live 集合里的记录在读取时收口为「上次运行中断」失败，不假装它还在跑；账本上限 50 条按创建时间淘汰。
+- 决策（阶段文案归后端）：`phaseDetail` 由 Rust 拥有（「排队中。」/「正在生成。」/「生成已完成。」/失败原因），前端面板与「生成任务」面板只渲染该字符串，不拼阶段、不做百分比。后端目前没有可播报的中间阶段（生成通道不暴露 job 的远端 `phaseDetail`），所以不伪造「正在处理。」这类前端文案。
+- 决策（本地排队）：第二条提交停在**前端本地队列**（`dispatched=false`，不调用提交 IPC，阶段显示本地排队的「排队中。」），第一条终态后由同一条循环自动补发。判据是「存在 `dispatched && 未终态` 的任务时不派发下一条」——**本批仍保留单条在途的前端排队**：AGC 本地槽此时已按精确动作指纹分槽（具备并行能力），但真并行派发需要并发收口设计（配对读 + manifest CAS + 聚焦意图互不覆盖），留待下一批；所以这里的排队是本批的**提交节流**，不再是「后端拒绝并发」的对应实现。
+- 决策（面板可关 + 非模态任务面板）：两块生成浮层在提交期间放开 × / 遮罩 / Esc，提交按钮旁给「后台运行并关闭」；**关闭 ≠ 取消**（表单的 `await` 挂在该任务的终局上，不是面板生命周期）。新增「生成任务」非模态浮层（不铺遮罩、不做焦点陷阱、**不进** `isResourceCanvasFloatingPanelOpen` / `resourceCanvasHostGenerationPanelOpen` 遮挡判据），入口按钮 `aria-label="生成任务"`；已完成的条目按 `assetId` 复用既有 `pendingResourceFocusRef` 聚焦链定位素材卡。
+- 影响范围：新增 `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。
+- 实现边界：api-server 在创建状态时冻结 Tiantoken 配置，LLM、图片和旧版非 Suno 音频按该配置路由；Suno 的提交 / 轮询仍使用旧 VectorEngine 配置。旧 `vector_engine_*` 测试构造保留为 Tiantoken fallback，生产新环境变量优先。
+- 验证：Tiantoken `/v1/models` 返回 HTTP 200（126 个模型，含 `gpt-image-2`、`gpt-5.4-mini`）；api-server Tiantoken 配置单测、platform-audio 全量测试、图片定向测试、前端 `apiClient` 定向测试、`npm run typecheck`、`npm run check:api-server-env`、编码 / fmt / diff 检查通过。未对音频上游提交生成任务，模型列表未列出 audio / Vidu 条目。
+
+## 2026-09-15 删除旧版 Vidu 音效实现
+
+- 决策：旧版 Vidu `audio1.0` 的 submit / poll / download builder、旧视觉小说与创建音效死代码、对应 platform-audio 请求类型和测试全部删除。历史素材的 `audio1.0` 展示与定价兼容数据保留；新编辑器音效仍只走 ElevenLabs，Suno 音乐链路不变。
+- 验证：platform-audio 全量测试 55 条通过，api-server `cargo check` 通过，fmt / 编码 / diff 检查通过；仓库现役源码不再包含 `VIDU_AUDIO_MODEL`、`AudioTaskKind::SoundEffect` 或 Vidu submit/poll 实现。
+
+## 2026-09-15 AGC 统一错误事件与项目诊断落库
+
+- 背景：DirectProject 的 app-server 超时、MCP 参数错误、浏览器完成门误判和普通 Agent Runtime 失败分别投影为短文案；失败正文没有稳定落库，下一轮模型看不到上一轮失败证据，用户追问原因时可能继续试玩或重复修改。
+- 决策：新增 `agent/runtime_error.rs` 作为统一错误事件与有界诊断 sidecar 边界。DirectProject 失败、Agent Runtime terminal failure 均持久化 `.agent/runtime/errors/<eventId>.json`，并将脱敏 assistant 终态写回 `project.jsonl`；前端只通过 `read_agent_runtime_error_detail` 读取脱敏详情。旧 `failure.json` 保留兼容，不把原始 stderr、凭据、URL/query、宿主绝对路径写入用户文本。
+- 决策：错误使用稳定 `source / stage / code / retryable / publicText / recoveryHint / detailRef` 字段；试玩 attempt 越界返回终态错误并停止继续等待。素材完成门扫描实际 npm 源码模块，并把 manifest 中合法的自定义 art-spritesheet 路径纳入候选，构建和浏览器观察仍需通过既有完成门。
+- 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-15 AGC 统一错误事件、诊断落库与验收反馈”；开发期计划见 `docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md` 与对应实施计划。
+## 2026-09-15 Direct 回合跨页面继续运行与活动项目面板
+
+- 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
+- 边界：快照不写项目文件、不进入公共 API、不跨应用重启恢复；读取失败保留上一份结果并单独提示，不改写成权限或审批失败。身份锁排他性、付费身份和项目写锁不变。

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

@@ -72,6 +72,10 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 3. 确认相关当前文档与共享记忆已同步，且 docs 入口没有指向已删除或退役实现依据。
 4. 提交标题使用中文，标题后逐行写明本次变更。
 
+## 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`。
+
 ## 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 镜像缓存，再重跑门禁。

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

@@ -1,5 +1,37 @@
 # 踩坑与排障记录
 
+## Windows 已登记生图资产未刷新
+
+Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` / `\\?\UNC\`，而前端项目路径仍是普通盘符或 UNC。失效监听不能直接比较原始字符串；识别为同一项目后，用当前项目路径重读 manifest，保留项目切换与 revision 门禁。普通 `agc_generate_image` 成功提交也必须发出失效通知，不能依赖整轮 Agent 结束。回归需覆盖两种 Windows 前缀、其它项目事件拒收，以及 Agent 尚未结束和后续失败时已登记图片卡片仍可见。
+
+## 2026-09-14 严格 IPC 桩缺登记新命令时，症状可能是「unhandled rejection + 不相干的提示断言」，而不是同一处报错
+
+- **现象**：`ProjectDevelopmentView` 新增「项目打开时读生成任务账本」（`list_local_project_asset_generations`）后，两个**别的关注点**的用例同时红：`resourceCanvasManualLayout.test.tsx` 报 `AssertionError: expected [ Array(1) ] to deeply equal []`（严格桩把新命令记进 `unexpectedCommands`），并伴随 7 条 `Unhandled Rejection: TypeError: Cannot read properties of undefined (reading 'map')`；`appSurface/project-development.suite.ts` 的「布局读时提示」用例则因为新命令被当成 unexpected invoke 抛错、触发了新的提示条，导致 `queryBySelector('.game-resource-live-notice')` 断言失败。
+- **原因**：这些用例的 `invoke` 桩是**严格白名单**（未登记即抛错或返回 `undefined`）。新命令在挂载期就被调用，于是：① 桩把未登记命令记进 `unexpectedCommands`/抛错；② 生产代码若对返回值无形状防御，就在 `undefined` 上 `.map` 产生 unhandled rejection。**两条失败都指不到真正的新增调用点**，很容易被误判成各自关注点的回归。
+- **处理（现行口径）**：① 渲染 `ProjectDevelopmentView` 的桩统一登记 `list_local_project_asset_generations`（返回**数组**，空账本 `[]`；Rust 侧返回 `Vec<AssetGenerationTaskRecord>`，不是 `{ tasks: [] }`）；② `unexpectedCommands` 这类门禁**不要放宽**，只登记合法命令；③ 生产代码对 IPC 返回值做形状防御（`Array.isArray` 归一化），IPC 拒绝走既有提示路径，不产生 unhandled rejection（`resourceCanvasAssetGenerationTaskModel.ts` / `resourceCanvasAssetGenerationQueue.ts` / `index.tsx` 的恢复 effect）。
+- **易错点**：① 桩返回**非数组**时用例可能"看着绿"但同时报 unhandled rejection（实测：把 `[]` 误写成 `{ tasks: [] }` 就是 8 passed + 7 unhandled error），所以判"绿"必须同时看 unhandled 计数；② 新增挂载期 IPC 后要一次性 grep 所有 `ProjectDevelopmentView` 的桩，而不是等 CI 逐个炸；③ 提示条类断言（如「无读时提示」）会把「桩抛错」翻译成「多了一条提示」，排查时先看 unhandled，再看断言。
+- **关联**：`apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`、`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`。
+## 2026-09-14 UI 编辑器返回后资源画布滚轮平移失效
+
+- **现象**：资源管理打开 UI 编辑器再返回后，资源画布滚轮平移/缩放不再响应；返回前同一手势正常。
+- **原因**：资源画布的非 passive `wheel` 监听绑定在 `resourceBookManagerRef` 当前 DOM 上，但 effect 只依赖 `handleResourceBookWheel` 与 `mode`。UI 编辑器切换会卸载旧 manager 并挂载新 manager，依赖不变导致新节点没有重新绑定监听。
+- **处理**：将 `uiEditorRoute` 纳入 wheel effect 依赖，使进入/退出 UI 编辑器时先清理旧节点监听，再给返回后的新 manager 绑定同一处理器。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts -t "restores resource canvas panning"`；回归用例覆盖打开栏目、wheel 平移、进入 UI 编辑器、返回并再次 wheel 平移。
+- **关联**：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+## 2026-09-14 AGC 就绪等待被 WMI 拖成分钟级：端口归属探测从 Get-NetTCPConnection 换成 netstat
+
+- **现象**：`npm run agc` 从 `[ai-game-creator-shell] starting backend stack` 到 `backend ready` 要等约 80 秒，中途反复出现 `等待配套后端就绪时归属校验未通过（api-server-owner-mismatch: 未知进程）`；而这段时间后端其实已经好了（实测 api-server 12:39:01 已在 8084 监听、`/healthz` 已 200，12:40:19 才判 ready）。
+- **根因（本机实测，不是推断）**：端口归属探测原实现用 `Get-NetTCPConnection -State Listen -LocalPort` 逐端口取 owner，而它底层走 WMI：**单端口单次 11.2 秒**；再叠加每个 PID 的 `Get-CimInstance Win32_Process`（热调用 3.3 秒、首次 18 秒）。三个端口一轮 ≈ 43 秒，而就绪等待每约 1 秒轮询一次 ⇒ 首轮几乎必然判负、要等好几轮才通过。同机对照：`netstat -ano -p tcp` 29 毫秒、`[System.Diagnostics.Process].MainModule.FileName` 4 毫秒、`Get-Process -Id` 19 毫秒；`Get-WmiObject` 4.2 秒、`wmic` 本机已被移除。结论是慢在 WMI 本身，换 cmdlet 没用。
+- **处理**：探测脚本改为 ①`netstat -ano -p tcp` 取「端口 → PID」——监听行判据用**外部地址 `0.0.0.0:0` / `[::]:0`**（不依赖会被本地化的 State 文本），PID 取**最后一列**而不是硬编码下标（状态列本地化或被合并时也取不错，这个下标一旦写错会被 `$ErrorActionPreference = "SilentlyContinue"` 静默吞掉，表现为「探测永远返回空」）；②`[System.Diagnostics.Process]::GetProcessById(...)` 读进程名与可执行文件路径；③只有核对 SpacetimeDB `--data-dir` 归属（或路径读不到要兜底标签）时才按 PID 取命令行，并按 PID 记 5 分钟 TTL 缓存、随探测请求经 `GENARRATIVE_KNOWN_COMMAND_LINES` 下发，让轮询只在首个周期付一次 WMI 成本。探测本身失败仍返回 null 走旧的退化分支，「归属无法证明就不复用」的语义不变。
+- **验证**：`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 新增两条——「探测脚本使用 netstat 且不再出现 Get-NetTCPConnection」「命令行按 PID 缓存后随请求下发、TTL 过期即失效」；定向 vitest 55 passed。本机实测：不含 SpacetimeDB 端口的探测 368 ms（原约 22 秒）、含 SpacetimeDB 端口 3.8 秒、命中缓存 368 ms；`npm run agc:serve` 的 `starting backend stack` → `backend ready` 由约 80 秒降到 16.7 秒（其中归属校验只占 4.4 秒，其余是 SpacetimeDB + api-server 的真实启动时间）。
+- **残留**：这台机器上首次 WMI 调用本身仍是秒级（曾见 18 秒），所以「新 SpacetimeDB PID 的第一次探测」仍可能多花几秒；命令行在进程存活期内不变，TTL 只用来限制 PID 复用造成的误判窗口。
+- **关联**：`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`（`readWindowsPortOwnerIdentities`）、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`、`apps/ai-game-creator-shell/scripts/dev-windows-process.mjs`（退出清理仍走整份 `Win32_Process` 快照，自带 1 秒缓存，不在本次范围）。
+## 2026-09-15 AGC JSON API 的响应体也必须有等待上限
+
+- `fetchClientHttp` 的超时只覆盖请求到响应头返回；随后直接等待 `response.text()` 仍可能无限挂起。模型目录共用一个在途 Promise，响应体卡住会使后续刷新复用同一挂起请求、选择器持续忙碌。
+- 成功 JSON 与错误响应体均复用 `readClientHttpResponseText` 的 15 秒上限；超时后保留最后一次有效目录并释放在途请求，手动重试重新发起请求。迟到的响应不得覆盖重试获得的新目录。
+- 排查时区分接口未挂载（404）、未授权（401）、网络或响应体超时以及刷新无变化但缺少反馈；不能仅凭客户端启动 IPC 回退警告判断刷新失败原因。
+
 ## 2026-09-14 未知 JS 异常必须继续进入 error report
 
 - **原则**：任何 JS 边界只要无法确认异常属于已知、已解决且有契约的业务失败，就必须保留原始异常并继续抛出，由全局 error report 链路采集；范围不限于 UI 编辑器、生成路径、剪贴板，也包括文件系统、权限、网络、插件和其它宿主调用。用户界面的 fallback（例如显示“复制失败，请手动复制”）只是附加的可继续操作提示，不代表异常已经被处理。
@@ -24,6 +56,14 @@
 - **处理**：`runNativeShellGate` 收窄为 `(group, gate)`，label 回到各门禁执行体里以字面量打印；分组能力与 `--groups=` 语义不变。脚本内已注明"不要把 label 抽成变量"，外部壳的 `check-config` 是它的消费者。
 - **验证**：`node apps/mobile-shell/scripts/check-config.mjs` exit 0；`node apps/desktop-shell/scripts/check-config.mjs` 已越过第 740–777 行的根脚本断言段（本机随后卡在本机不存在的 Tauri 生成产物目录，与本次改动无关）；`--groups=contract`、vitest `scripts/project-ci-workflow.test.ts`、eslint 均通过。修复后 run 2097 六个 job 全绿。
 - **关联**：`scripts/check-native-shells.mjs`（`runNativeShellGate`）、`apps/desktop-shell/scripts/check-config.mjs`、`apps/mobile-shell/scripts/check-config.mjs`。
+## 2026-09-14 AGC 资源画布不要恢复「无条件重派生」，否则新增一张素材就整张重排
+
+- **现象**：用户生成一张新素材后，画布上既有卡片全部移位，刚摆好的位置失效。
+- **原因**：`useProjectResourceCanvasLayout` 的 `rederiveAutomaticPositions=true` 会让**每一次资源协调签名变化**（新增 / 删除素材、改标签、改分类、拓扑签名变化）都丢掉全部 `manuallyPlaced=false` 坐标整体重算。签名里必然包含新素材，所以「新增一张素材」就等于「整张画布重排」；两个 hook 当时都开着它（type 侧无条件 `true`，dependency 侧长期等于 `resourceGraphReady`）。
+- **处理（现行口径）**：默认一律 `preserve`（只补新卡）。整张重排只由「整理画布」按钮调用 hook 的 `rederiveNow()` 发起，或由「关系图首次就绪」那一次按项目作用域的一次性 flag 发起。**不要**把 `rederiveAutomaticPositions` 改回长期 `true` / `resourceGraphReady`，也不要为「拓扑变了要立刻重排」再加自动触发点——那正是本条要修掉的行为。
+- **易错点**：① 一致性判据是 `reconcileResourceCanvasLayout` 输出里**每个分区按 `(y, x, resourceId)` 排序**后的数组与来源逐项比较，所以手工构造 sidecar 夹具时要按同序写，否则会被判成「变了」而多写一次，用例里会看到意料之外的写回；② 关系图首次就绪那一次重算要等该侧 sidecar `ready` 之后再发（关系图可能先就绪），否则这一次会被吃掉；③ 依赖侧的一次性 flag 按**项目作用域**记账，不要挂到 `resourceGraphReady` 这类会随排序 tab 反复翻转的值上，否则每次切回依赖视图都会重排一次；④ 新素材聚焦按 `manifest.assets` 的新增 id 判定，首次打开 / 切项目必须先登记基线，否则一进工作台就跳到最后的卡上；⑤ 不要为了让「整理画布」按钮"一定有反馈"而把 `changed` 门拿掉——重算结果与当前坐标一致时不写盘是既有合同，关系图 `producerMappingTruncated` 时强行写回等于把一份来自不完整关系图的自动布局持久化（`appSurface.test.ts` 的 `keeps trusted truncated-graph depths through the workbench without persisting a flat automatic layout` 会红）。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx`（8 条）；把两个 hook 配置改回旧口径会红 3 条。
+- **关联**：`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`。
 
 ## 2026-09-14 客户端 CI 拆分后，选组运行会跳过未选分组，且必须同步分支保护
 
@@ -3841,7 +3881,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 现象：在 Jenkins Job 页面给 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 配了默认值，下一次加载 Declarative Pipeline 后又变空或恢复旧描述；04:00 Full Job 还可能因默认选择 `pause-after-stdb` 且 approvers 为空而失败。
 - 原因：这些 Job 使用 Pipeline script from SCM，`parameters {}` 和 `triggers {}` 会作为 Job property 回写现场配置；只改 UI 不是持久修复。构建编排如果不显式关闭下游 `PUBLISH_AFTER_BUILD`，还会受下游默认值漂移影响。
 - 处理：credential ID 和参数默认值写回三个 Jenkinsfile；仅供开发使用的 dev 定时 Full Job 默认 `STDB_API_ROLLOUT_MODE=normal`，三路 Build 调用显式传 `PUBLISH_AFTER_BUILD=false`，再由 Full Job 统一按 Stdb → API → Web 发布。Secret 原文只放 Jenkins Secret File，旧 Secret Text 保留给 Import / Export。
-- 验证：推送后让 Full / Stdb Build 用不存在的源码分支在 checkout 阶段 fail-closed，让 Stdb Publish 用空构建版本在 Prepare 阶段 fail-closed，以安全刷新参数 schema；随后只读检查三个 live `config.xml` 的参数描述和默认值，确认 Full timer 仍为 `0 4 * * *`、rollout 默认值为 `normal`，并确认刷新运行未进入 publish / deploy stage。
+- 验证：推送后让 Full / Stdb Build 用不存在的源码分支在 checkout 阶段 fail-closed，让 Stdb Publish 用空构建版本在 Prepare 阶段 fail-closed，以安全刷新参数 schema；随后只读检查三个 live `config.xml` 的参数描述和默认值，确认 rollout 默认值为 `normal`、Full 与 AGC Job 都不再带 cron（定时只来自 `Genarrative-Scheduled-Revision-Trigger`），并确认刷新运行未进入 publish / deploy stage。
 - 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`scripts/check-production-ops-guardrails.mjs`。
 
 ## 维护模式内网全站放行不能信任 X-Forwarded-For
@@ -4953,7 +4993,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 原因：把“请求已入队”、“某个稳定 ID 已存在”或“job 已 completed”误当成整批业务记录已原子提交的证据。request fingerprint 只证明用户请求，不绑定最终 slot、派生记录、画布候选和 compact result；仅比较资源 ID 也无法发现内容漂移。
 - 处理：用 `editor_generation_operation` 记录 durable receipt，分开 request fingerprint 与整笔 commit SHA-256。首次调用在同一 SpacetimeDB 事务中校验 lease 并写 object/resource/asset/binding/canvas/job/receipt；重放先查 receipt，再读回逐 slot 权威事实精确比较。receipt 缺失但 resource/asset/binding 已存在时失败关闭，不得补写 receipt；事务前已确认的 asset object 只能在 ID、bucket/key、owner、策略、媒体、来源和实体字段全部相等时复用。
 - 时间与并发：`completed_at_micros` 必须为正数，object/resource/asset/binding/canvas 候选原时间字段与它一起纳入 commit SHA-256，不能在每次重放时重新取时；job 终态和完成事件只用 SpacetimeDB `ctx.timestamp`。canvas CAS 冲突后只刷新 project 并重算布局，不重跑 Provider / OSS。OSS 尚未进入该事务，无引用 object 仍是需另行清理的边界，不要宣称跨 OSS exactly-once。
-- queue completion 不能把 inline 完整响应无条件同时复制到 `result` 和 `editor-agent-tool-call-result`。图集/UI 最多 64 个切片会重复携带 resource/asset/prompt/generationInputs，容易超过 job payload 512 KiB 上限并让整个原子提交回滚。必须先按普通 UI、Editor Agent、External API 的消费方契约裁剪，再把最终 JSON 交给统一 procedure。
+- queue completion 不能把 inline 完整响应无条件同时复制到 `result` 和 `editor-agent-tool-call-result`。图集/UI 最多 256 个切片会重复携带 resource/asset/prompt/generationInputs，容易超过 job payload 512 KiB 上限并让整个原子提交回滚。必须先按普通 UI、Editor Agent、External API 的消费方契约裁剪，再把最终 JSON 交给统一 procedure。
 - 消费方身份不能在提交前重新读取 summary 兼容快照来判断：该快照按设计清空 dedupe key 并删除 generationInputs，Editor Agent / External API 会因此被误判成普通 UI。应在 worker 持有完整 claimed job 时把安全的 consumer kind 与 source identity 固化到调用上下文。
 - procedure future 超时或连接断开不能直接映射为业务失败，远端事务可能已经提交。必须有界重放同一 prepared commit；明确 CAS 后才刷新 layout，且刷新 layout 应使用新时间，不能把项目 `updated_at` 回拨。receipt 不复制 queue payload，只存摘要并从 job 权威行回读；跨记录 object/project 一致性必须在事务内验证，不能依赖当前 builder 通常会携带完整 candidate。
 - job 的 owner/kind/fingerprint/lease 都正确仍不够：`source_entity_id` 还必须绑定结果项目，来源资源必须另查存在性与 owner/project 归属；否则同 owner 的 job 可以误写别的项目，或伪造跨用户/跨项目血缘。
@@ -5562,3 +5602,26 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 原因：健康检查只能证明“有服务响应”，不能证明服务属于当前工作树；旧 `.app/dev-stack.json` 可能没有当前 `repoRoot`、`instanceId` 和服务级 dataDir 身份。
 - 处理：先读取 `.app/dev-stack.json`，核对顶层 `repoRoot + instanceId`，再核对服务 `repoRoot + instanceId + dataDir + pid + port`；AGC Vite marker 还必须带 `repoRoot + processId + port`。任何字段缺失或不匹配都拒绝静默复用，改为启动当前工作树自己的服务或明确提示清理。
 - 验证：`scripts/dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 覆盖 snapshot identity 和旧状态拒绝复用；运行时记录实际端口、进程命令行和 dataDir，不要只记录 HTTP 200。
+
+## 2026-09-15 登录失败提示必须保留接口返回原因
+
+- **现象**：账号登录失败时页面只显示“登录失败”，用户无法判断是手机号、验证码、密码还是服务状态问题。
+- **原因**：统一错误解析器只处理标准 `error.message/details` 结构；部分网关或旧兼容响应使用字符串 `error`，解析失败后回落到登录接口传入的通用文案。
+- **处理**：`parseApiErrorMessage` 同时支持字符串 `error`，标准嵌套结构保持原有优先级；未知或空响应继续使用通用兜底。
+- **验证**：`src/services/apiClient.test.ts` 新增字符串错误响应回归用例，定向测试 32 项通过，`npm run typecheck` 通过。
+
+## 2026-09-15 Jenkins Stdb 发布临时目录必须允许服务用户遍历
+
+- **现象**：`Genarrative-Stdb-Module-Publish` 在备份和 SpacetimeDB 就绪后，于 `spacetime publish` 报 `Permission denied`。
+- **原因**：Jenkins 以 root 运行时 `${HOME}/data/tmp` 位于 `/root` 下；即使发布临时子目录已 `chown` 给 `spacetimedb`，父目录仍不可遍历。
+- **处理**：发布给 `--run-as-user` 的 WASM 临时目录改用 `/var/tmp`，继续使用随机目录并在退出时清理。
+
+## Git hook 测试必须清除继承的 Git 仓库环境
+
+- 在 hook 内运行临时仓库测试时，`cwd` 不会覆盖继承的 `GIT_DIR`、`GIT_WORK_TREE` 或 `GIT_INDEX_FILE`。未隔离的 Git/lint-staged 子进程可能向真实仓库提交 fixture，甚至把测试版 ESLint、Prettier 配置带入主分支。
+- fixture 子进程统一清除 `GIT_*` 环境，并用一次性外层 linked worktree 验证引用、索引、配置不变；原有工程检查规则保持完整，不能用逐项关闭规则修复 fixture 污染。
+- 2026-09-16 复核：从链接工作树 `git push`/`git commit` 时，Git 注入 `GIT_DIR=<主仓库>/.git/worktrees/<name>`、`GIT_WORK_TREE`、`GIT_INDEX_FILE`，husky → npm → `check:repository-ci` → 夹具测试整链条继承。夹具 `git config user.name "Git Hooks Test"` 会写进共享 `.git/config`（此后所有提交 author 变成 `Git Hooks Test`）；夹具 `git init` 按是否带 `GIT_WORK_TREE` 分别写成 `core.bare=true`（`fatal: this operation must be run in a work tree`）或 `core.worktree=<临时夹具目录>`（`git status` 实际在操作临时目录）。
+- 处理：钩子与门禁入口先 `unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_PREFIX GIT_CONFIG_PARAMETERS GIT_CEILING_DIRECTORIES`；夹具 Git 调用在命令前自检 `rev-parse --show-toplevel` 等于夹具目录，落到外部仓库立即失败；守卫用例的子进程必须真的继承 `GIT_DIR`，否则断言会空转。
+- 验证：`git config --show-origin --get user.name` 出现 `file:.git/config  Git Hooks Test`、`git rev-parse --show-toplevel` 指向 `%TEMP%\genarrative-pre-push-*\repo` 都是被污染的确定性证据；被 `core.worktree` 劫持期间执行的 `git pull` 会把检出写进临时目录，真实工作树整体落后（本次 93 个文件），配置修好后用 `git checkout HEAD -- .` 回填。
+- Vitest 的 `toHaveBeenCalledWith` 匹配任意一次调用，失败输出会列出其它命令；应先定位相同命令的真实参数差异，不能由其它调用的序号推断时序故障。
+- 存在后台轮询的 IPC mock 不应要求目标命令占据全局最后一次调用。验证刷新时先记录调用边界，再筛选该边界之后的目标命令，严格核对其最后一次参数，避免后台查询影响断言，也避免旧调用掩盖刷新未执行。

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

@@ -51,6 +51,11 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 
 ## AGC DirectProject 与 UI workflow
 
+- DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。
+- 回合生命周期只由活动 client 回合快照和 Direct 事件恢复；Provider 的历史终态通知不能创建活动 client 回合。消息发送时间保存在历史信封，原始 item 不混入宿主字段；完成后的中间文本和工具默认收进“执行过程”，最终回复及失败提示保持可见。
+
+- AGC 安装产品名统一为“陶泥儿”，由 Tauri `productName` 控制安装项、快捷方式与 EXE 产品描述；Windows 内置 Codex 安装到顶层 `coding-agent/win-x64/`，打包资源映射与运行时查找路径必须一致。内部可执行文件名与应用 identifier 保持稳定。
+
 - 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建。单 HTML → Phaser 迁移固定走 DirectProject：文件落盘后先用受控 `project.bootstrap` 在 `game` 执行无参数 `npm install`，再用支持相对 cwd 的 `project.verify` 构建并确认 `game/dist/index.html`，已有单 HTML/Godot 不通过 JSON Generator 伪装成 npm 工程。
 
 - 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。

docs/project-memory/shared-memory/team-conventions.md

@@ -18,6 +18,7 @@
 
 - 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
 - UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
+- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。
 - 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
 - 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
 - 对已明确退役且无现役调用方、公开契约、持久化迁移或活跃实例的对象，不写兼容实现、维持旧行为的测试、墓碑注释或墓碑文档。