Merge branch 'master' into fix/ref_doc

2026-08-31 14:37:36 +08:00
parent 6505a151c3 80b8238d0a
commit 2f2fa035f3
146 changed files with 12817 additions and 3103 deletions
@@ -31,6 +31,7 @@

 ## 图片画布与媒体

+- [共享基础组件库与展示页](./technical/【前端架构】共享基础组件库与展示页-2026-08-26.md)：网站与客户端复用的无业务 UI chrome、样式边界和 `/components` 展示页。
 - [客户端素材创作无限画布阶段一合同](./technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md)
 - [图片画布结构化持久化与迁移回滚](./【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md)
 - [编辑器生成结果原子提交与幂等重放](./technical/【后端架构】编辑器生成结果原子提交与幂等重放方案-2026-08-06.md)
@@ -322,7 +322,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 - type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的历史坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪、`dependencyDepth` 或资源拓扑身份签名（精确引用端点和聚合 task-flow 成员）变化后按最终拓扑确定性重算。签名以稳定资源 ID 的规范端点 / 成员序列生成固定大小摘要，不使用显示名称或浏览器测量值；自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
 - 搜索或筛选只隐藏卡片，不删除、压缩或重排其坐标；清空搜索后恢复原位置。
 - 窗口尺寸变化只改变当前栏目的可视范围，不回写或裁切持久坐标，也不因资源 extent 或 resize 把已平移的 viewport 拉回内容边界。当前客户端继续以 `1280×800` 横屏合同验收。
- 任一栏目出现资源后，资源管理固定使用 `设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本` 五栏目分页画布；每个栏目按 `projectId + mode + category` 保留独立 viewport。普通 wheel 切换栏目，`Ctrl/Cmd + wheel` 以指针位置为锚点缩放当前无限画布，空白拖动只平移当前栏目；非空状态不提供分区高度、分区内部滚动或分区内容倍率。搜索和详情开关不得重置 viewport，项目、mode 或栏目切换只恢复各自会话状态，显式复位才重新适配当前栏目内容。
+- 任一可见资源出现后，普通用户资源管理固定使用 `设计文档 -> 美术资源 -> 音乐音效 -> 项目版本` 四栏目分页画布；游戏代码仍保留在内部资源、布局和依赖事实中，但不进入普通资源画布的导航、分页、卡片、搜索或详情入口。每个可见栏目按 `projectId + mode + category` 保留独立 viewport，普通 wheel 切换栏目，`Ctrl/Cmd + wheel` 以指针位置为锚点缩放当前无限画布，空白拖动只平移当前栏目；非空状态不提供分区高度、分区内部滚动或分区内容倍率。搜索和详情开关不得重置 viewport，项目、mode 或栏目切换只恢复各自会话状态，显式复位才重新适配当前栏目内容。
 - 首次载入项目中的既有资源不显示未读标识。当前会话内，非当前栏目出现稳定 ID 的新资源时，在对应栏目名称右上角显示红点；当前栏目新增资源不显示红点，用户通过点击、滚轮或程序跳转进入该栏目后立即清除。未读状态只属于当前前端会话，并按 `projectPath + projectId` 隔离，切换项目时清空，不写入 manifest、布局 sidecar 或后端。
 - 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；dependency 模式必须先等待与当前 `projectPath + projectId + resource inputs` 匹配的 Rust 图进入 `ready` 或 `failed` 终态，等待期间不得创建 fallback、读取 sidecar、协调资源或入队保存。`failed` 只允许以空图降级初始化一次。项目或 mode 已切换后返回的旧异步结果必须丢弃。
 - 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。当前 scope 内资源自动协调写入使用单写者 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
@@ -355,7 +355,7 @@ type UpdateProjectResourceCanvasLayoutResult =

 ### 5.3 资源类型与替换兼容性（P1）

-实现状态（2026-08-23）：当前资源投影与栏目页顺序收口为“设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本”。设计文档接收受支持的 UTF-8 文档、代码资产中的文档类型和合法 Agent 文本回执；项目版本只接收显式 `ProjectVersionResourceSummary` read model，未知任务产物不得兜底为版本；美术资源接收图片、SVG、动画和视频类产物；音乐音效接收 manifest 资产、上传登记资产和已完成任务 `artifacts` 明确声明的音频产物；游戏代码接收 Direct Codex / 任务产物登记的 HTML、CSS 和 JavaScript。无法识别的二进制任务产物和附件不进入资源画布。受控读取、中央聚焦、失败空态与媒体播放不改变 manifest 真相；编辑成功后只追加新的 asset 或版本子记录。
+实现状态（2026-08-29）：内部资源投影仍识别“设计文档、美术资源、音乐音效、游戏代码、项目版本”五类事实，但普通用户资源画布只展示“设计文档 -> 美术资源 -> 音乐音效 -> 项目版本”四个栏目；游戏代码不进入画布导航、分页、卡片、搜索或详情入口。设计文档接收受支持的 UTF-8 文档、代码资产中的文档类型和合法 Agent 文本回执；项目版本只接收显式 `ProjectVersionResourceSummary` read model，未知任务产物不得兜底为版本；美术资源接收图片、SVG、动画和视频类产物；音乐音效接收 manifest 资产、上传登记资产和已完成任务 `artifacts` 明确声明的音频产物；游戏代码继续接收 Direct Codex / 任务产物登记的 HTML、CSS 和 JavaScript，底层文件、manifest 事实、生成/编辑/运行能力、项目版本引用与依赖关系不变。无法识别的二进制任务产物和附件不进入资源画布。受控读取、中央聚焦、失败空态与媒体播放不改变 manifest 真相；编辑成功后只追加新的 asset 或版本子记录。

 资源身份固定使用 manifest asset ID、正式 version ID、Agent ID + run ID 或已导入资源稳定路径；显示标题、来源文案变化不得改变 `resourceId`，从而避免布局、依赖边、选择和聚焦状态因改名失效。

@@ -533,12 +533,12 @@ type ProjectAgentMudPointAttribution = {

 ### 7.5 资源栏目分页无限画布验收

-1. 完全空项目继续显示全部栏目的分区展览；任一栏目出现资源后，dependency / type 都切换为固定五栏目分页画布，悬浮 Dock、底部下一页标题和普通 wheel 可访问全部栏目，空栏目也可打开空画布。
-2. 每个 `projectId + dependency|type + document|art|audio|code|version` 组合保留独立 viewport；切换栏目、模式、项目和打开 / 关闭详情后恢复对应平移与缩放，窗口 resize、媒体测量和资源 extent 变化不得重置用户 viewport。
+1. 完全空项目继续显示四个可见栏目的分区展览；任一可见栏目出现资源后，dependency / type 都切换为固定四栏目分页画布，悬浮 Dock、底部下一页标题和普通 wheel 可访问全部可见栏目，空栏目也可打开空画布；游戏代码栏目和代码卡片不出现。
+2. 每个 `projectId + dependency|type + document|art|audio|version` 组合保留独立 viewport；隐藏代码资源的历史内部坐标和 sidecar 会话状态不被删除或重写，切换栏目、模式、项目和打开 / 关闭详情后恢复对应可见栏目平移与缩放，窗口 resize、媒体测量和资源 extent 变化不得重置用户 viewport。
 3. 当前栏目允许空白拖动无限平移；`Ctrl/Cmd + wheel` 以指针为锚点缩放，显式复位按包含负坐标资源在内的完整 bounds 适配内容。非空状态不显示分区高度、分区内部滚动或分区内容倍率操作。
 4. 资源卡超过 `5px` 阈值后进入拖动，预览和 dependency 线同步移动；成功释放只提交一次 `manuallyPlaced=true` CAS，取消、移出释放、媒体控制点击和未超过阈值均不写布局。
 5. dependency 引导线消费当前栏目的同类型精确引用，并与卡片共享同一 viewport transform；平移、缩放、拖动预览、搜索和 resize 后端点保持对齐，type 模式不渲染引导线。
-6. 栏目分页、viewport 和资源卡拖动只修改工作台会话状态或资源布局 sidecar，不改 manifest、项目 mutation revision、Runtime verification、Agent 权限和预览状态；图片、视频、音频、文档、代码、版本卡片及非模态详情回归全部通过。
+6. 栏目分页、viewport 和资源卡拖动只修改工作台会话状态或资源布局 sidecar，不改 manifest、项目 mutation revision、Runtime verification、Agent 权限和预览状态；图片、SVG、视频、音频、文档、任务产物、Agent 回执、项目版本卡片及非模态详情回归全部通过，游戏代码仅保留内部事实而不进入普通资源画布。

 ### 7.6 阶段七完整验收

@@ -1,4 +1,5 @@
 # 决策记录
+
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。

@@ -14,6 +15,14 @@
 - 关联文档：相关 PRD、技术文档、提交或 Issue
 ```

+## 2026-08-30 批准 GDD 直接进入做游戏链路
+
+- 背景：立项策划 GDD 批准后需要给用户一个进入做游戏的自然出口，产品决策改为点击按钮后直接开始建造。
+- 决策：批准态 GDD 交付行提供“做成游戏”按钮。点击后读取当前项目的权威 `game/fast_gdd.md`，直接创建自动游戏工作区、导入 `text/markdown` 参考附件，并以固定建造指令自动启动 Direct Codex；不再回首页等待用户二次提交。该动作不复制原项目的 `approvedGddRef`、planning sidecar 或 approval receipt。
+- 影响范围：AGC 前端 GDD 交付行与现有自动建项/附件导入/Direct Codex 链路；移除首页 RichInputArea 的 GDD 一次性预填链路；不新增 HTTP API、SpacetimeDB schema、迁移、OpenAPI 或正式构建绑定。
+- 验证方式：批准态按钮直接创建工作区、导入附件、携带固定首条指令进入项目工作台且重复点击不重复创建的 appSurface 回归；类型检查、编码检查和 `git diff --check` 通过。
+- 关联文档：`docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`。
+
 ---

 ## 2026-08-31 Direct 本轮附件只映射路径，不灌正文、不区别 GDD
@@ -117,6 +126,7 @@
 - 决策：三个工具调用的 arguments 统一限制为 `1 MiB`，先解析通用 JSON 并迭代检查，再进入递归业务类型。结构识别按每棵树独立限制 `512` 个 LLM 节点 / `32` 层，不跨树求和且不计 Rust 页面根；语义建议限制 `4` 节点 / `4` 层；合并计划限制 `512` 节点 / `32` 层。超限整次拒绝，不截断或交付部分结果，日志不记录 arguments 正文。
 - 输入边界：`merge_ui` 继续直接接收 `State`，不修改 Tauri/frontend IPC 参数；进入 Rust 后、发起 LLM 前按每棵源树独立限制 `512` 节点 / `32` 层，不跨树求和，并限制 `2 MiB` 序列化投影。UI 设计参考图只设单张 `5 MiB` 上限，不设批次合计或像素数上限；元数据检查、有限读取和 base64 编码进入 blocking worker，不新增命令超时。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-19 M1 审查后四项可靠性修复

 - **审批 stale 收口**：`status` 或 `phase` 为 `needs-reconciliation` 的策划根不再满足审批所需的 active 身份；审批命令返回 `PLAN_STALE_APPROVAL`，并且不得创建 approval receipt。
@@ -161,6 +171,7 @@
 - **验证**：`appSurface.test.ts` **381 passed / 0 failed**（378 既有 + 3 新增）；`agentTraceSummary` 与 `rememberCommand`（另两个 import `src/App` 的用例文件）13 passed；`agc:typecheck` 通过；6 个改动/新增文件 ESLint `--max-warnings 0` 通过；`check:encoding` 5409 文件通过。不改 Rust——三条全在前端，后端语义已经正确。
 - **对既有记录的更正**：M1D-1 与 M1D-2 两条记录分别称「Shell TypeScript typecheck 仍被仓库既有依赖缺失阻断」「appSurface UI suite 受仓库现有缺失 Tauri plugin 依赖阻断，未把该基线失败归因于本包」，在原分支主工作树上都不成立：`agc:typecheck` 干净退出，appSurface 378 条全绿；两道门分别位于 CI 的 `check:native-shells`（且 typecheck 排在 cargo test 之前）与 Frontend tests 内，一直是活的。实际情况与记录相反——`bf2185fba` 改名 `taskGroupLabels.design` 后，appSurface 有 8 个用例文件的断言变红，随后由 `c6a08ef98` 修复；把该套件记为「基线阻断、不归因本包」正是让这条自带回归合入的原因。**隔离工作树的依赖缺失不能作为跳过门禁的依据，须回原工作树复跑后再下结论。**
 - **未修的审查发现（本次不并入，单列后续）**：① hydrate 在校验 GDD/session 的 projectId 与 manifest 一致之前，已执行 `reconcile_plan_gdd_approval_projections_at`、session previous 提升与 index 重建等落盘修复，违反第 18.3 节固定顺序，其中 `session.previous.json` 的提升+删除不可逆（触发需外部篡改 `.agent/`，App 自身流程造不出该分歧）；② 项目写锁竞争时 `acquire_project_write_lock` 的错误原文内嵌项目绝对路径，被原样回传前端，违反第 18.3 节「返回值不包含绝对路径」，常态可达；③ design 组展示名只改了 `taskGroupLabels` 一本字典，`agentPresentation.ts` 的 `groupConfigs` 与 `view/project-development/index.tsx` 的 `summarizeAgent` 仍硬编码「策划 Agent」，与新阶段「立项策划」同屏共存，违反第 18.2 节；④ 阶段进度「轮次 X/3」直接透传 0-indexed 的 `clarificationRound` 未 +1（后端自己用的是 `current_round + 1`），最后一轮显示「轮次 2/3」，字面暗示还剩一轮。
+
 ## 2026-08-18 M1E 隔离工作树：Fast GDD submit 有界拒绝与覆盖审计

 - **范围与结论**：在 `codex/genarrative-isolated` 上按 M1E 只接受具备完整触发链的缺陷。确认 Provider 连续输出不合法 `plan.submit_gdd` 时，Runtime 原有「rejected observation → 同 child run 续跑」链没有次数上限，模型可反复请求 tool-plan 并累积历史 observation；这是可达的 prompt 膨胀与资源消耗链。
@@ -297,7 +308,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 不做：改 walker、透明补边、裁切、横纵不同倍率、Lanczos / bilinear、另存逻辑图、前端框缩放、失败路径、新测试。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

-
 - 背景：真实 `gpt-5.6-sol / max` 验收中，`art-director` 失败后已形成 `ready + needs-repair` delivery，但认领、合同读取、claim observation 和完成 blocker 均硬编码为 Supervisor-only；实际直属父 Run `code-prototype` 无法消费回执，随后又发起 29 次 Provider 请求。
 - 验证方式：覆盖合法认领与合同精确读取、错误 Agent/Run/delegation 拒绝、delivery 身份篡改阻断、唯一安全默认返工、普通失败零后续 Provider lifecycle，以及新的真实 Provider 空项目轮次。顺带收紧 `validate_executable_inline_javascript_syntax`：正文游离 `<` 不再吞掉后续 `<script>`，未闭合或非标签状 `<` 继续扫描，避免后置脚本被静默跳过语法校验。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
@@ -375,7 +385,8 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 **以下三条是经复核后有意保留的取舍，不是待办。后续 PR 不得在未重新裁决的情况下「顺手修掉」。**

 1. **`$isolatedAgentTemplates` 仍会向 plan 根 run 列出全部专业角色名。** `art-director` / `design-foundation` / `art-asset-plan` / `code-prototype` 等名字来自 `$base`（`RUNTIME_PROMPT_RUNTIME_COMPOSITION` 的 `$isolatedAgentTemplates` 段，由 `GAME_CREATOR_AGENT_GROUP_DEFINITIONS` 运行时渲染），用途是广告 `agent.spawn_isolated` 的合法模板 id，**不在本次裁掉的两段之内**。裁掉它要动 `$base` 与隔离模板目录，波及全部 Agent。保留的依据是：`A2` 已对 plan 根 run 硬拒 `spawn_isolated`，该目录对 plan 根 run 是**死文本**，不构成可利用面。**结论：上下文层的收窄边界到此为止；「plan 根 run 的上下文里不出现其它 Agent 名」这一目标 M1 不成立，不要据此写验收句。**
-3. **上下文层回归是弱断言。** `plan_root_supervisor_prompt_drops_intro_and_visual_contract_sections` 用「不含某几条独有短句」断言，不是对照组那种字节级 `assert_eq`。已实测非永真。已知漏报场景：若将来 `$visualContract` / `supervisorIntro` 被替换成措辞不同但仍暗示专业组扇出的新文本，这条不会报警。**执行层的 `A1`/`A2` 是该场景的唯一保障**——这也是本包把硬门排在裁段之前的原因。
+2. **上下文层回归是弱断言。** `plan_root_supervisor_prompt_drops_intro_and_visual_contract_sections` 用「不含某几条独有短句」断言，不是对照组那种字节级 `assert_eq`。已实测非永真。已知漏报场景：若将来 `$visualContract` / `supervisorIntro` 被替换成措辞不同但仍暗示专业组扇出的新文本，这条不会报警。**执行层的 `A1`/`A2` 是该场景的唯一保障**——这也是本包把硬门排在裁段之前的原因。
+
 - 关联文档：`docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md` 第 4.3、22、23.8、24 节。

 ## 2026-08-14 M1B-1：planning storage 基础与只挡写隔离完成（待合入）
@@ -523,7 +534,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（D10，问询机制）：策划节点不得直接调用 `user.input_request`，改走 **Runtime 直投**——策划节点提交结构化决策字段，Runtime 创建 **owner 为 Project Supervisor** 的 pending，用户在 Supervisor 对话里回答，Supervisor 的 Provider 全程不参与提问。这不是新造机制：`AgentRuntimeUserInputRecord` 已经是唯一事实源并两路投影（`user_input.rs:494-530` 投影成会话消息写进 pending owner 的会话文件，`:595-623` 投影成结构化 observation，`:803-807` 有「observation 重算冲突」校验防漂移），直投只是让两路分别落到 Supervisor 与策划节点。
 - 依据的产品约束：一、用户侧只有一个对话对象；二、所有呈现给用户的对话内容必须**物理存在于** Supervisor 的会话文件中，不得由前端把多个 Agent 的会话拼成单一视图。第二条不是靠约定满足，而是靠「会话文件按 `agentId` 分目录（`conversation.rs:42`）、消息归属完全由 pending owner 决定」这个物理事实。
 - 决策卡冻结范围收窄：冻结三个固定选项及顺序（要确定性映射到 decision state 与 answer source）与 question ID 规则（`decisionId` 由它推导）；**问题正文措辞不冻结**，作者是策划节点。保真由「Runtime 不经过任何 Provider 搬运」保证，与模板无关。
- Goal Contract 处置：原四方案 A/B/C/D 随之作废（共同前提是策划 run 自己就是那个 root）。但入口门 `validate_root_goal_contract_control_plan_at` 无 profile 判断，standard root Supervisor 仍受约束，故替换为三条实测约束：Supervisor 第一轮必须且只能提交 `agent.goal_contract`；验收 `requiredEvidence` 锚定 `game/fast_gdd.md` 配 `tool:file.read`，**不得指向 `.agent/planning/**`**（`reject_agent_runtime_private_control_path` 不区分读写，加进去会把 `file.read` 一并挡死、出口门永久 blocked，planning 的写保护须用只挡写的独立判据）；Supervisor 取证必须在 GDD 落盘之后。
+- Goal Contract 处置：原四方案 A/B/C/D 随之作废（共同前提是策划 run 自己就是那个 root）。但入口门 `validate_root_goal_contract_control_plan_at` 无 profile 判断，standard root Supervisor 仍受约束，故替换为三条实测约束：Supervisor 第一轮必须且只能提交 `agent.goal_contract`；验收 `requiredEvidence` 锚定 `game/fast_gdd.md` 配 `tool:file.read`，**不得指向 `.agent/planning/**`**（`reject_agent_runtime_private_control_path`不区分读写，加进去会把`file.read` 一并挡死、出口门永久 blocked，planning 的写保护须用只挡写的独立判据）；Supervisor 取证必须在 GDD 落盘之后。
 - M0 影响判定：三个代码工作包（`M0A-2` / `M0B-1` / `M0B-2`）**全部不受影响、零回退**——无一行按 D6 编写，全仓库检索 `fast_gdd` / `.agent/planning` / `project-supervisor-plan-chat` / `is_exact_supervisor_plan_run_at` 均零命中。只有 `M0A-1` 交付的文档基线失效，以工作包 `M0A-3` 修订，修订完成前不得声称「M0 全部完成」。**注意 `M0A-2` 虽不受影响，其实现也不可复用**：`autonomous_owner_artifact_validation_available_for_run_at`（`autonomous_completion.rs:416-441`）四重绑死 owner 白名单、profile、source 且要求 `parent_agent_id` 为 Project Supervisor，standard 路径必须另建物理独立实现。
 - 保留待裁决：策划节点 `agentId` / source 命名（是 `M0A-3` 批二的共同阻塞点，身份常量不定则第 3、8、9、12、13 节无法落笔，第 9.1 节 golden vector 的 SHA-256 必然重算）；Supervisor 侧新可信 source 是沿用旧字符串还是取新名；checkpoint handoff 私有持久化（原有项，不受影响）；plan run 是否允许 steer，以及 Supervisor 被 steer 时下游策划节点如何收束。

@@ -536,17 +547,14 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - M2 裁决二：planning baseline 不是「一次冻结永久有效」。steer 替换协议会终止旧根树并另起 replacement root run，该 run 必须在自己的锁/CAS 边界内重新冻结与被替换根**完全相同**的 `approvedGddRef`，即使期间已有更新的 approved 版本也不换稿；无法证明同一 ref 时失败关闭，不得降级为 `mode=direct-build`。
 - M2 附带证据：Goal Contract 落在 `.agent/runtime/goal-contracts/{rootAgent}/{rootRun}.json`，按 root run 分文件并绑定 binding fingerprint 与 source SHA-256。这是「自带 root/run 身份」的正面先例，D4 关于 `approvedGddRef` 是否进 manifest 的决策应参照此形态，而非项目级单例。

-
 - 背景：M0B-2 遗留一条挂起项——manifest 没有 root/run 绑定，不能安全决定 cached failed manifest 是否应覆盖活跃 main 状态。本条对该项作出处置，使 M0-4 可以收口。
 - 事实基线：`GameCreationAppManifest` / `GameCreationAppTaskState`（TS 与 Rust 双侧）不含任何 run/root/agent 身份字段；manifest 是项目级单例文件、跨轮复用；前端唯一读取入口按 `task.id === 'code-prototype'` 做纯字符串过滤。因此"这份 manifest 属于哪一轮"无法从数据本身判定，这是结构性质而非实现疏漏。
 - 本阶段不加绑定：不给 manifest 或其投影新增 `statusRunId` / `statusSource` 等身份字段，维持 M0B-2「不修改后端 DTO/schema/delivery/route」的范围声明。补字段的方案必须同时覆盖 `update_manifest_task_status_at` 与 `set_task_status` 两条写入路径，否则会制造"校验通过"的假象（详见 pitfalls 2026-08-12 条）。
 - 残余风险（明示保留，不视为回归）：当前 main 到达 Runtime 终态 `completed`、而全局 manifest state 尚未被本轮 `manifestInvalidated` 事件刷新时，跨轮残留的 `failed` 仍会被当作本轮结论显示。该窗口实际宽度未量化；三条候选机制（新鲜度门控、root-scoped 永久缓存、manifest 补身份字段）经审查均不可安全落地，故本阶段只记录不实现。

-
 - 归档边界：`【Supervisor 阶段记录】` 只有在 root、唯一 main、当前动态美术 children 与 manifest `code-prototype` 全部终态且无冲突/reconciliation 时才可写入。等待期间按完整 `agent/session/run` 身份保存 root-scoped Runtime 快照，避免 current-by-agent map 被新 root 覆盖后把新旧证据串线；消息 ID 固定绑定 root run，重载与 hydration 幂等。
 - 范围：M0B-2 只改前端纯投影、接线、文案与回归，不修改后端 DTO/schema/delivery/route，不迁移历史 manifest，也不提前实现 M1～M3。

-
 - 结构性依据：delivery 的 delegationId 由父动作 ID 派生，且 targetRunId 绑定原 child run；通用 retry 铸造的 `retry:{旧run}:{新run}:{纳秒}` 身份在结构上不可能匹配任何现有 delivery。即使只圈住 retry 的写边界，其产出也没有合法消费者。让 retry 继承 lineage 必须引入可变 delivery、换绑或放宽 exact binding，与不可变事实和失败关闭方向冲突，明确不采纳。
 - 既有语义确认：同一 main run 内“每个审计缺口最多委派一次”（不含 `Suppressed`、包含终态失败或取消 delivery）是 2026-08-08 单主编排重构的 master 既有防抖语义，本裁决有意保留，不为失败 child 开豁免。同 run 重来与通用 retry 一样被拒绝，恢复只走下一轮 main 重新审计；这与禁止 retry 继承 lineage 是同一设计哲学。
 - 实现边界：入口守卫落在 `runtime_driver/lifecycle_control.rs` 的 `retry_game_creator_agent_runtime_task_at`，必须使用不要求 child 仍为 running 的结构身份分类；`resolve_game_creator_agent_runtime_retry_configuration_at` 保持不变。纵深防御落在 `runtime_tools/file_ops.rs` 的动态美术分类入口；严格 lineage/Canvas 授权 predicate 本身不放宽。除这两处与对应测试外，不扩展 M0B-1 生产改动面。
@@ -574,8 +582,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：M0 验证 tracked 技术方案、索引、注册表、golden 指纹、提交/恢复合同和决策记录自包含一致；M1～M3 分别按关联技术方案的阶段门禁执行，不能以文档合入冒充功能完成。
 - 关联文档：`docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。

-
-
 ## 2026-08-10 资源管理评审阻塞项按第二轮正式合同修复

 - 背景：资源管理第一轮实现后，人工验证继续暴露 WebView 默认缩放、预览队列饥饿、过滤后媒体残留播放、外层滚动串 scope、超深依赖坐标越过 Rust 上限和暂时错误无法重试等问题。部分 PRD / 技术方案仍描述第一轮的中央媒体预览、单全局 Overlay 和统一 section scope，已经与第二轮代码及验收结论冲突。
@@ -706,7 +712,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：按权威专题的 28 项矩阵覆盖 Web/Tauri 共用源码、新增/精修、生成响应丢失、重复提交、两窗口并发、事务各崩溃点、草稿恢复、切项目/切状态/改选择/改筛选迟到结果和不刷新即时投影。
 - 关联文档：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

-
 - 验证方式：覆盖路由后只启动 `code-prototype`、既有素材零美术委派、精确缺口才允许单个对应 child、child 的 `game/**`、memory 和 manifest 写入拒绝而 `assets/**` 写入允许、回执恢复同一主 Run，以及主 Agent 的接入、静态 smoke 与双视口试玩；追加真实 scheduler 对旧 canonical task 的同 Run 恢复、旧固定美术 child 及其历史 isolated 后代对 Canvas/memory/manifest/project scope 零 mutation、伪只读 `agent.run_status` 阻断、嵌套美术 child 硬截止对账回执；另跑完整 DAG 非回归。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

@@ -794,8 +799,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 ---

-
-
 - 背景：ready scheduler 已为当前根 Run 持久化并启动 `code-prototype`，但并发 hydration 持有的旧 manifest 快照随后把该节点从 running 覆盖回 pending。父 Run 只读取 manifest 时会在 child 仍运行的情况下误判固定 Graph 已停滞并先行失败；child 完成门又因 pending 连续拒绝真实交付，最终耗尽 loop。
 - 失败关闭：GUI/CLI、旧父 Run child、终态 child、错误/伪造绑定、非确定性 runId、WaitingForConfirmation、WaitingForUserInput 和 needs-reconciliation 都不得借用该容忍；创建更新的根 Run 后，旧 child 立即失去父 DAG 活性与 pending 完成资格。
 - 玩法连续性：普通美术措辞不再触发历史玩法类型回溯；只有正式 failed continuation 继承原完成合同，纯“继续”沿用现有 continuation 识别边界。
@@ -805,7 +808,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 ## 2026-08-05 增量接入既有美术时复用已验收 Graph 节点

-
 - 禁止替代方案：不得增加 loop 次数掩盖冲突，不得递增虚构的产物版本号，不得覆盖 art manifest 扩展字段，也不得重放历史图片生成 action。
 - 验证方式：回归必须证明明确复用时两项美术节点保持 completed、父完成门不再报告 art manifest baseline 未变化、俄罗斯方块场景保持 `tetris-v1`；删除任一切片后豁免立即失效。另以普通新目标和“全新美术”请求证明旧美术不能被认领。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
@@ -1024,7 +1026,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

-
 - 背景：External Runner 和 Tauri 客户端各自拥有进程内 `PreviewRegistry`。Runner 完成 `preview.validate` 后，其 server 与 running 状态不会出现在 Tauri registry，导致已有可玩版本时用户预览不自动出现；后续 revision 即使验证成功，既有 iframe 也可能继续显示 WebView 缓存中的旧资源。顶部只写“未启动”还会让用户无法判断是 Runner、Runtime 还是预览未启动。
 - 验证方式：以当前 run 成功 `preview.validate` revision N 后断言 iframe 自动出现且 server 归 Tauri registry；再完成 revision N+1，断言 server 进程和 loopback origin 不变、iframe 重新加载新内容且所有响应为 `no-store`。Runner registry 单独 running 不得让页面显示预览；相同 / 更低 revision 不得刷新；停止预览后顶部必须显示“预览未启动”；构建产物和安装信息必须为 `0.1.1`。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。
@@ -1044,7 +1045,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：Rust mock 503 覆盖等待、恢复与耗尽，断言 exact HTTP status、attempt、sidecar 清理和正文零泄漏；前端模型覆盖状态卡优先级、严格字段解析、字段不一致与尾随正文失败关闭；conversation 测试覆盖 Provider URL/query、API Key、绝对路径、fingerprint、chars 和 redaction marker 均不可见。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

-
 - 背景：独立包原先在 Tauri 最终退出时仅调用一次 `runner.shutdown_if_idle`；若 Runner 正忙便返回 busy 且没有稍后关闭闩锁，Runner 和后台命令会永久残留。`command.exec / project.verify` 只有进程组 flag，STDIO MCP、Git 和清理命令也缺少 `CREATE_NO_WINDOW`，因此 Windows release 会连续弹出多个控制台窗口。
 - 验证方式：定向测试覆盖专用 RPC 的 draining / shutdown 与普通 idle 语义不变；正式安装包在活跃任务期间确认无后台控制台窗口，关闭主窗口后核对 Runner、MCP、command、ConPTY 和孙进程全部退出，再启动确认 durable 状态正确 reconciliation。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。
@@ -1055,16 +1055,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：Windows 定向测试覆盖 endpoint 原子写入与 TokenUser 复核、new/stale lock owner 修复、活锁不截断、hardlink / reparse 不触碰目标、project-owner 诊断 TokenUser 复核、错误码精确分类，以及子进程退出在 2 秒内返回；正式包在现场 TokenOwner 为 Administrators 的机器上必须依次出现 `startup.runner.start.complete`，创建项目任务时 execution-owner 诊断也必须成功。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

-
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

-
 - 背景：Windows 安装包首次创建 AppData 时若沿用继承 owner，目录 owner 可能是 Administrators 而非当前登录用户；后续严格 owner 校验会让客户端在 `.setup()` 阶段退出，且无控制台 release 缺少可见诊断。直接修改 foreign-owner 旧目录的 ACL 还可能覆盖其它主体持有的数据或跟随 reparse 路径。
 - 决策：新建客户端 AppData 时以进程 `TokenUser` SID 显式设置 owner 和当前用户私有 DACL，不使用 `TokenOwner` 代表用户。历史 foreign-owner 真实目录先原子重命名为同级唯一 `.owner-mismatch-backup-*`，再重建并回读验证安全目录；任何 reparse / junction / symlink、备份冲突或迁移失败都失败关闭，不在旧目录上放宽权限。独立 release 的 `startup.log` 和记录 Runner stdout / stderr 摘要的 `agent-runner.log` 均采用 256 KiB 上限、仅一份 previous 和脱敏写入；AppData 日志不可写时 `startup.log` 回退系统 TEMP，Tauri URL、AppData、Runner、`.setup()` 或 `.build()` 初始化失败时在 Windows 显示包含诊断日志位置的错误对话框。
 - 验证方式：Windows 定向测试覆盖 TokenUser owner、私有 DACL、foreign-owner 同级备份不覆盖和 reparse 拒绝；诊断测试覆盖 256 KiB 单 previous 轮转、凭据与绝对路径脱敏、AppData 不可写时 TEMP 回退和初始化失败对话框。安装包 smoke 后保留旧备份证据并确认新 AppData 可写、Runner 可启动。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

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

 ## 2026-07-28 AI 游戏临时页面启动消息采用 URL 消费加页面闩锁
@@ -6739,7 +6736,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 历史边界：成功加入画布时写一条 `perfect-pixel` 历史，中文标签为“完美像素”，并纳入新增结果保护；撤销不得让派生 PNG 消失。像素处理失败或 completion 因占位删除未落画布时不写该历史。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`。

-
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

 ## 2026-07-31 autonomous 单一任务图、预览 fail-fast 与逐 Agent 推理默认
@@ -6787,7 +6783,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证：顺序断言新增 `tokio::time::timeout_at(` 与超时文案；参照 `937378ab9` 的做法用 `assert_function_occurrence_count` 把 `resolve_editor_pixel_art_source_for_owner` 内的 `.list_editor_projects(` 和 `.get_editor_asset_library(` 各钉为 1 次，并用 `assert_function_not_contains` 禁止该函数重新调用取数包装。后者断言的是调用形式 `resolve_editor_reference_object_key_for_owner(state` 而非裸函数名，否则会命中生产代码里说明「老包装保持不动」的注释——该陷阱在编写时即由测试抓出。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

-
 - 预算：父 Run 接受请求后以 `240` 秒作为首版软预算；父 Run、所有 child Run、等待、回收和确定性验收共享 `300` 秒累计硬上限。硬上限是从 root `bound_at` 计算的绝对 deadline，必须包住 Provider、图片生成、文件写入、静态检查、`preview.validate` 和 final-reply 的在途等待；超时先强制持久化 `failed` 终态，再清理 pending action、Provider batch、confirmation、recovery 和进程会话，不能留下 `needs-reconciliation` 悬空态。软预算后不再扩展 Provider 规划，只能运行受控 fallback、`game.static_smoke` 和 `preview.validate`；硬上限未形成当前 revision 的通过证据时必须失败关闭，单轮确定性收束也必须复核累计时间，不能在上限后补写 completed。
 - Provider：首版最多一次 Provider 规划 / 写入请求，禁止同一首版自动传输重试、第二次 tool-plan 或无限 repair。Provider 结束后由 Runtime 按当前 revision 依次执行确定性静态 smoke 与浏览器试玩。
 - 兜底：fallback HTML 必须自包含、无远程运行依赖，从 `ready` 开始并真实绘制 Canvas，持续更新 `playable-web-game-state.v1`，提供键盘 / 触控、start / primary-action / restart 和胜负状态；primary-action 后可保持 `playing`，restart 后可稳定恢复 `ready | playing`，不得开始前固定 `lost` 或用固定失败充当完成。fallback 只有在 `assets/art-spec.png` 已有效登记并真实存在时才能生成，而且必须把该平台图片显著绘制为主要背景、玩家和目标；不得以纯 Canvas 视觉绕过平台图片硬门。
@@ -6830,13 +6825,9 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证：`dropDeadInlineGenerationPlaceholders` 四条单测覆盖「剥离已死 inline 占位」「保留队列型占位（缺字段与显式 false 两种）」「保留已终态的 inline 占位与普通图层」「标记经 hydrate 与序列化往返不丢失」——最后一条钉住白名单式 hydrate 漏字段会让标记在一次「加载→保存」后消失。工作流测试新增 `live-session-dialogs` 探针，正向断言完美像素占位置位、反向断言去除背景占位不置位。`vitest src/components/image-editor` 893 通过 / 72 文件，typecheck、eslint、check:encoding 通过。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

-
-
 - 显式协作合同：autonomous 的旧 `code-prototype + quality-review` 首批合同退出。显式 project collaboration policy 或持久 batch 恢复若进入首批 `agent.delegate` 路径，只允许且要求三个 Director 各一次；策划与程序 Director 是只读规划且 `expectedArtifacts=[]`，美术 Director 是非只读规范图任务且必须交付 `assets/art-spec.png`。任何非 repair 底层委派与 isolated child 都在首批失败关闭；默认 manifest DAG 仍是唯一自动首轮执行链，不额外复制三个 Director 委派。
 - 输出决策：保留未提交 `streaming / ready` 的当前 revision 门；已提交的专业 Agent final reply 继续使用既有 durable response-stream 身份，后续项目 revision 变化不再隐藏早期阶段回复。

-
-
 - 图集事务退役补充：九路径快照在创建和恢复读取时都使用跨平台不跟随符号链接 / reparse point 的文件句柄核算 64 MiB 总预算，marker、journal 与快照均通过有界双次读取和句柄元数据复核拒绝同长度并发改写；实际读取仍受剩余预算限制，稀疏或并发增长文件不能触发无界分配。恢复开始时锚定可信事务目录句柄，每次读取控制文件前后都复核目录身份，拒绝 rename、junction 或替换目录。恢复必须先把全部 journal 条目和九路径快照完成结构、大小与摘要校验并形成内存计划，随后缓存全部 canonical 路径的恢复前状态；每项落盘前再次校验目标与父目录，后续项失败时按逆序回滚本轮已应用项，但回滚前必须 CAS 证明目标仍等于本轮安装结果，外部修改不得被覆盖并进入 reconciliation。末尾路径竞态或快照损坏不得留下静默的新旧混合合同。`committed` 持久化后先删除并同步 `prepared`，再清理 `.previous / .replacement`、同步 canonical 合同并最后删除事务目录；递归删除中断后最多留下只有 `committed` 的可清理事务，不能重新落入 rollback 分支。
 - 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`start-dev-stack.mjs`、`src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`response_stream.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

@@ -7252,13 +7243,11 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证：模型测试覆盖允许与拒绝类型，工具栏和两类右键菜单覆盖视频、单个拆分图标、角色动作及音频不展示，打开与提交工作流覆盖视频等不支持类型绕过入口时仍拒绝；后端表驱动测试覆盖全部现役图片素材 / 媒体类型与未知类型，锁定图片编辑端点失败关闭。
 - 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`ImageCanvasSelectedLayerToolbarView.tsx`、`ImageCanvasContextMenusView.tsx`、`useImageCanvasGenerationWorkflow.ts`、`useImageCanvasGenerationSubmissionWorkflow.ts`。

-
 - Canvas 目的区域证明以 Oxc symbol、调用实参、计数循环和所属 Canvas 身份为权威。大 classic script 的调用图保持整轮 visited；函数内 alias 重绑定必须按作用域和写入位置解析。格子坐标无法进一步化简时只可在 `COLS × ROWS × CELL` 唯一合同下建模为完整棋盘轴区间，已知调用参数或循环边界优先，越界调用继续失败关闭。
 - 动态坐标只新增一种受限可见性证明：未遮蔽的全局 `Math.min(currentCanvas.width|height - size, Math.max(0, dynamic))`。尺寸成员必须属于创建当前绘图 context 的 Canvas；其它 Canvas、被遮蔽的 `Math`、缺少上下界或普通未知动态坐标均不得作证。
 - autonomous parent wake 的瞬态重试预算耗尽后必须形成 durable reconciliation。lane 忙时先写 deferred recovery signal；获得同一 execution lane 与项目写锁后，重新读取原始 Runtime state、最新 task、cancel tombstone 和 DAG 进展。只有仍指向同一非终态根 Run 时才能以 CAS 追加 reconciliation task 并原子替换 state；manifest 已损坏时也不能让普通 hydrated writer 先阻断对账证据。
 - autonomous 测试夹具必须先建立带完整 parent/delegation identity 的 linked Pending child，再由正式启动路径写第一条 Running；禁止先启动无父身份再补 journal，也禁止把 terminal runId 复活成 Running。Completed-only 深验按任务逐项执行：Pending 任务不深验，但同一 manifest 中已 Completed 的美术任务仍必须验证其切片合同。

-
 - code-prototype 只有在本人当前 Run 已有 `status=ok` 的真实 mutation action、对应 mutation revision 已通过 `game.static_smoke`，且完整 `runtime.autonomous_completion` 完成门无阻塞时，才允许快车道返回确定性交付或把结构化计划全部标为 completed。verification gate 的 mutation revision 可能因保守失效策略在失败 patch 前推进，不能单独证明文件已修改。若 static smoke 已过但完成门仍报告素材、正式产物或其它诊断，计划尚有未完成步骤时用单一 in-progress 修复步骤替换首个非终态步骤，并把其余非终态步骤保持 pending；计划已全 completed 且仍有容量时才追加修复步骤。这样既保留 completed 单调历史，也不会因 steer 合并后超过 8 步而永久卡在 `runtime.plan_update`；不得重复返回同一交付计划直至耗尽 loop budget。
 - mutation ownership 以当前 run 的最后一条同工具调用和 Agent DB receipt 为联合权威；pending action 的 `plannedSteerCursor` 必须在 recent tool-call 与 receipt 中使用同一 fingerprint。结构化计划含 failed 步骤时 code-prototype 立即失败关闭；8 个 completed 步骤仍有 blocker 时不追加第 9 步，改走只允许读取、真实 mutation 与重新验证的外部 repair lane。
 - 当前根 Run 有 durable active child 时，即使 manifest 快照把全部 seed task 写成 Completed，DAG 仍保持 in-progress；任一 seed task 为 Failed 时继续立即失败关闭。所有项目修改在取得项目写锁后再次核对 ready child 的确定性 runId、父绑定、durable Running 状态和当前活跃根 Run；新根 Run 建立后旧 child 不得推进 revision 或修改文件。
@@ -7266,7 +7255,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 根 Supervisor 的 manifest completion gaps 只对 status 已为 Completed 的 seed task执行正式产物与 Canvas 深验；pending/running/failed 本身已经构成完成阻塞，禁止提前扫描后续波次。自动唤醒 200 次瞬态重试预算耗尽后必须写入 `needs-reconciliation`，不能静默返回并留下假运行状态。
 - parent wake 的 terminal reconciliation task 是 durable commit marker，state / queue / event / Agent DB audit 是可幂等重建投影；非瞬态 task journal 读取错误直接失败关闭。restart 只在 raw state 具有完整 Agent/task/Session/run/source/profile/binding/task 身份时修复其当前 run；state 缺失、损坏、空对象或关键身份为空时只取 journal 最后 logical run，完整有效的新 Run 阻止历史 marker 覆盖。event/audit 必须完整 payload 唯一匹配，同键冲突或重复失败关闭；旧 task 终态、Runtime 非 waiting 或新 Run 接管时，durable deferred signal 追加 resolved/superseded 后才返回 obsolete。

-
 - 升级恢复兼容 v1 决策，但不沿用旧责任链：读取时严格复核 v1 fingerprint，从根完成合同的有效任务恢复 `intentSummary`，并保留旧 fingerprint 只用于核对已有 route 身份。旧 `code-director` coverage/route 对当前单主完成门表现为 migration pending；当前 `code-prototype` 必须重新 `asset.list`，再原位写入自己的 coverage/route。这样同一根 Run 可以继续，又不会把旧 Director 审计冒充成主 Agent 本人的完成证据。

 ## 2026-08-04 静态视觉状态流与可见证据收口
@@ -7754,6 +7742,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 失败结算的 `expectedDraftRevision` CAS、结算意图和公开投影必须在同一草稿锁边界内串行化；显式失败结算和生成流程内部错误都先持久化 `failure-settlement-pending` 或 `reconciliation-settlement-pending`，不能直接跨文件发布终态。
 - pending 恢复不依赖平台登录或 External API Key。恢复按当前权威草稿幂等补齐 generation 投影和 staging revision，再把私有 ledger 发布为 `failed` 或 `reconciliation-required`；公开投影已经存在时只完成账本，不重复增加草稿 revision。
 - 回归必须覆盖 pending ledger 写入后、公开草稿写入前，公开草稿写入后、staging revision 写入前，以及 staging revision 写入后、终态 ledger 写入前三种重启切点。
+
 ## 2026-08-23 AGC 本地资源与 External Editor 账号绑定分离

 - 权威边界：本地项目 ID、manifest asset、正式本地文件和内容摘要属于设备上的本地项目；`canvasProjectId / resourceId / assetObjectId / objectKey` 属于具体 External Editor 服务 principal。manifest 中现有远端字段继续保留生成来源，不再承担“当前账号可编辑句柄”，本轮不修改共享 manifest schema。
@@ -7792,6 +7781,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 严格图集崩溃收口：workflow 在严格图集调用前先持久化 `strictSpritesheetPending` 并冻结底层严格事务覆盖的九项旧合同身份；旧路径可精确冻结为缺失。Provider 完成结果先绑定原 retained stage ledger。恢复在同一项目锁内对账严格事务；只有新九项合同、规范图/背景图替换锚点与 retained spritesheet result 三者一致才补写 `completed`，旧九项合同才允许补偿。旧合同判定、写 `compensating`、恢复两项素材与登记、回读和清锚点必须在同一项目锁内，重启已有 `compensating` 也重新判定；第三种混合、漂移或 foreign result 状态进入 reconciliation。不能在主图集与四切片已整体提交后仍按两文件 rollback 制造混合包；若中断前阶段告警尚未进入 durable completed result，恢复结果追加“原阶段告警无法完整重放”的明确 warning，不静默清空。
 - Direct 对话恢复从新到旧扫描全部合法 User 回合，遇到较新已回答回合继续向前，不得丢失更早未回答回合。成功返回时 Rust 已先持久化 assistant，前端冗余 append 失败也不得重跑 Provider；普通错误终态的显式 append 失败后，恢复 claim 必须保持到 React fallback writer 对同一稳定 assistant messageId 的写入明确成功或失败，不能在 writer 尚在途时按旧 `/history` 快照重跑。fallback 成功后释放 claim；fallback 失败时跳过该 writer 的无界迟到重试并释放 claim，后续显式 `/history` 才可复用原稳定 `clientTurnId`。终态收敛后删除 claim，避免长会话无界增长。
 - 正式资源提交结算遵守同一顺序：阶段三 commit 成功后先持久化 `asset-commit-settlement-pending`，恢复器幂等补齐 `asset-durable-committed` 公开投影与 staging revision，再发布私有终态；公开投影已经存在时不得重复增加草稿 revision。恢复必须把私有回执与阶段三 commit ledger、transaction journal、manifest 资产和事件 payload 的完整身份绑定，任一错配都保留 pending 并失败关闭。回归同时覆盖三个 durable write cut，以及私有回执、commit ledger、journal 错配。
+
 ## 2026-08-24 AGC Direct 抠图语义工具

 - 决策：将 External v1 `/api/external/v1/editor/images/background-removals` 通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
@@ -7845,6 +7835,37 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 直连 Runtime 已取得 Developer Key 时，资源编辑的 `remote_credentials` 是该操作的完整身份边界；其中冻结平台快照为空表示 Developer 模式，禁止再从进程全局 GUI 登录态补回账号快照。平台账号模式仍只使用同一组凭据捕获的快照。
 - 回归覆盖 Direct 系统提示路径合同和 Developer Key / GUI 快照隔离；未触碰用户项目 `.agent` 锁、账本或凭据。

+## 2026-08-26 网站与客户端共享基础组件库
+
+- 决策：无业务 UI chrome 统一放入 `packages/shared/src/components`，通过 `@genarrative/shared/components` 导出；组件只接受 React props、原生 DOM props、短文案、图标节点和回调，不读取账号、钱包、请求客户端、store、Tauri API 或业务实体。
+- 样式边界：共享样式位于 `packages/shared/src/components/styles.css`，选择器使用 `.genarrative-ui-*` 前缀并消费 `packages/shared/src/theme.css` 的 `--platform-*` token。网站与客户端各自保留页面壳、路由、业务和玩法视觉，不导入网站总 CSS；账户 DTO 适配器只从 `@genarrative/shared/components/account` 单独导出，不进入通用组件 barrel。
+- 展示页：网站 `/components`（`/design-system` 兼容别名）展示所有公共组件的变体、状态、Token 和移动端布局，使用本地静态示例，不经过账号 Gate 或调用业务 API。
+
+## 2026-08-27 共享组件采用 shadcn open-code 渐进迁移
+
+- 决策：共享 Web UI 采用 shadcn 的源码归属项目模式，新增 canonical source 放入 `packages/shared/src/components/ui`，统一通过 `packages/shared/src/lib/utils.ts` 的 `cn` 与 CVA 组织变体；不引入 MUI / Ant Design 全量组件，也不一次性重写现有业务 common。
+- 首步：`Button`、`Modal`、`SegmentedTabs`、`Switch`、`Input`、`Textarea`、`Badge`、`Card` 已迁移到 `components/ui` canonical source，保留 `@genarrative/shared/components` 的旧 API 作为兼容适配；Button/Input/Badge 用 CVA，Dialog/Tabs/Switch 按需使用 Radix，Tailwind 4 继续消费现有 `--platform-*` token 与 `.genarrative-ui-*` 样式。原生 Select 暂不迁移。
+- 边界：网站与 Tauri WebView 可消费该 DOM 源码，移动端 React Native 不导入这套组件与 CSS；Radix primitive 仅在 Dialog、Tabs、Switch 等具体组件迁移时按需加入。
+
+## 2026-08-28 共享平台 chrome 与基础语义件继续扩展
+
+- 决策：无业务依赖的 `PlatformAsyncStatePanel`、`PlatformFilterToolbar`、`PlatformIconBadge`、`PlatformInfoBlock`、`PlatformNavigableListItem`、`PlatformRuntimeStatusToast`、`PlatformStatGrid` 实现统一收口到 `packages/shared/src/components`；`src/components/common` 仅保留兼容导出，展示页和部分实际业务页面开始直接消费共享 barrel。
+- 基础件：`components/ui` 新增语义 `Label`、原生 `Checkbox`、`Skeleton` 和语义 `Table` 组合件；继续沿用项目自有 shadcn open-code 源码，不引入额外运行时依赖。
+- 样式：筛选工具栏与可导航列表行的 hover/active/focus/disabled 反馈、移动端断点和独立宿主所需 chrome 放入共享样式；共享主题仍只消费 `--platform-*` token，不依赖网站总 CSS。
+- 验证：相关共享/兼容组件 10 个测试文件共 36 个断言、类型检查、编码检查、定向 ESLint、`git diff --check` 和生产构建均通过。
+
+## 2026-08-31 共享开关组件与业务页面直引迁移
+
+- 决策：新增 `packages/shared/src/components/PlatformToggleRow.tsx`，统一承接白底整行 checkbox / status 开关的语义、状态胶囊和禁用态；`src/components/common/PlatformToggleRow.tsx` 仅保留兼容导出，展示页改为直接从共享 barrel 引入。
+- 迁移：`Match3DResultView`、`PuzzleResultView`、`VisualNovelResultView`、`SquareHoleResultView`、`RpgCreationResultViewImpl`、`RpgCreationResultActionBar`、`RpgCreationAssetDebugPanel`、`CustomWorldCreationHub`、`BabyObjectMatchWorkspace`、`AccountModal`、`CreationAgentWorkspace` 直接消费共享 `Platform*` chrome，玩法专属资源 / 媒体 / 上传 / 弹窗组件继续留在业务层。
+- 验证：共享 PlatformToggleRow 定向测试、相关前端类型检查、编码检查和 `git diff --check` 通过；未改变业务行为或后端契约。
+
+## 2026-08-31 第二批共享组件直引
+
+- 决策：新增 `PlatformBackActionButton` canonical 返回动作组件，统一 compact / regular 尺寸、返回图标和 platform / editorDark surface；`src/components/common/PlatformBackActionButton.tsx` 仅保留兼容出口。
+- 迁移：`LoginScreen`、`BindPhoneScreen`、`CustomWorldEntityCatalog` 将已有共享 `Platform*` chrome 直接从 `@genarrative/shared/components` 引入；展示页新增返回动作示例并保留整行开关示例。
+- 边界：媒体、上传、资源换签、业务弹窗等带副作用组件继续留在网站业务层。
+
 ## 2026-08-28 AGC 自主构建放开编排约束

 - `autonomous-game-build` 中，manifest `dependencies` 只作为上下文，不阻塞 ready；代码、设计、美术、音频和发布任务允许并行启动，child 不依赖固定回执顺序或固定 run 身份才能推进。
@@ -16,6 +16,7 @@
 ## 开发中

 - 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
+- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
 - 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
 - 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
 - 对已明确退役且无现役调用方、公开契约、持久化迁移或活跃实例的对象，不写兼容实现、维持旧行为的测试、墓碑注释或墓碑文档。
@@ -0,0 +1,57 @@
+# 共享基础组件库与展示页
+
+更新时间：`2026-08-28`
+
+## 目标
+
+网站与 Tauri 客户端共享无业务依赖的基础 UI chrome，同时保留各自的页面布局、路由、账号/钱包业务和玩法视觉。共享层只接受 React props、原生 DOM props、短文案、图标节点和回调，不读取请求客户端、store、Tauri API 或业务实体。
+
+## 包边界
+
+组件位于 `packages/shared/src/components`，由 `@genarrative/shared` 根入口和 `@genarrative/shared/components` 子路径稳定导出。新增组件按 shadcn 的 open-code 方式归档在 `components/ui`，源码、变体和组合点归项目所有；`packages/shared/src/lib/utils.ts` 提供统一的 `cn` 工具。当前迁移阶段仍复用 `packages/shared/src/components/styles.css` 的 `.genarrative-ui-*` 选择器和 `packages/shared/src/theme.css` 的 `--platform-*` token，避免破坏既有平台视觉契约。
+
+已有账户 DTO 适配组件单独由 `@genarrative/shared/components/account` 导出；它们不进入本样式库的通用组件 barrel，也不从该入口转出。
+
+当前基础组件：
+
+- `Button`、`IconButton`
+- `TextField`、`SelectField`
+- `Subpanel`、`Modal`
+- `Status`、`EmptyState`、`Badge`
+- `ProgressBar`、`SegmentedTabs`、`Switch`
+- `Spinner`、`Divider`、`Label`、`Checkbox`、`Skeleton`
+- `Table`（含 `TableHeader`、`TableBody`、`TableRow`、`TableHead`、`TableCell`、`TableCaption`、`TableFooter`）
+
+平台 chrome 组件（同样从 `@genarrative/shared/components` 导出）：
+
+- `PlatformActionButton`、`PlatformIconButton`、`PlatformPillBadge`
+- `PlatformStatusMessage`、`PlatformEmptyState`、`PlatformTextField`
+- `PlatformProgressBar`、`PlatformSegmentedTabs`、`PlatformFieldLabel`、`PlatformSubpanel`
+- `PlatformAsyncStatePanel`、`PlatformFilterToolbar`、`PlatformIconBadge`、`PlatformRuntimeStatusToast`
+- `PlatformInfoBlock`、`PlatformNavigableListItem`、`PlatformStatGrid`
+- `PlatformToggleRow`（整行 checkbox / 状态开关）
+- `PlatformBackActionButton`（白底结果页返回动作）
+
+迁移约定：`Button`、`Modal`、`SegmentedTabs`、`Switch`、`Input`、`Textarea`、`Badge`、`Card` 的 canonical source 位于 `packages/shared/src/components/ui`，旧的 `@genarrative/shared/components` API 作为兼容适配层继续保留。`Button`、`Input`、`Badge` 使用 CVA，Dialog/Tabs/Switch 使用按需 Radix primitive；原生 `SelectField` 暂不迁移，避免破坏现有 `<option>` 与表单事件合同。后续组件按使用面逐个迁移。
+
+2026-08-28 平台 chrome 的无业务依赖组件继续完成实现收口：新增 `PlatformAsyncStatePanel`、`PlatformFilterToolbar`、`PlatformIconBadge`、`PlatformInfoBlock`、`PlatformNavigableListItem`、`PlatformRuntimeStatusToast`、`PlatformStatGrid`。这些组件的实现统一位于 `packages/shared/src/components`；`src/components/common` 中同名文件仅保留兼容导出，因此现有业务页面无需一次性改写导入路径，实际渲染已复用共享包实现。带 API、store、编辑器或素材解析副作用的组件仍留在业务层，后续按同一边界逐项评估。
+
+2026-08-31 继续迁移：`PlatformToggleRow` 已收口到共享包，保留 `src/components/common/PlatformToggleRow.tsx` 兼容出口；`Match3DResultView`、`PuzzleResultView`、`VisualNovelResultView`、`SquareHoleResultView`、`RpgCreationResultViewImpl`、`RpgCreationResultActionBar`、`RpgCreationAssetDebugPanel`、`CustomWorldCreationHub`、`BabyObjectMatchWorkspace`、`AccountModal` 和 `CreationAgentWorkspace` 已将共享 chrome 组件改为直接从 `@genarrative/shared/components` 引入。玩法专属的媒体、上传、编辑器、弹窗和资源状态组件仍保留在业务 common 层。
+
+2026-08-31 第二批：新增 `PlatformBackActionButton` canonical 实现及兼容出口，展示页加入 compact / regular 两种返回动作示例；`LoginScreen`、`BindPhoneScreen`、`CustomWorldEntityCatalog` 继续将共享 chrome 直引到 `@genarrative/shared/components`。媒体、上传、资源换签与业务弹窗仍不迁移。
+
+同时提供 `Platform*` 别名，便于从现有平台组件命名迁移；别名不携带平台业务语义。
+
+Web 宿主需要显式启用 Tailwind 4，并引入 `@genarrative/shared/styles.css` 和 `@genarrative/shared/theme.css`；Tauri WebView 与网站共用这套源码，移动端 React Native 不消费 DOM/CSS 组件。筛选工具栏所需的 `platform-category-*` chrome 样式也已放入共享样式文件，独立宿主无需依赖网站 `src/index.css`。组件库不提供页面壳或业务流程。`components.json` 只用于 shadcn CLI 定位源码，不允许覆盖现有业务组件。
+
+## 展示页
+
+网站 `/components`（兼容别名 `/design-system`）是共享组件展示页，不经过账号 Gate。页面按“基础组件”“平台通用组件”“Token”“状态”分区，覆盖公共组件的主要变体、交互态、筛选/标签/媒体/上传/异步状态/指标列表等平台 chrome 和移动端布局；展示数据均为本地静态示例，不调用 API。平台组件分区中的筛选按示例素材状态过滤结果，排序按最近使用或名称重排结果，并在筛选按钮、排序按钮和独立筛选面板之间保持同一份本地状态。展示页可用于网站与客户端接入前的视觉回归和人工验收。平台通用组件示例优先从 `@genarrative/shared/components` 直接导入，业务代码仍可通过 `src/components/common` 的兼容出口渐进迁移；展示页只接入不读取请求、store 或业务实体的 chrome，不把账号、发布和编辑器业务流程嵌入展示页。
+
+## 验收
+
+- 组件具备原生语义、键盘焦点、禁用态和可访问名称。
+- 按钮、图标按钮、分段标签和开关具备明确按压态；展示页中的可操作示例在点击后提供可见状态反馈，加载态按钮保持禁用。
+- `Modal` 支持 ESC、遮罩点击、可选 portal 和移动端底部面板布局。
+- 组件样式不依赖网站总 CSS；Tauri 只需共享主题、共享组件样式和自己的壳层样式。
+- 修改后运行 `npm run typecheck`、`npm run check:encoding`、`npm run test -- src/routing/activeAppRoutes.test.ts` 与 `git diff --check`。
@@ -169,6 +169,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创

 - Windows AppData 安全迁移：首次创建客户端 AppData 时必须以进程 `TokenUser` SID 显式设置 owner，并写入当前用户私有 DACL，不能把可能为 Administrators 的 `TokenOwner` 当作用户身份。发现历史目录 owner 不属于当前 `TokenUser` 时，不在原目录上放宽权限，而是拒绝 reparse point / junction / symlink 后，将旧目录原子重命名到同级唯一 `.owner-mismatch-backup-*` 备份，再新建并验证当前用户 owner 与私有 DACL；迁移或备份失败必须失败关闭，不覆盖旧配置。
 - Windows 私有文件初始化：父目录已归当前 `TokenUser` 后，新建 `.agent/.manifest.json.lock`、`agent-runner.lock`、endpoint 临时文件、project-owner 诊断临时文件与 real-E2E 私有文件的 owner 仍可能采用 token 默认 owner `Administrators`。manifest 固定锁和 Runner 固定 stale lock 只有在 Windows 不共享独占句柄已取得、且句柄确认普通文件、非 reparse point、链接数为一时才允许初始化或修复为当前 `TokenUser`，随后必须再次复核句柄并按既有 owner/DACL 门禁验证；其它临时文件只允许在本进程 `create_new` 成功且仍持有同一独占句柄时初始化 `TokenUser` owner / DACL，再写入、原子安装并严格复核，初始化失败必须清理刚创建的文件。既有 durable endpoint / diagnostic 读取不得自动接管；活锁不得截断，只有 sharing / lock violation `32/33` 表示占用，access denied 等其它错误立即返回。父进程观察到 Runner 子进程退出后立即返回错误，不等待完整 30 秒 deadline。
+- Windows ACL 提权边界：自定义 `--config-dir` 的启动前置检查必须把 `managed / user-selected` scope 一并传入提权子进程，不能依赖父进程内存中的配置目录覆盖；native picker 返回的文件或项目目录在同一进程登记短时授权，后续导入 / 项目操作只对登记路径（目录可覆盖其后代）允许 `user-selected` 自动提权，直接伪造 IPC 绝对路径不得获得该能力。项目文件列表 / 索引递归逐项拒绝 symlink 与 Windows reparse point，并在 metadata / read 前先完成 ACL 准备。
 - 启动恢复和续跑边界：本条取代上一条中“只有 accepted 才可恢复”的窄口径。若进程在 Supervisor 用户消息已持久、accepted 未持久之间崩溃，只读 preflight 可以把该 `preparing` 识别为可恢复，但不改写 task/conversation；真实 resume 持有 Agent 锁后必须先幂等补写 accepted，再提升为 `pending / queued`。用户消息或 accepted conversation 已落盘而辅助审计失败时，以 conversation 为公开真相继续入队，不留下“已接收但永不执行”的任务；根终态首次公开写入的瞬时失败必须在终态投影后用相同 message ID 重试。receipt / isolated-join 等带 parent 的 Supervisor continuation 不再另写 Session 终态，只保留单一后端公开事件；`runtime-task-*` 与 `runtime-public-status-*` 共享同 run 的不透明关联摘要，秒级时间戳下多个连续任务必须按实际 run 对应的 `user -> accepted -> terminal` 顺序交错展示。
 - ready-task 启动活性：`background_task.queued`、`autonomous_ready_task.scheduled`、Runner heartbeat 或执行锁已移交都不等于 child 已启动。实际持有执行权的 Runner 必须在释放项目写锁后同步写入 child 的 running task、`turn.started` 与 started journal，再把已启动 state 和 per-Agent 执行锁交给已确认开始轮询的独立 execution worker；同步启动或 worker 接管失败时，要在仍持有执行锁期间依次把 child 和 manifest Graph 节点明确落为 failed，再释放锁并让 parent 收到调度错误。`autonomous_ready_task.scheduled` 只作诊断审计，其写入失败不能阻断 durable child 启动；external client 只 wake Runner，不在客户端抢占执行。Supervisor 进度卡通过 durable `startedAt`（旧 Run 从完整 task journal 恢复，最新 task-record fallback 保持 0）显示真实持续时间，并以父 Run 与当前关联专业 Agent 的最大事件时间计算运行态活跃度：运行超过 5 分钟无新事件时显示“运行中 · 疑似停滞”和静默时长；等待用户、等待确认、Provider retry、视觉资产、进程会话、pausing 与 paused 不误报。父 Run terminal 后，持续时间冻结在父 Run 自身最后活动，不随 child 晚到收口事件增长。消息时间统一校验为 JavaScript 可表示的 Date；越界值显示“时间未知”且不写无效 `datetime`。实时回复只显示 response stream 自己的 `updatedAt`，缺失时同样显示“时间未知”，不能借用其它 Runtime 活动时间或随前端时钟漂移。该提示只提供可观测性，不改变 Runtime/manifest 正式状态。
 - ready-task 对账取消续跑：未知工具结果仍停在 `needs-reconciliation` 且禁止自动重放；人工核对后显式取消原 child，保留 cancel tombstone，旧 child 和旧父 Run 按真实终态收口。若随后创建同 Session、同 Supervisor source、同有效任务语义的 continuation，新完成合同只对同时具有历史 `failed / needs-reconciliation`、最终 `cancelled` 和 durable tombstone 的 ready-task，把当前 manifest 对应 failed 节点恢复为 pending，并由 scheduler 创建全新 child Run。manifest 的读取、failed 筛选、每任务一次的 child journal 索引、证据重验和写回必须位于同一项目写锁域；较新的无 child 根 Run 只有在 durable journal 精确表明为旧 failed Graph 在进入调度前即失败时才能跨过，scheduler 自身失败必须阻断借用更老 tombstone。普通失败、无 tombstone、不同 source/Session/任务语义或证据冲突均保持失败关闭；不得复活旧 pending action、补造 observation 或把取消任务标成 completed。
@@ -555,7 +556,7 @@ game-project/
 - 阶段三的聚类已落在 `reconcileResourceCanvasLayout` 的 dependency 自动坐标派生步骤。它先按资源分类过滤 reference edge，并把 task-flow 按固定分类切成仅在同类 source / target 同时存在时有效的聚合超边；每个 section 再用精确边与 flow 临时节点建无向邻接表，以迭代遍历生成弱连通组。task-flow 只以“流节点 -> 成员”的线性成员关联参与布局，绝不展开 source × target 资源组合，不绘制 SVG，也不把搜索后的 visible set 用作输入。`dependencyDepth` 仍唯一决定横向业务层级；相关簇按 `minDependencyDepth + minStableResourceId` 排序，孤立集合置于所有相关簇之后，簇间使用单一布局常量留白。每个相关簇内先按稳定资源 ID 建同层初始序，再做固定两轮左至右 / 右至左的中位数扫描：精确引用读取相邻层的上下游 rank，task-flow 读取另一端成员 rank 的中位数，平局按稳定资源 ID 收口。dependency 自动位置使用 `48px` 列间走线区和 `40px` 行间走线区；每个相关簇以最大层行数确定高度，资源较少的层增加确定性半差偏移而在簇内居中，菱形 / 分叉两侧因此保持均衡。type 模式仍使用原 `16px` 行列间距。跨分类 read model 关系不进入前端聚类、边界偏置或拓扑签名，但 Rust 深度与原始图真相不改。显示坐标必须遵守前后端共享的 `0..=1_000_000` 上限；超深依赖在最后合法列确定性饱和，保留原始 `dependencyDepth`，同列资源继续按稳定顺序纵向避让。若任一自动 `x / y` 无法在合法域内落槽，协调必须在 IPC 前失败关闭，不持续提交必然被 Rust 拒绝的坐标。算法保持 `O(V + E)` 图遍历，加固定轮数的层内稳定排序和现有有界占用索引；4096 资源不允许全量配对。旧的 `manuallyPlaced=true` 坐标先占位并原样保留，聚类只派生自动坐标；同类型拓扑身份签名只记录有界的资源 ID 端点 / 成员，以便深度未变但邻接变化时触发重派生。图边、cluster ID 和签名都不写 sidecar。
 - 中间主视窗提供 `resource-overview / asset-canvas / resource-editor / run` 四种状态。2026-08-10 起普通用户“新增资源”显示为禁用态且处理函数拒绝 create；所有现役资源从聚焦态“编辑资源”进入非破坏性派生。静态图片继续进入 refine 素材创作无限画布，SVG、视频、音频、文档/代码、Agent 回执和项目版本进入统一资源编辑壳并按能力分流；底层 create 合同仅保留兼容。编辑面板只替换中央区域，不覆盖右侧 Supervisor 或底部 Agent。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源总览只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执、已导入附件和已完成任务明确登记的产物派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，未完成任务或未在 `artifacts` 中登记的任意本地音频也不冒充正式资源。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源总览卡片拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供通用工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态。2026-08-26 视觉验收修正：资源总览初次适配与复位最多以 `1.5` 倍缩放卡片，避免把低尺寸卡片位图插值放大成糊图；用户主动缩放仍沿用通用画布倍率。美术资源聚焦态改为视口级大预览，保留原始资源读取与元数据，不生成第二份缩略图，图片 / 视频预览按弹窗可用高度展示并允许正文滚动。该资源总览边界不限制后续素材创作无限画布内的图片图层移动/缩放、生成和正式回写。
+- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源总览卡片拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供通用工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态。2026-08-30 视觉验收修正：资源总览所有栏目初次适配与复位最多以 `1.5` 倍缩放卡片，避免单个低尺寸卡片被插值放大成糊图；用户主动缩放仍沿用通用画布倍率，并按“排序模式 + 栏目”保留当前会话内的平移和缩放。美术资源聚焦态改为视口级大预览，保留原始资源读取与元数据，不生成第二份缩略图，图片 / 视频预览按弹窗可用高度展示并允许正文滚动。该资源总览边界不限制后续素材创作无限画布内的图片图层移动/缩放、生成和正式回写。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并保留素材信息和数值微调面板；两个面板保持原有 `156px` 最小高度，没有真实数据时只让正文为空，不渲染预设字段、默认数值、未载入控件或自然语言功能占位，也不随空内容收缩。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；参数调整首版仍只保留本地 UI 草稿，不修改代码或 manifest。preview server 对 UTF-8 HTML 响应注入固定同源尺寸桥脚本；注入点通过真实 HTML tokenizer 边界定位，保守处理注释异常结束、DOCTYPE 引号、script escaped / double-escaped、raw-text、template、plaintext、foreign content 与重复 `src`，并支持省略 `</body>` / `</html>`。桥以 `ResizeObserver` 观察 `documentElement / body` 根布局，结合页面 load、窗口 resize 与字体就绪重新测量；页面可见时另以 `500ms` 低频兜底探测至多 `512` 个元素的实际边界，探测截断时保留 body / scroll 上界，并按连续测量排除随 viewport 同步变化的 `100vh / 100% / bottom / right` 自反馈。相同尺寸元组去重后才以固定版本 `postMessage` 上报，不订阅整页 `MutationObserver`。宿主同时校验消息 origin 和 `event.source`，以实际内容宽高与当前容器宽高计算不超过 `1` 的等比缩放；首次适配后仍接受内容宽高的真实变化，但仅 viewport 回灌或重复内容尺寸不更新 React 状态。容器 resize 后回到原生视口重新测量；放得下时保持 `1:1`，超出时完整缩小并居中，iframe 禁止横纵滚动条，不能以 `overflow: hidden` 直接裁掉超出内容。非 UTF-8 HTML 原样返回，不因适配桥破坏已有预览。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
@@ -3,7 +3,7 @@
 - 日期：2026-08-10
 - 适用范围：AI 游戏创作独立 App、Project Supervisor、Agent Runtime、本地项目策划 sidecar 与后续完整构建准入

-> 当前口径（2026-08-25）：以本文件中标注的 D11 / 最新修订和当前 `apps/ai-game-creator-shell` 实现为准。D6～D9 等被明确标注为作废或被取代的段落仅保留推导背景，不得作为现行拓扑、入口或 Runtime 真相；产品入口与 DirectProject 总体口径见 `docs/README.md` 和 App 实施计划。
+> 当前口径（2026-08-30）：以本文件中标注的 D11 / 最新修订和当前 `apps/ai-game-creator-shell` 实现为准。D6～D9 等被明确标注为作废或被取代的段落仅保留推导背景，不得作为现行拓扑、入口或 Runtime 真相；产品入口与 DirectProject 总体口径见 `docs/README.md` 和 App 实施计划。

 ## 1. 背景与目标

@@ -180,7 +180,7 @@ D9/D10 描述的「manifest ready-task 调度器在 Supervisor 下游启动策
 | 构建引用 | `approvedGddRef {gddId, version, fingerprint}` |
 | 现有 design 组 UI 名 | `设计实现组`，替代原“策划 Agent”卡片名称 |
 | 新组件名 | `GDD 审批卡` |
-| 固定入口动作 | `直接开建`、`开始完整制作`、`批准并开建` |
+| 固定入口动作 | 当前客户端为 `做成游戏`：读取 `game/fast_gdd.md`，直接创建自动游戏工作区、导入参考附件并以固定建造指令启动 Direct Codex；不再回首页等待用户二次提交 |

 `approvalRequestId` 与 `responseId` 是两个不同的持久 ID：前者由 Runtime 在 GDD 提交前生成、进入不可变 GDD，一张审批卡终身不变；后者由 UI 在用户执行一次决定时生成，并在传输重试中复用。不得继续用含义不明的单个 `requestId` 同时承担两种职责。

@@ -278,7 +278,7 @@ flowchart TD
    SPLAN -->|"在自己的 runtime/session 上建 pending，向用户提问"| U
    SPLAN -->|"answersSha256 绑回 delivery，再发 continuation 委派<br/>（最多 3 轮，受 clarification_round 上限约束，见第 23.5 节）"| PLANAGENT
    PLANAGENT --> GDD["不可变 GDD + approve receipt"]
-    GDD -->|"用户动作：开始完整制作"| BUILD
+    GDD -->|"用户动作：做成游戏；读取并导入 game/fast_gdd.md"| BUILD["自动创建游戏工作区<br/>参考附件：fast_gdd.md<br/>固定建造指令"]
    U -.->|"直接开建"| BUILD
    BUILD --> DAG["现行 16 任务 DAG"]
    U --> CHAT
@@ -1517,7 +1517,8 @@ type PlanningBaselineInput =
 - 仅首页“做方案”新建项目提交 `standard + project-supervisor-plan`（2026-08-13 按 D11 更正，旧值 `project-supervisor-plan-chat` 作废）；“做游戏”和“做素材”保持 `autonomous-game-build` 直接开建。前端只提交 Supervisor 根 run 的身份，**不提交也不感知策划子 Agent**——后者由 Supervisor 在服务端通过 `agent.delegate` 派生，页面侧不得直接创建或引用它。
 - 项目页新建、打开既有项目和 Godot 导入不新增“进入立项策划”入口，保持现行构建/打开语义；只有已存在 planning sidecar 或 active plan lineage 的项目恢复原有策划链路。
 - 策划阶段聊天输入属于当前 run：有活跃决策卡/审批卡时，输入回到该卡片对应 action；无 active run 时才可创建新的 plan continuation。
- approved 后显示“开始完整制作”；“批准并开建”只是先审批、后开建的快捷交互，不合并后端命令或 durable 记录。
+- approved 后显示“做成游戏”。点击后读取当前有效的 `game/fast_gdd.md`，直接沿现有自动做游戏链路创建新的工作区、导入 `text/markdown` 参考附件，并以固定建造指令作为 `initialSupervisorMessage` 自动启动 Direct Codex；固定指令只说明 GDD 覆盖的栏目，不根据具体 GDD 内容生成总结。该动作不回首页等待二次提交，不把原项目的 `approvedGddRef` 复制到新项目。
+- 用户仍可在项目工作台继续补充需求；普通首页“做游戏”入口的手动提交行为保持不变。

 ### 18.2 GDD 审批卡

@@ -1529,7 +1530,7 @@ type PlanningBaselineInput =
 - command 进行中禁用重复点击；另一个窗口先决定后，当前卡刷新为 `already-decided`，不能覆盖。
 - `recoveryPending=true` 时显示可恢复状态，只允许重试同一 ID，不允许提交新版本或启动构建。
 - 待审版本的 receipt 已存在时隐藏对应 stale pending 卡；hydrate 只恢复精确 project/session/run/action identity。
- approved 后只在所有必需投影恢复完成时启用完整构建按钮。
+- approved 后只有在所有必需投影恢复完成时启用“做成游戏”；恢复态不提供该出口。

 决策卡继续复用现有用户输入卡，不新建平行提问系统。现有完整构建 design 组用户名称改为“设计实现组”，与新阶段“立项策划”区分；内部 Agent ID 不改。

@@ -1703,7 +1704,7 @@ receipt 永远压过 stale pending：一旦该版本存在有效 receipt，pendi
 | agent.db | 专用幂等 helper；same key conflict；日志达到普通容量、尾部截断与压缩后仍能补齐并保留决定记录 |
 | source/security | durable exact identity；三个 action tool（`file.read` / `file.list` / `plan.submit_gdd`）广告与执行；MCP 空且 webSearchEnabled=false；control functions 单列；tool-plan/batch/ledger/context/repair/completion 全部跳过 collaboration；plan retry 保留 source/profile；除 Runtime-owned submit 外的副作用工具拒绝 |
 | Prompt | **2026-08-13 按 D11 改写**：不新增 composition，Supervisor 根 run 沿用现役 supervisor composition、策划子 Agent 复用 `runtime` composition（见第 4.2 节）；`decision-checkpoint` 请求 kind 随 D10 作废（见第 5.1 节）。仍冻结：3 轮/单题/固定选项；回答后设计解释与 prototype item；平台事实；恢复摘要；direct-out 条件 |
-| frontend | 首页“做方案”目录提交与 Enter 自动创建均为 `standard + project-supervisor-plan`；“做游戏/做素材”均保持 `autonomous-game-build`；项目页新建/打开不首次注入 planning；stable approvalRequestId/responseId；busy；stale card；hydrate strict input/view；无目录空态；receipt 隐藏 stale pending；corrupt authority typed error；project open/reload/resume/submit/decision 刷新；recovery pending；批准并开建两命令顺序 |
+| frontend | 首页“做方案”目录提交与 Enter 自动创建均为 `standard + project-supervisor-plan`；“做游戏/做素材”均保持 `autonomous-game-build`；项目页新建/打开不首次注入 planning；stable approvalRequestId/responseId；busy；stale card；hydrate strict input/view；无目录空态；receipt 隐藏 stale pending；corrupt authority typed error；project open/reload/resume/submit/decision 刷新；recovery pending；批准 GDD 后“做成游戏”直接创建自动工作区、导入 `fast_gdd.md` 并自动启动 Direct Codex；重复点击不重复创建；普通首页链路不回归 |
 | M2 integration | explicit approved/direct mode；锁内重验 receipt；ref 贯穿 task/run/completion/context；无 ref 非回归；恢复不换稿 |

 关键强杀点逐项覆盖：
@@ -1994,7 +1995,7 @@ M0 完成不表示完整策划闭环已经上线。`M1A-1`～`M1A-4`、`M1B-1`
 | `M1C-2b` | 澄清中转接线、轮次派生、预算注入 | `M1C-2a` | **实现与本包门禁已完成并已快进合回 `feat/five_min_design`**：首 child 的 revision 1 session、`NeedsUserInput → awaiting_user_input`、回答绑定后 continuation 的确定性 session 投影、审批后 `revise/reject` 用户修订谱系及 Provider 活跃时间 usage fact/fold 已接线；末次 `plan.submit_gdd` usage 在 receipt/session successor 落盘且 standalone/v4 anchors 精确消费后于同一项目锁内折叠，真实 receipt 回归证明累计值恰好推进一次，重复审批与 recovery reconcile 不二次推进。`planning_clarification_*` **13 passed / 0 failed**（M1C-2c 语义回归另见本包），另有 static deliveries 44、planning storage 13、planning submit 53、Provider usage 4、末次 usage receipt 1、barrier detail 3 条定向回归通过；格式、offline all-targets、编码与 diff 门禁通过。锁序承诺只适用于 **M1C-2b 新增的 planning 澄清写投影路径**；`main_loop` 既有通用 completion blocker 的 execution→project 路径不在本包。第 4 轮信封在正常路径不可达：`agent.delegate` 已在工具边界按血缘上限硬拒并返回 failed observation；coordinator 的超三轮 reconciliation 仅用于损坏血缘纵深防御。审批 UI、hydrate、构建准入和下游完整构建不在本包范围 |
 | `M1C-2c` | 决策卡 A/B 语义（第 23.9 节，2026-08-18 实现完成并合回）：选项 → 台账映射改为 A/B 均 `confirmed/user_option`、信封 label 形状校验、planning role brief 与 Supervisor playbook/final-reply 文案（B 必须是真实岔路、第 3 项恒定且 description 须给出可执行验证方式、改口转述规则、提问纪律） | `M1C-2b` | **实现与门禁完成，已由 `6e4bd9703` 合回 `feat/five_min_design`**：Runtime 已实现 A/B/固定第三项校验、B 不再生成 `default_pending`、`answerSummary` 逐字保真；非法 C/缺项 fail-closed，A/B/自由填写回归已通过。`planning_clarification_*` 13、`project_planning` prompt 5、`planning_submit` 定向回归、prompt bundle、格式、编码、diff、offline all-targets 均通过；不含 M1D-1 前端、hydrate、构建准入或下游完整构建 |
 | `M1D-1` | 前端 hydrate 与 GDD 审批卡；决策卡按第 23.9 节实现（label 动态渲染、默认焦点 A、Other 槽不变） | `M1C-2b` | **已完成并合入 `feat/five_min_design`（落地 `0052a80da`，其后 ESLint 修正 `5b11a0530`）**：新增严格 `{projectPath}` hydrate command、`plan-gdd-state-view.v1` Rust read model、审批卡与独立 GDD 正文详情弹层；页面只消费 hydrate，决定 responseId 按审批请求/动作复用，`recoveryPending` 仅提供恢复重试；审批前置 pending 与错绑 session 继续 fail-closed。 |
-| `M1D-2` | 入口分流与阶段进度 | `M1D-1` | **2026-08-19 更正 `bf2185fba` 的错误入口映射**：仅首页“做方案”新项目以 `standard + project-supervisor-plan` 启动；“做游戏/做素材”保持 `autonomous-game-build`，不再展示额外“直接开建”按钮；项目页新建、打开和 Godot 导入不新增策划入口，仅恢复已有 planning lineage。阶段进度显示轮次 x/3、当前版本和状态徽章；实际项目总控页面挂载 hydrate/审批卡，并将 `project-planning` / 设计组展示名收口。未接 M2 approved-GDD 构建绑定或完整构建按钮。 |
+| `M1D-2` | 入口分流与阶段进度 | `M1D-1` | **2026-08-19 更正 `bf2185fba` 的错误入口映射**：仅首页“做方案”新项目以 `standard + project-supervisor-plan` 启动；“做游戏/做素材”保持 `autonomous-game-build`，不再展示额外“直接开建”按钮；项目页新建、打开和 Godot 导入不新增策划入口，仅恢复已有 planning lineage。阶段进度显示轮次 x/3、当前版本和状态徽章；实际项目总控页面挂载 hydrate/审批卡，并将 `project-planning` / 设计组展示名收口。**2026-08-30 变更：批准 GDD 后的“做成游戏”直接创建自动工作区、导入 `game/fast_gdd.md` 并自动启动 Direct Codex；仍未接入正式 `approvedGddRef` 构建绑定。** |
 | `M1E` | 端到端与故障注入收口 | `M1D-2` | **已完成**：planning 覆盖审计与 submit 拒绝上限收口完成。`PLAN_INVALID_REQUEST` / Provider input 或候选 GDD 的 `PLAN_SIZE_LIMIT` 每 child run 最多 5 次 rejected observation，第 5 次在 observation durable 后终态失败；counter durable，重启不清零。若在第五条 rejected observation 落盘与终态失败之间崩溃，恢复入口会按 durable counter 直接终态失败，不请求第六次 Provider tool-plan。既有不可变 GDD/receipt 的超限读取及 lineage 版本已耗尽均改走 reconciliation，不误耗 Provider 重试额度。第 21 节已存在的三轮、续跑、receipt/replay、投影恢复及 hydrate 回归复核通过；不为“拼接已有单测”新增脆弱大 E2E。 |

 **2026-08-18 M1D 审查修复快照**：对 `14c00017c..bf2185fba` 做规格对照审查后，修复三条决定链路缺陷并补齐回归。① `decidePlanGdd` 的失败分支原来不 hydrate，命中后端任一 `PLAN_STALE_APPROVAL` 分支后卡片会停在已失效的 pending 身份上、`recoveryPending` 永不翻真导致「重试恢复」入口不渲染，现已按第 18.3 节在失败分支同样重灌（顺序钉死：`hydratePlanGddState` 入口会清空错误，必须先 hydrate 再写决定错误）。② responseId 复用键原为 `approvalRequestId:action`，不含 comment，违反第 13.2 节「改变 action/comment 必须换新 responseId」，现改为比对 `{action, comment}` 完整意图，判据方向为宁可多换不可少换。③ 第 18.2 节「`recoveryPending` 时不允许提交决定」原来只作用于三个触发按钮，已打开的评论弹层仍可提交，现已同门控并保留用户已输入内容。回归位于 `tests/appSurface/plan-gdd.suite.ts`，三条均经变异验证（逆转对应修复即变红）；`appSurface.test.ts` 381 passed，`agc:typecheck`、ESLint、编码检查通过。其中锁错误回传绝对路径、阶段进度轮次差一格与 design 组展示名收口三条已于同日补修（见 decision-log 同日两条）；仅 hydrate 身份校验与落盘投影修复的顺序一条单列后续，未并入。
@@ -0,0 +1,216 @@
+# 【技术说明】DirectProject 未消费用户上传权威文档
+
+- 首次记录：2026-08-30
+- 问题类型：DirectProject 上下文消费缺陷 / 可审计性缺陷
+- 影响范围：用户上传文档并在正文中明确指定其为本次建造依据的“做游戏”链路
+- 当前状态：待排期，本文只用于提 Issue，暂不修复
+
+## 0. Issue 摘要
+
+当用户在正文中明确说明“我上传了一份 GDD，里面包含某些具体内容，请按照这份 GDD 做游戏”时，做游戏 Agent 没有可靠地把该附件当作本轮权威规格来检索、读取和消费。
+
+这不是“上传附件功能失败”：附件已经成功复制到新项目并登记。问题在于，DirectProject 只收到用户正文和项目路径，没有收到“用户上传了哪些附件、附件的真实项目路径、哪个附件被正文指认为权威参考”这类一等上下文；Agent 只能自行猜测并搜索项目文件。
+
+当前实现虽然存在条件性的 native 文件检索路径，但该路径既不是稳定的应用层契约，也没有对应的 Direct 读取审计记录。因此一次 run 结束后无法可靠回答：Agent 是否发现了附件、是否读取了附件、读取结果是否进入了后续设计和代码决策。
+
+## 1. 预期行为
+
+本 Issue 讨论的预期行为有一个重要前提：**不是所有上传文档都自动视为 GDD，也不是所有附件都必须被读取。**
+
+只有当用户在正文或交互中明确表达类似以下意图时，相关文档才应被视为本轮权威参考：
+
+> 我上传了一份 GDD，里面有探测艇、脉冲射击、敌方弹幕、模块选择和棱镜母体，请按照这份 GDD 做游戏。
+
+在这一前提下，Agent 应能够：
+
+1. 知道本轮存在用户上传的参考文档；
+2. 找到该文档在当前项目中的真实路径；
+3. 读取文档内容；
+4. 将文档内容用于后续游戏设计、代码和资源决策；
+5. 在可共享、可复核的审计信息中留下足以判断上述行为是否发生的记录。
+
+用户手写 GDD、通过外部功能生成后导入的 GDD、普通上传的 GDD，以及“做成游戏”入口带入的 GDD，在这里都属于同一个用户意图场景。是否来自“做方案”审批链路不是必要前提。
+
+## 2. 实际现象
+
+在 `gameagent-77b5aa31` 这次 2026-08-30 的 Direct run 中：
+
+- 用户正文明确要求先阅读附件中的 `fast_gdd.md`，并以其作为主要依据；
+- 文件成功复制到新项目：
+
+  ```text
+  assets/uploads/upload-1788083777445-fast_gdd.md
+  ```
+
+- 原策划项目文件与上传副本大小均为 `7944` 字节，SHA-256 一致，说明复制没有损坏；
+- 最终游戏却生成了《星光收集者》：星星收集、荆棘碰撞、左右移动、生命值；
+- 原 GDD 的核心实体和循环（探测艇、脉冲射击、敌人、弹幕、模块、风险岔路、棱镜母体）没有体现在最终游戏中；
+- 最终美术生成 prompt 只有“轻量、明快、暖色纸张质感背景、可爱的主角、可收集物、障碍物和简洁 HUD”等泛化描述；
+- 浏览器验收的 `expectedText` 为空，没有对 GDD 语义做断言。
+
+因此最终产物表现为一个内部自洽、但与用户指定 GDD 不同类型的通用收集类小游戏。
+
+## 3. 代码层证据
+
+### 3.1 附件不进入 Direct turn 的结构化输入
+
+首页正文和附件在前端被分开处理；附件节点不会进入正文 prompt，而是作为单独的附件集合保存。
+
+[richTextToPrompt.tsx](../../apps/ai-game-creator-shell/src/view/home/components/RichInputArea/richTextToPrompt.tsx:21)
+
+进入项目工作台后，`ProjectSupervisor` 只收到项目路径、manifest、初始消息和创作类型，没有附件字段。
+
+[WorkspaceLauncher.tsx](../../apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx:335)
+
+[model.ts](../../apps/ai-game-creator-shell/src/features/app-shell/model.ts:29)
+
+Direct Codex 调用的输入也只有：
+
+```ts
+{
+  projectPath,
+  prompt,
+  clientTurnId,
+  creationType
+}
+```
+
+[App.tsx](../../apps/ai-game-creator-shell/src/App.tsx:5484)
+
+其中没有附件列表、附件路径、附件 hash 或附件正文。
+
+### 3.2 上传后路径被重写，Agent 不会自动得到真实路径
+
+上传实现会把文件写入 `assets/uploads/upload-<timestamp>-<原文件名>`，例如 `fast_gdd.md` 会变成 `upload-...-fast_gdd.md`。
+
+[assets.rs](../../apps/ai-game-creator-shell/src-tauri/src/assets.rs:460)
+
+上传结果会写入项目的 `.agent/manifest.json` 和 `.agent/agent.db`，但这些是项目持久化产物，不是自动注入到 Direct LLM 请求的上下文；`.agent` 还是 Direct 的控制面边界，不能作为普通项目文档让 Agent 读取。
+
+### 3.3 代码中存在条件性的主动检索路径，但不是稳定契约
+
+DirectProject 的 app-server 使用项目根作为 `cwd`，并在可用配置下保留 native shell / 命令能力，因此 Agent 理论上可以：
+
+```text
+搜索 fast_gdd
+→ 找到 assets/uploads/upload-...-fast_gdd.md
+→ 用 native 命令读取正文
+```
+
+[codex_app_server.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs:1482)
+
+[codex_app_server.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs:1160)
+
+但这条路径有三个问题：
+
+- 需要 Agent 自己判断“这份附件值得检索”，应用没有把附件关系告诉它；
+- `agc_list_project_files` 只能返回路径、大小和类型，不返回 Markdown 正文；
+- DirectProject 没有接入旧 Agent Runtime 的 `file.read` / `project.search` 工具目录，读取能力取决于 Direct app-server 的 native 工具配置。
+
+[direct_tools_mcp.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs:214)
+
+[agent_native_tools.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/agent_native_tools.rs:1349)
+
+因此当前代码不能称为“附件已可靠进入 Agent 上下文”，只能称为“Agent 在部分配置下可能自行发现项目文件”。
+
+## 4. 持久化与取证现状
+
+### 4.1 这次 Direct run 没有持久化读取记录
+
+`gameagent-77b5aa31/.agent/agent.db` 共 12 条记录，类型只有：
+
+```text
+project.init                  1
+asset.register                5
+canvas.asset_generate         3
+conversation.message         3
+```
+
+其中没有：
+
+```text
+file.read
+file.list
+project.search
+command.exec
+agent.runtime.tool_observation
+agent.runtime.action_receipt
+```
+
+这能证明上传、资源生成、游戏入口写入和对话消息被记录，但不能证明 Direct app-server 没有执行过 native 文件读取。
+
+### 4.2 Direct app-server 的 native read 不在当前 Agent DB 审计范围内
+
+Direct app-server 使用 ephemeral thread。stdout 中的 `item/started`、`item/completed`、`commandExecution` 等事件只在运行期间被解析成有限的活动状态，再通过 Tauri event 发给前端；当前实现没有把 native 命令、读取路径、读取结果或读取 hash 追加到项目 `agent.db`。
+
+[codex_app_server.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs:883)
+
+[codex_app_server.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs:2496)
+
+相对地，旧 Agent Runtime 的 `file.read` 会写入 `agent.runtime.action_receipt` 和 `agent.runtime.tool_observation`，因此旧路径可以审计到读取了哪个文件。
+
+[main_loop.rs](../../apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs:3347)
+
+这说明问题不是项目完全没有持久化能力，而是 DirectProject 的文件读取路径绕过了现有可审计工具链。
+
+## 5. 问题定性
+
+本 Issue 应定性为：
+
+> 当用户明确把某个上传文档指定为本轮游戏制作的权威参考时，DirectProject 没有可靠地把“用户—附件—当前任务”的关系传给 Agent，也没有让文档发现、读取和后续消费形成可观察的工作流证据。结果是 Agent 可以从泛化的游戏目标出发完成一个可运行产物，却不一定消费用户指定的文档规格。
+
+这属于用户意图和 Agent 上下文消费之间的契约缺失，不属于 GDD 审批状态传递错误，也不属于附件复制损坏。
+
+## 6. 明确排除的归因与修复方向
+
+以下内容不应作为本问题的主要根因，也不应直接作为本 Issue 的修复目标：
+
+### 6.1 不把 `approvedGddRef` / approval receipt 缺失视为根因
+
+用户手写 GDD、外部生成后导入的 GDD、普通文件上传的 GDD，都不一定存在 `approvedGddRef` 或审批 receipt，但只要用户在 prompt 中明确指定“按照这份 GDD 做游戏”，Agent 就应该能够正确消费它。
+
+因此，缺失审批状态绑定不能解释这类通用失败。
+
+### 6.2 不把所有上传文档强制当成 GDD
+
+用户上传的文件可能是图片、素材说明、参考资料、README、代码片段或与游戏无关的文档。不能因为文件被上传，就默认它是策划案或本轮的权威规格。
+
+只有用户明确建立“这份文档用于本轮任务”的关系时，才进入本文讨论的语义范围。
+
+### 6.3 不采用“把所有上传文档正文直接拼进 prompt”作为通用修复
+
+附件可能很大、可能是二进制、可能包含不可信内容，也可能只是可选参考。把所有上传文件正文无条件塞入 prompt 会混淆普通附件、参考资料和权威任务规格，也改变当前附件模型的边界。
+
+本文不要求把上传文件正文统一注入 prompt。
+
+### 6.4 不采用“所有附件必须先读取，否则一律阻断”作为通用硬门禁
+
+对于用户没有要求使用的附件，系统不应强制 Agent 读取；对于非文本附件，也不能套用 Markdown 文本读取规则。
+
+本文关注的是用户明确指定文档为权威参考时的消费缺失，不要求把所有附件都改造成强制读取工作流。
+
+## 7. Issue 验收口径
+
+本问题修复完成后，至少应能验证以下事实，但具体实现方式不在本文展开：
+
+- 用户明确指定某个上传文档为本轮任务依据时，Agent 能够发现并读取对应文档；
+- 用户未指定的普通附件不会被自动当成 GDD 或强制纳入任务；
+- Agent 是否发现、读取以及使用该文档，应能从可共享的 run 审计产物或等价的可审计证据中判断；
+- 同一语义在“做成游戏”、普通上传、外部生成后导入和用户手写文档等入口下不依赖审批 receipt 才成立；
+- 文档被读取后，至少有一种可验证方式能判断其关键内容是否进入了后续任务上下文，而不是只记录了文件存在。
+
+具体修复方案、上下文协议设计和持久化字段设计另行讨论，本 Issue 不预设实现方案。
+
+## 8. 关联产物
+
+- 策划 run ID：`gameagent-cd7f6c81`
+- 做游戏 run ID：`gameagent-77b5aa31`
+- 上传 GDD（项目相对路径）：`assets/uploads/upload-1788083777445-fast_gdd.md`
+- 建议随 Issue 附上或引用对应 run 的以下复核材料：
+  - Direct 对话：`.agent/conversations/project.jsonl`
+  - Direct Agent DB：`.agent/agent.db`
+  - Direct manifest：`.agent/manifest.json`
+  - 最终游戏：`game/index.html`
+  - 浏览器验证：`.agent/runtime/direct-codex-browser-validation/6/attempt-3/validation.json`
+
+上述材料应以 Issue 附件、仓库归档或团队共享存储的形式提供；本文不依赖某位开发者电脑上的绝对路径。