# AI System Prompts Hub: VitePress 文档网站改造方案

## 概述

### 项目背景

原仓库 [system-prompts-and-models-of-ai-tools](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) 收集了 30+ AI 工具的系统提示词、工具定义和模型配置（如 Claude Code、Cursor、Devin AI）。文件格式多样（.txt、.json、.yaml），部分有语法问题或混合二进制（如图像）。

**改造目标**：

- 构建静态文档网站，便于浏览/复制提示词。
- 支持自动同步上游仓库更新。
- 功能：产品列表表格、代码块渲染、一键复制、搜索、响应式导航。
- 托管：GitHub Pages（免费）。

**技术栈**：

- **生成器**：VitePress（Vue-based，快速、ESM-native，支持 Markdown + Vue 组件）。
- **环境**：Node.js 18+。
- **自动化**：GitHub Actions（同步 + 构建 + 部署）。
- **优势**：零服务器、低维护、SEO 友好；内置代码复制，无需自定义 JS。

**预计时间**：初始设置 30-60min；后续自动化。

**前提**：

- GitHub 账号。
- windows环境
- Node.js 18+ 安装（[nodejs.org](https://nodejs.org)）。
- 基本命令行知识（CMD/PowerShell）。

---

## 步骤 1: Fork 与准备仓库

1. **Fork 仓库**：
   
   - 访问 [原仓库](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools)，点击 "Fork" 到你的账号。
   - 克隆 fork：
     ```bash
     git clone https://github.com/[你的用户名]/system-prompts-and-models-of-ai-tools.git
     cd system-prompts-and-models-of-ai-tools
     ```
   - 添加上游 remote（为同步）：
     ```bash
     git remote add upstream https://github.com/yancongya/system-prompts-and-models-of-ai-tools.git
     ```
2. **初始化 npm**：
   
   ```bash
   npm init -y
   ```
3. **安装依赖**：
   
   ```bash
   npm install vitepress js-yaml --save-dev
   ```
4. **创建 docs 目录**：
   
   ```bash
   mkdir docs
   cd docs
   npx vitepress init  # 生成基本 config.js 和 index.md
   cd ..
   ```

---

## 步骤 2: 配置 VitePress

编辑 `docs/.vitepress/config.js`（ESM 格式，用 import/export）：

```js
import { defineConfig } from 'vitepress'

export default defineConfig({
  base: '/',  // 修复路径加载
  title: 'AI System Prompts Hub',
  description: 'AI 工具提示词集合',
  themeConfig: {
    nav: [{ text: '首页', link: '/' }],  // 脚本动态更新
    sidebar: {
      '/': [{ text: 'Products', children: [] }]  // 脚本动态更新
    },
    search: true,
    features: {
      contentCodeCopy: true  // 内置代码复制按钮
    }
  },
  markdown: {
    attrs: { leftDelimiter: '{', rightDelimiter: '}' }  // 支持自定义
  }
})
```

添加 package.json scripts：

```json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  "type": "module"  // ESM 模式，修复 require/ESM 冲突
}
```

---

## 步骤 3: 转换脚本（自动生成 MD）

创建 `scripts/convert-to-md.js`（Node 脚本，扫描产品文件夹，生成 docs/[slug]/index.md）：

```js
const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');

const srcDir = '.';
const docsDir = './docs';

// 清理旧 docs（容错）
if (fs.existsSync(docsDir)) {
  try {
    fs.rmSync(docsDir, { recursive: true, force: true });
    console.log('清理并重置 docs/ 文件夹。');
  } catch (e) {
    console.warn(`清理失败: ${e.message}. 覆盖继续。`);
  }
}
fs.mkdirSync(docsDir, { recursive: true });

const products = fs.readdirSync(srcDir)
  .filter(dir => fs.statSync(path.join(srcDir, dir)).isDirectory() && !['docs', 'scripts', '.git', '.github', 'node_modules'].includes(dir));

const textExts = ['.txt', '.json', '.yaml', '.yml'];

let indexTable = '| 产品名称 | 描述 | 提示词链接 |\n|----------|------|------------|\n';
let navItems = '';

products.forEach(product => {
  const productDir = path.join(srcDir, product);
  const slug = product.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
  const mdDir = path.join(docsDir, slug);
  fs.mkdirSync(mdDir, { recursive: true });

  let mdContent = `# ${product}\n\n基于原仓库提取。使用代码块复制提示词。\n\n`;

  let hasBinaryWarn = false;

  fs.readdirSync(productDir).forEach(file => {
    if (file.startsWith('.')) return;
    const filePath = path.join(productDir, file);
    if (!fs.statSync(filePath).isFile()) return;
    const ext = path.extname(file).toLowerCase();
    if (!textExts.includes(ext)) {
      if (!hasBinaryWarn) console.warn(`跳过 ${product} 非文本文件。`);
      hasBinaryWarn = true;
      return;
    }
    let content;
    try {
      content = fs.readFileSync(filePath, 'utf8').trim();
      if (content.includes('\x00') || content.includes('IHDR')) {
        console.warn(`跳过二进制 ${file} (${product})。`);
        return;
      }
    } catch (e) {
      console.warn(`读取错误 ${file}: ${e.message}`);
      return;
    }

    let rendered;
    if (ext === '.txt') {
      rendered = `## ${file.replace(ext, '')}\n\n\`\`\`text\n${content}\n\`\`\``;
    } else if (ext === '.json') {
      try {
        const parsed = JSON.parse(content);
        rendered = `## ${file.replace(ext, '')}\n\n\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``;
      } catch (e) {
        rendered = `## ${file.replace(ext, '')}\n\n\`\`\`json\n${content}\n\`\`\`\n\n:::warning 格式问题，直接复制原始。\n:::`;
      }
    } else if (ext === '.yaml' || ext === '.yml') {
      try {
        const parsed = yaml.load(content);
        rendered = `## ${file.replace(ext, '')}\n\n\`\`\`yaml\n${yaml.dump(parsed, { indent: 2 })}\n\`\`\``;
      } catch (e) {
        rendered = `## ${file.replace(ext, '')}\n\n\`\`\`yaml\n${content}\n\`\`\`\n\n:::warning 格式问题，直接复制原始。\n:::`;
      }
    }
    mdContent += `\n\n${rendered}\n\n`;
  });

  fs.writeFileSync(path.join(mdDir, 'index.md'), mdContent);
  console.log(`生成: docs/${slug}/index.md`);

  indexTable += `| ${product} | AI 工具提示 | [查看](/${slug}/) |\n`;
  navItems += `{ text: '${product}', link: '/${slug}/' }, `;
});

const indexMd = `# AI System Prompts Hub\n\n## 产品列表\n\n${indexTable}\n\n*自动生成。*`;
fs.writeFileSync(path.join(docsDir, 'index.md'), indexMd);

let config = fs.readFileSync(path.join(docsDir, '.vitepress/config.js'), 'utf8');

// 动态更新 nav/sidebar
config = config.replace(/nav:\s*\[\s*{ text: '首页', link: '/' }(,\s*)?\]/, `nav: [ { text: '首页', link: '/' }, ${navItems.slice(0, -2)} ]`);
config = config.replace(/children:\s*\[\]/, `children: [ ${navItems.slice(0, -2)} ]`);

// 确保 features
if (!config.includes('contentCodeCopy')) {
  config = config.replace(/themeConfig: \{/, 'themeConfig: { features: { contentCodeCopy: true },');
}
fs.writeFileSync(path.join(docsDir, '.vitepress/config.js'), config);

console.log(`\n完成！生成 ${products.length} 页。跑 npm run docs:dev 测试。`);
```

**运行脚本**：

```bash
node scripts/convert-to-md.js
```

- 输出：生成 docs/index.md（表格）+ docs/[slug]/index.md（提示代码块）。
- 警告：YAML/JSON 格式问题 raw 输出。

---

## 步骤 4: 本地测试

1. **启动 dev 服务器**：
   
   ```bash
   npm run docs:dev -- --port 5173
   ```
   
   - 访问 http://localhost:5173/：首页表格，点击产品链接打开提示页。
   - 代码块右上复制图标测试。
   - 搜索：内置，搜 "prompt"。
2. **构建测试**：
   
   ```bash
   npm run docs:build
   ```
   
   - 检查 docs/.vitepress/dist/：有 index.html 等静态文件。
3. **问题排查**：
   
   - 404/MIME：确保 config.js 有 `base: '/'`。
   - ESM 错：package.json 有 `"type": "module"`。
   - 中文路径：移动到英文文件夹重试。

---

## 步骤 5: 自动化同步与部署

1. **GitHub Actions**（.github/workflows/sync-and-deploy.yml）：
   
   ```yaml
   name: Sync & Build
   on:
     schedule:
       - cron: '0 0 * * 0'  # 每周日
     workflow_dispatch:  # 手动
   jobs:
     sync:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with:
             token: ${{ secrets.GITHUB_TOKEN }}
             fetch-depth: 0
         - name: Sync Upstream
           run: |
             git remote add upstream https://github.com/yancongya/system-prompts-and-models-of-ai-tools.git || true
             git fetch upstream
             git merge upstream/main --allow-unrelated-histories
             git push origin main
         - uses: actions/setup-node@v4
           with:
             node-version: 18
             cache: 'npm'
         - run: npm ci
         - run: node scripts/convert-to-md.js
         - run: npm run docs:build
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./docs/.vitepress/dist
   ```
2. **启用 Pages**：
   
   - GitHub 仓库 Settings > Pages > Source: Deploy from branch "gh-pages"。
3. **推送初始**：
   
   ```bash
   git add .
   git commit -m "Init VitePress site"
   git push origin main
   ```
   
   - Actions 自动跑，站点上线：https://[用户名].github.io/system-prompts-and-models-of-ai-tools/。

---

## 优化与维护

### 功能增强

- **搜索**：内置全文搜提示词。
- **主题**：VitePress 默认暗黑模式支持。
- **RSS**：加插件通知更新。
- **版本**：用 VitePress 版本控制历史提示。

### 常见问题

| 问题           | 解决方案                                      |
| -------------- | --------------------------------------------- |
| ESM/require 错 | package.json 加`"type": "module"`，重装 npm。 |
| 404/MIME 错    | config.js 加`base: '/'`，清理 .vite 缓存。    |
| YAML/JSON 坏   | 脚本 raw 输出；手动 fix 原文件。              |
| 中文路径       | 移动到英文路径重 clone。                      |
| Actions 失败   | 检查日志，手动触发 workflow_dispatch。        |

### 更新机制

- 上游变化：Actions 自动 merge + 脚本转换 + 重新构建。
- 手动：`git pull upstream main && node scripts/convert-to-md.js && npm run docs:build`。

### 资源

- VitePress 文档：https://vitepress.dev/
- 示例仓库：你的 fork（添加脚本后 commit）。

此方案简洁、可复制。如果需自定义（如加 React 组件），扩展 config.js。测试后反馈！