suzmii
84b8f5130b
前一次改动（60d8b8fbb）把 `useProjectResourceCardPreviews` 的 `resources` 从全量投影收窄成当前分页栏目，造成产品回归：该入参不只喂热预取，它同时决定返回的 `identityByResourceId`，而 `renderResourceBookCard` 在身份缺失时 `return null`，于是资源总览（main 态）只有当前分页栏目画出真实卡片，其余栏目只剩栏目标题栏加空的层叠占位。 - 拆成两个入参：`resources` 恢复全量资源投影语义（决定 `identityByResourceId`、缓存与卡片挂载），新增 `eagerResources` 只用于 `eagerPreviewLimit` 计数的热预取，缺省回退 `resources`。两个入参的语义写进 Hook 参数注释，调用方 `index.tsx` 在传参处注明「收窄 `resources` 会让其它栏目只剩标题栏」。 - 纠正前一次提交的说法：**identity map 必须保持全量**，不能跟着热预取一起收窄。热预取可以只喂当前栏目（上一个提交的意图保留、`A → B → 回 A` 会重读 A 可见卡的已知代价也保留），但身份 / 渲染口径收窄会让总览其它栏目不再挂载卡片——技术方案要求「主画布展示各子画布的缩略入口，内部按资源类型显示有限层叠卡片……主画布预览和子画布展开态复用同一套卡片视觉」，这是产品回归而非可接受的行为变更。 - 不使用「身份未知时用 idle 占位兜底渲染」这条备选：它会让总览卡片失去真实预览，观感更差。 - `pitfalls.md` 追加同题排障口径，含通用规则：凡 Hook 入参同时参与「身份 / 缓存 key」与「调度 / 预热」，就不能为优化调度去收窄它，应先确认它还有没有别的消费者。 - 回归用例 `appSurface > uses one full-page canvas per resource section with dependency-only guide lines` 已自行变绿（未改该断言）。验证：`npm run test -- apps/ai-game-creator-shell/tests` 1171 passed / 4 skipped / 0 failed；`appSurface.test.ts` + `useProjectResourceCardPreviews.test.ts` 415 passed；`src/components/image-editor` 1385 passed；typecheck exit 0；check:encoding 4374 文件；`git diff --check` 干净。
项目记忆目录
本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。.codex/ 只放 Codex 工具资源，不作为项目知识库。
当前结构
docs/project-memory/
├─ README.md
├─ shared-memory/
│ ├─ project-overview.md
│ ├─ team-conventions.md
│ ├─ development-workflow.md
│ ├─ document-map.md
│ ├─ decision-log.md
│ ├─ pitfalls.md
│ └─ handoff-template.md
├─ plans/ # 仅限正在执行的短期计划
└─ todos/ # 仅限仍开放且有退出条件的事项
使用原则
- 开发前先读
AGENTS.md；复杂任务再读 Agent 执行准则、共享记忆和任务对应的当前专题文档。 - 稳定架构、接口、流程和排障边界写入
shared-memory/；同一事实只保留一个当前口径，细节放在权威专题文档。 plans/只保存正在执行、具有明确剩余项和验收门禁的计划；完成或作废后立即删除，稳定结论融合进当前专题或共享记忆。todos/只保存真实开放、有人接手即可执行的事项；每项应写明状态、下一决策点和关闭条件。已退役对象不保留未来 TODO。- 分支、提交、测试轮次和阶段流水账不进入长期记忆；需要追溯时使用 Git 历史。
- 若本目录与代码或最新
docs/冲突，以代码和最新专题为准，并在同次变更中修正记忆。 - 禁止写入个人配置、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
RAG 索引
本目录是本地 RAG 的高权重索引源，但检索结果只作为候选上下文。索引脚本位于 scripts/rag/；运行时依赖和 .rag/ 数据默认不安装、不提交，启用前需先征得用户确认。