@windcoder/astro-theme-orchid 0.2.0 → 0.3.0

package/scripts/migrate-posts.mjs

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * 文章迁移工具（§4.94）：把 Hexo / Hugo 或通用 Markdown 博客文章迁移为符合
+ * 主题 definePostSchema 的 frontmatter（title/published 必需，其余尽力映射），
+ * 正文一字不动；默认 dry-run 只出报告，--write 才写盘。
+ *
+ * 用法（站点根目录）：
+ *   node node_modules/@windcoder/astro-theme-orchid/scripts/migrate-posts.mjs \
+ *     --src <文章目录> [--platform hexo|hugo|generic] [--out migrated-posts] \
+ *     [--write] [--flat]
+ *
+ * 规则：
+ *   - 只迁移 frontmatter。主题无 <!-- more --> 摘要分隔符机制，列表摘要由
+ *     remark-excerpt 取正文首段自动兜底，无需转换。
+ *   - 标题三级回退：frontmatter → 正文首个 `# 标题` → 文件名；
+ *     发布时间缺失时用文件修改时间兜底。
+ *   - 白名单之外的 frontmatter 字段不写入目标，仅在报告中列出，便于人工核对。
+ *   - 正文中的相对路径图片在报告中提示：目录结构调整后需人工核对引用。
+ *   - 输出文件名取自源文件名（Hugo 优先 slug 字段），冲突自动加 -2/-3 序号；
+ *     默认保留相对目录结构，--flat 拍平到输出根目录。
+ */
+import {
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse, stringify } from "yaml";
+
+const pad2 = (n) => String(n).padStart(2, "0");
+
+function parseArgs(argv) {
+	const args = {
+		src: "",
+		platform: "generic",
+		out: "migrated-posts",
+		write: false,
+		flat: false,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--src") args.src = argv[++i];
+		else if (a === "--platform") args.platform = argv[++i] ?? "";
+		else if (a === "--out") args.out = argv[++i];
+		else if (a === "--write") args.write = true;
+		else if (a === "--flat") args.flat = true;
+		else if (a === "--help" || a === "-h") {
+			console.log(
+				"用法：node migrate-posts.mjs --src <文章目录> [--platform hexo|hugo|generic] [--out migrated-posts] [--write] [--flat]",
+			);
+			process.exit(0);
+		}
+	}
+	return args;
+}
+
+/** 解析 `---` 界定的 frontmatter；无界定符或 YAML 损坏时 broken/空对象兜底 */
+export function parseFrontmatter(raw) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+	if (!m) return { data: {}, body: raw, broken: false };
+	let data = {};
+	let broken = false;
+	try {
+		const parsed = parse(m[1]);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			data = parsed;
+		} else if (parsed != null) {
+			broken = true;
+		}
+	} catch {
+		broken = true;
+	}
+	return { data, body: raw.slice(m[0].length), broken };
+}
+
+/** 日期值归一化为 YAML 友好字符串；非法返回 null。
+ *  date-only 原样保留（避免时区漂移），hexo 斜杠格式转 ISO，
+ *  带显式时区偏移的 ISO 串直接取墙钟（同理，避免经 Date 本地化漂移），其余 new Date 兜底。 */
+export function normalizeDate(value) {
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : formatDate(value);
+	}
+	if (typeof value !== "string") return null;
+	const s = value.trim();
+	if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s;
+	const slash =
+		/^(\d{4})\/(\d{2})\/(\d{2})(?:\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?$/.exec(s);
+	if (slash) {
+		const date = `${slash[1]}-${slash[2]}-${slash[3]}`;
+		return slash[4]
+			? `${date}T${pad2(slash[4])}:${slash[5]}:${slash[6] ?? "00"}`
+			: date;
+	}
+	const offseted =
+		/^(\d{4}-\d{2}-\d{2})[Tt ](\d{2}:\d{2})(?::(\d{2}))?(?:\.\d+)?(?:[Zz]|[+-]\d{2}:?\d{2})$/.exec(
+			s,
+		);
+	if (offseted) return `${offseted[1]}T${offseted[2]}:${offseted[3] ?? "00"}`;
+	const d = new Date(s);
+	return Number.isNaN(d.getTime()) ? null : formatDate(d);
+}
+
+/** Date → 本地时分秒格式：零点只写日期，其余带 T 时间（无时区后缀，保墙钟） */
+export function formatDate(d) {
+	const date = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+	const time = `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+	return time === "00:00:00" ? date : `${date}T${time}`;
+}
+
+/** 任意嵌套结构拍平成非空字符串数组（hexo categories 可能是嵌套数组） */
+function flattenStrings(value) {
+	if (value == null) return [];
+	if (Array.isArray(value)) return value.flatMap(flattenStrings);
+	const s = String(value).trim();
+	return s ? [s] : [];
+}
+
+/** 标题三级回退：frontmatter → 正文首个 `# 标题` → 文件名 */
+export function resolveTitle(data, body, fallback) {
+	const t = data.title;
+	if (typeof t === "string" && t.trim()) {
+		return { title: t.trim(), from: "frontmatter" };
+	}
+	if (typeof t === "number") return { title: String(t), from: "frontmatter" };
+	const m = /^[ \t]*#[ \t]+(.+?)[ \t]*$/m.exec(body);
+	if (m) {
+		return { title: m[1].replace(/[#*`_]/g, "").trim(), from: "heading" };
+	}
+	return { title: fallback, from: "filename" };
+}
+
+/** 文件名净化：空白转 -，剔除文件系统不安全字符，空值兜底 "post"（保留中文） */
+export function toSlug(name) {
+	const slug = name
+		.trim()
+		.replace(/\s+/g, "-")
+		.replace(/[/\\:*?"<>|\p{Cc}]/gu, "")
+		.replace(/^[.-]+|[.-]+$/g, "");
+	return slug || "post";
+}
+
+/** 正文里的相对路径图片（不含 http(s)://、//、/、data: 开头） */
+export function findRelativeImages(body) {
+	const out = [];
+	const re = /!\[[^\]]*\]\(([^)\s]+)[^)]*\)|<img[^>]+src=["']([^"']+)["']/g;
+	for (const m of body.matchAll(re)) {
+		const url = m[1] ?? m[2];
+		if (
+			!url.startsWith("/") &&
+			!url.startsWith("data:") &&
+			!url.startsWith("#") &&
+			!/^(https?:)?\/\//.test(url)
+		) {
+			out.push(url);
+		}
+	}
+	return out;
+}
+
+/**
+ * 按平台把源 frontmatter 映射为目标白名单字段（键序固定）。
+ * 白名单外与未消费的源键进 notes，不写入目标。
+ */
+export function mapFrontmatter(data, platform) {
+	const notes = [];
+	const used = new Set();
+	/** 取第一个有值的键；候选键一律记为已消费（不进未映射报告） */
+	const take = (...keys) => {
+		let hit;
+		for (const k of keys) {
+			const v = data[k];
+			if (hit === undefined && v !== undefined && v !== null && v !== "") {
+				hit = v;
+			}
+			used.add(k);
+		}
+		return hit;
+	};
+
+	const fm = {};
+	const title = take("title");
+	if (title !== undefined) fm.title = String(title);
+
+	const description = take("description", "summary", "excerpt");
+	if (description !== undefined) fm.description = String(description);
+
+	const rawPublished =
+		platform === "generic"
+			? take("published", "date", "created")
+			: take("date", "publishDate");
+	const published = normalizeDate(rawPublished);
+	if (published) fm.published = published;
+
+	const rawUpdated =
+		platform === "hugo"
+			? take("lastmod", "updated")
+			: take("updated", "modified", "lastmod");
+	const updated = normalizeDate(rawUpdated);
+	if (updated) fm.updated = updated;
+
+	if (platform === "hexo") {
+		const p = take("published");
+		if (p === false || p === "false") fm.draft = true;
+	} else {
+		const d = take("draft");
+		if (d === true || d === "true") fm.draft = true;
+	}
+
+	let image;
+	if (platform === "hexo") {
+		image = take("cover", "image") ?? flattenStrings(take("photos"))[0];
+	} else if (platform === "hugo") {
+		image = take("image", "cover") ?? flattenStrings(take("images"))[0];
+	} else {
+		image = take("cover", "image", "banner", "thumbnail");
+	}
+	if (image !== undefined && image !== "") fm.image = String(image);
+
+	const tags = flattenStrings(take("tags"));
+	if (tags.length) fm.tags = tags;
+
+	const categories = flattenStrings(take("category", "categories"));
+	if (categories.length) fm.category = categories[0];
+
+	// hugo slug 供输出文件名用（见 migrateFile），标记已消费避免误报
+	if (platform === "hugo") take("slug");
+
+	const unmapped = Object.keys(data).filter((k) => !used.has(k));
+	if (unmapped.length) {
+		notes.push(`未映射字段：${unmapped.join("、")}（未写入目标）`);
+	}
+	return { fm, notes };
+}
+
+/** 递归收集 src 下 .md/.markdown，返回 posix 分隔符的相对路径（排序稳定） */
+export function scanMarkdownFiles(srcDir) {
+	const out = [];
+	function walk(dir) {
+		for (const ent of readdirSync(dir, { withFileTypes: true })) {
+			const abs = join(dir, ent.name);
+			if (ent.isDirectory()) walk(abs);
+			else if (ent.isFile() && /\.(md|markdown)$/i.test(ent.name)) {
+				out.push(relative(srcDir, abs).replace(/\\/g, "/"));
+			}
+		}
+	}
+	walk(srcDir);
+	return out.sort();
+}
+
+/** 迁移单篇：映射 frontmatter + 兜底补齐 + 生成输出路径与文件内容 */
+export function migrateFile({ rel, raw, platform, mtimeMs, usedSlugs, flat }) {
+	const notes = [];
+	const { data, body, broken } = parseFrontmatter(raw);
+	if (broken) notes.push("frontmatter 解析失败，已按无元数据处理");
+
+	const { fm, notes: mapNotes } = mapFrontmatter(data, platform);
+	notes.push(...mapNotes);
+
+	const base = basename(rel).replace(/\.(md|markdown)$/i, "");
+	const title = resolveTitle(data, body, base);
+	fm.title = title.title;
+	if (title.from === "heading") notes.push("标题缺失，已取正文首个一级标题");
+	else if (title.from === "filename") notes.push("标题缺失，已使用文件名");
+
+	if (!fm.published) {
+		fm.published = formatDate(new Date(mtimeMs));
+		notes.push("发布时间缺失，已用文件修改时间兜底");
+	}
+
+	for (const img of new Set(findRelativeImages(body))) {
+		notes.push(`正文含相对路径图片：${img}（目录调整后需人工核对）`);
+	}
+
+	const slugSource =
+		platform === "hugo" && typeof data.slug === "string" && data.slug.trim()
+			? data.slug.trim()
+			: base;
+	const slug = toSlug(slugSource);
+	const dir =
+		flat || dirname(rel) === "." ? "" : `${dirname(rel).replace(/\\/g, "/")}/`;
+	let relOut = `${dir}${slug}.md`;
+	for (let n = 2; usedSlugs.has(relOut); n++) relOut = `${dir}${slug}-${n}.md`;
+	usedSlugs.add(relOut);
+
+	const content = `---\n${stringify(fm)}---\n\n${body.replace(/^\r?\n+/, "")}`;
+	return { relOut, fm, content, notes };
+}
+
+/** 迁移整目录：write 为 false 时只生成报告不落盘 */
+export function runMigration({
+	src,
+	out,
+	platform,
+	write = false,
+	flat = false,
+}) {
+	const usedSlugs = new Set();
+	const results = [];
+	for (const rel of scanMarkdownFiles(src)) {
+		const abs = join(src, rel);
+		const { mtimeMs } = statSync(abs);
+		const r = migrateFile({
+			rel,
+			raw: readFileSync(abs, "utf8"),
+			platform,
+			mtimeMs,
+			usedSlugs,
+			flat,
+		});
+		if (write) {
+			const absOut = resolve(out, r.relOut);
+			mkdirSync(dirname(absOut), {
+				recursive: true,
+			});
+			writeFileSync(absOut, r.content);
+		}
+		results.push({ source: rel, output: r.relOut, notes: r.notes });
+	}
+	return { platform, total: results.length, write, results };
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (!args.src) {
+		console.error(
+			"[migrate-posts] 缺少 --src <文章目录>。加 --help 查看用法。",
+		);
+		process.exit(1);
+	}
+	if (!["hexo", "hugo", "generic"].includes(args.platform)) {
+		console.error(
+			`[migrate-posts] 未知 --platform ${args.platform}，可选 hexo | hugo | generic。`,
+		);
+		process.exit(1);
+	}
+	const src = resolve(args.src);
+	try {
+		if (!scanMarkdownFiles(src).length) {
+			console.log(
+				`[migrate-posts] ${src} 下没有 .md / .markdown 文件，无事可做。`,
+			);
+			process.exit(0);
+		}
+	} catch {
+		console.error(`[migrate-posts] 无法读取目录 ${src}，请确认路径。`);
+		process.exit(1);
+	}
+
+	console.log(
+		`[migrate-posts] 平台 ${args.platform}，输出 ${resolve(args.out)}${args.write ? "" : "（dry-run 预览，不会写盘）"}\n`,
+	);
+
+	const report = runMigration({ ...args, src });
+	for (const f of report.results) {
+		console.log(`  ${f.source}  →  ${f.output}`);
+		for (const n of f.notes) console.log(`      ⚠ ${n}`);
+	}
+
+	const noted = report.results.filter((f) => f.notes.length).length;
+	console.log(
+		`\n[migrate-posts] 完成：${report.total} 篇，${noted} 篇有提示${
+			args.write
+				? `，已写入 ${resolve(args.out)}`
+				: "。确认无误后加 --write 落盘"
+		}`,
+	);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+	main();
+}

package/scripts/subset-fonts.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * 字体子集化脚本（M4-3，移植自 orchid-blog/scripts/subset-fonts.ts）
+ *
+ * astro build 之后运行：扫描 dist/ 全部 HTML 收集实际用到的字符，
+ * 为 subset-fonts.json 清单中声明的本地字体生成 woff2 子集，
+ * 重写 dist 内 CSS/HTML 对原字体的 url()/href 引用，并删除 dist 中的原字体。
+ * 相比原版的改动：原版靠 __SUBSET_FONT_{id}__ 占位符替换，但源码中并无
+ * 占位符生成方（半成品机制）；本版直接重写原字体 URL，配合站点自写的
+ * @font-face 即可端到端生效，且不再依赖 Astro Font API 与站点 src/config。
+ *
+ * 运行：pnpm --filter site build 内链（cwd 必须是 site 根）
+ * 清单：site 根 subset-fonts.json（可选）：
+ *   { "fonts": [{ "src": "/assets/fonts/Foo.ttf", "id": "foo", "extraChars": "…" }] }
+ *   - src 必填：dist 绝对路径（/ 开头），也兼容 ./public/ 前缀写法
+ *   - id 选填：默认取文件名；extraChars 选填：补充动态内容字符
+ * 无清单或清单为空时跳过（exit 0），CI 无需感知。
+ * dev 模式不受影响：dev 直接走 public 原字体，仅构建产物被子集化。
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import subsetFont from "subset-font";
+
+const DIST_DIR = "dist";
+const MANIFEST_FILE = "subset-fonts.json";
+
+/** 与 generate-lqips.mjs 一致：目录递归替代 glob 依赖 */
+async function walkFiles(dir, exts, out = []) {
+	let entries;
+	try {
+		entries = await fs.readdir(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await walkFiles(full, exts, out);
+		} else if (exts.has(path.extname(entry.name).toLowerCase())) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+/**
+ * 将清单 src 归一为 dist 绝对 URL（/ 开头）。
+ * 兼容 ./public/x、public/x、/public/x、/x 四种写法；无法归一返回 null。
+ */
+function toPublicPath(rawSrc) {
+	if (rawSrc.startsWith("/")) {
+		const m = rawSrc.match(/^\/public\/(.+)$/);
+		return m ? `/${m[1]}` : rawSrc;
+	}
+	const m = rawSrc.match(/^\.?\/?public\/(.+)$/);
+	return m ? `/${m[1]}` : null;
+}
+
+/**
+ * 从 HTML 提取可见文本：剔除 script/style，剥标签，
+ * 解常见实体，另收 alt/title/aria-label/placeholder 属性值（移植原版）
+ */
+function extractTextFromHtml(html) {
+	let text = html.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, " ");
+	text = text.replace(/<[^>]+>/g, " ");
+	text = text
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'")
+		.replace(/&nbsp;/g, " ");
+	const attrs = html.matchAll(
+		/(?:alt|title|aria-label|placeholder)=["']([^"']+)["']/gi,
+	);
+	for (const m of attrs) text += m[1];
+	return text;
+}
+
+async function collectChars(distDir) {
+	const files = await walkFiles(distDir, new Set([".html"]));
+	const chars = new Set();
+	for (const file of files) {
+		const html = await fs.readFile(file, "utf-8");
+		for (const c of extractTextFromHtml(html)) chars.add(c);
+	}
+	return [...chars].join("");
+}
+
+function contentHash(buffer) {
+	return crypto.createHash("sha256").update(buffer).digest("hex").slice(0, 16);
+}
+
+/** 生成 url(...) 与 href/src 属性两种引用形态的重写规则 */
+function rewriteReferences(content, originalUrl, subsetUrl) {
+	const escaped = originalUrl.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const urlRe = new RegExp(`url\\(\\s*(['"]?)${escaped}\\1\\s*\\)`, "g");
+	const attrRe = new RegExp(`((?:href|src)=['"])${escaped}(['"])`, "g");
+	return content
+		.replace(urlRe, `url($1${subsetUrl}$1)`)
+		.replace(attrRe, `$1${subsetUrl}$2`);
+}
+
+async function main() {
+	const cwd = process.cwd();
+	const distDir = path.join(cwd, DIST_DIR);
+
+	// 1. 读清单；无清单/空清单 → no-op 跳过
+	let manifest;
+	try {
+		manifest = JSON.parse(
+			await fs.readFile(path.join(cwd, MANIFEST_FILE), "utf-8"),
+		);
+	} catch {
+		console.log("[subset-fonts] 无 subset-fonts.json 清单，跳过（exit 0）");
+		return;
+	}
+	const entries = (manifest.fonts ?? [])
+		.map((e) => {
+			const publicUrl = toPublicPath(e.src ?? "");
+			if (!publicUrl) {
+				console.warn(
+					`[subset-fonts] ⚠ 无法归一 src 路径，跳过：${e.src}（需 /assets/... 或 public/ 前缀）`,
+				);
+				return null;
+			}
+			const id = (e.id || path.basename(publicUrl, path.extname(publicUrl)))
+				.toLowerCase()
+				.replace(/\s+/g, "-");
+			return { id, url: publicUrl, extraChars: e.extraChars ?? "" };
+		})
+		.filter(Boolean);
+
+	if (entries.length === 0) {
+		console.log("[subset-fonts] 清单为空，跳过（exit 0）");
+		return;
+	}
+
+	// 2. 收集 dist 页面实际字符
+	console.log("[subset-fonts] 扫描 dist/ HTML 收集字符…");
+	const pageChars = await collectChars(distDir);
+	if (pageChars.length === 0) {
+		console.warn("[subset-fonts] ⚠ dist/ 无 HTML 或无字符，跳过");
+		return;
+	}
+	console.log(`[subset-fonts] 收集到 ${pageChars.length} 个去重字符`);
+
+	// 3. 逐字体生成子集
+	const outDir = path.join(distDir, "assets", "fonts");
+	await fs.mkdir(outDir, { recursive: true });
+	const results = [];
+	for (const entry of entries) {
+		const originalPath = path.join(distDir, entry.url.slice(1));
+		let fontBuffer;
+		try {
+			fontBuffer = await fs.readFile(originalPath);
+		} catch {
+			console.error(
+				`[subset-fonts] ❌ dist 中未找到字体 ${entry.url}（确认已在 public/ 放置并参与构建）`,
+			);
+			continue;
+		}
+
+		const charSet = new Set([...pageChars, ...entry.extraChars]);
+		const chars = [...charSet].join("");
+		try {
+			const subsetBuffer = await subsetFont(fontBuffer, chars, {
+				targetFormat: "woff2",
+				preserveNameTable: true,
+			});
+			const hash = contentHash(subsetBuffer);
+			const outName = `${entry.id}.${hash}.woff2`;
+			await fs.writeFile(path.join(outDir, outName), subsetBuffer);
+
+			const kb = (n) => (n / 1024).toFixed(1);
+			const saved = (
+				((fontBuffer.length - subsetBuffer.length) / fontBuffer.length) *
+				100
+			).toFixed(1);
+			console.log(
+				`[subset-fonts] ✔ ${entry.id} → ${outName}（${kb(subsetBuffer.length)} KB，原 ${kb(fontBuffer.length)} KB，省 ${saved}%）`,
+			);
+			results.push({ ...entry, outName });
+		} catch (err) {
+			console.error(`[subset-fonts] ❌ ${entry.id} 子集化失败:`, err);
+		}
+	}
+	if (results.length === 0) {
+		console.warn("[subset-fonts] ⚠ 未产出任何子集");
+		return;
+	}
+
+	// 4. 重写 dist 内 CSS/HTML 引用（url() 与 href/src 属性）
+	console.log("[subset-fonts] 重写 dist 内字体引用…");
+	const targets = await walkFiles(distDir, new Set([".css", ".html"]));
+	for (const file of targets) {
+		let content = await fs.readFile(file, "utf-8");
+		const before = content;
+		for (const r of results) {
+			content = rewriteReferences(content, r.url, `/assets/fonts/${r.outName}`);
+		}
+		if (content !== before) {
+			await fs.writeFile(file, content);
+			console.log(`[subset-fonts] ✔ 已更新 ${path.relative(cwd, file)}`);
+		}
+	}
+
+	// 5. 删除 dist 中的原字体（public 源文件保留，dev 仍走原字体）
+	for (const r of results) {
+		const originalPath = path.join(distDir, r.url.slice(1));
+		try {
+			await fs.unlink(originalPath);
+			console.log(
+				`[subset-fonts] ✔ 已删除 ${path.relative(cwd, originalPath)}`,
+			);
+		} catch {
+			// 原文件可能已不在 dist，忽略
+		}
+	}
+	console.log("[subset-fonts] ✨ 字体子集化完成");
+}
+
+main().catch((err) => {
+	console.error("[subset-fonts] ❌ 执行失败:", err);
+	process.exit(1);
+});

package/src/components/Analytics.astro

@@ -8,15 +8,18 @@ import GoogleAnalytics from "./analytics/GoogleAnalytics.astro";
 import La51Analytics from "./analytics/La51Analytics.astro";
 import MicrosoftClarity from "./analytics/MicrosoftClarity.astro";
 import UmamiAnalytics from "./analytics/UmamiAnalytics.astro";
+import WebVitals from "./analytics/WebVitals.astro";
 
 const a = config.analytics;
 const showGA = a.googleAnalyticsId.trim() !== "";
 const showClarity = a.microsoftClarityId.trim() !== "";
 const showUmami = a.umami.websiteId.trim() !== "";
 const show51la = a.la51.id.trim() !== "";
+const showWebVitals = a.webVitals.endpoint.trim() !== "";
 ---
 
 {showGA && <GoogleAnalytics analyticsId={a.googleAnalyticsId} />}
 {showClarity && <MicrosoftClarity clarityId={a.microsoftClarityId} />}
 {showUmami && <UmamiAnalytics {...a.umami} />}
 {show51la && <La51Analytics analyticsId={a.la51.id} sdkUrl={a.la51.sdkUrl} ck={a.la51.ck} autoTrack={a.la51.autoTrack} hashMode={a.la51.hashMode} screenRecord={a.la51.screenRecord} />}
+{showWebVitals && <WebVitals {...a.webVitals} />}

package/src/components/BaseLayout.astro

@@ -50,6 +50,17 @@ const showBanner =
 /* hero 文案（§4.42）：quote 留空不渲染；有 banner 时叠加其上，否则渲染为列表上方独立区块 */
 const heroEnabled = config.banner.enabled && Boolean(config.banner.quote);
 const heroOnBanner = heroEnabled && showBanner && page === "home";
+/* 全站背景壁纸（§4.92）：与 banner 相互独立；数组时构建期随机选一张（每页各自取，零 JS） */
+const bgSrc = Array.isArray(config.background.src)
+	? config.background.src.length
+		? config.background.src[
+				Math.floor(Math.random() * config.background.src.length)
+			]
+		: ""
+	: config.background.src || "";
+const showWallpaper = config.background.enabled && Boolean(bgSrc);
+/* 模糊边缘会泛出透明底：按模糊量轻微放大补偿（1px blur ≈ 1% 放大），服务端算好 scale */
+const bgScale = (1 + config.background.blur / 100).toFixed(3);
 /* 字体角色映射（§4.66）：配置了 role 的字体生成 html:root 规则，把主题三角色
    变量重定向为 var(字体变量), 原角色回退栈（取自 global.css :root 默认值，
    字体未覆盖的字形如中文自然回落）。html:root Specificity (0,1,1) 高于
@@ -70,7 +81,7 @@ const fontRoleCss = config.fonts
 ---
 
 <!doctype html>
-<html lang={config.lang} style={`--accent-h:${h};--accent-s:${s}%;--accent-l:${l}%;--page-width:${config.pageWidth}px`} data-accent-h={h} data-color-mode={config.colorMode}>
+<html lang={config.lang} style={`--accent-h:${h};--accent-s:${s}%;--accent-l:${l}%;--page-width:${config.pageWidth}px${config.darkMode.adaptExternalImages ? ";--img-adapt-b:.85" : ""}`} data-accent-h={h} data-color-mode={config.colorMode}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -97,6 +108,8 @@ const fontRoleCss = config.fonts
     <link rel="alternate" type="application/rss+xml" title={config.title} href={Astro.site ? new URL("rss.xml", Astro.site).href : "/rss.xml"} />
     <meta name="theme-color" media="(prefers-color-scheme: light)" content="#f6f4ef" />
     <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#131516" />
+    {/* PWA（§4.95）：manifest 清单链接，端点由 pwa.enabled 门控注入 */}
+    {config.pwa.enabled && <link rel="manifest" href="/manifest.webmanifest" />}
     {/* OG/Twitter meta（b9.4）：ogImage 仅文章页传入；绝对链接依赖 site 配置 */}
     <meta property="og:type" content={ogImage ? 'article' : 'website'} />
     <meta property="og:title" content={pageTitle} />
@@ -122,10 +135,36 @@ const fontRoleCss = config.fonts
     <script is:inline>
       (function(){var m=localStorage.getItem('qy-mode');var d=document.documentElement.dataset.colorMode||'system';if(m==='dark'||(!m&&d==='dark')||(!m&&d==='system'&&matchMedia('(prefers-color-scheme: dark)').matches))document.documentElement.classList.add('dark');var h=localStorage.getItem('qy-hue');if(h)document.documentElement.style.setProperty('--accent-h',h);})();
     </script>
+    {/* PWA（§4.95）：SW 注册。load 后注册不抢占首屏；is:inline + define:vars 在
+        ClientRouter VT swap 时不重复执行，全站仅注册一次；注册失败静默（离线兜底
+        属增强能力，不影响正常浏览） */}
+    {config.pwa.enabled && (
+      <script is:inline define:vars={{ swUrl: "/sw.js" }}>
+        if ("serviceWorker" in navigator) {
+          window.addEventListener("load", function () {
+            navigator.serviceWorker.register(swUrl).catch(function () {});
+          });
+        }
+      </script>
+    )}
   </head>
   <!-- 客户端动态文案载体（i18n，M3b-b5）：app.ts 读取，VT swap 后随新 body 重建 -->
   <script type="application/json" id="qy-ui-labels" set:html={JSON.stringify({ close: t('close'), prevImage: t('prevImage'), nextImage: t('nextImage'), copied: t('copied'), fullscreen: t('fullscreen'), slideshow: t('slideshow'), thumbs: t('thumbs'), sharePoster: t('sharePoster'), generatingPoster: t('generatingPoster'), copyLink: t('copyLink'), savePoster: t('savePoster'), scanToRead: t('scanToRead'), author: t('author'), searchLoading: t('searchLoading'), searchNoResults: t('searchNoResults'), searchUnavailable: t('searchUnavailable'), searchTypeSomething: t('searchTypeSomething') })} />
   <body data-page={page}>
+    <!-- 全站背景壁纸（§4.92）：fixed 于视口、z-index:-1，叠在 body 传播的画布底色之上、
+         内容之下——壁纸加载中仍有画布底色兜底；enabled=false / src 未配置不渲染 -->
+    {
+      showWallpaper && (
+        <div
+          class="site-wallpaper"
+          aria-hidden="true"
+          style={`--wp-dim:${config.background.dimOpacity};--wp-dim-dark:${config.background.darkDimOpacity};--wp-blur:${config.background.blur}px;--wp-scale:${bgScale}`}
+        >
+          <img src={bgSrc} alt="" loading="eager" decoding="async" />
+          <div class="site-wallpaper-dim" />
+        </div>
+      )
+    }
     <a class="skip-link" href="#main">{t('skipToContent')}</a>
     <Header />
     <!-- 首页 banner（§4.42，hero+壁纸合并单配置）：Header 之后下沉横幅 + 黑蒙层；enabled=false / src 未配置 / homeOnly 非首页不渲染 -->