合并远端 master（直连 Codex 改造）

冲突 19 处 / 6 个文件，逐处判定归属而不是二选一：

· commands.rs —— 保留本分支的 hydrate_game_creator_plan_gdd_state 输入解析，
  丢掉与 master 重复的项目根定义（master 把它挪到了后面）。
· types.ts / useHomeProjectCreation.ts —— 取 master 把 mode/prompt/attachments
  重构成 HomeDraft 的形状，保留本分支新增的 startMode。
· App.tsx —— directGameChatRuntime（master）与 !planningStartMode（本分支）是两个
  互不相干的条件，合并保留；refreshDirectProjectSurface 在 merge base 里就带预览
  逻辑，是 master 主动删掉并改名成 refreshDirectProjectManifest 的，取 master；
  capturePendingGameChatStageManifestBeforeNextRun 是分支新增且仍被调用，保留。
· SupervisorChatOnlyView.tsx —— master 的 directCodex 短路与本分支的
  projectedRuntime / descendantsStillActive 正交，逐处合成。
· project-development.suite.ts —— 那段专业 Agent 断言 base 里就有、master 主动
  删除（直连 Codex 之后不再适用），取 master。

两处语义缺口一并补上：master 新增的 codex_app_server 构造
AgentRuntimeProviderRequestSnapshot 时缺本分支新增的 planning_session_binding
字段（首页直连对话不属于任何立项 session，填 None）；首页提交按钮的 aria-label
还引用着已被删除的 homeAgentMode，取 master 的固定文案。

**做方案 UI 入口暂时缺失，待定。** master 在 bacd7a9da 里把 HomeAgentMode 整个删了，
首页的「做游戏 / 做素材 / 做方案」模式选择不再存在，而 startMode 在前端只有那一个
来源（homeDraftStartMode(mode)）。立项策划链路的代码全部保留——后端、prompt、
澄清卡、审批卡、E2E 都在——但首页现在统一按 direct-build 进入
（HOME_DRAFT_START_MODE 常量，已在原处留注释）。入口放哪由产品侧决定后另做一笔。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

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

@@ -749,12 +749,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`。
 
 ## 图片编辑器宣发素材生成器刷新后不要丢快照
@@ -4298,6 +4298,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。
@@ -4787,8 +4808,8 @@
 
 - 现象：像素规整后的图片虽然保持了源图宽高，放大观察却能看到相邻逻辑块占用的物理列数或行数不同，表现为部分块更宽、部分块更窄；整数倍样例看起来正常，换一张网格数不能整除输入尺寸的图才复现。
 - 原因：逻辑图宽高为检测后的列数、行数。把 `C × R` 的逻辑图用 nearest 恢复到 `W × H` 时，只要 `W % C != 0` 或 `H % R != 0`，目标栅格就只能在不同逻辑像素间分配 `floor / ceil` 数量的列或行；nearest 能避免混色，却不能让非整数缩放后的块严格等大。只用 `128 × 128 → 64 × 64 → 128 × 128` 这类整数倍测试会掩盖问题。
-- 处理：最终资产直接编码一格一像素的逻辑分辨率 PNG，不再执行输入 / 交付尺寸 nearest 恢复，也不要求成功输出与源图或占位尺寸相等。普通图片和角色的前置 Lanczos 交付尺寸归一仍用于确定检测输入；平底网格源与透明 RGBA 源仍必须同尺寸，不能把“取消输出同尺寸”误解为放开两个内部采样坐标系。
-- 验证：使用至少一组逻辑列数或行数不能整除输入尺寸的图片，断言输出宽高等于切线数减一而不是输入宽高；同时核对响应、project resource、账号素材和结果 layer 都记录最终 PNG 实际尺寸，且只持久化一个最终 PNG，没有输入尺寸恢复版、诊断图或额外资源。失败降级用例继续验证 Alpha / 交付尺寸守卫，不应因成功输出改为逻辑分辨率而删除。
+- 处理：采样仍是一格一像素；编码前只允许横纵同一整数 N 的 nearest 放大，N 取最接近规整输入尺寸的正整数，禁止非整数拉回精确 `W × H`。成品宽高比等于逻辑图，尺寸接近但不保证等于源图或占位。普通图片和角色的前置 Lanczos 交付尺寸归一仍用于确定检测输入；平底网格源与透明 RGBA 源仍必须同尺寸。
+- 验证：整数倍样例与非整除样例都不得出现宽窄不一的逻辑块；响应、project resource、账号素材和结果 layer 都记录最终 PNG 实际尺寸，且只持久化一个最终 PNG，没有未放大逻辑图、输入尺寸恢复版、诊断图或额外资源。失败降级用例继续验证 Alpha / 交付尺寸守卫。
 - 关联：`server-rs/crates/platform-image/src/pixel_art_snapper.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
 ## Codex CLI 节点不能把进程终态当成 Runtime 提交证据（2026-08-10）
@@ -4864,3 +4885,17 @@
 - 原因：测试代码仅为动态生成 RSA fixture 引入 `openssl` dev-dependency，从而把原本使用纯 Rust 加密实现的 crate 额外绑定到本机原生 OpenSSL 工具链；Strawberry 附带的库面向 MinGW，不等于可用的 MSVC OpenSSL SDK。
 - 处理：测试优先使用明确标记、只供测试的固定 PEM fixture，并继续通过项目自身的密钥解析与签名验证路径覆盖真实行为；不要仅为生成 fixture 引入系统原生库，也不要把 MinGW OpenSSL 路径写入 `OPENSSL_DIR` 冒充 MSVC 依赖。
 - 验证：运行目标 crate 的 `cargo tree -i openssl-sys --target all` 确认依赖已退出，再执行包含测试目标的 `cargo test --tests`，不能只用不会编译 dev-dependency 的 `cargo check --lib` 代替。
+
+## 隔离 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 二进制成功不能替代该链路。