SuBlog/AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

SuBlog（尼克的小窝）— 个人技术博客，基于 Nuxt 3 + TypeScript，使用 @nuxt/content v3 管理 Markdown 文章。

常用命令

pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm generate     # 静态站点生成
pnpm preview      # 预览构建产物
pnpm new-post <name>  # 创建新文章（自动生成 frontmatter 和图片目录）

项目使用 pnpm 作为包管理器。

架构要点

内容系统

• 文章放在 content/posts/<slug>/index.md，图片放在同级 img/ 目录
• 使用 @nuxt/content v3 的 queryCollection('posts') API 查询文章
• frontmatter 字段：title, published(日期), description, image, draft, tags, pinned
• pinned 字段控制文章置顶排序
• 构建时 nuxt.config.ts 中的 hook 自动将 content/posts/<slug>/img/ 复制到产物目录
• 开发模式图片通过 server/routes/posts/[slug]/img/[...file].ts 读取源文件

新增文章流程

1. 执行 pnpm new-post <slug> 自动生成目录结构和模板
2. 脚本会创建 content/posts/<slug>/index.md（含 frontmatter 模板）和 content/posts/<slug>/img/ 目录
3. 填写 frontmatter（description、tags 必填），编写正文
4. 封面图放在 img/ 目录下，路径为 /posts/<slug>/img/cover.jpg

页面路由

• pages/index.vue — 首页（个人名片、3D 技术栈头像、社交卡片、导航、网易云热评、不蒜子计数、文章更新入口）
• pages/posts/index.vue — 文章列表（搜索、标签过滤、分页）
• pages/posts/[slug].vue — 文章详情（Giscus 评论、右侧 TOC 目录）
• pages/[...slug].vue — 兜底路由
• 其他页面：cover(封面制作)、friends(友链)、sponsor(赞助)、about(关于)

组件分层

• components/layout/ — NavBar（面包屑导航 + 头像旋转）、AvatarOrbit（首页 3D 技术栈头像）、Footer、ThemeToggle
• components/blog/ — PostCard、PostToc（基于 IntersectionObserver 的目录）、Giscus
• components/content/ProseImg.vue — 覆盖 @nuxt/content 默认图片组件，支持相对路径解析

工具层

• composables/usePostSearch.ts — 客户端搜索 composable，支持标题/描述/正文/标签多维过滤和高亮
• utils/content-ast.ts — Nuxt Content v3 AST 工具函数（文本提取、标题提取、slugify、去重）
• config/site.ts — 全站配置（站点信息、导航、社交链接、友链、赞助、Giscus）

主题与样式

• Tailwind CSS + @tailwindcss/typography，暗色模式使用 class 策略
• CSS 变量定义在 assets/css/main.css（--color-bg, --color-primary 等）
• 暗色模式通过 .dark class 切换
• 动画类：anim-fade-in-up、anim-delay-N

服务端

• server/routes/api/wyy.ts — 网易云热评 API 代理

开发规范

文章标签规范

• 使用语言/框架的官方名称，首字母大写：Go（非 Golang）、TypeScript（非 typescript）
• 框架/库名保持官方写法：Nuxt、SvelteKit、Tailwind CSS、Docker
• 中文分类标签：运维、后端、前端框架、踩坑、博客
• 缩写保持大写：MCP、CSS、API、SQL

工作流程

• 效率至上：快速单元式开发
• 改完即退：完成代码修改后立即退出，用户会手动测试
• 单元提交：每个功能/修改单独提交到 Git
• 非用户要求不输出多余内容

编辑规则

• 编辑文件仅使用 Read 和 Edit 工具，不使用 Python/PowerShell/Bash 修改文件
• Edit 工具使用函数签名等唯一字符串做锚点，避免 tab 缩进匹配问题

Git 提交规范

• feat: 新功能 | fix: 修复 | refactor: 重构 | style: 样式 | perf: 性能 | chore: 构建/工具/配置