chore(ai): 新增 CLAUDE.md

2026-05-31 01:00:04 -04:00 · 2026-04-25 14:22:26 +08:00
parent f12db2071e
commit 6ad88b733d
1 changed files with 101 additions and 0 deletions
@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+基于 [Fuwari](https://github.com/saicaca/fuwari) 的静态博客，使用 Astro 6.1 + TailwindCSS 3.4 + Svelte 5。
+
+- **包管理器**: pnpm 9（`preinstall` hook 强制只允许 pnpm）
+- **语言**: TypeScript (strict)
+- **代码规范**: Biome（同时负责 format 和 lint），无 ESLint/Prettier
+- **部署**: Cloudflare Pages（见 `wrangler.toml`）
+
+## 常用命令
+
+| 命令 | 用途 |
+|---|---|
+| `pnpm dev` | 启动本地开发服务器 (`localhost:4321`) |
+| `pnpm build` | 构建生产版本到 `./dist/` 并运行 Pagefind 索引 |
+| `pnpm preview` | 本地预览构建产物 |
+| `pnpm check` | 运行 Astro 类型检查 |
+| `pnpm type-check` | 运行 TypeScript 类型检查 (`tsc --noEmit`) |
+| `pnpm format` | Biome 格式化 `./src` |
+| `pnpm lint` | Biome 检查和修复 `./src` |
+| `pnpm new-post <filename>` | 在 `src/content/posts/` 创建新文章 Markdown |
+| `pnpm astro` | 直接调用 Astro CLI |
+
+## 项目结构
+
+```
+src/
+├── config.ts              # 站点主配置（标题、导航、个人资料、许可证等）
+├── content.config.ts      # Astro Content Collections 定义（posts + spec）
+├── content/
+│   ├── posts/             # 博客文章（.md / .mdx），通过文件系统集合加载
+│   └── spec/              # 特殊页面集合
+├── components/
+│   ├── widget/            # 侧边栏组件（Profile, TOC, Tags, Categories 等）
+│   ├── control/           # 交互控件（BackToTop, Pagination, ButtonLink 等）
+│   ├── misc/              # 杂项（ImageWrapper, License, Markdown）
+│   └── *.astro/*.svelte   # 页面级组件（Navbar, Footer, Search, PostPage 等）
+├── pages/
+│   ├── [...page].astro    # 首页分页路由
+│   ├── posts/[...slug].astro  # 文章详情页
+│   ├── archive.astro      # 归档页
+│   ├── about.astro        # 关于页
+│   ├── friends.astro      # 友链页
+│   ├── rss.xml.ts         # RSS 生成
+│   └── robots.txt.ts      # robots.txt
+├── layouts/
+│   ├── Layout.astro       # 根布局（SEO、主题、Umami 分析、PhotoSwipe）
+│   └── MainGridLayout.astro # 主网格布局（导航栏、Banner、侧边栏、TOC）
+├── plugins/               # Remark/Rehype 插件 + Expressive Code 插件
+├── i18n/                  # 多语言翻译（en, zh_CN, ja, ko 等）
+├── utils/                 # 工具函数（content-utils, date-utils, url-utils, setting-utils）
+├── types/                 # TypeScript 类型定义
+├── constants/             # 常量（分页大小、主题模式、Banner 高度等）
+└── styles/                # CSS 文件（main.css, markdown.css, scrollbar.css 等）
+```
+
+## 关键架构信息
+
+### 内容管理
+- 文章以 Markdown/MDX 格式存储在 `src/content/posts/`
+- 使用 Astro Content Collections 加载，schema 在 `content.config.ts` 中定义
+- 文章 frontmatter 包含: `title`, `published`, `description`, `image`, `tags`, `category`, `draft`, `lang`, `showcover`, `customcover` 等
+
+### 路由
+- `[...page].astro` — 首页分页
+- `posts/[...slug].astro` — 文章详情页，生成 JSON-LD 结构化数据
+- `archive.astro` — 归档，tags，categories
+- 自定义页面: `about.astro`, `friends.astro`
+
+### 路径别名（tsconfig 配置）
+- `@/*` → `src/*`，`@components/*` → `src/components/*`，`@assets/*` → `src/assets/*`
+- `@utils/*` → `src/utils/*`，`@i18n/*` → `src/i18n/*`
+- `@layouts/*` → `src/layouts/*`，`@constants/*` → `src/constants/*`
+
+### 页面过渡
+- 使用 Swup 实现 SPA 风格页面过渡
+- 支持自定义滚动条 (`OverlayScrollbars`)，图片点击放大 (`PhotoSwipe`)
+
+### Markdown 扩展
+- GitHub Admonitions (note, tip, important, caution, warning)
+- GitHub 仓库卡片，数学公式 (KaTeX)
+- 扩展代码块 (Expressive Code) 支持折叠、行号、复制按钮、语言徽章
+- 自动标题锚点链接
+
+### 外部服务
+- **分析**: Umami（自建）+ Google Analytics
+- **评论**: Giscus（基于 GitHub Discussions）
+- **搜索**: Pagefind（构建时生成搜索索引）
+- **统计**: 通过 Umami API 获取文章浏览量
+
+## 注意事项
+
+- `src/config.ts` 是站点配置中心
+- 构建会先运行 `astro build`，然后执行 `pagefind --site dist` 生成搜索索引
+- Biome 不处理 CSS 文件（在 `biome.json` 中排除）
+- Svelte 组件使用 Svelte 5 语法
+- 主题色基于 CSS 变量 `--hue` 动态计算