caae9fb69b
- 简化 AGENTS.md 文档结构，更新构建命令和代码风格指南 - 新增 2026 年 1 月工作日志记录项目进展和问题解决 - 添加 Cursor 连接 WSL 开发完整教程，涵盖环境配置和最佳实践 - 创建 SDKMAN Java 和 Maven 版本管理指南，支持多项目环境 - 编写 Windows Jabba Java 版本管理文档，提供 PowerShell 集成方案
160 lines
4.1 KiB
Markdown
160 lines
4.1 KiB
Markdown
# 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:` 前缀）
|