docs(guidelines): 更新编码指南并添加工作日志和开发工具文档

- 简化 AGENTS.md 文档结构，更新构建命令和代码风格指南 - 新增 2026 年 1 月工作日志记录项目进展和问题解决 - 添加 Cursor 连接 WSL 开发完整教程，涵盖环境配置和最佳实践 - 创建 SDKMAN Java 和 Maven 版本管理指南，支持多项目环境 - 编写 Windows Jabba Java 版本管理文档，提供 PowerShell 集成方案
2026-02-04 10:55:36 +08:00
parent 6d05134161
commit caae9fb69b
6 changed files with 1387 additions and 146 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,218 +1,159 @@
 # AGENTS.md - MyBlog 编码指南

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

 ## 项目概述

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

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

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

-# 清除缓存后启动开发服务器
-npm run docs:clean-dev
+# 构建与部署
+npm run docs:build            # 生产构建

-# 构建生产版本
-npm run docs:build
+# 维护
+npm run docs:update-package   # 更新 VuePress 包
+npm run update:browsers       # 更新 browserslist

-# 更新 VuePress 包
-npm run docs:update-package
-
-# 更新 browserslist 数据库
-npm run update:browsers
+# 类型检查
+npx tsc --noEmit              # TypeScript 检查
 ```

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

-### 类型检查
-```bash
-# TypeScript 类型检查（如果需要）
-npx tsc --noEmit
-```
-
-## 代码风格指南
-
-### 文件结构
 ```
 src/
-├── .vuepress/          # VuePress 配置
+├── .vuepress/
 │   ├── config.ts       # 站点配置
 │   ├── theme.ts        # 主题配置
-│   ├── navbar.ts       # 导航栏配置
+│   ├── navbar.ts       # 导航配置
 │   ├── sidebar.ts      # 侧边栏配置
-│   ├── styles/         # 自定义样式
+│   ├── styles/         # 自定义 SCSS
 │   └── components/     # Vue 组件
-├── programming/        # 编程相关文章
+├── 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
+- **模块**: ES 模块（`"type": "module"`）
+- **目标**: ES2022
+- **解析**: NodeNext
+- 函数参数和返回值使用显式类型
+- 复杂数据结构使用接口

-### TypeScript 使用
- 所有配置文件都使用 TypeScript
- 为函数参数和返回值定义显式类型
- 对复杂数据结构使用接口
- 结合 TypeScript 使用 Vue 3 的 Composition API
+### 导入
+- 使用 ES 模块：`import { defineUserConfig } from "vuepress"`
+- 分组导入：框架优先，本地其次
+- 使用 config.ts 中定义的路径别名

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

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

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

+### 格式化
+- **缩进**: 2 个空格
+- **行长度**: 80-100 字符
+- **分号**: 必需
+- **引号**: 字符串使用单引号，模板使用反引号
+- **尾随逗号**: 多行时使用
+
+### CSS/SCSS
+- 使用 SCSS（已安装 sass-embedded）
+- 自定义类遵循 BEM 命名
+- 使用 CSS 变量进行主题化
+
 ### 错误处理
- 对异步操作使用 try-catch
+- 异步操作使用 try-catch
 - 验证配置对象
 - 提供有意义的错误信息
- 适当记录错误（开发时使用 console.error）
+- 使用 console.error 进行调试

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

-### CSS/样式
- 使用 SCSS 进行自定义样式（已安装 sass-embedded）
- 自定义类遵循 BEM 命名约定
- 使用 CSS 自定义属性（变量）进行主题化
- 利用 VuePress Theme Hope 的内置样式
+- **提交**: 约定式提交格式
+- **分支**: feature/描述、fix/描述、docs/描述

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

 ## 常见任务

 ### 添加新文章
-1. 在适当目录中创建 Markdown 文件
+1. 在适当目录创建 Markdown 文件
 2. 添加包含标题、日期、分类、标签的 YAML frontmatter
-3. 编写包含清晰章节标题的内容
-4. 包含 `<!-- more -->` 标签作为摘要
-5. 如果需要，添加到侧边栏配置
-
-### 修改主题
-1. 编辑 `src/.vuepress/theme.ts`
-2. 查阅 VuePress Theme Hope 文档
-3. 在开发模式下测试更改
-4. 验证生产构建
+3. 编写包含清晰标题的内容
+4. 包含 `<!-- more -->` 摘要标记
+5. 如需则更新 sidebar.ts

 ### 添加自定义组件
-1. 在 `src/.vuepress/components/` 中创建 Vue 组件
-2. 如果需要，在配置中注册
-3. 在 Markdown 或其他组件中导入并使用
-4. 在开发中测试
-
-### 更新导航
-1. 编辑 `src/.vuepress/navbar.ts`
-2. 遵循现有结构
-3. 测试导航功能
-4. 验证移动端响应性
+1. 在 `src/.vuepress/components/` 创建
+2. 如需则在配置中注册
+3. 在 Markdown/组件中导入使用
+4. 在开发模式测试

 ## 故障排除

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

-### 调试
-1. 检查浏览器控制台中的错误
-2. 验证终端中的 VuePress 日志
-3. 在开发者工具中检查生成的 HTML
-4. 如果需要，使用干净缓存测试
+## 部署
+
+- **输出目录**: `src/.vuepress/dist/`
+- **托管**: 兼容静态托管
+- **基础路径**: 如需则在 `config.ts` 中配置
+
+## 注意事项
+
+- 未配置单元测试（仅构建验证）
+- 主要语言：中文（zh-CN）
+- 主题：VuePress Theme Hope 自定义
+- 图标：FontAwesome 6（`fa6-solid:` 前缀）