Skip to content

Agent.md

Latest commit

 

History

History
23 lines (21 loc) · 3.38 KB

Agent.md

File metadata and controls

23 lines (21 loc) · 3.38 KB
Raw

Agent Notes

  • 项目：UI & Animation Collection。

  • 当前约定：新增资源优先放在 app/assets/ 下，避免污染项目根目录。

  • 字体来源：优先使用 Google Fonts / 官方仓库文件，保留清晰文件名。

  • 开发服务：不要主动启动 Nuxt dev server；用户通常会自己常驻启动，先使用已打开的服务。

  • 页面骨架：默认 layout 统一维护全宽 UContainer + UMain + UPage 和全局侧栏；页面级 UPage 可以保留，但不得重复创建 UMain 或 UContainer。

  • 全局背景：默认 layout 统一挂载 PlumGrowthBackground，Canvas 固定在所有前景内容下方；页面不得重复创建该背景。

  • 构建检查：非必要不要跑完整 build，Nuxt 构建太慢；优先用相关文件 lint、已有 dev server 路由探测或局部检查。

  • Nuxt 组件命名：app/components/SinAni/AniDemo.vue 使用时写 <SinAniDemo>，不要写重复的 <SinAniAniDemo>。

  • GSAP 变量类型：创建 ctx、t1、resetAni 等变量时显式标注类型，例如 let ctx: gsap.Context、let t1: gsap.core.Timeline、let resetAni: () => void，避免 VSCode TS 插件报错。

  • 内容架构：收藏条目统一放在 content/zh|en/ui|animation/*.yml，标题/描述/截图/date 都归 Nuxt Content 管；i18n/locales/*.json 只放导航、按钮、页面外壳等固定文案。

  • 动画入库：从 AiLaboratory.vue 复制实现到 app/components/SinAni/，不得修改或清空实验室原稿；提取后的组件需保留并补齐算法注释，列表缩略图放在 public/。全局梅花背景与动画库单株演示是两个独立用途，不得互相替换。

  • 3D 音频可视化组件（Meteor Soundwave / Three.js）：

    • 着色器文件统一放在 app/components/SinUI/shaders/（如 stageVertex.glsl, stageFragment.glsl），通过 ?raw 导入。
    • Web Audio 与 Three.js 逻辑封装在 app/components/SinUI/composables/useMeteorSoundwave.ts 中，组件在 app/components/SinUI/MeteorSoundwave.vue，页面在 app/pages/ui/meteor-soundwave.vue。
    • 缩略图统一放在 public/，内容元数据分别配置在 content/zh/ui/meteor-soundwave.yml 与 content/en/ui/meteor-soundwave.yml。

  • Nuxt Studio：本项目先只启用本地 /_studio 编辑，不配置生产 OAuth/Git 发布和外部媒体存储。

  • Music 沉浸页：app/pages/Music.vue 使用 layout: false，不挂默认导航、侧栏、页脚和全局梅花背景；入口仅放在 SidebarMusicPlayer.vue 的 3D 可视化按钮；页面顶部 HUD 需提供返回主页的快捷入口（Back）。

  • Music 播放进度条与音量条采用流光渐变（from #2255ff via #8ef0de to #44ddff），走过的部分动态高亮。

  • 多语言与 useAsyncData 缓存约定：凡是依赖语言查询的 useAsyncData，其 key 必须绑定当前语言（如 `xxx-${locale.value}` 或带上 ${route.path}），严禁使用与语言无关的静态 key，避免路由/语言切换时命中同名 Payload 缓存导致数据语言错乱。

  • 纯客户端库与 SSR/Prerender 规范：强依赖 DOM/Browser 全局对象（如 MouseEvent、AudioContext）的第三方组件（例如 @applemusic-like-lyrics），严禁在页面顶层静态 import；必须通过 onMounted 动态 import() 或 defineAsyncComponent 加载，并配合 <ClientOnly> 包裹，确保 Nitro 服务端预渲染（prerender）阶段顺利通过。