Merge branch 'master' into fix/ref_doc

docs/technical/【前端架构】共享基础组件库与展示页-2026-08-26.md

@@ -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`。

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

@@ -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 与回滚合同完备前不向普通用户开放。

docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md

@@ -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 身份校验与落盘投影修复的顺序一条单列后续，未并入。

docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md

@@ -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 附件、仓库归档或团队共享存储的形式提供；本文不依赖某位开发者电脑上的绝对路径。