# AGENTS.md - MyBlog 编码指南

AI 智能助手在此 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            # 生产构建

# 维护
npm run docs:update-package   # 更新 VuePress 包
npm run update:browsers       # 更新 browserslist

# 类型检查
npx tsc --noEmit              # TypeScript 检查
```

## 文件结构

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

## 代码风格

### TypeScript
- **模块**: ES 模块（`"type": "module"`）
- **目标**: ES2022
- **解析**: NodeNext
- 函数参数和返回值使用显式类型
- 复杂数据结构使用接口

### 导入
- 使用 ES 模块：`import { defineUserConfig } from "vuepress"`
- 分组导入：框架优先，本地其次
- 使用 config.ts 中定义的路径别名

### Vue 组件
- 使用 Vue 3 Composition API 和 `<script setup>`
- 使用 TypeScript 接口定义 props
- 使用 `ref()` 和 `reactive()` 管理状态
- 自定义组件放在 `src/.vuepress/components/`

### 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

### 格式化
- **缩进**: 2 个空格
- **行长度**: 80-100 字符
- **分号**: 必需
- **引号**: 字符串使用单引号，模板使用反引号
- **尾随逗号**: 多行时使用

### CSS/SCSS
- 使用 SCSS（已安装 sass-embedded）
- 自定义类遵循 BEM 命名
- 使用 CSS 变量进行主题化

### 错误处理
- 异步操作使用 try-catch
- 验证配置对象
- 提供有意义的错误信息
- 使用 console.error 进行调试

## Git 实践

- **提交**: 约定式提交格式
- **分支**: feature/描述、fix/描述、docs/描述

## 智能助手指令

1. **修改前**: 运行 `npm run docs:dev` 验证
2. **修改后**: 运行 `npm run docs:build` 确保构建成功
3. **新文章**: 遵循现有 frontmatter 模式
4. **配置修改**: 检查现有配置模式
5. **新组件**: 使用 Vue 3 模式，放在 components/ 目录
6. **依赖更新**: 使用 `npm run docs:update-package`

## 常见任务

### 添加新文章
1. 在适当目录创建 Markdown 文件
2. 添加包含标题、日期、分类、标签的 YAML frontmatter
3. 编写包含清晰标题的内容
4. 包含 `<!-- more -->` 摘要标记
5. 如需则更新 sidebar.ts

### 添加自定义组件
1. 在 `src/.vuepress/components/` 创建
2. 如需则在配置中注册
3. 在 Markdown/组件中导入使用
4. 在开发模式测试

## 故障排除

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

## 部署

- **输出目录**: `src/.vuepress/dist/`
- **托管**: 兼容静态托管
- **基础路径**: 如需则在 `config.ts` 中配置

## 注意事项

- 未配置单元测试（仅构建验证）
- 主要语言：中文（zh-CN）
- 主题：VuePress Theme Hope 自定义
- 图标：FontAwesome 6（`fa6-solid:` 前缀）