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 图片描述 %}

资源文件夹命名与文章文件名一致（不含扩展名）

写作风格

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

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

可用样式类

博客在 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

部署步骤

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

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 - 分享功能

开发注意事项

文件修改建议

不要直接修改 themes/next/_config.yml: 建议通过 source/_data/ 下的文件进行覆盖
样式修改: 在 source/_data/styles.styl 中添加自定义样式
新文章: 使用 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 数据文件

故障排查

常见问题

本地预览空白
- 检查 hexo server 是否正常启动
- 尝试 hexo clean 后重新生成
样式不生效
- 检查 source/_data/styles.styl 语法
- 确保主题配置中 custom_file_path.style 指向正确
部署失败
- 检查 VPS SSH 连接
- 验证部署仓库配置

调试命令

# 详细日志
hexo generate --debug

# 检查配置
hexo config

# 检查版本
hexo version

AGENTS.md 8.3 KB

Istoric Crud

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

项目概述

技术栈

项目结构

常用命令

开发环境

构建与部署

内容创建

内容创作规范

文章 Front Matter

文章资源管理

写作风格

可用样式类

主题定制

NexT 主题配置

自定义文件路径

部署流程

部署配置

部署步骤

SEO 配置

已安装的插件

核心插件

功能增强

第三方集成

开发注意事项

文件修改建议

性能优化

版本控制

故障排查

常见问题

调试命令

相关链接

AGENTS.md 8.3 KB Istoric Crud

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

项目概述

技术栈

项目结构

常用命令

开发环境

构建与部署

内容创建

内容创作规范

文章 Front Matter

文章资源管理

写作风格

可用样式类

主题定制

NexT 主题配置

自定义文件路径

部署流程

部署配置

部署步骤

SEO 配置

已安装的插件

核心插件

功能增强

第三方集成

开发注意事项

文件修改建议

性能优化

版本控制

故障排查

常见问题

调试命令

相关链接

AGENTS.md 8.3 KB

Istoric Crud