hexo-blog/AGENTS.md

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 仓库

常用命令

开发环境

# 安装依赖
pnpm install

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

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

构建与部署

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

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

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

内容创建

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

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

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

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

内容创作规范

文章 Front Matter

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

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

文章资源管理

• 启用 post_asset_folder: true，每篇文章可拥有同名资源文件夹

• 图片引用使用 Hexo 资源标签：

  {% 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	星空分隔线

使用方式：

<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 中配置：

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 加载第三方库

版本控制

# 忽略的文件
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 连接
   • 验证部署仓库配置

调试命令

# 详细日志
hexo generate --debug

# 检查配置
hexo config

# 检查版本
hexo version

相关链接

• Hexo 文档
• NexT 主题文档
• Mermaid 图表语法
• Stylus 文档

---

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