feat(cms): 首页四项可配 + 开源页项目可见性 + GitHub README 开篇

- 首页：subtitle（markdown 短文本）｜latestPhotos 0-6（0 隐藏）｜
  perTrackLimit 4-8｜sections{tracks,photos,heatmap,projects} 开关，
  访问器 homeConfig() 夹取越界值，字段级回落默认（零配置=原形态）
- 开源页项目可见性：mode all|only|exclude + include[]/exclude[] +
  sort pinned-first|stars|updated + perSource both|github|gitea；
  projects.ts 加 LoadProjectsOptions + arrange()（来源→可见性→排序）
- 开源页开篇支持 GitHub README：intro_from off|github-readme，构建期
  取 wait4xx/wait4xx README（token 复用宿主 0600 文件）→ 缓存
  content/.github-readme.md 入仓 → renderMarkdown；失败逐级回落
  （缓存 → yaml blurb）。实测取到 3117 字符，现状仍 off 待用户开启
- 修既有 bug：orderPinned 内硬 slice(0,6) 把开源页 limit=99 也截到 6 条
  → 移除，开源页恢复全量 16 条
- 文档：写作指南加首页/项目墙两张字段表（含 YAML 1.1 `off` 需加引号坑、
  README 行为与外部徽章风险说明）

车道：op-gitea（3/3）；收编复验：构建 48 页 + E2E 37/37 + 开源页 16 条 +
首页默认形态（2 轨/热力图/项目墙）无回归

验证: node v26.13.0 构建 48 页 exit 0；E2E 37/37 PASS；playwright 实测

Spec: none (首页与开源页后台扩展，车道级交付)

Co-authored-by: GLM-5.3

src/components/geek/ProjectWall.astro

@@ -12,8 +12,16 @@ interface Props {
   locale?: Locale;
   /** 置顶仓短名（顺序即展示），由 content/site/opensource.yaml 供给 */
   pinned?: string[];
+  /** 可见性/排序/来源选项（同上，开源页消费） */
+  options?: {
+    mode?: 'all' | 'only' | 'exclude';
+    include?: string[];
+    exclude?: string[];
+    sort?: 'pinned-first' | 'stars' | 'updated';
+    perSource?: 'both' | 'github' | 'gitea';
+  };
 }
-const { limit = 6, locale = 'zh', pinned } = Astro.props;
+const { limit = 6, locale = 'zh', pinned, options } = Astro.props;
 const title = t('open_source_projects', locale);
 const LANG_COLORS: Record<string, string> = {
   Astro: '#ff5a03', TypeScript: '#3178c6', JavaScript: '#f1e05a',
@@ -23,7 +31,7 @@ const LANG_COLORS: Record<string, string> = {
 
 let projects: RepoCard[] = [];
 try {
-  projects = (await loadProjects(pinned)).slice(0, limit);
+  projects = (await loadProjects({ pinned, ...options })).slice(0, limit);
 } catch {
   projects = []; // 兜底已在 lib 内处理，此处再守一层：空墙不破构建
 }

src/content.config.ts

@@ -84,6 +84,21 @@ export const collections = {
         avatar: image().optional(),
         /** 站点图标：public 下的路径（.svg/.ico 直出，不经图片管线）；缺省回退 /favicon.svg */
         favicon: z.string().optional(),
+        /** 副标题（markdown 短文本，渲染在身份语下）；空 = 不渲染 */
+        subtitle: bilingual.optional(),
+        /** 最新影像张数：0 隐藏区块，1-6 有效（越界由访问器夹取） */
+        latestPhotos: z.number().int().optional(),
+        /** 首页每轨条数：4-8（越界由访问器夹取，缺省 6） */
+        perTrackLimit: z.number().int().optional(),
+        /** 区块开关：缺省全开 */
+        sections: z
+          .object({
+            tracks: z.boolean().optional(),
+            photos: z.boolean().optional(),
+            heatmap: z.boolean().optional(),
+            projects: z.boolean().optional(),
+          })
+          .optional(),
         /** 社交链接，顺序即展示顺序；icon 为内置图标集键（github/rss/email/...） */
         socials: z
           .array(
@@ -110,6 +125,16 @@ export const collections = {
       repo_label: z.string().optional(),
       /** 置顶仓短名，顺序即展示顺序（原 projects.ts 硬编码名单迁于此） */
       pinned: z.array(z.string()).optional(),
+      /** 项目墙可见性：all=全部 / only=仅 include / exclude=排除 exclude */
+      mode: z.enum(['all', 'only', 'exclude']).optional(),
+      include: z.array(z.string()).optional(),
+      exclude: z.array(z.string()).optional(),
+      /** 排序：pinned-first（默认）/ stars / updated */
+      sort: z.enum(['pinned-first', 'stars', 'updated']).optional(),
+      /** 来源过滤：both（默认）/ github / gitea */
+      perSource: z.enum(['both', 'github', 'gitea']).optional(),
+      /** 开篇文案来源：off（默认，用本文件 blurb）/ github-readme（构建期取 profile 仓 README） */
+      intro_from: z.enum(['off', 'github-readme']).optional(),
     }),
   }),
   // slug 即文件名（glob loader 默认按文件名生成 id）

src/lib/projects.ts

@@ -54,11 +54,25 @@ function toCard(r: RawRepo, source: RepoCard['source']): RepoCard | null {
  * 拉双源合并去重（同名优先 gitea 自托管叙事，star 取 GitHub 真值）。
  * 任一源失败不抛：置顶项回落仓内缓存 JSON（构建产物绝不被网络单点卡死）。
  */
+export interface LoadProjectsOptions {
+  /** 置顶仓短名（顺序即顺序），缺省 PINNED_DEFAULT */
+  pinned?: string[];
+  /** 可见性：all=全部 / only=仅 include / exclude=排除 exclude */
+  mode?: 'all' | 'only' | 'exclude';
+  include?: string[];
+  exclude?: string[];
+  /** 排序：pinned-first（默认）/ stars / updated */
+  sort?: 'pinned-first' | 'stars' | 'updated';
+  /** 来源过滤：both（默认）/ github / gitea */
+  perSource?: 'both' | 'github' | 'gitea';
+}
+
 /**
- * 拉取双源并排序（置顶名单由 content/site/opensource.yaml 供给，缺省用 PINNED_DEFAULT）
- * @param pinned 置顶仓短名，顺序即展示顺序
+ * 拉取双源并按选项过滤/排序（选项来自 content/site/opensource.yaml，缺省 = 现状行为）
+ * @returns 未截断的完整列表：展示上限由调用方 slice（首页 6 / 开源页 99）
  */
-export async function loadProjects(pinned: string[] = PINNED_DEFAULT): Promise<RepoCard[]> {
+export async function loadProjects(options: LoadProjectsOptions = {}): Promise<RepoCard[]> {
+  const { pinned = PINNED_DEFAULT, mode = 'all', include = [], exclude = [], sort = 'pinned-first', perSource = 'both' } = options;
   const [gitea, github] = await Promise.allSettled([fetchJson(GITEA_API), fetchJson(GITHUB_API)]);
   const byName = new Map<string, RepoCard>();
 
@@ -76,15 +90,32 @@ export async function loadProjects(pinned: string[] = PINNED_DEFAULT): Promise<R
 
   if (byName.size === 0) {
     const fb = (await import('../data/projects-fallback.json')).default as RepoCard[];
-    return orderPinned(fb, pinned);
+    return arrange(fb, pinned, mode, include, exclude, sort, perSource);
   }
-  return orderPinned([...byName.values()], pinned);
+  return arrange([...byName.values()], pinned, mode, include, exclude, sort, perSource);
 }
 
-function orderPinned(list: RepoCard[], pinned: string[]): RepoCard[] {
-  return [...list].sort((a, b) => {
+/** 来源过滤 + 可见性过滤 + 排序（不截断：上限交给调用方） */
+function arrange(
+  list: RepoCard[],
+  pinned: string[],
+  mode: 'all' | 'only' | 'exclude',
+  include: string[],
+  exclude: string[],
+  sort: 'pinned-first' | 'stars' | 'updated',
+  perSource: 'both' | 'github' | 'gitea',
+): RepoCard[] {
+  let out = perSource === 'both' ? list : list.filter((r) => r.source === perSource);
+  if (mode === 'only') out = out.filter((r) => include.includes(r.name));
+  else if (mode === 'exclude') out = out.filter((r) => !exclude.includes(r.name));
+
+  if (sort === 'stars') return [...out].sort((a, b) => b.stars - a.stars);
+  if (sort === 'updated') {
+    return [...out].sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+  }
+  return [...out].sort((a, b) => {
     const pa = pinned.indexOf(a.name), pb = pinned.indexOf(b.name);
     if (pa !== -1 || pb !== -1) return (pa === -1 ? 99 : pa) - (pb === -1 ? 99 : pb);
     return b.stars - a.stars;
-  }).slice(0, 6);
+  });
 }

src/lib/site-content.ts

@@ -131,3 +131,127 @@ export async function aboutIntroMarkdown(locale: Locale): Promise<string> {
   const entry = await getEntry('siteAbout', 'about');
   return pickBi(entry?.data.intro, SITE_DEFAULTS.aboutIntro, locale);
 }
+
+// ---- 车道「首页+开源页后台扩展」：首页四项可配 + 项目墙可见性 + README 开篇 ----
+
+export interface HomeSections {
+  tracks: boolean;
+  photos: boolean;
+  heatmap: boolean;
+  projects: boolean;
+}
+
+export interface HomeConfig {
+  /** 副标题 markdown 原文；空串 = 不渲染 */
+  subtitle: string;
+  /** 最新影像张数：0 = 隐藏区块 */
+  latestPhotos: number;
+  /** 每轨文章条数 */
+  perTrackLimit: number;
+  sections: HomeSections;
+}
+
+const clampInt = (value: number | undefined, min: number, max: number, fallback: number): number => {
+  if (typeof value !== 'number' || Number.isNaN(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+};
+
+/** 首页可配项（字段级回落：零配置 = 现有形态；越界值夹取而非报错） */
+export async function homeConfig(locale: Locale): Promise<HomeConfig> {
+  const entry = await getEntry('siteHome', 'home');
+  const d = entry?.data;
+  return {
+    subtitle: pickBi(d?.subtitle, { zh: '', en: '' }, locale),
+    latestPhotos: clampInt(d?.latestPhotos, 0, 6, 4),
+    perTrackLimit: clampInt(d?.perTrackLimit, 4, 8, 6),
+    sections: {
+      tracks: d?.sections?.tracks ?? true,
+      photos: d?.sections?.photos ?? true,
+      heatmap: d?.sections?.heatmap ?? true,
+      projects: d?.sections?.projects ?? true,
+    },
+  };
+}
+
+export type ProjectMode = 'all' | 'only' | 'exclude';
+export type ProjectSort = 'pinned-first' | 'stars' | 'updated';
+export type ProjectSource = 'both' | 'github' | 'gitea';
+
+export interface OpenSourceOptions {
+  mode: ProjectMode;
+  include: string[];
+  exclude: string[];
+  sort: ProjectSort;
+  perSource: ProjectSource;
+  introFrom: 'off' | 'github-readme';
+}
+
+/** 开源页项目墙选项（缺省 = 现状：all / pinned-first / 双源） */
+export async function openSourceOptions(): Promise<OpenSourceOptions> {
+  const entry = await getEntry('siteOpenSource', 'opensource');
+  const d = entry?.data;
+  return {
+    mode: d?.mode ?? 'all',
+    include: (d?.include ?? []).filter((n) => n.trim()),
+    exclude: (d?.exclude ?? []).filter((n) => n.trim()),
+    sort: d?.sort ?? 'pinned-first',
+    perSource: d?.perSource ?? 'both',
+    introFrom: d?.intro_from ?? 'off',
+  };
+}
+
+/** GitHub profile README 缓存：取不到网就吃缓存，都无则调用方回落 yaml blurb */
+const README_CACHE = 'content/.github-readme.md';
+const PROFILE_REPO = 'wait4xx/wait4xx';
+
+/**
+ * 构建期取 profile 仓 README（Accept: raw），成功后回写 content/.github-readme.md（入仓缓存）
+ * @returns README markdown；网络/权限/仓无 README 时回落缓存，仍无 → null
+ */
+export async function githubReadmeMarkdown(): Promise<string | null> {
+  const { readFileSync, writeFileSync, existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const cachePath = join(process.cwd(), README_CACHE);
+  const readCache = (): string | null => {
+    try {
+      return existsSync(cachePath) ? readFileSync(cachePath, 'utf8') : null;
+    } catch {
+      return null;
+    }
+  };
+
+  let token: string | null = null;
+  try {
+    token = readFileSync(join(process.env.HOME ?? '', 'docker_apps/blog/github-token.txt'), 'utf8').trim() || null;
+  } catch {
+    token = null;
+  }
+  if (!token) {
+    console.warn('[opensource] github-readme：token 缺位，用缓存/回落 yaml blurb');
+    return readCache();
+  }
+
+  try {
+    const res = await fetch(`https://api.github.com/repos/${PROFILE_REPO}/readme`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github.raw', 'User-Agent': 'wait4x-blog-build' },
+    });
+    if (!res.ok) {
+      console.warn(`[opensource] github-readme：${PROFILE_REPO} 取 README 失败 HTTP ${res.status}，用缓存/回落`);
+      return readCache();
+    }
+    const md = (await res.text()).trim();
+    if (!md) {
+      console.warn('[opensource] github-readme：README 为空，用缓存/回落');
+      return readCache();
+    }
+    const cached = readCache();
+    if (cached !== md) {
+      writeFileSync(cachePath, `${md}\n`, 'utf8');
+      console.log(`[opensource] github-readme：已刷新缓存 ${README_CACHE}（${md.length} 字符）`);
+    }
+    return md;
+  } catch (err) {
+    console.warn(`[opensource] github-readme：请求异常（${(err as Error).message}），用缓存/回落`);
+    return readCache();
+  }
+}

src/pages/en/index.astro

@@ -8,9 +8,12 @@ import PostList from '../../components/PostList.astro';
 import ProjectWall from '../../components/geek/ProjectWall.astro';
 import Heatmap from '../../components/geek/Heatmap.astro';
 import { t } from '../../i18n/ui';
-import { homeTagline } from '../../lib/site-content';
+import { homeConfig, homeTagline, renderMarkdown } from '../../lib/site-content';
 import SocialLinks from '../../components/SocialLinks.astro';
 
+// 首页可配项（后台主页设置）：副标题/影像张数/区块开关/每轨条数，字段级回落
+const cfg = await homeConfig('en');
+const subtitleHtml = cfg.subtitle ? await renderMarkdown(cfg.subtitle) : '';
 const posts = (await getCollection('posts', ({ data }) => !data.draft && !data.tags.includes('hidden'))).sort(
   (a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime(),
 );
@@ -18,7 +21,7 @@ const posts = (await getCollection('posts', ({ data }) => !data.draft && !data.t
 const enTitle = Object.fromEntries(
   (await getCollection('postsEn')).map((e) => [e.id, e.data.title]),
 );
-const photos = (await getCollection('photos')).slice(0, 4);
+const photos = (await getCollection('photos')).slice(0, Math.max(1, cfg.latestPhotos));
 // 身份语与 zh 版同源（content/site/home.yaml 的 en 字段），缺值回落默认
 const tagline = await homeTagline('en');
 ---
@@ -26,11 +29,13 @@ const tagline = await homeTagline('en');
 <BaseLayout title="wait4x" description="wait4x's blog: reading · code · photography">
   <IdCard>
     <p class="tagline">{tagline}</p>
+    {subtitleHtml && <div class="subtitle" set:html={subtitleHtml} />}
     <SocialLinks />
     </IdCard>
 
-  <PostList {posts} locale="en" titleOverrides={enTitle} perTrack={6} />
+  {cfg.sections.tracks && <PostList {posts} locale="en" titleOverrides={enTitle} perTrack={cfg.perTrackLimit} />}
 
+  {cfg.sections.photos && cfg.latestPhotos > 0 && (
   <section class="latest" aria-label={t('latest_photos', 'en')}>
     <div class="latest-head">
       <span class="lab">{t('latest_photos', 'en')}</span>
@@ -49,8 +54,9 @@ const tagline = await homeTagline('en');
       ))}
     </div>
   </section>
+  )}
 
-  <Heatmap
+  {cfg.sections.heatmap && <Heatmap
     labels={{
       title: t('heatmap_title', 'en'),
       summary: t('heatmap_summary', 'en'),
@@ -58,11 +64,19 @@ const tagline = await homeTagline('en');
       more: t('heatmap_more', 'en'),
       note: t('heatmap_note', 'en'),
     }}
-  />
-  <ProjectWall locale="en" />
+  />}
+  {cfg.sections.projects && <ProjectWall locale="en" />}
 </BaseLayout>
 
 <style>
+  .subtitle {
+    font-size: 13.5px;
+    color: var(--ink-4);
+    margin-top: 2px;
+    letter-spacing: 0.01em;
+  }
+  .subtitle :global(p) { margin: 0; }
+  .subtitle :global(a) { color: var(--accent); }
   .tagline {
     font-size: 14px;
     color: var(--ink-3);

src/pages/en/opensource.astro

@@ -3,21 +3,33 @@ import ProjectWall from '../../components/geek/ProjectWall.astro';
 import Heatmap from '../../components/geek/Heatmap.astro';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { t } from '../../i18n/ui';
-import { openSourceCopy } from '../../lib/site-content';
+import { githubReadmeMarkdown, openSourceCopy, openSourceOptions, renderMarkdown } from '../../lib/site-content';
 
 const copy = await openSourceCopy('en');
+const options = await openSourceOptions();
+const readmeMd = options.introFrom === 'github-readme' ? await githubReadmeMarkdown() : null;
+const readmeHtml = readmeMd ? await renderMarkdown(readmeMd) : null;
 ---
 <BaseLayout title="Open Source · wait4x" description="My open-source activity: repos, contributions, and this site's source">
   <h1 class="page-title">Open Source</h1>
-  <p class="blurb">{copy.blurb}<a class="link" href={copy.repoUrl}>{copy.repoLabel}</a>{copy.blurbAfter}</p>
+  {readmeHtml ? (
+    <div class="blurb readme-intro" set:html={readmeHtml} />
+  ) : (
+    <p class="blurb">{copy.blurb}<a class="link" href={copy.repoUrl}>{copy.repoLabel}</a>{copy.blurbAfter}</p>
+  )}
   <Heatmap labels={{
     title: t('heatmap_title', 'en'), summary: t('heatmap_summary', 'en'),
     less: t('heatmap_less', 'en'), more: t('heatmap_more', 'en'), note: t('heatmap_note', 'en'),
   }} />
-  <ProjectWall limit={99} locale="en" pinned={copy.pinned} />
+  <ProjectWall limit={99} locale="en" pinned={copy.pinned} options={options} />
 </BaseLayout>
 
 <style>
   .page-title { font-size: var(--text-h1); color: var(--ink-1); }
+  .readme-intro :global(p) { margin-block: 0 var(--space-2); }
+  .readme-intro :global(ul) { margin-block: var(--space-1) var(--space-2); padding-left: 1.2em; list-style: disc; }
+  .readme-intro :global(h2), .readme-intro :global(h3) { font-size: 16px; margin: var(--space-3) 0 var(--space-1); }
+  .readme-intro :global(img) { max-width: 100%; height: auto; border-radius: 8px; }
+  .readme-intro :global(a) { color: var(--accent); }
   .blurb { margin-top: var(--space-3); margin-bottom: var(--space-5); font-size: 15px; color: var(--ink-2); line-height: 1.7; max-width: 640px; }
 </style>

src/pages/index.astro

@@ -8,14 +8,17 @@ import ProjectWall from '../components/geek/ProjectWall.astro';
 import Heatmap from '../components/geek/Heatmap.astro';
 import { fetchHeartbeat, agoZh } from '../lib/heartbeat';
 import { t } from '../i18n/ui';
-import { homeTagline } from '../lib/site-content';
+import { homeConfig, homeTagline, renderMarkdown } from '../lib/site-content';
 import SocialLinks from '../components/SocialLinks.astro';
 
+// 首页可配项（后台主页设置）：副标题/影像张数/区块开关/每轨条数，字段级回落
+const cfg = await homeConfig('zh');
+const subtitleHtml = cfg.subtitle ? await renderMarkdown(cfg.subtitle) : '';
 const posts = (await getCollection('posts', ({ data }) => !data.draft && !data.tags.includes('hidden'))).sort(
   (a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime(),
 );
 // 最新影像取集合前 4 张；照片时间序由照片管线（exif 车道）治理，此处只裁切
-const photos = (await getCollection('photos')).slice(0, 4);
+const photos = (await getCollection('photos')).slice(0, Math.max(1, cfg.latestPhotos));
 const heartbeat = await fetchHeartbeat();
 // 身份语改由 content/site/home.yaml 供给（后台可改），缺值回落默认文案
 const tagline = await homeTagline('zh');
@@ -24,11 +27,13 @@ const tagline = await homeTagline('zh');
 <BaseLayout title="wait4x">
   <IdCard>
         <p class="tagline">{tagline}</p>
+    {subtitleHtml && <div class="subtitle" set:html={subtitleHtml} />}
 <SocialLinks />
     </IdCard>
 
-  <PostList {posts} perTrack={6} />
+  {cfg.sections.tracks && <PostList {posts} perTrack={cfg.perTrackLimit} />}
 
+  {cfg.sections.photos && cfg.latestPhotos > 0 && (
   <section class="latest" aria-label="最新影像">
     <div class="latest-head">
       <span class="lab">最新影像</span>
@@ -50,8 +55,9 @@ const tagline = await homeTagline('zh');
       ))}
     </div>
   </section>
+  )}
 
-  <Heatmap
+  {cfg.sections.heatmap && <Heatmap
     labels={{
       title: t('heatmap_title', 'zh'),
       summary: t('heatmap_summary', 'zh'),
@@ -59,8 +65,8 @@ const tagline = await homeTagline('zh');
       more: t('heatmap_more', 'zh'),
       note: t('heatmap_note', 'zh'),
     }}
-  />
-  <ProjectWall />
+  />}
+  {cfg.sections.projects && <ProjectWall />}
   {heartbeat && (
     <p class="heartbeat" aria-label="最近心跳">
       <span class="beat-dot" aria-hidden="true"></span>
@@ -70,6 +76,14 @@ const tagline = await homeTagline('zh');
 </BaseLayout>
 
 <style>
+  .subtitle {
+    font-size: 13.5px;
+    color: var(--ink-4);
+    margin-top: 2px;
+    letter-spacing: 0.01em;
+  }
+  .subtitle :global(p) { margin: 0; }
+  .subtitle :global(a) { color: var(--accent); }
   .tagline {
     font-size: 14px;
     color: var(--ink-3);