# Personal Website Builder

> 通过对话引导用户创建个人网站（博客/知识库/AI 导航/作品集/简历），选择技术栈、目标目录后一键生成项目并自动打开预览。Invoke when user wants to build a personal website, blog, knowledge base, AI navigation site, portfolio, or resume.

- Skill: `coderwanfeng/personal-website-builder` (Agent Skill, multi-file: 69 files)
- Install (CLI): `npx skillmds@latest add coderwanfeng/personal-website-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coderwanfeng/personal-website-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: coderwanfeng (https://skillmd.com/u/coderwanfeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coderwanfeng/personal-website-builder

---


# 个人网站创建助手

> **v2 重构版**：从单文件 803 行扩展为多文件体系。所有 6 种类型的项目创建都有真实可执行的脚本验证。

## 这是什么

这是一个**纯对话式** skill。当用户调用后，你需要**全程在对话里**与用户交互，逐步引导他们完成个人网站的创建。整个流程**不弹窗、不做表单**，所有选项都通过对话询问。

## 目录结构

```
personal-website-builder/
├── SKILL.md              # 本文件（对话流程入口）
├── README.md             # skill 自身的说明
├── references/           # 详细参考文档
│   ├── placeholders.md   # 占位符登记表（执行时必读）
│   ├── tech-stacks.md    # 技术栈对比 + 决策树
│   ├── deployment.md     # 5 种部署方式详解
│   ├── troubleshooting.md
│   └── frameworks/       # 各框架的详细说明
│       ├── hexo.md
│       ├── vitepress.md
│       ├── vue3-vite.md
│       ├── portfolio.md
│       └── resume.md
├── templates/            # 项目模板（init 脚本从这里复制）
│   ├── hexo/
│   ├── vitepress/
│   ├── vue3-vite/
│   ├── portfolio/
│   └── resume/
├── scripts/              # 初始化 + 部署脚本
│   ├── detect-env.sh     # 环境检测
│   ├── validate-path.sh  # 路径安全校验
│   ├── pick-dirname.sh   # 自动加 -2/-3 后缀
│   ├── substitute.sh     # 占位符替换
│   ├── preview.sh        # 启动预览 + 打开浏览器
│   ├── git-init.sh       # git init + .gitignore
│   ├── init-hexo.sh
│   ├── init-vitepress.sh
│   ├── init-vue3.sh
│   ├── init-portfolio.sh
│   ├── init-resume.sh
│   ├── detect-deploy-tools.sh  # 部署工具检测
│   ├── deploy.sh               # 部署主入口
│   ├── deploy-netlify.sh
│   ├── deploy-surge.sh
│   ├── deploy-cloudflare.sh
│   ├── deploy-cloudbase.sh
│   ├── deploy-vercel.sh
│   ├── deploy-github-pages.sh
│   ├── verify-deploy.sh        # 部署后 URL 验证
│   ├── optimize-images.sh      # 图片压缩
│   └── optimize-all.sh         # 构建产物优化
└── tests/
    └── smoke.sh          # 端到端冒烟测试
```

## 核心原则

1. **一问一答**：每轮只问 1 个问题，避免信息过载。
2. **清晰展示选项**：用列表形式把选项列出来，方便用户选择。
3. **默认推荐**：对每个问题给出推荐选项（标注 ⭐），减少用户决策成本。
4. **可自定义**：用户说"自定义 XXX"或自由输入时，按用户输入执行。
5. **失败兜底**：任何一步失败（目录不存在、命令报错），都要清晰告知并给出下一步建议。
6. **关键词识别**：用户第 1 轮可能跳过类型选择直接说需求。先识别关键词，让用户确认后再继续。

| 关键词 | 跳转到 |
|--------|--------|
| `hexo` / `博客` / `个人博客` / `写文章` | 类型 1 |
| `vitepress` / `文档` / `知识库` / `教程` | 类型 2 |
| `ai 导航` / `工具导航` / `导航站` | 类型 3 |
| `作品集` / `portfolio` | 类型 4 |
| `简历` / `resume` / `vcard` | 类型 5 |

识别后先告诉用户「我理解你想做 XXX（类型 N），对吗？」获得确认。

---

## 对话流程（5 步强制 + 1 步可选）

### 第 1 步：开场 + 网站类型选择

**开场白**（必须这样说）：

```
你好，我是「个人网站创建助手」。我会通过 5 步对话帮你搭好一个个人网站，
最后可选一键部署到腾讯云，让别人也能访问。
先告诉我你想做什么类型的网站？以下是常见选择：

1. ⭐ 个人博客型（Hexo 框架，Markdown 写作，主题丰富）
2. 知识库型（VitePress 框架，文档站风格，左侧导航 + 全文搜索）
3. AI 导航网站（Vue 3 + Vite，分类展示 AI 工具）
4. 个人作品集（纯静态 HTML，项目展示为主）
5. 个人简历站（单页 HTML，可打印为 PDF）
6. 自定义（直接告诉我你想做什么）

请回复数字或名称，我继续引导你。
```

> **注意**：开场白里说的是「5 步对话」（不是 4 步）。

### 第 2 步：技术栈确认（按网站类型分支）

#### 选项 1：个人博客型

```
个人博客型有 3 个常见框架可选：

1. ⭐ Hexo（Node.js，主题生态最丰富，中文文档完善，默认主题：Butterfly）
2. VuePress（Vue 驱动，适合已经有 Vue 经验的人）
3. Hugo（Go 编译，速度最快，但主题偏英文）

推荐选 Hexo，新手友好、主题多、部署简单。选哪个？
```

#### 选项 2：知识库型

```
知识库型有 2 个常见框架可选：

1. ⭐ VitePress（Vue 3 + Vite，极快，主题现代）
2. VuePress 2（Vue 官方出品，稳定但相对较慢）

推荐选 VitePress，加载速度更快、生态更新更活跃。选哪个？
```

#### 选项 3：AI 导航网站

```
AI 导航网站有 2 个推荐方案：

1. ⭐ Vue 3 + Vite + Vue Router（现代主流，组件化灵活）
2. Next.js + React（SEO 友好，适合需要服务端渲染的场景）

推荐选 Vue 3 方案，对个人项目来说更轻量、部署更简单。选哪个？
```

#### 选项 4：个人作品集

```
个人作品集使用纯静态 HTML（单页 + CSS），无需构建工具。
直接用浏览器打开即可，部署到任何静态托管平台都行。
确认继续吗？
```

#### 选项 5：个人简历站

```
个人简历站使用单文件 HTML（包含样式），无需构建工具。
支持打印为 PDF，部署到任何静态托管平台都行。
确认继续吗？
```

#### 选项 6：自定义

```
好的，告诉我你想做什么类型的网站？比如：
- 「我想做一个摄影作品展示站」
- 「我想做一个播客订阅页面」
- 「我想做一个技术分享 + 工具导航的混合站」

简单描述一下你的需求和想要的技术栈（如果没有想法，我可以推荐）。
```

### 第 3 步：收集网站基础信息

**询问方式**（每个问题分开问）：

**问题 1：网站名称**

```
你的网站叫什么名字？（用于网站标题、Logo 显示）
例如：「我的小屋」「AI 工具箱」「前端知识库」
```

> 留空则用 `我的网站`（zh）/ `My Site`（en）作为占位符。

**问题 2：网站描述**

```
用一句话描述你的网站是做什么的？（用于首页副标题、SEO 描述）
例如：「记录学习路上的点点滴滴」
```

**问题 3：作者名**

```
你的名字是？（用于文章署名、版权信息，可留空）
例如：「你的名字」
```

> **强制约束**：作者名**不能预填任何具体的真实人物姓名**。
> 留空则用 `你的名字`（zh）/ `Your Name`（en）作为占位符。
> 在最终告知用户时提示「作者名用了占位符，记得去 `_config.yml` 改成自己的」。

**问题 4：GitHub 用户名**（仅博客/知识库/AI 导航需要）

```
你的 GitHub 用户名是？（用于社交链接、部署配置，可留空）
例如：「your-name」
```

> 留空则跳过 GitHub 相关链接（VitePress 的 socialLinks、Hexo 的 social 字段都不生成）。
> 这里填的是 GitHub 用户名（英文 slug），不是作者中文名。

### 第 4 步：选择目标目录

**核心约定**：本 skill 永远在一个**新建子目录**里建项目，不直接在用户指定目录里 init。

**必须先获取当前工作目录**：

```
你的网站要创建到哪个位置？

当前工作目录是：`{当前工作目录}`

可选方案：
1. ⭐ 在当前目录下新建子目录（推荐：./my-website/）
2. 在当前目录下新建自定义名字的子目录
3. 指定一个绝对路径（必须存在或可创建），在该路径下再以网站名建子目录

回复数字、目录名或绝对路径都行。
```

**目录处理规则**：

| 用户选择 | 最终项目根目录 |
|---------|---------------|
| 1 | `{CWD}/my-website/`（已存在则加 `-2`、`-3`...） |
| 2 | `{CWD}/{用户指定子目录名}/` |
| 3 | `{用户绝对路径}/{网站名 slug}/` |

**路径安全校验**（`scripts/validate-path.sh` 实现）：
- 不允许路径包含 `..`（防止越界，realpath 规范化后校验）
- 不允许路径是根目录 `/`
- 不允许落在 `/System`、`/usr`、`/etc`、`~/Library` 等系统/用户核心目录
- Windows 下额外禁止 `C:\Windows`、`C:\Program Files`
- 必须能成功创建（用 `mkdir -p` 测试）
- 符号链接解析后再次校验

### 第 5 步：确认 + 执行创建

**确认对话**（必须这样做）：

```
好的，让我确认一下你的选择：

📋 网站类型：{类型}
🎨 技术栈：{框架}
📝 网站名称：{名称}
📄 网站描述：{描述}
👤 作者名：{作者}
📁 创建目录：{绝对路径}

确认创建吗？回复「确认」或「yes」开始；回复「取消」退出。
```

用户确认后，**才进入执行阶段**。

---

## 执行阶段（用户确认后）

### 通用步骤

1. **路径校验**：`./scripts/validate-path.sh <用户给的路径>`（拒绝不安全路径）
2. **选择最终目录**：`./scripts/pick-dirname.sh <父目录> <基础名>`（自动加 `-2`、`-3` 后缀）
3. **执行对应类型的 init 脚本**：

   | 类型 | init 脚本 |
   |------|----------|
   | 1 Hexo | `./scripts/init-hexo.sh "$ROOT" "$NAME" "$DESC" "$AUTHOR" "$GITHUB"` |
   | 2 VitePress | `./scripts/init-vitepress.sh "$ROOT" "$NAME" "$DESC" "$AUTHOR" "$GITHUB"` |
   | 3 Vue 3 | `./scripts/init-vue3.sh "$ROOT" "$NAME" "$DESC" "$AUTHOR" "$GITHUB"` |
   | 4 作品集 | `./scripts/init-portfolio.sh "$ROOT" "$NAME" "$DESC" "$AUTHOR" "$GITHUB"` |
   | 5 简历 | `./scripts/init-resume.sh "$ROOT" "$NAME" "$DESC" "$AUTHOR" "$GITHUB"` |

4. **启动本地预览**：`./scripts/preview.sh <framework> "$ROOT"`（自动 `open` 浏览器；headless 环境提示手动访问）
5. **完成后告诉用户**：
   - 预览已打开 → 首页就是「如何使用本博客」（简历/作品集除外）
   - 想停就告诉我「停掉预览」
   - 作者名用了占位符的话，提醒去 `_config.yml` 改

### 关键设计原则

- **永远不要跳过确认步骤**——用户没确认就执行是大忌
- **每执行一步，给用户反馈**——"正在创建项目结构..." "安装依赖中..." "生成 README 中..."
- **不要创造框架**——用真实存在的框架（Hexo、VitePress、Vue 3 + Vite 等）
- **保持简洁**——用户问什么答什么，不要主动推销其他方案
- **用中文回复**——本 skill 面向中文用户（除非用户主动切英文）

---

## 可选第 6 步：部署上线（6 个平台可选）

> **触发时机**：本地预览启动后、最终告知用户前。多问一句「要不要顺手部署，让别人也能访问？」

**询问**：

```
你的网站已就绪。要不要顺手部署，让别人也能访问？

1. ⭐ Netlify 匿名部署（推荐 · 零账号 · 1 分钟拿到 URL）
2. Surge.sh（极简 · 首次免注册）
3. Cloudflare Pages（生产级 · 需 API token）
4. 腾讯云 CloudBase（国内快 · 需环境 ID）
5. Vercel（海外 · 需登录）
6. GitHub Pages（免费 · 需 gh CLI）
7. 暂不部署，我先本地看看

选哪个？
```

**自动选择**：如果不指定平台，运行 `./scripts/detect-deploy-tools.sh` 按以下优先级推荐：

1. 用户显式覆盖（`DEPLOY_PLATFORM_OVERRIDE` 环境变量）→ 用它
2. 特殊例外：中国时区 + CloudBase 已登录 → Cloudbase（国内访问快）
3. Netlify 已安装 → Netlify（未登录自动走匿名模式）
4. Vercel 已安装 → Vercel
5. Cloudflare (wrangler) 已安装 → Cloudflare
6. CloudBase 已安装但不在例外条件 → Cloudbase
7. Surge 已安装 → Surge
8. GitHub Pages (gh CLI) 已安装
9. 都没装 → 推荐 Netlify（最简单，装上就用）

> 详细决策树见 `references/platform-selection.md`。

**执行命令**：

```bash
# 自动选择平台 + 自动优化 + 自动验证
./scripts/deploy.sh hexo /path/to/blog

# 显式指定平台
./scripts/deploy.sh hexo /path/to/blog --platform=netlify --anonymous
./scripts/deploy.sh vue3 /path/to/tools --platform=surge --domain=mytools
./scripts/deploy.sh vitepress /path/to/docs --platform=cloudbase --env-id=myenv-1234

# 跳过验证 / 跳过优化
./scripts/deploy.sh hexo /path/to/blog --no-verify
./scripts/deploy.sh hexo /path/to/blog --no-optimize
```

**部署后**：
- 自动调 `verify-deploy.sh` 验证 URL 可访问
- 保存 `.deploy-state.json`（用于「重新部署」）
- 重新部署：直接跑同一个 `deploy.sh` 命令

**详细文档**：`references/deployment.md`（含各平台限制 / 注意事项）
**平台对比**：`references/platform-selection.md`（决策树）

---

## 异常处理

详见 `references/troubleshooting.md`，常见问题：

| 情况 | 处理方式 |
|------|----------|
| 目标目录已存在 | 自动加 `-2`、`-3` 后缀（pick-dirname.sh 实现） |
| 路径不安全 | validate-path.sh 拒绝（系统目录、越界、符号链接） |
| `npm install` 失败 | 检查 Node.js 版本（要求 ≥ 18） |
| 用户中途取消 | 礼貌退出，不做任何操作 |
| 用户想修改之前的选项 | 允许重新开始任意一步 |
| 网络问题导致初始化失败 | 提示用户检查网络，重试或手动初始化 |
| 占位符未替换 | substitute.sh --check 检查模板合规性 |

---

## 双语策略

| 类型 | 中文版 | 英文版 | 原因 |
|------|--------|--------|------|
| 博客 | ✅ | ✅ | 默认中文，英文版用于 EN 用户跳转 |
| 知识库 | ✅ | ✅ | VitePress 站通常中英双语 |
| AI 导航 | ❌ | ❌ | 内容是工具列表，无多语言概念 |
| 作品集 | ✅（一种语言） | ❌ | 用户内容本身就是单一语言 |
| 简历 | ✅（一种语言） | ❌ | 同上 |

**生成方式**：在 `source/_posts/welcome-zh.md` 和 `source/_posts/welcome-en.md`（Hexo）/ `docs/guide/getting-started.md` 和 `docs/en/guide/getting-started.md`（VitePress）放置双语首篇文章，互相跳转。

---

## 更多信息

- **占位符列表**：`references/placeholders.md`（执行 init 脚本时自动读取）
- **技术栈对比**：`references/tech-stacks.md`
- **部署详解**：`references/deployment.md`
- **故障排查**：`references/troubleshooting.md`
- **框架细节**：`references/frameworks/*.md`