Merge remote-tracking branch 'origin/master' into refactor/extract-dep-from-ref-inputer

# Conflicts:
#	docs/project-memory/shared-memory/decision-log.md

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

@@ -13,6 +13,24 @@
 - 未纳入本次：粘贴解析（未来接入点是 provider 的 `mentionToken` 与既有 `buildContentFromTextTokens`）、`resource-reference-*` CSS 类名重命名（独立机械提交）、扩展变更事件的即时失效。
 - 验证方式：定向 `npx vitest run apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx` 与受影响宿主用例、`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`；行为零变化按「改名后芯片显示名自动刷新、打开面板前重读清单、`@`/`$` 候选与键盘交互、附件上限与失败提示文案」逐条对照核验，唯一例外是已裁决的 Skill 可见性缺陷修复。
 
+## 2026-09-22 AGC release 增加每日调度，dev 调度保持双平台
+
+- 背景：原有 `Genarrative-Scheduled-Revision-Trigger` 每小时跟随 revision 发布 dev 客户端，但没有对应的 release 渠道自动入口；Mac 节点此前已纳入小时 dev 调度，需要避免新增 release 调度时再退回 Windows-only。
+- 决策：新增 `Genarrative-Scheduled-Release-Trigger`，每天 04:00 检查 `SOURCE_BRANCH`，使用独立的 `.jenkins-last-release-revision` 与客户端相关路径白名单；上一轮 release 调度后有客户端变更时，先经 `Genarrative-Agc-Global-Version-Issue` 发统一总号，再以同一固定 `COMMIT_HASH` 触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 的 `AGC_UPDATE_CHANNEL=release` 分区，Mac 继续带 `SKIP_IF_SUPERSEDED=true`。小时 dev 调度保持同时触发 Windows 与 macOS dev。
+- 原因：release 与 dev 是不同渠道和发布节奏，不能靠同一个小时 Job 隐式切换；独立 Job 能分别去重、记录状态和审计发号。release 调度不触发 Full Build，避免把桌面客户端发布与线上全栈部署绑定。
+- 影响范围：`jenkins/Jenkinsfile.scheduled-release-trigger`、`jenkins/scheduled-release-trigger-job-config.xml`、`jenkins/Jenkinsfile.agc-global-version-issue`、`scripts/check-production-ops-guardrails.mjs`、开发运维文档、共享开发工作流与 AGC 总版本号技术方案。
+- 验证方式：`npm run check:production-ops` 校验 release Job 的 cron、发号、双平台 release 参数、Mac 让位和 Copy Artifact 授权；`npm run check:encoding` 与 `git diff --check` 校验文件与补丁。
+
+## 2026-09-22 项目快照 `.agent` 全量上传：远端工程包要能还原项目身份与 Agent 历史
+
+- 背景：快照上传此前复用 `should_skip_project_snapshot_path`，把整个 `.agent`（`manifest.json`、`agent.db`、conversations、logs、runtime、checkpoint、workbench、`project.lock`）排除在上传集合之外。后台“项目工程”的「下载完整工程」是按清单逐文件打包的，于是导出的 ZIP 里没有项目身份与对话历史，用户在 AGC 里恢复不出同一个项目。
+- 决策：快照同步改用独立口径 `should_skip_project_snapshot_sync_path`（`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`）。它与原口径共用同一份组件与后缀规则（提取为 `PROJECT_SNAPSHOT_EXCLUDED_COMPONENTS` / `PROJECT_SNAPSHOT_EXCLUDED_SUFFIXES`），只额外放行两点：`.agent` 组件本身，以及 `.agent` 内的 Agent 状态数据库后缀 `.db`/`.db-wal`/`.db-shm`（`agent.db` 是项目状态而不是凭据转储）。扫描入口 `src-tauri/src/project_snapshot/scan.rs` 切到新口径。
+- 边界：`.agent` 内部的版本库 / 依赖 / 构建目录、凭据目录（`.ssh`、`credentials`、`secrets` 等）、`.env*` 与 `.pem`/`.key`/`.sql` 等敏感后缀继续排除；符号链接与重解析点照旧在扫描阶段跳过；单文件 64 MiB、单次 512 MiB、单项目 2 GiB 上限不变。项目索引、checkpoint、Agent 上下文与 git 检查继续使用 `should_skip_project_snapshot_path`（仍排除整个 `.agent`）——本变更只放开快照同步。
+- 代价与取舍：`.agent` 里的会话记录、运行日志与诊断快照会随项目离机并写入该用户自己的私有前缀，这是“可还原”的代价，属于本轮产品决定。服务端不需要改动：快照路径校验只检查路径形状，后台归档按清单逐文件打包，都不含 `.agent` 特判。模板包导入门禁（`IMPORT_FORBIDDEN_SEGMENTS`）与 CLI 模板发布门禁继续拒绝 `.agent`，不会因为这份 ZIP 而放宽。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`、`src-tauri/src/project_snapshot/{scan.rs,tests.rs}`；主规范 `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-17 AGC 项目定时快照上传”与“后台工程列表与下载”两节；`docs/project-memory/plans/` 的两份里程碑与实施计划。
+- 验证方式：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot`（24 passed、0 failed、1 ignored），新增用例覆盖 `.agent` 整目录进入候选集、`.agent` 内凭据与 `.env*` 仍被排除、项目索引与 checkpoint 口径不变；另用同一份规则复算 15 个本机 AppData 项目的 487 个 `.agent` 普通文件，0 个仍落在排除集。
+- 运行时证据（2026-09-22）：真实项目副本（`.agent` 164 文件 / 5.61 MiB，`projectId=gameagent-agentsmoke1`）经真实差异引擎 → 本地 api-server → 真实 OSS `agc-dev`：`uploaded=179`（= 原口径 15 个项目文件 + 164 个 `.agent` 文件）/18,991,590 字节、`synced` 后第二轮 `no-op`；只读 GET 远端 `agc/project-snapshots/v1/<user>/gameagent-agentsmoke1/manifest.json` 得 `files=179`（`.agent/**` 164 条）、HEAD 命中 `agent.db` 等对象；后台 download 的 ZIP 含 179 条目（164 条 `.agent/`），抽样文件 SHA-256 与本地一致。注意该 bucket 仍是 `v1/` 键布局：本地 `api-server.exe`（2026-09-21 14:06）早于渠道分区提交 `4951b71d7`（16:57），重建重启后才会写 `v2/{channel}/`。
+
 ## 2026-09-21 合并 origin/master：Supervisor 永久退役，策划 V1V2 退役落到当前两条产品路径
 
 - 背景：`refactor/split-direct-project`（DirectProject 独立聊天容器）与 `origin/master`（#355 退役策划 Agent V1/V2）在 2026-09-18 之后各走一条线：本分支删掉 Supervisor 前端链路、把立项策划收敛到 `view/project-development/planning/`，master 删掉整套策划 V1/V2（前端会话 / 审批卡 / 适配器 / 类型与 Rust `planning_*_v2` 命令、`planning_gdd_model.rs`、`planning_policy_v2.rs`、`planning_session_v2.rs`）只保留 Design Agent。两边都在删 Supervisor，冲突集中在 `App.tsx`、聊天视图（`PlanningChatView`、`DirectProjectTurn`、`ToolCallGroup`）、Direct composer / 引用输入区、`styles.css`、Rust direct user item 与 appSurface 用例。
@@ -290,6 +308,42 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
 - 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
 - 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
 
+## 2026-09-20 游戏分发用灰度开关承载「关闭投稿、保在线」的回滚口径
+
+- 背景：主规范要求回滚部署时“关闭新提交和新版本激活，保留当前可玩版本与状态读取”。此前只能靠改配置或停服实现。
+- 决策：复用现役灰度配置（`game-distribution:publish`，后台「灰度发布配置」可改），没有 gate 行或 `enabled=false` 时默认开放；`enabled=true` 时只有白名单/标签/灰度命中的作者能发布，`rolloutPercent=0` 且无白名单等于紧急关闭投稿。拦截范围是作者写入（创建游戏/版本、上传、送审、撤回、下架）与管理员批准；读取、发行网关、审核队列读取、拒绝审核与安全下架始终可用，避免把“关投稿”变成“停服务”或“无法处理事故”。
+- 失败姿态：开关读取失败按关闭处理（写入口 503），读取路径不受影响。
+- 关联：`server-rs/crates/module-runtime/src/application.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[开发运维文档](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
+
+## 2026-09-20 游戏发行包 PUT 采用受控重试与容量边界口径
+
+- 背景：阶段 D 容量验证时实测 99.0 MiB 发行包单次 PUT 成功耗时 11.8s、api-server 峰值内存 378 MB（基线 82 MB），但三次尝试里出现过一次 `请求 OSS 失败：error sending request`。当时版本停在 `awaiting_upload`（可原版本重传），代价是作者白传一次整包。
+- 决策：`platform-oss` 新增 `put_internal_object_with_retry`，复用既有 `oss_error_is_retryable` 分类（传输/超时/connect、408、429、5xx、400+RequestTimeout 可重试；确定性 4xx 不重试），body 只转一次引用计数的 `Bytes`，各 attempt 复用同一份字节；发行包上传配置为 3 次尝试、250/500ms 退避，参数不合法（次数为 0 或缺退避）时按配置错误失败关闭。
+- 容量口径（真实栈实测，作为阶段 D 证据基线）：99.0 MiB 包 11.8s / 峰值 +296 MB；声明 101 MiB 在创建版本即 413；请求体 101 MiB 被请求体限制 413 且版本保持可重传；压缩比 1000 与单文件 65 MiB、10,001 文件都是 422 `PACKAGE_VALIDATION_FAILED` 并落到 `upload_failed`/`reupload`；失败包不进公开目录。
+- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[实施计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)。
+
+## 2026-09-20 游戏详情的“游玩方式”以版本声明的 inputModes 为准
+
+- 背景：公开投影里 `currentVersion.controls` 一直是空数组（首版没有自由文本操作说明的录入），详情页却只读它，于是所有已发布游戏都显示「未标注操作方式」，而作者其实在发布时声明过 `inputModes`。
+- 决策：展示层优先用公开投影里已有的结构化 `inputModes`（键盘 / 鼠标 / 触屏，去重后按声明顺序拼接），再退回 `controls` 自由文本，两者都为空才显示「未标注操作方式」。不改 HTTP 契约、不新增后端字段。
+- 关联：`src/components/game-distribution/GameDetailPage.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 游戏分发的版本回读、撤回与安全下架以服务端 recoveryAction 为准
+
+- 决策：游戏发行版本的「下一步做什么」不从客户端状态推断。`GET /api/game-distribution/versions/{versionId}`（作者）与 `/admin/api/game-distribution/versions/{versionId}`（管理员）返回版本私有投影 + 服务端派生的 `recoveryAction`（`upload` / `submit` / `wait` / `none` / `reupload` / `fix_package` / `fix_metadata`），网页发布页与作者中心只按它渲染主行动作。
+- 撤回语义：`POST /api/game-distribution/versions/{versionId}/cancel` 只能撤回未参与当前公开投影的版本，要求 `Idempotency-Key` 与 `expectedPublicationRevision` CAS；已公开版本必须走作者下架或管理员 `suspend`，不能借撤回关闭线上入口。
+- 可见性：未知版本与非 owner 的版本一律 404，不用 403 区分「别人的版本」和「不存在的版本」。
+- 幂等响应：命中既有幂等收据的写操作统一回传 `replayed: true`（此前所有写操作固定 false），客户端据此区分「本次生效」与「复用既有结果」。
+- 网页恢复：`/games/publish` 只把 `{ownerUserId, gameId, versionId, versionNumber, title}` 写入 localStorage 作为恢复标识；换账号只忽略草稿、不回读也不清除，禁止展示上一账号的私有状态。
+- 关联文档：[游戏分发实现计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-18 AGC backend 采用共享 Runtime、本地宿主与云端控制面分层
+
+- 决策：AGC backend 统一按“`agent-runtime-core`/`agent-runtime-orchestration` 共享内核 + Tauri 本地执行宿主 + `server-rs` 云端控制面 + `module-*`/`platform-*` 领域与外部适配器”整理；先建立 application facade、能力合同和跨边界状态映射，不新建第二套 Agent Runtime、会话库或业务真相。
+- 数据边界：本地项目文件、manifest、JSONL、checkpoint、锁和 Runner 状态由 AGC 本地宿主持有；认证、模型目录、编辑器资源、异步生成、计费、快照元数据和诊断由云端持有；大对象按现有 OSS 合同保存。
+- 约束：Runtime core 不依赖 Tauri/Axum/SpacetimeDB/Provider；领域规则留在 `module-*`；HTTP/SSE/BFF 留在 `api-server`；SpacetimeDB 访问统一经 `spacetime-client`；外部服务统一经 `platform-*`；前端只消费后端或本地宿主投影。
+- 权威文档：[AGC 后端框架整理与演进路线](../../technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)。
+
 ## 2026-09-17 AGC 抠图提交使用远端画布项目身份
 
 - 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
@@ -9325,3 +9379,30 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（空白口径）：`directCodexContentToPromptText` 逐字投影、不再 `trim`（前端只在整条 content 上判空）；出站提示词的收边规范化收敛成一个共享函数 `resourceCanvasAssetGenerationPromptText`，面板校验与任务落账共用，图集走 Unicode White_Space、其余走 JS 口径。
 - 影响面：`apps/ai-game-creator-shell/src/features/{project-workspace/resourceReferences.ts,project-workspace/ResourceReferenceInput.tsx,resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx,resource-canvas/resourceCanvasAssetGenerationTaskModel.ts,resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx` 与对应 6 个定向测试文件。
 - 验证：定向 `resourceCanvasAssetGenerationReferences` / `resourceCanvasAssetGenerationBackgroundClose` / `resourceCanvasBottomToolbar` / `resourceCanvasGenerationFloatingPanel(Chrome)` / `resourceReferenceInput` / `resourceReferences` / `resourceCanvasAssetGenerationTasksPanel` 全绿；全量 `npm run test -- apps/ai-game-creator-shell/tests` 只剩 `clientHttp` / `clientApi` / `clientAuthStorage` / `projectCreationDirectory` / `recentProjectsHook` 五个 jsdom `localStorage` 环境用例红（与本次改动无调用关系）；TS typecheck、`check:encoding`、`git diff --check` 通过。未复核真实客户端观感。
+
+## 2026-09-22 DirectProject 聊天状态显式化：回合三态 + 「在跑吗」唯一派生入口 + 数据流地图
+
+- 背景：DirectProject 聊天框只有三份真相源（`project.jsonl` 历史切片、Thread Manager 运行态事件、本地乐观消息），但「这一轮在跑吗」在四层里各叫一个名字——reducer 的 `turnRunning`、controller 的 `turnBusy`、视图里手拼的 `busy`、投影里的 `active`。定位发送后空窗缺陷时，读代码无法判断某个窗口期的界面表现是否有依据，也说不清谁该信谁。
+- 决策（三态取代布尔）：`DirectChatTurn.active` 改为 `DirectChatTurn.state: 'running' | 'awaiting-start' | 'finished'`。`running` 只由 reducer 的 `turnRunning` 决定；`awaiting-start` 由「最新一轮的用户条目身份 = 本地在途的 `pendingUserItemId`（`direct-codex:{clientTurnId}:user`）、且本轮还没有明确终态」决定；其余是 `finished`。判据是身份不是时间戳，`pendingUserItemId` 由 controller 在 `beginTurnCommand()` / `endTurnCommand()` 里与 `turnBusy` 同生共死。
+- 决策（单一派生入口）：新增 `useDirectProjectTurnStatus()`，返回 `{ nativeRunning, commandInFlight, displayBusy, latestTurnState }`。header / composer 只读 `displayBusy`（两者并集，语义与原来的 `turnBusy || directTurnRunning` 完全一致），「陶泥儿正在处理」卡片只读 `nativeRunning`。约定：新增「忙 / 在跑」类判据先落进这里，不在组件里另拼布尔。
+- 决策（地图落代码）：三层数据流、三份原始输入、一次发送的时序（含空窗步骤）与状态变量归属写进 `apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表写进 `.../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。不另开技术方案文档——这套说明是给改这块代码的人看的，放代码里才不会与实现脱节。ADR 补一条「活动回合唯一判据约束的是**原生回合**」的澄清与代码指针。
+- 口径更正（2026-09-22，同日第二条）：本条记录的「`awaiting-start` 暂时与 `finished` 同渲染」已由随后的三态接入渲染改动修掉，见下面那条。
+- 边界（本次不修）：`awaiting-start` 暂时与 `finished` 同渲染，所以空窗期内仍会显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」；`Math.max(turn.endedAt, turn.startedAt)` 的兜底与 `DirectProjectTurnUsage` 的渲染条件都没动。同源的第二条缺陷也记录在案：`turnEndedAt` 只是会话内展示缓存，页面重进后所有已结束回合都会走同一条兜底显示 0.0 秒（临时渲染用例实测确认，用例未入库）。修法与证据要求见下面那条（三态接入渲染）以及 `DirectProjectTurn.tsx` 里标注未修范围的注释。
+- 验证：`npx vitest run` 定向 `directTurnPresentation`（17 条，新增 4 条三态用例）、`directProjectTurnStatus`（4 条）、`directHistoryPaging`（9 条）全绿；`appSurface.test.ts` 202 passed / 13 skipped；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。真实客户端观感与窗口期表现未在客户端复核。
+
+## 2026-09-22 空窗期不再谎报「本轮结束」：DirectProject 三态接入渲染
+
+- 背景：上一条只把回合三态显式化，渲染层仍按 `state === 'running'` 判断，于是「本地已发出、宿主还没回 `turn.started`」的窗口里 `awaiting-start` 被当成 `finished` 渲染，显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」（用户现场反馈的现象）。
+- 决策（判据分两类，不许对调）：**否定式**判断（不要说它结束、不要折叠过程、不要显示终态文案）读 `state !== 'finished'`；**肯定式**判断（哪段正文在流式、「陶泥儿正在处理」卡片与滚动已耗时）读 `state === 'running'`。理由是 `awaiting-start` 能支持"还没结束"，但不能支持"宿主已经在跑"——后者只有 `turn.started` 能证明。
+- 决策（卡片口径取保守）：`DirectProjectConversation` 的「正在处理」卡片与 `activeTurnStartedAt` 仍只认 `turnStatus.nativeRunning`，窗口期不出现这张卡片。文案是「陶泥儿正在处理」，在 `turn.started` 之前无法断言宿主已经开始，这与空窗缺陷是同一个病根（把"本地已发出"当成"宿主已在跑"）；窗口期用户看到的是"消息已发出 + 输入框忙"，语义诚实。若将来改成窗口期也显示卡片，`running` 在渲染层就没有消费者了，那时应把投影压成 `unfinished: boolean`，不要留一个没人读的状态成员。
+- 边界（A 仍未修）：`DirectProjectTurnUsage` 的 `Math.max(turn.endedAt, turn.startedAt)` 兜底没动，所以两类 `finished` 回合仍显示「耗时 0.0秒」——① 页面重进后读回来的历史回合（`turnEndedAt` 只是会话内展示缓存）；② 发送后没有产生任何原生事件 / 发送失败的本地回合。为什么会有这两类、修法与要产品确认的口径都写在代码里（`DirectProjectTurn.tsx` 的 `DirectProjectTurnUsage` 注释与 `directTurnPresentation.ts` 的 `DirectChatTurnState` 注释），改完删掉那段注释。
+- 验证：`tests/directProjectTurn.test.tsx`（新增 3 条渲染契约：`awaiting-start` 与 `running` 不显示终态文案且不折叠、`finished` 有终态时显示结束时间与耗时）；`tests/appSurface/chat-composer.suite.ts` 新增 `does not report a finished turn while the host has not acknowledged the send yet`（invoke 挂起、无任何原生事件时断言不出现「本轮结束于」）；变异验证：把 `state !== 'finished'` 退回 `state === 'running'` 后渲染契约用例变红，恢复即绿。定向 vitest、`appSurface.test.ts`（203 passed / 13 skipped）、`tsc`、ESLint、Prettier、`check:encoding`、`check:doc-index`、`git diff --check` 通过。真实客户端观感未复核。
+
+## 2026-09-22 宿主崩掉不再留下永远开着的回合：本地命令失败时按身份兜底收口
+
+- 背景：`turn.started` / `turn.completed` 是原生回合唯一的开闭配对，界面上的「正在处理」卡片与输入盒忙态都读 reducer 的 `turnRunning`。但 app-server 崩了、回合任务被中止或 panic 时没人补终态事件，事件流里就留一条永远开着的 `turn.started`：界面一直显示「陶泥儿正在处理」、输入盒一直排队（用户现场反馈）。
+- 决策（本地命令返回即这一轮在宿主那边收场）：`chat_with_game_creator_direct_codex` 以真失败返回时，controller 按本轮身份调用 `stopDirectThreadTurn`，只放掉「是否在跑」，**不写终态时间**——命令返回不等于知道这一轮真正的结束时刻，编一个只会让耗时变成假数。用户主动终止与「正在跑的是另一轮」两条不适用：前者宿主必然补终态，后者不是这一轮（不能顺手抹掉别人的回合）。
+- 决策（身份作用域 + 不复活）：`stopDirectThreadTurn` 只在 reducer 里的运行身份相同或为空时生效；收口记进 `commandClosedTurnUserItemId`，同身份迟到的 `turn.started` 不再把这一轮拉回运行态（迟到的 `turn.completed` 例外放行，仍要拿它补上真正的结束时间）。身份按 clientTurnId 唯一，所以这条记忆只挡它自己那一轮。
+- 影响面：`apps/ai-game-creator-shell/src/view/project-development/chat/{conversation/directThreadChat.ts,controller/useDirectThreadChatSubscription.ts,controller/useDirectProjectChatController.ts}` 与 `apps/ai-game-creator-shell/tests/{directThreadChat.test.ts,appSurface/chat-composer.suite.ts}`。
+- 验证：reducer 新增 2 条用例（兜底收口后同名 `turn.started` 不复活且真终态仍能补上结束时间；身份不同的回合不动），appSurface 新增 `stops claiming the turn is running when a failed send left turn.started open`；变异验证：拿掉 controller 里的兜底收口调用后该用例变红（界面仍显示「陶泥儿正在处理」），恢复即绿。
+- 边界（未做）：根因仍在宿主侧——要在进程内保证开闭配对，应由 Rust 在回合函数退出（含 panic / 任务中止）时补一条终态事件（drop 守卫）；本次只做到前端不再跟着说谎。另：兜底收口的回合没有终态时间，仍会落进「`finished` 但拿不到终态时间」那个已知缺口（终态文案要不要藏，见 `DirectProjectTurn.tsx` 与 `DirectChatTurnState` 注释里的 A 项）。

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

@@ -4,7 +4,7 @@
 
 ## 标准流程
 
-前端测试稳定性验证使用根目录 `npm test`（与 Frontend tests job 相同），保留 Vitest 的 8 worker 上限。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
+前端测试稳定性验证使用根目录 `npm test` 执行全量集合，保留 Vitest 的 8 worker 上限。CI 的 `Frontend tests` 使用 `npm run test:ci:frontend`，继承根配置并排除 `apps/ai-game-creator-shell/tests/**`；该目录由 `AI game creator shell web tests` 执行，两个 job 的 Vitest 文件集合互斥且并集等于本地全量。原生壳定向检查与 Repository checks 的 AppSurface 检查仍保留。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
 
 用例隔离必须包括浏览器状态与 mock 实现：修改 `window.history` 后恢复基线路由；`spyOn(window, 'getSelection')` 等 spy 在用例结束后 restore；`clearAllMocks` 仅清调用记录，不能恢复被上一个用例替换的返回值。顺序打乱暴露的失败应修复泄漏来源，保留原有业务断言。
 
@@ -61,6 +61,8 @@ AGC 预览快捷操作的界面测试按独立命令或有状态短流程注册
 
 Rust 分片失败日志保留有界的失败详情，包括 panic 位置、断言和最终通过/失败数量；分片选中数量标为 selected，避免误读为失败数量。修改分片日志时运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`，用最小 Rust fixture 验证失败详情和成功摘要。
 
+Linux process-session 的 owner SIGKILL 测试在启动 owner 后立即建立清理 guard，正常结束和 panic 展开都必须终止并回收 owner，再按独立临时项目目录清理残留进程。先完成「杀掉 owner 后子进程自行退出」的原有断言，guard 只在退出测试作用域时兜底，不得提前清理子树使生命周期回归假绿；清理本身不得 panic 或无限等待。
+
 AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
 
 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
@@ -90,8 +92,14 @@ 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-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`。
+定时与版本比较收口到两条调度器：`Genarrative-Scheduled-Revision-Trigger` 每小时处理 dev 渠道，变化时触发 Full Build、AGC Windows/macOS dev，并让两个客户端平台共用同一个总版本号；`Genarrative-Scheduled-Release-Trigger` 每天 04:00 处理 AGC release 渠道，只在上一轮 release 调度后出现客户端相关路径变化时，经 `Genarrative-Agc-Global-Version-Issue` 发同一个总号并触发 AGC Windows/macOS release。各下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住回退。macOS 节点是日常办公机，两条调度触发它时都置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## Gitea CI 依赖闭合
 
+Gitea Rust 缓存自动维护由宿主 `genarrative-ci-cache.timer` 收集同一 master push run 六个 Rust job 的原生 V4 缓存产物，不重复执行 Cargo 预热。只传本轮新 key，命中对象只传使用时间；宿主与真实来源镜像对象合并、去重、按新近使用时间裁剪到 4 GiB，从无对象缓存基础镜像重新组装。源 run 不要求全绿，但取消、缺组、旧 attempt、未完成上传或混用来源镜像不得采用。网关暂停新 FetchTask、在途领取结束、持久化任务账本清空且内层活动容器为空才切换，不打断运行中的 CI。首次接入/升级网关需空闲窗口；Token 只需普通仓库 `write:repository`，不查管理员 API。候选装载后清理已收集 artifact，遗留项保留 7 天；真实 master CI 验证后才清理旧镜像，保留当前、一个回滚版、基础镜像及容器引用。部署入口见 `deploy/container/README.md`，合并代码不等于服务启用。
+
+修改 Gitea workflow 的 job 显示名称、ID 或缓存导出组时，必须同步维护器的 `JOBS` / `RUST_JOB_IDS`；`test_gitea_cache_maintenance.py` 直接对照实际 workflow 检查全集和导出映射，避免自动刷新或镜像验收因名单漂移长期等待。维护器 `Api.request` 的 `method` 是必填关键字参数，GET 也必须显式指定，不根据 body 推断请求方法。
+
+AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。仅首次人工 bootstrap 时，维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。
+
 `.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/pitfalls.md

@@ -1,5 +1,13 @@
 # 踩坑与排障记录
 
+## release 安装包文件名中的编码空格不能按控制字符拒绝
+
+- **现象**：release 环境点击“下载客户端”只显示无法获取最新版本，`GET /api/client-downloads` 返回 `502 UPSTREAM_ERROR`；dev 环境正常。
+- **原因**：release 渠道产品名为“陶泥儿 Release”，NSIS 首装包名因此包含空格，OSS `latest.json` 中的 URL 使用 `%20`。`validate_download_url` 的百分号解码校验把 `0x20` 当成控制字符拒绝，Windows 清单被判非法；release macOS 清单当时又未发布，聚合后两端都无下载项并返回 502。
+- **处理（现行口径）**：清单 URL 校验允许百分号编码的空格，继续拒绝其它控制字符、`/`、`\`、DEL、非法编码和跨目录文件名；不得通过改写真实产物名绕过校验。
+- **验证**：`platform-oss` 用 `陶泥儿%20Release_0.1.110_x64-setup.exe` 做清单解析回归；线上修复后接口应返回 release Windows 下载项，macOS 未发布时进入 `unavailablePlatforms`。
+- **关联**：`server-rs/crates/platform-oss/src/client_downloads.rs`、`apps/ai-game-creator-shell/scripts/build-release.mjs`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
+
 ## 客户端图标素材描述不能先包装再截断
 
 - 现象：资源画布填写了具体图标需求，平台实际收到的 `iconDescriptions` 却只包含泛化的小游戏美术指令，生成结果不遵循输入。
@@ -5455,7 +5463,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 原因：tauri-bundler 的 `download_and_verify` 现场从 GitHub 取 NSIS 工具链，只有一次机会、没有重试；响应体被截断即报 `io: unexpected end of file`，看起来像打包错误其实是网络问题。Checkout 阶段的 `git clean -fdx` 每次都会清掉 `target/.tauri`，所以每个构建都要重新下载，在受限网络下必然反复失败。
 - 处理：新增 `apps/ai-game-creator-shell/scripts/nsis-toolset.mjs` 与 `ensure-nsis-toolset.mjs`，在 `buildRelease`（Windows 目标且需要打包时）与 Jenkins `Tauri NSIS toolchain` 阶段按固定 SHA1 预置 `target/.tauri/NSIS`：原始归档带 4 次重试，缓存在工作区外的 `%ProgramData%\genarrative\tauri-nsis-cache`（可用 `AGC_TAURI_NSIS_CACHE_DIR` 覆盖），镜像开关沿用 bundler 的 `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR_TEMPLATE` / `TAURI_BUNDLER_TOOLS_GITHUB_MIRROR`。该阶段同时执行 `makensis.exe -VERSION`，把 2026-09-02 记录的缓存目录不可执行问题也提前到编译之前暴露。Checkout 阶段改为 `git clean -fdx -e apps/ai-game-creator-shell/src-tauri/target/.tauri`：Tauri 的工具缓存位于工作区内，裸 `git clean -fdx` 会连它一起删，排除后同一节点的稳态构建不再需要联网，只有冷缓存（新节点、工作区重建）才下载。
 - 验证：`node --test apps/ai-game-creator-shell/scripts/nsis-toolset.test.mjs`（已就绪零下载复用、缓存离线还原、失败重试、哈希不符与归档越界失败关闭）与 `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs`；真实节点上该阶段必须早于 Rust 编译失败关闭。
-- 注意：不要改回 `bundle.useLocalToolsDir: false` 去用 `%LOCALAPPDATA%`，也不要依赖 PATH 里预装的 `makensis`；升级 `@tauri-apps/cli` 时同步核对归档 URL、SHA1 与必需文件清单。
+- 注意：不要改回 `bundle.useLocalToolsDir: false` 去用 `%LOCALAPPDATA%`，也不要依赖 PATH 里预装的 `makensis`；升级 `@tauri-apps/cli` 时同步核对归档 URL、SHA1 与必需文件清单。回归测试自身也必须跨平台：仓库根目录用 `fileURLToPath(new URL(...))` / `defaultAppRoot()` 解析，不能用 `URL.pathname` 得到 `/C:/...` 后再 `path.resolve`；模拟 Windows 与 POSIX 缓存路径时要分别使用 `path.win32` 与 `path.posix`，不要用当前节点的原生分隔符断言另一平台。
 
 ## AGC 登录态续期必须同步本地运行时
 
@@ -5909,6 +5917,56 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。
 
+## 2026-09-22 自动合并"无冲突"也可能静默拼坏 CSS 分组选择器
+
+- **现象**：合并 master 时 git 报告 0 冲突，但 `apps/ai-game-creator-shell/src/styles.css` 里新加的头条规则被并进了 master 策划态分组选择器的中间——`.game-workbench-layout--design .project-chat-topbar-status,` 后面直接跟了别的选择器，策划态的 `font-size` / `color` 等声明整块丢失；类型检查与多数用例都不受影响，只有 `chatDialogFrameLayout` 这类 CSS 级联用例报"缺少生效声明"。
+- **原因**：双方在同一分组选择器附近各自插入规则时，hunk 可以"兼容"地拼在一起，git 不会报冲突，但选择器列表被拆散。
+- **处理**：改完 CSS 后按 master 原文重建分组规则、把新增规则独立成块；顺手删掉重复规则时要用带上下文的精确片段，避免删到分组选择器的第二个选择器。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts`（12 用例）与全量 `npm test` 通过。
+
+## 2026-09-22 合并 master 时“双方保留”不是通用解法
+
+- **现象**：把分支与 master 的同一批冲突统一按“ours + theirs 依次保留”处理后，`apps/admin-web/src/api/adminApiTypes.ts`、`api/adminApiClient.ts`、`app/adminRoutes.test.ts` 都出现语法/结构错误（接口少闭合、函数体被截断、用例少 `});`）。prettier 能通过、vitest 里被转译的纯类型文件也不报错，只有 `tsc`（admin-web typecheck）与随后单文件跑测试才暴露。
+- **原因**：冲突块可能切断一个语法结构（接口、函数、`test(...)` 调用），而双方各自的块只是在“同一位置添加内容”，拼起来会丢闭合；类型文件在 vitest 里被 esbuild 直接剥离类型，不会校验。
+- **处理**：冲突若落在语法结构内部，按“以某一侧为完整骨架、把另一侧的新增内容插到正确位置”重建，而不是简单拼接；重建后必须跑 `tsc`（含 `npm run admin-web:typecheck`）并对改动文件单独跑一次 vitest，别只看全量测试是否绿。
+- **验证**：合并后 admin-web 23 个测试文件 212 用例全绿、两端 typecheck 通过。
+
+## 2026-09-20 复用注册端口段时可能连到别的 worktree 的 SpacetimeDB
+
+- **现象**：在 `/data/dsk/Genarrative` 跑 `npm run dev:api-server` 后，日志显示端口段 `10000-10099 (dsk)`、spacetime `http://127.0.0.1:10002`，但 api-server 反复报 `ws://127.0.0.1:10002/v1/database/xushi-p4wfr/subscribe` 返回 `HTTP error: 404 Not Found`，且始终不响应 `/healthz`。
+- **原因**：该端口段是**按用户**登记的，同一用户的其他 worktree 实例已占用 `10002`；启动器只探测到端口被占用就按"已复用"继续，api-server 于是连到了另一份 data-dir 的 standalone，那里没有当前 database，发布步骤也没有落到这个实例上。api-server 在启动恢复阶段会一直重试，**accept 了连接但不返回任何响应**，所以 `curl` 表现为超时而不是连接拒绝。
+- **处理（现行口径）**：核对 `ss -ltnp | grep :10002` 的进程与 `--data-dir` 是否属于当前仓库；不属于就换用空闲端口段（`GENARRATIVE_DEV_PORT_RANGE` / `--port-range`）或先停掉确认无用的实例，不要把 404 当作 schema 缺失去改代码。排查"健康检查通过但接口 404"时不要只跑 `/healthz`。
+- **关联**：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`/var/tmp/genarrative-dev-port-ranges/registry.json`、[`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`](../../../.codex/skills/genarrative-dev-stack-port-routing/SKILL.md)。
+
+## 2026-09-20 新增 API 命名空间在本地返回 404：Vite 代理是前缀白名单
+
+- **现象**：api-server 上 `GET /api/game-distribution/games` 直连返回 200，但浏览器里 `http://127.0.0.1:<web>/games` 报 `404`，页面显示「读取游戏目录失败」。同一 URL 换成 `curl` 直连后端却正常。
+- **原因**：`vite.config.ts` 的 `server.proxy` 是**逐个前缀白名单**（`/api/auth`、`/api/profile`、`/api/runtime`、`/api/editor`、`/api/assets`、`/api/llm`、`/api/ws`），没有兜底 `/api/`。未登记的新命名空间不会转发到 Rust 后端，而是回退到 SPA 静态资源，前端再按 JSON 解析就失败。生产 nginx 走的是通用 `location ^~ /api/`，所以症状只出现在本地 dev。
+- **处理（现行口径）**：新增任何 `/api/<namespace>` 时，同一次变更里补 `vite.config.ts` 代理项和 `src/config/viteProxyConfig.test.ts` 断言；`src/config/**` 已加入 `vitest.config.ts` 的 include，漏测会直接红。注意该测试文件里可能残留已退役前缀（例如已退役的 `/api/creation-entry`）的断言，退役命名空间按「四不写」直接删断言，不要为它补代理。
+- **关联**：`vite.config.ts`、`src/config/viteProxyConfig.test.ts`、`vitest.config.ts`、`server-rs/crates/api-server/src/app.rs`、`deploy/nginx/genarrative.conf`。
+
+## 2026-09-20 发行网关用 CORP same-origin 会让沙箱内游戏加载不了自己的脚本
+
+- **现象**：平台游玩页的 iframe 明明 `onLoad` 了（加载遮罩消失、`game-player-frame--ready`），但控制台出现 `net::ERR_BLOCKED_BY_RESPONSE.NotSameOrigin … /releases/<gameId>/assets/app.js`，游戏内的脚本从未执行；直接在新标签页打开同一个 `index.html` 却一切正常，很容易误判成「已经能玩」。
+- **原因**：按安全合同 iframe 必须只用 `sandbox="allow-scripts"`（禁止 `allow-same-origin`），文档因此是不透明来源（opaque origin）。此时它对同包资源的请求不再与网关同源，而响应上的 `Cross-Origin-Resource-Policy: same-origin` 会把请求判为跨来源并拦下；ES modules 还会额外走 CORS，需要 `Access-Control-Allow-Origin`。
+- **处理（现行口径）**：发行网关的公开静态响应使用 `Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`，继续保留 `X-Content-Type-Options: nosniff`、内容类型白名单、HTML 最小权限 CSP 和「带 Cookie 一律 403」。这些都是公开静态文件，放宽 CORP/CORS 不暴露凭据；容器隔离靠沙箱、CSP 与独立来源，不靠 CORP。
+- **验证方式**：不要只用 `onLoad` 判断可玩。要在真实浏览器里点「开始游戏」，确认控制台没有 `ERR_BLOCKED_BY_RESPONSE`/CSP 报错，并核对 api-server 访问日志里该版本资源的 `http.response.status_code=200`。
+- **关联**：`server-rs/crates/api-server/src/modules/game_distribution.rs`（`release_asset_response`）、`src/components/game-distribution/GamePlayPage.tsx`、[`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 在 jsdom 里把 AGC 发布接到真实后端：Blob 没有 arrayBuffer，且跨 realm BodyInit 会被 undici 拒绝
+
+- **现象**：给 AGC 的 `publishLocalProjectGame` 写“默认跳过”的真实后端集成测试时，创建游戏、创建版本都成功，只有上传 ZIP 报“无法连接登录服务”（`networkError: true`），服务端访问日志里也没有这次上传。
+- **原因**：测试跑在 jsdom 环境，`fetch` 是 Node(undici)，但请求体是 jsdom 的 `Blob`：① 该 jsdom 版本的 `Blob` 没有 `arrayBuffer()`（`typeof blob.arrayBuffer === 'undefined'`），直接调用会抛异常；② 即便拿到字节，jsdom realm 的 `ArrayBuffer`/`Uint8Array` 也不是 undici 认得的 `BodyInit`。
+- **处理（现行口径）**：桥接层用 `FileReader.readAsArrayBuffer` 读 jsdom Blob（有 `arrayBuffer` 时才走它），再用 `Buffer.from(new Uint8Array(...))` 复制成 Node 侧 Buffer 交给 undici。参考 `apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`。
+- **关联**：`apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`、`apps/ai-game-creator-shell/src/services/clientHttp.ts`。
+
+## 2026-09-20 AGC 导出后自动弹发布面板：焦点陷阱会吞掉模态之外的点击，既有导出快捷操作用例变红
+
+- **现象**：给 AGC 加「导出试玩包后自动打开发布到游戏广场面板」后，`appSurface.test.ts` 的「预览快捷操作：导出确认、取消与包列表」变红——期望点消息上的「显示目录」把 `/open-project` 填进输入框，实际输入框仍是空。把发布面板的自动打开去掉，或用例先关掉面板，就恢复绿色。
+- **原因**：同目录的 `ThemedModal` 用 `createPortal` + `focus-trap-react` 渲染模态。焦点陷阱存在时，模态之外的 `click` 不会触达 React 的处理器（实测：临时把 `FocusTrap` 换成普通 `div`、其余不动，同一个被模态遮住的按钮点击立刻恢复生效），所以自动化里“点模态背后的按钮”不会报错，只是静默无效。
+- **处理（现行口径）**：① 产品行为保留“导出成功后自动打开面板”（一键发布入口），但受影响的用例必须先用 `findByRole('dialog', { name: '发布到游戏广场' })` 断言面板出现、点「关闭发布面板」再继续后续会话操作；② 给这类“新增自动弹窗”改流程时，先跑一遍相关 `appSurface` 用例，避免只跑新增用例；③ 排查同类“点了没反应”时，先看当前是否有焦点陷阱模态打开，而不是先怀疑事件绑定或状态。
+- **关联**：`apps/ai-game-creator-shell/src/App.tsx`（`setPublishPanelOpen(true)`）、`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-preview/preview-shortcuts/assert-project-tools-and-preview.ts`。
+
 ## 2026-09-21 受控 Lexical 输入区的回写用被动 effect：滞后渲染的 props 会把用户草稿清空
 
 - **现象**：DirectProject 输入盒里粘贴（或连续输入）长文本，提交时 `chat_with_game_creator_direct_codex` 根本没发出去，界面停在空输入盒；`chat-composer` 用例里表现为「队列/终止/语音追加」五条一起红，但手工操作只在快速输入后偶发。
@@ -5942,3 +6000,19 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 ## 2026-09-21 应用日志整行凭据脱敏会吃掉整条结构化诊断
 
 `append_application_log_line` 在落盘前对整行做 `sanitize_diagnostic_message`：行内只要出现 `token=`、`bearer `、`authorization`、`credential`、`api key` / `apikey` / `api_key` 这类标记，**整行**就被换成 `<sensitive diagnostic details redacted>`，只留下时间戳与 `RUST module:` 前缀；同时每行还会被截到 2048 字符。于是把“身份字段 + 诊断正文”拼成一行 `app_log!` 时，正文里一个凭据词就可能让整条记录连 `eventId`、`code` 一起消失（2026-09-21 加统一错误事件的日志投影时按两行落：身份行只放程序生成与调用方常量字段，summary / hint / detail 等自由文本一律只放详情行，且自由文本先自行压平换行——裸词标记脱敏消不掉，自由文本放错行会把 eventId、code 一起带走）。
+
+## 策划聊天不能按可选子节点序号分配消息高度
+
+策划与开发 Agent 共用聊天类名，但布局合同不同。策划新增状态条后，按第二个子节点分配 `1fr` 会把空白给状态条、让消息框随回复增长；只给 `.is-direct-codex` 的状态样式也不会覆盖策划。策划使用纵向 Flex，仅消息列表伸缩，阶段/待处理区域限高滚动；改共用样式时同时核对两种入口。jsdom 交互通过不代表布局正确，须匹配完整 CSS 层叠并用真实浏览器核对空/短/长消息与长待办。窄屏上下堆叠必须在固定外壳内提供工作台滚动容器，两块面板明确限高；低优先级的 `height: auto` 不能覆盖外壳后代规则的 `height: 100%`。布局夹具必须包含窗口外壳与启动器层级，并实际滚动验证输入框可见可操作，不能只检查输入框在聊天面板内部。实时正文/思考不更新持久消息数组，滚动跟随必须覆盖这些独立状态并保留用户上滚门禁；历史消息缺失的时间不得用读取时刻填补。详见 AGC 实施计划的“策划 Agent 对话显示与滚动合同”。
+
+## 2026-09-22 Rust 对象快照必须对齐 CI 编译目录和 Cargo 环境
+
+- 现象：sccache 快照已包含数百 MiB 对象，但全新 target 的“热缓存”仍然全部 miss，甚至比直接 rustc 更慢。
+- 原因：Rust cache key 包含编译 cwd；sccache `0.18.0` 还会 hash `CARGO_*` 环境（jobserver、jobs 等少数例外除外）。不同 checkout 根目录、随机的 `CARGO_BUILD_RUSTC_WRAPPER` 路径、预热遗漏 workflow 的 HTTP/retry/color 环境都可能让整套缓存 miss。小型真实 Rust 实验显示仅配置 `SCCACHE_BASEDIRS` 不能消除 cwd 差异。快照存在不等于缓存有效。
+- 处理：预热使用已核实的 Gitea 路径 `/workspace/GenarrativeAI/Genarrative`，并与分片运行器一样从 AGC `src-tauri` 启动 Cargo；保存 `workspace.txt`，路径不符时回退直接编译。wrapper 放在容器内固定路径，daemon 状态与 Unix socket 仍使用随机私有目录；预热环境与 workflow 的 Cargo 环境由定向契约测试核对。不要为命中率随意增加 `RUSTFLAGS`、改写源码路径或恢复共享可写 target。
+- 验证：相同源码、资源上限和独立干净 target 下分别记录无缓存、冷缓存、热缓存的编译耗时和 hit/miss；只有真实热命中有净收益才切换候选镜像。PR 的写入始终留在 job 容器层，公共快照仍由可信维护流程生成。
+- 统计：job 私有 daemon 设置 `SCCACHE_IDLE_TIMEOUT=0`，由 `report` 显式停止；最终测试 bin 的不可缓存编译或测试可能超过一分钟，短 idle timeout 会让 daemon 提前退出，结尾查询启动新 daemon 后误报零次请求。容器销毁仍会回收该 job 的全部进程。
+- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。对象缓存容量上限不涵盖宿主旧镜像及导出归档。自动维护只回收自己预先登记的 Image ID/tag 和专属归档，保留当前、一个回滚版、基础镜像及所有容器引用；内层按 ID 导入的镜像可能没有 tag，不能只按 tag 判断已清理。接管前历史试验版本仍需人工确认。
+- CI 产物清理：Gitea 1.26.4 的仓库 REST 仅列出 finalized/expired V4 artifact，内置到期清理不回收上传中断的 tmp-upload 分块。缓存上传块须带专属标识，宿主只清理目标仓库已结束且超过 7 天的 master run 中同样过期的自有普通文件，未知文件/符号链接保护，不改数据库或全局 prune。Artifact.workflow_run 仅含 ID/SHA，判断过期产物所属事件和状态须再读 run API，不能当作完整 run 使用。
+- 自动切换：Gitea 1.26.4 的 disabled 检查与 FetchTask 事务不原子，Runner 客户端超时不能证明服务端回滚，容器暂时为空也不能证明没有已领取任务。网关必须解析实际 Connect Protobuf/gzip，转发 FetchTask 结果前持久化任务 ID，仅在最终日志及执行清理后的最终 UpdateTask 确认后清账；取消响应不能提前释放。暂停新领取、在途为零、账本为零且内层活动容器为空才可切换，无需全局 Runner admin API。未知协议/响应或崩溃遗留标记停止切换；旧网关缺 active_tasks 不能默认零。首次接入与账本升级须空闲窗口。.runner 的 mtime 不证明地址已加载，应核验真实 FetchTask 来源及本次容器启动时间。
+- 扩展：预热所有 Rust 测试组时保留各自 cwd、profile、features 和锁策略；同一临时 target 的 Cargo fresh 不代表不同 cwd 都已生成缓存键，AGC 提示词契约、分片和 smoke 切换入口前清理预热 target。不要把 workspace 与 spacetime-module 合并成一次编译；Native shell release step 清空双 wrapper，避免将测试缓存扩展成发布缓存。当前 sccache 0.18.0 的 READ_ONLY 在 miss 后仍打包产物并产生 cache write error，不适合用来承诺“未命中无开销”。