Merge remote-tracking branch 'refs/remotes/origin/master' into feat/gptimage2to2.5

# Conflicts: # docs/project-memory/shared-memory/decision-log.md
2026-09-22 11:54:00 +08:00
parent 46c8573b0e 1b951619c9
commit a943048093
225 changed files with 8857 additions and 57184 deletions
@@ -13,6 +13,7 @@ AI Game Creator Shell 采用 IDEA 风格的当前进程错误报告：错误事
 - 指纹计算可使用调用方的 page/action 及脱敏后的首个调用点作为进程内区分输入，但这些上下文不会作为事件字段上传；消息与 stack 在入池前统一脱敏，WebCrypto 失败时降级为稳定可读指纹，采集本身不得产生新的未处理拒绝。
 - 客户端 API 自动采集只覆盖网络错误、408 和 5xx；预期的 4xx 登录/鉴权失败不进入错误报告池。
 - Rust 侧通过 `app_log!` 将普通文本日志同时输出到 stderr 和 AppData `diagnostics/application.log`，超出 256 KiB 滚动到 `application.previous.log`；WebView 的 console 输出通过 `append_application_log` 镜像到同一 raw log，并在客户端桥接处再次脱敏；`read_diagnostic_logs` 只读取应用级日志。
+- 这里有两套互不相干的东西，不要互相代入：**错误报告事件池**是进程内 `error_report` 的结构化事件（本次变更不动它，仍然只在内存里、提交时才生成 `events.jsonl`）；**统一 Agent Runtime 错误事件**是项目内 sidecar `.agent/runtime/errors/<eventId>.json`，既不进事件池也不进报告包。因为报告包里的日志附件只有 AppData 应用日志，所以 sidecar 的同一份已脱敏诊断再作为**日志行**（不是报告事件）投影成两行：`agent.runtime.error`（身份行：eventId / source / stage / code / retryable / clientTurnId / elapsedMs / detailRef，全部是程序生成或调用方常量）与 `agent.runtime.error.detail`（详情行：hint / summary / detail / metadata，自由文本只出现在这里）。两行都由 `agent/runtime_error.rs` 从同一份 diagnosis 生成，不新增字段来源；落到日志前 summary 按 320 字符、detail / metadata 按（1200 / 200 字符）预算脱敏截断（summary 由调用方给，`direct_tool_bridge` 会传工具错误原文，而 `app_log!` 同时把整行写 stderr，那里没有 `sanitize_diagnostic_message` 兜底）。`sanitize_diagnostic_message` 命中凭据标记时替换的是**整行**，自由文本因此只放详情行：详情行被吃掉也不影响身份行定位事件。
 - 报告面板只由自动诊断通知中的“查看并报告”打开，不提供聊天命令、崩溃页按钮或其他手动入口；默认选中当前快照中的全部事件，用户可取消不想提交的事件。允许填写最多 2,000 字中文描述并取消日志附件；本版本不支持截图或任意文件附件。
 - 报告面板读取当前错误快照失败时，必须明确显示“错误事件暂不可用，请关闭后重试”，不能把失败误显示为“当前没有待报告的错误”。
 - 通知中的“查看并报告”打开面板时必须保留该次通知快照；最新快照读取瞬时失败时使用这份 fallback 继续展示和提交，不能因先清空通知而丢失用户刚看到的事件。
@@ -285,7 +285,7 @@ Rust 分片日志在失败时输出有界 stdout 尾部中的失败段，保留

 ## DirectProject 用户消息契约验证

-`chat_with_game_creator_direct_codex` 必须携带 `projectPath`、`prompt`、稳定的 `clientTurnId` 和完整 `userItem`；`creationType` 与 `attachments` 按实际输入传递。Rust 通过 `projectPath` 解析项目身份，不接收额外 `projectId`。界面测试必须核对 `userItem` 的消息身份、角色、正文及附件内容，拒绝回合用例仍验证实际返回的错误原因。重开项目的历史恢复测试使用 `read_direct_project_history_slice` 的 canonical raw items 与 `hasMore`，首屏 `limit: 20`。资源图和生成任务的读取继续遵守原有工作台恢复逻辑，不因聊天断言失败延迟、关闭或改变它们。
+`chat_with_game_creator_direct_codex` 必须携带 `projectPath`、稳定的 `clientTurnId` 和完整 `userItem`（文本、`@` 素材引用与附件引用都在同一份 content 里）；`creationType` 按实际输入传递。Rust 只从 canonical `userItem` 派生回合输入，不接收前端渲染的 `@显示名` 文本投影。Rust 通过 `projectPath` 解析项目身份，不接收额外 `projectId`。界面测试必须核对 `userItem` 的消息身份、角色、正文及附件内容，拒绝回合用例仍验证实际返回的错误原因。重开项目的历史恢复测试使用 `read_direct_project_history_slice` 的 canonical raw items 与 `hasMore`，首屏 `limit: 20`。资源图和生成任务的读取继续遵守原有工作台恢复逻辑，不因聊天断言失败延迟、关闭或改变它们。

 ## 2026-09-16 DirectProject 回合展示唯一归属

@@ -537,8 +537,8 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创

 ## 技术选择

- 桌面壳：新建 `apps/ai-game-creator-shell`，与现有 `apps/desktop-shell` 分离，避免把游戏创作本地能力塞进主站宿主壳；启动时先检查平台登录态，未登录只展示登录页，登录后进入单窗口客户端首页；正式用户窗口常驻左侧栏和顶部栏，并在首页、项目组、指南 / 反馈和项目开发页之间切换。发布和 debug 启动都只登记并打开 `client` 用户窗口；`index.html?agent-chat` 仅保留为显式前端调试路由，不是 Tauri 自动启动入口。
- 窗口外壳：`client`、动态 `main` / `launcher` / `supervisor-chat` 窗口统一关闭原生 decorations，由前端 `WindowChrome` 绘制陶泥儿品牌 Logo、当前页面 / 项目标题和最小化 / 最大化 / 关闭控制。标题栏不重复展示项目列表或本地工作区入口：首页及非项目页面的居中标题固定为“创作工作台”，打开项目后切换为当前项目名；泥点账户入口通过标题栏右侧插槽渲染，标题文本使用独立的窗口几何居中层，不参与左右入口宽度分配，项目名过长时仅在可用宽度内省略。标题栏只复用 `packages/shared/src/theme.css` 的暖陶土变量与现有产品 IP，不引入另一套主题；浏览器预览或非 Tauri 宿主中窗口控制安全降级，不能阻断页面渲染。
+- 桌面壳：新建 `apps/ai-game-creator-shell`，与现有 `apps/desktop-shell` 分离，避免把游戏创作本地能力塞进主站宿主壳；启动时先检查平台登录态，未登录只展示登录页，登录后进入单窗口客户端首页；正式用户窗口常驻左侧栏和顶部栏，并在首页、项目组、指南 / 反馈和项目开发页之间切换。发布和 debug 启动都只登记并打开 `client` 用户窗口。
+- 窗口外壳：`client`、动态 `main` / `launcher` 窗口统一关闭原生 decorations，由前端 `WindowChrome` 绘制陶泥儿品牌 Logo、当前页面 / 项目标题和最小化 / 最大化 / 关闭控制。标题栏不重复展示项目列表或本地工作区入口：首页及非项目页面的居中标题固定为“创作工作台”，打开项目后切换为当前项目名；泥点账户入口通过标题栏右侧插槽渲染，标题文本使用独立的窗口几何居中层，不参与左右入口宽度分配，项目名过长时仅在可用宽度内省略。标题栏只复用 `packages/shared/src/theme.css` 的暖陶土变量与现有产品 IP，不引入另一套主题；浏览器预览或非 Tauri 宿主中窗口控制安全降级，不能阻断页面渲染。
 - 平台后端：继续使用 `server-rs + Axum + SpacetimeDB`；本地开发启动独立客户端时，`agc` / Tauri dev 会先启动或复用配套 SpacetimeDB 与 `api-server`，再启动固定端口 Vite，并通过 `/api` 代理访问实际后端端口。
 - 本地能力：使用 Tauri Rust command；正式用户 App 在项目运行工作台内承载 `127.0.0.1` 本地 HTTP preview，不再调用系统外部浏览器。运行容器只接受当前授权项目由 `PreviewRegistry` 返回的 loopback URL，release / dev CSP 都只为 `http://127.0.0.1:*` 开放 `frame-src`，并使用受限 iframe sandbox 隔离游戏脚本；远程 URL、`file://` 和任意手填地址均不得进入该容器。
 - Agent Runtime：扩展 `server-rs/crates/platform-agent`，不引入 LangChain、AutoGen、Microsoft Agent Framework 或 OpenAI Agents SDK sidecar 作为核心。
@@ -548,13 +548,6 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 代码组织：桌面客户端入口保持为薄组合层。前端把认证、Tauri 桥接、Runtime 配置、Agent Runtime 展示和项目摘要分别放入 `src/app`、`src/services` 与 `src/features`；Rust 项目能力和测试按功能域使用目录模块；界面测试与真实 Runtime E2E 使用薄 suite registry / entry 保留原执行顺序。后续拆分必须保持公开导出、命令契约、测试名称和行为不变，不能用 `include!`、整文件文本拼接或只移动到另一个超大文件代替真实模块边界。
 - 源码门禁：`check:native-shells` 等源码扫描必须跟随真实模块归属；入口组合层只验证受控组件的挂载关系，具体实现由所属模块单独验证。模块拆分后不得为了满足旧字符串扫描把实现搬回 `App.tsx`，也不得用跨文件文本拼接代替组件归属检查。

-## 开发态 Project Supervisor 纯聊天独立窗口
-
- 入口边界：当前仅 Tauri dev 提供独立窗口，路由为 `index.html?supervisor-chat&projectPath=...`，其中 `projectPath` 传入 URL 编码后的项目绝对路径。该窗口仅通过显式开发调试动作打开，不增加正式用户入口，也不随 `npm run agc` 自动弹出；重复打开同一项目只恢复并聚焦原窗口，切换项目时在同一窗口导航。
- Runtime 边界：窗口固定对话 Agent 为 `project-supervisor`，新 Run 使用 `standard` profile，复用现有 active Session、External Runner、Agent Runtime、AppData 配置和持久 conversation；不新建平行会话库、Runner 或配置存储，也不把该测试入口隐式切成自动修改项目的自主构建模式。
- 界面边界：只显示持久消息区、输入框、必要的等待 / 错误状态、工具确认 / 用户追问卡片和设置入口；不显示 Agent picker、Session 面板、Goal 面板、完整 Runtime 面板或专业 Agent 协作栏。会话历史仍绑定 `project-supervisor` 的 active Session 持久化，不因隐藏 Session 控制面而变为临时聊天；`supervisor-chat` 窗口必须具备只读 Tauri event listen / unlisten capability，以实时接收 Runtime 更新。
- 产品边界：正式用户 `client` 窗口、登录后首页和项目开发流程保持不变，不暴露该开发验证面。
-
 ## 2026-07-29 “游戏运行 + 聊天”独立构建入口

 - Windows AppData 安全迁移：首次创建客户端 AppData 时必须以进程 `TokenUser` SID 显式设置 owner，并写入当前用户私有 DACL，不能把可能为 Administrators 的 `TokenOwner` 当作用户身份。发现历史目录 owner 不属于当前 `TokenUser` 时，不在原目录上放宽权限，而是拒绝 reparse point / junction / symlink 后，将旧目录原子重命名到同级唯一 `.owner-mismatch-backup-*` 备份，再新建并验证当前用户 owner 与私有 DACL；迁移或备份失败必须失败关闭，不覆盖旧配置。
@@ -572,7 +565,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 固定试玩契约：`generic-v1` 初始状态必须为 `ready` 且 `level > 0`；点击 start 后 sequence 必须推进、phase 必须进入 `playing`，并先持续观察 2 秒、取得至少 8 个实际样本，期间保持 `playing`，以确认玩家获得正常操作机会。随后必须点击唯一可见、启用且真实可交互的 `data-playtest-id="primary-action"` 控件；该控件必须映射游戏的真实主要玩法操作，并以 sequence 相对点击前严格推进证明操作已被接受。玩家获得这次正常操作机会之前进入 `won | lost` 属于过早结束并失败；操作被接受后的单次 `lost` 是合法游戏结局，但不能成为所有受控尝试的唯一结果；若主要操作后仍为 `playing`，则继续观察 3 秒并取得至少 12 个实际样本，`won` 可提前证明非失败推进。点击 restart 后 sequence 必须再次推进并恢复到 `ready | playing`，随后持续观察 3 秒且取得至少 12 个实际样本。若首轮结果为 `lost`，重开稳定后必须再执行一次必要的 start、2 秒 / 8 样本操作机会和真实 primary-action；第二次必须进入或保持 `playing`（再观察 3 秒 / 12 样本且不得转为 `lost`）或进入 `won`，两次都固定 `lost` 代表无法正常推进的恶性 bug，必须失败。各观察窗口内 sequence 不得回退，restart 窗口只能保持 `ready | playing`；样本数门槛不能替代时长门槛，窗口末端必须强制再读取一次有效状态，不能只在前段快速取得足够样本后提前通过。控件 selector、观察时长、最少样本数、终态边界、非失败推进、末端覆盖、sequence 单调 / 严格推进规则及完整 required assertions 都进入 scenario fingerprint。读取旧 fingerprint 回执和检查 plan liveness 时，把合同升级造成的 fingerprint 不匹配视为 stale missing，允许同一 run 重新执行 `preview.validate` 自愈；身份、路径、digest 或内容完整性篡改仍失败关闭。最终完成门每次按当前合同重算 fingerprint，并严格拒绝旧 fingerprint、旧 assertion 集或仅保存历史 `passed=true` 的证据。
 - 一次性自动预览授权：用户在该入口成功提交本轮自主生成需求，即视为对“当前项目 + 当前 Supervisor 父 run”的一次 `preview.start` 授权。授权以仅含项目路径与 accepted parent runId 的客户端本地记录持久化，App / WebView 重启后仍可恢复，但项目或 run 身份不匹配时不得使用。只有当前 accepted parent run 成功完成 `preview.validate` 且给出有效 revision 后，客户端才可消费授权，由 Tauri 首次启动并自动展示该 revision 的用户可见预览；一次授权最多成功启动一个 Tauri preview server，并必须继续走现有权限、项目写锁、审计和客户端 `PreviewRegistry` 链路。项目或 Agent 策略的显式 deny 始终优先，不得被此授权绕过。启动成功、显式 deny、非瞬时失败、父 run 在首版验证前终止或切换项目后授权失效；`preview.start` 恰逢项目写锁竞争属于瞬时失败，不消费授权，释放写锁后由同一轮询链路重试。
 - 增量预览刷新：Tauri 客户端记录当前 iframe 已展示的 validated revision；同一当前 run 后续成功 `preview.validate` 的 revision 严格高于已展示 revision 时，只在原 Tauri preview server 和原 loopback origin 上刷新 iframe，不得再次调用 `preview.start`、新增 server 或切换到 Runner registry。相同或更低 revision 不触发刷新。preview HTTP server 对 HTML、脚本、样式、资源和错误响应统一发送 `Cache-Control: no-store`，iframe 刷新必须读取新 revision，不能继续命中 WebView 缓存中的旧版本。自动预览轮询回归的等待上限必须严格大于生产 `1000ms` 轮询间隔，不得使用同为 `1000ms` 的默认上限制造 CI 边界竞争。
- 系统边界：该页面是既有 AI 游戏创作工作台的独立构建例外，不新增平台玩法入口、后端 API、会话库、Runner 或预览服务，也不把入口并回普通正式客户端。原 `supervisor-chat` 继续固定使用 `standard` profile 并保持纯聊天行为，不继承本例外的自主构建、事件聚合或自动预览授权。
+- 系统边界：该页面是既有 AI 游戏创作工作台的独立构建例外，不新增平台玩法入口、后端 API、会话库、Runner 或预览服务，也不把入口并回普通正式客户端，也不继承本例外的自主构建、事件聚合或自动预览授权。

 - 对话输出中的 `eventId + publicText` 只指需要独立进入聊天的进度事件；`turn.started` 和根 Run 终态失败事件由上一条 `runtime-public-status-*` 硬门覆盖，不得同时转成事件消息。专业 Agent child 的失败消息继续留在其 Agent Session，根项目聊天只接收 Supervisor 终态失败、明确公开进度和安全 final-reply，避免一项失败被 Runtime event 与 conversation 各播报一次。
 - 验证：前端运行时模型定向测试、Rust completion/source/asset 合同测试、`cargo fmt --check`、`npm run check:encoding` 与 `git diff --check` 必须全部执行；Windows 文件锁竞态只可作为既有测试失败单独记录，不得将其改写为本次改动的通过证据。
@@ -763,7 +756,7 @@ Agent Runtime 负责：
 ## Agent 能力清单

 - 用户能力：项目开发工作台、陶泥儿聊天、上传文件、manifest 资源视图、客户端内运行表现层和专业 Agent 紧凑状态；正式用户窗口仍不展示原始任务 / 文件 / 日志、开发预览调试面板、能力清单或开发专用单 Agent 聊天入口。
- 开发调试能力：`index.html?agent-chat` 可作为显式前端调试路由；开发者可选择 Agent、授权本地项目路径，并通过 `read_local_conversation` / `append_local_conversation_message` 读写 `.agent/conversations/agents/<agentId>.jsonl`，通过 `agentLlm.<agentId>` 调用该 Agent 的独立 LLM 路由做真实对话，用于单独调试某个 Agent 的长期对话上下文。这里的 `<agentId>` 以 manifest taskId 为规范值，旧 `group-role` 别名只作为兼容输入映射到 taskId。
+- 开发调试能力：无 GUI 调试使用 `npm run agc:chat` / `npm run agc:swarm` 终端入口，复用 External Runner、active Session、conversation 与各 Agent 私有记忆；`<agentId>` 以 manifest taskId 为规范值，旧 `group-role` 别名只作为兼容输入映射到 taskId。
 - 命令能力：内置命令调用、权限 gate、执行日志；v1 只允许白名单受限命令，不执行任意 shell。
 - 编排能力：任务拆分、任务图依赖、专业组调度、多智能体协作；Runtime V1 会为单 Agent 对话和生成 loop 中的角色 brief 写入独立 runtime state / event，先解决“每个 Agent 正在做什么、跑到哪一步、最近一次 task/run 是什么”的可观测性。
 - 历史边界说明：下一条“后台任务能力”保留 V1.1 前的进程内演进记录，其中 App 内 tokio task、进程内 drain、旧工具箱和“不是独立 OS 进程”的描述均已失效；当前执行边界以上文独立 Runner 说明为准。
@@ -1340,7 +1333,7 @@ game-project/
 - 开发模式可执行 `canvas.asset_import`，将项目内已有文件按画板来源导入 manifest；也可执行 `canvas.export_import`，把现有画板素材导出 ZIP 回流为本地项目资产。`game.generate_draft` 在普通模式登录态有效或高级模式凭据有效时复用同一平台图片生成能力，不新增平行资产模型。
 - 普通模式已在登录后的单窗口项目开发页渲染 GameAgent 工作台、`project-supervisor` 主聊天和专业 Agent 协作只读状态，不提供专业 Agent / child 单 Agent 对话；首页首条需求直接投递 active Supervisor Session，全新项目没有该 Session 时先通过既有 Session 命令创建并设为 active，已有项目恢复该 Session 与历史后继续交互。Tauri 主窗口承载当前授权项目的 loopback 游戏画面，但不承载开发 Agent picker、调度工具台或任意地址预览调试面板。
 - 聊天生成草案后会尝试启动只读 `127.0.0.1:<port>` 静态 HTTP server，把预览地址回写客户端项目运行工作台并切换到运行视图；不再调用系统外部浏览器。
- 开发模式仅在 Vite dev 环境响应 `?dev` 或 `#dev`；`npm run agc` 与 release 都只打开 `client` 用户窗口，显式 `?agent-chat` 与 `supervisor-chat` 调试入口不随启动自动弹出。正式构建忽略 dev 参数，release 配置只登记一个用户窗口，登录后同窗口进入首页并在项目组 / 项目开发页之间切换。
+- `npm run agc` 与 release 都只打开 `client` 用户窗口。正式构建与 release 配置只登记一个用户窗口，登录后同窗口进入首页并在项目组 / 项目开发页之间切换。
 - `check:native-shells` 会运行 `ai-game-creator-shell:check` 和 `ai-game-creator-shell:build -- --no-bundle`，并静态检查 release 与 debug 启动都只登记 `client / index.html` 这一个默认窗口、禁止 Tauri setup 自动打开 developer 窗口、开发面板必须挂在 `devMode` 分支内，正式用户 App 的运行容器只接受 `http://127.0.0.1:*`，release / dev CSP 都只为该 loopback origin 开放 `frame-src`，Tauri 预览激活命令不得调用 opener，用户主流程不得调用旧工作区窗口切换 command。
 - 共享契约提供 `GAME_CREATION_AGENT_CAPABILITIES` 和内置命令权限枚举；开发模式会展示能力列表。
 - 共享契约提供 manifest task schema 和 ready-task 选择器，用于记录任务拆分、专业组、角色模板、依赖、产物、验收条件和当前可执行任务。
@@ -1846,3 +1839,9 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 用户级配额：跨节点的用户总量配额与计费口径未定；当前用单项目 2 GiB 上限 + 清单引用回收保证常驻占用有界，用户级总量只能靠项目数间接约束。
 - 目标 bucket 的生命周期规则（例如转低频/过期删除）需要在部署环境确认后单独收口；功能本身已不再依赖它来控制增长。
 - 大项目（素材数量多、单文件大）的首轮全量上传耗时与带宽占用未实测；单次预算 512 MiB 会把超出部分留到下一次同步，但并发上限与断点续传仍未引入。
+
+## 2026-09-21 统一错误事件同时落到 AppData 应用日志
+
+`AgentRuntimeErrorEvent` 把失败投影到用户消息、运行面板和项目内 `.agent/runtime/errors/<eventId>.json` 时，同一份已脱敏诊断还要投影成 AppData `diagnostics/application.log` 的两行：`agent.runtime.error`（身份行：`eventId / source / stage / code / retryable / clientTurnId / elapsedMs / detailRef`）与 `agent.runtime.error.detail`（详情行：`hint / summary / detail / metadata`）。原因是项目内 sidecar 只在项目目录可见，而“报告问题”只上传应用级日志：没有这两行时，用户提交的失败消息里只剩一个 `详情：.agent/runtime/errors/...json` 路径，团队拿不到诊断正文。
+
+口径：两行都由 `agent/runtime_error.rs` 从同一份 diagnosis 生成，字段不退化成第二份来源；`summary` 按 320 字符、`detail` 与 `metadata` 按（1200 / 200 字符）预算先脱敏再截断，落盘前还会被 `sanitize_diagnostic_message` 二次脱敏并按行截断，因此自由文本字段在行内先压平换行。拆两行是因为整行一旦出现凭据标记会被整体替换成脱敏占位：所以**自由文本（summary / hint / detail）只放详情行**，身份行只留程序生成与调用方常量字段，详情行被整体脱敏时事件仍能按 eventId / detailRef 定位。写日志先于写 sidecar：sidecar 失败不能连日志一起丢。
@@ -106,7 +106,7 @@ readHistory(threadId, { beforeItemId?, limit }) -> {

 Thread 内所有公开事件共用一个单调递增 seq，但 **seq 只是 Thread Manager 的内部游标事实，不下发**：同一个 subscriber 的 `consume` 按队列顺序返回事件数组，数组顺序就是前端要处理的顺序，前端因此不需要 item 级 cursor 或第二套 reducer。

-线上模型是 ts-rs 导出的 tagged enum（`agent/direct_thread_wire.rs`），前端消费 `src/features/project-workspace/generated/` 里的生成绑定，改 Rust 模型后跑 `cargo test export_bindings` 重新生成；毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
+线上模型是 ts-rs 导出的 tagged enum（`agent/direct_thread_wire.rs`），前端消费 `src/view/project-development/chat/generated/` 里的生成绑定，改 Rust 模型后跑 `cargo test export_bindings` 重新生成；毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。

 事件按 `type` 区分，条目按 `itemType` 区分：

@@ -227,7 +227,7 @@ initialAttachments={currentProjectContext.attachments}
 1. [`home.suite.ts`](../../apps/ai-game-creator-shell/tests/appSurface/home.suite.ts)「imports home attachments…」：Direct invoke 必须带 `attachments`，其中 `name` 为 `角色参考.png`、`localPath` 为 upload 返回路径、`status: 'imported'`。用 png 证明不是 md 特例。
 2. 无附件的 Direct invoke 仍不得出现 `attachments` 键（或等价：不传该字段）。
 3. `planningStartMode` 首轮仍走 Supervisor，`chat_with_game_creator_agent` 的 payload 不含附件 sidecar。
-4. 工作台后发的普通消息：`chat_with_game_creator_direct_codex` 只有 `projectPath/prompt/clientTurnId`（及既有 creationType 规则），不带 attachments。
+4. 工作台后发的普通消息：`chat_with_game_creator_direct_codex` 只有 `projectPath/clientTurnId`（及既有 creationType 规则），不带 attachments。
 5. 若本分支已能跑 PR #210 的 home.suite / plan-gdd 做成游戏用例：只断言它仍调用 `createHomeDraftAutomatically` / 仍使用原固定 prompt；**不要**给做成游戏加第二条附件协议。sidecar 由通用 Direct 断言覆盖。

 ### 不测
@@ -1,6 +1,6 @@
 # 策划 Agent 生产迁移与工作区浏览方案

-更新时间：2026-09-20
+更新时间：2026-09-21
 状态：已完成（2026-09-18）

 > 现状说明（2026-09-18）：本文记录的迁移已完成，当前策划入口统一使用 Design Agent。旧 Planning V1/V2 会话、专用命令、审批卡和展示适配已删除；文中提到的 V2 文件仅代表迁移时的参考来源，不得作为现行实现、回退路径或测试迁移目标。
@@ -174,6 +174,18 @@ Runtime 不维护文档版本号，不解析文档版本，不提供版本回退

 验收至少覆盖：保存后重新进入策划显示一致；旧会话切换模型后实际请求改变；当前执行不被中途改档；下一次发送/澄清/审批继续/主动重试生效；自动恢复不重复工具副作用；GameAgent 原有选择、发送和运行行为不回归。真实 Provider 或桌面环境缺失时明确记为未验证，不用 fixture 冒充实机结果。

+### 4.2 策划参考附件导入
+
+- 首页策划入口与策划聊天框将用户附件按原始字节导入 `design_artifacts/references/`，Agent 通过现有工作区文件工具自行发现。有用户文字时，导入完成后才开始首页首轮策划；只有附件时只进入工作区，不合成消息或自动启动策划。聊天框导入中暂缓发送、阶段批准、澄清与重试，并提示等待导入完成再切换游戏制作，避免新回合读取未完成文件或模式切换丢失导入结果。
+- 文件名保留安全的原始名称；同名自动追加序号，禁止覆盖已有文件。沿用项目权限与工作区路径边界，禁止通过文件名、符号链接或目录链接写出工作区。空文件也可导入。
+- 导入只写策划工作区，不登记游戏资产、不更新项目资源清单或游戏 revision，不触发上传后的清单刷新。不组装回合附件、不把文件路径或清单注入 Agent 消息。
+- 每个文件独立返回结果；部分失败不丢弃成功文件，界面显示成功数量及失败文件和原因。用户可重新选择失败文件重试；成功导入不自动重放，再次手动导入同名文件视为新副本。
+- 游戏入口继续使用现有资产上传链路。已有 `assets/uploads/` 文件不自动搬迁；转入游戏制作时沿用现有策划工作区登记行为。
+- 本次不修改 Agent 提示词、工具或消息协议，不增加 PDF、Word 等二进制文档解析；保存成功不代表格式可由现有 UTF-8 文件读取工具解析。
+- 验收覆盖：首页与聊天框导入、多文件部分失败、同名与空文件、工作区工具可列出并读取文本、路径与链接边界、资源清单和 revision 保持不变、游戏上传兼容。证据由定向前端测试、本地 Rust 文件往返测试、类型检查和编码检查提供；真实桌面交互另行记录。
+
+验证证据（2026-09-21）：`appSurface.test.ts` 中策划导入、导入中审批、首页游戏附件与模型控件定向用例通过；`designWorkspaceDebug.test.tsx`、`designProjectRestore.test.tsx` 与 `workspaceLauncherManifestMerge.test.tsx` 通过，覆盖文件事件刷新、项目恢复和导入中模式切换。Rust `agent::design_tools::tests::` 8 项通过，覆盖文件往返及写入边界。AGC typecheck（含命令注册检查）、定向 ESLint、Rust 格式、编码、文档索引与差异检查通过。未运行安装包桌面点击验证或真实 Provider；Windows 链接用例在宿主不支持建链接时跳过。
+
 ## 5. Agent Runtime

 新的 Runtime 应提供自由工具循环：
@@ -586,13 +586,13 @@ hydrate_planning_session_v2

 ### 7.3 UI 复用边界

-第一版可复用现有：
+策划会话的入口容器、审批卡与工作台布局已经落地在当前模块结构里：

- `ProjectSupervisorView` 的聊天区域和工作台布局；
- `GddApprovalCard` 的产物展示与审批交互；
- 现有耗时展示和会话历史加载。
+- `view/project-development/planning/PlanningChatView.tsx`：策划会话容器，只消费 V2 状态；
+- `view/project-development/planning/GddApprovalCard.tsx` 与 `PlanningLaneRuntimeStrip.tsx`：产物展示、审批交互与窄条运行态；
+- 现有耗时展示和会话历史加载继续复用。

-但数据来源必须改为 V2 状态，不再把“页面组件叫 Supervisor”当作运行时身份。后续再把组件重命名为 `PlanningSessionView`，不作为本次切换前置。
+数据来源只有 V2 状态；旧 `project-supervisor-plan` 运行时不参与页面渲染，也不再作为组件身份。

 ## 8. 最小安全与业务校验