system-prompts-and-models-of-ai-tools/重构文档.md

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

概述

项目背景

原仓库 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）。
• 基本命令行知识（CMD/PowerShell）。

---

步骤 1: Fork 与准备仓库

1. Fork 仓库：

   • 访问 原仓库，点击 "Fork" 到你的账号。
   • 克隆 fork：

     git clone https://github.com/[你的用户名]/system-prompts-and-models-of-ai-tools.git
     cd system-prompts-and-models-of-ai-tools
     

   • 添加上游 remote（为同步）：

     git remote add upstream https://github.com/yancongya/system-prompts-and-models-of-ai-tools.git
     

2. 初始化 npm：

   npm init -y
   

3. 安装依赖：

   npm install vitepress js-yaml --save-dev
   

4. 创建 docs 目录：

   mkdir docs
   cd docs
   npx vitepress init  # 生成基本 config.js 和 index.md
   cd ..
   

---

步骤 2: 配置 VitePress

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

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：

{
  "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）：

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 测试。`);

运行脚本：

node scripts/convert-to-md.js

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

---

步骤 4: 本地测试

1. 启动 dev 服务器：

   npm run docs:dev -- --port 5173
   

   • 访问 http://localhost:5173/：首页表格，点击产品链接打开提示页。
   • 代码块右上复制图标测试。
   • 搜索：内置，搜 "prompt"。

2. 构建测试：

   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）：

   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. 推送初始：

   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。测试后反馈！