feat: 已将贡献者数据改为由后端脚本落盘的 JSON，并在文档页直接读取渲染。

Author: longsizhuo

.github/workflows/sync-uuid.yml

@@ -12,6 +12,7 @@ on:
       - "package.json"
       - "pnpm-lock.yaml"
       - ".github/workflows/sync-uuid.yml"
+      - "generated/doc-contributors.json"
   workflow_dispatch: {}
 
 concurrency:
@@ -56,8 +57,8 @@ jobs:
       - name: Auto-commit added docIds (if any)
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
-          commit_message: "chore(docs): add missing docId via uuid.mjs [skip ci]" # ← 防循环
-          file_pattern: "app/docs/**/*.md app/docs/**/*.mdx app/docs/**/*.markdown"
+          commit_message: "chore(docs): sync doc metadata [skip ci]" # ← 防循环
+          file_pattern: "app/docs/**/*.md app/docs/**/*.mdx app/docs/**/*.markdown generated/doc-contributors.json"
 
       - name: Backfill contributors & sync DB
         run: pnpm exec node scripts/backfill-contributors.mjs
@@ -66,5 +67,5 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: doc-contributors-snapshot
-          path: tmp/doc-contributors.json
+          path: generated/doc-contributors.json
           if-no-files-found: ignore

app/components/Contributors.tsx

@@ -1,17 +1,25 @@
 import Image from "next/image";
 import Link from "next/link";
+import type { DocContributorsRecord } from "@/lib/contributors";
 
-interface Contributor {
-  login: string;
-  avatar_url: string;
-  html_url: string;
+interface ContributorsProps {
+  entry: DocContributorsRecord | null;
 }
 
-export function Contributors({
-  contributors,
-}: {
-  contributors: Contributor[];
-}) {
+function formatLastContributedAt(value: string | null) {
+  if (!value) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return new Intl.DateTimeFormat("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+export function Contributors({ entry }: ContributorsProps) {
+  const contributors = entry?.contributors ?? [];
+
   if (contributors.length === 0) {
     return null;
   }
@@ -21,25 +29,54 @@ export function Contributors({
       <hr className="border-border/70 !mt-10 !mb-5" />
       <h2 id="contributors-heading">贡献者</h2>
       <ul className="mt-0 mb-0 flex flex-wrap items-center gap-x-6 gap-y-4 list-none p-0">
-        {contributors.map((contributor) => (
-          <li key={contributor.login}>
-            <Link
-              href={contributor.html_url}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="inline-flex items-center gap-3 text-base font-medium text-primary transition-colors hover:text-primary/80 no-underline"
-            >
+        {contributors.map((contributor) => {
+          const displayName = contributor.login ?? `#${contributor.githubId}`;
+          const href = contributor.htmlUrl ?? undefined;
+          const avatarSrc =
+            contributor.avatarUrl ??
+            `https://avatars.githubusercontent.com/u/${contributor.githubId}`;
+          const lastDate = formatLastContributedAt(
+            contributor.lastContributedAt,
+          );
+
+          const content = (
+            <>
               <Image
-                src={contributor.avatar_url}
-                alt={contributor.login}
+                src={avatarSrc}
+                alt={displayName}
                 width={35}
                 height={35}
                 className="!m-0 h-10 w-10 rounded-full border border-border/50 object-cover shadow-sm"
               />
-              <span>{contributor.login}</span>
-            </Link>
-          </li>
-        ))}
+              <span className="flex flex-col text-left leading-tight">
+                <span className="font-medium">{displayName}</span>
+                <span className="text-sm text-muted-foreground">
+                  贡献 {contributor.contributions} 次
+                  {lastDate ? ` · 最近 ${lastDate}` : ""}
+                </span>
+              </span>
+            </>
+          );
+
+          return (
+            <li key={contributor.githubId}>
+              {href ? (
+                <Link
+                  href={href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-3 text-base text-primary transition-colors hover:text-primary/80 no-underline"
+                >
+                  {content}
+                </Link>
+              ) : (
+                <div className="inline-flex items-center gap-3 text-base">
+                  {content}
+                </div>
+              )}
+            </li>
+          );
+        })}
       </ul>
       <hr className="!mb-0 !mt-5 border-border/70" />
     </section>

app/docs/[...slug]/page.tsx

@@ -5,7 +5,11 @@ import type { Metadata } from "next";
 import { getMDXComponents } from "@/mdx-components";
 import { GiscusComments } from "@/app/components/GiscusComments";
 import { EditOnGithub } from "@/app/components/EditOnGithub";
-import { buildDocsEditUrl, getContributors } from "@/lib/github";
+import { buildDocsEditUrl } from "@/lib/github";
+import {
+  getDocContributorsByPath,
+  getDocContributorsByDocId,
+} from "@/lib/contributors";
 import { Contributors } from "@/app/components/Contributors";
 import { DocsAssistant } from "@/app/components/DocsAssistant";
 import fs from "fs/promises";
@@ -44,10 +48,15 @@ export default async function DocPage({ params }: Param) {
 
   // 统一通过工具函数生成 Edit 链接，内部已处理中文目录编码
   const editUrl = buildDocsEditUrl(page.path);
-  // Get file path for contributors
-  const filePath = "app/docs/" + page.file.path;
-  // Fetch contributors data on server side
-  const contributors = await getContributors(filePath);
+  const docIdFromPage =
+    (page.data as { docId?: string; frontmatter?: { docId?: string } })
+      ?.docId ??
+    (page.data as { docId?: string; frontmatter?: { docId?: string } })
+      ?.frontmatter?.docId;
+
+  const contributorsEntry =
+    getDocContributorsByPath(page.file.path) ||
+    getDocContributorsByDocId(docIdFromPage);
   const Mdx = page.data.body;
 
   // Prepare page content for AI assistant
@@ -75,7 +84,7 @@ export default async function DocPage({ params }: Param) {
             <EditOnGithub href={editUrl} />
           </div>
           <Mdx components={getMDXComponents()} />
-          <Contributors contributors={contributors} />
+          <Contributors entry={contributorsEntry} />
           <section className="mt-16">
             <GiscusComments />
           </section>

generated/doc-contributors.json

@@ -0,0 +1,7 @@
+{
+  "repo": "",
+  "generatedAt": "",
+  "docsDir": "app/docs",
+  "totalDocs": 0,
+  "results": []
+}

lib/contributors.ts

@@ -1,5 +1,60 @@
-/**
- * @description 贡献者相关工具方法
- * @author Siz Long
- * @date 2025-09-27
- */
+import dataset from "@/generated/doc-contributors.json";
+
+export interface ContributorEntry {
+  githubId: string;
+  contributions: number;
+  lastContributedAt: string | null;
+  login?: string | null;
+  avatarUrl?: string | null;
+  htmlUrl?: string | null;
+}
+
+export interface DocContributorsRecord {
+  docId: string;
+  path: string | null;
+  contributorStats: Record<string, number>;
+  contributors: ContributorEntry[];
+}
+
+export interface ContributorsDataset {
+  repo: string;
+  generatedAt: string;
+  docsDir: string;
+  totalDocs: number;
+  results: DocContributorsRecord[];
+}
+
+const contributorsDataset = dataset as ContributorsDataset;
+
+function normalizeRelativePath(relativePath: string): string {
+  const cleaned = relativePath.replace(/^\/+/, "").replace(/\\/g, "/");
+  return `app/docs/${cleaned}`;
+}
+
+export function getContributorsDataset(): ContributorsDataset {
+  return contributorsDataset;
+}
+
+export function getDocContributorsByPath(
+  relativeDocPath: string,
+): DocContributorsRecord | null {
+  if (!relativeDocPath) return null;
+  const normalized = normalizeRelativePath(relativeDocPath);
+  return (
+    contributorsDataset.results.find((entry) => entry.path === normalized) ??
+    null
+  );
+}
+
+export function getDocContributorsByDocId(
+  docId: string | undefined | null,
+): DocContributorsRecord | null {
+  if (!docId) return null;
+  return (
+    contributorsDataset.results.find((entry) => entry.docId === docId) ?? null
+  );
+}
+
+export function listDocContributors(): DocContributorsRecord[] {
+  return contributorsDataset.results;
+}

lib/github.ts

@@ -1,5 +1,3 @@
-import { cache } from "react";
-
 // GitHub 相关工具方法：集中维护仓库常量与文档路径生成逻辑
 const GITHUB_OWNER = "InvolutionHell";
 const GITHUB_REPO = "involutionhell.github.io";
@@ -55,61 +53,3 @@ export const githubConstants = {
   docsBase: DOCS_BASE,
   repoBaseUrl: REPO_BASE_URL,
 };
-
-
-
-// Define contributor data structure
-interface Contributor {
-  login: string;
-  avatar_url: string;
-  html_url: string;
-}
-
-// Use React's cache function for request caching and deduplication
-export const getContributors = cache(
-  async (filePath: string): Promise<Contributor[]> => {
-    try {
-      // Use GITHUB_TOKEN environment variable for authorization to increase API rate limit
-      const headers: HeadersInit = {};
-      if (process.env.GITHUB_TOKEN) {
-        headers.Authorization = `token ${process.env.GITHUB_TOKEN}`;
-      }
-
-      const response = await fetch(
-        `https://api.github.com/repos/InvolutionHell/involutionhell.github.io/commits?path=${filePath}`,
-        {
-          headers,
-          // Use next.revalidate to configure cache strategy (e.g., revalidate every hour)
-          next: { revalidate: 3600 },
-        },
-      );
-
-      if (!response.ok) {
-        // If request fails, return empty array
-        console.error(
-          `Failed to fetch contributors for ${filePath}: ${response.statusText}`,
-        );
-        return [];
-      }
-
-      const commits = await response.json();
-
-      // Use Map to deduplicate contributors
-      const uniqueContributors = new Map<string, Contributor>();
-      commits.forEach((commit: { author?: Contributor }) => {
-        if (commit.author) {
-          uniqueContributors.set(commit.author.login, {
-            login: commit.author.login,
-            avatar_url: commit.author.avatar_url,
-            html_url: commit.author.html_url,
-          });
-        }
-      });
-
-      return Array.from(uniqueContributors.values());
-    } catch (error) {
-      console.error(`Error fetching contributors for ${filePath}:`, error);
-      return [];
-    }
-  },
-);