MyBlog/AGENTS.md

AGENTS.md - MyBlog 编码指南

AI 智能助手在此 VuePress 博客项目中的工作指南。

项目概述

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

构建命令

# 开发
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：

  ---
  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: 前缀）