@xingwangzhe/stalux 1.24.7 → 1.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.24.7",
+    "version": "1.25.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/components/stalux/analytics/clarity.astro

@@ -1,25 +1,4 @@
 ---
-import { getCollection } from "astro:content";
-import { getHeadData } from "@utils/config-utils";
-const configEntries = await getCollection("config");
-const headConfig = getHeadData(configEntries);
-const id = headConfig?.bingClarityId;
 ---
 
-<script is:inline data-astro-rerun define:vars={{ id }}>
-    // 防止重复初始化
-    const load = () => {
-        if (!id || document.getElementById("stalux-clarity-script") || window.clarity) return;
-        (function (c, l, a, r, i, t, y) {
-            c[a] = c[a] || function () { (c[a].q = c[a].q || []).push(arguments); };
-            t = l.createElement(r);
-            t.id = "stalux-clarity-script";
-            t.async = 1;
-            t.src = "https://www.clarity.ms/tag/" + i;
-            y = l.getElementsByTagName(r)[0];
-            y.parentNode.insertBefore(t, y);
-        })(window, document, "clarity", "script", id);
-    };
-    if ("requestIdleCallback" in window) requestIdleCallback(load, { timeout: 4000 });
-    else window.addEventListener("load", () => setTimeout(load, 0), { once: true });
-</script>
+<script src="../../../scripts/clarity.ts"></script>

package/src/components/stalux/analytics/google.astro

@@ -1,34 +1,4 @@
 ---
-import { getCollection } from "astro:content";
-import { getHeadData } from "@utils/config-utils";
-const configEntries = await getCollection("config");
-const headConfig = getHeadData(configEntries);
-const gaID = headConfig?.googleAnalyticsId;
 ---
 
-<script is:inline define:vars={{ gaID }}>
-    (() => {
-        const load = () => {
-            if (window.__staluxAnalyticsLoaded) return;
-            window.__staluxAnalyticsLoaded = true;
-            const script = document.createElement("script");
-            script.async = true;
-            script.src = `https://www.googletagmanager.com/gtag/js?id=${gaID}`;
-            document.head.appendChild(script);
-            window.dataLayer = window.dataLayer || [];
-            window.gtag = window.gtag || function () {
-                window.dataLayer.push(arguments);
-            };
-            window.gtag("js", new Date());
-            window.gtag("config", gaID);
-            if (!window.__gtagListenerAdded) {
-                document.addEventListener("astro:page-load", () => {
-                    window.gtag("event", "page_view", { page_path: window.location.pathname });
-                });
-                window.__gtagListenerAdded = true;
-            }
-        };
-        if ("requestIdleCallback" in window) requestIdleCallback(load, { timeout: 3000 });
-        else window.addEventListener("load", () => setTimeout(load, 0), { once: true });
-    })();
-</script>
+<script src="../../../scripts/google-analytics.ts"></script>

package/src/components/stalux/common/verCount.astro

@@ -2,15 +2,4 @@
 
 ---
 
-<script is:inline data-astro-rerun>
-    (() => {
-        const load = () => {
-            const script = document.createElement("script");
-            script.defer = true;
-            script.src = "https://events.vercount.one/js";
-            document.head.appendChild(script);
-        };
-        if ("requestIdleCallback" in window) requestIdleCallback(load, { timeout: 5000 });
-        else window.addEventListener("load", () => setTimeout(load, 0), { once: true });
-    })();
-</script>
+<script src="../../../scripts/vercount.ts"></script>

package/src/components/stalux/footer/FooterStats.astro

@@ -41,7 +41,7 @@ const { showStats = true, wordCount, buildtime } = Astro.props;
 
 {
     buildtime && (
-        <div class="site-build-time">
+        <div class="site-build-time" data-stalux-buildtime={buildtime} data-stalux-runtime-format={t("footer.runtimeFormat")}>
             <span>
                 {t("footer.runningTime")}
                 <span id="runtime-counter" />
@@ -50,41 +50,7 @@ const { showStats = true, wordCount, buildtime } = Astro.props;
     )
 }
 
-<script define:vars={{ buildtime, runtimeFormat: t("footer.runtimeFormat") }}>
-    document.addEventListener("astro:page-load", () => {
-        if (!buildtime) return;
-        const runtimeCounter = document.getElementById("runtime-counter");
-        if (!runtimeCounter) return;
-
-        const updateRuntime = () => {
-            const now = new Date();
-            const start = new Date(buildtime);
-            const diffMs = now.getTime() - start.getTime();
-            if (Number.isNaN(diffMs) || diffMs < 0) return;
-
-            const totalSeconds = Math.floor(diffMs / 1000);
-            const days = Math.floor(totalSeconds / 86400);
-            const hours = Math.floor((totalSeconds % 86400) / 3600);
-            const minutes = Math.floor((totalSeconds % 3600) / 60);
-            const seconds = totalSeconds % 60;
-
-            runtimeCounter.textContent = runtimeFormat
-                .replace("{days}", String(days))
-                .replace("{hours}", String(hours))
-                .replace("{minutes}", String(minutes))
-                .replace("{seconds}", String(seconds));
-        };
-
-        updateRuntime();
-        // define:vars 内联脚本会在每次视图切换时重新执行，
-        // 因此用 window 句柄记录定时器，创建新定时器前先清掉旧的，避免累加 1Hz 定时器。
-        const w = window;
-        if (w.__staluxRuntimeTimer != null) {
-            clearInterval(w.__staluxRuntimeTimer);
-        }
-        w.__staluxRuntimeTimer = setInterval(updateRuntime, 1000);
-    });
-</script>
+<script src="../../../scripts/runtime-counter.ts"></script>
 
 <style>
     .site-stats {

package/src/components/stalux/layout/head.astro

@@ -269,7 +269,7 @@ if (isArticle) {
     ],
   };
 }
-const ldJson = JSON.stringify(schema, null, 2).replace(/<\//g, "<\\/");
+const ldJson = JSON.stringify(schema).replace(/<\//g, "<\\/");
 ---
 
 <head>

package/src/components/stalux/posts/randomPost.astro

@@ -3,132 +3,23 @@ import style from "@styles/components/posts/randomPost.module.css";
 import { getCollection } from "astro:content";
 import { createTranslator } from "@utils/i18n";
 
-interface Props {
-    count?: number;
-    title?: string;
-}
-
+interface Props { count?: number; title?: string; }
 const configEntries = await getCollection("config");
-const siteConfig = (configEntries.find(e => e.id === "site")?.data ?? {}) as Record<string, unknown>;
+const siteConfig = (configEntries.find((entry) => entry.id === "site")?.data ?? {}) as Record<string, unknown>;
 const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
 const { count = 5, title = t("randomPost.title") } = Astro.props;
 ---
-
-<aside class={style.container} transition:persist-props aria-label={t("randomPost.title")}>
+<aside class={style.container} transition:persist-props aria-label={t("randomPost.title")} data-stalux-random-posts data-count={count} data-no-posts={t("randomPost.noPosts")} data-load-failed={t("randomPost.loadFailed")} data-load-error={t("randomPost.loadError")}>
     <div class={style.header}>
         <h3 class={style.title}>{title}</h3>
-        <button
-            id="refresh-random-posts"
-            class={style.refreshButton}
-            title={t("randomPost.refresh")}
-            aria-label={t("randomPost.refresh")}
-        >
-            <svg
-                xmlns="http://www.w3.org/2000/svg"
-                width="16"
-                height="16"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-            >
-                <path
-                    d="M21.5 2v6h-6M2.5 22v-6h6M2 11.5a10 10 0 0 1 18.8-4.3M22 12.5a10 10 0 0 1-18.8 4.2"
-                ></path>
+        <button id="refresh-random-posts" class={style.refreshButton} title={t("randomPost.refresh")} aria-label={t("randomPost.refresh")}>
+            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <path d="M21.5 2v6h-6M2.5 22v-6h6M2 11.5a10 10 0 0 1 18.8-4.3M22 12.5a10 10 0 0 1-18.8 4.2"></path>
             </svg>
         </button>
     </div>
     <ul class={style.list} id="random-posts-list">
         <li class={style.loading}>{t("randomPost.loading")}</li>
-	    </ul>
-	</aside>
-
-<script define:vars={{ count, labels: { noPosts: t("randomPost.noPosts"), loadFailed: t("randomPost.loadFailed"), loadError: t("randomPost.loadError") } }}>
-    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-    // 费雪-耶茨洗牌（crypto 优先，回退 Math.random）
-    const shuffleArray = (array) => {
-        const shuffled = [...array];
-        const randomIndex = (max) => {
-            if (globalThis.crypto?.getRandomValues) {
-                const buf = new Uint32Array(1);
-                crypto.getRandomValues(buf);
-                return buf[0] % max;
-            }
-            return Math.floor(Math.random() * max);
-        };
-        for (let i = shuffled.length - 1; i > 0; i--) {
-            const j = randomIndex(i + 1);
-            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
-        }
-        return shuffled;
-    };
-
-    const fetchRandomPosts = async () => {
-        try {
-            const response = await fetch("/api/post.abbrlink.json");
-            if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
-            return (await response.json()) ?? [];
-        } catch (error) {
-            console.error("Failed to fetch posts:", error);
-            return [];
-        }
-    };
-
-    const generatePostsHTML = (posts) => {
-        if (posts.length === 0) {
-            return `<li class="no-posts">${labels.noPosts}</li>`;
-        }
-        return posts
-            .map(
-                (post) => `
-            <li class="random-post-item">
-                <a href="/posts/${post.abbrlink}/" class="random-post-link a-none">
-                    ${post.title}
-                </a>
-            </li>
-        `,
-            )
-            .join("");
-    };
-
-    const renderRandomPosts = async (listEl, emptyMsg, errorMsg) => {
-        try {
-            const allPosts = await fetchRandomPosts();
-            if (allPosts.length === 0) {
-                listEl.innerHTML = `<li class="no-posts">${emptyMsg}</li>`;
-                return;
-            }
-            listEl.innerHTML = generatePostsHTML(shuffleArray(allPosts).slice(0, count));
-        } catch (error) {
-            console.error("Error rendering random posts:", error);
-            listEl.innerHTML = `<li class="error">${errorMsg}</li>`;
-        }
-    };
-
-    const refreshRandomPosts = async () => {
-        const randomPostsList = document.getElementById("random-posts-list");
-        if (!randomPostsList) return;
-
-        randomPostsList.style.opacity = "0.5";
-        await sleep(300);
-        await renderRandomPosts(randomPostsList, labels.noPosts, labels.loadFailed);
-        randomPostsList.style.opacity = "1";
-    };
-
-    document.addEventListener("astro:page-load", () => {
-        const refreshButton = document.getElementById("refresh-random-posts");
-        refreshButton?.addEventListener("click", async (e) => {
-            e.preventDefault();
-            refreshButton.classList.add("rotating");
-            await refreshRandomPosts();
-            await sleep(600);
-            refreshButton.classList.remove("rotating");
-        });
-
-        const list = document.getElementById("random-posts-list");
-        if (list) void renderRandomPosts(list, labels.noPosts, labels.loadError);
-    });
-</script>
+    </ul>
+</aside>
+<script src="../../../scripts/random-posts.ts"></script>

package/src/index.ts

@@ -8,7 +8,14 @@
  * 基于 Astro 7.1.3 Integration API（astro:config:setup / injectRoute / injectScript）
  */
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import {
+    copyFileSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    readdirSync,
+    writeFileSync,
+} from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -28,6 +35,34 @@ import { runFontSlicing, type FontSlice } from "./internal/font-slices";
 import { featureFlagsHast, featureFlagsMdast } from "./plugins/feature-flags";
 import { temml } from "./plugins/satteri-temml";
 
+function stripGeneratedHtmlComments(outDir: string): void {
+    const walk = (dir: string) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const target = path.join(dir, entry.name);
+            if (entry.isDirectory()) walk(target);
+            else if (entry.isFile() && entry.name.endsWith(".html")) {
+                const source = readFileSync(target, "utf8");
+                const protectedBlocks: string[] = [];
+                const protectedSource = source.replace(
+                    /<(pre|code|textarea)\b[\s\S]*?<\/\1>/gi,
+                    (block) => {
+                        protectedBlocks.push(block);
+                        return `__STALUX_PROTECTED_HTML_${protectedBlocks.length - 1}__`;
+                    },
+                );
+                const stripped = protectedSource
+                    .replace(/<!--(?!\[if)[\s\S]*?-->/g, "")
+                    .replace(
+                        /__STALUX_PROTECTED_HTML_(\d+)__/g,
+                        (_, index: string) => protectedBlocks[Number(index)] ?? "",
+                    );
+                if (stripped !== source) writeFileSync(target, stripped);
+            }
+        }
+    };
+    walk(outDir);
+}
+
 // 字体配置（Astro Fonts API）通过 updateConfig 注入，两种模式（源码模板/npm 插件）都生效。
 // 官方 local provider 完全本地读文件（readFile），不联网；
 // 7.2.2 已修复 Fonts API 随机端口污染 incrementalBuild dependencyHash 的问题（PR #17659）。
@@ -112,6 +147,7 @@ function getRoutes(baseDir: URL): RouteEntry[] {
         { pattern: "/atom.xml", entrypoint: resolvePage("./pages/atom.xml.ts") },
         { pattern: "/llms.txt", entrypoint: resolvePage("./pages/llms.txt.ts") },
         { pattern: "/llms-full.txt", entrypoint: resolvePage("./pages/llms-full.txt.ts") },
+        { pattern: "/openapi.json", entrypoint: resolvePage("./pages/openapi.json.ts") },
         {
             pattern: "/api/post.abbrlink.json",
             entrypoint: resolvePage("./pages/api/post.abbrlink.json.ts"),
@@ -438,9 +474,12 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
             },
 
             "astro:build:done": async ({ dir, logger }) => {
+                const outDir = fileURLToPath(dir);
+                stripGeneratedHtmlComments(outDir);
+                logger.info("Removed generated HTML comments (preserved pre/code/textarea blocks)");
+
                 // 6. 后处理：Pagefind 搜索索引
                 if (opt.pagefind) {
-                    const outDir = fileURLToPath(dir);
                     logger.info("Running Pagefind indexer...");
 
                     try {

package/src/layouts/Stalux.astro

@@ -5,7 +5,7 @@ import { getCollection } from "astro:content";
 import "@styles/base/init.css";
 import "@styles/shared/stagger.css";
 import "@styles/shared/view-transitions.css";
-import { getAuthorData, getAiDiscoveryData, getPromoteData, getSiteData } from "@utils/config-utils";
+import { getAuthorData, getAiDiscoveryData, getHeadData, getPromoteData, getSiteData } from "@utils/config-utils";
 import { getRouteAnimation, getRouteKind } from "@utils/view-transitions";
 const props = Astro.props as Props;
 
@@ -25,6 +25,7 @@ interface Props {
 const configEntries = await getCollection("config");
 const siteConfig = getSiteData(configEntries);
 const authorConfig = getAuthorData(configEntries);
+const headConfig = getHeadData(configEntries);
 const promoteConfig = getPromoteData(configEntries);
 const aiConfig = getAiDiscoveryData(configEntries);
 const htmlLang = siteConfig.lang || "zh-CN";
@@ -65,21 +66,6 @@ const routeAnimation = getRouteAnimation(routeKind);
   {
     aiConfig?.conformance !== "disabled" && (
       <>
-        <script
-          define:vars={{
-            siteTitle: siteConfig.title,
-            siteUrl: siteConfig.url,
-            siteDesc: siteConfig.description,
-            siteLang: siteConfig.lang,
-          }}
-        >
-          window.__STALUX_SITE_INFO__ = {
-            title: siteTitle,
-            url: siteUrl,
-            description: siteDesc,
-            lang: siteLang,
-          };
-        </script>
         <script>
           import "../scripts/webmcp.ts";
         </script>
@@ -90,8 +76,18 @@ const routeAnimation = getRouteAnimation(routeKind);
     class="stalux-root dark"
     data-stalux-bg-layer="a"
     data-stalux-bg-index="0"
+    data-stalux-site-title={siteConfig.title}
+    data-stalux-site-url={siteConfig.url}
+    data-stalux-site-description={siteConfig.description}
+    data-stalux-site-lang={siteConfig.lang}
+    data-stalux-ga-id={headConfig?.googleAnalyticsId}
+    data-stalux-clarity-id={headConfig?.bingClarityId}
   >
-    {llmPromote && <div style="display:none">{llmPromote}</div>}
+    {llmPromote && (
+      <section class="stalux-ai-prompt" data-stalux-ai-prompt aria-label="AI site context">
+        <p>{llmPromote}</p>
+      </section>
+    )}
     <div
       class="bg-layer bg-a"
       style="opacity: 1;"
@@ -116,3 +112,17 @@ const routeAnimation = getRouteAnimation(routeKind);
 </html>
 
 <style></style>
+
+<style>
+  .stalux-ai-prompt {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: pre-wrap;
+    border: 0;
+  }
+</style>

package/src/pages/404.astro

@@ -21,42 +21,12 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
     <div class="error-content">
       <h1>404</h1>
       <p>{t("page404.pageNotFound")}</p>
-      <p id="countdown" class="countdown-text">{t("page404.countdown", { n: 5 })}</p>
+      <p id="countdown" class="countdown-text" data-countdown-template={t("page404.countdown", { n: "{n}" })}>{t("page404.countdown", { n: 5 })}</p>
       <a href="/" class="home-btn" data-astro-prefetch>{t("page404.backHome")}</a>
     </div>
   </div>
 
-  <script define:vars={{ countdownText: t("page404.countdown", { n: "{n}" }) }} is:inline>
-    let timer;
-
-    function startCountdown() {
-      if (timer !== undefined) window.clearInterval(timer);
-      let seconds = 5;
-      const el = document.getElementById("countdown");
-      if (!el) return;
-
-      timer = window.setInterval(() => {
-        seconds--;
-        if (seconds <= 0) {
-          if (timer !== undefined) window.clearInterval(timer);
-          timer = undefined;
-          const home = document.querySelector(".home-btn");
-          home?.click();
-        } else {
-          el.textContent = countdownText.replace("{n}", String(seconds));
-        }
-      }, 1000);
-    }
-
-    function stopCountdown() {
-      if (timer !== undefined) window.clearInterval(timer);
-      timer = undefined;
-    }
-
-    document.addEventListener("astro:before-swap", stopCountdown);
-    document.addEventListener("astro:page-load", startCountdown);
-    startCountdown();
-  </script>
+  <script src="../scripts/countdown.ts"></script>
 </Stalux>
 
 <style>

package/src/pages/about.md.ts

@@ -10,6 +10,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = await renderAboutMd(site);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/archives.md.ts

@@ -19,6 +19,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = await renderArchivesMd(site, exportMd, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/categories/[category].md.ts

@@ -29,6 +29,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = renderTaxonomyPageMd(category, posts, site, "categories", exportMd);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/categories/index.md.ts

@@ -22,6 +22,9 @@ export const GET: APIRoute = async (context) => {
     const map = buildTaxonomyMap(posts, "categories");
     const text = renderTaxonomyListMd(map, site, "categories", t("ai.allCategories"));
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/index.md.ts

@@ -13,6 +13,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = await renderIndexMd(config, site, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/links.md.ts

@@ -13,6 +13,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = renderLinksMd(config, site, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/llms-full.txt.ts

@@ -20,6 +20,7 @@ export const GET: APIRoute = async (context) => {
     return new Response(text, {
         headers: {
             "Content-Type": "text/plain; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/llms.txt.ts

@@ -21,6 +21,7 @@ export const GET: APIRoute = async (context) => {
     return new Response(text, {
         headers: {
             "Content-Type": "text/plain; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/openapi.json.ts

@@ -0,0 +1,77 @@
+import type { APIRoute } from "astro";
+
+export const prerender = true;
+
+const responseSchema = {
+    type: "array",
+    items: { type: "object", additionalProperties: true },
+};
+
+export const GET: APIRoute = async ({ site }) => {
+    const server = site?.toString().replace(/\/$/, "") || "";
+    const document = {
+        openapi: "3.1.0",
+        info: {
+            title: "Stalux Blog Read API",
+            version: "1.0.0",
+            description:
+                "Read-only machine-readable endpoints for discovering and retrieving published Stalux blog content.",
+        },
+        servers: server ? [{ url: server }] : undefined,
+        paths: {
+            "/api/posts.json": {
+                get: {
+                    operationId: "listPublishedPosts",
+                    summary: "List published posts",
+                    description: "Returns metadata for every published post, newest first.",
+                    responses: {
+                        "200": {
+                            description: "Published post metadata",
+                            content: { "application/json": { schema: responseSchema } },
+                        },
+                    },
+                },
+            },
+            "/api/post.abbrlink.json": {
+                get: {
+                    operationId: "listPostIdentifiers",
+                    summary: "List post identifiers",
+                    description: "Returns the title and stable abbrlink for every published post.",
+                    responses: {
+                        "200": {
+                            description: "Published post identifiers",
+                            content: { "application/json": { schema: responseSchema } },
+                        },
+                    },
+                },
+            },
+            "/posts/{abbrlink}.md": {
+                get: {
+                    operationId: "readPostMarkdown",
+                    summary: "Read one post as Markdown",
+                    description: "Returns the normalized Markdown source for a published post.",
+                    parameters: [
+                        {
+                            name: "abbrlink",
+                            in: "path",
+                            required: true,
+                            description: "Stable post identifier returned by the post index.",
+                            schema: { type: "string" },
+                        },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Markdown post content",
+                            content: { "text/markdown": { schema: { type: "string" } } },
+                        },
+                        "404": { description: "Post not found" },
+                    },
+                },
+            },
+        },
+    };
+
+    return new Response(JSON.stringify(document, null, 2), {
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+};

package/src/pages/posts/[post].md.ts

@@ -98,6 +98,7 @@ export const GET: APIRoute = async ({ props }) => {
         status: 200,
         headers: {
             "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/tags/[tag].md.ts

@@ -29,6 +29,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = renderTaxonomyPageMd(tag, posts, site, "tags", exportMd);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/tags/index.md.ts

@@ -22,6 +22,9 @@ export const GET: APIRoute = async (context) => {
     const map = buildTaxonomyMap(posts, "tags");
     const text = renderTaxonomyListMd(map, site, "tags", t("ai.allTags"));
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/words.md.ts

@@ -9,6 +9,9 @@ export const GET: APIRoute = async () => {
 
     const text = await renderWordsMd();
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/scripts/clarity.ts

@@ -0,0 +1,26 @@
+declare global {
+    interface Window {
+        clarity?: ((...args: unknown[]) => void) & { q?: unknown[][] };
+        __staluxClarityLoaded?: boolean;
+    }
+}
+
+function load() {
+    const id = document.body?.dataset.staluxClarityId;
+    if (!id || document.getElementById("stalux-clarity-script")) return;
+    window.__staluxClarityLoaded = true;
+    window.clarity =
+        window.clarity ||
+        Object.assign((...args: unknown[]) => window.clarity?.q?.push(args), { q: [] });
+    const script = document.createElement("script");
+    script.id = "stalux-clarity-script";
+    script.async = true;
+    script.src = `https://www.clarity.ms/tag/${encodeURIComponent(id)}`;
+    document.head.appendChild(script);
+}
+
+document.addEventListener("astro:page-load", load);
+if (document.readyState === "loading")
+    document.addEventListener("DOMContentLoaded", load, { once: true });
+else load();
+export {};

package/src/scripts/countdown.ts

@@ -0,0 +1,27 @@
+let timer: number | undefined;
+
+function stop() {
+    if (timer !== undefined) window.clearInterval(timer);
+    timer = undefined;
+}
+
+function start() {
+    stop();
+    const el = document.getElementById("countdown");
+    const template = el?.dataset.countdownTemplate;
+    if (!el || !template) return;
+    let seconds = 5;
+    timer = window.setInterval(() => {
+        seconds -= 1;
+        if (seconds <= 0) {
+            stop();
+            document.querySelector<HTMLAnchorElement>(".home-btn")?.click();
+        } else {
+            el.textContent = template.replace("{n}", String(seconds));
+        }
+    }, 1000);
+}
+
+document.addEventListener("astro:before-swap", stop);
+document.addEventListener("astro:page-load", start);
+start();

package/src/scripts/google-analytics.ts

@@ -0,0 +1,47 @@
+declare global {
+    interface Window {
+        dataLayer?: unknown[];
+        gtag?: (...args: unknown[]) => void;
+        __staluxAnalyticsLoaded?: boolean;
+        __staluxAnalyticsPageLoadListener?: boolean;
+    }
+}
+
+function load() {
+    const gaID = document.body?.dataset.staluxGaId;
+    if (!gaID) return;
+    const hasScript = document.querySelector('script[data-stalux-google="true"]');
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = window.gtag || ((...args: unknown[]) => window.dataLayer?.push(args));
+    if (!hasScript) {
+        const script = document.createElement("script");
+        script.async = true;
+        script.dataset.staluxGoogle = "true";
+        script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(gaID)}`;
+        document.head.appendChild(script);
+    }
+    if (!window.__staluxAnalyticsLoaded) {
+        window.__staluxAnalyticsLoaded = true;
+        window.gtag("js", new Date());
+        window.gtag("config", gaID);
+    }
+}
+
+if (!window.__staluxAnalyticsPageLoadListener) {
+    window.__staluxAnalyticsPageLoadListener = true;
+    let firstPageLoad = true;
+    document.addEventListener("astro:page-load", () => {
+        load();
+        if (firstPageLoad) {
+            firstPageLoad = false;
+            return;
+        }
+        window.gtag?.("event", "page_view", { page_path: window.location.pathname });
+    });
+}
+
+if (document.readyState === "loading")
+    document.addEventListener("DOMContentLoaded", load, { once: true });
+else load();
+
+export {};

package/src/scripts/random-posts.ts

@@ -0,0 +1,58 @@
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function shuffle<T>(items: T[]): T[] {
+    const result = [...items];
+    for (let i = result.length - 1; i > 0; i -= 1) {
+        const bytes = new Uint32Array(1);
+        const j = globalThis.crypto?.getRandomValues
+            ? (crypto.getRandomValues(bytes)[0] ?? 0) % (i + 1)
+            : Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}
+
+async function fetchPosts() {
+    const response = await fetch("/api/post.abbrlink.json");
+    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+    return (await response.json()) as { abbrlink: string; title: string }[];
+}
+
+function render(posts: { abbrlink: string; title: string }[]) {
+    return posts
+        .map(
+            (post) =>
+                `<li class="random-post-item"><a href="/posts/${post.abbrlink}/" class="random-post-link a-none">${post.title}</a></li>`,
+        )
+        .join("");
+}
+
+async function refresh(container: HTMLElement, fallback: string) {
+    const list = container.querySelector<HTMLElement>("#random-posts-list");
+    if (!list) return;
+    list.style.opacity = "0.5";
+    await sleep(300);
+    try {
+        const posts = shuffle(await fetchPosts()).slice(0, Number(container.dataset.count ?? 5));
+        list.innerHTML = posts.length
+            ? render(posts)
+            : `<li class="no-posts">${container.dataset.noPosts ?? fallback}</li>`;
+    } catch {
+        list.innerHTML = `<li class="error">${container.dataset.loadFailed ?? fallback}</li>`;
+    } finally {
+        list.style.opacity = "1";
+    }
+}
+
+document.addEventListener("astro:page-load", () => {
+    const container = document.querySelector<HTMLElement>("[data-stalux-random-posts]");
+    if (!container || container.dataset.staluxBound === "true") return;
+    container.dataset.staluxBound = "true";
+    container.querySelector("#refresh-random-posts")?.addEventListener("click", async (event) => {
+        event.preventDefault();
+        await refresh(container, container.dataset.loadError ?? "Failed to load posts");
+    });
+    void refresh(container, container.dataset.loadError ?? "Failed to load posts");
+});
+
+export {};

package/src/scripts/runtime-counter.ts

@@ -0,0 +1,32 @@
+declare global {
+    interface Window {
+        __staluxRuntimeTimer?: ReturnType<typeof setInterval>;
+    }
+}
+
+function update() {
+    const container = document.querySelector<HTMLElement>("[data-stalux-buildtime]");
+    const counter = document.getElementById("runtime-counter");
+    if (!container || !counter) return;
+    const start = new Date(container.dataset.staluxBuildtime ?? "");
+    const diffMs = Date.now() - start.getTime();
+    if (Number.isNaN(diffMs) || diffMs < 0) return;
+    const total = Math.floor(diffMs / 1000);
+    const format =
+        container.dataset.staluxRuntimeFormat ?? "{days}d {hours}h {minutes}m {seconds}s";
+    counter.textContent = format
+        .replace("{days}", String(Math.floor(total / 86400)))
+        .replace("{hours}", String(Math.floor((total % 86400) / 3600)))
+        .replace("{minutes}", String(Math.floor((total % 3600) / 60)))
+        .replace("{seconds}", String(total % 60));
+}
+
+function start() {
+    if (window.__staluxRuntimeTimer) clearInterval(window.__staluxRuntimeTimer);
+    update();
+    window.__staluxRuntimeTimer = setInterval(update, 1000);
+}
+
+document.addEventListener("astro:page-load", start);
+start();
+export {};

package/src/scripts/vercount.ts

@@ -0,0 +1,21 @@
+declare global {
+    interface Window {
+        __staluxVerCountLoaded?: boolean;
+    }
+}
+
+function load() {
+    if (document.querySelector("script[data-stalux-vercount]")) return;
+    window.__staluxVerCountLoaded = true;
+    const script = document.createElement("script");
+    script.defer = true;
+    script.dataset.staluxVercount = "true";
+    script.src = "https://events.vercount.one/js";
+    document.head.appendChild(script);
+}
+
+document.addEventListener("astro:page-load", load);
+if (document.readyState === "loading")
+    document.addEventListener("DOMContentLoaded", load, { once: true });
+else load();
+export {};

package/src/scripts/webmcp.ts

@@ -56,9 +56,11 @@ interface DocumentWithModelContext extends Document {
 // 语言选择（跟随站点 site.yml 的 lang）
 // ---------------------------------------------------------------------------
 
-const SITE_LANG = (
-    typeof window !== "undefined" ? (window.__STALUX_SITE_INFO__?.lang ?? "zh-CN") : "zh-CN"
-).toLowerCase();
+const SITE_LANG =
+    (typeof document !== "undefined"
+        ? document.body?.dataset.staluxSiteLang
+        : "zh-CN"
+    )?.toLowerCase() ?? "zh-cn";
 
 /** 站点为英文站时为 true */
 const IS_EN = SITE_LANG === "en" || SITE_LANG === "en-us" || SITE_LANG === "en-gb";
@@ -492,7 +494,13 @@ function siteInfoTool(): WebMCPTool {
         annotations: { readOnlyHint: true, untrustedContentHint: false },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
         execute: async () => {
-            const info = window.__STALUX_SITE_INFO__ ?? {};
+            const body = document.body;
+            const info = window.__STALUX_SITE_INFO__ ?? {
+                title: body?.dataset.staluxSiteTitle,
+                url: body?.dataset.staluxSiteUrl,
+                description: body?.dataset.staluxSiteDescription,
+                lang: body?.dataset.staluxSiteLang,
+            };
             return {
                 ok: true,
                 title: info.title ?? "",

package/src/utils/ai-discovery.ts

@@ -468,6 +468,38 @@ export async function renderLlmsTxt(config: ConfigMap, site: string): Promise<st
     lines.push(buildMdLink("llms-full.txt", `${site}/llms-full.txt`, t("ai.llmsFullTxtDesc")));
     lines.push("");
 
+    // Developer resources and agent guidance. Keep these links predictable so an
+    // agent can discover the read API without scraping the HTML application shell.
+    lines.push("## Developer resources");
+    lines.push(
+        buildMdLink(
+            "OpenAPI specification",
+            `${site}/openapi.json`,
+            "Machine-readable description of the read-only blog API.",
+        ),
+    );
+    lines.push(
+        buildMdLink(
+            "Published post index",
+            `${site}/api/posts.json`,
+            "JSON metadata for published posts, including stable abbrlink identifiers.",
+        ),
+    );
+    lines.push(
+        buildMdLink(
+            "Post identifier index",
+            `${site}/api/post.abbrlink.json`,
+            "JSON mapping of published post titles to stable identifiers.",
+        ),
+    );
+    lines.push("");
+
+    lines.push("## When to use this site");
+    lines.push(
+        "Use the read API or Markdown endpoints when you need to search, cite, summarize, or retrieve the author's published technical articles. Start with `/openapi.json` or `/api/posts.json`, then fetch a specific `/posts/{abbrlink}.md` resource. The endpoints are read-only and do not require authentication.",
+    );
+    lines.push("");
+
     // Optional
     lines.push(`## ${t("ai.optional")}`);
     lines.push(buildMdLink(t("ai.rss"), `${site}/rss.xml`));