并行拆分客户端运行时与项目摘要模块

将 runtime_tools 拆为十五个职责模块并保留 Agent 可见性

将 Runner 拆为协议端点分发客户端与所有权模块

将进程会话拆为模型持久化生命周期 IO 恢复与测试模块

将项目摘要拆为十四个无环模块并保留一百一十二个导出

记录并行拆分边界与稳定树验收规则

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

@@ -5226,3 +5226,10 @@
 - 决策：Unix 浏览器子进程统一在 `/tmp/ga-browser-*` 下创建临时根目录和 Profile，并显式把该短目录作为子进程 `TMPDIR`；证据仍写入项目内既有受控目录。`image.inspect` 仅把精确 basename `desktop.png / mobile.png` 解析为当前 Agent、当前 run 下数字最大的已有 revision 截图，不跨 Agent、run 回退，也不改变显式项目相对路径语义。
 - 安全边界：截图别名仍经过项目根、祖先 symlink、普通文件、图片格式和总字节上限校验。没有当前 run 截图时失败关闭，不能为提高成功率搜索全项目或复用旧 run 证据。
 - 验收状态：短路径真实 Chrome smoke、截图别名定向测试、Rust 串行全量 `1139 passed / 5 ignored / 0 failed` 和确定性自主构建 E2E 均通过。外部 Provider 后续轮次在已完成真实浏览器试玩后出现单次非重试 Provider lifecycle 失败，整轮仍为 FAIL；当前不能据此宣称外部 Provider 完整 PASS。
+
+## 2026-07-22 AI 游戏创作客户端大型模块按稳定 facade 并行拆分
+
+- 背景：首轮拆出 `agent.rs`、`project.rs`、`tests.rs`、`App.tsx` 和真实 E2E 脚本后，客户端仍有多个 4k 至 10k 行的单文件热点，继续把工具、Runner、进程会话和项目摘要堆在单文件中会扩大多人修改冲突和审查范围。
+- 决策：本轮只做结构搬迁，入口文件保留原 API facade，不改函数名、测试名、Tauri 调用路径和业务行为。`runtime_tools.rs` 从 `9586` 行降到 `69` 行并拆为 15 个工具职责模块；`runner.rs` 从 `5450` 行降到 `31` 行并拆为 protocol、state、endpoint、project owner、dispatch、server、client 和 tests；`process_session.rs` 从 `4837` 行降到 `23` 行并拆为 model、persistence、lifecycle、I/O、recovery 和 tests；`projectSummary.ts` 从 `5801` 行降到 `138` 行，显式转导出原 112 个符号，具体摘要按常量、路径、Trace、产物、资产、规划、试玩、质量、交付、运行和引导拆分。
+- Rust 可见性：嵌套子模块会改变 `pub(super)` 的直接父级语义。`runtime_tools` 中原本要供 `crate::agent` 兄弟模块使用的符号最小化调整为 `pub(in crate::agent)`；`runner` 和 `process_session` 的内部兄弟调用仍经父模块 facade 或直接父级 `pub(super)`，不扩大到 crate 公共 API。
+- 验收：稳定共享树的客户端 `cargo fmt --check`、typecheck、Prettier 和编码检查通过；Rust 串行全量 `1139 passed / 5 ignored / 0 failed`，客户端前端 `329/329` 通过，确定性自主可玩 E2E 继续满足 17 次 Provider lifecycle、revision `0 -> 2`、真实浏览器 `37/37` 和零残留/泄漏。

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

@@ -3497,3 +3497,17 @@
 - 原因：Provider 能看到固定截图名，却看不到持久证据路径中的 Agent、run 和 revision；让模型猜完整内部路径既不稳定，也会扩大私有路径暴露面。
 - 处理：只为精确 basename 提供受控别名，解析到当前 Agent、当前 run 下最新数字 revision；显式路径继续按原规则处理。严禁跨 run 搜索“最近截图”，否则旧轮次成功证据会污染当前验收。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/image_inspect.rs`。
+
+## Rust 大文件拆成嵌套模块后不能机械保留 pub(super)
+
+- 现象：函数正文原样搬到 `foo/bar.rs` 后，兄弟模块或原父模块突然无法访问；为了尽快编译又容易把全部符号改成 `pub(crate)`，无意扩大内部 API。
+- 原因：`pub(super)` 永远指当前模块的直接父级。源文件从 `crate::agent::runtime_tools` 变成 `crate::agent::runtime_tools::bar` 后，原可见范围随层级一起缩小。
+- 处理：先记录拆分前公开符号和可见性数量。只把确实需要供 `crate::agent` 兄弟模块调用的 `runtime_tools` 符号改为 `pub(in crate::agent)`，其余保持私有或直接父级 `pub(super)`；入口 facade 显式重导出原公开 API。拆分后比对公开 API、测试名和测试路径，并跑全 crate 编译与串行测试。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools.rs`、`apps/ai-game-creator-shell/src-tauri/src/runner.rs`、`apps/ai-game-creator-shell/src-tauri/src/process_session.rs`。
+
+## 共享工作树并行拆分期间不能启动全 crate 验收
+
+- 现象：真实 E2E 在准备 CLI 阶段以 Rust exit `101` 退出，任务、run 和 Provider lifecycle 全为 0；同一代码在并行 Agent 停笔后可以正常编译。
+- 原因：多个 Agent 虽然拥有互不重叠的写入文件，但全 crate 编译会同时读取所有模块。某个入口刚写入 `mod`、对应子文件尚未全部落盘时启动构建，会读到合法的中间态半成品。
+- 处理：并行 Agent 只做各自 scoped 格式和测试；主 Agent 等所有写入方正式完成并关闭后，再在稳定共享树统一运行 crate fmt、全量测试和真实 E2E。编译前失败且 `stdin/provider/task=0` 的轮次只能算 harness 准备失败，不能归因给 Runtime 行为。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/runner.rs`、`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e/`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -673,3 +673,5 @@ game-project/
 - 本轮 V1.44 wrapper 与正式子 suite 均为 **PASS**：Provider 共 `17` 次 planning、异常请求 `0`；项目从 revision `0` 推进到 `2`，最终 `game/index.html` 为 `4924` 字节；`lane-defense-v1` 的植物选择、放置、敌人移动与受伤、胜利、下一关和重开共 `37/37` 断言通过，桌面与移动浏览器验证通过；三份专业回执全部认领，Supervisor assistant 唯一，pending、confirmation、user-input、provider batch/retry/handoff、tool-plan handoff、finalization journal、reconciliation、重复和泄漏计数均为 `0`，隔离 Runner、AppData、配置和项目已清理。该确定性 loopback PASS 不能替代外部 Provider 可用性验收；外部路由仍须单独形成同轮完整 PASS。
 - 2026-07-22 的外部 Provider 排障补齐两个宿主边界：Chrome 子进程必须使用 `/tmp/ga-browser-*` 短 `TMPDIR`，避免隔离 AppData 令 SingletonSocket 超过 Unix 路径上限；`image.inspect` 的 `desktop.png / mobile.png` 固定别名只解析当前 Agent/run 最新 revision 截图，不能跨 run 回退。对应真实 Chrome smoke、Rust 串行全量 `1139/1139` 和确定性正式 E2E 已通过。
 - 外部 Provider 仍无可拼接的完整 PASS：一轮因 Chrome status `134` 失败，一轮在真实浏览器 `37/37` 后因截图 basename 无法解析耗尽循环；别名修复后的独立轮次已再次推进到真实浏览器通过和截图检查阶段，但 `58` 个 Provider lifecycle 中出现 `1` 个非重试失败，父 turn 终态为 failed。后续必须以新的独立完整轮次证明生成、静态检查、真实浏览器、截图审阅、唯一 Supervisor 回复和零残留全部同轮通过。
+- 2026-07-22 的并行结构拆分把 `runtime_tools.rs / runner.rs / process_session.rs / projectSummary.ts` 收敛为 `69 / 31 / 23 / 138` 行兼容 facade，具体实现分别下沉到职责子模块。该轮不改变 Runtime、Runner、Tauri 或前端导出契约；Rust 嵌套模块只在原 `crate::agent` 可见性确有需要时使用 `pub(in crate::agent)`，不得统一放宽为 `pub(crate)`。
+- 结构拆分的稳定树门禁为 Rust 串行全量 `1139 passed / 5 ignored / 0 failed`、客户端前端 `329/329`、typecheck、客户端 crate fmt、Prettier、encoding 和确定性自主可玩 E2E PASS。并行写入期间发生在 CLI 构建阶段、尚未创建 run 的 exit `101` 不计作 Runtime E2E 结果。