Imported from zuoliang0/ocean-doodle-kids (AGENTS.md). Install upstream with npx skills add zuoliang0/ocean-doodle-kids. Copyright stays with the author.

AGENTS.md

本文件为 /Users/zuoliang/Documents/儿童海洋涂鸦项目 的项目级协作规范。后续 agent 在本仓库工作时，必须先阅读 pages.json 与 docs/，并以其中的产品、页面、技术方案为事实来源。

项目定位

• 产品名称：海洋伙伴 / 儿童海洋涂鸦 MVP。
• 项目形态：Pad 横屏 Web/H5，离线优先，静态资源可托管。
• 核心用户：3-9 岁儿童；次级用户为家长或老师。
• 核心体验：选择海洋动物模板 -> 分区涂色 -> 完成预览 -> 送入海洋 -> 在动态海洋世界中看到作品游动。
• 默认不做：账号体系、云端同步、社交分享、复杂自由绘画、多人协作。

必读资料

变更前必须按需读取以下文件：

• pages.json：页面、路由、UI prompt、视觉稿路径、切片资产索引。
• docs/prd.md：产品目标、MVP 范围、非功能要求。
• docs/feature-plan.md：模块级功能规划。
• docs/feature-list.md：可拆票功能清单。
• docs/technical-plan.md：Web/H5 技术方案与数据结构。
• docs/page-plan.md：页面路由、交互、状态与全局组件规划。

读取顺序建议：

1. 先读 docs/page-plan.md 与 pages.json，确认路由和页面事实。
2. 再读 docs/technical-plan.md，确认架构和实现约束。
3. 最后读 docs/prd.md、docs/feature-plan.md、docs/feature-list.md，确认范围边界。

页面与路由

必须以当前规划为准实现以下页面：

• /：启动与主页。
• /templates：模板选择。
• /color/:templateId：涂色编辑器。
• /preview/:artworkId：完成预览与入海。
• /ocean：海洋世界动态展示。
• /gallery：我的作品。
• /settings：设置与帮助。

页面实现要求：

• 面向 Pad 横屏，优先保证 1024x768 及以上横屏体验。
• 后续界面开发必须优先按 pages.json 中各页面的 imagePath 指向 UI 设计稿做视觉还原，并结合 uiPrompt、description 校准交互意图。
• 样式实现必须优先使用现有设计稿切片与素材资产，不应仅用通用 CSS 自由发挥整体视觉；缺失素材时先说明缺口，再用最小占位方案推进。
• 如果设计稿还原所需素材缺失，直接使用 imagegen 技能和内置 image_gen 工具生成项目可用位图素材；生成后的正式素材必须复制或移动到仓库内的 assets/ 或 src/assets/，并更新代码引用，不能只停留在默认生成目录。
• 每轮界面开发必须边开发边截图验证：至少截取当前实现页面，与 pages.json 中对应 imagePath 设计稿做视觉和交互对比，再根据差异调整。
• 竖屏时提供旋转设备提示，不强制依赖浏览器锁屏能力。
• 所有主要触控目标不小于 44px。
• 儿童主流程文案短、动作清晰、避免信息拥挤。
• 高风险操作必须二次确认；涉及删除、清空、重置时需要家长门禁或明确确认。

推荐技术栈

优先采用以下方案，除非已有源码明确使用其他栈：

• 构建：Vite。
• 语言：TypeScript。
• UI：React + React Router，或 Vue 3 + Vue Router。二选一后保持一致，不混用。
• 状态管理：轻量方案，如 Zustand / Pinia；避免过度抽象。
• 涂色编辑器：SVG 分区点击填色 + Canvas 图层合成导出。
• 海洋世界：PixiJS 实现 2D/WebGL 场景、精灵动画、视差、深度排序与点击交互。
• 存储：IndexedDB 保存作品、纹理、缩略图、元数据；LocalStorage 保存设置项。
• 可选增强：PWA 仅缓存静态资源，不引入远端账号或同步。

架构分层

保持简单清晰的三层结构：

• UI 与路由层：页面、导航、弹层、引导、空态、错误态。
• 绘画引擎层：模板渲染、区域填色、画笔图层、撤销重做、导出纹理。
• 世界引擎层：/ocean 场景、实体运动、深度排序、点击反馈、性能降级。

设计原则：

• KISS：先实现可运行 MVP，不为未来玩法预留复杂系统。
• YAGNI：未被 docs/ 明确要求的分享、账号、云同步、奖励系统不实现。
• DRY：页面通用按钮、弹层、顶部栏、空态、确认框应复用。
• SOLID：绘画逻辑、存储逻辑、场景动画逻辑分离，避免页面组件承担过多职责。

数据模型约束

参考 docs/technical-plan.md，本地数据至少覆盖：

• artworks：作品草稿与已入海作品。
  • 字段建议：id, templateId, title, status, createdAt, updatedAt, regionColorMap, doodleStrokes, texturePngBlob, thumbnailPngBlob, textureVersion。
• oceanWorld：海洋世界中的作品伙伴。
  • 字段建议：artworkId, spawnAt, pathSeed, depthSeed, scale, speed, preferredLayer。
• settings：声音、音效、低性能模式、新手引导状态。

隐私与安全：

• 默认不采集个人信息。
• 默认不接入第三方追踪 SDK。
• 作品、轨迹、导出纹理仅保存在本地。

涂色编辑器要求

• 模板以 SVG 分区为主，每个可涂区域有稳定 regionId。
• 点击封闭区域立即填色，并提供轻量反馈。
• 画笔图层使用 Canvas，橡皮擦只作用于画笔图层。
• 撤销/重做使用命令栈，填色按区域颜色变更记录，画笔按 stroke 记录。
• 清空属于高风险操作，必须二次确认。
• 离开编辑器前如仍在保存，必须提示并避免误退。
• 导出作品时生成透明背景 PNG，只包含动物主体，不带编辑器背景。

海洋世界要求

• 使用分层场景：背景层、中景作品与系统鱼、前景气泡/水草、UI 层。
• 已入海作品以无背景动物纹理游动，不使用相框。
• 通过 depth 控制缩放、透明度、速度、排序，形成类 3D 空间感。
• 动物路径使用预设曲线或样条，朝向随路径切线翻转。
• 点击作品伙伴时提供轻弹、高亮、信息卡；点击空白关闭信息卡。
• 低性能模式下减少粒子、滤镜、同时游动数量，仍保留基础游动。

资产使用

• 页面视觉稿在 assets/pages/**/versions/*.png。
• 切片资产在 assets/slices/** 与 assets/sprites/**。
• 使用资产前先从 pages.json 查找 assetIds、imagePath、页面描述与 UI prompt。
• 对有设计稿的页面，先检查对应 imagePath 和 assetIds，再决定布局、颜色、圆角、阴影、背景、按钮样式和装饰元素。
• 可直接复用的按钮、背景、图标、卡片、装饰图，应优先作为 <img>/CSS background/纹理素材使用；只有通用容器、排版和状态变化用 CSS 补齐。
• 如果素材切片不满足实现需求，优先从 assets/pages/**/versions/*.png 或 assets/sprites/**/manifest.json 追溯可用区域，不要重新设计一套不一致的视觉语言。
• 对比设计稿时优先检查：主视觉背景、主按钮位置与大小、卡片层级、圆角/阴影、图标素材、首屏可见性、触控目标和交互动线。
• 不要把日志目录 logs/ 或临时目录 tmp/ 当作运行时资源来源，除非任务明确要求。
• 新增正式资源应放入清晰的 assets/ 子目录，并更新引用路径。

代码与实现规范

• 默认使用简体中文回应用户。
• 代码注释语言应跟随现有代码库；没有既有代码时，业务注释优先用简体中文，技术命名保持英文。
• 路径必须使用正斜杠 /，命令中的路径使用双引号包裹。
• 搜索优先使用 rg。
• 修改前先阅读相关文件；不要基于猜测改动。
• 不要主动执行 git commit、git push、创建分支或重置分支，除非用户明确要求。
• 不要提交或依赖 .DS_Store、.playwright-mcp/、tmp/、logs/ 等本地临时文件。

验证要求

实现 Web 项目后至少执行：

• 安装依赖后运行项目已有的 lint/typecheck/test 命令。
• 若存在 package.json，优先检查并运行：
  • npm run typecheck
  • npm run lint
  • npm test
  • npm run build
• 若命令不存在，说明原因，不临时发明验证命令。
• 前端页面变更后必须用浏览器验证关键路由，尤其是横屏布局、主流程跳转、按钮可点击性、文字不溢出。

MVP 实施顺序

推荐按以下顺序推进，避免过早复杂化：

1. 搭建 Vite + TypeScript 前端工程与路由骨架。
2. 实现主页、模板选择、设置、作品列表的静态可交互版本。
3. 实现本地模板数据与作品 IndexedDB 存储。
4. 实现 SVG 分区填色、调色板、撤销重做、自动保存。
5. 实现作品预览、透明 PNG 导出、入海状态写入。
6. 实现 /ocean PixiJS 基础场景、系统小鱼、作品伙伴游动。
7. 补充空态、加载态、错误态、家长门禁、低性能模式。
8. 做横屏 Pad 浏览器验证与构建验证。

危险操作确认

执行以下操作前必须取得用户明确确认：

• 删除文件或目录。
• 批量移动或重命名文件。
• git commit、git push、git reset --hard。
• 修改系统配置、环境变量或全局依赖。
• 清空 IndexedDB、本地作品或运行破坏性脚本。
• 调用生产环境 API 或上传敏感数据。

确认时说明操作类型、影响范围、风险评估，并等待用户明确回复“是”“确认”或“继续”。