@xingwangzhe/stalux 1.2.0

package/src/utils/collections-stats.ts

@@ -0,0 +1,48 @@
+import { getCollection, type CollectionEntry } from "astro:content";
+
+type Post = CollectionEntry<"posts">;
+
+/** 统一拉取已发布的文章集合，避免各统计函数重复查询。 */
+async function getPosts(): Promise<Post[]> {
+    return getCollection("posts", ({ data }) => !data.draft);
+}
+
+/**
+ * 统计 posts 中每个分类键出现的次数。
+ * @param posts 文章集合
+ * @param keyFn 从单篇文章取出若干分类键（如标签、分类）
+ * @param defaultValue 文章没有任何分类键时的兜底分类名（可选）
+ */
+function countBy(
+    posts: Post[],
+    keyFn: (post: Post) => string[] | undefined,
+    defaultValue?: string,
+): Array<{ name: string; count: number }> {
+    const counts = new Map<string, number>();
+    for (const post of posts) {
+        const keys = keyFn(post) ?? [];
+        const names = keys.length > 0 ? keys : defaultValue ? [defaultValue] : [];
+        for (const name of names) {
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return [...counts].map(([name, count]) => ({ name, count }));
+}
+
+/**
+ * 获取标签计数统计（用于标签云）
+ * @returns Array<{ name: string; count: number }>
+ */
+export async function getTagCountList() {
+    const posts = await getPosts();
+    return countBy(posts, (p) => p.data.tags);
+}
+
+/**
+ * 获取分类计数统计（用于分类列表）
+ * @returns Array<{ name: string; count: number }>
+ */
+export async function getCategoryCountList() {
+    const posts = await getPosts();
+    return countBy(posts, (p) => p.data.categories, "uncategorized");
+}

package/src/utils/config-utils.ts

@@ -0,0 +1,107 @@
+import type {
+    AuthorData,
+    AiDiscoveryData,
+    CommentData,
+    FooterData,
+    HeadData,
+    LinksData,
+    MediaLinksData,
+    NavsData,
+    PromoteData,
+    SiteData,
+    TypetextsData,
+} from "@schemas/config";
+/**
+ * 类型安全的 Config 访问工具
+ *
+ * 利用 discriminated union + for/if 窄化，零 as/any/unknown 类型垃圾。
+ *
+ * 每个函数单独写 for + if (entry.id === 具体字面量)，
+ * TS 在此条件分支中自动收窄 entry.data 为对应类型。
+ */
+import type { CollectionEntry } from "astro:content";
+
+// ===================================================================
+// Config 集合 (stalux/config/*.yml)
+// ===================================================================
+
+export function getSiteData(entries: CollectionEntry<"config">[]): SiteData {
+    for (const entry of entries) {
+        if (entry.id === "site") return entry.data;
+    }
+    throw new Error("Missing site config");
+}
+
+export function getAuthorData(entries: CollectionEntry<"config">[]): AuthorData {
+    for (const entry of entries) {
+        if (entry.id === "author") return entry.data;
+    }
+    throw new Error("Missing author config");
+}
+
+export function getHeadData(entries: CollectionEntry<"config">[]): HeadData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "head") return entry.data;
+    }
+    return undefined;
+}
+
+export function getNavsData(entries: CollectionEntry<"config">[]): NavsData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "navs") return entry.data;
+    }
+    return undefined;
+}
+
+export function getTypetextsData(entries: CollectionEntry<"config">[]): TypetextsData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "typetexts") return entry.data;
+    }
+    return undefined;
+}
+
+export function getMediaLinksData(
+    entries: CollectionEntry<"config">[],
+): MediaLinksData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "media-links") return entry.data;
+    }
+    return undefined;
+}
+
+export function getLinksData(entries: CollectionEntry<"config">[]): LinksData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "links") return entry.data;
+    }
+    return undefined;
+}
+
+export function getFooterData(entries: CollectionEntry<"config">[]): FooterData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "footer") return entry.data;
+    }
+    return undefined;
+}
+
+export function getCommentData(entries: CollectionEntry<"config">[]): CommentData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "comment") return entry.data;
+    }
+    return undefined;
+}
+
+export function getPromoteData(entries: CollectionEntry<"config">[]): PromoteData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "promote") return entry.data;
+    }
+    return undefined;
+}
+
+export function getAiDiscoveryData(
+    entries: CollectionEntry<"config">[],
+): AiDiscoveryData | undefined {
+    for (const entry of entries) {
+        if (entry.id === "ai-discovery") return entry.data;
+    }
+    return undefined;
+}

package/src/utils/count-words.ts

@@ -0,0 +1,20 @@
+/**
+ * CJK 友好的字数统计 — 基于 W3C Intl.Segmenter API（UAX #29 标准分词）。
+ *
+ * 替代手写 Unicode 正则的方案：
+ * - CJK 字符：`Intl.Segmenter` 逐字分割，每个字计 1
+ * - 拉丁/数字/其他字母文字：按词计 1
+ * - 标点/空白不计
+ */
+const segmenter = new Intl.Segmenter("zh", { granularity: "word" });
+
+/**
+ * 统计文本字数（基于 Intl.Segmenter 分词）。
+ */
+export function countWords(text: string): number {
+    let count = 0;
+    for (const { isWordLike } of segmenter.segment(text)) {
+        if (isWordLike) count++;
+    }
+    return count;
+}

package/src/utils/dayjs.ts

@@ -0,0 +1,106 @@
+/**
+ * 日期工具 — 纯原生 Date + Intl，无 date-fns 依赖。
+ * 保留旧 dayjs 封装导出名，方便现有调用方继续使用。
+ */
+
+/** 解析日期字符串，返回 Date 对象 */
+export const parseDate = (v: unknown): Date => {
+    if (v == null || v === 0 || v === "") return new Date(0);
+    const d = new Date(v as string | number | Date);
+    return Number.isNaN(d.getTime()) ? new Date(0) : d;
+};
+
+/** 是否为有效日期 */
+export const isValid = (d: Date): boolean => !Number.isNaN(d.getTime());
+
+/** 获取时间戳（用于排序比较） */
+export const toTimestamp = (v: unknown): number => parseDate(v).getTime();
+
+const pad2 = (n: number): string => String(n).padStart(2, "0");
+
+/**
+ * 轻量 format：仅覆盖本项目实际用到的 token。
+ * 支持：yyyy MM dd HH mm ss
+ */
+export function format(date: Date | string | number, formatStr: string): string {
+    const d = date instanceof Date ? date : new Date(date);
+    if (Number.isNaN(d.getTime())) return "";
+
+    // 本地时区（与原先 date-fns format 默认行为一致）
+    // 单次正则替换，避免 replaceAll 链式替换的 token 交叉问题
+    const tokens: Record<string, string> = {
+        yyyy: String(d.getFullYear()),
+        MM: pad2(d.getMonth() + 1),
+        dd: pad2(d.getDate()),
+        HH: pad2(d.getHours()),
+        mm: pad2(d.getMinutes()),
+        ss: pad2(d.getSeconds()),
+    };
+    return formatStr.replace(/yyyy|MM|dd|HH|mm|ss/g, (t) => tokens[t] ?? t);
+}
+
+/**
+ * 在指定 IANA 时区中格式化为带偏移的 ISO 局部串。
+ * 默认输出：yyyy-MM-dd'T'HH:mm:ssXXX（如 2026-03-27T14:30:00+08:00）
+ */
+export function formatInTimeZone(
+    date: Date | string | number,
+    timeZone: string,
+    formatStr: string = "yyyy-MM-dd'T'HH:mm:ssXXX",
+): string {
+    const d = date instanceof Date ? date : new Date(date);
+    if (Number.isNaN(d.getTime())) return "";
+
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "longOffset",
+    }).formatToParts(d);
+
+    const get = (type: Intl.DateTimeFormatPartTypes): string =>
+        parts.find((p) => p.type === type)?.value ?? "";
+
+    const year = get("year");
+    const month = get("month");
+    const day = get("day");
+    const hour = get("hour");
+    const minute = get("minute");
+    const second = get("second");
+
+    let offset = get("timeZoneName"); // GMT+08:00 / UTC / GMT
+    if (offset === "GMT" || offset === "UTC") {
+        offset = "+00:00";
+    } else {
+        offset = offset.replace(/^GMT/, "").replace(/^UTC/, "");
+        if (!offset.startsWith("+") && !offset.startsWith("-")) {
+            offset = `+${offset}`;
+        }
+        const m = offset.match(/^([+-])(\d{1,2})(?::?(\d{2}))?$/);
+        if (m) {
+            offset = `${m[1]}${m[2].padStart(2, "0")}:${m[3] || "00"}`;
+        }
+    }
+
+    // 目前调用方只使用这一种 pattern；保留 formatStr 参数以便兼容签名
+    if (formatStr === "yyyy-MM-dd'T'HH:mm:ssXXX") {
+        return `${year}-${month}-${day}T${hour}:${minute}:${second}${offset}`;
+    }
+
+    // 回退：按 token 替换（不含 locale 名）
+    const tokens: Record<string, string> = {
+        yyyy: year,
+        MM: month,
+        dd: day,
+        HH: hour,
+        mm: minute,
+        ss: second,
+        XXX: offset,
+    };
+    return formatStr.replace(/yyyy|MM|dd|HH|mm|ss|XXX/g, (t) => tokens[t] ?? t);
+}

package/src/utils/feed.ts

@@ -0,0 +1,70 @@
+import { toTimestamp, parseDate, isValid, formatInTimeZone } from "@utils/dayjs";
+import { toMachineDateTime } from "@utils/semantic-time";
+import { getPostDescriptions } from "@utils/word-count-utils";
+import type { CollectionEntry } from "astro:content";
+
+interface FeedConfig {
+    timezone: string;
+}
+
+interface FeedItem {
+    title: string;
+    pubDate: Date;
+    description: string;
+    link: string;
+    categories: string[];
+    customData: string;
+}
+
+/**
+ * 构建 RSS / Atom 共用的 feed 条目列表。
+ * 两个端点的唯一差异是“更新时间”节点名（RSS 用 `atom:updated`，Atom 用 `updated`），
+ * 通过 updatedTag 参数化，避免整文件复制。
+ *
+ * 性能：文章描述走共享缓存 getPostDescriptions()，避免每个端点各自渲染；
+ * 排序用 updated ?? date 的时间戳做纯数字比较。
+ */
+export async function buildFeedItems(
+    stalux: FeedConfig,
+    posts: CollectionEntry<"posts">[],
+    updatedTag: string,
+): Promise<FeedItem[]> {
+    const sortedPosts = [...posts].sort((a, b) => {
+        // Newest first: compare post dates, use the greater of updated/date
+        const aTime = toTimestamp(a.data.updated || a.data.date);
+        const bTime = toTimestamp(b.data.updated || b.data.date);
+        return bTime - aTime;
+    });
+
+    const descriptions = await getPostDescriptions();
+    return Promise.all(
+        sortedPosts.map(async (post) => {
+            const cached = descriptions.get(String(post.data.abbrlink));
+
+            let customData = "";
+            if (post.data.updated) {
+                const parsed = parseDate(post.data.updated);
+                if (isValid(parsed)) {
+                    const updatedIso = formatInTimeZone(
+                        parsed,
+                        stalux.timezone,
+                        "yyyy-MM-dd'T'HH:mm:ssXXX",
+                    );
+                    customData += `<${updatedTag}>${updatedIso}</${updatedTag}>`;
+                }
+            }
+            if (post.data.cc) {
+                customData += `<rights>${post.data.cc}</rights>`;
+            }
+
+            return {
+                title: post.data.title,
+                pubDate: new Date(toMachineDateTime(post.data.date, stalux.timezone)),
+                description: cached?.desc || post.data.desc || "",
+                link: `/posts/${post.data.abbrlink}/`,
+                categories: post.data.categories || [],
+                customData,
+            };
+        }),
+    );
+}

package/src/utils/i18n.ts

@@ -0,0 +1,64 @@
+import en from "@i18n/en.json";
+import zhCN from "@i18n/zh-CN.json";
+
+const dicts: Record<string, Record<string, unknown>> = {
+    "zh-CN": zhCN as Record<string, unknown>,
+    en: en as Record<string, unknown>,
+};
+
+export interface Translator {
+    t(key: string, params?: Record<string, string | number>): string;
+    lang: string;
+}
+
+export function createTranslator(lang: string): Translator {
+    const dict = dicts[lang] || dicts["zh-CN"];
+
+    function t(key: string, params?: Record<string, string | number>): string {
+        const keys = key.split(".");
+        let text: unknown = dict;
+        for (const k of keys) {
+            if (text && typeof text === "object") {
+                text = (text as Record<string, unknown>)[k];
+            } else {
+                return key;
+            }
+        }
+        if (typeof text !== "string") return key;
+
+        let result = text;
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                result = result.replace(`{${k}}`, String(v));
+            }
+        }
+        return result;
+    }
+
+    return { t, lang };
+}
+
+/**
+ * Map config lang value to OpenGraph locale format.
+ * e.g. "zh-CN" → "zh_CN", "en" → "en_US"
+ */
+export function langToOpenGraphLocale(lang: string): string {
+    const map: Record<string, string> = {
+        "zh-CN": "zh_CN",
+        "zh-TW": "zh_TW",
+        en: "en_US",
+        "en-US": "en_US",
+        "en-GB": "en_GB",
+        ja: "ja_JP",
+        ko: "ko_KR",
+    };
+    return map[lang] || lang;
+}
+
+/**
+ * Map config lang value to RSS/Atom feed language tag.
+ * e.g. "zh-CN" → "zh-cn", "en" → "en-us"
+ */
+export function langToFeedLanguage(lang: string): string {
+    return lang.toLowerCase();
+}

package/src/utils/lucide-icons.ts

@@ -0,0 +1,52 @@
+/**
+ * 导航等场景用到的 Lucide 图标静态映射。
+ * 按需从 @lucide/astro 导入，避免整包 lucide 依赖。
+ *
+ * 新增图标：在下方 import 并写入 iconMap 即可（key 为 kebab-case，与 config.yml 一致）。
+ * 图标列表: https://lucide.dev/icons/
+ */
+import type { AstroComponent } from "@lucide/astro";
+import Airplay from "@lucide/astro/icons/airplay";
+import Archive from "@lucide/astro/icons/archive";
+import Folder from "@lucide/astro/icons/folder";
+import House from "@lucide/astro/icons/house";
+import Link from "@lucide/astro/icons/link";
+import Menu from "@lucide/astro/icons/menu";
+import Quote from "@lucide/astro/icons/quote";
+import Search from "@lucide/astro/icons/search";
+import Tag from "@lucide/astro/icons/tag";
+import TrainFront from "@lucide/astro/icons/train-front";
+import User from "@lucide/astro/icons/user";
+import X from "@lucide/astro/icons/x";
+
+/** config.yml 中 icon 字段（kebab-case）→ Astro 图标组件 */
+const iconMap: Record<string, AstroComponent> = {
+    home: House,
+    house: House,
+    archive: Archive,
+    folder: Folder,
+    tag: Tag,
+    quote: Quote,
+    link: Link,
+    user: User,
+    "train-front": TrainFront,
+    menu: Menu,
+    search: Search,
+    x: X,
+    airplay: Airplay,
+};
+
+/**
+ * 按 kebab-case 名称取图标组件；找不到时打日志并返回 null。
+ */
+export function getLucideIcon(iconName: string | undefined | null): AstroComponent | null {
+    if (!iconName) return null;
+    const Icon = iconMap[iconName];
+    if (!Icon) {
+        console.error(
+            `lucide 图标 '${iconName}' 未找到，请在 src/utils/lucide-icons.ts 中添加映射`,
+        );
+        return null;
+    }
+    return Icon;
+}

package/src/utils/semantic-time.ts

@@ -0,0 +1,11 @@
+import { parseDate, formatInTimeZone } from "@utils/dayjs";
+
+/**
+ * 将原始时间字符串转换为机器可读的带时区 ISO 格式
+ * @param dateStr - frontmatter 中的原始时间字符串
+ * @param timezone - IANA 时区字符串，如 "Asia/Shanghai"
+ * @returns 带时区的 ISO 8601 格式字符串
+ */
+export function toMachineDateTime(dateStr: string, timezone: string): string {
+    return formatInTimeZone(parseDate(dateStr), timezone, "yyyy-MM-dd'T'HH:mm:ssXXX");
+}

package/src/utils/taxonomy.ts

@@ -0,0 +1,44 @@
+import { toTimestamp } from "@utils/dayjs";
+import { getCollection, type CollectionEntry, type GetStaticPathsResult } from "astro:content";
+
+type TaxonomyKey = "tags" | "categories";
+
+/**
+ * 为 tags / categories 分类页生成 getStaticPaths 结果。
+ *
+ * 复杂度优化：每个 post 只解析一次时间（`postTs`），
+ * 用数字时间戳比较“最近更新”，避免原实现在内层循环里反复
+ * `new Date()` 解析同一个时间字符串（最坏 O(n × 平均标签数) 次 Date 构造）。
+ */
+export async function buildTaxonomyStaticPaths(key: TaxonomyKey): Promise<GetStaticPathsResult> {
+    const posts = await getCollection("posts", ({ data }) => !data.draft);
+    const paramName = key === "tags" ? "tag" : "category";
+    const map = new Map<
+        string,
+        { posts: CollectionEntry<"posts">[]; latestTs: number; latestTime: string }
+    >();
+
+    for (const post of posts) {
+        const postTime = post.data.updated ?? post.data.date;
+        const postTs = toTimestamp(postTime);
+        for (const name of post.data[key] ?? []) {
+            const entry = map.get(name) ?? { posts: [], latestTs: postTs, latestTime: postTime };
+            entry.posts.push(post);
+            if (postTs > entry.latestTs) {
+                entry.latestTs = postTs;
+                entry.latestTime = postTime;
+            }
+            map.set(name, entry);
+        }
+    }
+
+    return [...map].map(([name, entry]) => ({
+        params: { [paramName]: name },
+        props: {
+            [paramName]: name,
+            count: entry.posts.length,
+            posts: entry.posts,
+            lastUpdateDate: entry.latestTime,
+        },
+    }));
+}

package/src/utils/toc-scrollspy.ts

@@ -0,0 +1,95 @@
+/**
+ * TOC 滚动同步 —— 文章正文滚动时，自动高亮右侧目录中对应的条目，
+ * 并将该条目滚动到侧边栏可视区域内。
+ */
+
+export function initTocScrollSpy(activeClass: string) {
+    const tocLinks = document.querySelectorAll<HTMLAnchorElement>("[data-toc-link]");
+    if (tocLinks.length === 0) return;
+
+    // 建立标题 ID → 目录链接元素的映射
+    const linkMap = new Map<string, HTMLAnchorElement>();
+    for (const link of tocLinks) {
+        const id = link.getAttribute("href")?.replace("#", "");
+        if (id) linkMap.set(id, link);
+    }
+
+    // 按 DOM 顺序解析出文章中的标题元素
+    const headings = [...linkMap.keys()]
+        .map((id) => document.getElementById(id))
+        .filter((el): el is HTMLElement => el !== null);
+
+    if (headings.length === 0) return;
+
+    let activeLink: HTMLAnchorElement | null = null;
+    let pending = false;
+    let sidebarHovered = false;
+
+    // 鼠标悬停在侧边栏上时跳过自动滚动，避免跟用户手动操作冲突
+    const sidebar = tocLinks[0]?.closest<HTMLElement>("[data-toc-active-class]");
+    if (sidebar) {
+        sidebar.addEventListener("mouseenter", () => {
+            sidebarHovered = true;
+        });
+        sidebar.addEventListener("mouseleave", () => {
+            sidebarHovered = false;
+        });
+    }
+
+    // 切换当前高亮的目录项，并将该项滚动到侧边栏可视区域内
+    const setActive = (link: HTMLAnchorElement | null) => {
+        if (activeLink === link) return;
+        activeLink?.classList.remove(activeClass);
+        activeLink = link;
+        if (link && !sidebarHovered) {
+            link.classList.add(activeClass);
+            link.scrollIntoView({ block: "nearest", behavior: "smooth" });
+        } else if (link) {
+            // 用户正在操作侧边栏时只高亮，不自动滚动
+            link.classList.add(activeClass);
+        }
+    };
+
+    const observer = new IntersectionObserver(
+        () => {
+            // 用 rAF 合并同一帧内的多次回调，避免频繁触发布局计算
+            if (pending) return;
+            pending = true;
+            requestAnimationFrame(() => {
+                pending = false;
+
+                // 找到视口上方 35% 区域内最靠上的标题
+                let current =
+                    headings.find((h) => {
+                        const rect = h.getBoundingClientRect();
+                        return rect.top < window.innerHeight * 0.35 && rect.bottom > 0;
+                    }) ?? null;
+
+                // 兜底：滚动到文章底部时，取最后一个仍在视口上方或已经越过顶部的标题
+                current ??=
+                    headings.findLast((h) => {
+                        const rect = h.getBoundingClientRect();
+                        return rect.bottom <= window.innerHeight * 0.35 || rect.top < 0;
+                    }) ?? null;
+
+                setActive(current ? (linkMap.get(current.id) ?? null) : null);
+            });
+        },
+        {
+            rootMargin: "0px 0px -65% 0px",
+            threshold: 0,
+        },
+    );
+
+    for (const h of headings) observer.observe(h);
+
+    // 拦截 TOC 锚点点击，替换为平滑滚动
+    for (const link of tocLinks) {
+        link.addEventListener("click", (e) => {
+            e.preventDefault();
+            const id = link.getAttribute("href")?.replace("#", "");
+            const target = id ? document.getElementById(id) : null;
+            target?.scrollIntoView({ behavior: "smooth", block: "start" });
+        });
+    }
+}

package/src/utils/waline.ts

@@ -0,0 +1,27 @@
+/**
+ * 从主题配置（stalux.comment.waline，类型较宽松）中提取 Waline 组件所需的 props，
+ * 集中处理字段透传，避免在每个调用处（about / PostLayout）重复十几行 as any 赋值块。
+ */
+export function buildWalineProps(walineConfig: unknown) {
+    const c = (walineConfig ?? {}) as Record<string, unknown>;
+    return {
+        serverURL: c.serverURL,
+        lang: c.lang,
+        locale: c.locale,
+        emoji: c.emoji,
+        reaction: c.reaction,
+        meta: c.meta,
+        wordLimit: c.wordLimit,
+        pageSize: c.pageSize,
+        login: c.login,
+        recaptchaV3Key: c.recaptchaV3Key,
+        turnstileKey: c.turnstileKey,
+        dark: c.dark,
+        noCopyright: c.noCopyright,
+        commentSorting: c.commentSorting,
+        imageUploader: c.imageUploader,
+        highlighter: c.highlighter,
+        texRenderer: c.texRenderer,
+        search: c.search,
+    };
+}