@windcoder/astro-theme-orchid 0.2.0 → 0.2.1

package/README.md

@@ -12,6 +12,8 @@
 
 ## 快速上手
 
+> 新站点推荐直接从 [astro-theme-orchid-starter](https://github.com/iwinder/astro-theme-orchid-starter) 模板生成（Use this template），配置与内容骨架开箱即用；以下为在已有 Astro 站点上接入主题的步骤。
+
 ### 1. 安装
 
 ```sh
@@ -78,8 +80,8 @@ site/
 
 完整配置说明与文章 frontmatter 全字段表统一放在 demo 站「主题使用指南」系列文章（源文件在本仓库 `site/src/content/posts/`），按主题分组：
 
-- 基础：《站点基础配置》｜《导航栏与首页横幅》｜《侧边栏与个人资料》｜《文章列表与归档》
-- 功能：《文章页功能》｜《视觉特效与媒体》（含 fonts 详细配置）｜《独立页面与数据》｜《评论、公告、统计与广告》
+- 基础：《站点基础配置》｜《导航栏》｜《首页横幅》｜《侧边栏与小组件》｜《个人资料卡》｜《版权声明》｜《文章列表与归档》
+- 功能：《文章页功能》｜《内容渲染》｜《樱花特效》｜《音乐播放器》｜《Live2D 看板娘》｜《字体》｜《评论系统》｜《公告》｜《站点统计》｜《广告位》｜《友链》｜《赞助》｜《画廊》｜《独立页面》
 - 写作：《写作指南》（frontmatter 全字段与增强语法）｜《MDX 指南》（MDX 启用与踩坑修复）
 
 ## 定制与覆盖

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@windcoder/astro-theme-orchid",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "清新简约的 Astro 博客主题，以 Integration 形式提供，支持版本化升级与组件覆盖",
 	"type": "module",
 	"keywords": [
@@ -31,7 +31,9 @@
 		"./styles/*": "./src/styles/*"
 	},
 	"files": [
-		"src"
+		"src",
+		"scripts",
+		"!scripts/*.test.mjs"
 	],
 	"peerDependencies": {
 		"@iconify-json/lucide": "^1.2.0",
@@ -61,11 +63,11 @@
 		"remark-math": "^6.0.0",
 		"satori": "^0.47.1",
 		"sharp": "^0.35.5",
+		"subset-font": "^2.5.0",
 		"tailwindcss": "^4.3.2"
 	},
 	"devDependencies": {
 		"@types/pako": "^2.0.3",
-		"@types/qrcode": "^1.5.6",
-		"subset-font": "^2.5.0"
+		"@types/qrcode": "^1.5.6"
 	}
 }

package/scripts/generate-lqips.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * LQIP 生成脚本（M3b-b9，P1-14）：扫描站点 public 下的图片，每张采样
+ * 2×2 像素取三色，产出 18 字符 compact hex（三段 rgb hex 拼接），
+ * 整体写入站点根 lqips.json（键 → 色，全量重建，增量收益有限故不做）。
+ *
+ * 运行：pnpm --filter site lqip（cwd 必须是 site 根）
+ * 消费链路：lqips.json → themeLqipsPlugin（vite.ts）→ virtual:theme/lqips
+ *   → utils/lqip.ts getLqipStyle() → 构建期内联渐变（零客户端请求）。
+ *
+ * 键约定：`public:<posix 相对路径>`。主题图片一律 public 路径或外链
+ * （不用 astro:assets），故无需 src: 键；外链/无数据在消费端自然降级纯色。
+ * sharp 经本脚本文件位置解析到 theme 包依赖，与 cwd 无关。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+
+const cwd = process.cwd();
+const publicDir = path.join(cwd, "public");
+const outFile = path.join(cwd, "lqips.json");
+
+const EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".avif"]);
+const EXCLUDED_DIRS = new Set(["node_modules", ".astro", "dist", ".git"]);
+
+if (!fs.existsSync(publicDir)) {
+	console.error(`[lqip] 未找到 ${publicDir}，请在 site 根目录运行本脚本`);
+	process.exit(1);
+}
+
+/** 递归收集图片相对路径（posix 风格，排除构建/依赖目录） */
+function collectImages(dir, base = "") {
+	const out = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.isDirectory()) {
+			if (EXCLUDED_DIRS.has(entry.name)) continue;
+			out.push(
+				...collectImages(
+					path.join(dir, entry.name),
+					base ? `${base}/${entry.name}` : entry.name,
+				),
+			);
+		} else if (EXTS.has(path.extname(entry.name).toLowerCase())) {
+			out.push(base ? `${base}/${entry.name}` : entry.name);
+		}
+	}
+	return out;
+}
+
+/** sharp 2×2 fill 采样 → 取 [0][1][3] 三像素（左上/右上/右下）rgb hex 拼接 */
+async function sampleColors(file) {
+	const { data, info } = await sharp(file)
+		.resize(2, 2, { fit: "fill" })
+		.removeAlpha()
+		.raw()
+		.toBuffer({ resolveWithObject: true });
+	const hex = (i) => {
+		const o = i * info.channels;
+		return [data[o], data[o + 1], data[o + 2]]
+			.map((v) => v.toString(16).padStart(2, "0"))
+			.join("");
+	};
+	return hex(0) + hex(1) + hex(3);
+}
+
+try {
+	const files = collectImages(publicDir);
+	const entries = await Promise.all(
+		files.map(async (rel) => [
+			`public:${rel}`,
+			await sampleColors(path.join(publicDir, rel)),
+		]),
+	);
+	fs.writeFileSync(
+		outFile,
+		JSON.stringify(Object.fromEntries(entries), null, 2) + "\n",
+	);
+	console.log(`[lqip] ${files.length} 张图片 → ${path.relative(cwd, outFile)}`);
+} catch (err) {
+	console.error("[lqip] 生成失败：", err);
+	process.exit(1);
+}

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/i18n/en.ts

@@ -97,6 +97,9 @@ const en: Record<UiKey, string> = {
 	allTags: "All",
 	galleryNoAlbums: "No albums yet. Add one in theme config gallery.albums.",
 	galleryNoPhotos: "No photos in this album",
+	/* 说说页（§4.87） */
+	momentsTitle: "Moments",
+	momentsEmpty: "No moments yet.",
 	encryptedAlbum: "Encrypted album",
 	searchAlbumNoResults: "No matching albums",
 	postEncrypted: "Encrypted",

package/src/i18n/zh-CN.ts

@@ -112,6 +112,9 @@ const zhCN = {
 	allTags: "全部",
 	galleryNoAlbums: "还没有相册，在主题配置 gallery.albums 中添加。",
 	galleryNoPhotos: "相册里还没有照片",
+	/* 说说页（§4.87） */
+	momentsTitle: "说说",
+	momentsEmpty: "还没有说说。",
 	encryptedAlbum: "加密相册",
 	searchAlbumNoResults: "没有匹配的相册",
 	/* 加密文章（M3b-b7）：postEncrypted 用于列表/文章 meta 标记，其余构建期渲染进锁 UI */

package/src/index.ts

@@ -41,6 +41,7 @@ import {
 	rehypeExternalLinks,
 	rehypeFigure,
 	rehypeFirstImage,
+	rehypeNoReferrer,
 } from "./plugins/rehype.js";
 import {
 	rehypeDiagramPanZoom,
@@ -125,6 +126,8 @@ export function defineTheme(userConfig: ThemeConfig): AstroIntegration[] {
 					// GitHub 仓库卡片（§4.10）：github 标签 → 卡片（自带 target，须在外链处理前）
 					rehypeGithubCard,
 					rehypeExternalLinks,
+					// 图片防盗链（§4.87）：命中域名外链图加 no-referrer（domains 空时插件空转）
+					[rehypeNoReferrer, { domains: config.noReferrer.domains }],
 					rehypeCallouts,
 					rehypeFigure,
 					rehypeFirstImage,
@@ -308,9 +311,13 @@ export function defineTheme(userConfig: ThemeConfig): AstroIntegration[] {
 					["/page/[page]", "page/[page].astro"],
 					["/archive", "archive.astro"],
 					["/tags", "tags/index.astro"],
-					["/tags/[tag]", "tags/[tag].astro"],
+					// §4.87 分类/标签分页：第一页 /tags/<tag>/（page 段省略），后续 /2/ 起
+					["/tags/[tag]/[...page]", "tags/[tag]/[...page].astro"],
 					["/categories", "categories/index.astro"],
-					["/categories/[category]", "categories/[category].astro"],
+					[
+						"/categories/[category]/[...page]",
+						"categories/[category]/[...page].astro",
+					],
 					["/posts/[...slug]", "posts/[...slug].astro"],
 					// sitemap（§4.63）：改由官方 @astrojs/sitemap integration 产出
 					// sitemap-index.xml，原手写 /sitemap.xml 路由移除
@@ -333,6 +340,10 @@ export function defineTheme(userConfig: ThemeConfig): AstroIntegration[] {
 					routes.push(["/series", "series/index.astro"]);
 					routes.push(["/series/[name]", "series/[name].astro"]);
 				}
+				// 说说页（§4.87）：moments collection 时间流；站点需先定义该集合（默认关）
+				if (config.pages.moments) {
+					routes.push(["/moments/[...page]", "moments/[...page].astro"]);
+				}
 				// 相关/随机文章推荐（P1-12）：随机栏数据源
 				if (config.relatedPosts.enabled) {
 					routes.push(["/api/allPostMeta.json", "api/allPostMeta.json.ts"]);

package/src/plugins/rehype.ts

@@ -53,6 +53,44 @@ export function rehypeExternalLinks(): Transformer {
 	};
 }
 
+/**
+ * 图片防盗链（§4.87）：部分图床/CDN（如 B 站）校验 Referer 头，站内引用返回 403。
+ * 为匹配域名的外链 <img> 追加 referrerpolicy="no-referrer"（浏览器请求图片时不发
+ * Referer，绕过防盗链限制），仅影响外链图片与匹配域名，本地图片不受影响。
+ */
+export interface NoReferrerOptions {
+	/** 域名列表：裸域名匹配自身与全部子域；*.example.com 只匹配子域 */
+	domains: string[];
+}
+
+export function rehypeNoReferrer(options: NoReferrerOptions): Transformer {
+	if (!options.domains.length) return () => {};
+	const matchers = options.domains.map((domain) => {
+		const d = domain.toLowerCase();
+		if (d.startsWith("*.")) {
+			const base = d.slice(2);
+			return (host: string) => host.endsWith(`.${base}`) && host !== base;
+		}
+		return (host: string) => host === d || host.endsWith(`.${d}`);
+	});
+	return (tree) => {
+		visit(tree, (node) => {
+			if (node.type !== "element" || node.tagName !== "img") return;
+			const src = String(node.properties?.src ?? "");
+			if (!/^https?:\/\//i.test(src)) return;
+			let host: string;
+			try {
+				host = new URL(src).hostname.toLowerCase();
+			} catch {
+				return;
+			}
+			if (matchers.some((match) => match(host))) {
+				node.properties.referrerPolicy = "no-referrer";
+			}
+		});
+	};
+}
+
 /* -------------------------------------------------------------- callouts */
 
 const CALLOUT_META: Record<

package/src/routes/categories/[category]/[...page].astro

@@ -0,0 +1,53 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import Pagination from "virtual:theme/components/Pagination.astro";
+import config from "virtual:theme/config";
+import { t } from "../../../i18n/index.js";
+import {
+	collectCategories,
+	formatDate,
+	getSortedPosts,
+} from "../../../utils.js";
+
+/**
+ * 分类详情（§4.87 分页）：每分类按 postList.pageSize 分页，第一页
+ * /categories/<category>/（page 段省略），后续 /categories/<category>/2/ 起。
+ * paginate() helper 生成 Page 对象（props.page），Page.data 即当前页文章。
+ */
+export async function getStaticPaths({ paginate }: { paginate: any }) {
+	const all = await getCollection("posts", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	// 先排序再聚合，保证每个分类内文章按新→旧排列
+	const sorted = getSortedPosts(all);
+	return [...collectCategories(sorted).entries()].flatMap(([category, posts]) =>
+		paginate(posts, {
+			params: { category },
+			props: { category },
+			pageSize: config.postList.pageSize,
+		}),
+	);
+}
+
+const { page, category } = Astro.props;
+const posts = page.data;
+---
+
+<BaseLayout title={t('categoryTitle', { category })} page="categories">
+  <header class="archive-head reveal">
+    <h1 class="page-title">{category}</h1>
+    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+  </header>
+  <div class="tag-list">
+    {
+      posts.map((post: any) => (
+        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
+          <div class="rc-title">{post.data.title}</div>
+          <div class="rc-meta">{formatDate(post.data.published)}</div>
+        </a>
+      ))
+    }
+  </div>
+  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/categories/${category}/`} />
+</BaseLayout>

package/src/routes/moments/[...page].astro

@@ -0,0 +1,80 @@
+---
+import { getCollection, render } from "astro:content";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import Pagination from "virtual:theme/components/Pagination.astro";
+import config from "virtual:theme/config";
+import { t } from "../../i18n/index.js";
+import { formatDate } from "../../utils.js";
+
+/**
+ * 说说页（§4.87）：moments collection 时间流，按 published 新→旧，
+ * 每页 20 条（第一页 /moments/，后续 /moments/2/）。
+ * 正文走主题统一 markdown processor（全部增强语法可用）；配图 images 网格
+ * 展示并接入通用灯箱（data-lightbox-group 组浏览）。
+ */
+export async function getStaticPaths({ paginate }: { paginate: any }) {
+	const all = await getCollection("moments", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	const sorted = [...all].sort(
+		(a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
+	);
+	return paginate(sorted, { pageSize: 20 });
+}
+
+const { page } = Astro.props;
+const rendered = await Promise.all(
+	page.data.map(async (moment: any) => {
+		const { Content } = await render(moment);
+		return { moment, Content };
+	}),
+);
+---
+
+<BaseLayout title={t('momentsTitle')} page="moments">
+  <header class="archive-head reveal">
+    <h1 class="page-title">{t('momentsTitle')}</h1>
+  </header>
+
+  {
+    rendered.length === 0 ? (
+      <p class="gallery-empty reveal">{t('momentsEmpty')}</p>
+    ) : (
+      <div class="moments-list">
+        {rendered.map(({ moment, Content }) => (
+          <article class="moment card reveal">
+            <div class="moment-meta">
+              <time datetime={moment.data.published.toISOString()}>
+                {formatDate(moment.data.published)}
+              </time>
+              {moment.data.mood && <span class="moment-mood">{moment.data.mood}</span>}
+            </div>
+            <div class="moment-content">
+              <Content />
+            </div>
+            {moment.data.images.length > 0 && (
+              <div class="moment-images" data-lightbox-group>
+                {moment.data.images.map((src: string) => (
+                  <figure class="moment-img">
+                    <img src={src} alt={t('momentsTitle')} loading="lazy" decoding="async" />
+                  </figure>
+                ))}
+              </div>
+            )}
+            {moment.data.tags.length > 0 && (
+              <div class="moment-tags">
+                {moment.data.tags.map((tg: string) => (
+                  <a class="moment-tag" href={`/tags/${tg}/`}>
+                    {tg}
+                  </a>
+                ))}
+              </div>
+            )}
+          </article>
+        ))}
+      </div>
+    )
+  }
+
+  <Pagination page={page.currentPage} total={page.lastPage} basePath="/moments/" />
+</BaseLayout>

package/src/routes/rss.xml.ts

@@ -1,32 +1,59 @@
-import { getCollection } from "astro:content";
+import { getCollection, render } from "astro:content";
 import config from "virtual:theme/config";
 import rss from "@astrojs/rss";
 import type { APIContext, APIRoute } from "astro";
+import { experimental_AstroContainer as AstroContainer } from "astro/container";
 import { getSortedPosts } from "../utils.js";
 
 /**
- * RSS（§4.63 官方 @astrojs/rss 端点）：item description 使用 frontmatter
- * description，不做全文输出（避免 RSS 端点再渲染全部 Markdown）。
- * channel 头部、atom:link self、XML 转义由官方库负责；trailingSlash 与
- * 主题 trailingSlash: "always" 口径一致（/posts/xxx/）。
+ * RSS（§4.63 官方 @astrojs/rss 端点）：
+ * - 默认 item description 使用 frontmatter description（摘要输出）；
+ * - rss.fullText 开启后 item 追加 content:encoded 全文（§4.87）——经
+ *   AstroContainer 逐篇容器渲染 Markdown（与文章页同一套 remark/rehype 插件产物），
+ *   构建时间随文章数增加，默认关；
+ * - 条数 rss.limit（默认 20）；channel 头部、atom:link self、XML 转义由官方库负责；
+ *   trailingSlash 与主题 trailingSlash: "always" 口径一致（/posts/xxx/）。
  */
 export const GET: APIRoute = async (context: APIContext) => {
 	const all = await getCollection("posts", ({ data }) => !data.draft);
-	const posts = getSortedPosts(all).slice(0, 20);
+	const posts = getSortedPosts(all).slice(0, config.rss.limit);
 	const site = context.site ?? new URL("https://blog.example.com");
 
+	const items = await Promise.all(
+		posts.map(async (post) => {
+			const item: {
+				title: string;
+				description: string;
+				link: string;
+				pubDate: Date;
+				content?: string;
+			} = {
+				title: post.data.title,
+				description: post.data.description,
+				link: `/posts/${post.id}/`,
+				pubDate: post.data.published,
+			};
+			if (config.rss.fullText && !post.data.password) {
+				// 加密文章不进 RSS 全文（内容构建期加密，明文进 RSS 会绕过密码）
+				const { Content } = await render(post);
+				const container = await AstroContainer.create();
+				item.content = await container.renderToString(Content);
+			}
+			return item;
+		}),
+	);
+
 	return rss({
 		title: config.title,
 		description: config.description,
 		site,
-		items: posts.map((post) => ({
-			title: post.data.title,
-			description: post.data.description,
-			link: `/posts/${post.id}/`,
-			pubDate: post.data.published,
-		})),
-		// atom 命名空间 + feed 自引用（v4 不再自动生成，保持对原手写版的兼容）
-		xmlns: { atom: "http://www.w3.org/2005/Atom" },
+		items,
+		// atom 命名空间 + feed 自引用（v4 不再自动生成，保持对原手写版的兼容）；
+		// content 命名空间供 fullText 的 content:encoded 使用
+		xmlns: {
+			atom: "http://www.w3.org/2005/Atom",
+			content: "http://purl.org/rss/1.0/modules/content/",
+		},
 		// RSS <language> 通道级语言标记（跟随站点语言）
 		customData: [
 			`<language>${config.lang}</language>`,

package/src/routes/tags/[tag]/[...page].astro

@@ -0,0 +1,51 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import Pagination from "virtual:theme/components/Pagination.astro";
+import config from "virtual:theme/config";
+import { t } from "../../../i18n/index.js";
+import { collectTags, formatDate, getSortedPosts } from "../../../utils.js";
+
+/**
+ * 标签详情（§4.87 分页）：每标签按 postList.pageSize 分页，第一页
+ * /tags/<tag>/（page 段省略），后续 /tags/<tag>/2/ 起。结构与分类详情页一致。
+ */
+export async function getStaticPaths({ paginate }: { paginate: any }) {
+	const all = await getCollection("posts", ({ data }) =>
+		import.meta.env.PROD ? !data.draft : true,
+	);
+	// 先排序再聚合，保证每个标签内文章按新→旧排列
+	const sorted = getSortedPosts(all);
+	return [...collectTags(sorted).entries()].flatMap(([tag, posts]) =>
+		paginate(posts, {
+			params: { tag },
+			props: { tag },
+			pageSize: config.postList.pageSize,
+		}),
+	);
+}
+
+const { page, tag } = Astro.props;
+const posts = page.data;
+---
+
+<BaseLayout title={t('tagTitle', { tag })} page="tags">
+  <header class="archive-head reveal">
+    <h1 class="page-title">{tag}</h1>
+    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+  </header>
+  <div class="tag-list">
+    {
+      posts.map((post: any) => (
+        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
+          <div class="rc-title">{post.data.title}</div>
+          <div class="rc-meta">
+            {formatDate(post.data.published)}
+            {post.data.category ? ` · ${post.data.category}` : ''}
+          </div>
+        </a>
+      ))
+    }
+  </div>
+  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/tags/${tag}/`} />
+</BaseLayout>

package/src/schema.ts

@@ -342,6 +342,8 @@ export const themeConfigSchema = z.object({
 			gallery: z.boolean().default(true),
 			/** 专题（§4.31）：frontmatter series 聚合页 /series/ 与 /series/[name]/ */
 			series: z.boolean().default(true),
+			/** 说说页（§4.87）：/moments/ 短内容时间流；站点需定义 moments collection。默认关——老站点无该集合，开启前先在 content.config.ts 定义 */
+			moments: z.boolean().default(false),
 		})
 		.default({
 			about: true,
@@ -350,6 +352,7 @@ export const themeConfigSchema = z.object({
 			sponsor: true,
 			gallery: true,
 			series: true,
+			moments: false,
 		}),
 	/**
 	 * 画廊/相册（M3b-b8）。相册数据纯配置驱动，照片两个来源：
@@ -915,6 +918,26 @@ export const themeConfigSchema = z.object({
 			method: z.enum(["base64", "rot13"]).default("base64"),
 		})
 		.default({ enabled: false, method: "base64" }),
+	/**
+	 * 图片防盗链（§4.87）：部分图床/CDN（如 B 站）校验 Referer，站内引用返回 403。
+	 * 命中域名列表的外链图片构建期追加 referrerpolicy="no-referrer"。
+	 * 裸域名匹配自身与全部子域；*.example.com 只匹配子域。留空不处理。
+	 */
+	noReferrer: z
+		.object({
+			domains: z.array(z.string()).default([]),
+		})
+		.default({ domains: [] }),
+	/**
+	 * RSS 输出（§4.87）：fullText 开启后 item 带 content:encoded 全文
+	 * （构建期逐篇容器渲染，构建时间相应增加）；limit 控制输出条数。
+	 */
+	rss: z
+		.object({
+			fullText: z.boolean().default(false),
+			limit: z.number().int().min(1).default(20),
+		})
+		.default({ fullText: false, limit: 20 }),
 	/**
 	 * favicon 图标列表（§4.30）：数组非空时替换默认 /favicon.svg；
 	 * theme 指定 "light"/"dark" 时按系统深浅色经 media 切换（可配双图标）。
@@ -1216,3 +1239,24 @@ export function definePostSchema(extensions: z.ZodRawShape = {}) {
 		})
 		.extend(extensions);
 }
+
+/**
+ * 内容 schema 工厂：说说集合 frontmatter（§4.87 说说页）。
+ * 站点 content.config.ts 定义 moments collection（loader 扫描
+ * src/content/moments 目录下全部 .md 文件，schema 用本工厂）。
+ * 正文即说说内容（Markdown，支持主题全部增强语法）；主题开关 pages.moments
+ * 打开后注入 /moments/（时间流，按 published 新→旧，每页 20 条）。
+ */
+export function defineMomentSchema(extensions: z.ZodRawShape = {}) {
+	return z
+		.object({
+			published: z.coerce.date(),
+			/** 心情 emoji（卡片右上角展示） */
+			mood: z.string().optional(),
+			tags: z.array(z.string()).default([]),
+			/** 配图（public 路径或外链，网格展示 + 灯箱浏览） */
+			images: z.array(z.string()).default([]),
+			draft: z.boolean().default(false),
+		})
+		.extend(extensions);
+}

package/src/styles/global.css

@@ -3088,6 +3088,9 @@ html.dark .series-nav-item.cur .series-nav-row {
 .gallery-banner {
 	position: relative;
 	overflow: hidden;
+	/* 显式定宽阻断 aspect-ratio 反推：窄容器下 min-height 拉高后 3/1 会
+	   反解出 200×3=600px 的宽度穿透容器，导致页面横向滚动（§4.86） */
+	width: 100%;
 	border-radius: var(--radius);
 	aspect-ratio: 3 / 1;
 	min-height: 200px;
@@ -3208,6 +3211,8 @@ gallery-filter {
 .gallery-masonry {
 	column-count: 2;
 	column-gap: 12px;
+	/* 与封面横幅/降级头部的间隔（§4.86，原来零间距贴合） */
+	margin-top: 24px;
 }
 @media (min-width: 640px) {
 	.gallery-masonry {
@@ -3234,6 +3239,84 @@ gallery-filter {
 	transform: scale(1.025);
 }
 
+/* 说说页（§4.87）：时间流卡片 */
+.moments-list {
+	display: flex;
+	flex-direction: column;
+	gap: 16px;
+}
+.moment {
+	padding: 18px 22px;
+}
+.moment-meta {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	margin-bottom: 10px;
+	font-size: 13px;
+	color: var(--muted);
+}
+.moment-mood {
+	font-size: 18px;
+	line-height: 1;
+}
+.moment-content {
+	font-size: 15px;
+	line-height: 1.75;
+}
+.moment-content > :first-child {
+	margin-top: 0;
+}
+.moment-content > :last-child {
+	margin-bottom: 0;
+}
+.moment-images {
+	display: grid;
+	grid-template-columns: repeat(3, 1fr);
+	gap: 8px;
+	margin-top: 12px;
+}
+@media (max-width: 480px) {
+	.moment-images {
+		grid-template-columns: repeat(2, 1fr);
+	}
+}
+.moment-img {
+	overflow: hidden;
+	border-radius: var(--radius-sm);
+	background: var(--bg-soft);
+	cursor: zoom-in;
+}
+.moment-img img {
+	display: block;
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+	aspect-ratio: 1 / 1;
+	transition: transform 0.35s ease;
+}
+.moment-img:hover img {
+	transform: scale(1.04);
+}
+.moment-tags {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px;
+	margin-top: 12px;
+}
+.moment-tag {
+	padding: 1px 10px;
+	border-radius: 999px;
+	font-size: 12px;
+	color: var(--ink-2);
+	background: var(--bg-soft);
+	transition: background-color 0.15s;
+}
+.moment-tag:hover {
+	background: var(--accent-soft);
+	color: var(--ink);
+}
+
 /* 灯箱（§4.69）：样式由 photoswipe/photoswipe.css 提供（BaseLayout 引入） */
 /* 灯箱自定义 UI（§4.70/§4.71）：全屏/自动播放按钮与缩略图条（可开关、内容居中）。
    自定义图标用 .qy-pswp-icn 独立类名，避开 .pswp__icn 的 fill 覆盖（图标走 stroke 描边） */

package/src/routes/categories/[category].astro

@@ -1,37 +0,0 @@
----
-import { getCollection } from "astro:content";
-import BaseLayout from "virtual:theme/components/BaseLayout.astro";
-import { t } from "../../i18n/index.js";
-import { collectCategories, formatDate, getSortedPosts } from "../../utils.js";
-
-// 先排序再聚合，保证每个分类内文章按新→旧排列
-export async function getStaticPaths() {
-	const all = await getCollection("posts", ({ data }) =>
-		import.meta.env.PROD ? !data.draft : true,
-	);
-	const sorted = getSortedPosts(all);
-	return [...collectCategories(sorted).entries()].map(([category, posts]) => ({
-		params: { category },
-		props: { category, posts },
-	}));
-}
-
-const { category, posts } = Astro.props;
----
-
-<BaseLayout title={t('categoryTitle', { category })} page="categories">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{category}</h1>
-    <p class="page-sub">{t('totalPosts', { n: posts.length })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">{formatDate(post.data.published)}</div>
-        </a>
-      ))
-    }
-  </div>
-</BaseLayout>

package/src/routes/tags/[tag].astro

@@ -1,40 +0,0 @@
----
-import { getCollection } from "astro:content";
-import BaseLayout from "virtual:theme/components/BaseLayout.astro";
-import { t } from "../../i18n/index.js";
-import { collectTags, formatDate, getSortedPosts } from "../../utils.js";
-
-// 先排序再聚合，保证每个标签内文章按新→旧排列
-export async function getStaticPaths() {
-	const all = await getCollection("posts", ({ data }) =>
-		import.meta.env.PROD ? !data.draft : true,
-	);
-	const sorted = getSortedPosts(all);
-	return [...collectTags(sorted).entries()].map(([tag, posts]) => ({
-		params: { tag },
-		props: { tag, posts },
-	}));
-}
-
-const { tag, posts } = Astro.props;
----
-
-<BaseLayout title={t('tagTitle', { tag })} page="tags">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{tag}</h1>
-    <p class="page-sub">{t('totalPosts', { n: posts.length })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">
-            {formatDate(post.data.published)}
-            {post.data.category ? ` · ${post.data.category}` : ''}
-          </div>
-        </a>
-      ))
-    }
-  </div>
-</BaseLayout>