Merge branch 'main' into feat/add-unit-tests-priority-1

Author: SiYG

.github/workflows/sync-uuid.yml

@@ -0,0 +1,71 @@
+name: Docs Backfill (on docs changes)
+
+on:
+  push:
+    branches:
+      - main
+      - feat/contributor
+    paths:
+      - "app/docs/**"
+      - "scripts/uuid.mjs"
+      - "scripts/backfill-contributors.mjs"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/sync-uuid.yml"
+      - "generated/doc-contributors.json"
+  workflow_dispatch: {}
+
+concurrency:
+  group: backfill-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backfill:
+    # 防止 fork、限定 main、并避免机器人循环
+    if: github.repository == 'InvolutionHell/involutionhell.github.io' &&
+      (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/feat/contributor') &&
+      github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      GITHUB_TOKEN: ${{ secrets.GH_PAT }} # 供脚本调用 GitHub API 提升速率
+      DOCS_DIR: app/docs
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm" # 顺便启用 pnpm 缓存，加速
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma Client
+        run: pnpm prisma generate
+
+      - name: Ensure docId frontmatter
+        run: pnpm exec node scripts/uuid.mjs
+
+      - name: Backfill contributors & sync DB
+        run: pnpm exec node scripts/backfill-contributors.mjs
+
+      - name: Auto-commit doc metadata (if any)
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore(docs): sync doc metadata [skip ci]" # ← 防循环
+          file_pattern: "app/docs/**/*.md app/docs/**/*.mdx generated/doc-contributors.json"
+
+      - name: Upload snapshot JSON
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-contributors-snapshot
+          path: generated/doc-contributors.json
+          if-no-files-found: ignore

.idea/workspace.xml

@@ -0,0 +1,36 @@
+# AGENT Guidelines
+
+Welcome! This repository hosts the Involution Hell documentation site, built with Next.js App Router, Fumadocs UI, TypeScript, and Tailwind CSS. Follow the instructions below whenever you contribute changes.
+
+## General workflow
+
+- Prefer `pnpm` for all Node.js commands (`pnpm install`, `pnpm dev`, `pnpm build`, etc.).
+- Keep changes focused and provide helpful descriptions in commits and PR messages.
+- When adding dependencies, ensure they are compatible with Node.js 18+.
+
+## Coding standards
+
+- Follow existing patterns in the codebase; align new components with the established structure under `app/` and `components/`.
+- Use TypeScript (`.ts` / `.tsx`) and Tailwind CSS utility classes for styling unless a file already uses a different approach.
+- Avoid unnecessary abstractions; keep components small, composable, and accessible.
+- Do not wrap imports in `try/catch` blocks.
+
+## Documentation & content
+
+- All documentation lives under `app/docs/` (folder-as-book). Each Markdown/MDX file **must** retain a frontmatter block with at least a `title`.
+- Place images referenced by a document inside the document’s sibling `*.assets/` folder. Use the provided image migration scripts if needed.
+- Prefer relative links within the docs unless cross-referencing an external resource.
+
+## Testing & validation
+
+- Run relevant scripts before submitting changes. Common checks include:
+  - `pnpm dev` for local verification.
+  - `pnpm build` for production validation when you touch runtime logic.
+  - `pnpm lint:images` when you add or move media assets.
+
+## PR expectations
+
+- Summarize user-facing changes clearly.
+- Mention any new scripts, configuration, or docs that reviewers should be aware of.
+
+For additional details, consult `README.md` and `CONTRIBUTING.md`.

AGENT.md

@@ -102,6 +102,18 @@ git push origin doc_raven
 
 ---
 
+## Q&A
+
+> Windows + VSCode(Cursor) 用户：如遇 Husky 在 VSCode 内置终端阻止提交，请使用外部命令行执行 `git commit`。
+
+> 本地离线调试 Fumadocs 时，如果发现界面加载需要等待远程图片尺寸请求，可以设置环境变量 `DOCS_REMOTE_IMAGE_SIZE=disable` 或直接沿用默认行为（开发模式自动禁用远程图片尺寸请求），显著加快调试速度。如需强制启用远程图片尺寸补全，可手动设置 `DOCS_REMOTE_IMAGE_SIZE=force`。
+
+| `DOCS_REMOTE_IMAGE_SIZE` | 行为说明                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| 未设置（默认）           | 构建时忽略远程图片尺寸请求报错，开发模式下额外禁用远程尺寸请求，避免离线调试受阻 |
+| `disable`                | 在任何模式下都跳过远程图片尺寸请求，仅使用文档内手动声明的宽高                   |
+| `force`                  | 强制启用远程图片尺寸请求，并在出现错误时抛出异常以暴露问题                       |
+
 ## 🚀 开发环境
 
 ### 1. 克隆仓库
@@ -114,20 +126,35 @@ cd involutionhell.github.io
 ### 2. 安装依赖
 
 ```bash
-npm install
+pnpm install    # 推荐；如需可改用 npm install
 ```
 
 ### 3. 本地开发
 
 运行开发服务器：
 
 ```bash
-npm dev
+pnpm dev
 ```
 
 打开浏览器访问 [http://localhost:3000](http://localhost:3000)。
 
-修改 `docs/` 下的 `.md` 或 `.mdx` 文件，会自动热更新。
+修改 `docs/` 下的 `.md` 文件，会自动热更新。
+
+---
+
+## 🛠️ 可用脚本
+
+常用脚本集中在 `package.json` 中，以下是最常用的命令：
+
+```bash
+pnpm dev             # 启动开发服务器
+pnpm build           # 构建生产版本
+pnpm start           # 启动生产服务器
+pnpm lint:images     # 检查图片是否符合规范
+pnpm migrate:images  # 自动迁移图片到对应 assets 目录
+pnpm postinstall     # 同步必要的 Husky/Fumadocs 配置
+```
 
 ---
 
@@ -138,7 +165,7 @@ npm dev
 docxA 引用了 imgA 图片, 那么他们的文档结构应该是 `docxA.assets/imgA`:
 
 ```md
-docsA.mdx
+docsA.md
 docsA.assets/
 imgA
 ```
@@ -182,35 +209,35 @@ tags:
 ```
 📂 docs/
 ├── 📂 computer-science/           # 计算机科学
-│   ├── 📄 index.mdx               # 概述
+│   ├── 📄 index.md               # 概述
 │   └── 📂 data-structures/        # 数据结构
-│       ├── 📄 index.mdx           # 概述
+│       ├── 📄 index.md           # 概述
 │       ├── 📂 array/              # 数组
-│       │   ├── 📄 index.mdx       # 概述
-│       │   ├── 📄 01-static-array.mdx    # 静态数组
-│       │   └── 📄 02-dynamic-array.mdx   # 动态数组
+│       │   ├── 📄 index.md       # 概述
+│       │   ├── 📄 01-static-array.md    # 静态数组
+│       │   └── 📄 02-dynamic-array.md   # 动态数组
 │       └── 📂 linked-list/        # 链表
-│           ├── 📄 index.mdx       # 概述
-│           └── 📄 01-singly-linked-list.mdx  # 单向链表
+│           ├── 📄 index.md       # 概述
+│           └── 📄 01-singly-linked-list.md  # 单向链表
 ```
 
 ### URL 生成
 
 文件结构会自动生成简洁的 URL：
 
-- `docs/computer-science/index.mdx` → `/computer-science`
-- `docs/computer-science/data-structures/array/01-static-array.mdx` → `/computer-science/data-structures/array/static-array`
+- `docs/computer-science/index.md` → `/computer-science`
+- `docs/computer-science/data-structures/array/01-static-array.md` → `/computer-science/data-structures/array/static-array`
 
 ### 命名约定
 
 **文件夹:**
 
 - 使用 `kebab-case` 命名: `computer-science`, `data-structures`
-- 每个主题文件夹应该有一个 `index.mdx` 文件作为概述
+- 每个主题文件夹应该有一个 `index.md` 文件作为概述
 
 **文件:**
 
-- 使用 `kebab-case` 命名: `static-array.mdx`
+- 使用 `kebab-case` 命名: `static-array.md`
 - 使用数字前缀排序: `01-`, `02-`
 - 前缀会自动从最终 URL 中移除