# 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



## 步骤 3: 本地测试

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"`。
   - 中文路径：移动到英文文件夹重试。

---

## 步骤 4: 自动化更新检查（半自动）

为了避免上游仓库的更新在您不知情的情况下直接合并到您的项目中，我们采用一种更稳妥的半自动方案：**自动检查更新并生成报告**。您可以在审阅报告后，自行决定如何进行手动更新。

1. **新的 GitHub Actions 工作流** (`.github/workflows/sync-check.yml`):

    我们将创建一个新的 Action，它的核心逻辑是检查差异并报告，而不是同步和部署。

    ```yaml
    name: Check for Upstream Updates
    on:
      schedule:
        - cron: '0 0 * * 0' # 每周日
      workflow_dispatch:  # 允许手动触发

    jobs:
      sync-check:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout repository
            uses: actions/checkout@v4
            with:
              token: ${{ secrets.GITHUB_TOKEN }}

          - name: Set up Git
            run: |
              git config --global user.name 'github-actions[bot]'
              git config --global user.email 'github-actions[bot]@users.noreply.github.com'
              git remote add upstream https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git || true
              git fetch upstream

          - name: Check for differences and generate report
            id: diff_check
            run: |
              # 定义更新报告的存放目录
              UPDATE_DIR="upstream_updates"
              # 清理旧报告
              rm -rf $UPDATE_DIR
              
              # 获取差异文件列表
              CHANGED_FILES=$(git diff main upstream/main --name-only)

              if [ -z "$CHANGED_FILES" ]; then
                echo "No new updates found from upstream."
                echo "changes_found=false" >> $GITHUB_OUTPUT
              else
                echo "Updates found. Generating report..."
                echo "changes_found=true" >> $GITHUB_OUTPUT
                mkdir -p $UPDATE_DIR
                
                # 创建摘要文件
                echo "# 上游仓库更新报告" > $UPDATE_DIR/summary.md
                echo "检测到以下文件有更新：" >> $UPDATE_DIR/summary.md
                echo "" >> $UPDATE_DIR/summary.md
                echo '```' >> $UPDATE_DIR/summary.md
                echo "$CHANGED_FILES" >> $UPDATE_DIR/summary.md
                echo '```' >> $UPDATE_DIR/summary.md

                # 复制所有变动文件的最新版本
                for file in $CHANGED_FILES; do
                  mkdir -p "$UPDATE_DIR/$(dirname "$file")"
                  git show "upstream/main:$file" > "$UPDATE_DIR/$file"
                done
              fi

          - name: Commit update report
            if: steps.diff_check.outputs.changes_found == 'true'
            uses: stefanzweifel/git-auto-commit-action@v5
            with:
              commit_message: "chore: Check for upstream updates and generate report"
              file_pattern: "upstream_updates/**/*"
              commit_user_name: "github-actions[bot]"
              commit_user_email: "github-actions[bot]@users.noreply.github.com"

    ```

2. **新的工作流程**:

    *   **触发**: 您可以进入仓库的 "Actions" 标签页，手动触发 "Check for Upstream Updates" 工作流，或等待它按计划（每周日）自动运行。
    *   **生成报告**: Action 运行后，如果检测到上游有更新，它会自动创建一个名为 `upstream_updates` 的文件夹，并将所有更新内容和摘要文件放在里面，然后将这个文件夹提交到您的 `main` 分支。
    *   **手动更新**: 您只需 `git pull` 拉取最新的提交，本地就会出现 `upstream_updates` 文件夹。您可以从容地查看里面的内容，然后手动将这些更新应用到您的主项目中。

3. **部署**:

    由于此流程不再自动合并，部署步骤也变为手动。当您完成手动更新并想发布网站时，只需在本地运行 `npm run docs:build`，然后将 `docs/.vitepress/dist` 目录的内容部署到您的静态网站托管服务（如 GitHub Pages）即可。

---

## 优化与维护

### 功能增强

- **搜索**：内置全文搜提示词。
- **主题**：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 + 生成提醒文本 + 重新构建。


### 资源

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

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