合并master直连Codex工具链

合入master的直连Codex、受控Skill、工具桥与首页创作入口改造

保留资源画布精修、生成占位拖动与失败任务归档链路

修正三项内置AGC Skill内容指纹并保持审核包版本

对齐master合入后的Rust格式与项目开发前端测试

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

@@ -45,6 +45,7 @@
 - 处理：让每个固定分区在自己的 `.game-resource-plane` 中拥有独立 SVG，卡片与路径都直接使用布局逻辑坐标并共享父级 CSS scale / 原生 scroll；viewport 原生 overflow 负责本区裁剪。DOM 测量只换算本区逻辑 viewport，用于完整路径、incoming / outgoing 继续线和两端离屏隐藏，不参与端点身份或主路径坐标。每区 observer 和 RAF 各至多一个，卸载时清理。
 - 验证：同时挂载至少两个分区和各自同类型关系，断言每条边只存在于对应分区 SVG；只滚动其中一分区，另一分区的逻辑 viewport 与 path 不变。另覆盖缩放后 SVG / 卡片仍在同一 plane、双向离屏继续线、两端离屏隐藏、marker、自环以及 mode / 项目切换清理。
 - 关联：`apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx`、`apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。
+
 ## 正式保存不能等待 React state 才取得草稿 CAS 的新 revision
 
 - 现象：用户刚完成编辑就点击“保存到项目”，自动草稿保存已经成功，但正式提交仍携带旧 `expectedDraftRevision`，于是单窗口也得到 draft revision conflict；快速连续保存时还可能使用不同 commitId 重复 staging。
@@ -666,12 +667,12 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasInteractionModel.test.ts`，并在多素材画布拖拽时确认参考线仍能命中邻近图层且 pointermove 不再明显掉帧。
 - 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/ImageCanvasInteractionModel.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
-## 图片画布视口拖动卡顿先查自动保存和小地图合帧
+## 图片画布拖动卡顿先查 Stage 合帧和交互期自动保存
 
-- 现象：素材多或序列帧多时，拖动小地图视口框或手型平移明显卡顿，像是接口慢或 CSS 动画掉帧，但网络请求不一定异常。
-- 原因：`pointermove` 高频修改 `viewport` 会触发画布重渲染、小地图模型重算和工程持久化 effect；持久化链路会同步 `serializeCanvasLayout`、`JSON.stringify` 并写 sessionStorage。远端 PATCH 有防抖也挡不住本地同步缓存写入。
-- 处理：把 viewport 拖动标记为临时交互；拖动中只更新画布显示，不触发项目保存、session cache 写入或封面快照上传，`pointerup` / `pointercancel` 后保存最终 viewport。小地图拖动的 `updateViewportFromMinimapDrag` 必须用 `requestAnimationFrame` 合帧，结束拖拽时 flush 最后一帧。
-- 验证：`npm run test -- src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx --reporter verbose` 应覆盖小地图拖动合帧、平移 / 小地图 viewport 交互边界，以及拖动期间不写 sessionStorage / 不调用 `saveEditorProjectLayout`。
+- 现象：素材多或序列帧多时，拖动图层、生成占位、小地图视口框或手型平移明显卡顿，像是接口慢或 CSS 动画掉帧，但网络请求不一定异常。
+- 原因：高刷新率输入设备会在单个屏幕帧内发出多次 `pointermove`；每次直接 `setLayers` / `setViewport` 都会触发画布重渲染、吸附或小地图模型重算和工程持久化 effect。即使 `moveLayersFromDrag` 保留未移动图层的对象引用，若 WorldView 仍在每帧重建全部图层子树，所有真实位图的 URL hook、加载态、标签和 SVG 操作也会重复执行。持久化链路还会同步 `serializeCanvasLayout`、`JSON.stringify` 并写 sessionStorage，远端 PATCH 有防抖也挡不住本地同步缓存写入。
+- 处理：Stage 的图层、生成占位、框选和手型平移统一用单一在途 `requestAnimationFrame` 合并同帧输入，只应用最新坐标；结束拖拽时 flush 最后一帧，主动清理和卸载时 cancel。图层、生成占位、平移和小地图拖动一旦越过拖动阈值就标记为临时交互，拖动中不触发项目保存、session cache 写入或封面快照上传，`pointerup` / `pointercancel` 后保存最终布局。WorldView 的完整单图层节点必须按稳定 layer 对象浅比较 memo，父回调通过 latest ref 的稳定门面转发，避免未移动图层重渲染或读取陈旧闭包。小地图继续只在 viewport controls 内合帧，不要重复套 rAF。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx --reporter verbose` 应覆盖只重渲染移动图层、稳定节点调用最新回调、同帧只保留最新坐标、结束前 flush、卸载 cancel、小地图无双重合帧、图层 / 生成占位 / 平移 / 小地图交互边界，以及拖动期间不写 sessionStorage / 不调用 `saveEditorProjectLayout`。浏览器验收必须使用多个独立 raster URL，并区分 rAF 心跳与目标实际位置变化帧；共享 data URI SVG 和包含空闲尾帧的自由 rAF 不能作为拖动流畅证据。
 - 关联：`src/components/image-editor/useImageCanvasViewportControls.ts`、`src/components/image-editor/useImageCanvasStageInteractions.ts`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
 ## 图片编辑器宣发素材生成器刷新后不要丢快照
@@ -4215,6 +4216,27 @@
 - 处理：CONNECT 一开始就为 client socket 注册 `error / close`，解析完成后为 upstream socket注册同样的双向销毁处理；DNS 返回、写 200 和开始 pipe 前都检查 client 是否已销毁。任一端 error、close 或 timeout 都幂等 destroy 两端，不把普通客户端 reset 写成错误日志。不要用进程级 `uncaughtException` 吞掉问题，也不要只增加 npm/Cargo 重试掩盖 gateway 崩溃。
 - 验证：在独立 canary 和正式 gateway 上分别并发制造至少 500 次“CONNECT 后立即断开”，随后确认容器仍运行、restart count 不增加、日志无 EPIPE；再通过同一 proxy 对 npm registry 与 crates index 建立完整 TLS 隧道。切换前仍须确认 Gitea 无活跃 run 且 Runner 内层无 job 容器。
 
+## 独立 AGC lockfile 不能丢失可选 WASM 包的 bundled 依赖节点（2026-08-21）
+
+- 现象：`npm ci --prefix apps/ai-game-creator-shell` 在安装前失败，报告 lockfile 缺少 `@emnapi/core` / `@emnapi/runtime`；错误版本可能是 registry 当前满足 `^1.11.1` 的最新版，而不是原 lock 中曾记录的版本。
+- 原因：重写或解决 `apps/ai-game-creator-shell/package-lock.json` 冲突时，保留了 `@tailwindcss/oxide-wasm32-wasi` 对 bundled `@emnapi` 包的声明，却删掉了对应嵌套 package 节点。npm 会重新解析当前 registry 版本并判定 manifest 与 lock 不同步；这不是单一 npm 版本问题，也不表示应用应直接依赖两个 `@emnapi` 包。
+- 处理：只在最新目标分支执行 `npm install --package-lock-only --ignore-scripts --prefix apps/ai-game-creator-shell`，保留 npm 对 bundled 节点及 `peer` / `optional` 标记的完整规范化结果；确认子包 `package.json` 没有变化，不要手工只补报错中的两个版本。
+- 验证：至少用 Jenkins 对应 npm major 和当前开发 npm 分别执行干净的 `npm ci --prefix apps/ai-game-creator-shell`，再运行 AGC typecheck、编码检查和 `git diff --check`；根目录 `npm ci` 不能替代独立子包 lock 验证。
+
+## Windows 专属 Tauri resource 不能写进通用配置（2026-08-21）
+
+- 现象：Linux CI 已完成 AGC `npm ci`，却在 Tauri custom build command 中报 `resources/codex/win-x64/...exe doesn't exist`；Windows 侧车的 Rust staging 受 `cfg(windows)` 保护，因此非 Windows 构建不会生成这些文件。
+- 原因：Tauri 会在所有平台校验通用 `tauri.conf.json` 的 bundle resource 源路径；把 Windows x64 资源映射写进通用配置，等于要求 Linux / macOS 也预先拥有不属于其安装闭包的 Windows 可执行文件。
+- 处理：通用配置只保留跨平台 bundle 项；Windows 原生侧车的完整白名单放入 Tauri 自动合并的 `tauri.windows.conf.json`。不要提交二进制占位文件，也不要让非 Windows build script 下载或伪造 Windows 资源。
+- 验证：配置门禁断言通用配置没有 Windows resource、Windows 平台配置保留完整固定白名单；Linux 运行原生壳门禁必须越过 Tauri resource 校验，Windows release 仍由 build script 对 npm 原生包、SHA-256 清单和目标布局失败关闭。
+
+## AGC Skill 指纹与相对路径校验必须跨平台一致（2026-08-21）
+
+- 现象：内置 Skill 文件集合没有缺失，原生测试却统一报内容指纹不匹配；另一个测试在 Linux 上把 `C:\\temp\\SKILL.md` 判为安全相对路径，受控资源工具可能继续处理 Windows 盘符或反斜杠遍历形式。
+- 原因：审核文件定稿后未按最终字节重新生成 manifest SHA-256；同时 `std::path::Path` 只按当前宿主语义解析路径，Linux 不会把 Windows 盘符和反斜杠视为绝对路径或分隔符。
+- 处理：Skill 文件变化与 manifest 指纹更新必须同次提交，并提升审核包版本；资源引用只接受使用 `/` 的普通相对段，显式拒绝反斜杠、冒号盘符、UNC、绝对路径和父目录段，再查询审核清单。不要先把反斜杠替换成 `/` 后再做安全检查。
+- 验证：逐项按排序后的 `relativePath + NUL + file bytes + NUL` 重算并核对 manifest；Rust 单测同时覆盖 POSIX 绝对路径、`..`、`C:\\...`、`C:/...`、UNC 和反斜杠相对路径，受控 MCP 工具也必须把 Windows 绝对路径投影为 `isError=true`。
+
 ## Gitea CI 预构建镜像不能只靠 tag 判断内容
 
 - 现象：宿主已重建带日期修订 tag 的 `genarrative/gitea-project-ci` 镜像，但 `genarrative-ci` job 仍跑旧内容，或直接报 image not found；另一种危险操作是只改 runner label，没把对应镜像装入 rootless runner 的内层 Docker。
@@ -4815,3 +4837,24 @@
 - 处理：只有后继事务 committed、项目/草稿/资源身份一致、旧 after 与后继 before 精确衔接、后继 after 与当前 manifest/revision 精确一致、两份候选文件与 manifest 唯一引用都验证通过时，才把旧事务标为 `superseded`；候选文件和审计记录都保留。任何证据不完整继续失败关闭。
 - 门禁：同一资源存在 prepared 或 reconciliation 事务时，新的“设为正式图”提交必须先被拒绝并引导安全恢复，不能继续制造另一笔可能覆盖旧结果的提交。`committed/rolled-back/superseded` 是可继续后续提交的终态。
 - 关联坑：正式文件路径会追加 commitId，重新打开 refine 时不能把整个文件 stem 当作下一次素材名，否则多次精修后超过 80 字符并阻塞提交。路径只推导显示名，且必须循环剥离历史 `--<uuid>` 后缀；确定性名称/用途校验要发生在读取候选与 staging 前，并按输入错误处理而不是进入事务恢复。
+
+## 隔离 Codex app-server 会误吃代理的 ChatGPT 额度头（2026-08-20）
+
+- 现象：同一自定义 Responses endpoint 和 API Key 直接 HTTP 为 200，普通用户 HOME 下的 smoke 也完成，但隔离 `CODEX_HOME/HOME` 的 app-server 在真正发请求前返回 `usageLimitExceeded`，并投影 credits balance 0。
+- 原因：开发网关把 `X-Codex-*` ChatGPT 账户额度头附在 API Key Provider 响应上；隔离进程没有用户 ChatGPT 额度状态覆盖，Codex 0.147 将这些头当作本地账户限制。模型、Key、MCP 和 Skill 均不是根因。
+- 处理：只为 Direct conversation 启动随机 loopback `/responses` 流式代理；它不注入 Authorization，只转发请求自带 Bearer，拒绝其它方法/路径并剥离 `X-Codex-*` 账户头。不要复制用户 `auth.json` 来掩盖问题，也不要把 Provider 切换当根因修复。
+- 验证：同时记录上游直接 200、未过滤时 credits=0/usage-limit、过滤后真实 turn completed；代理测试必须证明无 Bearer 拒绝、路径收窄、正文流式保留和额度头不下传。
+
+## Codex MCP 子进程不适合直接启动桌面浏览器（2026-08-20）
+
+- 现象：同一 `agc_browser_playtest` 在普通进程中能返回双视口截图，但从 Codex 启动的 STDIO MCP 子进程调用时 Chrome 启动超时。
+- 原因：MCP 子进程继承隔离 HOME/AppData 和 Codex 进程约束；把真实浏览器或 GUI 登录态硬塞给子进程既不稳定，也扩大凭据边界。
+- 处理：STDIO MCP 只做 schema 与协议适配；浏览器和付费美术通过随机 loopback 工具桥回到持有项目、登录态和正常桌面环境的客户端主进程。桥只绑定当前项目、限制请求大小和审核工具名，返回脱敏文本与有界 PNG。
+- 验证：必须从真实 Codex thread 发起 MCP 调用并观察 desktop/mobile `readyState=complete` 与两张截图；直接运行 MCP 二进制成功不能替代该链路。
+
+## 独立 Cargo workspace 的测试增量缓存会吞噬数百 GiB（2026-08-22）
+
+- 现象：`server-rs/target` 与 AGC `src-tauri/target` 合计超过 `231 GiB`；其中两个 `debug/incremental` 约 `158.5 GiB`，server-rs 累积 `1298` 个增量会话目录，AGC 累积 `100` 个。
+- 原因：两个 Cargo workspace 拥有独立 target 和锁文件，AGC 又以 path dependency 复用若干 server-rs crate；更主要的是全量 / 分组 `cargo test` 继承增量编译，每组 crate / feature / profile hash 都可以留下新会话，Cargo 不会按仓库期望自动收缩这些历史目录。
+- 处理：保留两个 workspace 的产品 / 发布边界；两边 `[profile.test]` 关闭 incremental 并固定 `debug=1`，AGC dev profile 与 server-rs 对齐调试信息级别。日常用 `npm run audit:rust-build-cache` 只读核对；需要回收时先停止 Cargo / rustc，再显式运行 `npm run clean:rust-incremental -- --apply`，只删两个固定增量目录。
+- 验证：清理前后各跑一次只读审计并核对磁盘可用空间；分别运行 server-rs 与 AGC 定向 `cargo test`，确认 test profile 不再生成持久 `debug/incremental` 堆积。共享 `CARGO_TARGET_DIR` 必须另做并发启动基准，不得为节省磁盘直接改变生产产物路径。