zhaoguiyang.site/.trae/rules/project_rules.md

项目说明文档

本文档旨在提供对 zhaoguiyang.site 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。

1. 项目概述

zhaoguiyang.site 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目，并包含完整的博客功能，支持多语言（英文和中文）。网站采用响应式设计，适配各种设备尺寸，并支持亮色/暗色主题切换。

2. 技术栈和框架

• 主要框架: Astro - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。项目配置在 astro.config.mjs 中，包含了对 React、TailwindCSS、MDX 和国际化的支持。
• UI 框架: React - 用于构建用户界面的 JavaScript 库。在本项目中，交互性组件（如头部导航、主题切换、语言切换、动画效果等）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
• 样式: Tailwind CSS - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 @tailwindcss/vite 集成到 Astro 项目中。项目还使用了 @tailwindcss/typography 插件来美化博客文章内容。全局样式定义在 src/styles/global.css 中，包含了亮色和暗色主题的颜色变量。
• 动画: Framer Motion (framer-motion) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在页面元素中实现入场动画、悬停效果等。具体使用方式可以参考 src/components/MotionWrapper.tsx 组件，它是一个统一处理动画逻辑的封装，提供了淡入和Y轴位移动画效果。
• 图标: Lucide React - 一个简单、美观的 SVG 图标库，用于提供界面图标。
• 包管理器: pnpm - 一个快速、磁盘空间高效的包管理器。
• TypeScript: 用于类型检查和提高代码质量。项目使用严格的 TypeScript 配置，类型定义集中在 src/types/index.ts 文件中。
• 国际化: 使用自定义的国际化解决方案，通过 src/i18n 目录下的文件管理多语言内容。ui.ts 定义了翻译文本，utils.ts 提供了国际化工具函数，如 useTranslations 和 getLocalizedPath。
• 内容管理: 使用 MDX 进行博客文章的编写，支持 Markdown 语法和 React 组件的混合使用。
• UI 组件增强: 使用 Radix UI 的 @radix-ui/react-scroll-area 和 @radix-ui/react-slot 组件来增强用户界面的可访问性和交互性。

3. 组件库和 UI

• 核心组件: 项目包含多个自定义 React 组件，位于 src/components/ 目录下：
  • GlassHeader.tsx: 玻璃拟态效果的导航栏，实现了响应式设计、语言切换、主题切换、滚动效果和移动端菜单。
  • Footer.tsx: 页脚组件，包含社交媒体链接和版权信息。
  • LanguageSwitcher.tsx: 语言切换组件，支持英文和中文切换，使用 Framer Motion 实现动画效果。
  • TypewriterEffect.tsx: 打字机效果组件，支持单文本或文本数组的循环显示、自定义打字/删除速度、延迟和光标样式。
  • SkillsMarquee.tsx: 技能标签滚动展示组件，使用 Framer Motion 实现无限滚动效果，支持自定义滚动方向和速度。
  • MotionWrapper.tsx: 动画包装组件，为子组件添加基于 Framer Motion 的动画效果，包括淡入和Y轴位移。
  • AuthorCard.tsx: 作者信息卡片，用于博客文章页面，显示作者头像、姓名、简介和社交媒体链接。
  • ShareButtons.tsx: 社交媒体分享按钮组件，用于博客文章页面，支持 Twitter、LinkedIn、Facebook 分享和链接复制。
• 博客组件 (src/components/blog/): 专门用于博客功能的组件集合：
  • BlogList.astro: 博客文章列表组件，支持分类和标签筛选，展示文章标题、描述、特色图片和阅读链接。
  • CategoryCard.astro: 博客分类卡片组件，用于展示和筛选文章分类，支持多语言。
  • TagCard.astro: 博客标签卡片组件，用于展示和筛选文章标签，支持多语言。
  • PostMeta.astro: 博客文章元数据组件，展示发布日期、阅读时间等信息。
• 布局组件 (src/layouts/): 用于页面布局的组件：
  • Layout.astro: 基础布局组件，定义了页面的基本HTML结构、元数据、字体引入、全局CSS样式和主题切换逻辑。
  • BlogLayout.astro: 博客页面布局组件，继承自 Layout，添加了博客特定的样式和结构。
  • BlogPostLayout.astro: 博客文章页面布局组件，用于展示单篇博客文章，集成了作者信息、目录导航和文章导航功能。
• UI 组件 (src/components/ui/): 基于 Shadcn UI 风格，提供可复用的基础 UI 元素：
  • button.tsx: 按钮组件，支持多种变体和尺寸。
  • glass-card.tsx: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion 实现悬停动画效果。
  • theme-toggle.tsx: 主题切换组件，实现亮色/暗色模式切换功能。
  • Container.tsx: 容器组件，用于统一页面内容的宽度和边距。
• 工具函数 (src/utils/): 提供各种实用功能：
  • blog-utils.ts: 博客相关工具函数，包括获取文章、排序、按分类和标签过滤等功能。
  • lib/utils.ts: 通用工具函数，如类名合并等。
• 数据管理 (src/lib/):
  • data.ts: 集中管理个人信息和项目数据，支持多语言。
• UI 辅助库:
  • class-variance-authority: 用于创建可变样式的组件。
  • clsx 和 tailwind-merge: 用于有条件地组合和合并 Tailwind CSS 类名。
  • tw-animate-css: 用于集成 Animate.css 的 Tailwind CSS 插件。

4. 目录结构

zhaoguiyang.site/
├── .github/                # GitHub 相关配置
├── public/                 # 静态资源
│   ├── assets/             # 图片、字体等资源
│   └── favicon.svg        # 网站图标
├── src/                    # 源代码
│   ├── components/         # React 组件
│   │   ├── blog/           # 博客相关组件
│   │   │   ├── BlogList.astro        # 博客文章列表组件
│   │   │   ├── CategoryCard.astro    # 分类卡片组件
│   │   │   ├── PostMeta.astro        # 文章元数据组件
│   │   │   └── TagCard.astro         # 标签卡片组件
│   │   ├── ui/             # UI 组件
│   │   │   ├── button.tsx            # 按钮组件
│   │   │   ├── Container.tsx         # 容器组件
│   │   │   ├── glass-card.tsx        # 玻璃效果卡片组件
│   │   │   └── theme-toggle.tsx      # 主题切换组件
│   │   ├── AuthorCard.tsx            # 作者信息卡片组件
│   │   ├── Footer.tsx               # 页脚组件
│   │   ├── GlassHeader.tsx          # 玻璃效果导航栏组件
│   │   ├── LanguageSwitcher.tsx     # 语言切换组件
│   │   ├── MotionWrapper.tsx        # 动画包装组件
│   │   ├── ShareButtons.tsx         # 社交分享按钮组件
│   │   ├── SkillsMarquee.tsx        # 技能标签滚动组件
│   │   └── TypewriterEffect.tsx     # 打字机效果组件
│   ├── i18n/               # 国际化相关
│   │   ├── ui.ts           # UI 文本翻译
│   │   └── utils.ts        # 国际化工具函数
│   ├── layouts/            # Astro 布局组件
│   │   ├── BlogLayout.astro         # 博客页面布局
│   │   ├── BlogPostLayout.astro     # 博客文章页面布局
│   │   └── Layout.astro             # 基础页面布局
│   ├── lib/                # 工具库
│   │   ├── data.ts         # 个人信息和项目数据
│   │   └── utils.ts        # 通用工具函数
│   ├── pages/              # 页面
│   │   ├── blog/           # 博客页面
│   │   │   ├── index.astro           # 博客首页
│   │   │   ├── category/             # 分类页面
│   │   │   ├── tag/                  # 标签页面
│   │   │   └── posts/                # 博客文章
│   │   ├── projects.astro            # 项目页面
│   │   ├── index.astro               # 首页
│   │   └── zh/             # 中文页面
│   │       ├── blog/       # 中文博客页面
│   │       │   ├── index.astro       # 中文博客首页
│   │       │   ├── category/         # 中文分类页面
│   │       │   ├── tag/              # 中文标签页面
│   │       │   └── posts/            # 中文博客文章
│   │       ├── projects.astro        # 中文项目页面
│   │       └── index.astro           # 中文首页
│   ├── styles/             # 样式
│   │   └── global.css      # 全局样式
│   ├── types/              # TypeScript 类型定义
│   │   └── index.ts        # 类型定义文件
│   └── utils/              # 工具函数
│       └── blog-utils.ts   # 博客相关工具函数
├── .gitignore              # Git 忽略文件
├── astro.config.mjs        # Astro 配置
├── package.json            # 项目依赖
├── pnpm-lock.yaml          # pnpm 锁文件
├── tailwind.config.cjs     # Tailwind CSS 配置
└── tsconfig.json           # TypeScript 配置

5. 关键文件说明

• astro.config.mjs: Astro 配置文件，定义了项目的构建设置、集成（React、TailwindCSS、MDX）和国际化支持。
• tailwind.config.cjs: Tailwind CSS 配置文件，定义了自定义主题、颜色、动画、插件和其他 Tailwind 相关设置。
• src/i18n/ui.ts: 包含所有 UI 文本的翻译，按语言（英文和中文）组织，包括导航、按钮、标题和描述等文本。
• src/i18n/utils.ts: 提供国际化相关的实用函数，如 useTranslations（获取翻译文本）和 getLocalizedPath（处理多语言路径）。
• src/lib/data.ts: 集中管理个人信息（姓名、位置、邮箱、社交媒体链接、职位、描述、关于、统计数据、技能等）和项目数据（标题、描述、图片、链接、技术栈等），支持多语言。
• src/lib/utils.ts: 包含通用工具函数，如 cn（合并类名）等。
• src/utils/blog-utils.ts: 提供博客相关工具函数，包括根据语言获取文章、按日期排序、按类别和标签过滤文章等功能。
• src/styles/global.css: 全局 CSS 样式，包括 Tailwind 指令、自定义 CSS 变量（亮色和暗色主题的颜色方案）和博客相关样式。
• src/types/index.ts: 集中定义项目中使用的 TypeScript 类型和接口，如 Project、Author、SocialLink 等。

6. 国际化实现

项目使用自定义的国际化解决方案，主要包括以下部分：

1. 语言定义: 在 src/i18n/ui.ts 中定义所有支持的语言（英文和中文）和翻译文本，使用 TypeScript 类型确保翻译的完整性。
2. 工具函数:
   • src/i18n/utils.ts 中的 useTranslations 函数用于获取当前语言的翻译文本
   • getLocalizedPath 函数用于处理多语言路径，根据当前语言生成正确的 URL
3. 目录结构: 使用 /zh/ 前缀区分中文页面，默认路径为英文页面。所有页面内容都有对应的中英文版本。
4. 语言切换: 通过 LanguageSwitcher.tsx 组件实现语言切换功能，使用 Framer Motion 实现动画效果，并根据选择的语言更新 URL 路径。
5. 数据国际化: 在 src/lib/data.ts 中，所有个人信息和项目数据都支持多语言，根据当前语言显示相应的内容。

7. 数据流和状态管理

项目使用简单的数据流模式，主要通过以下方式管理数据和状态：

1. 静态数据: 大部分内容（如个人信息、工作经历、技能、项目）存储在 src/lib/data.ts 中，作为静态数据导出，支持多语言。
2. 国际化文本: UI 文本存储在 src/i18n/ui.ts 中，通过 useTranslations 钩子在组件中获取当前语言的翻译文本。
3. 主题状态: 使用 localStorage 和 DOM 操作管理主题状态（亮色/暗色），通过 theme-toggle.tsx 组件实现切换功能，并在页面加载时通过 useEffect 钩子恢复主题设置。
4. 博客文章: 使用 Markdown/MDX 文件存储博客文章内容，通过 Astro 的 import.meta.glob 在构建时处理，支持按分类和标签筛选。
5. 组件状态: 使用 React 的 useState 和 useEffect 钩子管理组件内部状态，如打字机效果的当前文本、技能标签滚动的动画控制等。
6. 动画状态: 使用 Framer Motion 的 animate、initial、whileHover 等属性和 useAnimationControls 钩子管理动画状态。

项目没有使用复杂的状态管理库（如 Redux 或 MobX），因为大部分内容是静态的，不需要复杂的状态管理。组件之间的通信主要通过 props 传递和上下文（如当前语言）实现。

8. 博客功能

博客功能主要通过以下方式实现：

1. 内容管理: 使用 Markdown/MDX 文件存储博客文章，位于 src/pages/blog/posts/ 和 src/pages/zh/blog/posts/ 目录，支持 Markdown 语法和 React 组件的混合使用。
2. 文章列表: 通过 src/pages/blog/index.astro 和 src/pages/zh/blog/index.astro 实现博客文章列表页面，使用 import.meta.glob 读取所有文章，并处理文章数据。
3. 分类和标签: 支持按分类和标签筛选文章，通过 CategoryCard.astro 和 TagCard.astro 组件实现，从所有文章中提取分类和标签，并生成对应的链接。
4. 文章元数据: 每篇文章包含标题、描述、日期、作者、分类、标签、特色图片等元数据，通过 Markdown frontmatter 定义。
5. 阅读时间: 自动计算文章的阅读时间，通过 PostMeta.astro 组件显示。
6. 作者信息: 通过 AuthorCard.tsx 组件显示作者信息，包括头像、姓名、简介和社交媒体链接。
7. 社交分享: 通过 ShareButtons.tsx 组件实现社交媒体分享功能，支持 Twitter、LinkedIn、Facebook 分享和链接复制。
8. 博客工具函数: 在 src/utils/blog-utils.ts 中提供博客相关工具函数，包括获取文章、排序、按类别和标签过滤等功能。

9. 项目功能

项目展示功能主要通过以下方式实现：

1. 项目数据: 在 src/lib/data.ts 中定义项目数据，包括标题、描述、图片、链接、技术栈等信息，支持多语言。
2. 项目列表: 通过 src/pages/projects.astro 和 src/pages/zh/projects.astro 实现项目列表页面，根据当前语言获取项目数据。
3. 项目卡片: 使用 glass-card.tsx 组件展示项目信息，实现玻璃拟态效果和悬停动画效果，使用 Framer Motion 进行动画处理。
4. 响应式设计: 项目列表页面采用响应式设计，在不同设备尺寸下自动调整布局和显示方式。

10. 主题切换

项目支持亮色/暗色主题切换，主要通过以下方式实现：

1. 主题定义: 在 src/styles/global.css 中定义亮色和暗色主题的 CSS 变量，包括背景色、文本色、边框色等。
2. 主题切换组件: 通过 src/components/ui/theme-toggle.tsx 组件实现主题切换功能，通过操作 document.documentElement 的 classList 来改变主题。
3. 主题持久化: 使用 localStorage 存储用户的主题偏好，在页面加载时通过 useEffect 钩子恢复主题设置。
4. 系统主题检测: 支持检测系统主题偏好，并自动应用相应的主题。

11. 特殊效果和动画

项目使用多种技术实现特殊效果和动画，主要包括：

1. 玻璃拟态效果: 通过 glass-card.tsx 和 GlassHeader.tsx 组件实现玻璃拟态效果，使用 CSS 的 backdrop-filter 和 background-color 属性。
2. 打字机效果: 通过 TypewriterEffect.tsx 组件实现打字机效果，支持单文本或文本数组的循环显示、自定义打字/删除速度、延迟和光标样式，使用 Framer Motion 和 React hooks 实现。
3. 技能标签滚动: 通过 SkillsMarquee.tsx 组件实现技能标签的无限滚动效果，使用 Framer Motion 的 animate 和 useAnimationControls 实现，支持自定义滚动方向和速度。
4. 动画包装: 通过 MotionWrapper.tsx 组件为子组件添加基于 Framer Motion 的动画效果，包括淡入和Y轴位移，提供统一的动画处理方式。
5. 悬停动画: 多个组件（如 glass-card.tsx、按钮等）实现了悬停动画效果，通过 Framer Motion 的 whileHover 属性实现。
6. 页面过渡: 页面元素的入场动画，通过 Framer Motion 的 initial、animate 和 exit 属性实现。

6. 数据流和状态管理

• 静态数据驱动：项目主要依赖 src/lib/data.ts 中的静态数据来渲染内容。这意味着大部分内容在构建时就已经确定，无需复杂的运行时数据获取或状态管理。
• 博客内容管理：博客文章使用 Markdown 文件存储在 src/pages/blog/posts/ 和 src/pages/zh/blog/posts/ 目录中，通过 Astro 的 import.meta.glob 功能在构建时读取和处理。
• 无复杂状态管理：由于项目性质（个人简历/作品集/博客），没有引入 Redux、Zustand 或 React Context 等复杂的状态管理库。组件的状态管理主要通过 React 自身的 useState 和 useEffects Hook 在组件内部完成，或者通过 props 从父组件传递。
• 国际化数据流：src/i18n/ui.ts 提供翻译文本，src/i18n/utils.ts 提供辅助函数来处理语言切换和文本获取，确保多语言内容正确显示。

7. 博客功能

项目实现了完整的博客功能，主要特点包括：

• Markdown 支持：使用 Astro 的 Markdown 集成，支持在 Markdown 文件中编写博客文章。
• 前置元数据：通过 Markdown 文件的 frontmatter 部分定义文章的标题、描述、发布日期、标签、分类等元数据。
• 多语言支持：博客文章支持英文和中文两种语言，分别存储在不同的目录中。
• 分类和标签：支持对文章进行分类和添加标签，并提供按分类/标签筛选文章的功能。
• 文章导航：在文章页面提供上一篇/下一篇导航功能，方便读者浏览相关内容。
• 目录导航：自动生成文章目录，支持点击跳转到对应章节。
• 作者信息：在文章页面展示作者信息，包括头像、简介和社交媒体链接。
• 分享功能：提供社交媒体分享按钮，方便读者分享文章。
• 响应式设计：博客页面适配各种屏幕尺寸，提供良好的移动端体验。

8. 构建和部署

• 构建命令：项目使用 pnpm run build 命令进行构建。此命令会触发 Astro 的构建过程，将项目编译为静态文件，输出到 dist/ 目录。
• 开发环境：使用 pnpm run dev 启动开发服务器，支持热重载和实时预览。
• 预览构建：使用 pnpm run preview 预览构建后的静态文件。
• 部署：由于是静态网站，构建产物可以直接部署到任何静态文件托管服务，如 Netlify, Vercel, GitHub Pages 等。

9. AI 代码重构和功能开发指南

在进行代码重构或新功能开发时，请遵循以下原则：

• 保持 Astro 核心优势：优先使用 Astro 的 Islands 架构，确保大部分内容以静态 HTML 形式提供，仅在必要时水合（hydrate）交互式组件。
• React 组件化：对于需要交互的 UI 部分，使用 React 进行组件化开发，并确保组件是可复用和可测试的。
• Tailwind CSS 优先：样式应通过 Tailwind CSS 实用程序类实现。只有在 Tailwind 无法满足需求时，才考虑使用自定义 CSS。
• Framer Motion 动画：所有动画效果通过 Framer Motion 实现，保持动画逻辑的统一性。
• 国际化支持：所有用户可见的文本通过 src/i18n/ui.ts 进行管理，确保新功能也支持多语言。
• 数据驱动：新功能所需的数据集中管理，例如添加到 src/lib/data.ts 中，而不是硬编码在组件内部。
• 性能优化：关注 Lighthouse 等工具的性能指标，确保代码更改不会引入性能瓶颈。
• 可访问性：确保所有 UI 元素都符合 WCAG 标准，特别是对于交互式组件。
• 代码质量：遵循 TypeScript 最佳实践，编写清晰、可读、有注释的代码。
• 测试：对于复杂逻辑或关键组件，考虑编写单元测试或集成测试。
• 博客功能扩展：在扩展博客功能时，保持与现有的文件结构和数据流一致，确保新功能与多语言支持兼容。

10. 潜在的改进和扩展方向

• CMS 集成：将静态数据（如项目、博客文章）迁移到 CMS（如 Contentful, Sanity, Strapi），实现更灵活的内容管理。
• 博客功能增强：
  • 添加评论系统（如 Disqus, Giscus）
  • 实现文章搜索功能
  • 添加相关文章推荐
  • 支持更多的内容格式（如代码高亮、数学公式）
• 国际化完善：除了文本，考虑图片、日期格式等内容的国际化。
• 性能监控：集成 Web Vitals 监控，持续跟踪网站性能。
• SEO 优化：进一步优化元标签、结构化数据等，提升搜索引擎排名。
• 无障碍优化：深入研究 ARIA 属性和键盘导航，提升无障碍体验。
• 动画库扩展：探索 Framer Motion 更多高级特性，或集成其他动画库以实现更丰富的视觉效果。
• 组件库扩展：基于 Radix UI 或其他无头 UI 库构建更多可复用的组件。
• 测试框架引入：引入 Vitest 或 React Testing Library 等测试框架，提高代码质量和可维护性。
• 交互式项目展示：为项目展示部分添加更多交互元素，如项目详情模态框、项目筛选等。
• 暗色模式优化：进一步完善暗色模式的视觉效果和用户体验。
• 性能优化：实现图片懒加载、代码分割等技术，提升页面加载速度。