6d05134161
- 新增 AGENTS.md，详细描述博客项目编码规范和智能助手操作指南 - 添加 ssh-setup 脚本用于交互式自动配置 SSH 连接密钥与别名 - 实现密钥生成、备份配置、自动部署公钥与连接测试功能 - 提供彩色日志输出和详细错误处理提升用户体验 - 包含安装、使用方法和故障排除说明文档 - 支持自动创建 shell 别名和配置文件更新 - 确保配置安全性和兼容多种 shell 环境
218 lines
6.3 KiB
Markdown
218 lines
6.3 KiB
Markdown
# AGENTS.md - MyBlog 编码指南
|
||
|
||
本文档为在此 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
|
||
|
||
# 更新 VuePress 包
|
||
npm run docs:update-package
|
||
|
||
# 更新 browserslist 数据库
|
||
npm run update:browsers
|
||
```
|
||
|
||
### 测试与质量
|
||
本项目没有配置显式的测试命令。由于是 VuePress 博客：
|
||
- package.json 中没有配置单元测试
|
||
- 通过 `npm run docs:build` 进行构建验证
|
||
- 通过 `npm run docs:dev` 进行开发服务器验证
|
||
|
||
### 类型检查
|
||
```bash
|
||
# 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 存储元数据：
|
||
```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
|
||
|
||
### 错误处理
|
||
- 对异步操作使用 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. 如果需要，使用干净缓存测试 |