MyBlog/AGENTS.md

AGENTS.md - MyBlog 编码指南

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

项目概述

这是一个基于以下技术构建的个人博客：

• 框架: VuePress v2 (静态站点生成器)
• 主题: VuePress Theme Hope
• 语言: TypeScript + Vue 3
• 构建工具: Vite
• 包管理器: npm

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

开发

# 启动开发服务器
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 进行开发服务器验证

类型检查

# 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 存储元数据：

  ---
  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. 如果需要，使用干净缓存测试