# AGENTS.md - AI 编码代理项目指南

本文档为 AI 编码代理提供本项目的详细背景信息，帮助快速理解和高效协作。

## 项目概述

这是一个基于 **Hexo** 静态站点生成器的个人技术博客，使用 **NexT** 主题（Mist 方案）。博客主要聚焦 Java 技术、前端开发（React）、架构设计、AI 应用等技术文章，同时包含个人成长、职业规划等内容。

- **站点标题**: 正儿八经 - 资深技术专家
- **作者**: Gamehu
- **语言**: 中文（zh-CN）
- **时区**: Asia/Shanghai
- **站点 URL**: https://www.gamehu.run/

## 技术栈

| 类别 | 技术 |
|------|------|
| 静态站点生成器 | Hexo 6.3.0 |
| 主题 | NexT 8.12.2 (Mist 方案) |
| 模板引擎 | Nunjucks (.njk)、EJS |
| 样式预处理 | Stylus |
| 包管理器 | pnpm |
| 部署方式 | Git 部署到 VPS |
| 评论系统 | Waline（可选） |
| 搜索 | 本地搜索 (hexo-generator-searchdb) |

## 项目结构

```
hexo-blog/
├── _config.yml              # Hexo 主配置文件
├── _config.landscape.yml    # Landscape 主题配置（备用）
├── package.json             # 项目依赖和脚本
├── pnpm-lock.yaml           # pnpm 锁定文件
├── db.json                  # hexo-admin 数据库文件
├── CLAUDE.md                # Claude Code 专用指南
├── AGENTS.md                # 本文档
│
├── source/                  # 源文件目录
│   ├── _posts/             # 已发布的博客文章（Markdown）
│   ├── _drafts/            # 草稿文章
│   ├── _discarded/         # 已废弃文章
│   ├── _data/              # 自定义数据文件
│   │   └── styles.styl     # 自定义样式覆盖
│   ├── images/             # 全局图片资源
│   ├── uploads/            # 上传文件
│   ├── about/              # 关于页面
│   ├── categories/         # 分类页面
│   ├── tags/               # 标签页面
│   └── guestbook/          # 留言板页面
│
├── themes/                  # 主题目录
│   ├── next/               # NexT 主题（当前使用）
│   │   ├── _config.yml     # NexT 主题配置
│   │   ├── layout/         # 模板文件 (.njk)
│   │   ├── source/         # 静态资源 (css/js/images)
│   │   └── scripts/        # Hexo 脚本和辅助函数
│   └── landscape/          # Landscape 主题（备用）
│
├── scaffolds/               # 文章模板
│   ├── post.md             # 文章模板
│   ├── draft.md            # 草稿模板
│   └── page.md             # 页面模板
│
├── public/                  # 生成的静态文件（.gitignore）
└── .deploy_git/             # 部署用 Git 仓库
```

## 常用命令

### 开发环境

```bash
# 安装依赖
pnpm install

# 启动本地开发服务器（默认端口 4000）
npm run server
# 或
hexo server

# 清理生成的文件
npm run clean
# 或
hexo clean
```

### 构建与部署

```bash
# 生成静态文件
npm run build
# 或
hexo generate

# 部署到远程服务器（VPS）
npm run deploy
# 或
hexo deploy

# 一键生成并部署
hexo generate --deploy
```

### 内容创建

```bash
# 创建新文章（使用 scaffolds/post.md 模板）
hexo new post "文章标题"

# 创建草稿
hexo new draft "草稿标题"

# 发布草稿
hexo publish draft "草稿标题"

# 创建新页面
hexo new page "页面名称"
```

## 内容创作规范

### 文章 Front Matter

每篇文章必须包含以下 YAML 前置元数据：

```yaml
---
title: 文章标题
author: Gamehu
date: YYYY-MM-DD HH:mm:ss
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
---
```

### 文章资源管理

- 启用 `post_asset_folder: true`，每篇文章可拥有同名资源文件夹
- 图片引用使用 Hexo 资源标签：
  ```markdown
  {% asset_img filename.png 图片描述 %}
  ```
- 资源文件夹命名与文章文件名一致（不含扩展名）

### 写作风格

基于现有文章，博客具有以下写作特点：

1. **去 AI 味**: 内容要求自然、有个人观点、避免模板化表达
2. **口语化**: 使用轻松、生活化的语言
3. **技术深度**: 注重实战经验和个人见解
4. **结构清晰**: 使用标题、列表、代码块等组织内容

### 可用样式类

博客在 `source/_data/styles.styl` 中定义了多个自定义样式类：

| 样式类 | 用途 |
|--------|------|
| `.highlight-text` | 黄色背景标注重点 |
| `.wavy-underline` | 波浪下划线 |
| `.gradient-text` | 渐变色文字 |
| `.ai-tag` | AI 标签（带闪光动画效果）|
| `.article-quote` | 引言样式 |
| `.divider-gradient` | 渐变分隔线 |
| `.divider-wave` | 波浪分隔线 |
| `.divider-tech` | 科技感分隔线 |
| `.divider-stars` | 星空分隔线 |

使用方式：
```markdown
<span class="highlight-text">重点内容</span>
<div class="ai-tag">AI 内容</div>
```

## 主题定制

### NexT 主题配置

主题配置文件：`themes/next/_config.yml`

主要配置项：
- **Scheme**: Mist（紧凑型布局）
- **自定义样式**: `source/_data/styles.styl`
- **菜单项**: 首页、关于、标签、分类、归档
- **社交链接**: GitHub、Email
- **侧边栏**: 左侧显示，包含头像、站点概览、目录

### 自定义文件路径

NexT 支持在 `source/_data/` 下创建文件覆盖主题默认设置：

| 文件 | 用途 |
|------|------|
| `styles.styl` | 自定义 CSS 样式（已使用）|
| `head.njk` | 自定义 head 标签 |
| `header.njk` | 自定义页头 |
| `sidebar.njk` | 自定义侧边栏 |
| `footer.njk` | 自定义页脚 |
| `body-end.njk` | body 结束前的自定义内容 |

## 部署流程

### 部署配置

在 `_config.yml` 中配置：

```yaml
deploy:
  type: git
  repo:
    vps: ssh://root@104.128.95.214:28915/home/git/blog.git,master
```

### 部署步骤

1. 运行 `hexo deploy` 生成静态文件并推送到部署仓库
2. 部署触发 VPS 上的 Git Hook
3. 网站自动更新

### SEO 配置

- **Sitemap**: `sitemap.xml`（Google）和 `baidusitemap.xml`（百度）
- **RSS**: `atom.xml`
- **Robots.txt**: 位于 `source/robots.txt`

## 已安装的插件

### 核心插件
- `hexo-generator-archive` - 归档页面生成
- `hexo-generator-category` - 分类页面生成
- `hexo-generator-index` - 首页生成
- `hexo-generator-tag` - 标签页面生成
- `hexo-generator-sitemap` - Sitemap 生成
- `hexo-generator-baidu-sitemap` - 百度 Sitemap
- `hexo-generator-searchdb` - 本地搜索数据

### 功能增强
- `hexo-all-minifier` - 资源压缩（HTML/CSS/JS/图片）
- `hexo-asset-img` - 文章资源图片支持
- `hexo-deployer-git` - Git 部署
- `hexo-admin` - 后台管理界面
- `hexo-wordcount` - 字数统计
- `hexo-renderer-marked` - Markdown 渲染
- `hexo-renderer-stylus` - Stylus 渲染

### 第三方集成
- `@waline/hexo-next` - Waline 评论系统
- `hexo-next-share` - 分享功能

## 开发注意事项

### 文件修改建议

1. **不要直接修改 `themes/next/_config.yml`**: 建议通过 `source/_data/` 下的文件进行覆盖
2. **样式修改**: 在 `source/_data/styles.styl` 中添加自定义样式
3. **新文章**: 使用 `hexo new post` 创建，保持 Front Matter 一致性

### 性能优化

- CSS 和 JS 压缩已启用（`hexo-all-minifier`）
- 图片懒加载可通过主题配置启用
- 使用 CDN 加载第三方库

### 版本控制

```gitignore
# 忽略的文件
node_modules
.history
*.pdf
public
```

- `public/` 目录由 Hexo 生成，不提交到版本控制
- `.deploy_git/` 是部署用的 Git 仓库
- `db.json` 是 hexo-admin 数据文件

## 故障排查

### 常见问题

1. **本地预览空白**
   - 检查 `hexo server` 是否正常启动
   - 尝试 `hexo clean` 后重新生成

2. **样式不生效**
   - 检查 `source/_data/styles.styl` 语法
   - 确保主题配置中 `custom_file_path.style` 指向正确

3. **部署失败**
   - 检查 VPS SSH 连接
   - 验证部署仓库配置

### 调试命令

```bash
# 详细日志
hexo generate --debug

# 检查配置
hexo config

# 检查版本
hexo version
```

## 相关链接

- [Hexo 文档](https://hexo.io/docs/)
- [NexT 主题文档](https://theme-next.js.org/docs/)
- [Mermaid 图表语法](https://mermaid.js.org/)
- [Stylus 文档](https://stylus-lang.com/)

---

*本文档最后更新：2026-02-28*