@windcoder/astro-theme-orchid 0.0.0-stage → 0.2.0

package/src/utils/crypto.ts

@@ -0,0 +1,46 @@
+/**
+ * 构建期内容加密（M3b-b7）：AES-256-GCM + PBKDF2（node:crypto）。
+ * 与客户端 app.ts 的 Web Crypto 解密参数严格对齐：
+ *   PBKDF2-SHA256 100000 轮派生 256 位密钥；输出 base64(salt[16] + iv[12] + authTag[16] + ciphertext)。
+ * salt/iv 由 password + slug 经 HMAC-SHA256 确定性派生——同一篇文与同一密码
+ * 每次构建产出相同密文，使 sessionStorage 缓存的密码跨刷新/跨构建稳定有效。
+ * 密文经 data-* 属性输出，文本内容不含明文；注：这是「防君子」级保护，
+ * 密钥材料来自用户输入，安全性依赖密码强度。
+ */
+import { createCipheriv, createHmac, pbkdf2Sync } from "node:crypto";
+
+const PBKDF2_ITERATIONS = 100_000;
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const KEY_LENGTH = 32;
+
+/** 由 key + 上下文字符串确定性派生 length 字节（HMAC-SHA256 截断） */
+function deriveBytes(key: string, context: string, length: number): Buffer {
+	return createHmac("sha256", key).update(context).digest().subarray(0, length);
+}
+
+/** 加密 HTML 字符串，输出 base64(salt + iv + authTag + ciphertext) */
+export function encryptContent(
+	html: string,
+	password: string,
+	slug: string,
+): string {
+	const salt = deriveBytes(password, `salt:${slug}`, SALT_LENGTH);
+	const iv = deriveBytes(password, `iv:${slug}`, IV_LENGTH);
+	const key = pbkdf2Sync(
+		password,
+		salt,
+		PBKDF2_ITERATIONS,
+		KEY_LENGTH,
+		"sha256",
+	);
+
+	const cipher = createCipheriv("aes-256-gcm", key, iv);
+	const encrypted = Buffer.concat([
+		cipher.update(html, "utf8"),
+		cipher.final(),
+	]);
+	const authTag = cipher.getAuthTag();
+
+	return Buffer.concat([salt, iv, authTag, encrypted]).toString("base64");
+}

package/src/utils/gallery.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 画廊相册扫描（M3b-b8）：构建期在站点根目录扫描 public/gallery/<id>/。
+ * process.cwd() 在 dev/build 时均为站点项目根，与 Astro 解析 public/ 一致。
+ */
+
+const IMAGE_RE = /\.(jpe?g|png|webp|avif|gif)$/i;
+const COVER_RE = /^cover\./i;
+
+export interface GalleryAlbumMeta {
+	id: string;
+	name: string;
+	description?: string;
+	date?: string;
+	location?: string;
+	tags?: string[];
+	cover?: string;
+	password?: string;
+	passwordHint?: string;
+}
+
+/**
+ * 扫描相册照片：本地文件（cover.* 提到首位）+ urls.txt 远程 URL（追加在本地之后）。
+ * 目录不存在返回空数组（空相册合法，渲染空态）。
+ */
+export function scanAlbumPhotos(albumId: string): string[] {
+	const dir = path.join(process.cwd(), "public", "gallery", albumId);
+	if (!fs.existsSync(dir)) return [];
+
+	const files = fs
+		.readdirSync(dir)
+		.filter((f) => IMAGE_RE.test(f))
+		.sort();
+	const coverIdx = files.findIndex((f) => COVER_RE.test(f));
+	if (coverIdx > 0) {
+		const [coverFile] = files.splice(coverIdx, 1);
+		files.unshift(coverFile);
+	}
+	const localPhotos = files.map((f) => `/gallery/${albumId}/${f}`);
+
+	// urls.txt：每行一个远程图片 URL，# 开头为注释
+	const urlsFile = path.join(dir, "urls.txt");
+	let remotePhotos: string[] = [];
+	if (fs.existsSync(urlsFile)) {
+		remotePhotos = fs
+			.readFileSync(urlsFile, "utf-8")
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line && !line.startsWith("#"));
+	}
+	return [...localPhotos, ...remotePhotos];
+}
+
+/** 相册封面：显式 cover → cover.* 文件 → 第一张照片 → 空（空态兜底） */
+export function getAlbumCover(
+	album: GalleryAlbumMeta,
+	photos: string[],
+): string {
+	if (album.cover) return album.cover;
+	const coverFile = photos.find((p) => COVER_RE.test(p));
+	return coverFile || photos[0] || "";
+}
+
+/** 列表页数据组装：扫描 + 封面 + 计数一次完成 */
+export function buildAlbumIndex(albums: GalleryAlbumMeta[]) {
+	return albums.map((album) => {
+		const photos = scanAlbumPhotos(album.id);
+		return {
+			...album,
+			cover: getAlbumCover(album, photos),
+			photoCount: photos.length,
+		};
+	});
+}

package/src/utils/lqip.ts

@@ -0,0 +1,18 @@
+/**
+ * LQIP 占位渐变（M3b-b9，P1-14）：构建期从 virtual:theme/lqips 查表，
+ * 返回内联渐变样式。查不到（外链 / data URL / 未生成 lqips.json）时
+ * 返回纯色兜底，功能自然降级，无需配置开关。
+ */
+import lqips from "virtual:theme/lqips";
+
+/** 图片 public 路径（/assets/x.jpg）→ 18 字符 compact hex 三段渐变背景 */
+export function getLqipStyle(src: string): string {
+	const hex = lqips[`public:${src.replace(/^\//, "")}`];
+	if (hex && /^[0-9a-f]{18}$/i.test(hex)) {
+		const c1 = `#${hex.slice(0, 6)}`;
+		const c2 = `#${hex.slice(6, 12)}`;
+		const c3 = `#${hex.slice(12, 18)}`;
+		return `background:linear-gradient(135deg, ${c1} 0%, ${c2} 50%, ${c3} 100%)`;
+	}
+	return "background:var(--muted)";
+}

package/src/utils/related.ts

@@ -0,0 +1,101 @@
+import type { PostLike } from "../utils.js";
+
+/**
+ * 标题分词：Intl.Segmenter 对中文按词切分，英文/数字按词切分；
+ * 过滤标点与空白，英文统一小写。每次调用新建 segmenter 成本可接受（构建期）。
+ */
+function tokenizeTitle(title: string): Set<string> {
+	const tokens = new Set<string>();
+	const segmenter = new Intl.Segmenter("zh", { granularity: "word" });
+	for (const { segment, isWordLike } of segmenter.segment(title)) {
+		if (!isWordLike) continue;
+		tokens.add(segment.toLowerCase());
+	}
+	return tokens;
+}
+
+/** Jaccard 相似度：交集 / 并集（空集对空集记 0） */
+function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+	if (a.size === 0 && b.size === 0) return 0;
+	let intersection = 0;
+	for (const item of a) {
+		if (b.has(item)) intersection++;
+	}
+	const union = a.size + b.size - intersection;
+	return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * 相关文章推荐（P1-12，移植自 orchid-blog getRelatedPosts）。
+ * 评分：totalScore = tagMatchScore(0-100) + titleSimilarityScore(0-100)
+ *                    + timeFreshnessScore(0-30) + categoryBonus(0|10)
+ * - 标签/标题均为 Jaccard 相似度 × 100
+ * - 时间新鲜度按 6 个月半衰期指数衰减
+ * - 同分类加 10 分
+ * 候选排除：自身与加密文章（加密内容不可预览，标题亦不进推荐位）。
+ * 排序：先取有标签匹配者（按总分降序），不足 maxCount 时
+ * 用无标签匹配者按「新鲜度 + 同分类」降序补充。
+ */
+export function getRelatedPosts<T extends PostLike>(
+	all: T[],
+	current: T,
+	maxCount = 5,
+): T[] {
+	if (maxCount <= 0) return [];
+	const candidates = all.filter((p) => p.id !== current.id && !p.data.password);
+
+	const currentTags = new Set(current.data.tags || []);
+	const currentTokens = tokenizeTitle(current.data.title);
+	const currentCategory = current.data.category || "";
+	const now = Date.now();
+
+	const scored = candidates.map((post) => {
+		const tagMatchScore =
+			jaccardSimilarity(currentTags, new Set(post.data.tags || [])) * 100;
+		const titleSimilarityScore =
+			jaccardSimilarity(currentTokens, tokenizeTitle(post.data.title)) * 100;
+		const daysSincePublished =
+			(now - post.data.published.getTime()) / (1000 * 60 * 60 * 24);
+		const timeFreshnessScore =
+			30 * Math.exp((-Math.LN2 * daysSincePublished) / 180);
+		const postCategory = post.data.category || "";
+		const categoryBonus =
+			currentCategory && postCategory && currentCategory === postCategory
+				? 10
+				: 0;
+		return {
+			post,
+			totalScore:
+				tagMatchScore +
+				titleSimilarityScore +
+				timeFreshnessScore +
+				categoryBonus,
+			tagMatchScore,
+			timeFreshnessScore,
+			categoryBonus,
+		};
+	});
+
+	scored.sort((a, b) => b.totalScore - a.totalScore);
+
+	const result: T[] = [];
+	for (const s of scored) {
+		if (result.length >= maxCount) break;
+		if (s.tagMatchScore > 0) result.push(s.post);
+	}
+	if (result.length < maxCount) {
+		const rest = scored
+			.filter((s) => s.tagMatchScore === 0)
+			.sort(
+				(a, b) =>
+					b.timeFreshnessScore +
+					b.categoryBonus -
+					(a.timeFreshnessScore + a.categoryBonus),
+			);
+		for (const s of rest) {
+			if (result.length >= maxCount) break;
+			result.push(s.post);
+		}
+	}
+	return result;
+}

package/src/utils.ts

@@ -0,0 +1,233 @@
+import config from "virtual:theme/config";
+
+/**
+ * 格式化为 YYYY-MM-DD（§4.30：配置 timezone 时经 Intl timeZone 指定，与构建机时区解耦；
+ * 未配置跟随本地时区，避免 toISOString 的 UTC 偏移）
+ */
+export function formatDate(date: Date): string {
+	return new Intl.DateTimeFormat("en-CA", {
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		timeZone: config.timezone || undefined,
+	}).format(date);
+}
+
+/** 文章最小结构约束：兼容站点内 CollectionEntry<'posts'> 与主题内部中间结果 */
+export interface PostLike {
+	id: string;
+	body?: string;
+	data: {
+		title: string;
+		description: string;
+		published: Date;
+		updated?: Date;
+		draft: boolean;
+		pinned: boolean;
+		image?: string;
+		tags: string[];
+		category?: string;
+		/** 加密文章：非空即视为加密（列表锁标 / 正文条件加密 / 评论 TOC 规避） */
+		password?: string;
+		/** 加密提示（仅展示，不参与解密） */
+		passwordHint?: string;
+		/** remark 插件注入：摘要 / 首图 / 字数 / 阅读时长 */
+		excerpt?: string;
+		firstImage?: string;
+		words?: number;
+		minutes?: number;
+		cardStyle?: "cover" | "compact" | "text";
+		/** 专题名（§4.31）：同专题文章聚合到 /series/<name>/ */
+		series?: string;
+		/** 专题内顺序（小在前）；未配置则按发布时间升序 */
+		seriesOrder?: number;
+		/** 专题内分组（§4.75）：专题页/专题目录按组分块展示 */
+		seriesGroup?: string;
+	};
+}
+
+/**
+ * hex（#rrggbb）转 HSL，用于构建期把 accentColor 注入 --accent-h/s/l。
+ * 例：#4a9d8f → { h: 170, s: 36, l: 45 }
+ */
+export function hexToHsl(hex: string): { h: number; s: number; l: number } {
+	const m = hex.replace("#", "");
+	const r = parseInt(m.slice(0, 2), 16) / 255;
+	const g = parseInt(m.slice(2, 4), 16) / 255;
+	const b = parseInt(m.slice(4, 6), 16) / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const l = (max + min) / 2;
+	let h = 0;
+	let s = 0;
+	if (max !== min) {
+		const d = max - min;
+		s = d / (1 - Math.abs(2 * l - 1));
+		switch (max) {
+			case r:
+				h = 60 * (((g - b) / d) % 6);
+				break;
+			case g:
+				h = 60 * ((b - r) / d + 2);
+				break;
+			default:
+				h = 60 * ((r - g) / d + 4);
+		}
+	}
+	return {
+		h: Math.round((h + 360) % 360),
+		s: Math.round(s * 100),
+		l: Math.round(l * 100),
+	};
+}
+
+/** 过滤草稿并排序：置顶优先，其余按发布时间倒序 */
+export function getSortedPosts<T extends PostLike>(posts: T[]): T[] {
+	return posts
+		.filter((p) => !p.data.draft)
+		.sort((a, b) => {
+			if (a.data.pinned !== b.data.pinned) return a.data.pinned ? -1 : 1;
+			return b.data.published.getTime() - a.data.published.getTime();
+		});
+}
+
+/** 专题内排序比较器：seriesOrder 升序（未配置排最后），同序按发布时间升序 */
+function compareSeriesOrder<T extends PostLike>(a: T, b: T): number {
+	const oa = a.data.seriesOrder ?? Number.MAX_SAFE_INTEGER;
+	const ob = b.data.seriesOrder ?? Number.MAX_SAFE_INTEGER;
+	if (oa !== ob) return oa - ob;
+	return a.data.published.getTime() - b.data.published.getTime();
+}
+
+/** 专题渲染序列条目：groupHead 非空 = 该条目是新分块首条，值为组名（未分组块无头） */
+export interface SeriesEntry<T> {
+	post: T;
+	/** 全局序号（0 起，贯穿分块连续编号） */
+	index: number;
+	groupHead: string | null;
+}
+
+/**
+ * 专题分块序列（§4.75）：按 seriesOrder 排序后分块规范化——
+ * 未分组文章为最前块，各分组（seriesGroup 非空）按组内首篇顺序依次排列。
+ * 同组文章 seriesOrder 不连续时自动归拢，不依赖作者保证组内连续。
+ * 序号贯穿所有分块连续递增，供专题页与文章页专题目录共用。
+ */
+export function seriesEntries<T extends PostLike>(
+	posts: T[],
+): SeriesEntry<T>[] {
+	const sorted = [...posts].sort(compareSeriesOrder);
+	const entries: SeriesEntry<T>[] = [];
+	const groups = new Map<string, T[]>();
+	for (const post of sorted) {
+		const group = post.data.seriesGroup;
+		if (!group) {
+			entries.push({ post, index: entries.length, groupHead: null });
+			continue;
+		}
+		const list = groups.get(group);
+		if (list) list.push(post);
+		else groups.set(group, [post]);
+	}
+	for (const [group, list] of groups) {
+		for (const post of list) {
+			entries.push({
+				post,
+				index: entries.length,
+				groupHead: post === list[0] ? group : null,
+			});
+		}
+	}
+	return entries;
+}
+
+/** 按标签聚合：Map<标签名, 文章[]>，标签按文章数降序 */
+export function collectTags<T extends PostLike>(posts: T[]): Map<string, T[]> {
+	const map = new Map<string, T[]>();
+	for (const post of posts) {
+		for (const tag of post.data.tags) {
+			const list = map.get(tag);
+			if (list) list.push(post);
+			else map.set(tag, [post]);
+		}
+	}
+	return new Map([...map.entries()].sort((a, b) => b[1].length - a[1].length));
+}
+
+/** 按分类聚合：Map<分类名, 文章[]>，分类按文章数降序（无分类文章不参与） */
+export function collectCategories<T extends PostLike>(
+	posts: T[],
+): Map<string, T[]> {
+	const map = new Map<string, T[]>();
+	for (const post of posts) {
+		const cat = post.data.category;
+		if (!cat) continue;
+		const list = map.get(cat);
+		if (list) list.push(post);
+		else map.set(cat, [post]);
+	}
+	return new Map([...map.entries()].sort((a, b) => b[1].length - a[1].length));
+}
+
+/** 计算整站已发布文章总字数（站点信息卡「共 N 字」用） */
+export function countTotalWords(posts: PostLike[]): number {
+	return posts.reduce((sum, p) => sum + (p.data.words ?? 0), 0);
+}
+
+/** 建站至今天数（since: YYYY-MM-DD） */
+export function daysSince(since: string): number {
+	const start = new Date(`${since}T00:00:00`);
+	if (Number.isNaN(start.getTime())) return 0;
+	return Math.max(0, Math.floor((Date.now() - start.getTime()) / 86400000));
+}
+
+/* ---------- 随机封面（§4.33） ---------- */
+
+/**
+ * Java String.hashCode 同款散列：同 slug 跨构建/跨设备稳定，
+ * 作为随机封面的确定性 seed（对齐 orchid-blog getSeedHash）。
+ */
+export function seedHash(str: string): number {
+	let h = 0;
+	for (let i = 0; i < str.length; i++)
+		h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+	return Math.abs(h);
+}
+
+/** 把 seed 拼进 URL（已有 query 用 &，否则 ?），同 URL 每次构建请求同图 */
+export function appendSeedParam(url: string, hash: number): string {
+	return `${url}${url.includes("?") ? "&" : "?"}v=${hash}`;
+}
+
+/**
+ * 随机封面单条 URL：{slug} 占位符替换为文章 id，再追加 ?v=<hash>。
+ * 同 slug 的/apis[i] 输出恒定 → 列表页与文章页、多次构建之间图片一致。
+ */
+export function randomCoverUrl(template: string, slug: string): string {
+	const withSlug = template.includes("{slug}")
+		? template.replaceAll("{slug}", slug)
+		: template;
+	return appendSeedParam(withSlug, seedHash(slug));
+}
+
+/**
+ * 解析文章封面（§4.33）：frontmatter image 为 "api" 且配置了图源时，
+ * 返回 { cover, retries }——cover 为主图 URL，retries 为客户端
+ * 加载失败时的依次重试列表（图源全量 + fallbackCover 兜底）。
+ * 非 "api" 或未配置图源时原样返回，行为与之前一致。
+ */
+export function resolveCover(
+	image: string | undefined,
+	firstImage: string | undefined,
+	fallbackCover: string | undefined,
+	apis: string[],
+	slug: string,
+): { cover: string | undefined; retries: string[] | undefined } {
+	if (image !== "api" || apis.length === 0) {
+		return { cover: image || firstImage || fallbackCover, retries: undefined };
+	}
+	const cover = randomCoverUrl(apis[0], slug);
+	const retries = [...apis.map((u) => randomCoverUrl(u, slug))];
+	if (fallbackCover) retries.push(fallbackCover);
+	return { cover, retries };
+}

package/src/vite.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ResolvedThemeConfig } from "./schema.js";
+
+/**
+ * 主题内部统一通过 `virtual:theme/...` 引用可覆盖组件：
+ *   import Header from 'virtual:theme/components/Header.astro'
+ * 解析优先级：site/src/overrides/（路径镜像虚拟 id，去掉前缀）
+ *   virtual:theme/components/X.astro → site/src/overrides/components/X.astro
+ *   下存在同名文件时优先采用；override 文件内部再 import 同一虚拟路径时
+ * 强制走默认实现，从而支持「包装默认实现」式定制而不产生自引用死循环。
+ */
+const VIRTUAL_PREFIX = "virtual:theme/";
+
+export function overridesPlugin() {
+	// vite.ts 位于包内 src/ 下，默认实现根即 src/
+	const themeSrcDir = path.dirname(fileURLToPath(import.meta.url));
+	let overridesDir: string | undefined;
+
+	return {
+		name: "@windcoder/astro-theme-orchid:overrides",
+		enforce: "pre" as const,
+		// root 在 configResolved 阶段确定（兼容 URL / string 两种形态）
+		configResolved(resolvedConfig: { root: URL | string }) {
+			const rootDir =
+				typeof resolvedConfig.root === "string"
+					? resolvedConfig.root
+					: fileURLToPath(resolvedConfig.root);
+			overridesDir = path.join(rootDir, "src", "overrides");
+		},
+		resolveId(id: string, importer?: string) {
+			if (!id.startsWith(VIRTUAL_PREFIX)) return null;
+			const rel = id.slice(VIRTUAL_PREFIX.length);
+			if (overridesDir) {
+				const relImporter = importer
+					? path.relative(overridesDir, importer)
+					: "";
+				const importerInOverrides =
+					!!importer &&
+					relImporter !== "" &&
+					!relImporter.startsWith("..") &&
+					!path.isAbsolute(relImporter);
+				if (!importerInOverrides) {
+					const overrideFile = path.join(overridesDir, rel);
+					if (fs.existsSync(overrideFile)) return overrideFile;
+				}
+			}
+			return path.join(themeSrcDir, rel);
+		},
+	};
+}
+
+/** 将站点配置暴露为虚拟模块，主题组件通过 `import config from 'virtual:theme/config'` 消费 */
+export function themeConfigPlugin(config: ResolvedThemeConfig) {
+	const virtualId = "virtual:theme/config";
+	const resolvedId = "\0" + virtualId;
+	return {
+		name: "@windcoder/astro-theme-orchid:config",
+		enforce: "pre" as const,
+		resolveId(id: string) {
+			return id === virtualId ? resolvedId : null;
+		},
+		load(id: string) {
+			if (id === resolvedId) return `export default ${JSON.stringify(config)};`;
+		},
+	};
+}
+
+/**
+ * LQIP 虚拟模块（M3b-b9，P1-14）：读取站点根 lqips.json
+ * （generate-lqips.mjs 产物，键 `public:<路径>` → 18 字符 compact hex），
+ * 以 `virtual:theme/lqips` 暴露给构建期内联占位渐变（utils/lqip.ts）。
+ * 文件缺失（未跑生成脚本）时导出空对象，消费端自然降级纯色，不阻塞构建。
+ * 注意：本插件必须注册在 overridesPlugin 之前——后者的 resolveId 会兜住
+ * 所有 virtual:theme/* 并返回一个不存在的文件路径。
+ */
+export function themeLqipsPlugin() {
+	const virtualId = "virtual:theme/lqips";
+	const resolvedId = "\0" + virtualId;
+	let lqips: Record<string, string> = {};
+	return {
+		name: "@windcoder/astro-theme-orchid:lqips",
+		enforce: "pre" as const,
+		configResolved(resolvedConfig: { root: URL | string }) {
+			const rootDir =
+				typeof resolvedConfig.root === "string"
+					? resolvedConfig.root
+					: fileURLToPath(resolvedConfig.root);
+			try {
+				lqips = JSON.parse(
+					fs.readFileSync(path.join(rootDir, "lqips.json"), "utf8"),
+				);
+			} catch {
+				lqips = {};
+			}
+		},
+		resolveId(id: string) {
+			return id === virtualId ? resolvedId : null;
+		},
+		load(id: string) {
+			if (id === resolvedId) return `export default ${JSON.stringify(lqips)};`;
+		},
+	};
+}