feat(ssh-setup): 添加 SSH 自动化配置工具文档与脚本
- 新增 AGENTS.md，详细描述博客项目编码规范和智能助手操作指南 - 添加 ssh-setup 脚本用于交互式自动配置 SSH 连接密钥与别名 - 实现密钥生成、备份配置、自动部署公钥与连接测试功能 - 提供彩色日志输出和详细错误处理提升用户体验 - 包含安装、使用方法和故障排除说明文档 - 支持自动创建 shell 别名和配置文件更新 - 确保配置安全性和兼容多种 shell 环境
This commit is contained in:
liumangmang
218
AGENTS.md
Normal file
218
AGENTS.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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. 如果需要，使用干净缓存测试
|
||||
Reference in New Issue
Block a user