合并 origin/master（58 个提交）：生产 Nginx 模板收敛与记录同步

- 合并 origin/master 58 个提交，解决 2 处文件冲突：决策记录与踩坑记录均按两侧新增条目并存处理
- claude_code_cli.rs 自动合并通过：本机 Claude sidecar 诊断改动与上游 sidecar 归位并存，无重复函数定义、无冲突残留
- 保留本地未推送提交：AGC Claude 执行认证与错误诊断、Claude sidecar 超时诊断
- 本次推送主体内容不变：生产 Nginx 模板收敛、host-only snippet 与运维/踩坑/决策文档同步

docs/README.md

@@ -38,6 +38,7 @@
 
 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
 - [AGC 后端框架整理与演进路线](./technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)：共享 Runtime、本地执行宿主、云端控制面、领域/平台适配器及分阶段收口边界。
+- [AGC 随包资源 staging 归位](./technical/【技术方案】AGC随包资源staging归位-2026-09-26.md)：随包资源改由准备步骤在 `tauri dev|build` 之前一次性生成、`build.rs` 退化为校验者；含缓存与原子性合同、入口接线、验收判据与里程碑拆分。
 - [AGC 异步操作可恢复闭环](./【技术方案】AGC异步操作可恢复闭环-2026-09-14.md)：认证响应体、最近项目检查和首页自动创建的超时、逐项恢复与跨页防重合同。
 - [AGC 客户端稳定版生命周期大切换](./【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md)：统一 operation、认证/Runner、项目入口、本地恢复和 dev-stack 身份边界。
 - [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：历史方案，仅用于追溯 V2 的实现与退役过程，不作为当前实现依据。

docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md

@@ -10,7 +10,7 @@
 
 ## 背景
 
-AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（实时）、`turn-stream.jsonl`（文本段与工具交替顺序）、`tool-calls.jsonl`（已脱敏工具卡片），重进页面时还要额外接管活动回合快照。同一段文本和同一张工具卡片因此存在多个来源，实时与回读会互相覆盖，恢复路径也只能靠"哪个源先到"决定。
+AGC 项目开发聊天框当前同时从多处取数据：Direct 回合事件（实时）、另一份按顺序重建的回合投影、以及按读取期另算的工具卡片，重进页面时还要额外接管活动回合快照。同一段文本和同一张工具卡片因此存在多个来源，实时与回读会互相覆盖，恢复路径也只能靠"哪个源先到"决定。
 
 `.agent/conversations/project.jsonl` 里的 Codex 原始条目本身已经带着顺序（`function_call` 与 `function_call_output` 按写入顺序落行），顺序信息并不是协议缺陷，而是在投影层被丢弃。
 
@@ -18,10 +18,10 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 
 - AGC 项目开发对话的持久事实源只有 **项目对话历史**（`.agent/conversations/project.jsonl` 的原始条目）；消息文本、工具卡片和它们的先后顺序都从它派生。
 - 运行期间的回合状态只来自 **运行态事件**（Thread Manager 的 subscribe / consume / notify）；`notify` 只做唤醒，不携带状态。
-- **聊天投影** 在读取与渲染时生成，不落盘、不成为第二事实源；DirectProject 聊天框停止读取 `turn-stream.jsonl` 与 `tool-calls.jsonl`，也不再提供供前端读取的命令。DirectRuntime 自己那套进度事件与文件写入属于运行时账本，本轮保留不动。
+- **聊天投影** 在读取与渲染时生成，不落盘、不成为第二事实源；聊天视图只由项目对话历史与运行态事件驱动，不再有供前端读取的旁路命令。
 - 页面重进的运行态只由 `subscribe` 的 bootstrap 事件重建，删除活动回合快照接管路径。
 - 可见性判断留在前端聊天投影：后端历史分页只按原始条目切片，前端自己跳过不可显示条目并推进锚点。
-- 线上模型是 **ts-rs 导出的 tagged enum**（`agent/direct_thread_wire.rs`），不是"一个大结构体加一堆可空字段"：`DirectThreadItem` 用 `itemType` 区分条目，`DirectThreadEvent` 用 `type` 区分事件，前端直接消费生成的 TS 类型（改完 Rust 模型跑 `cargo test export_bindings`）。条目上的毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
+- 线上模型是 **ts-rs 导出的 tagged enum**（`agent/thread_manager/wire.rs`），不是"一个大结构体加一堆可空字段"：`ThreadItem` 用 `itemType` 区分条目，`ThreadEvent` 用 `type` 区分事件，前端直接消费生成的 TS 类型（改完 Rust 模型跑 `cargo test export_bindings`）。条目上的毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
 - 运行态事件与历史切片使用同形条目，Rust 在两侧套同一套安全过滤（脱敏、截断、路径归一），前端只有一个「原始条目 → 视图」投影函数。
 - 两侧的过滤口径必须完全一致，包含「哪些条目根本不是本项目的聊天条目」：Codex app-server 回显的用户消息（`userMessage` / 非 AGC 的 `role=user`）在落盘侧被过滤，在运行态事件侧也必须被过滤（`direct_thread_visible_item`）。少一侧就会出现「实时比历史多出两条同文本用户条目、各自开出一个耗时 0 秒的假回合，重进页面又正常」这类只有其中一侧的事实源缺陷。
 - 搬运层不生成展示形状：Thread Manager 只下发脱敏原始条目（`itemType` 原样透传），工具卡片的 `kind`、标题、折叠摘要都由前端生成。
@@ -43,7 +43,7 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 - 思考正文以 `item.delta{kind:"reasoning"}` 流式下发（`item/reasoning/summaryTextDelta` 与 `item/reasoning/textDelta`）。这不放宽可见范围：同一段文本本来就已落进 `project.jsonl` 并在 `item.completed` 展示；plan 文本与命令输出仍只降级为活动状态。
 - 首屏历史由 `subscribe` 返回的 `lastCompletedItemId` 锚定，再取最近切片；删除返回整份对话的历史命令。锚点是切片**新端（较新一侧）的边界且含该条**（命令参数 `throughItemId`）：比锚点更新的条目只从运行态事件来，历史切片与实时流因此不重叠；向后翻页仍用切片返回的 `firstItemId` 作为 `beforeItemId`（不含锚点）。订阅回执到达之前不读首屏，也不退化成"取文件尾"（那会把回执之后才完成的条目也拉进历史）。
 - 生命周期锚点独立于 replay 队列保存（队列会回收 `cleanable` 事件，新订阅的游标又在队尾，回收后无法反推"最新回合是 started 还是 completed"），`subscribe` 必须返回最新的一条 `turn.started` / `turn.completed`，否则新订阅无法判定回合是否仍在运行。
-- 前端工具卡片形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`：聊天卡片不再有回合身份，`tool-calls.jsonl` 的持久化形状仍保留 `turnId`（DirectRuntime 的账本没动）。
+- 前端工具卡片形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`：聊天卡片不再有回合身份。
 - 未识别 item 类型由 Rust 原样透传（只带类型与身份，Rust 侧留 TODO），当前由前端投影丢弃：哪些类型可见属于前端决策，不回 Rust 加白名单。
 - 删除范围包含前端对 `read_direct_turn_stream`、`read_direct_tool_calls`、`read_direct_project_history`（整份历史）与 `game-creator-direct-turn-update` 事件的调用；保留分页用的历史切片读取（`read_direct_project_history_slice`），且该切片从文件尾反向扫描。`list_game_creator_direct_active_turns` 有意保留：它服务首页跨页面的「运行中的项目」列表，不是聊天框读路径。
 - 前端删掉 `directTurnStream` / `directToolCalls` / 活动回合快照接管 / 瞬时应答文本这些并行状态，聊天视图只由 reducer 状态投影（含工具卡片）。
@@ -53,13 +53,12 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 
 ## 备选方案与取舍
 
-1. **保留 `tool-calls.jsonl` 作为"读侧已脱敏"缓存**：省一次脱敏与截断，但它成为与项目对话历史并行的第二事实源，卡片状态与顺序会和实时事件分叉。选择按读取期投影，必要时在进程内缓存。
+1. **保留一份"读侧已脱敏"的持久缓存**：省一次脱敏与截断，但它会成为与项目对话历史并行的第二事实源，卡片状态与顺序会和实时事件分叉。选择按读取期投影，必要时在进程内缓存。
 2. **保留 Direct 回合事件作为实时传输**：迁移量小，但同一段文本仍有两条实时链路，reducer 必须处理互相覆盖，正是本次要消除的问题。
 3. **让后端分页按"可显示消息数"切片**：界面能少写循环，代价是 Rust 需要理解 UI 可见性，界面规则一变就要同步改后端。
 
 ## 影响
 
-- 旧项目磁盘上遗留的 `turn-stream.jsonl` / `tool-calls.jsonl` 保留不动，不迁移、不清理、不再由 DirectProject 聊天框读取。
 - 工具卡片的脱敏与截断必须在读取期执行一次，不能因为"原始条目已在磁盘"就把未脱敏内容直接渲染到界面。
 - 回合结束语义务必由 `turn.completed` 判定（失败时同一事件带 `failure` 载荷，不新增事件类型）；缺少该事件的残留回合不得被渲染成运行中。
 - 两条已知边界，都**不**在本次补路径，且已被 [`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md) 取代（§3、§2）：① 宿主进程被强杀（`kill -9`）时没有任何 `Drop` 会执行，但队列随进程消失，新进程的订阅 bootstrap 因此不会看到"有开始没结束"，界面不会卡在忙碌态；② `turn.started` 之前的失败按发生位置分流——接单**之前**的是拒单，根本不产生回合（不写用户条目、不写失败诊断），接单**之后**的由这一轮的占用对象统一收口成 `turn.completed`，不存在"有回合却没有事件解释"的路径。
@@ -69,5 +68,5 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 - **调用级拒绝**（同一 `clientTurnId` 并发复用 / 项目已有另一条回合在跑 / 权限策略拒绝 / 目录锚不定 / 输入校验 / 环境与凭据未就绪）不属于回合失败：这一轮没有开始，只把原因回给命令边界（界面出运行错误横幅），不写失败诊断、不发 `failed` 事件、不进交付报告。此前它们与回合失败混在同一层、共用同一份错误文本，现在分流只认 typed 判据。
 - 「活动回合的唯一判据」约束的是**原生回合**：界面上的「本地已发出、原生还没认领」是投影的展示态（`DirectChatTurn.state = 'awaiting-start'`），由本地在途用户条目身份派生，不构成第二套原生生命周期，也不参与 `turnRunning` 的判定。
 - 三层数据流、变量归属与一次发送的时序写在代码里：`apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表在 `apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。改判据时同步这两处与对应测试。
-- 验收证据是端到端行为，不是单元测试：回合进行中杀掉应用进程后重开项目，应看到部分文本与工具卡片按原顺序出现且不显示忙碌；正常结束后重进应与实时渲染一致；文件系统不得再新增 `turn-stream.jsonl` / `tool-calls.jsonl`。
+- 验收证据是端到端行为，不是单元测试：回合进行中杀掉应用进程后重开项目，应看到部分文本与工具卡片按原顺序出现且不显示忙碌；正常结束后重进应与实时渲染一致。
 - id 空间已用源码核对：codex-rs `app-server-protocol/src/protocol/thread_history.rs` 中所有工具 item 都是 `id: payload.call_id.clone()`，而 `project.jsonl` 落盘的是原始 response item。真实 app-server 会话核对仍列为运行时验收项。

docs/project-memory/plans/【实施计划】AGC随包资源改由校验器读入-2026-09-26.md

@@ -0,0 +1,64 @@
+# 【实施计划】AGC 随包资源改由校验器读入
+
+| 字段      | 值                                                              |
+| --------- | --------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md` |
+| Status    | ready（待里程碑规范评审通过后开工）                              |
+| Owner     | suzmii / Agent                                                  |
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src-tauri/build.rs`：新增只读校验调用点；本里程碑内保持现有写入分支不变（不改变既有构建行为）。
+- `apps/ai-game-creator-shell/src-tauri/build_support/**`：把平台布局、组件白名单、摘要校验整理为可被构建脚本之外的独立工具复用的一处声明。
+- 新增随包资源准备工具及其测试（位置见「待确认决策」）。
+- 需要时扩展 `apps/ai-game-creator-shell/scripts/check-config.mjs` 的断言。
+- 文档：主规范未决问题收口、开发运维文档对应段落。
+
+明确不修改：
+
+- 三份 tauri 配置的 `resources` 映射、包内路径与安装包形态。
+- 运行时资源解析与完整性校验（`codex_cli.rs`、`plugin_host.rs`、`editor_adapters.rs`、`environment_check.rs`）。
+- 发布脚本流程、版本号机制、签名与上传。
+- dev 启动器与发布入口的接线（下一里程碑）。
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式（最后一个里程碑）。
+
+## 实现顺序
+
+1. **共用能力可复用**：确认 `build_support` 内的平台布局与组件白名单能被独立工具引用（现状先例：`src/agent/codex_cli.rs` 与 `main.rs` 已通过 `#[path]` 复用同一模块），把「布局 + 白名单 + 摘要校验」收敛为单一入口，避免准备工具另写一份清单。
+2. **准备工具骨架**：目标目录与清单写出、缓存 key（上游 lockfile 的 `resolved` + `integrity` + 布局版本 + 目标三元）、临时目录 + 原子替换、所有权与符号链接校验、并发串行化、单行汇总日志。先实现纯复制两条路径（随包组件、插件工作区），编辑器分支产物本轮仍由构建脚本生成。
+3. **幂等与失败关闭**：重复执行不改变内容与时间戳；上游缺失、摘要不匹配、目录被非本工具占用、目标平台不支持四类场景各自失败并给出可定位原因。
+4. **校验路径上线**：构建脚本在既有产物上执行只读校验（默认不影响现有写入行为），校验失败以明确原因中止。
+5. **测试与证据**：按里程碑「证据要求」补齐用例与运行记录。
+
+## 验证命令
+
+1. 声明唯一性与门禁：`npm run agc:bundled-resources:check`（已进 `agc:typecheck` 链），不一致时用 `npm run agc:bundled-resources:sync` 重新生成。
+2. 准备工具用例（含幂等与失败关闭）：`npm run agc:bundled-resources:test`。
+3. 校验路径独立运行（跳过写入分支）：`AGC_SKIP_RESOURCE_STAGING=1 cargo check --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`。
+4. Rust 用例：`cargo test --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml package_layout` 与 `cargo test --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml codex_bundle`。
+5. 幂等（真实工作区）：连续两次 `node apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`，第二次必须全部「命中缓存」，且两次之后的目录快照（相对路径、大小、mtime、sha256）完全一致。
+6. 并存一致：准备步骤产物与构建脚本产物逐文件比对（相对路径、大小、sha256）一致。
+7. 行为不回归：`cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-default-features`（本里程碑不承诺构建变快，仅确认行为与改造前一致，并记录当前构建耗时作为后续里程碑基线）。
+8. 门禁：`node apps/ai-game-creator-shell/scripts/check-config.mjs`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`，以及改动范围内相关 vitest/Rust 测试。
+
+## 风险与回滚点
+
+| 风险 | 影响 | 处理 |
+| --- | --- | --- |
+| 校验器误判把构建卡死 | 影响所有本机构建 | 只读校验先以「不影响写入行为」的方式接入；出现误判可先关闭校验调用点回滚 |
+| 准备工具与构建脚本并存产生双写 | 两处结果漂移、时间戳变化 | 并存期以「准备工具产物 == 构建脚本产物」逐文件比对作为过渡判据；不一致视为失败 |
+| 缓存 key 漏掉上游变化 | 静默用旧组件 | key 含 lockfile `resolved` + `integrity` + 布局版本 + 三元；清单校验作为第二道闸 |
+| 准备工具实现形态选错 | 返工 | 见「待确认决策」，评审时一次定清 |
+
+回滚点：本里程碑不改变既有构建行为，回滚只需移除校验调用点与准备工具，不影响产物与发布流程。
+
+## 已定决策
+
+准备工具的实现形态（主规范未决问题 1）**已定为混合**（2026-09-27，机制见主规范 §4.8）：
+
+- 上游获取、`integrity` 校验、归档安全与原子替换复用 Node 侧既有范式（`scripts/stage-node-runtime.mjs`、`scripts/prepare-macos-codex.mjs`）；
+- 平台布局、组件白名单与逐文件摘要校验复用 Rust 侧既有声明（`build_support/codex_bundle.rs`、`build_support/godot_bundle.rs`），由准备工具与校验路径共用同一份声明文件承载，不再各写一份清单。（上游原生包元数据的期望值后来并入同一份声明；`build_support/codex_package_metadata.rs` 已在 M2 因失去调用方删除。）
+
+理由：避免出现第二份组件白名单，同时不必重写 registry 下载、`integrity` 与 tar 安全校验；缺点是声明需要经过一次生成步骤才能在 Rust 侧使用，由 `check-package-layout.mjs` 门禁保证两者一致。

docs/project-memory/plans/【实施计划】DirectProject聊天真相源收敛-2026-09-16.md

@@ -8,20 +8,20 @@
 
 ## 修改边界
 
-- 允许修改：`agent/direct_thread_wire.rs`、`agent/direct_thread_manager.rs`、`agent/codex_app_server/`、`agent/direct_project_history.rs`、`main.rs` 命令注册、`src/features/project-workspace/generated/`（ts-rs 生成目录）、AGC 前端订阅与聊天投影、对应测试与 `docs/`。
-- 明确不修改：SpacetimeDB schema 与绑定、HTTP/OpenAPI、DirectRuntime 自己的进度事件与 `turn-stream.jsonl` / `tool-calls.jsonl` 写入、Codex durable thread 行为、审批弹层现有状态来源。
+- 允许修改：`agent/thread_manager/wire.rs`、`agent/thread_manager/mod.rs`、`agent/codex_app_server/`、`agent/direct_project_history.rs`、`main.rs` 命令注册、ts-rs 生成目录、AGC 前端订阅与聊天投影、对应测试与 `docs/`。
+- 明确不修改：SpacetimeDB schema 与绑定、HTTP/OpenAPI、Codex durable thread 行为、审批弹层现有状态来源；DirectRuntime 的进度事件与账本本轮不动（该账本随后已随 issue #553 整体删除）。
 - 保持 `.env` 未提交修改，不触碰个人配置。
 
 ## 实现顺序
 
-1. Rust 只搬运：`agent/direct_thread_wire.rs` 把 Codex 原始条目挑字段、脱敏、截断后下发，事件载荷与历史切片同形，不生成卡片形状；线上模型是 ts-rs 导出的 tagged enum（`DirectThreadItem` / `DirectThreadEvent` / bootstrap / consume / history slice），`at` 标 `#[ts(as = "f64")]`，改完模型跑 `cargo test export_bindings` 生成前端绑定。
+1. Rust 只搬运：`agent/thread_manager/wire.rs` 把 Codex 原始条目挑字段、脱敏、截断后下发，事件载荷与历史切片同形，不生成卡片形状；线上模型是 ts-rs 导出的 tagged enum（`ThreadItem` / `ThreadEvent` / bootstrap / consume / history slice），`at` 标 `#[ts(as = "f64")]`，改完模型跑 `cargo test export_bindings` 生成前端绑定。
 2. 条目身份归一：进队列前收敛成一个 `itemId`，事件 envelope 与前端形状里都不出现第二个 id 概念；历史切片的 `firstItemId` 继续取文件里的原始 item id。
 3. 删掉回合身份：`turn.started` 无载荷、`turn.completed{status}`，条目 / 增量 / 请求 / 生命周期锚点都不带 turn id；队列 `append` 直接收 `DirectThreadEvent`，`seq` 内部自算。
 4. 思考正文流式：`item/reasoning/summaryTextDelta` 与 `item/reasoning/textDelta` 产出 `item.delta{kind:"reasoning"}`；plan 文本与命令输出保持活动状态。
 5. 前端收敛为单一 reducer：`subscribe` 返回的 bootstrap 事件就是已暂存的运行态，游标已经在队尾，前端直接 reduce 这批事件即可（不需要为了拿这批事件再补一次 `consume`）；此后只由 notify 唤醒 `consume`。唯一例外是回执竞态：Rust 注册完 subscriber 就开始通知，而前端要等回执才知道 `subscriptionId`，这段时间到达的通知只能记欠账，回执到达后立刻补一次 `consume`（否则整轮最后一个事件之后可能再无通知，事件会卡死在队列里）。合并规则只保留"先到定形、后到补空白"（正文只增不减、工具状态允许从 running 升级到终态），`item.delta` 直接追加到运行态条目正文，删掉 `deltaText` 缓冲，`turn.completed` 把运行态条目并入历史再清空。
 6. 首屏与分页：以 `lastCompletedItemId` 为锚点取最近切片，历史读取改为从文件尾反向扫描；切片的新端边界由这个锚点给出（含该条，命令参数 `throughItemId`），首屏读取等订阅回执里的锚点，回执到达前不发请求、也不退化成「取文件尾」；之后锚点按原始 item id 推进（`beforeItemId`，不含锚点）。一次翻页操作在前端连拉，直到合并后聊天投影出现新回合（新的用户气泡）或 `hasMore=false`，每个操作上限 5 页；锚点未推进（`items` 为空 / `firstItemId` 为 null / 与请求锚点相同）时立即停止。可见性口径只在 `features/project-workspace/directHistoryPaging.ts` 实现一份，首屏与「显示更早」共用。
 7. App.tsx 接线：订阅 + 立即 reduce bootstrap + notify 唤醒 consume，聊天视图改由 reducer 状态投影（含工具卡片），删除 Direct 回合事件订阅与 `directTurnStream` / `directToolCalls` 状态。
-8. 删除只服务旧读路径的命令与前端调用（`read_direct_project_history`、`read_direct_turn_stream`、`read_direct_tool_calls`），DirectRuntime 自己的写入保留。`list_game_creator_direct_active_turns` 是唯一的例外并有意保留：它服务首页跨页面的「运行中的项目」列表（`WorkspaceLauncher` / `directActiveTurns.ts`），不是聊天框读路径。
+8. 删除只服务旧读路径的命令与前端调用（`read_direct_project_history`、`read_direct_turn_stream`、`read_direct_tool_calls`）。`list_game_creator_direct_active_turns` 是唯一的例外并有意保留：它服务首页跨页面的「运行中的项目」列表（`WorkspaceLauncher` / `directActiveTurns.ts`），不是聊天框读路径。DirectRuntime 自己的账本写入本轮保留，随后已随 issue #553 整体删除。
 9. 测试与文档收口：补 reducer 单测、解锁跳过的工具卡片用例、更新主规范并把冲突的实施计划与工具卡片文档改写为当前状态。
 
 ## 验证命令

docs/project-memory/plans/【里程碑】AGC编辑器分支产物归位与症状层补丁清理-2026-09-26.md

@@ -0,0 +1,115 @@
+# 【里程碑】AGC 编辑器分支产物归位与症状层补丁清理
+
+| 字段        | 值                                                              |
+| ----------- | --------------------------------------------------------------- |
+| Version     | 1.0                                                              |
+| Status      | in-progress（2026-09-28 已过 Windows 真机核心评审；2026-09-29 完成打包一致性验收，客户端加载待有编辑器环境的机器；Cocos payload feature 集差异待裁决） |
+| Date        | 2026-09-26                                                       |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 已实现（2026-09-27）
+
+- 声明新增三类「准备步骤」产物：`subdirectories[origin=prepared]`（Unity publish 目录）、`libraryStaging[].prepare + files`（Godot gdextension）、`nativePayloads[]`（Cocos bridge dll）；`plugins.prepareSteps` 描述每个准备步骤的程序、工作目录、指纹与必需产物。
+- 准备步骤（`scripts/prepare-bundled-resources.mjs`）按声明执行 `powershell.exe -File build.ps1` 与 `cargo build -p … --target …`，用内容指纹跳过未变化的步骤，校验必需产物齐全后才复制；命中指纹且产物齐全时零写入。
+- 构建脚本删除了三处产物生成与整棵树复制（`prepare_unity_editor_helper`、`prepare_godot_editor_extension`、`stage_cocos_editor_payload`、`stage_build_generated_plugin_payloads` 及其辅助函数，共减少约 220 行），只保留只读校验：源码派生内容逐文件比对、已准备产物存在性、Godot 随包库沿用既有深度校验（`godot_bundle::validate`）。Godot 随包文件清单改由声明提供（单一来源）。
+- `.taurignore` 的两份 staging 条目已删除（构建期不再写 `resources/plugins`，无需忽略）。
+- 准备步骤的 Windows 侧命令路径已随系统性审计在真机复跑（powershell/cargo 两条路径、产物归位与幂等均已验证）。
+
+## 目标
+
+编辑器分支（Unity/Godot/Cocos）的随包产物也由准备步骤生成，构建脚本不再调用外部工具链产出随包资源；此前为绕开自触发问题而加入的症状层补丁与说明全部删除，实现形态与主规范一致。
+
+## 范围
+
+- 三个编辑器分支产物的生成职责迁出构建脚本，包括需要外部工具链的两条路径。
+- 构建脚本内与资源生成相关的规避手段删除：残留清理逻辑、为幂等而设的辅助常量与判断、开发监听忽略条目中与随包资源相关的部分。
+- 平台与特性开关（哪些平台、哪些特性才需要这些产物）在新形态下保持既有语义。
+- 与发布打包、包内资源门禁、运行时解析的一致性核对。
+
+## 不在范围内
+
+- 编辑器分支本身的接入协议、宿主能力与运行时行为。
+- 外部工具链版本管理与安装流程（沿用现状）。
+- 随包组件与插件工作区的生成形态（上一里程碑已完成）。
+
+## 依赖与前置条件
+
+- 前两个里程碑验收通过。
+- Windows 环境具备 Unity/Godot 分支所需的工具链（.NET 与 CMake 等），以便验证产物生成与打包。
+
+## 验收标准
+
+- [ ] 构建脚本中不再存在向随包资源目录写入的分支，也不再调用产出随包资源的外部工具链。
+- [ ] 三个编辑器分支的随包产物路径、内容摘要、可执行位与迁移前逐项一致，且由准备步骤稳定产出。（2026-09-29 验收：路径集合与源码派生内容、Unity/Godot 产物逐字节一致；Cocos payload 因声明只构建 `windows-injection` 而与迁移前不同，且 MSVC 链接产物本身不可字节复现，见下方验收记录，口径待裁决）
+- [ ] 此前为规避自触发而加入的补丁（残留清理、幂等辅助、监听忽略条目）在代码与文档中全部移除，不再有「为了绕开构建问题」的说明。
+- [ ] 平台与特性开关语义不变：不支持的平台不产出这些资源，且不因此失败。
+- [ ] 全量门禁通过，且客户端在具备条件与不具备条件两种环境下都能给出明确结论（可用 / 缺组件及原因）。
+
+## 验收记录（2026-09-29，Windows 本机）
+
+### 打包一致性（验收标准第 2 条）
+
+准备步骤按发布入口同样的参数复跑（`prepareBundledResources({ target: 'x86_64-pc-windows-msvc', features: Set('unity-editor-execute','godot-editor-execute','cocos-editor-injection'), profile: 'release' })`）：`cocos-bridge-build 已构建`、`unity-helper-publish` / `godot-extension-build 命中缓存`、`plugins 重新生成`；随后连续三次复跑，`resources/plugins` 的 32 个文件内容与 mtime 均不再变化（稳定产出）。
+
+出包走同一发布入口（`runTauriBuild` + `--bundles nsis`），并临时把 `bundle.createUpdaterArtifacts` 置 false——本机没有 updater 签名私钥，只出安装包；产物 `target/x86_64-pc-windows-msvc/release/bundle/nsis/陶泥儿开发版_0.1.67_x64-setup.exe`（166452206 B，sha256 `04a0be8ab8f54d8f032ce86d3e5c7a99c1dd6e81f71d49b63486827b11a01940`）。`tauri.windows.conf.json` 里 `resources/plugins → plugins` 是目录级映射。
+
+包内核对：7z 解包得 2108 个文件，包内 `plugins/` 的 32 个文件与准备步骤产出的 `resources/plugins` **逐文件 sha256 完全一致**；`editor_adapters.rs` 的三个运行时相对路径（`UNITY_ATTACH_HELPER_RELATIVE` / `GODOT_BRIDGE_PAYLOAD_RELATIVE` / `COCOS_BRIDGE_PAYLOAD_RELATIVE`）加上声明里的必需产物共 17 项在包内全部命中。
+
+迁移前对照取两份：本机已安装的 2026-09-24 包（`%LOCALAPPDATA%\陶泥儿开发版\plugins`，迁移前产品产物），以及把 `src-tauri` 整体切回合并基线 `8f59c034f` 后在同一个工作树里跑 `cargo build --release --target x86_64-pc-windows-msvc --features=unity-editor-execute,godot-editor-execute,cocos-editor-injection` 得到的 `resources/plugins`。三份对照路径集合一致，源码派生内容（JS/HTML/JSON/license/notice）逐字节一致，Unity helper、Godot 扩展逐字节一致。
+
+两处已定性的差异：
+
+1. **Cocos payload 的构建 feature 集不同（需裁决口径）**：迁移前由同一次应用构建产出（`windows-bootstrap` + `windows-injection`，345088 B）；准备步骤按声明只构建 `windows-injection`（26112 B，见 2026-09-27 决策日志条）。两者导出面完全相同（`DllMain`、`cocos_editor_bridge_bootstrap_source`），差掉的是宿主侧 bootstrap 传输（`reqwest`/`tungstenite`/`inspector`），注入进程不使用；但按「内容摘要与迁移前逐项一致」的字面判据不成立。
+2. **MSVC 链接产物不可字节复现**：同一 source / feature / profile / target 连续构建的 payload 摘要不同（除 PE `TimeDateStamp` 外还有 22 字节 RSDS GUID 差异）；.NET publish 相反是确定的（Unity helper 跨两次重新发布逐字节一致），Godot 因 `buildId` 早退未重链也保持逐字节一致。因此「摘要一致」只在源码派生物、.NET 产物与命中工具链内部缓存的产物上成立。
+
+新发现的风险（本轮未修，不影响上述结论）：
+
+- 准备步骤的 `cocos-bridge-build` 与同一次应用构建写同一个输出路径 `target/<triple>/<profile>/deps/cocos_editor_bridge.dll`（两个 feature 单元同名产物），准备步骤的候选查找可能取到另一单元刚写下的文件；本轮实测两者交替后 cargo 会多一次重链。建议让准备步骤在独立 target 目录构建，或与应用的 feature 集对齐后从同一单元取产物。
+
+### 客户端编辑器分支（验收标准第 5 条）
+
+本机未安装 Unity / Godot / Cocos Creator（`Program Files`、`UnityHub`、scoop shims 均无），进入编辑器分支只会停在「未检测到编辑器进程」，拿不到「helper/扩展被加载」的真机结论，因此**本轮未执行**，需在有三种编辑器的机器上补做。
+
+已完成的自动化前段（本轮实测，用安装包解出的客户端、不安装）：
+
+- 从 NSIS 包 7z 解出后直接运行 `genarrative-ai-game-creator-shell.exe`：窗口落在 `http://tauri.localhost/`（生产态嵌入前端，不是 `devUrl`），首页正常渲染，最近项目与模板库可见——说明包内 `plugins/`、`skills`、模板资源都被正确读取（对照：用 `cargo build --release` 直接编出来的 exe 没有 `custom-protocol`，会去连 `127.0.0.1:3080` 并落到 chrome 错误页，不能拿它当打包客户端）。
+- CDP 主世界（`page.target().createCDPSession()` + `Runtime.evaluate`）可读只读投影：`list_agc_plugins` 返回 `agc-cocos-editor` / `agc-unity-editor`（`builtin=true`、`hasRuntime=true`、`adapter` 正确），`list_agc_skill_catalog` 返回 8 条 —— 插件的 JS 入口与 Skill 包都按声明进包。
+- `agc-godot-editor` 插件不在该列表里符合现役语义：`plugin_host.rs::plugin_matches_project` 只在当前项目是 Godot 工程（根或一层子目录有 `project.godot`）时才让它可见。
+- 三种编辑器分支的判据入口：`require_plugin_adapter` 缺适配器时报「当前客户端不支持 X 编辑器桥接」，适配器在 payload/helper 缺失时报各自缺组件文案（如 Godot「插件缺少原生 DLL 资源」），编辑器没开时报探测失败——补做时要按这三类分开记录。
+
+### 顺带定性：CI 唯一红项与本 PR 无关
+
+run 2980（HEAD `0cf536b6`）唯一失败项是 `tests::sessions::background_agent_runtime_can_write_memory_and_project_files`（`src-tauri/src/tests/sessions.rs:405`，第二个 provider follow-up 请求 `recv_timeout(2s)` 超时）：
+
+- 本 PR 对这条路径零改动：`src/` 下只有 `main.rs`（`#[cfg(test)]` 引入 `package_layout` 单测）与 `agent/codex_cli.rs`（去掉 `codex_package_metadata` 测试模块）两处**测试编译期**改动；`sessions.rs` 与 agent runtime 与合并基线逐字节相同。
+- 把 `src-tauri` 整体切回合并基线 `8f59c034f` 后，同一条命令在本机失败在同一断言（`second llm request: Timeout`）。
+- 本机实测第二个 follow-up 请求耗时 **5.18s / 4.87s**（两次），而测试预算 2s：该断言在本机裕量不足。master run 2979（lane 2 shard 3）也因另一条并发用例失败，属同一类时间预算抖动。
+- 结论：既有测试时间预算问题，不在本 PR 内顺手修。
+
+## 验证步骤（Windows 侧执行清单）
+
+准备：切到本里程碑分支，`npm ci`（需装上 `@openai/codex-win32-x64`），确认 `spacetime --version` 与 `server-rs` 锁定版本一致（仅本地 dev 需要）。
+
+1. **准备步骤单独跑（不打包）**
+   - `npm run agc:bundled-resources:prepare -- --target x86_64-pc-windows-msvc`
+   - 预期：一行汇总日志；`src-tauri/resources/plugins/agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe`、`agc-godot-editor/native/gdextension/` 下的扩展在位。
+   - Cocos payload 只在 injection 构建下交付（与迁移前一致）：加 `--features=cocos-editor-execute,unity-editor-execute,godot-editor-execute,cocos-editor-injection` 再跑一次，确认 `agc-cocos-editor/native/payload/cocos-editor-bridge.dll` 同时出现在插件工作区与随包目录。
+   - 再跑一次：预期全部「命中缓存」，且 `resources/**` 的文件时间戳不变。
+2. **构建期不再写随包资源**
+   - 取 `src-tauri/resources` 全量快照（相对路径/大小/mtime/sha256）→ `touch apps/ai-game-creator-shell/src-tauri/build.rs` → 再 `cargo build` → 两次快照必须逐项一致。
+3. **构建新鲜度**：源码不变时连续两次 `cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`，第二次应为秒级 `Finished`，且不再出现 `Compiling genarrative-ai-game-creator-shell`。
+4. **打包一致性**：出一次 Windows 安装包，核对包内 `plugins/` 下三种编辑器分支产物的路径与 sha256 与迁移前一致；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --no-run` 必须通过（会触发只读校验，所以要先跑过准备步骤）。
+5. **客户端启动**：进入 Unity/Godot/Cocos 编辑器分支各一次，确认对应 helper/扩展被加载，没有「缺少组件」类提示。
+6. **边界（负例）**
+   - 删掉 `plugins/agc-unity-editor/dotnet/publish/` 且让工具链不可用后打包：准备步骤必须给出明确失败原因（缺工具链/缺产物），而不是静默产出缺组件的包。
+   - 删掉 `target/agc-resource-staging.json` 再跑准备步骤：预期重新生成，产物内容不变（丢缓存只多一次哈希）。
+   - 删掉 `plugins/agc-unity-editor/dotnet/publish/win-x64/.agc-source.sha256` 后重跑准备步骤：预期重新执行 dotnet publish，而不是复用旧产物。
+   - 手工改 `resources/**` 一个字节后 `cargo build`：只读校验必须失败（该规则覆盖 source 派生内容；prepared 产物只查存在性，见排障经验）。
+
+记录：把每步命令、关键输出与结论贴回本里程碑或对应 PR；未通过项回到主规范 §9 记为未决问题。
+
+## 证据要求
+
+- 自动化：编辑器分支产物的摘要对比、平台门槛用例、配置门禁与包内资源门禁。
+- 运行时：Windows 上一次完整打包与一次客户端启动，确认编辑器分支产物被读取。
+- 边界：缺少外部工具链、缺少组件、非目标平台三种情形下的失败与跳过语义。

docs/project-memory/plans/【里程碑】AGC随包资源改由校验器读入-2026-09-26.md

@@ -0,0 +1,51 @@
+# 【里程碑】AGC 随包资源改由校验器读入
+
+| 字段        | 值                                                          |
+| ----------- | ----------------------------------------------------------- |
+| Version     | 1.0                                                         |
+| Status      | completed（2026-09-27）                                     |
+| Date        | 2026-09-26                                                  |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 已定决策（2026-09-27）
+
+- **实现形态：混合**——生成归 Node（`scripts/prepare-bundled-resources.mjs`），声明与校验归 Rust。依据与对比见主规范 §4.8。
+- **单一声明**：`build_support/package-layout.json` 是唯一人工声明；Rust 侧使用由 `scripts/check-package-layout.mjs` 生成的编译期常量（`package-layout.generated.rs`），门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链；运行期 `codex_bundle.rs` 的公开接口与取值不变。
+- **校验收口边界**：本里程碑对随包 Codex 目录做全量校验（清单 schema/平台/版本、文件集合、逐文件摘要、第三方声明、可执行位、白名单外文件）；插件随包目录只校验必需组件与符号链接。插件产物的逐文件摘要校验在 M2 由准备步骤写入树内清单后启用——M1 期间构建脚本仍整体重建 `resources/plugins`，树内清单会被清掉。
+- **独立验证入口**：`AGC_SKIP_RESOURCE_STAGING=1` 让构建脚本只跑只读校验、跳过写入分支。
+
+## 目标
+
+构建脚本不再需要「自己写随包资源」才能成立：在约定目录已有合规资源时，构建只做只读校验并通过；校验失败时给出明确原因并拒绝继续，而不是静默重新生成。
+
+## 范围
+
+- 随包资源的合规性判定：平台目录存在、清单 schema 与平台一致、逐文件摘要一致、必需组件齐全、版本与上游锁定一致。
+- 资源生成能力的可复用化：同一份布局与摘要校验能力既能被构建期校验使用，也能被准备步骤使用，不得出现第二份组件白名单。
+- 生成结果的稳定性要求：同一输入重复生成时，产物内容与文件时间戳不发生变化。
+
+## 不在范围内
+
+- 接入 dev 与发布入口（下一里程碑）。
+- 移除构建脚本里的资源写入分支。
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用。
+- 运行时资源解析顺序、完整性校验语义与打包配置里的资源映射。
+- Linux 产物支持。
+
+## 依赖与前置条件
+
+- 主规范第 4.3 与第 4.4 节的合同（准备步骤合同、构建脚本退化后的职责边界）。
+- 现有随包资源与清单已由当前实现产出，可用于校验回归。
+
+## 验收标准
+
+- [ ] 资源合规时，校验路径可独立运行并通过，不依赖构建脚本的写入分支。
+- [ ] 上游锁定版本、平台、逐文件摘要、必需组件四类不一致各自被拒绝，并给出可定位的原因。
+- [ ] 重复执行资源生成，产物内容与文件时间戳不变（幂等）。
+- [ ] 同一份布局与组件白名单只有一处声明，构建期校验与准备步骤共用。
+
+## 证据要求
+
+- 自动化：资源校验的通过/拒绝用例；同输入重复生成后目录快照对比（内容 + 时间戳）。
+- 运行时：本机在既有随包资源上运行一次校验与一次构建，确认资源被正常读取且构建行为与改造前一致。
+- 边界：目标平台不支持、上游缺失、摘要不匹配、目录被非本工具内容占用四种场景各自的失败输出。

docs/project-memory/plans/【里程碑】AGC随包资源生成接入dev与发布入口-2026-09-26.md

@@ -0,0 +1,48 @@
+# 【里程碑】AGC 随包资源生成接入 dev 与发布入口
+
+| 字段        | 值                                                              |
+| ----------- | --------------------------------------------------------------- |
+| Version     | 1.0                                                              |
+| Status      | in-progress（2026-09-27 起实施）                                 |
+| Date        | 2026-09-26                                                       |
+| Parent Spec | `docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md` |
+
+## 目标
+
+随包资源在客户端开发与发布两条链上，都由启动/打包之前的准备步骤一次性生成；构建脚本不再承担生成职责，源码不变时构建不再重复编译。
+
+## 范围
+
+- 客户端开发的启动流程：在拉起客户端之前完成资源准备，命中缓存时不重写任何文件。
+- 发布打包流程：Windows 与 macOS 两条链在拉起打包工具之前完成资源准备，包括既有的运行时资源准备点。
+- 纯复制型资源（随包组件与插件工作区）的生成职责从构建脚本迁出。
+- 不打包场景（仅校验、不产包）的放行口径。
+
+## 不在范围内
+
+- 编辑器分支产物（Unity/Godot/Cocos）的生成方式与外部工具链调用（下一里程碑）。
+- 打包配置里的资源映射、包内资源门禁与安装包形态。
+- 运行时资源解析与完整性校验语义。
+- 构建脚本中与资源无关的既有职责（配置能力、提示词产物、元数据）。
+
+## 依赖与前置条件
+
+- 上一里程碑的验收通过：资源校验可只读通过、生成幂等、白名单唯一。
+- M1 交付的准备步骤与声明门禁已在位：`apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`（Codex 与插件两条纯复制路径，写临时目录后原子替换，命中缓存不重写）与 `npm run agc:bundled-resources:check`（已进 `agc:typecheck` 链）。本里程碑需要让准备步骤改为在 `resources/plugins` 内写入自己的清单，并停止构建脚本对该目录的整体重建，插件产物的逐文件摘要校验才能启用。
+- 开发与发布两条链在拉起客户端/打包工具之前都有明确可插入的准备阶段。
+- Windows 与 macOS 均需具备可验证的开发环境（两个平台各自验收）。
+
+## 验收标准
+
+- [x] 客户端开发启动一次成功：不再出现因资源变更而触发的重复构建，客户端与运行器进程稳定存活。（证据：清理 `AGC` dev 探针——`tauri dev` 全程 `Rebuilding application` 0 次、`Running DevCommand` 1 次、主 crate 仅编译 1 次，app 起来后持续处理项目；完整 `npm run agc` 在本机被 SpacetimeDB `Pre-publish check`（401 InvalidSignature / 502 Bad Gateway）阻断，属既有本机环境问题。）
+- [x] 源码不变时连续两次构建，第二次为秒级完成；构建脚本声明的输入中不再出现随包资源路径。（证据：`cargo build --no-default-features` 连续三次 0.69 / 0.22 / 0.22 秒；强制构建脚本重跑后 `resources/codex` 与 `resources/plugins` 快照逐项不变。）
+- [ ] Windows 与 macOS 打包产物中的随包资源，与迁移前逐项一致（路径、内容摘要、可执行位）。（macOS 侧 `check-macos-bundle.mjs` 待打包验证；Windows 待 M3 归位三处构建期产物后复验。）
+- [x] 准备步骤连续执行两次不改变产物内容与时间戳；缺少准备步骤时，打包与启动以明确错误失败，而不是静默产出缺组件的包。（证据：准备步骤 10 条用例含幂等、上游缺失、上游元数据漂移与失败关闭；`AGC_SKIP_RESOURCE_STAGING=1` 在既有产物上只读通过；构建脚本校验缺失组件时 fail closed。）
+- [ ] 本机 Rust 门禁（会触发构建脚本的测试入口）与不打包构建路径仍然可用。（macOS 侧已验；Windows 的 `check:rust:shell` 待真机确认。）
+
+## 证据要求
+
+- 自动化：构建新鲜度日志、构建脚本输入清单、准备步骤幂等快照、包内资源门禁脚本结果。
+- 运行时：macOS 与 Windows 各一次客户端启动，确认随包组件被读取而非回退到外部安装。
+- 边界：缺少准备步骤、缓存命中、上游锁定变化三种情形下的行为。
+1

docs/project-memory/plans/【里程碑】DirectProject聊天真相源收敛-2026-09-16.md

@@ -11,7 +11,7 @@
 
 AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话历史**（`.agent/conversations/project.jsonl`）与 **运行态事件**（Thread Manager `subscribe` / `consume` / `notify`）。Direct 回合事件、`turn-stream.jsonl`、`tool-calls.jsonl` 与活动回合快照都不再是聊天视图的输入。
 
-边界固定为：Thread Manager 只是**搬运层**——把 Codex 原始条目挑字段、脱敏、截断后下发；工具卡片的形状、可见性与合并全部由前端投影完成。线上模型是 ts-rs 导出的 tagged enum（`agent/direct_thread_wire.rs`），条目身份只有一个：Rust 在进队列前归一成一个 `itemId`，不再暴露第二个 id 概念，也不带任何回合身份。
+边界固定为：Thread Manager 只是**搬运层**——把 Codex 原始条目挑字段、脱敏、截断后下发；工具卡片的形状、可见性与合并全部由前端投影完成。线上模型是 ts-rs 导出的 tagged enum（`agent/thread_manager/wire.rs`），条目身份只有一个：Rust 在进队列前归一成一个 `itemId`，不再暴露第二个 id 概念，也不带任何回合身份。
 
 ## 范围
 
@@ -27,7 +27,7 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
 
 - 审批、提问与用户输入请求的状态机迁移；本次事件只作同一条流的 pass-through。
 - 跨进程回合账本、按回合统计与持久 turn ledger。
-- DirectRuntime 自己的进度事件与该运行时仍在使用的 `turn-stream.jsonl` / `tool-calls.jsonl` 写入：它们属于运行时的账本，本轮只切 DirectProject 聊天框的读路径。
+- DirectRuntime 自己的进度事件与该运行时的账本：本轮只切 DirectProject 聊天框的读路径；该账本（`turn-stream.jsonl` / `tool-calls.jsonl`）随后已随 issue #553 整体删除。
 - 旧项目磁盘上既有投影文件的清理、迁移或回填。
 - 非 DirectProject 运行时、Codex durable thread 语义、SpacetimeDB 与 HTTP 契约。
 
@@ -40,7 +40,7 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
 - 思考正文流式下发不放宽可见范围：被下发的就是此前已在 `item.completed` 展示、并已落进 `project.jsonl` 的同一段文本。
 - 失败与中止说明只在运行期显示（不写 `project.jsonl`），页面重进后不再出现。
 - 未知 item 类型由 Rust 原样透传（只有类型与身份，Rust 侧留 TODO），当前由前端投影丢弃。
-- 前端聊天卡片的工具形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`；`tool-calls.jsonl` 的持久化形状与 DirectRuntime 的写入保持不变。
+- 前端聊天卡片的工具形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`。
 - 「可显示」的判据取**前端回合反馈**：一次翻页操作连拉到「合并后聊天投影的回合数增加」为止。工具卡片与思考文本虽然能通过 `projectDirectThreadItem`，但可能整页落进已渲染回合的折叠「执行过程」，不构成用户可见反馈；口径只在 `directHistoryPaging.ts` 里实现一份，首屏与「显示更早」共用。
 - 首屏切片的**新端边界**只认 `subscribe` 回执里的 `lastCompletedItemId`（含该条）：回执到达之前不读首屏，也不退化成「取文件尾」；锚点缺失（订阅不可用 / 失败 / 历史为空）时才按文件尾取尾屏，手动重读保持按当前文件尾取尾屏的恢复语义。
 

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

@@ -6,6 +6,21 @@
 - 决策：生产 vhost 以 `deploy/nginx/genarrative.conf` 为唯一来源；生产机专属路径收进 `deploy/nginx/snippets/genarrative-host-extras.conf`，由主模板 include、由 Server-Provision 安装，新增平台路由仍必须在主模板内声明并同步 `deploy/pingora/nginx-route-parity.matrix.json` 与 Pingora 网关。snippet 内的 location 有意不在矩阵覆盖范围，Pingora 接公网 443 前必须单独确认这些路径的处理方式。
 - 边界：退役路由（`/match3d`、`/puzzle`、`/runtime/*`、`/gallery/*/detail`、`/works/detail`、`/worlds/detail`、`/bark-battle` 等）不再进 SPA allowlist，也不配置显式 404，统一落 `location /` 的 `error_page 404 /404.html`。`/home/` 是 2026-08-11 官网拆分前的历史入口，是否退役需与官网侧一起决定。
 - 验证方式：`node scripts/check-nginx-spa-routes.mjs`、`node scripts/check-pingora-route-parity.mjs`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`、`bash -n scripts/jenkins-server-provision.sh`；线上改后按生效配置烟测 `/profile`、模板 12 条 SPA 路由、`/admin/`、`/home/`、`/finance-forecast/`、`/medical-science/`、画廊 API 与 `/games/game_<id>/…` 发行网关。
+## 2026-10-01 DirectProject 审批拒绝原因留痕
+
+- 决策：宿主拒绝 app-server 的审批 / 交互请求时，原因必须落 AppData `RUST` 日志。稳定键 `agent.direct_codex.approval.denied`，字段为 `thread_id` / `method` / `reason` / `distinct_reasons`；未绑定宿主执行器时另记 `agent.direct_codex.interaction.no_adapter`（`method` / `outcome`，`outcome` 区分 `decline` / `empty-permissions` / `unsupported-method`）；回包未送达另记 `agent.direct_codex.approval.response_delivery_failed`，`cause` 区分 `response-write-failed` 与 `turn-bind-mismatch`。
+- 原因：线上对审批只回 `{"decision":"decline"}`，模型与用户都看不到是哪一道闸门（合同缺失 / 预算耗尽 / 阶段已收束 / item 不在途 / 无适配器）拦下的，只能靠复现。
+- 边界：`reason` 只接受 `execution.rs` 内的静态分类或宿主自己的错误文本；透传的宿主错误在留痕出口统一走 `sanitize_diagnostic_message`，不带请求参数、上游正文、路径或凭据（去重键也用脱敏后的文本）。有界去重一律按 `MAX_DENIED_REASON_LOGS = 64` 条封顶——适配器路径按回合内 `(method, reason)`、未绑定执行器路径按进程级 `(method, outcome)`、回包未送达按回合内原因各只记一次。拒绝留痕在释放审批临界区（`state`）之后进行；回合收束说明按 `cause` 区分，只有 `response-write-failed` 才说「回包丢失」，`turn-bind-mismatch` 说明作用域无法确认。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/execution.rs`。
+- 验证：`cargo test --bin genarrative-ai-game-creator-shell agent::codex_app_server::execution::tests`（15 passed，含 `denied_approval_records_its_reason_once_per_turn`、`denied_reason_logging_is_bounded`）、`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-30 退役 DirectProject 工具调用与回合流账本（issue #553）
+
+- 背景：`tool-calls.jsonl` / `turn-stream.jsonl` 是只写不读的账本——读命令在 2026-09-16 随聊天真相源收敛删除后，唯一"消费方"是 `game-creator-direct-turn-update` 事件，而全仓已无监听方；工具卡片的真实读路径早已是「项目对话历史 + 运行态事件」的前端投影。issue #553 还暴露了同一时期绝对路径脱敏误伤 HTML 结束标签的问题。
+- 决策：整体删除 DirectRuntime 的 `turn-stream.jsonl` / `tool-calls.jsonl` 写入器、`DirectToolCallCollector`、回合流节流器、`DirectCodexTurnObservation::ToolCall` 与 `GameCreatorDirectTurnUpdateEvent`；`update_active_turn` 保留，首页「运行中的项目」快照不变。工具卡片只由读取期在 `agent/thread_manager/wire.rs` 脱敏、截断的历史条目投影。
+- 边界：不在运行时做磁盘清理；旧项目里可能残留的文件不迁移、不读取，历史由 Git 保存。
+- 未修（另开）：`redact_absolute_path_tokens` 的无语境绝对路径扫描仍会把 HTML 结束标签、嵌套 JSON 转义里的 `/` 误判成路径，是 issue #553 的根因；本次只删死路径，未改扫描器。
+- 验证：`cargo test --bin genarrative-ai-game-creator-shell agent:: -- --test-threads=1`（929 passed / 0 failed / 5 ignored）、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
 
 ## 2026-09-30 release 渠道移除产品名与包名后缀
 
@@ -2119,6 +2134,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。钱包明细每次展开都重新读取充值中心 BFF，打开期间实时总额变化时继续补读；图片画板的生成扣费或退款完成后同时刷新总额与充值中心拆分。充值中心读请求必须使用 revision 门禁，支付创建、到账确认等权威响应写入时使旧读失效，避免旧响应覆盖新的每日免费 / 不限时明细。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
 - 2026-07-17 追加：主站、图片画板与 AI 游戏创作独立 App 的泥点账单统一复用 `packages/shared/src/components/PlatformProfileWalletLedgerModal`。共享组件只依赖 `ProfileWalletLedgerResponse`，承接来源 label、金额正负号、UTC 日期、余额兜底和 loading / empty / error 展示；`/api/profile/wallet-ledger` 请求、鉴权、打开状态与重试生命周期继续由各宿主持有，不把账户事实或后端副作用下沉到共享 UI。
 - 2026-09-07 追加：资产扣费在既有钱包流水 metadata 中记录服务端确定的 `assetKind`，`GET /api/profile/wallet-ledger` 只把白名单类型映射为可选用户文案 `reason`，不暴露原始 metadata、资源 ID、任务 ID 或未知内部枚举。共享账单组件优先展示非空 `reason`；历史、未知和空 metadata 继续按 `sourceType` 回退为“资产操作消耗”，不得由客户端猜测业务类型。
+- 2026-10-01 追加：账单不计入实际变动为 0 的条目，规则落在 SpacetimeDB 侧而不是展示层。写入侧只在余额真的变化时落账：每日免费 / 会员周期换期按 `resolve_expiring_points_wallet_transition` 先算出“换期后余额 + 实际变动”，变动为 0（含到期额度等于发放额度、余额不足以扣回到期额度、额度与发放都为 0）时只更新余额状态、不写 `profile_wallet_ledger`；通用结算入口 `apply_profile_wallet_signed_delta` 在 0 变动时同样直接返回当前余额。读取侧 `list_profile_wallet_ledger_entries` 在按余额结算链排序之后、截断 50 条上限之前剔除 `amount_delta == 0` 的存量行，因此历史遗留的 0 流水也立即从账单消失，且不占用列表上限、不改变其余条目的先后与 `balance_after` 语义。此前 `update_profile_wallet_balance_for_expiring_points` 只判断“到期额度与发放额度都为 0”，判的是入参而不是实际余额变动，所以余额不变的换期流水仍会落账并显示成 0。
 - 影响范围：`profile_recharge_product_config` 默认商品、充值中心 read model、共享前后端契约、主站与图片画板泥点资产入口、充值弹窗、后台充值商品默认值。
 - 验证方式：充值与统一入口定向前端测试、`npm run typecheck`、充值商品定向 Rust 测试、`cargo check -p spacetime-module -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -9086,6 +9102,35 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证（真实上游 smoke，本地 dev DB）：清空 `agc_model_catalog` 后启动 api-server → 日志 `已按上游模型列表初始化 AGC 模型目录 revision=1 model_count=6`；登录后 `GET /api/llm/models` 返回同一批模型、`displayName` 即上游原名、默认项为排序后第一项；上游不可达/非 2xx 时启动只记录 error、AGC 接口 `503` 且目录保持未初始化；目录已存在时重启不重写。
 - 边界（未验证/残留）：上游在售模型超过 32 条时同步会失败（目录项上限未改）；`qwen-image-3.0` 这类图像模型会一起进入目录，是否对 AGC 隐藏由 owner 在后台停用；混合版本期间未升级的 api-server 会把自己的 AGC 接口打到 `503`，module 与 api-server 必须同批发布/回滚。
 
+## 2026-09-27 AGC 随包资源改为「单一声明 + 准备步骤生成 + 构建期只读校验」
+
+- 背景：随包资源（内置 Codex CLI、插件工作区）由 `build.rs` 在构建期写入 `src-tauri/resources/**`，而这些路径同时被 tauri 配置的 `bundle.resources` 登记成构建输入，cargo 因此永远判 stale：Windows/macOS 每次构建重编主 crate（41–87 秒），macOS dev 反复 `Rebuilding application`、客户端起不来（issue #519）。三轮症状层修复（内容比对、权限跳过、`.taurignore`）都只减少写入次数，没有改变「构建期写被登记文件」这一结构。
+- 决策（形态：混合）：准备步骤用 Node（复用 `stage-node-runtime.mjs` / `prepare-macos-codex.mjs` 的下载、`integrity`、临时目录 + rename 原子替换），布局与摘要校验留在 Rust（复用 `codex_bundle.rs` / `godot_bundle.rs`），运行期模块公开接口与取值不变。
+- 决策（单一声明）：唯一人工声明是 `apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`（Codex 三元表与组件白名单、上游候选路径、第三方声明来源、插件随包子目录与跳过规则、平台与 feature 门槛）。Node 直接读该 JSON；Rust 读由 `scripts/check-package-layout.mjs` 生成的 `package-layout.generated.rs` 编译期常量（不解析 JSON、不引入生命周期妥协）。门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链，同时校验声明自身不变量：目标唯一、`executable` 属于白名单、每个目标恰有一条第三方声明来源，且 `codex.version` 与应用锁定的 `@openai/codex` 一致。
+- 决策（校验与独立入口）：`build.rs` 新增只读校验——Codex 目录校验清单 schema/平台/版本、文件集合、逐文件 sha256、第三方声明、可执行位与白名单外文件；插件目录校验必需组件与整树符号链接。`AGC_SKIP_RESOURCE_STAGING=1` 可跳过写入分支、只跑校验，用于在既有产物上单独验证校验路径。插件产物的逐文件摘要校验留到 M2（届时准备步骤在树内写清单，不再被构建脚本整体重建覆盖）。
+- 影响面：`apps/ai-game-creator-shell/src-tauri/{build.rs,build_support/**}`、`apps/ai-game-creator-shell/scripts/{check-package-layout.mjs,prepare-bundled-resources.mjs,prepare-bundled-resources.test.mjs}`、`apps/ai-game-creator-shell/package.json`、根 `package.json`、`.gitignore`、AGC 技术方案 §4.8/§8/§9、M1 里程碑规范与实施计划、开发运维文档。三份 tauri 配置的 `resources` 映射与包内路径不变。
+- 验证：`npm run agc:bundled-resources:check`；`npm run agc:bundled-resources:test`（9 passed，含幂等、上游缺失、非本工具目录、目标不支持、dry-run）；`AGC_SKIP_RESOURCE_STAGING=1 cargo check --no-default-features --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 在准备步骤产物上通过；准备步骤产物与构建脚本产物逐文件一致（相对路径、大小、sha256）；连续两次运行准备步骤第二次全部命中缓存，目录快照（含 mtime）不变。
+- 边界（未验证）：准备步骤尚未接入 dev 与发布入口（M2）；Windows 真机的构建新鲜度与打包未验证；Unity/Godot/Cocos 产物仍由构建脚本生成（M3）；Linux 上五条 staging 与校验均为 no-op。
+
+## 2026-09-27 AGC 随包资源准备步骤接入 dev 与发布入口，构建脚本退出写入
+
+- 背景：M1 只交付了单一声明、准备步骤与只读校验，构建脚本仍在写随包资源，所以 macOS 的 `npm run agc` 仍会因 `resources/codex/mac-native` 被重写而反复重建、`cargo build` 每次重编主 crate（41–87 秒）。
+- 决策（接线）：`start-tauri-dev.mjs` 在前端与配套后端就绪之后、spawn Tauri CLI 之前调用准备步骤（命中缓存零写入，日志前缀 `[ai-game-creator-shell]`）；`build-release.mjs` 的 `runTauriBuild` 与既有 `stageRuntime(target)` 并列调用 `stageBundledResources(target)`，`tauri build --no-bundle` 仍不强制 staging。两处都保留依赖注入，便于入口测试断言调用顺序与 no-bundle 行为。
+- 决策（写入边界，声明新增 `origin`）：`origin: source`（Codex 组件、插件 `src`/`panels`/`skills`/`native/payload`）由准备步骤写；`origin: build`（Unity `dotnet/publish/win-x64`）与外部工具链产物（Godot `native/gdextension`、Cocos payload）由构建脚本在产物生成后写。构建脚本删除 codex 与插件白名单的写入分支及 `stage_plugin_file`/`copy_plugin_tree`/`copy_plugin_file`，改为 `stage_build_generated_plugin_payloads`。
+- 决策（契约收口）：插件随包工作区改为与仓库源码逐文件比对（清单 + 逐文件 sha256 + 整树符号链接，构建期派生内容只查存在性），实现移入 `build_support/package_layout.rs` 以复用单测；上游原生包元数据（layoutVersion/version/target/entrypoint/resourcesDir/pathDir）改由准备步骤按声明校验，`build_support/codex_package_metadata.rs` 因失去调用方而删除。准备步骤改为同步实现（全部是本地同步 IO），入口可直接调用而无需子进程。
+- 影响面：`apps/ai-game-creator-shell/scripts/{prepare-bundled-resources.mjs,prepare-bundled-resources.test.mjs,start-tauri-dev.mjs,build-release.mjs,build-release.test.mjs}`、`apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts`、`src-tauri/build.rs`、`build_support/{package_layout.rs,package-layout.json,package-layout.generated.rs}`（`codex_package_metadata.rs` 删除）、`src/agent/codex_cli.rs`、技术方案 §4.9、M1/M2 里程碑与运维文档。
+- 验证：`cargo build --no-default-features` 连续三次 0.69 / 0.22 / 0.22 秒全程 fresh；强制构建脚本重跑（`touch build.rs`）后 `resources/codex` 与 `resources/plugins` 的快照（相对路径/大小/mtime/sha256）逐项不变；`cargo test --no-default-features … package_layout` 36 passed；`node --test scripts/prepare-bundled-resources.test.mjs` 10 passed（含上游元数据漂移被拒）；`node --test scripts/build-release.test.mjs` 39 passed（含 `stage → bundled → build` 顺序与 no-bundle 不 staging）；`npx vitest run tests/start-tauri-dev.test.ts` 12 passed（含「准备步骤先于 CLI 启动」）。
+- 边界（未验证）：Windows 真机未验证，且 Unity publish 目录、Godot gdextension、Cocos payload 仍是构建期写入，Windows 构建新鲜度要等 M3 归位；完整 `npm run agc` 在本机被 SpacetimeDB `Pre-publish check`（先后 401 InvalidSignature 与 502 Bad Gateway，属既有本机环境问题）阻断，未跑通整条 dev 启动链路。
+
+## 2026-09-27 AGC 编辑器分支产物归位：构建脚本彻底退出写入
+
+- 背景：M2 之后构建脚本仍生成 Unity publish 目录、Godot gdextension 与 Cocos bridge payload，这三处写入落在 `resources/plugins/**`（`bundle.resources` 映射目录），Windows 上仍会触发每次重编，`.taurignore` 的 staging 条目也还不能删。
+- 决策（声明扩展）：`subdirectories` 新增 `origin: prepared`；`libraryStaging` 增加 `prepare` 与 `files`；新增 `nativePayloads` 与 `plugins.prepareSteps`（程序类型、工作目录、指纹、必需产物）。Godot 随包文件清单改由声明提供——`godot_bundle::BUNDLE_FILES` 从生成的编译期常量取值，不再各写一份。
+- 决策（准备步骤执行器）：准备步骤按声明运行 `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File build.ps1`（Unity/Godot，Godot 额外移除 `PSModulePath`）与 `cargo build -p cocos-editor-bridge --target … --features windows-injection`；内容指纹命中且必需产物齐全时零写入；命令执行器可注入，便于在 macOS 上用假执行器覆盖调度、指纹与失败关闭逻辑。
+- 决策（构建脚本瘦身）：删除 `prepare_unity_editor_helper`、`prepare_godot_editor_extension`、`stage_cocos_editor_payload`、`stage_build_generated_plugin_payloads` 及其辅助函数（build.rs 415 → 193 行），只留只读校验，并新增「已准备产物存在性 + Godot 随包库深度校验」；`AGC_SKIP_RESOURCE_STAGING` 开关随写入分支一并删除；两份只含 staging 条目的 `.taurignore` 删除。
+- 影响面：`apps/ai-game-creator-shell/src-tauri/build_support/{package-layout.json,package-layout.generated.rs,package_layout.rs,godot_bundle.rs}`、`src-tauri/build.rs`、`scripts/{prepare-bundled-resources.mjs,prepare-bundled-resources.test.mjs,check-package-layout.mjs,build-release.mjs}`、两份 `.taurignore`、技术方案 §4.9/§8、M3 里程碑、运维文档、决策日志与排障经验。
+- 验证：准备步骤 13 条用例通过（含三类准备步骤调度、指纹跳过、缺产物失败关闭、幂等与失败关闭）；`npm run agc:bundled-resources:check` 通过；`cargo check --no-default-features` 通过（构建脚本仅剩只读校验，且不再出现在随包资源的写入路径上）。
+- 边界（未验证）：Windows 真机未验证——powershell/cargo 两条命令路径、Unity/Godot/Cocos 产物归位、包内容一致性与客户端加载，需按 M3 里程碑的验收清单在 Windows 上确认。
 ## 2026-09-24 命令入队化与待发消息队列归宿主：放行归 Thread Manager，CLI 直连入口退役
 
 - 决策（词表）：「接单 / 拒单」退役，命令边界的成功与失败改叫「入队 / 入队失败」；旧「接单」的语义角色
@@ -9265,7 +9310,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 列表排序（新增能力，同日）：`AdminListPanel` 增加 `sortable` / `sortValue` / `sortDescription`——列头渲染与表查询一致的排序按钮（`admin-table-sort-button` + 升/降/双向图标），点击按「正序 → 倒序 → 不排序」循环，同步 `th[aria-sort]`，排序是稳定排序（值相同保持服务端原顺序）。已接入**一次取全**的 5 个列表：邀请码列表、操作记录、灰度 Gate 列表、可配置开关、任务配置列表（这些接口没有分页，前端排序语义正确）。
 - 列表实现全量收口（同日续做）：把剩余 **15 处** `children` 形态列表全部迁到 `columns` + `renderRow`（表体 JSX 原样搬进 `renderRow`，外壳/状态/分页槽位不变）：`AdminRedeemCodePage`(2)、`AdminRechargeProductPage`、`AdminProjectSnapshotsPage`、`AdminErrorReportsPage`、`AdminAgcTrackingPage`、`AdminGameDistributionReviewPage`、`AdminGameManagementPage`(主列表 + 版本历史)、`AdminUserDetailDialog`(充值订单)、`AdminRechargeOrderPage`、`AdminAgcModelsPage`、`AdminEditorAssetQueryPage`、`AdminEditorShowcaseReviewPage`、`AdminAgcTemplatesPage`。迁移后全仓统计：`AdminListPanel` **26 处 / 21 个文件**，其中 **24 处 columns 形态**（含 2 处弹窗内 `surface="plain"`），仅剩 2 处非表格列表仍是 children 形态（账号管理卡片列表、账号配置的键值列表）；`<AdminTable>` 作为 children 的写法已归零。可排序列累计 **45 个**（新增写入 `AdminAgcTemplatesPage` 列头 4 个：模板/引擎版本/包大小/状态）。
 - 迁移中顺带处理的形态差异：① `AdminErrorReportsPage` 的详情弹窗原本嵌在列表面板里，随表格一起搬到面板外（遮罩是 fixed，视觉不变）；② `AdminAgcModelsPage` 的工具栏与状态行改为走 `toolbar` 槽位（列表面板按 toolbar → 加载行 → 表格渲染，顺序与原来一致）；③ `AdminAgcTemplatesPage` 的列表从共享 `ui/Table`（`genarrative-ui-table*`）换成 `AdminTable`，与其它页签视觉统一——该页唯一的 ui Table 只剩「上传模板」弹窗里的待上传队列表（有逐行校验/进度状态的编辑态表格，未纳入列表组件，属有意保留）。
-- 排序能力边界（重要）：后端目前**只有** `GET /admin/api/database/tables/{table}/rows` 与 `GET /admin/api/external-api-keys` 接受 `sortColumn`/`sortDirection`；其余列表在 handler 里写死顺序（例如埋点数据固定 `occurred_at desc`、错误报告按时间倒序）。因此埋点数据、客户端埋点、错误报告、项目工程、充值订单这类**分页明细列表暂时不能排序**——只在前端排「当前页」会给出错误结论，必须给对应接口加排序参数（DTO + handler + `adminApiTypes` + 契约/测试）后前端复用同一列头。账号管理是卡片列表（`children` 形态），本轮未加排序。
+- 排序能力边界（重要）：后端目前**只有** `GET /admin/api/database/tables/{table}/rows` 与 `GET /admin/api/external-api-keys` 接受 `sortColumn`/`sortDirection`；其余列表在 handler 里写死顺序（例如埋点数据固定 `occurred_at desc`、错误报告按时间倒序）。埋点数据、客户端埋点、错误报告、充值订单等分页明细不能只在前端排「当前页」，必须先让对应接口支持全局排序，再复用列头。项目工程采用独立的主动全量读取按钮：当前渠道完整读取成功后按同步时间降序、用户/项目 ID 升序，本地分页；原目录接口及上传/下载契约保持不变，不新增 OSS 索引或数据库表。读取限制为 200 页、10,000 个唯一项目、60 秒，可取消；失败保留原列表，切换渠道/令牌取消请求并销毁临时集合。账号管理是卡片列表（`children` 形态），本轮未加排序。
 - 本地假数据补齐：`scripts/admin-web-fake-api.mjs` 新增 `agc-models`、`game-distribution/games`、`profile/recharge-products`、`profile/redeem-codes`、`profile/tasks`、`agc/tracking-events` 夹具，并对 `profile/recharge-orders` 按 `AdminRechargeOrderEntryPayload` 的真实字段补齐（缺字段会让页面抛 `Cannot read properties of undefined`——后台没有 error boundary，整页会白屏）。**已知缺口**：充值管理页仍缺一处夹具字段（页面读 `undefined.find`），本轮没能出图；该页自身 21 条单测通过、类型检查通过，仅缺截图。
 - 排序验证：共享组件新增用例覆盖「正序 / 倒序 / 取消 + aria-sort + 行序」；现场实测邀请码列表按「创建」排序：正序 `EXPIRED-CODE, BETA-CREATOR, TAONIER-VIP-2026`、倒序翻回 `TAONIER…, BETA…, EXPIRED…`，`th[aria-sort]` 依次为 `ascending` / `descending`。
 - 边界（未完成）：未跑生产后台构建与真实后台接口联调（截图用假数据）；`apps/admin-web` 目前没有 error boundary，任何接口形状不符仍会把整页渲染清空（本次只加固了 `AdminAgcTrackingPage` 一处，其余页面同类写法未逐个排查）；`AdminAgcTemplatesPage` 的列表面板是本次新增的外壳（原页面没有面板），视觉上多了白底卡片。
@@ -9283,3 +9328,15 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 后台 AGC 模型目录新增 `agentMode`，只允许 `codex` / `cc`，缺失的历史目录按 `codex` 兼容；模型选择返回的公开摘要同步携带该绑定。
 - 客户端把后台 `codex` 映射到现有 Codex app-server，把 `cc` 映射到独立 Claude Code CLI adapter；不通过替换 Codex JSON-RPC 可执行文件实现。
 - Claude Code 只使用隔离环境和 AGC loopback MCP，禁用原生工具；取消通过独立 Direct 回合进程树回收处理。Codex、provider 和自定义 Responses 链路保持原路径。
+
+## 2026-09-30 合入 master 时把 Claude Agent SDK sidecar 归位到随包资源准备步骤
+
+- 背景：master `fb130d184` 新增 `cc` 执行模式与 Claude Agent SDK sidecar，sidecar 的 staging 写在 `build.rs`（构建期 `remove_dir_all` + 从 `node_modules/@anthropic-ai/**` 复制 `resources/claude-agent`），同时把 `resources/claude-agent` 映射进**基线** `tauri.conf.json`。本分支的 M1–M3（issue #519）已把「构建期写随包资源」定性为结构问题，合入时必须按同一套架构落地，不能把写入分支带回来。
+- 决策（归位实现）：新增声明 section `claudeAgent`（锁定版本、资源目录、sidecar 入口源码、上游 SDK 包与平台原生运行时包的目标表、复制跳过规则）。Node 准备步骤整目录原子替换 staging，缓存 key = `layoutVersion + target + 声明版本 + 入口摘要`，命中即零写入；`build.rs` 只读校验：入口与仓库源码逐字节一致、SDK 与原生运行时 `package.json` 版本等于声明、原生运行时在位（unix 还要求可执行位）、随包目录里没有白名单外的文件。
+- 决策（版本单一真源）：`CLAUDE_AGENT_SDK_VERSION` 由声明生成；`claude_code_cli.rs` 的 sidecar 身份串改用 `cargo:rustc-env=AGC_CLAUDE_AGENT_SDK_VERSION`，门禁断言声明版本等于 `apps/ai-game-creator-shell/package.json` 与 `agent-sidecar/package.json` 锁定的 `@anthropic-ai/claude-agent-sdk`。
+- 决策（平台映射从基线配置移到平台配置）：`resources/claude-agent` 由 `tauri.conf.json` 移入 `tauri.windows.conf.json` 与 `tauri.macos.conf.json`。基线配置同时服务 Linux——CI 只在那里编译壳 crate 且按设计不装 npm 依赖，而 `tauri-build` 会把 `bundle.resources` 的每个路径拷进 target、缺失即失败；留在基线等于要求一份只有 Windows/macOS 才产出的资源。`check-config.mjs` 增加「基线不得声明 `resources/**`」的守卫。
+- 决策（删掉自带的清理逻辑）：不保留 master 的 `prune_stale_codex_components`。准备步骤对 staging 单元整目录原子替换已经清掉旧布局残留，构建期另有「白名单外的文件」断言；构建脚本不再删任何人的文件。
+- 影响面：`src-tauri/build_support/{package-layout.json,package-layout.generated.rs,package_layout.rs}`、`src-tauri/build.rs`、`scripts/{prepare-bundled-resources.mjs,prepare-bundled-resources.test.mjs,check-package-layout.mjs,check-config.mjs}`、三份 tauri 配置、`src/agent/claude_code_cli.rs`、技术方案 §4.5/§4.9、排障记录。
+- 验证：`npm run agc:bundled-resources:test`（18 passed，含 sidecar 归位、跳过规则、上游缺失、版本漂移、目录被占）；`npm run agc:bundled-resources:check`、`check-config.mjs`、`cargo test --bin genarrative-ai-game-creator-shell package_layout::tests`、`cargo check --no-default-features`、`cargo fmt --check`、`check:encoding`、eslint/prettier 全部通过；Windows 真机准备步骤 staging 24 个文件（含 243MB `claude.exe`）后 `cargo check` 不再出现构建期写入。
+- 边界（未验证）：macOS 真机的 sidecar 加载与 `check-macos-bundle.mjs` 包内容门禁未在本机验证；Linux 门禁按新配置不再要求 sidecar 资源，需 CI 实跑确认转绿。
+- 关联：issue #519、master `fb130d184`、`docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md`、CI run 3083。

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

@@ -55,6 +55,8 @@
 
 Windows 下的移动壳 smoke 通过 Node 启动从当前 workspace 包解析出的 Expo/EAS CLI，不直接 `spawnSync('npm.cmd')`；保留原配置与导出断言。具体入口和警告清理边界见本地开发运维文档。
 
+AGC 的纯桌面/生产接入按模块排除测试编译，共享实现与受测入口保持可测试；拆分后同时检查普通目标和测试目标，并保留原有行为断言。命令注册与退出接线的源码检查跟随真实模块位置更新，不能因移动文件而漏检；不通过全局允许死代码或虚假调用消除告警。具体边界见开发运维文档“编译告警的保留边界与待优化项”。
+
 提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。
 
 提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。

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

@@ -9,6 +9,13 @@
 - **处理**：线上只收敛 SPA allowlist（12 条，含 `/profile`）并补 `error_page 404 /404.html`；host-only 块收进 `deploy/nginx/snippets/genarrative-host-extras.conf`，由主模板 include、由 `Genarrative-Server-Provision` 安装。退役路由不进白名单，也不需要显式 404 配置，落 `location /` 即得品牌 404（非 HTML 客户端保持纯 404）。
 - **判据/取证**：改前 `grep -c profile /etc/nginx/conf.d/genarrative.conf` 为 0；改后 `curl -s -o /dev/null -w '%{http_code}' https://www.genarrative.world/profile` 为 200（正文 sha 与 `/` 一致），`sudo nginx -T | grep -c 'editor/canvas|profile|project'` 为 1，`match3d` 计数为 0。
 - **长期口径**：任何 SPA/路由白名单改动都要同时核对**生效配置**（`sudo nginx -T`）与仓库模板；线上主站 vhost 只由模板 + `genarrative-host-extras.conf` 生成，不再手工追加路由。snippet 内的 location 不在 Pingora 路由矩阵覆盖范围，Pingora 接公网 443 前要单独确认这些 host-only 路径。
+## 2026-09-30 构建期 staging 撞上不装 npm 依赖的 Linux 门禁：AGC 壳 Rust lane 全红
+
+- **现象**：`Project CI` 的 AGC 壳 Rust 三条 lane（`npm run check:native-shells:agc-rust-shard-*`）在 `fb130d184` 之后全部失败，日志只有 `error: failed to run custom build command for genarrative-ai-game-creator-shell` 与 `thread 'main' panicked at build.rs:65:28: Claude Agent SDK 缺失；请先执行 npm ci`（run 3083 / job 17521 实测，1 分钟即失败）。
+- **原因**：Claude Agent SDK sidecar 的 staging 写在 `build.rs`（构建期 `remove_dir_all` + 从 `node_modules/@anthropic-ai/**` 复制），而这三条 lane 按设计**不装 npm 依赖**（`scripts/project-ci-workflow.test.ts` 的 `jobsWithoutNpmInstall` 显式允许它们没有 `node_modules`），构建脚本一跑就必 panic。同一批改动还把 `resources/claude-agent` 映射进**基线** `tauri.conf.json`：`tauri-build` 会把 `bundle.resources` 的每个路径拷进 target，缺失即 fail（`tauri-utils` 的 `ResourcePathNotFound`），所以即使绕开 panic，Linux 也会在资源解析处再红一次。
+- **处理（现行口径）**：随包资源一律由准备步骤在 `tauri dev|build` 之前 staging，`build.rs` 只读校验（sidecar 走声明 section `claudeAgent` + `scripts/prepare-bundled-resources.mjs`）；平台专属资源只允许出现在 `tauri.<platform>.conf.json`，基线 `tauri.conf.json` 里不得出现 `resources/**`——基线同时服务不产出客户端包的 Linux，`check-config.mjs` 已加该守卫。
+- **判据/取证**：`node --test apps/ai-game-creator-shell/scripts/prepare-bundled-resources.test.mjs`、`node apps/ai-game-creator-shell/scripts/check-config.mjs`；Linux 侧判据是三条 AGC Rust lane 转绿且构建期不再出现 `Claude Agent SDK 缺失`。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`、`apps/ai-game-creator-shell/scripts/{prepare-bundled-resources.mjs,check-config.mjs}`、`apps/ai-game-creator-shell/src-tauri/{tauri.conf.json,tauri.windows.conf.json,tauri.macos.conf.json}`、`.gitea/workflows/project-ci.yml`、CI run 3083。
 
 ## 2026-09-30 Jenkins release 渠道环境污染 AGC 构建单测
 
@@ -24,7 +31,7 @@
 - **处理（本次）**：`sanitize_error_context` 改为 `split_inclusive('\n')` 逐段处理、原样保留行终止符（CRLF 仍归一成 LF，私钥块整行吞掉的旧口径不变）。逐段脱敏因此与整段脱敏同形，Markdown 结构不再依赖 delta 的切法。
 - **仍未修**：`/` 开头的 delta 片段被判成绝对路径（上面 ②）。要修必须把「上一个字符」带进边界判定（正文增量可从 `direct_project_history` 的累计文本取，思考增量目前没有累计器），属于跨 delta 状态的取舍，本次未一并改。
 - **判据/取证**：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell direct_thread_delta`——新增 `direct_thread_delta_sanitization_preserves_line_breaks` 钉住「逐段脱敏 == 整段脱敏」，去掉 `split_inclusive` 即红；真实文本的回归用渲染侧夹具复核（修复前 table/li/h2 全 0，修复后与整段脱敏一致：1 个 table / 3 个 th / 4 个 h2）。
-- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs`、`.../agent/generation/prompt_context.rs`、`.../agent/direct_thread_wire.rs`、`apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts`、`#384`。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs`、`.../agent/generation/prompt_context.rs`、`.../agent/thread_manager/wire.rs`、`apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts`、`#384`。
 
 ## 2026-09-29 Game Agent 读工具被项目相对路径规则拦住
 
@@ -120,6 +127,23 @@
 - **leader 卡死的兜底**：闸门只有 follower 的有界等待（60s），若提权子进程真的挂死（`Start-Process -Wait` 无超时），`leader_deadline`（5 分钟）之前该 key 一直被占住，之后新调用会接管并按新 leader 执行；被接管后旧 leader 迟到的结果按令牌丢弃，不会覆盖接管者。`clear_game_creator_acl_elevation_denials` 只清「被拒绝」记忆，不清理 running。
 - **关联**：`src-tauri/src/acl_repair_gate.rs`、`src-tauri/src/config.rs`、issue #498。
 
+## 2026-09-29 随包资源的编译产物摘要不可复现，且准备步骤与应用构建共用同一输出路径
+
+- **摘要不可复现**：同一 source / feature / profile / target 连续构建的 `cocos-editor-bridge` payload 摘要不同（除 PE `TimeDateStamp` 外还有 RSDS GUID 等 22 字节差异），所以「与迁移前逐项一致」只能对**源码派生物**（JS/HTML/JSON/license/notice，逐字节比对）、**.NET publish 产物**（Unity helper 跨两次重新发布逐字节一致）和**命中工具链内部缓存的产物**（Godot 走 `buildId` 早退，不重链）成立。核对打包一致性时不要用编译产物的 sha256 判回归，改比路径集合 + 导出面（`DllMain`、`cocos_editor_bridge_bootstrap_source`）+ 源码派生物摘要。
+- **共用输出路径**：准备步骤的 `cocos-bridge-build` 用 `cargo build -p cocos-editor-bridge --features windows-injection`，而应用构建带的是 `windows-bootstrap + windows-injection`（`cocos-editor-injection` 的闭包），两个单元写同一个 `target/<triple>/<profile>/deps/cocos_editor_bridge.dll`。后构建的单元覆盖先构建的产物时，准备步骤的候选查找会取到「上一次遗留的另一个单元」，交替构建还会多一次重链。要改就从这里改：让准备步骤用独立 target 目录，或与应用的 feature 集对齐。
+- **验证方式**：`runTauriBuild`（`scripts/build-release.mjs`）+ `--bundles nsis`，再 `7z x` 解包比 `plugins/**`；准备步骤连续三次复跑要求 `resources/plugins` 的 32 个文件内容与 mtime 全不变。
+
+## 2026-09-27 随包资源的写入方按产物来源分界：源码派生直接复制，需工具链的先由准备步骤产出
+
+- **写法**：新增随包内容先判断来源——能从仓库源码复制就写进 `build_support/package-layout.json` 的 `subdirectories`（`origin: source`）；需要外部工具链或同一次 cargo 构建才能产出的，写成 `origin: prepared` / `libraryStaging` / `nativePayloads`，并在 `plugins.prepareSteps` 里声明要跑的程序、工作目录、指纹与必需产物——**不要写进构建脚本**（构建脚本自 M3 起只做只读校验，不再生成任何随包资源）。
+- **校验口径**：`origin: source` 的内容在构建期会与仓库源码逐文件比对（插件清单 + 逐文件 sha256 + 整树符号链接），手改这部分会被 `cargo build` 直接拒绝；`origin: prepared` 只查存在性（Godot 随包库额外跑 `godot_bundle::validate`），手改 prepared 产物不会被拒，要改就改准备步骤的来源或声明。
+- **准备步骤指纹**：声明了指纹的步骤（Unity）命中后不会重跑工具链，改 `plugins/**` 源码即失效；指纹戳文件（`publish/win-x64/.agc-source.sha256`）删掉只会多跑一次构建。`resources/plugins` 由准备步骤拥有，不要手工往里放文件。
+
+## 2026-09-27 AGC 随包资源的布局只能改声明文件，生成物由门禁锁死
+
+- **现象**：直接编辑 `apps/ai-game-creator-shell/src-tauri/build_support/package-layout.generated.rs`，或另写一份组件白名单，`npm run agc:typecheck`（链内含 `npm run agc:bundled-resources:check`）会立刻失败并报「随包资源声明与 Rust 常量不一致」。
+- **正确做法**：改 `build_support/package-layout.json`，运行 `npm run agc:bundled-resources:sync` 重新生成；改布局同时递增 `layoutVersion`（参与准备步骤的缓存 key）。声明里的 `codex.version` 必须与应用锁定的 `@openai/codex` 一致，门禁会对照 `apps/ai-game-creator-shell/package.json` 校验。
+- **边界（M1 完成时）**：准备步骤 `scripts/prepare-bundled-resources.mjs` 尚未接入 dev / 发布入口，`npm run agc` 仍由构建脚本 staging；构建脚本当前既写资源又做只读校验，`AGC_SKIP_RESOURCE_STAGING=1` 可只跑校验。构建脚本重建 `resources/plugins` 时会整体删除该目录，所以插件侧的准备步骤清单要等 M2 接管写入后才成立，插件目录现在只校验必需组件与符号链接。
 ## 2026-09-24 模型输出的围栏会粘在正文行里：聊天 Markdown 必须先归一化再解析
 
 - **现象**：AGC 对话里代码块解析错位——引言行被当成代码渲染（`…实现细节（game.js）：```js`），或者代码块收不住、把后面的正文一起吞进去（`… return centerOn(projection); }````）。文本本身「看起来没问题」，容易被当成渲染器坏了。
@@ -2984,9 +3008,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`、`sccache: error: Timed out waiting for server startup`，或 `sccache: caused by: Failed to send data to or receive data from server / Failed to read response header / failed to fill whole buffer`；真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
 - 原因：环境、Jenkinsfile 或 `server-rs/.cargo/config.toml` 启用了 `sccache` wrapper，但当前 agent 没有可执行的 `sccache`、PATH 中 shim 损坏，或本地 sccache server/client 通道状态损坏。Windows 本机若配置了 `SCCACHE_OSS_*`，sccache daemon 冷启动会先经 OSS/本机代理完成缓存读写检查，再监听 `127.0.0.1:4226`；代理或 OSS 链路慢时，Cargo 的 `sccache rustc -vV` 可能先超时。
-- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；本地 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` 在 Windows 下限时执行真实 wrapper 探测 `sccache rustc -vV`，成功才启用 sccache，缺少命令、daemon 启动超时或 wrapper 返回非零时立即给 Rust 子进程注入空 wrapper，回退到直接 rustc，避免损坏的 daemon 阻断启动；显式设置的非 sccache 自定义 wrapper 会被保留。Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
+- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；本地 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` 在 Windows 下限时执行真实 wrapper 探测 `sccache rustc -vV`，成功才启用 sccache，缺少命令、daemon 启动超时或 wrapper 返回非零时立即给 Rust 子进程注入空 wrapper，回退到直接 rustc，避免损坏的 daemon 阻断启动；显式设置的非 sccache 自定义 wrapper 会被保留。`npm run agc` 的 Tauri Cargo 原先直接继承启动器环境，用户级 `~/.cargo/config.toml` 的 `rustc-wrapper` 会在这里生效并复现同一故障（表现为 `failed to run rustc to learn about target-specific information`，AGC 前端与配套后端已经起来、只有 Tauri 客户端退出）；现在 `start-tauri-dev.mjs` 在启动 Tauri CLI 前调用 `scripts/dev.mjs` 的 `buildLocalRustProcessEnv`，把两个 wrapper 变量显式写进子进程环境——空环境变量同样能覆盖 Cargo 配置文件里的 wrapper，不能只依赖「本机没配 sccache」。Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
 - 验证：`rustc -Vv` 能输出版本；本地 `npm run dev` 能完成 `spacetime publish`、`api-server` `/healthz`、主站 Vite 和后台 Vite 启动；冷启动后原始 `cargo check -p api-server` 和 `cargo check -p spacetime-module` 能通过；`sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，证明原始 Cargo/Jenkins 路径仍可使用 sccache/OSS 缓存；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
-- 关联：`scripts/dev.mjs`、`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
+- 关联：`scripts/dev.mjs`、`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
 ## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
 
@@ -6090,7 +6114,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **现状（正确）**：`src/services/appUpdate.ts` 的 `installAppUpdate` 先 `await update.downloadAndInstall(...)`、成功后才清空待装更新并 `restartAppAfterUpdate()`；失败时保留待装更新，重试走同一条链路。
 - **判据**：`apps/ai-game-creator-shell/tests/appUpdate.test.ts` 新增「签名校验失败时拒绝安装、不重启进程，并保留待装更新供重试」——插件抛 `signature verification failed` 时断言 ①错误原样上抛 ②`restart_agc_app` 未被调用 ③再次安装仍会走插件调用并在成功后重启。变异验证：把 `restartAppAfterUpdate()` 挪到 `await` 之前，该用例立即以 `expected "spy" to not be called with arguments: [ 'restart_agc_app' ]` 变红。
 - **边界**：真正的验签与临时文件清理都在官方插件原生实现里，本地只能证明"客户端不把失败当成功"，真机安装闭环仍需已发布包与真实设备。
-- **顺带记一条环境陷阱（2026-09-28 已修）**：`apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/` 下曾有两个 codex 二进制——`bin/codex.exe` 是**真正被解析**的那份（0.155.1），而包根目录那份 `codex.exe` 是 0.147.0 的旧残留（tauri 的 Windows 资源映射只引用 `bin/` 等路径），检查都查不出来，却会让本地核对误判「应用跑的是 0.147.0」。根因是 `src-tauri/build.rs` 的 `stage_codex_target()` 只按布局拷贝、从不清理目录，旧布局的组件会永久留在随包资源目录里。现在加了 `prune_stale_codex_components()`：拷贝前删掉不在本轮布局、也不在 `manifest.json`/`NOTICE.md` 白名单里的文件并收掉空目录；实测重建后根目录 `codex.exe` 被清掉、六个声明组件与清单/声明保留。
+- **顺带记一条环境陷阱（2026-09-28 已修）**：`apps/ai-game-creator-shell/src-tauri/resources/codex/win-x64/` 下曾有两个 codex 二进制——`bin/codex.exe` 是**真正被解析**的那份（0.155.1），而包根目录那份 `codex.exe` 是 0.147.0 的旧残留（tauri 的 Windows 资源映射只引用 `bin/` 等路径），检查都查不出来，却会让本地核对误判「应用跑的是 0.147.0」。根因是构建脚本只按布局拷贝、从不清理目录，旧布局的组件会永久留在随包资源目录里。**现行口径（2026-09-30 起）**：随包资源改由准备步骤整目录原子替换（`scripts/prepare-bundled-resources.mjs` 的 `stageAtomically`），旧布局残留随替换消失；构建脚本只剩只读校验，遇到白名单外的文件会立即失败，所以「本机留着旧组件」最多表现为一次可读的失败，不会再静默随包。（2026-09-28 加的构建期 `prune_stale_codex_components()` 已随 M3 退役，实现不再存在。）
 
 ## 2026-09-29 Vite dev 冷启动会让 web E2E 的首个 goto 超时，别当成页面回归
 
@@ -6172,3 +6196,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **现象**：模型目录把回合路由到 `cc`，本地 `game-creator.config.json` 的 `llm.apiKey` 为空时，Claude Agent SDK 返回失败终态；界面只显示“执行通道未能建立或已断开”。
 - **根因**：Claude sidecar 只从 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 或本地 `llm.apiKey` 读取认证，没有复用已登录的 AGC 平台会话；同时失败终态解析丢弃了上游错误摘要。
 - **处理**：官方模型且未启用自定义目录时，将当前平台会话令牌仅注入 sidecar 子进程环境；保留最多 512 字符的 Claude 终态错误摘要，继续由统一诊断层脱敏，避免凭据落盘。
+## 2026-10-01 AGC 首页把 Web 预检错误与 Tauri IPC 错误合并，造成无法诊断的生成阻拦
+
+- **现象**：用户在首页点击「做游戏」后看到「Web 游戏环境预检未通过，请检查 Node/npm 或浏览器」，但同一安装包的 `--environment-check` 可能已经返回 `status=ready`；首页仍会阻止自动命名、建项和首次生成。
+- **根因**：`homeWebPreflight.ts` 原先对 `preflight_web_game_creation` 的所有异常统一抛出 `HOME_WEB_PREFLIGHT_FAILURE`，调用方 `useHomeProjectCreation.ts` 的两层 `catch` 又再次覆盖原始错误。于是宿主真实预检码、Tauri IPC 断连、命令未注册和 WebView `Failed to fetch` 都显示成 Node/npm/浏览器故障。
+- **处理**：保留预检失败关闭语义，但提取 Rust 返回的安全错误码；对无错误码的 Tauri 调用故障显示独立 IPC 提示，并仅对这类瞬态调用失败重试一次。首页调用方必须透传该安全提示，不能重新覆盖为通用文案。
+- **验证**：`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx` 覆盖 ready、具体宿主错误码、IPC 失败、无错误码 blocked 和 planning 绕过；同一 Windows 安装包 CLI 实测 Node `v22.22.2`、npm `10.9.7`、Edge desktop/mobile PNG 均通过。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx`、`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`。

docs/technical/【技术方案】AGC随包资源staging归位-2026-09-26.md

@@ -0,0 +1,225 @@
+# AGC 随包资源 staging 归位技术方案
+
+状态：待评审（方案草案，评审通过前不进入实现）
+日期：2026-09-26
+范围：AGC 客户端（`apps/ai-game-creator-shell`）随包资源的生成、校验与打包链路
+关联：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`
+
+## 1. 一句话目标
+
+把「随包资源」从 build script 的**产物**改回它的**输入**：由准备步骤在 `tauri dev|build` 之前一次性 staging，`build.rs` 退化为校验者，构建期不再向 `src-tauri/resources/**` 写任何文件。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. `build.rs` 的输入集合里不再包含任何「本次构建会写」的文件，`cargo` 在源码不变时稳定 fresh。
+2. Tauri dev 的文件监听不再因为 staging 变更重启 `cargo run`（macOS 与 Windows 一致，不依赖 `.taurignore` 兜）。
+3. staging 与上游版本的绑定可验证：版本、平台、逐文件摘要由校验器 fail closed 检出，不会静默发旧二进制。
+4. 打包产物内容与当前口径一致（三份 tauri 配置的 `resources` 映射与包内资源门禁不变）。
+5. 删除症状层补丁（整目录重建的规避、为绕开自触发而加的 `.taurignore` staging 条目）。`prune_staging`、`STAGED_*` 一类命名只出现在未合入的症状层补丁里，主线从未有过，不需要清理。
+
+### 2.2 非目标
+
+1. 不改发布渠道、版本号机制、签名与上传流程。
+2. 不改运行时资源解析顺序与完整性校验语义（`codex_cli.rs`、`plugin_host.rs`、`environment_check.rs`、`editor_adapters.rs` 保持行为）。
+3. 不统一 `server-rs` 与 `src-tauri` 两个 workspace，不改 target 布局。
+4. 不为 Linux 增加客户端产物（Linux 上五条 staging 全为 no-op，见 §3.6）。
+5. 不改 Windows/macOS 之外的平台支持面。
+
+## 3. 现状与证据
+
+### 3.1 build script 目前负责五条 staging
+
+`apps/ai-game-creator-shell/src-tauri/build.rs` 的 `main()` 前段依次执行（`build.rs:225-229`）：
+
+| # | 步骤 | 动作类型 | 平台门槛 | 目标路径 |
+|---|---|---|---|---|
+| 1 | `stage_bundled_codex_cli` | 纯复制（内容+权限比对） | Windows / macOS | `resources/codex/**` |
+| 2 | `prepare_unity_editor_helper` | **外部工具链**（`powershell -File build.ps1`，需 .NET 10 SDK + VS C++ x64） | Windows + unity feature | `resources/plugins/agc-unity-editor/**` |
+| 3 | `prepare_godot_editor_extension` | **外部工具链**（`powershell -File build.ps1`，需 CMake ≥ 3.25 + VS17 2022 + Python 3） | Windows + godot feature | `resources/plugins/agc-godot-editor/native/gdextension/**` |
+| 4 | `stage_plugin_workspace` | 复制 + 清残留 | Windows / macOS | `resources/plugins/**` |
+| 5 | `stage_cocos_editor_payload` | 复制（同一 cargo 构建产出的 cdylib） | Windows | `resources/plugins/agc-cocos-editor/native/payload/**` |
+
+（Prompt Bundle 生成代码写 `OUT_DIR`，属正确形态；Node 运行时已由 `scripts/stage-node-runtime.mjs` 在发布前一次性 staging，是本次改造的既有先例。）
+
+### 3.2 这些写入为什么会让 build script 永远失效
+
+`tauri-build` 会对 `bundle.resources` 里的**每个文件**发 `cargo:rerun-if-changed`，并把它拷进 target（`tauri-build-2.6.3/src/lib.rs:88-93`）。我们的三份 tauri 配置把 `resources/codex/**` 与 `resources/plugins` 列进了 `bundle.resources`（`tauri.windows.conf.json:7-15`、`tauri.macos.conf.json:8-22`；基线配置故意不含，见 `check-config.mjs:1377-1383`）。
+
+于是「构建期写的文件」与「build script 声明的输入」是同一批：
+
+```text
+staging 写 resources/**  →  tauri-build 把同一批文件登记成输入  →  mtime 变化
+        ↑                                                              ↓
+        └──────────────  cargo 判 build script stale，重跑脚本  ←──────┘
+```
+
+判据是「输入文件 mtime 比 build script 的输出新」，与目录位置无关：把 staging 搬到 `target/` 也躲不开——登记的是配置里写的那些路径，只要构建期写它们，照样自触发。所以关键不是「产物放哪」，而是「**构建期有没有人写这些被登记的文件**」。
+
+### 3.3 已发生的故障
+
+| 症状 | 范围 | 观察证据 |
+|---|---|---|
+| 每次构建都重编主 crate（41–87 秒，从不变 fresh） | Windows + macOS（Linux 上五条 staging 全为 no-op，不受影响） | `CARGO_LOG=cargo::core::compiler::fingerprint=info cargo build --no-default-features` 打印 `stale: changed "resources/codex/mac-native/darwin-arm64/NOTICE.md"`，且 `.fingerprint/**/run-build-script-build-script-build.json` 的 `RerunIfChanged.paths` 含 staging 目标路径 |
+| `npm run agc` 反复 `Rebuilding application`，客户端起不来 | 仅 macOS | dev 日志一轮 28 次以上不收敛；原因是被重写的 `resources/codex/mac-native/**` 落在监听范围内且未被忽略 |
+| `remove_dir_all` 抛 `DirectoryNotEmpty`，整次启动中断 | 并发重建时 | `清理 macOS Codex staging 失败` |
+
+### 3.4 三轮症状层修复都没有收口
+
+| commit | 日期 | 修的是什么 | 结果 |
+|---|---|---|---|
+| `299877b19` | 2026-09-11 | 插件资源改成「内容变化才落盘」+ 引入 `.taurignore` | 只覆盖插件路径，且挡不住 cargo stale |
+| `710d6dddf` | 2026-09-23（PR #487） | Windows 上「权限一致就不写元数据」 | 只减少一类写入，未解决整目录重建 |
+| 本次未合入的 B 改动 | 2026-09-26 | 全部写入改幂等 + 按布局清残留 + 补 `.taurignore` | 实测可行（第二次 `cargo build` 0.25 秒 fresh），但规则靠人守：新增一条写 `resources/**` 的步骤漏改即回退（godot/cocos/plugin.json 正是三个漏点） |
+
+结论：**只要 build script 继续写这些受跟踪路径，就必须持续为每一处写入维护「无改动不写」，成本随写入点增长**；这是结构问题，不是疏漏问题。
+
+## 4. 方案设计
+
+### 4.1 原则
+
+build script 只写 `OUT_DIR`/`target`；随包资源是它的输入。凡需要「由本仓库生成、再随包分发」的内容，都由 `tauri dev|build` 之前的**准备步骤**生成，build script 只校验。
+
+### 4.2 目标形态
+
+```text
+准备步骤（新，唯一写入方）                  build.rs（退化为校验者）
+  fetch/校验上游 → 生成到 staging 目录       只读 resources/** → 校验 manifest/hash/版本/平台
+  → 原子替换到 resources/**                  → 不写任何随包资源
+  → 写 manifest.json（schema 化）
+        ↑                                          ↑
+  dev: start-tauri-dev 内、spawn tauri 之前      release: build-release/build-macos-ci 内
+```
+
+### 4.3 准备步骤的合同（必须成立的行为）
+
+1. **调用时机**：`tauri dev` / `tauri build` 之前完成；任何入口都不得依赖 build script 兜底生成。
+2. **缓存与幂等**：以「上游 lockfile `resolved` + `integrity` + 布局版本 + 目标三元」为 key；命中且 manifest 校验通过的 staging 目录不重写任何文件（避免把「产物」变成「每次构建都变」的新源头）。
+3. **原子性**：写入 staging 临时目录后 rename 替换；不得出现半成品目录（杜绝并发下的 `DirectoryNotEmpty`）。
+4. **所有权**：只允许替换由本工具创建并带 manifest 的目录；遇到非本工具目录、符号链接、越界路径必须 fail closed（沿用 `stage-node-runtime.mjs` 与 `prepare-macos-codex.mjs` 既有判定）。
+5. **清理语义**：准备步骤负责删除本轮布局不再产出的残留（否则旧组件会继续被打包），删除范围限于自己的 staging 目录，不得触碰受版本控制的文件（例如 `resources/codex/win-x64/NOTICE.md`）。
+6. **失败语义**：上游缺失、integrity 不匹配、目标平台不支持、外部工具链缺失 → 立即失败并给出可执行提示；不允许「跳过生成、继续打包」。
+7. **可观测**：输出一行汇总（命中缓存 / 重新生成 / 跳过原因），供本地与 CI 排障。
+8. **并发**：不做并发支持（无实际场景）。同一 staging 目录的并发调用未加锁，会以可读错误失败并保留已生成的 staging 目录；需要并发时由调用方外部串行化。
+9. **实际构建目标**：资源准备与 Cargo 必须使用同一目标和 feature 集。正式发布使用发布目标；无显式 `--target` 的 `--no-bundle` 使用宿主平台，Windows/macOS 仍须准备资源，Linux 编译 smoke 不准备桌面平台专属资源。feature 从最终 Tauri/Cargo 参数解析，不能被开发环境变量单独覆盖；dev 启动器转交的应用参数不参与构建参数解析。
+
+### 4.4 build.rs 退化后的职责
+
+保留：
+
+1. 读取 `TARGET` 并写 `cargo:rustc-env=AGC_BUILD_TARGET`（运行时定位随包目录依赖它）。
+2. 校验 `resources/**` 与清单一致：平台目录存在、manifest schema/平台/版本、逐文件 sha256、必需组件齐全（缺一即 fail closed）。
+3. 声明**真实输入**：上游源文件、布局表、受版本控制资源（含 macOS 声明文件）的 `rerun-if-changed`；不得声明任何由本脚本或准备步骤生成的文件。
+4. `tauri_build::build()` 与既有 Prompt Bundle、能力与配置校验。
+
+删除：
+
+1. 五条 staging 的写入逻辑（M2 删除了 codex 与插件工作区的写入分支，仍是构建期产物的三处留在 M3）、针对大目录的整目录重建。
+2. 为绕开自触发而加的 `.taurignore` staging 条目与说明（准备步骤在监听启动前完成，不再需要）。
+
+### 4.5 资源清单（谁生成、谁消费）
+
+| 资源 | 生成方式 | 运行时消费方 | dev 是否需要 |
+|---|---|---|---|
+| `resources/codex/**` | 纯复制（上游平台包 `vendor/<triple>`） | `codex_cli.rs`（内置 sidecar 优先，其次 npm 目录、PATH） | macOS dev 只接受真 `.app` 的 `Contents/Resources`，非 `.app` 场景走 npm/PATH 回退；Windows dev 从 exe 同级读取 |
+| `resources/plugins/**` | 复制 + 三个编辑器分支的产物 | `plugin_host.rs`（`AGC_PLUGIN_WORKSPACE` → `resource_dir/plugins` → dev 回退仓库 `plugins/`）、`editor_adapters.rs` | dev 有仓库回退，但 cocos/unity/godot payload 仍以随包路径为准 |
+| `resources/plugins/agc-unity-editor/**`、`agc-godot-editor/native/gdextension/**` | 外部工具链（Windows 专属） | `editor_adapters.rs` 候选链 | 仅 Windows |
+| `resources/node-runtime/**` | 已有：`stage-node-runtime.mjs` | `environment_check.rs`（`agc-node-runtime.v1` 全量 sha256） | 发布与需要随包 Node 的 dev |
+| `resources/claude-agent/**` | 纯复制（应用 `agent-sidecar/src/index.mjs` + 上游 `@anthropic-ai/claude-agent-sdk`、`@anthropic-ai/claude-agent-sdk-<platform>`） | `claude_code_cli.rs`（`exe_dir/claude-agent/index.mjs`、macOS `.app` 的 `Contents/Resources/claude-agent`） | Windows / macOS dev：准备步骤按声明 staging |
+| `design-agent`、`vendor/*` 许可 | 受版本控制 | `design_tools.rs` 等 | 无需 staging |
+
+### 4.6 入口接线
+
+| 入口 | 位置 | 现状 | 改造后 |
+|---|---|---|---|
+| AGC dev | `start-tauri-dev.mjs`（`runTauriDev` → 预检 → 前端 → `spawnCli`，准备点在前端就绪之后、`spawnCli` 之前） | 无准备步骤，依赖 build script | 在 `spawnCli` 之前调用准备步骤（命中缓存时秒退） |
+| Windows 发布 | `build-release.mjs`（`runTauriBuild`，现有 `stageRuntime(target)` 紧邻 spawn tauri） | 只有 Node 运行时走准备步骤 | 同一挂点串上全部 staging |
+| macOS 发布 | `build-macos-ci.mjs`（复用 `runTauriBuild`）→ `check-macos-bundle.mjs` | 同上 | 同上 |
+| 本机 Rust 门禁 | `ai-game-creator-shell:check:rust:shell`（Windows 上 `cargo test --no-run` 会跑 build script） | 依赖 build script 生成资源 | 校验器在该场景必须能只读通过；需要真实资源的用例沿用既有 fixture，不得依赖本机 staging 产物 |
+| `tauri build --no-bundle` | `build-release.mjs` 的 no-bundle 分支（当前跳过 `stageRuntime`） | 不生成 Node 运行时 | 改为：`--no-bundle` 也执行 staging（app 构建本身需要随包资源），只跳过总号发布；校验器在资源缺失时仍然 fail closed |
+| CI（Linux） | `.gitea/workflows/project-ci.yml` 的 AGC 分组 | 五条 staging 全为 no-op | 不需要新增准备步骤；分片与 smoke 命令不变 |
+
+### 4.7 与现有机制的关系
+
+1. **已有先例**：`stage-node-runtime.mjs` 已实现 schema 常量、目标平台失败关闭、staging 目录 + rename 原子替换、拒绝覆盖非本工具目录；`prepare-macos-codex.mjs` 已实现 lockfile `integrity` 驱动的下载、缓存与原子替换。准备步骤应复用这两套范式而不是另起一套。
+2. **打包侧不变**：三份 tauri 配置的 `resources` 映射与 `check-config.mjs:1356-1424` 的逐字断言保持不变；`check-macos-bundle.mjs` 对包内 `coding-agent/mac-native`、`game-runtime/node`、`plugins/agc-cocos-editor` 的存在性、架构与 sha256 断言继续作为发布后门禁。
+3. **fail closed 已有兜底**：`tauri-build` 在资源缺失时以 `ResourcePathNotFound` 直接失败；校验器应比它更早、更明确地报错。
+
+### 4.8 单一声明与实现形态（M1 定案）
+
+准备步骤与构建期校验共用一份人工声明：`apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`。
+
+| 侧 | 读取方式 | 用途 |
+| --- | --- | --- |
+| Node 准备步骤（`scripts/prepare-bundled-resources.mjs`） | 直接读声明 JSON | 组件白名单、Codex 上游候选路径、插件随包子目录与跳过规则、平台与 feature 门槛、缓存 key 组成、manifest 序列化 |
+| Rust 构建期校验与运行期布局 | 读声明生成的 `build_support/package-layout.generated.rs`（编译期常量） | 只读校验既有产物、运行期定位随包组件（`codex_bundle.rs` 接口不变） |
+| 声明门禁 | `scripts/check-package-layout.mjs`（`npm run agc:bundled-resources:check`，已进 `agc:typecheck` 链） | 校验生成物与声明一致，并检查声明自身不变量：目标唯一、`executable` 属于白名单、每个目标恰有一条第三方声明来源、`codex.version` 与应用锁定的 `@openai/codex` 一致 |
+
+形态选择**混合**：生成归 Node（复用 `stage-node-runtime.mjs` / `prepare-macos-codex.mjs` 的下载、`integrity`、临时目录 + rename 原子替换范式），声明与校验归 Rust（复用 `codex_bundle.rs` / `godot_bundle.rs` 的布局与摘要校验，运行期模块不改公开接口）。理由：Rust 侧没有下载与 lockfile 解析能力（`[build-dependencies]` 无 HTTP 客户端），Node 侧没有 staging 能力；任选单一语言都要迁移另一侧既有资产。Rust 侧刻意不解析 JSON：声明经生成器变成编译期常量，避免运行期解析与生命周期妥协，也让 `&'static` 布局表与现有调用点保持不变。
+
+构建脚本自 M3 起只做只读校验（写入分支与 `AGC_SKIP_RESOURCE_STAGING` 开关一并删除），`cargo build/check` 本身就是对既有产物的校验。
+
+### 4.9 M2/M3 实况：构建期写入边界
+
+「谁写随包资源」按产物来源分界，声明里的 `origin` 字段表达同一口径：
+
+| 来源 | 例子 | 谁写 | 时机 |
+| --- | --- | --- | --- |
+| `source`：声明 + 仓库源码即可生成 | `resources/codex/**`、插件工作区的 `src`/`panels`/`skills`/`native/payload` | 准备步骤（Node） | `tauri dev` / `tauri build` 之前 |
+| `prepared` / `libraryStaging` / `nativePayloads`：需要外部工具链或同一次 cargo 构建 | Unity `dotnet/publish/win-x64`、Godot `native/gdextension`、Cocos `native/payload` | 准备步骤：先按声明运行 `powershell.exe -File build.ps1` 或 `cargo build -p … --target …`，再复制产物 | 同上 |
+
+M2 之后构建脚本只做只读校验；M3 之后它也不再生成任何随包资源（连编辑器分支产物一并交给准备步骤），并在校验阶段确认源码派生内容逐文件一致、已准备产物在位、Godot 随包库通过既有深度校验。因此源码不变时 `cargo` 稳定 fresh（macOS 实测连续三次 `cargo build --no-default-features` 为 0.69 / 0.22 / 0.22 秒），`resources/plugins` 也不再需要在 `.taurignore` 里忽略（两份 staging 条目已删除）。
+
+准备步骤的 Windows 侧命令执行（powershell / cargo）只在本机无法验证，验收清单见 M3 里程碑规范。
+
+**2026-09-30（合并 master）**：新增随包组件 Claude Agent SDK sidecar（cc 执行模式）沿用同一口径——声明 `claudeAgent` section（上游 SDK 包与平台原生运行时包的目标表、复制跳过规则、锁定版本），staging 由准备步骤整目录原子替换，`build.rs` 只读校验（入口与仓库源码一致、SDK 与原生运行时版本等于声明、白名单外文件）。它的 `resources/claude-agent` 映射放在 `tauri.windows.conf.json` 与 `tauri.macos.conf.json`，**不得**回到基线 `tauri.conf.json`：基线同时服务 Linux（CI 只在那里编译壳 crate 且不装 npm 依赖），`tauri-build` 会因资源缺失直接失败。
+
+## 5. 兼容与迁移
+
+1. **产物兼容**：包内路径、manifest schema（`genarrative-codex-sidecar.v2`、`agc-node-runtime.v1`、插件 `plugin.json`）不变，安装包内容逐项对得上；升级路径不需要用户侧动作。
+2. **过渡期（已完成）**：M1 让准备步骤与构建脚本产物并存并逐文件比对一致，M2 移除了构建脚本里 codex 与插件工作区的写入分支；剩余在构建期写入的三处（Unity publish 目录、Godot gdextension、Cocos payload）随 M3 归位。删除与新增不跨里程碑混在一起。
+3. **本机残留**：M2 已删除 codex 与插件工作区的写入逻辑与整目录重建；`.taurignore` 的 staging 条目及其原因说明保留到 M3——Windows 上仍有三处构建期写入落在 `resources/plugins/**`，去掉忽略会重新引入监听自触发。`resources/**` 仍保持 gitignored。
+4. **回滚**：准备步骤与校验器保持独立可关闭（例如校验器只读、不写），回滚只需恢复 build script 的写入分支，不涉及数据迁移。
+
+## 6. 验收标准与证据
+
+| 项 | 判据 |
+|---|---|
+| 构建新鲜度 | 源码不变时连续两次 `cargo build --no-default-features` 第二次为秒级 `Finished`；IDE 的 `cargo check --all-targets` 同样不重复构建 |
+| 无自触发 | `cargo:rerun-if-changed` 输出与 fingerprint 记录里不出现任何 `src-tauri/resources/**` 路径 |
+| dev 可用 | macOS/Windows `npm run agc` 在准备步骤后一次成功：`Rebuilding application` 为 0 次、`Running DevCommand` 为 1 次，客户端与 Runner 进程稳定存活 |
+| 包内容 | `check-macos-bundle.mjs` 全绿；Windows 安装包内 `coding-agent`、`plugins`、`game-runtime/node` 与改造前逐项一致 |
+| 失败关闭 | 上游缺失 / integrity 不匹配 / 清单缺组件 / 目标平台不支持 四类场景各自返回明确错误且不产出包 |
+| 幂等 | 准备步骤连续执行两次，staging 目录内容与 mtime 不变（不改动受跟踪输入） |
+| 门禁 | `check-config.mjs`、`check:encoding`、`check:doc-index`、`git diff --check`、AGC 相关 vitest 与 Rust 测试全绿 |
+
+未验证项必须在交付记录中标注（例如 Windows 真机行为、真实上游包下载在受限网络下的表现）。
+
+## 7. 风险与回滚
+
+| 风险 | 影响 | 措施 |
+|---|---|---|
+| 忘记调用准备步骤（dev 或某个发布入口） | 资源缺失，打包或启动失败 | 校验器 fail closed + 入口测试断言「spawn tauri 前已调用准备步骤」 |
+| staging 缓存 key 不覆盖上游变化 | 静默发旧二进制 | key 含 lockfile `resolved`+`integrity`+布局版本+三元；manifest 校验作为第二道闸 |
+| 外部工具链步骤（unity/godot）搬出后顺序变化 | Windows 打包失败 | 准备步骤显式声明工具链前置检查；先在 Windows 上单独验证再合入 |
+| 并发调用同一 staging 目录 | 失败可读、不丢 staging | 不加锁也不支持并发：替换失败给出可执行提示并保留 staging 目录，需要并发时外部串行化 |
+| 迁移期两套生成并存 | 结果漂移 | 并存阶段以「准备步骤生成结果 == build script 生成结果」逐文件比对作为过渡判据 |
+
+回滚点：准备步骤上线但校验器未启用前，任一步失败都可直接恢复 build script 写入分支，无需数据迁移。
+
+## 8. 里程碑拆分（建议）
+
+| 里程碑 | 交付 | 停止条件 |
+|---|---|---|
+| M1 校验器化 | 单一声明 + 生成门禁、`build.rs` 只读校验路径、准备步骤脚本（codex + plugins 两条纯复制路径）、缓存与原子替换 | 校验器在既有 staging 产物上全绿且不改变现有构建行为（写入分支与 `AGC_SKIP_RESOURCE_STAGING` 开关在 M3 一并删除） |
+| M2 入口接线 | dev 与两个发布入口调用准备步骤；codex/plugins 的写入分支从 build.rs 移除；`cargo` 新鲜度与 dev 不再重建达标 | 已交付（2026-09-27）：macOS 侧 §6 前三行达标（连续 `cargo build` 0.69 / 0.22 / 0.22 秒 fresh；`tauri dev` 全程 `Rebuilding application` 0 次、`Running DevCommand` 1 次）；Windows 新鲜度待 M3 归位三处构建期产物后复验 |
+| M3 外部工具链归位与清理 | unity/godot/cocos 的产物生成移出 build.rs；删除 `.taurignore` 的 staging 条目与相关注释；文档收口 | 已实现（2026-09-27）：三处产物改由准备步骤按声明运行 powershell/cargo 后复制，build.rs 只剩只读校验，两份 `.taurignore` 已删除；已通过第五轮 Windows 真机评审：构建脚本不再写资源（90 个文件 0 变化）、第二次 `cargo build` 1.13s fresh、三分支产物齐备、幂等与 fail-closed 通过；仍待验收的是「安装包内产物路径/sha256 比对」与「三个编辑器分支客户端加载」 |
+
+里程碑规范与单里程碑实现计划按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../【协作规范】规范驱动开发工作流-2026-09-12.md) 另立 `docs/project-memory/plans/` 下的临时文件；本方案是它们的主规范来源。
+
+## 9. 未决问题
+
+1. ~~准备步骤用 Rust bin 还是 Node 脚本？~~ **已定（2026-09-27）：混合**——生成归 Node、声明与校验归 Rust，布局与白名单收敛为单一声明文件。机制、门禁与验证入口见 §4.8。
+2. unity/godot 的外部工具链步骤是否值得搬出 build script（它们本身是构建动作，搬出后需要显式前置顺序）——需在 Windows 上确认收益与风险。
+3. `resources/**` 是否需要继续保留在 crate 内（`bundle.resources` 相对路径解析要求），还是改用生成式配置指向 `target/` 下的 staging：前者改动小、后者更彻底，需与 Tauri 的资源解析规则一起评估。

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

@@ -116,6 +116,7 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema
 - 对客户端刚创建且内容仍匹配可信模板的 Web 脚手架，在正式生成前由宿主执行受控依赖准备和真实 Vite 构建。依赖安装禁用生命周期脚本；不自动安装或覆盖导入/用户修改过的工程。
 - 准备凭证的 `ready` 只证明初次环境准备成功，不代表当前游戏已验收，后续正常修改不得因此重新安装。`preparing` 中断恢复必须证明原拥有者已结束且其执行子树已回收；身份或归属未知时保留阻断，不重复执行。
 - 输出明确区分“Node/npm 构建能力通过”与“本项目 Vite 构建通过”；任何一步失败保留可行动错误，不降级为预检成功。
+- 首页必须区分宿主预检阻塞与 Tauri IPC 调用失败：Rust 返回的安全错误码可透传到状态栏；无错误码的瞬态 IPC 失败只允许一次有界重试后显示独立的客户端连接故障，不得统一伪装成 Node/npm 或浏览器故障。预检仍保持失败关闭，不得因为展示错误变得可绕过。
 - 安装载荷提供相同的安全预检 CLI，验证无系统 Node 的独立运行、缺包/篡改失败关闭。NSIS 解包载荷 smoke 与真实安装器注册流程分开报告，不覆盖当前用户的既有安装。
 
 ### 跑酷固定基线
@@ -1787,6 +1788,9 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 清单补充可选 `projectName` 与 `pendingFiles`：名称来自本地 manifest；`pendingFiles` 是本轮失败、延后、并发变动与非策略排除的跳过文件数量。`0` 表示扫描范围已同步；大文件等被跳过不能标成完整。旧清单字段缺失表示完整性未知，维持可读取兼容，不反写旧清单。
 - 项目名称或完整性发生变化时，即使文件内容没有差异也要提交新清单；本机索引记录上次已提交的这两个字段。实际客户端下一次正常同步可补齐历史清单元数据；后台只读访问不迁移旧清单。缺失 `pendingFiles` 不能默认成 0，临时跳过原因消失后允许无文件上传的 `partial → ready` 转换。
 - 后台增加“项目工程”入口，仅 owner 及拥有 `project-snapshots` 页签权限的管理员可访问。`GET /admin/api/project-snapshots?cursor=&limit=20` 读取私有 OSS 清单并返回 `{items,nextCursor}`；单页最多 100 个，游标由服务端校验，目录与清单读取有界。条目为 `{userId,projectId,projectName,syncRevision,syncedAtMs,fileCount,totalBytes,status}`，状态为 `ready / partial / unverified`，名称缺失时显示 projectId。
+- 后台“按同步时间排序”是主动读取当前渠道全量项目的临时展示操作：从首游标开始，以每次 100 条沿 `nextCursor` 顺序读取，只有全部读取成功后才切换为 `syncedAtMs` 降序、`userId` 字符串升序、`projectId` 字符串升序；不能只排序当前远端页。成功后回到第一页，20/50/100 条分页及上一页/下一页复用浏览器中的完整列表，不再请求远端；“刷新”重新读取全量并回到第一页，“恢复默认顺序”在远端目录第一页读取成功后统一切换列表、排序模式和分页游标；读取失败保留原排序集合、当前页码和本地分页，支持重试。切换渠道、令牌或离开页面销毁临时结果并取消在途读取，不跨会话持久化。
+- 全量读取展示已取得项目数并允许取消；单次最多 200 个远端页、10,000 个唯一项目、60 秒，重复游标或超限明确报错。读取失败、鉴权失败、超时或取消保留原来的列表和分页，不能发布部分数据作为排序完成的结果。并发同步期间重复项目按用户/项目身份合并，保留同步时间较新的一份，相同时间取后读到的清单；该列表是遍历期间读到的数据集合，不承诺 OSS 全局事务快照，后续同步由管理员刷新读取。仍由原接口实施渠道和页签鉴权，不新增 OSS 索引、数据库表、API 参数或客户端迁移。
+- 排序验收覆盖远端多页与空中间页、时间相同的身份排序、本地翻页/页容量、刷新与恢复默认、失败/取消/超时/限额/重复游标、并发重复身份，以及渠道/令牌切换和卸载后的旧响应隔离；证据入口为 `apps/admin-web/src/pages/AdminProjectSnapshotsPage.test.tsx`、后台类型检查和编码/文档索引检查。
 - `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 只读取该用户/项目的固定清单与其引用对象，返回 `application/zip` 附件。ZIP 中路径直接使用原始相对路径，不包含 userId、摘要目录或 OSS 前缀；名称使用经过安全处理的项目名和 revision。下载固定本次读到的清单，远端并发回收导致对象缺失则整体失败，不能静默遗漏。
 - `partial` 快照下载返回 409；`unverified` 历史快照可导出已同步文件，列表明确显示“完整性未知”，动作称“下载已存文件”。`ready` 才显示“下载完整工程”。ZIP 构建核验每一文件的长度与 fnv1a64 摘要，拒绝穿越、绝对路径、重复/大小写冲突路径、非法项目身份；缺失或损坏整体失败，不返回成功的残缺 ZIP。
 - ZIP 使用服务端临时文件并限制并发，不将 2 GiB 工程整体驻留内存；成功、失败、客户端取消均清理临时文件。单文件、总量、文件数沿用上传上限，超限明确拒绝。零字节工程文件可以上传和导出。OSS 凭据与签名不下发浏览器，列表失败保留错误而非伪造空列表。

docs/technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md

@@ -4,10 +4,10 @@
 
 本方案的**卡片表现层**（折叠 / 展开、标题与摘要文案、耗时与时间显示、脱敏、无障碍、样式）仍然是有效契约；**数据来源层**已被 `docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md` 取代，边界改为：
 
-- DirectProject 聊天框的工具卡片由**运行态事件 + 项目对话历史**在前端投影生成（`features/project-workspace/directThreadItemProjection.ts`），不再读取 `tool-calls.jsonl`；`read_direct_tool_calls` 命令与 Rust 侧 `read_direct_tool_calls_at` 回读函数已删除，该文件现在只有 DirectRuntime 的写入。
-- 报文中不再有 `toolCalls` 增量字段与 `GameCreatorDirectTurnUpdateEvent` 这条实时链路：卡片形状由前端从脱敏原始条目生成，事件里只有 `item.started` / `item.completed` / `item.delta`（线上模型见 `agent/direct_thread_wire.rs`，由 ts-rs 导出绑定）。
+- DirectProject 聊天框的工具卡片由**运行态事件 + 项目对话历史**在前端投影生成（`src/view/project-development/chat/conversation/directThreadItemProjection.ts`）；工具条目在读取期由 `agent/thread_manager/wire.rs` 统一脱敏与截断，不再有独立的工具调用账本或回读命令。
+- 报文中不再有 `toolCalls` 增量字段与 `GameCreatorDirectTurnUpdateEvent` 这条实时链路：卡片形状由前端从脱敏原始条目生成，事件里只有 `item.started` / `item.completed` / `item.delta`（线上模型见 `agent/thread_manager/wire.rs`，由 ts-rs 导出绑定）。
 - 卡片身份只有一个 `itemId`（工具条目在 `project.jsonl` 里带的两个 id 已在 Rust 边界归一），前端卡片形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`：聊天卡片不再有回合身份。
-- 下面「### 1. 工具调用条目」「### 2. 实时事件」「### 3. 回读命令」三节描述的是 DirectRuntime 自己的账本（`tool-calls.jsonl` 的写入形状与脱敏规则仍然有效，DirectRuntime 保留），**不再是 DirectProject 聊天框的读路径**；「### 4. 前端合并与渲染」中按 `turnId` 归并、按 `turn-stream.jsonl` 的 `seq` 交替的规则已作废，改为按事件顺序 + 历史文件顺序投影。
+- DirectRuntime 曾经的 `tool-calls.jsonl` / `turn-stream.jsonl` 账本、写入器与进度事件已整体删除（2026-09-30，issue #553）；本方案原先描述这些落盘与事件契约的「工具调用条目」「实时事件」「回读命令」三节一并移除，改为按事件顺序 + 历史文件顺序投影。
 
 ## 一句话交付
 
@@ -44,60 +44,24 @@
 - 同一用户消息从本地发送转为正式条目时必须保留原发送时间，不能因去重丢掉该时间而改用启动应答后的观测时间。回合明确结束时，即使当前 live 集合为空，也应将终态边界关联到已知的本轮用户条目；不得仅按“历史最后一项”猜测或向无关旧回合补时间。
 - 生命周期事件可携带已有用户条目的 `userItemId`，用于把时间边界精确关联到同一条历史消息（不产生新的回合 ID 或持久化字段）。恢复时该关联随 Thread Manager 原事件重放；带旧用户身份的终态不能收口另一条新请求。缺少身份的旧事件不据时间猜测归属。
 
-## 背景与现状（已核实）
+## 背景与现状（2026-09-14 立项时点）
+
+> 以下记录立项时点的现状，用来解释这次改造的动机；其中「工具调用不留痕」「没有结构化工具调用」等结论都已被后续实现与 2026-09-16 修订取代，**当前状态以文首修订与 ADR 为准**。
 
 - 数据来源：Codex app-server 会推 `item/started` / `item/completed`，item 里带完整信息（`commandExecution.command`、`fileChange.changes[].path` 等）。
 - 现状投影：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs` 的 `direct_codex_item_intermediate_text()`（约 791 行）把 item **压成一行中文文本**（`正在执行命令：xxx` / `正在写入文件：xxx`），经 `DirectCodexTurnObservation::IntermediateText` 下发。
-- 前端事件：`GameCreatorDirectTurnUpdateEvent`（`src/app/types.ts:1090`）只有 `projectPath / turnId / sequence / status / activity / accumulatedText / updatedAt`，**没有结构化工具调用**。
+- 前端事件：`GameCreatorDirectTurnUpdateEvent`（该事件已随 issue #553 删除）只有 `projectPath / turnId / sequence / status / activity / accumulatedText / updatedAt`，**没有结构化工具调用**。
 - 历史持久化：`.agent/conversations/project.jsonl` 现在只写 message 条目（实测 61 条全是 message），工具调用不留痕。
 - 历史回读：`read_direct_project_chat_history_at()`（`direct_project_history.rs:575`）只把 `role ∈ {user, assistant}` 且有文本的条目投影成 `LocalConversationMessageRecord`，**形状上装不下工具调用**。
 - 结论：要做成卡片必须同时改「采集 → 传输 → 持久化 → 回读 → 渲染」五段，纯前端做不出来。
 
 ## 契约（实现必须照此，不得自行改形状）
 
-### 1. 工具调用条目（采集与持久化形状）
+工具卡片的两处数据来源是 `.agent/conversations/project.jsonl` 的原始条目与 Thread Manager 的运行态事件；Rust 出口只做挑字段、脱敏、截断，卡片形状、可见性、合并与计时全部由前端投影完成。
 
-新增独立历史文件：`<projectRoot>/.agent/conversations/tool-calls.jsonl`，一行一条，行信封与既有历史一致：
+### 前端合并与渲染（回合唯一归属，连续工具成块）
 
-```json
-{ "type": "tool_call_item", "payload": { "schemaVersion": "agc-tool-call.v1", "id": "...", "turnId": "...", "kind": "command|file_change|mcp_tool|web_search|context_compaction|other", "title": "执行命令", "summary": "npm run build", "status": "running|completed|failed", "detail": { "command": "...", "output": "...", "changes": [{ "path": "game/src/x.ts", "kind": "add|update|delete" }] }, "startedAt": 0, "updatedAt": 0 } }
-```
-
-- `id`：Codex item 的 id；同一 item 的 `started` 与 `completed` 必须落成**同一条**（按 id 幂等 upsert，不允许写两行）。
-- **状态单调**：同一 `id` 的每条快照按 `updatedAt` 合并落盘——`updatedAt` 更旧的快照不得覆盖更新的 `status` 与 `updatedAt`。逐条快照落盘与回合末整批落盘两条路径会并发竞争，后到的旧快照不能把已经 `completed` / `failed` 的卡片打回 `running`；`updatedAt` 相同时终态优先；`startedAt` 取最早的非零值（`item/completed` 不一定带 `startedAtMs`）。
-- `title` 是折叠态的一行标题，按 kind 固定：`command` → `执行命令`、`file_change` → `编辑 N 个文件`（N = changes 去重后数量）、其余见 kind 枚举。
-- `summary` 是折叠态标题后面的短摘要：命令取命令首行（截断 120 字符），`file_change` 取首个变更路径。`summary` 的每个来源（命令、变更路径、`tool`）都必须先脱敏再落盘。
-- `detail.command` 读取原生命令或 MCP `arguments`，`detail.output` 读取 `aggregatedOutput` / `output` / `result` / `error`；对象格式化为 JSON，先脱敏再各截断到 4000 字符。展开工具行分别显示“输入”“输出”。MCP 摘要保留工具名，不把 JSON 开头的 `{` 当成摘要。状态相同但详情变化也必须更新；完成快照缺少输入字段时保留开始快照的输入。
-- **路径形状**：`detail.changes[].path` 用**项目相对路径**（如 `game/src/x.ts`，分隔符统一成 `/`）；项目外的绝对路径落成 `<absolute-path>` 占位。任何情况下都不得写出项目根目录本身、用户家目录或绝对路径的原始值。
-- **必须脱敏**（落盘前统一走 `agent/direct_tool_calls.rs` 的 `sanitize_detail_text`，顺序：项目路径归一化 → `redact_absolute_path_tokens` → `redact_secret_tokens` → `sanitize_error_context`）：
-  - 前缀型密钥沿用 `redact_secret_tokens`（`sk-…`、`tnr_sk_…`、`ghp_…`、`AKIA…`、`eyJ…` 等）；
-  - 键值型凭据沿用 `sanitize_error_context`（= `redact_secret_tokens` + `redact_error_sensitive_assignments` + `redact_error_bearer_values` + `redact_error_config_names` 的既有组合），覆盖 `Authorization: Bearer …`、`Cookie: session=…`、`api_key=…`、`client_secret=…`、`token=…` 等形状；
-  - 含 `--password` / `--token` / `--secret` / `--api-key` 这类敏感 CLI 标志的行按既有 fail-closed 约定**整行**替换成 `[redacted sensitive context]`（与 `sanitize_agent_runtime_text` 一致；即使标志后面只是 `$VAR` 占位符也整行替换，占位符本身不会保留）；
-  - 脱敏必须幂等（同一段文本连跑两次结果一致），且不得把未脱敏文本写进 `detail` / `summary`。
-
-### 2. 实时事件（新增字段，不改既有字段语义）
-
-`GameCreatorDirectTurnUpdateEvent` 增加**可选**字段：
-
-```ts
-toolCalls?: DirectTurnToolCall[] | null;
-```
-
-- 只有在本回合工具调用集合发生变化时才带（不要每个 heartbeat 都重发全量）。
-- 字段**可选**：老版本事件解析路径必须保持兼容（前端拿到 `undefined` 时行为与现在一致）。
-- `DirectTurnToolCall` 与上面 payload 同形（去掉 `turnId`）。
-
-### 3. 落盘契约（写侧）
-
-DirectRuntime 写 `<projectRoot>/.agent/conversations/tool-calls.jsonl`；回读命令与 Rust 侧回读函数已随聊天读路径退役删除，下面的语义约束的是**写进文件的行**。
-
-- **上限语义**：200 条是「按时间保留最新 200 条」。超出时更早回合的卡片会被**静默丢弃**（老回合卡片会消失），不做分页、不做历史回填；同一 `id` 的多条记录先按 `updatedAt` 合并，再按时间正序裁剪。
-- 历史文件缺失 → 返回空数组，不报错。
-- 单行损坏 → 逐行读字节并逐行解码，跳过该行继续，不整体失败；只有损坏字节与下一行黏成一行（例如写入被截断、缺失换行）时，被丢掉的也只是那**一行**，其后的合法记录必须继续读回（与 Codex item 流一样是"尽力而为"的展示数据，不是业务真相）。
-
-### 4. 前端合并与渲染（回合唯一归属，连续工具成块）——已作废，见文首修订
-
-- 加载对话时按 `turnId` 归并为唯一回合容器，用户消息保留在该回合前部。有 `turn-stream.jsonl` 时，文本与工具按 item `seq` 交替，连续工具合为一块，遇到文本另起一块；没有流的历史回合才采用“工具块 + 历史正文”。
+- 加载对话时按历史条目进入 `project.jsonl` 的原始顺序投影：用户消息、文本与工具块保持原序，连续工具合为一块、遇到文本另起一块，不按 `turnId` 重新归并、也不再有 `seq` 交替。
 - 回合完成后，中间文本及所有工具块统一收进默认关闭的“执行过程”；最终回复及失败提示留在外面。展开后仍按原顺序查看中间输出和工具详情；运行中不使用外层折叠区。用户消息的发送时间从消息自身的历史时间读取，不能拿工具起点补造。
 - 实时与回读共用同一投影，正文、工具和耗时不另建实时/未归属渲染出口。先在完整历史按消息身份关联，再分页；禁止按第 N 个工具回合匹配第 N 条用户消息。详情通过当前回合 `callId` 关联；同项目回读与实时增量幂等合并，切项目清空旧状态。完整合同见 [AGC 实施计划](./【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md) 的“DirectProject 回合展示唯一归属”。
 - 块 DOM 与交互（对齐 Codex）：
@@ -146,32 +110,28 @@ DirectRuntime 写 `<projectRoot>/.agent/conversations/tool-calls.jsonl`；回读
 
 ## 验收判据（每条都要有可复现证据）
 
-1. 一轮真实回合里，`tool-calls.jsonl` 里同 id 只有一行，`completed` 后 `status` 变 `completed`。
+1. 一轮真实回合里，按项目对话历史投影出的工具卡片同 id 只有一张，`completed` 后状态变 `completed`。
 2. 刷新页面 / 重开项目后，工具调用卡仍在原位（不重复、不丢）。
 3. 实时回合中卡片状态从 `running` 走到 `completed`。
 4. 折叠/展开键盘可达（Tab 到头部按钮、Enter/Space 切换、`aria-expanded` 同步）。
-5. `Read` 到的既有对话（无工具调用）行为不变；老事件（无 `toolCalls` 字段）行为不变。
-6. 脱敏检查：`tool-calls.jsonl` 里不出现 API Key / Token / 绝对用户目录。
+5. `Read` 到的既有对话（无工具调用）行为不变。
+6. 脱敏检查：卡片摘要、输入 / 输出与展开详情的落盘内容中不出现 API Key / Token / 绝对用户目录。
 
 ## 不做项（本次明确不做）
 
 - 不做工具调用的重试 / 取消 / 编辑按钮。
 - 不做 diff 级展开（只在展开态列文件路径与变更类型）。
 - 不做工具输出的完整回放、不做卡片内搜索。
-- 不改 `.agent/conversations/project.jsonl` 的既有格式与注入 Codex 上下文的路径（新数据走独立文件，避免污染模型上下文）。
+- 不改 `.agent/conversations/project.jsonl` 的既有格式与注入 Codex 上下文的路径。
 - 不改工具调用之外的聊天渲染（markdown、气泡、滚动）。
 - 不做历史工具调用的迁移回填（存量项目没有卡片，属预期）。
 
 ## 涉及文件（实现边界）
 
-- Rust（`apps/ai-game-creator-shell/src-tauri/src/`）：`agent/codex_app_server.rs`（item → 结构化采集）、`agent/direct_runtime.rs`（随事件下发 + 回合结束持久化）、`agent/direct_project_history.rs` 或新增 `agent/direct_tool_calls.rs`（upsert 与回读）、`commands.rs`（新增命令注册）。
-- 前端（`apps/ai-game-creator-shell/src/`）：`app/types.ts`（新增字段与类型）、`App.tsx`（订阅、累加、加载时合并）、`features/agent-runtime/` 或新增 `features/project-workspace/ToolCallCard.tsx`（卡片组件）、`styles.css`（卡片样式，新样式集中在文件末尾中文注释区块）。
-- 测试：Rust 侧单元测试（upsert 幂等、状态按 `updatedAt` 单调合并、截断、脱敏覆盖与幂等性、项目相对路径形状、非法 UTF-8 损坏行跳过、200 条上限保留最新）、前端 `tests/`（卡片渲染、折叠交互、重开项目后合并、老事件兼容）。
+- Rust（`apps/ai-game-creator-shell/src-tauri/src/`）：`agent/codex_app_server/mod.rs`（item → 结构化采集）、`agent/thread_manager/wire.rs`（读取期脱敏、截断与 ts-rs 导出模型）、`agent/direct_runtime/mod.rs`（运行态事件）。
+- 前端（`apps/ai-game-creator-shell/src/`）：`app/types.ts`（卡片类型）、`view/project-development/chat/conversation/directThreadItemProjection.ts`（历史条目 → 卡片投影）、`view/project-development/chat/components/ToolCallGroup/`（卡片组件与文案）、`packages/shared`（共享过程样式）。
+- 测试：Rust 侧单元测试（历史条目投影、脱敏覆盖与幂等性、相对路径形状、截断）、前端 `tests/`（卡片渲染、折叠交互、重开项目后合并）。
 
-## 实施顺序（每步都要能独立验证）
+## 实施状态
 
-1. Rust 采集 + 独立文件 upsert：先只落盘，单元测试证明幂等与截断。
-2. 事件字段下发 + 前端类型：老路径不受影响（回归现有 appSurface 用例）。
-3. Tauri 回读命令 + 前端加载合并：刷新后卡片存在。
-4. 卡片组件 + 样式 + 无障碍：折叠/展开 + 键盘。
-5. 真实回合联调（本地 Tauri 起一轮），截图留证。
+卡片表现层已按本方案落地；数据来源层在 2026-09-16 改为「运行态事件 + 项目对话历史」前端投影（见文首修订），原先的直连工具账本链路已随 issue #553 清理移除。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -812,8 +812,9 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 ### `profile_wallet_ledger`
 
 - Rust 结构体：`ProfileWalletLedger`
-- 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
+- 源码：`server-rs/crates/spacetime-module/src/runtime/active/profile.rs`
 - 说明：账号钱包流水表。`created_at` 表示钱包事务实际结算时间，列表先按当前余额反向校验 `balance_after - amount_delta` 的结算链，再以该时间倒序兜底，避免支付回调或退款重放延迟时出现余额顺序倒置；支付平台确认时间继续保存在充值订单 `paid_at`。`metadata_json` 为可选 JSON 对象字符串，旧行缺失时读取层按 `{}` 归一；外部生成扣费 / 退款写入 `externalGenerationJobId`，使退款记录可以追溯到对应 `external_generation_job`。
+- 实际变动为 0 的条目不进账单：写入侧只在余额真的变化时落账，每日免费 / 会员周期换期先按 `previous_balance - expired_points + granted_points`（饱和运算）算出实际变动，变动为 0 时只更新余额状态、不写本表；通用结算入口 `apply_profile_wallet_signed_delta` 在 `amount_delta == 0` 时同样不落账。读取侧 `list_profile_wallet_ledger_entries` 在结算链排序之后、截断 50 条上限之前剔除 `amount_delta == 0` 的存量行，因此历史遗留的 0 变动流水不会出现在 `GET /api/profile/wallet-ledger`，也不占用列表上限。该规则只影响展示与落账，不改变幂等 ledger、余额结算、消费投影和退款语义。
 
 ### `profile_wallet_consumption_total`
 

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -123,10 +123,16 @@ AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creato
 
 AGC 开发态还会按后台 Web 的端口约定额外拉起 `apps/admin-web`：Linux 用当前用户端口段的 `start + 3` 槽位，非 Linux 以 `3102` 为兼容首选并允许统一漂移，`ADMIN_WEB_PORT` 可显式指定且必须避开已解析的 AGC Vite 端口；设置 `AGC_DEV_ADMIN_WEB=0` 可关闭。后台 Vite 与 AGC Vite 一样由 `start-dev-stack.mjs` 直接持有并随启动器退出收束，不走 `npm run dev:admin-web`——后者会整体重写 `.app/dev-stack.json`，覆盖本次配套后端的归属状态；后台 Web 的端口解析、启动失败或运行中意外退出都只打印告警，不阻断也不连带停止 AGC 客户端与配套后端。前端与配套后端就绪后，启动器会打印一行 `[ai-game-creator-shell] 启动汇总:`，依次给出前端、后端、后台、数据库与 `bgfilter-worker` 的实际地址；端口漂移或默认端口被其它工作树占用时，以这一行为准。
 
-Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Windows 下每个长驻服务都经 `cmd.exe /d /s /c` 包装层启动，Ctrl+C 会先杀掉包装层（退出码 `0xC000013A`），因此清理不能只看直接子进程是否存活：`taskkill` 对已退出的 PID 只会失败，必须继续按记录下来的根 PID 遍历，并在退出时按本工作树 `api-server.exe` 绝对路径（以及本次自己拉起的 SpacetimeDB `--data-dir`）做一次身份兜底清扫；`scripts/dev-windows-process.mjs` 是这套判定的唯一实现。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
+Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Windows 下每个长驻服务都经 `cmd.exe /d /s /c` 包装层启动，Ctrl+C 会先杀掉包装层（退出码 `0xC000013A`），因此清理不能只看直接子进程是否存活：`taskkill` 对已退出的 PID 只会失败，必须继续按记录下来的根 PID 遍历，并在退出时按本工作树 `api-server.exe` 绝对路径（以及本次自己拉起的 SpacetimeDB `--data-dir`）做一次身份兜底清扫；`scripts/dev-windows-process.mjs` 是这套判定的唯一实现。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
 
 Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-worker` 默认不主动启用 sccache；只有用户通过 `RUSTC_WRAPPER` 或 `CARGO_BUILD_RUSTC_WRAPPER` 显式配置 wrapper 时才进入处理流程。配置为 sccache 时会限时执行真实 wrapper 探测，成功才使用缓存；未安装、不可执行、超时或两个变量冲突时设置为空值，回退到真实 `rustc`，不阻断启动。完整栈和 `dev:api-server` 把 API 与 BgFilter worker 作为一个 Rust 重启单元：源码变化时先停两个进程，再先启动并验活 worker、最后启动并验活 API，避免两个 `cargo run` 并发链接同一个 Windows 可执行文件。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志中的 wrapper 启用、冲突或回退提示。
 
+`npm run agc` 的 Tauri Cargo 走同一套本地 wrapper 规则：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 在启动 Tauri CLI 前调用 `scripts/dev.mjs` 导出的 `buildLocalRustProcessEnv`，把决定结果显式写进 `RUSTC_WRAPPER` 与 `CARGO_BUILD_RUSTC_WRAPPER`。用户级或仓库级 Cargo 配置里的 `rustc-wrapper`（本地常见为 `~/.cargo/config.toml` 的 sccache）只在环境变量非空时才会被覆盖，所以这两个变量必须由脚本写入而不能留空；否则本机 sccache daemon 状态损坏时，Tauri Cargo 的首次 rustc 探测（`failed to run rustc to learn about target-specific information`）就会中断整个 AGC 启动，而配套后端因为已经在用同一规则而能正常起来。AGC 启动日志出现 `[dev:rust]` 提示即为该规则生效。
+
+AGC 随包资源（内置 Codex CLI、插件工作区）的布局与组件白名单只有一份人工声明：`apps/ai-game-creator-shell/src-tauri/build_support/package-layout.json`。Node 侧准备步骤直接读它，Rust 侧读由 `node scripts/check-package-layout.mjs --write`（仓库根 `npm run agc:bundled-resources:sync`）生成的 `build_support/package-layout.generated.rs`；门禁 `npm run agc:bundled-resources:check` 已进 `agc:typecheck` 链，两者不一致直接失败。改布局只能改声明文件再同步生成物，不要手改生成文件，也不要另写第二份白名单。准备步骤是 `node apps/ai-game-creator-shell/scripts/prepare-bundled-resources.mjs`：写临时目录后原子替换、命中缓存不写任何文件、只替换本工具产物、失败即退出并给出可执行提示；其用例为 `npm run agc:bundled-resources:test`。内置 Codex CLI 的上游平台包来自仓库根 `npm ci`，缺失时工具会直接提示重新安装。构建脚本对既有随包产物做只读校验（不再有写入分支，因此也没有跳过写入的开关）。
+
+随包资源由准备步骤在 Tauri 之前生成：`npm run agc` 在 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 里、spawn Tauri CLI 之前调用（日志以 `[ai-game-creator-shell]` 前缀给出命中缓存或重新生成）；发布链在 `build-release.mjs` 的 `runTauriBuild` 内与 Node 运行时 staging 并列调用，并传 `profile: 'release'`，`tauri build --no-bundle` 也会执行随包资源 staging（app 构建本身就需要这些资源），只跳过总号发布。**构建脚本完全不生成随包资源**（源码派生内容逐文件比对、已准备产物查存在性、Godot 随包库跑既有深度校验），源码不变时 `cargo build` 稳定 fresh。需要外部工具链或同一次 cargo 构建才能产出的内容（Unity publish 目录、Godot gdextension、Cocos bridge dll）也由准备步骤按 `build_support/package-layout.json` 的 `prepareSteps` 先运行 `powershell.exe -File build.ps1` 或 `cargo build -p … --target …` 再复制；这些步骤按内容指纹跳过未变化的情况。`resources/plugins` 由准备步骤拥有：不要手工往里放东西，准备步骤会按仓库 `plugins/` 与声明重建；dev 构建下客户端读的是 `target/debug/plugins/**`（Tauri 在 debug 配置下把随包资源拷到那里），所以改完资源要重跑准备步骤而不是手动改 `resources/`；`.taurignore` 的 staging 条目已删除（构建期不再写该目录）。
+
 ### 本地 Rust 构建缓存与磁盘上限
 
 `server-rs/Cargo.toml` 和 `apps/ai-game-creator-shell/src-tauri/Cargo.toml` 是两个独立 Cargo workspace；AGC 会以 path dependency 复用 `agent-runtime-core`、`platform-llm`、`platform-agent` 和 `shared-contracts`，但两边默认仍分别写入 `server-rs/target` 与 `apps/ai-game-creator-shell/src-tauri/target`。这个代码和锁文件边界继续保留，不为节省磁盘直接合并 workspace；生产构建脚本和 Tauri 发布还依赖当前 manifest / lock / target 身份。
@@ -334,6 +340,17 @@ npm run check
 
 ### 编译告警的保留边界与待优化项
 
+- 设计会话的水合、重置和调试快进通过共享核心验证损坏会话隔离、不确定批次恢复和事件失败后的落盘状态；仅 Tauri 包装限定生产编译，资源与模型客户端仍在原校验阶段之后按需加载。旧 UI 绑定、合并及语义建议命令已随现役 UI 工作流替换而删除；分离恢复测试验证已完成的绑定和图片不被重新生成，不代表首次生成全链路已覆盖。音频派发测试验证使用派发时的 revision、保留提交身份，并在远程上下文失败时保持 Prepared 账本及项目内容不变。
+- AGC 纯生产接入按模块限定 `cfg(not(test))`：桌面启动、Tauri 命令注册和没有测试消费者的命令接入集中到对应生产模块；共享业务实现、被测试直接调用的入口和现有断言仍参与测试编译。拆分不改变命令名、注册集合、权限校验或启动/退出顺序，也不新增 `allow(dead_code)`、虚假引用或仅为消警的测试。每批同时检查 AGC 普通目标和测试目标，源码结构检查跟随真实接线位置更新；不能用测试目标通过代替生产目标检查，也不以清零告警为由排除已有测试覆盖。
+- 插件/客户端扩展、模板库和预览的桌面命令与所属模块的共享实现分离：插件进程及权限逻辑、扩展仓库、模板访问授权/归档校验/建项、预览注册表与生命周期继续由原测试验证。模板命令和普通建项命令共用的 AppData 根目录选择接入随生产模块编译，用户所选目录的安全校验仍保留在共享实现中。
+- 编辑器适配器注册、随包资源定位和平台会话 fixture 加载属于桌面/Runner 启动接入，按生产模块编译；fixture 的发行版拒绝、路径边界、文件大小及凭据校验不得随拆分改变。配置 setup、Windows 提权 helper 的票据消费和 Runner bootId 初始化随其生产调用方限定范围，配置迁移、ACL 安全规则、平台身份/凭据轮换、编辑器执行回执及进程归属的已有测试继续编译。
+- 项目快照的周期调度、窗口事件、退出等待和桌面命令与共享同步核心分离；Analytics 的服务初始化、窗口/退出事件、上传定时启动和启动时补投同样属于生产接入。窗口登记状态机、快照索引与同步事务、埋点状态机、上传轮次和补投资格处理继续参与测试，不能用移除这些测试的方式消除告警。
+- Runner 服务监听循环、连接读写接入、心跳和 GUI owner 监控按生产边界编译；共享 RPC 分发、endpoint 校验、请求幂等、项目 owner 和生命周期测试继续参与测试。只读配置入口有 Unix 专属测试，必须保留 `any(not(test), unix)` 的使用范围，不能直接归入仅生产模块。
+- MCP 的 STDIO 启动和 Tauri 命令包装限定生产编译；loopback 启停、服务注册表、析构与工具桥启动属于 Claude Direct 的共享依赖，必须参与测试编译。认证链路调用的 `validate_platform_session_input`、线程队列使用的 `DirectGameCreatorTurnUpdateEmitter::new` 同样保留在测试编译中；Direct/设计工具及 UI 编辑器的纯命令包装随桌面入口编译。Thread Manager 的订阅/消费同时服务 Unix 集成测试与跨平台取消回合回归，不限定为生产或 Unix。项目资源的生产命令 DTO 与读取接入按实际消费者限定范围；分类更新测试从正式 camelCase 请求解码后验证同一身份与 revision 的写入，音频提交测试核对派发 operationId 与账本任务一致、幂等键不被替换。业务编排、网络鉴权和持久化安全逻辑不能仅因没有直接测试而整段排除。
+- Direct 取消入口必须验证错轮请求不取消、不释放、不发送终态；执行器退出后的残留守卫释放须返回原 clientTurnId，并发布对应 canonical userItemId 的 aborted 终态。旧守卫析构不能清掉随后启动的新回合。此类安全行为通过真实入口回归保留在测试构建，不以条件编译排除取消链。
+- 预览测试使用系统临时目录，不依赖 Windows 未必提供的 `HOME`。Cocos 插件 RPC 往返测试在注册完成后，通过只读状态查询确认插件已接收启动时的项目上下文，再执行原有隐式项目路径断言；Unity 跨项目测试先等待项目事件订阅，再切换项目。不能把注册完成等同于项目订阅快照已到达，也不能重试写操作掩盖初始化竞态。
+- AGC 测试编译使用 `cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell --tests` 定向核对。GUI 主入口在测试构建中被排除，不能把测试目标的 `dead_code` 一律认定为废弃生产代码；仅生产入口使用的导入限定 `not(test)`，平台测试导入与对应 Unix/Linux 测试保持相同条件，失去调用方的测试 helper 和多余重导出直接删除。DirectHome 命令配置测试明确断言禁用 `shell_tool` 与 `unified_exec`；Windows 路径校验的测试分支不触发宿主提权修复，修复范围参数仅由生产分支消费。
+- 测试 helper 的条件要覆盖真实使用范围：Unity delivery 观测 helper 限于 Windows x86_64 的 `unity-editor-execute` 测试，Agent DB 链接安全断言与 app-server 工作区启动包装限于 Unix 测试，模板假数据的环境变量读取限于 `template-library-fixtures` feature。底层生产实现与共享测试逻辑继续保留。仅检查完成阻塞协议固定中文措辞、且失去测试标记的遗留函数直接删除；现役自由执行请求使用短任务协议，不向其测试搬入标准模式的完成阻塞提示词要求，标准模式的生产协议保持不变。
 - AGC 默认 Windows dev 构建在 2026-09-23 清理后的 `cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell` 复核通过，剩余 3 条 AuthBridge 相关 Rust warning 和 5 条 ts-rs 提示。这是当次配置的检查结果，不代表后续提交、正式 editor features、其它平台、test targets、release 链接或安装包均无告警；后续按改动范围定向验证。
 - AuthBridge 的 3 条 warning 暂缓处理，支持或退役 OAuth 的决策仍未确定。完整证据、保留边界和关闭条件以 [AGC 主方案“OAuth 认证路线的契约冲突与待决边界”](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#oauth-认证路线的契约冲突与待决边界)为准。
 - ts-rs 12.0.1 的 5 条提示来自四个枚举（`DirectCodexUserItem`、`DirectCodexUserContentPart`、`DirectThreadItem`、`DirectThreadEvent`）的 `serde(deny_unknown_fields)` 和图片组件的 `serde(deserialize_with = "deserialize_fill_amount")`。已静态核对 TypeScript 类型形状及基础类型正确、Serde 运行时校验仍有效；暂保留提示，不引入依赖补丁、不改业务校验或全局屏蔽，待上游正式版本支持后再评估。
@@ -644,6 +661,8 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
 
 后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照，默认只看本部署渠道，顶部“渠道”选择框可切换远端已存在的其它渠道；列表按游标分页（每页 20/50/100，上一页复用已取得的游标，远端不给总数所以只显示当前页）。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。“用户”列与“素材查询”同口径展示昵称与陶泥号，并可点开用户详情；不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。
 
+“按同步时间排序”按钮按需读取所选渠道全部项目，完成后按同步时间从新到旧、用户 ID 和项目 ID 字符串升序显示，并在浏览器本地按 20/50/100 条分页；列表会显示本轮项目总数。读取中可取消，失败保留原结果。排序模式下“刷新”重新读取全部项目，“恢复默认顺序”返回远端目录分页；切换渠道或重新登录清除临时排序结果。每次全量读取上限为 200 页、10,000 个唯一项目和 60 秒，超限报错，不将部分集合视作排序完成。该操作增加当次 OSS 清单读取量，不写 OSS 索引、不改数据库或 AGC 上传契约；并发同步结果以本轮读取集合为准，最新变化需刷新。
+
 自动上传以原生登记的活动工程为准：打开即首传、每 300 秒周期同步、切换/关闭补传。排障同时核对 AppData `project-snapshots` 索引、`project_snapshot.sync.*` 日志和远端清单；只有测试项目的历史清单不能证明现役项目同步生效。前端在同一窗口内切项目时必须登记生命周期，不能只检查 URL 是否包含 `projectPath`。
 
 后台枚举另外需要 AGC 私有前缀的 `ListObjects`（RAM `oss:ListObjects`，限制 prefix）与 `GetObject` 权限；下载不需要写入权限。客户端修复、后台页面与 api-server 必须分别发布才能在安装版和线上后台使用。本地定向测试及页面模拟不能代替发布后的真实上传与 ZIP 下载验收。