AGENTS.md

AI 代理在此代码库工作时的指导文档。

项目概述

基于 VitePress 2.0 的个人博客，使用自定义主题 vitepress-theme-newst。核心功能包括博客文章列表、标签分类、归档页面、Waline 评论系统、Algolia 搜索等。

包管理器

使用 bun 作为包管理器，不要使用 npm 或 pnpm。

构建与开发命令

# 开发服务器 (运行在 localhost:38881)
bun run dev

# 仅运行预处理脚本 (Python)
bun run prereq

# 生产构建
bun run build

# 预览构建结果
bun run preview

Python 预处理脚本

• 预处理脚本位于 scripts/ 目录
• scripts/main.py 是入口，自动运行所有 exec_*.py 和 gen_*.py 脚本
• 依赖: requirements.txt (Pillow, PyYAML, pytz, requests)
• 功能: 下载友链头像、生成 friends.json、build.json 等数据文件

测试命令

此项目无自动化测试套件。验证方式：

• 开发环境: bun run dev 手动验证
• 生产构建: bun run build 检查构建是否成功

代码风格指南

TypeScript / JavaScript

模块系统

• 强制使用 ESM (import/export)，不使用 CommonJS (require)
• package.json 中已声明 "type": "module"

导入风格

// 优先使用命名导入减少 bundle 大小
import { computed, ref } from "vue";

// 默认导入仅在必要时使用
import matter from "gray-matter";

类型定义

• 使用 TypeScript 类型注解，但 noImplicitAny: false 和 strictNullChecks: false
• 类型定义集中在 src/types.ts
• 组件 props 使用 defineProps<{ ... }>()

// 示例
const props = defineProps<{
  posts: IPost[];
  pagination: number;
}>();

函数风格

• 禁止使用 class，优先使用函数式编程
• 使用箭头函数和 const

// 推荐
const formatDate = (datetime: string) => {
  return new Date(datetime).toISOString().split('T')[0]
}

// 避免
class DateFormatter {
  format() { ... }
}

异步操作

• 使用 async/await 而非 Promise 链
• 错误处理使用 try-catch 包装

const safeExecute = async <T>(
  promise: Promise<T>,
  errorMsg: string
): Promise<T | false> => {
  try {
    return await promise;
  } catch (error) {
    console.error(errorMsg, error);
    return false;
  }
};

Vue 组件

组件结构顺序

<template>
  <!-- 模板 -->
</template>

<script lang="ts" setup>
// 导入
// 类型定义
// Props / Emits
// Composables
// 响应式状态
// 计算属性
// 方法
// 生命周期钩子
</script>

<style lang="less" scoped>
/* 样式 */
</style>

样式

• 使用 LESS 预处理器
• 使用 BEM 命名或简单嵌套
• scoped 样式优先

.home {
  display: flex;

  &__image {
    width: 18rem;
    height: 18rem;
  }
}

命名约定

• 文件名: PascalCase for components (HomeView.vue, PostList.vue)
• 变量/函数: camelCase (formatDate, filteredPosts)
• 类型/接口: PascalCase with I prefix (IPost, IPage)
• 常量: UPPER_SNAKE_CASE (REQUIRED_CONFIG, FEED_FILES)

错误处理

• 使用 try-catch 捕获错误
• 记录错误但不让应用崩溃
• 提供降级方案

try {
  return new Date(datetime).toISOString().split("T")[0];
} catch (error) {
  console.error("日期格式化错误:", error);
  return "";
}

路径别名

• @/* 映射到 src/*
• 在 tsconfig.json 和 vite.config.ts 中配置

import { IPost } from "@/types";
import { usePosts } from "@/composables/usePosts";

架构关键点

数据流

scripts/main.py (预处理)
  ↓
.vitepress/config.ts (调用 usePosts)
  ↓
主题组件 (src/views/*, src/components/*)
  ↓
.vitepress/hooks/buildEnd.ts (构建后处理)

关键模块

• src/composables/usePosts.ts: 文章加载、排序、prev/next 生成
• src/types.ts: TypeScript 类型定义
• .vitepress/hooks/buildEnd.ts: RSS/Feed 生成、搜索引擎索引
• .vitepress/config.ts: VitePress 配置和主题配置

文章 Frontmatter

---
datetime: 2024-01-01T00:00:00+0800 # 必需
lastmod: 2024-01-02T12:00:00+0800 # 必需
title: 文章标题 # 必需
description: 文章描述 # 必需
permalink: /category/slug # 必需，不含 .html
tags:
  - 标签1
order: 1 # 可选，置顶
---

• 特殊标签 特殊页面 用于非常规页面（关于、友链等）
• <!-- more --> 标记摘要分界点

重要约定

不要做

• ❌ 不要使用 class 语法
• ❌ 不要使用 CommonJS (require/module.exports)
• ❌ 不要直接修改 package.json 依赖版本（使用 bun add/remove）
• ❌ 不要跳过 linter/formatter 检查

务必做

• ✅ 使用 ESM 导入
• ✅ 使用函数式编程
• ✅ 使用 bun 管理依赖
• ✅ 运行 bun run dev 验证修改
• ✅ 检查 TypeScript 类型错误（即使配置宽松）

依赖库选择偏好

• 优先选择活跃维护、流行度高的库
• 示例: yaml 优于 js-yaml（更活跃）
• 审慎添加新依赖，优先使用已有依赖

提交前检查清单

• [ ] 代码使用 ESM 而非 CJS
• [ ] 无 class 语法
• [ ] TypeScript 无严重类型错误
• [ ] 运行 bun run build 无报错
• [ ] Vue 组件遵循推荐结构
• [ ] 样式使用 LESS 且有 scoped

特殊说明

• 此项目针对中文内容优化（i18n 配置见 .vitepress/config.ts）
• 图片懒加载已启用 (markdown.image.lazyLoading: true)
• 支持 Mermaid 图表 (vitepress-plugin-mermaid)
• 评论系统使用 Waline (@waline/client)
• 搜索使用 Algolia

相关文档

详细项目说明参见 CLAUDE.md。