高物
548db78ca7
Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.
经验沉淀
这一组文档主要回答两个问题：
- 这个项目开发时有哪些稳定有效的方法论。
- 遇到 UI、运行时、编辑器、AI 边界问题时，优先应该怎么判断。
推荐入口
- PROJECT_WORK_EXPERIENCE_PLAYBOOK.md：最完整的项目开发手册，适合先建立全局认识。
- PROJECT_DEVELOPMENT_EXPERIENCE.md：项目级经验浓缩版，适合快速回顾。
- ADVENTURE_RUNTIME_DEV_EXPERIENCE.md：专门看运行时、战斗、演出、NPC 流程时优先读。
- MOBILE_UI_DEV_EXPERIENCE.md：做移动端/游戏 UI 时的布局和交互经验。
- AGENT_UI_CHANGELOG.md：当前 UI 改动脉络、资产约束和已知坑。
历史实现经验
- CODEX_IMPLEMENTATION_EXPERIENCE_2026-03-24.md：偏“这类需求怎么拆链路”的实战经验。
- CODEX_PAST_WORK_EXPERIENCE_SUMMARY.md：偏“之前做过什么、怎么做的”的历史记录。
使用建议
- 只需要读一份时，优先看
PROJECT_WORK_EXPERIENCE_PLAYBOOK。 - 做 UI 改动时，把本目录和根目录的
UI_CODING_STANDARD.md对照着看。 - 做运行时流程改动时，把本目录和
docs/audits/engineering/README.md一起看，能更快发现风险边界。
近期专项记录
- RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md：记录 RPG 底稿阶段角色主形象与场景背景图并行生成约束。
- PLATFORM_HOME_BANNER_IMAGE_SIZE_FIX_2026-04-25.md：记录首页 banner 背景图不能进入普通布局流的修复经验。
- RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md：记录 RPG 发布后首页 / 分类页公开作品列表刷新链路。
- VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md：记录视觉小说模板交接时的阅读顺序、常见坑和维护检查口径。
- AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
- BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
- BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md：记录大鱼作品列表
items_json字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。 - BIG_FISH_DRAFT_GENERATION_CHAIN_FIX_2026-04-28.md：记录大鱼吃小鱼草稿生成从结构化内容产出到主图/动作默认提示词回填的修复口径。
- PUZZLE_LOCAL_RUN_LEADERBOARD_FIX_2026-04-28.md：记录拼图本地 run 通关后误请求后端排行榜、导致“run 不存在”报错的边界修复口径。