# AGENTS.md - MyBlog 编码指南

本文档为在此 VuePress 博客项目中工作的智能编码助手提供指南。

## 项目概述

这是一个基于以下技术构建的个人博客：
- **框架**: VuePress v2 (静态站点生成器)
- **主题**: VuePress Theme Hope
- **语言**: TypeScript + Vue 3
- **构建工具**: Vite
- **包管理器**: npm

## 构建/代码检查/测试命令

### 开发
```bash
# 启动开发服务器
npm run docs:dev

# 清除缓存后启动开发服务器
npm run docs:clean-dev

# 构建生产版本
npm run docs:build

# 更新 VuePress 包
npm run docs:update-package

# 更新 browserslist 数据库
npm run update:browsers
```

### 测试与质量
本项目没有配置显式的测试命令。由于是 VuePress 博客：
- package.json 中没有配置单元测试
- 通过 `npm run docs:build` 进行构建验证
- 通过 `npm run docs:dev` 进行开发服务器验证

### 类型检查
```bash
# TypeScript 类型检查（如果需要）
npx tsc --noEmit
```

## 代码风格指南

### 文件结构
```
src/
├── .vuepress/          # VuePress 配置
│   ├── config.ts       # 站点配置
│   ├── theme.ts        # 主题配置
│   ├── navbar.ts       # 导航栏配置
│   ├── sidebar.ts      # 侧边栏配置
│   ├── styles/         # 自定义样式
│   └── components/     # Vue 组件
├── programming/        # 编程相关文章
├── apps/              # 应用部署指南
├── tools/             # 工具分享
├── work/              # 工作日志
└── README.md          # 首页
```

### TypeScript 配置
- **模块系统**: ES 模块 (package.json 中的 `"type": "module"`)
- **目标版本**: ES2022
- **模块解析**: NodeNext
- **包含文件**: `src/.vuepress/**/*.ts` 和 `src/.vuepress/**/*.vue`

### 导入语句
- 使用 ES 模块导入: `import { defineUserConfig } from "vuepress";`
- 需要时显式导入类型
- 分组导入：框架导入在前，本地导入在后
- 使用 config.ts 中定义的路径别名（如果可用）

### TypeScript 使用
- 所有配置文件都使用 TypeScript
- 为函数参数和返回值定义显式类型
- 对复杂数据结构使用接口
- 结合 TypeScript 使用 Vue 3 的 Composition API

### Vue 组件
- 使用 Vue 3 Composition API 和 `<script setup>` 语法
- 使用 TypeScript 接口定义 props
- 使用 `ref()` 和 `reactive()` 处理响应式状态
- 遵循现有组件的 VuePress 组件模式

### Markdown 文件
- 使用 YAML frontmatter 存储元数据：
  ```yaml
  ---
  title: 文章标题
  icon: simple-icons:iconname
  date: YYYY-MM-DD
  category:
    - 分类名称
  tag:
    - 标签1
    - 标签2
  ---
  ```
- 包含 `<!-- more -->` 标签作为文章摘要
- 使用中文内容 (zh-CN)
- 遵循现有文章结构，包含清晰的章节

### 命名约定
- **文件**: Markdown 文件使用 kebab-case，Vue 组件使用 PascalCase
- **变量**: camelCase
- **常量**: UPPER_SNAKE_CASE
- **函数**: camelCase，描述性名称
- **类型/接口**: PascalCase
- **目录**: kebab-case

### 错误处理
- 对异步操作使用 try-catch
- 验证配置对象
- 提供有意义的错误信息
- 适当记录错误（开发时使用 console.error）

### 格式化
- **缩进**: 2 个空格（不使用制表符）
- **行长度**: 目标 80-100 个字符
- **分号**: 使用分号
- **引号**: 字符串使用单引号，模板字面量使用反引号
- **尾随逗号**: 在多行对象和数组中使用

### CSS/样式
- 使用 SCSS 进行自定义样式（已安装 sass-embedded）
- 自定义类遵循 BEM 命名约定
- 使用 CSS 自定义属性（变量）进行主题化
- 利用 VuePress Theme Hope 的内置样式

### Git 实践
- **提交消息**: 使用约定式提交格式
- **分支命名**: feature/描述, fix/描述, docs/描述
- **.gitignore**: 已配置为忽略 node_modules、dist、缓存文件

### 配置文件
- **config.ts**: 主要 VuePress 配置
- **theme.ts**: 主题自定义
- **navbar.ts**: 导航结构
- **sidebar.ts**: 侧边栏组织
- 遵循这些文件中的现有模式

### 性能考虑
- 优化 `src/.vuepress/public/` 中的图片
- 对图片使用懒加载 (`imgLazyload: true`)
- 通过仅导入所需组件来最小化打包大小
- 使用 VuePress 内置优化

### 可访问性
- 使用语义化 HTML 元素
- 为图片提供 alt 文本
- 确保正确的标题层级
- 保持键盘导航支持

### 国际化
- 主要语言: 中文 (zh-CN)
- 在 `config.ts` 中配置: `lang: "zh-CN"`
- 所有面向用户的内容使用中文
- 保持一致的术语

### 部署
- 构建输出: `src/.vuepress/dist/`
- 兼容静态托管
- 如果需要，在 `config.ts` 中配置基础路径
- 确保所有相对路径正常工作

## 智能助手特定指令

1. **修改前**: 始终运行 `npm run docs:dev` 验证更改是否有效
2. **修改后**: 运行 `npm run docs:build` 确保生产构建成功
3. **添加文章时**: 遵循现有的 frontmatter 和结构模式
4. **修改配置时**: 检查现有配置文件中的模式
5. **创建组件时**: 放置在 `src/.vuepress/components/` 并遵循 Vue 3 模式
6. **更新依赖时**: 使用 `npm run docs:update-package` 更新 VuePress 包

## 常见任务

### 添加新文章
1. 在适当目录中创建 Markdown 文件
2. 添加包含标题、日期、分类、标签的 YAML frontmatter
3. 编写包含清晰章节标题的内容
4. 包含 `<!-- more -->` 标签作为摘要
5. 如果需要，添加到侧边栏配置

### 修改主题
1. 编辑 `src/.vuepress/theme.ts`
2. 查阅 VuePress Theme Hope 文档
3. 在开发模式下测试更改
4. 验证生产构建

### 添加自定义组件
1. 在 `src/.vuepress/components/` 中创建 Vue 组件
2. 如果需要，在配置中注册
3. 在 Markdown 或其他组件中导入并使用
4. 在开发中测试

### 更新导航
1. 编辑 `src/.vuepress/navbar.ts`
2. 遵循现有结构
3. 测试导航功能
4. 验证移动端响应性

## 故障排除

### 常见问题
- **构建失败**: 检查 TypeScript 错误、缺失的依赖
- **开发服务器无法启动**: 尝试 `npm run docs:clean-dev`
- **图片无法加载**: 验证 `public/` 目录中的路径
- **样式未应用**: 检查 SCSS 编译、导入顺序

### 调试
1. 检查浏览器控制台中的错误
2. 验证终端中的 VuePress 日志
3. 在开发者工具中检查生成的 HTML
4. 如果需要，使用干净缓存测试