Merge branch 'master' into opt/design-debug

2026-09-15 12:29:58 +08:00
parent 77d3917d9c dfdcc43a0b
commit 8ae7ed0128
15 changed files with 261 additions and 12 deletions
@@ -0,0 +1,20 @@
+Version: 1
+Status: active
+Date: 2026-09-15
+Parent Spec: 【里程碑】AGC首页策划补全入口-2026-09-15.md
+
+## 修改顺序
+
+1. 在 `view/home/index.tsx` 增加本地复选框状态与入口切换清理。
+2. 将游戏勾选状态映射到既有 `ProjectStartMode`。
+3. 增加启动模式纯函数测试，覆盖模式分流；首页显示边界和切换清理作为后续组件测试补充项。
+
+## 验证
+
+- AGC 首页相关定向测试。
+- AGC 前端 typecheck。
+- `npm run check:encoding` 与 `git diff --check`。
+
+## 当前验证边界
+
+本次已交付测试覆盖 `planning` / `direct-build` 模式分流；“策划补全”复选框的显示边界及切换创作类型后的状态清理尚未有组件级自动化测试，需后续补充 `HomeView` 测试时完成。
@@ -0,0 +1,20 @@
+Version: 1
+Status: active
+Date: 2026-09-15
+Parent Spec: AGC 首页与 Agent Runtime 入口
+
+## 范围
+
+在首页“做游戏”输入框下增加“策划补全”复选框；勾选后复用现有 `planning` 启动模式进入策划 Agent Runtime。
+
+## 验收标准
+
+- 仅“做游戏”显示复选框。
+- 勾选时提交 `planning`，未勾选时提交 `direct-build`。
+- “做方案”原有 `planning` 行为保持不变。
+- 切换到其它创作类型时清除游戏专属勾选状态。
+
+## 不做项
+
+- 不新增 runtime 类型、后端接口或持久化字段。
+- 不改变现有策划 runtime 内部流程。
@@ -1,5 +1,9 @@
 # 踩坑与排障记录

+## Windows 已登记生图资产未刷新
+
+Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` / `\\?\UNC\`，而前端项目路径仍是普通盘符或 UNC。失效监听不能直接比较原始字符串；识别为同一项目后，用当前项目路径重读 manifest，保留项目切换与 revision 门禁。普通 `agc_generate_image` 成功提交也必须发出失效通知，不能依赖整轮 Agent 结束。回归需覆盖两种 Windows 前缀、其它项目事件拒收，以及 Agent 尚未结束和后续失败时已登记图片卡片仍可见。
+
 ## 2026-09-14 严格 IPC 桩缺登记新命令时，症状可能是「unhandled rejection + 不相干的提示断言」，而不是同一处报错

 - **现象**：`ProjectDevelopmentView` 新增「项目打开时读生成任务账本」（`list_local_project_asset_generations`）后，两个**别的关注点**的用例同时红：`resourceCanvasManualLayout.test.tsx` 报 `AssertionError: expected [ Array(1) ] to deeply equal []`（严格桩把新命令记进 `unexpectedCommands`），并伴随 7 条 `Unhandled Rejection: TypeError: Cannot read properties of undefined (reading 'map')`；`appSurface/project-development.suite.ts` 的「布局读时提示」用例则因为新命令被当成 unexpected invoke 抛错、触发了新的提示条，导致 `queryBySelector('.game-resource-live-notice')` 断言失败。
@@ -1167,7 +1167,7 @@ game-project/

 - `.agent/manifest.json` 的存储写边界使用同目录持久文件锁跨线程、跨进程串行化；锁必须覆盖旧 manifest 读取、不可变版本前缀校验、临时文件安装和安装后回读一致性校验。锁文件拒绝符号链接、非普通文件和异常所有权 / 硬链接；Windows 使用不共享写句柄，Unix 使用 `O_NOFOLLOW + flock`。旧快照在新版本安装后只能被拒绝，不能覆盖已追加版本。
 - 后台 Agent 的 manifest 变化以共用 Runtime 状态投影 / 终态 emitter 作为失效因果点：`game-creator-agent-runtime-update` 的 Rust / TypeScript DTO 固定携带 `manifestInvalidated`，且 App 必须在 Supervisor、selected agent、session 和 run 身份的任何 early return 之前处理失效。GUI 进程内 Runtime 直接发该事件；External Runner 是独立进程、没有 GUI `AppHandle`，因此 Runner 协议 v5 的 `runner.attach_gui_owner` 必须登记 GUI 创建的随机 loopback 端口和 64 位随机令牌，Runner 的同一 emitter 通过受令牌保护的短连接转发 `game-creator-manifest-invalidated`。两条路径都只传项目路径与 Agent 身份，不复制 manifest，也不靠轮询补偿。
- Direct Codex 不伪造普通 Agent Runtime state。每张平台美术在本地文件与 manifest 提交成功后，统一通过 standalone `game-creator-manifest-invalidated` 发送 `projectPath + direct-codex-art`；只读恢复的已付费源图同样在 `register_local_asset_at` 成功后发送，下载、解码、文件写入或登记失败时不得发送成功失效。前端仍把 `game-creator-agent-progress` 仅用于进度文案；Direct Codex 整体命令成功、失败或超时 reject 后都追加一次 manifest 最终对账，只有完整成功才启动本地预览。
+- Direct Codex 不伪造普通 Agent Runtime state。每张平台美术在本地文件与 manifest 提交成功后，统一通过 standalone `game-creator-manifest-invalidated` 发送 `projectPath + direct-codex-art`；普通 `agc_generate_image` 同样在生成通道成功返回后、工具结果组装前发出通知，不能只覆盖标准美术包。只读恢复的已付费源图同样在 `register_local_asset_at` 成功后发送，下载、解码、文件写入或登记失败时不得发送成功失效。失效事件匹配当前项目时统一 Windows 盘符、UNC 与对应 verbatim 前缀的写法，实际重读始终使用当前项目保存的路径；该比较仅用于刷新提示，不替代后端路径与权限校验。前端仍把 `game-creator-agent-progress` 仅用于进度文案；Direct Codex 整体命令成功、失败或超时 reject 后都追加一次 manifest 最终对账，只有完整成功才启动本地预览。
 - App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。集成测试记录“事件未重新打开项目”的调用基线前，必须先等待项目写入最近列表后触发的只读目录状态刷新完成，不能把这项合法后台检查误算成失效事件副作用。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer、task flow 或对应任务环。前端收到截断 DTO 时只剔除 `producerAssignments`、`taskFlows` 与对应 `cyclicTaskIds`；Rust 根据当前 manifest、精确资源引用和仍可信任务深度下限返回的 `dependencyDepths` 继续保留，前端只校验资源仍存在且深度为非负安全整数，不得自行重算或压平权威深度。精确引用边、reference connection index、`cyclicResourceIds` 与 unresolved references 同样继续保留。
  -- 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。