@xingwangzhe/stalux 1.25.15 → 1.26.1

package/README.md

@@ -226,3 +226,32 @@ jobTitle: Software Engineer # Optional; emitted as JSON-LD Person.jobTitle
 ```
 
 This is a build-time metadata field. It does not create a contact endpoint or expose private information; only publish a role that is already intended to be public.
+
+
+## Development diagnostics
+
+Stalux routes integration, content-loader and rendering diagnostics through Astro's official logger. Normal mode keeps summaries, warnings and errors. Verbose mode adds configuration/routes, component overrides, font cache, Markdown analysis/cache, content statistics, feeds, asset sync and Pagefind stages.
+
+```bash title="Stalux diagnostics"
+bun run dev:debug
+bun run build:debug
+# In a consuming project:
+STALUX_DEBUG=1 bun run dev --verbose
+STALUX_DEBUG=1 bun run build --verbose
+# Silence Astro; standalone verification output remains separate:
+bun run astro -- build --silent
+```
+
+| Surface | Behavior |
+| --- | --- |
+| Terminal | Integration loggers use `fork("stalux/module")`; rendering uses `Astro.logger`, with explicit context propagation to utilities and loaders. Astro levels, custom destinations and `--silent` remain authoritative. |
+| Browser console | A separate lightweight logger uses `[stalux/module]` prefixes. Detail requires development mode plus `STALUX_DEBUG=1` or `--verbose`; enable Verbose messages in DevTools. Production only emits warnings and errors. |
+| Content diagnostics | `getStaticPaths()` has no runtime logger; pure computation errors are reported by callers or Astro. Math failures use Sätteri diagnostics without duplicate error reporting. |
+
+Browser diagnostics cover mount/disposal, navigation, search, PhotoSwipe, Waline, WebMCP, backgrounds and external analytics script loading. Logs stay local: no reporting endpoint or telemetry is added. Search terms, article bodies, complete configuration and credentials are not intentionally logged. Errors retain module, cause and stack; common credentials and URL query parameters are redacted, but review third-party error text before sharing.
+
+In Astro 7.3, integration `logger.debug()` uses the official `DEBUG/--verbose` channel, separate from custom JSON destinations. `info/warn/error` and rendering diagnostics use the configured destination. Do not enable `--verbose` or `DEBUG` when requesting a silent run.
+
+Timing is emitted only as logs, never included in generated pages or cache keys. Switching between normal and verbose builds may require one rebuild; repeated builds in the same mode remain deterministic. Consumers running `astro dev --background` can read terminal output with `astro dev logs`.
+
+Keep the TypeScript 6 alias for `astro check`, upgrade Vitest and its coverage provider together, and run `bun run validate` before releasing.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.25.15",
+    "version": "1.26.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -82,14 +82,16 @@
         "knip": "knip",
         "verify:build": "bun scripts/verify-build.mjs",
         "validate": "bun run check && bun run astro:check && bun run knip && bun run test:coverage && bun run build",
-        "prepare": "git config core.hooksPath scripts/git-hooks"
+        "prepare": "git config core.hooksPath scripts/git-hooks",
+        "dev:debug": "STALUX_DEBUG=1 astro dev --verbose",
+        "build:debug": "STALUX_DEBUG=1 astro build --verbose && bun run verify:build"
     },
     "dependencies": {
-        "@astrojs/markdown-satteri": "0.4.0",
+        "@astrojs/markdown-satteri": "0.4.1",
         "@astrojs/rss": "^4.0.19",
         "@astrojs/sitemap": "^3.7.4",
         "@expressive-code/plugin-line-numbers": "^0.44.2",
-        "@lucide/astro": "^1.38.0",
+        "@lucide/astro": "^1.42.0",
         "@mcp-b/webmcp-polyfill": "^5.1.0",
         "@pagefind/component-ui": "^1.5.2",
         "@waline/client": "^3.15.2",
@@ -103,21 +105,21 @@
         "pagefind": "^1.5.2",
         "photoswipe": "^5.4.4",
         "satteri": "^0.10.5",
-        "simple-icons": "^16.29.0",
+        "simple-icons": "^16.30.0",
         "subset-font": "^2.7.0",
         "temml": "^0.13.5"
     },
     "devDependencies": {
         "@astrojs/check": "0.9.10",
-        "@biomejs/biome": "2.5.11",
-        "@vitest/coverage-v8": "4.1.11",
-        "astro": "^7.2.10",
-        "knip": "^6.34.0",
+        "@biomejs/biome": "2.5.12",
+        "@vitest/coverage-v8": "5.0.0",
+        "astro": "^7.3.2",
+        "knip": "^6.35.1",
         "typescript": "npm:@typescript/typescript6@6.0.2",
         "vite": "8.2.2",
-        "vitest": "4.1.11"
+        "vitest": "5.0.0"
     },
     "peerDependencies": {
-        "astro": "7.2.10"
+        "astro": "7.3.2"
     }
 }

package/src/components/stalux/categories/categoriesList.astro

@@ -3,7 +3,7 @@ import CategoriesCard from "@components/stalux/categories/categoriesCard.astro";
 import styles from "@styles/components/categories/categoriesList.module.css";
 import { getCategoryCountList } from "@utils/collections-stats";
 
-const categoryList = await getCategoryCountList();
+const categoryList = await getCategoryCountList(Astro.logger);
 ---
 
 <ul class={`${styles.categoriesList} stagger-children`}>

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

@@ -15,7 +15,7 @@ const siteConfig = getSiteData(configEntries);
 const { t } = createTranslator(siteConfig.lang || "zh-CN");
 
 function badgeImg(opts: BadgeOptions) {
-    const src = svgToDataUrl(generateBadge(opts));
+    const src = svgToDataUrl(generateBadge(opts, Astro.logger));
     const alt = opts.alt || `${opts.label}: ${opts.message}`;
     if (opts.href) {
         return `<a href="${opts.href}" target="_blank" rel="${opts.rel ?? "noopener"}"><img src="${src}" alt="${alt}" class="badge" /></a>`;

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

@@ -46,7 +46,7 @@ const badges: BadgeItem[] | undefined = footerConfig?.badges?.map((item) => {
     };
 });
 
-const totalWordCount = await getTotalWordCount();
+const totalWordCount = await getTotalWordCount(Astro.logger);
 const formattedWordCount = formatWordCount(totalWordCount, siteConfig.lang || "zh-CN");
 ---
 

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

@@ -6,8 +6,8 @@ import { getNavsData, getSiteData } from "@utils/config-utils";
 import { createTranslator } from "@utils/i18n";
 import { getLucideIcon } from "@utils/lucide-icons";
 
-const MenuIcon = getLucideIcon("menu");
-const SearchIcon = getLucideIcon("search");
+const MenuIcon = getLucideIcon("menu", Astro.logger);
+const SearchIcon = getLucideIcon("search", Astro.logger);
 const configEntries = await getCollection("config");
 const siteConfig = getSiteData(configEntries);
 const navsConfig = getNavsData(configEntries);
@@ -45,7 +45,7 @@ const navs = navsConfig?.items ?? [];
 
         <ul data-ref="stalux-nav-list" class={styles.navList}>
             {navs.map((item) => {
-                    const NavIcon = item.icon ? getLucideIcon(item.icon) : null;
+                    const NavIcon = item.icon ? getLucideIcon(item.icon, Astro.logger) : null;
                     return (
                         <li class={styles.navItem}>
                             <a

package/src/components/stalux/tags/tagsCloud.astro

@@ -8,7 +8,7 @@ import { createTranslator } from "@utils/i18n";
 const configEntries = await getCollection("config");
 const siteConfig = getSiteData(configEntries);
 const { t } = createTranslator(siteConfig.lang || "zh-CN");
-const tagList = await getTagCountList();
+const tagList = await getTagCountList(Astro.logger);
 const tagLinks = tagList.map((t) => ({
     type: "link" as const,
     text: t.name,

package/src/index.ts

@@ -20,7 +20,6 @@ import { fontProviders } from "astro/config";
 // pagefind 是 ESM-only 包，需要在模块顶层导入
 // 因为 astro:build:done 钩子中 Vite module runner 已关闭，无法动态 import
 import { createIndex as pagefindCreateIndex } from "pagefind";
-
 import type { StaluxOptions } from "./config";
 import { expressiveCode } from "./expressive-code";
 import { staluxComponentsAlias } from "./internal/components-plugin";
@@ -35,6 +34,7 @@ import {
 import { createViteAliases } from "./internal/vite-aliases";
 import { featureFlagsHast, featureFlagsMdast } from "./plugins/feature-flags";
 import { temml } from "./plugins/satteri-temml";
+import { describeError } from "./utils/diagnostics";
 
 // 字体配置（Astro Fonts API）通过 updateConfig 注入，两种模式（源码模板/npm 插件）都生效。
 // 官方 local provider 完全本地读文件（readFile），不联网；
@@ -162,6 +162,13 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 config,
                 logger,
             }) => {
+                const started = performance.now();
+                const configLogger = logger.fork("stalux/config");
+                const assetsLogger = logger.fork("stalux/assets");
+                const routesLogger = logger.fork("stalux/routes");
+                const markdownLogger = logger.fork("stalux/markdown");
+                const fontsLogger = logger.fork("stalux/fonts");
+                configLogger.debug(`setup started; mode=${isPluginMode ? "plugin" : "source"}`);
                 const srcDir = fileURLToPath(new URL(".", import.meta.url));
                 const runtimeCacheKey = createRuntimeCacheKey(
                     path.join(srcDir, "scripts"),
@@ -174,8 +181,14 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                         resolve: {
                             alias: createViteAliases(srcDir),
                         },
-                        plugins: [staluxComponentsAlias(opt.components)],
+                        plugins: [
+                            staluxComponentsAlias(opt.components, logger.fork("stalux/components")),
+                        ],
                         define: {
+                            __STALUX_DEBUG__: JSON.stringify(
+                                process.env.STALUX_DEBUG === "1" ||
+                                    process.argv.includes("--verbose"),
+                            ),
                             __VUE_OPTIONS_API__: true,
                             __VUE_PROD_DEVTOOLS__: false,
                             __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: false,
@@ -196,12 +209,12 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 try {
                     const { copied, skipped } = syncBackgroundSvgs(srcDir);
                     if (copied > 0) {
-                        logger.info(`Stalux: 同步背景 SVG ${copied} 个（跳过 ${skipped} 个不变）`);
+                        assetsLogger.info(`同步背景 SVG ${copied} 个（跳过 ${skipped} 个不变）`);
                     } else if (skipped > 0) {
-                        logger.debug(`Stalux: 背景 SVG 无变化（跳过 ${skipped} 个）`);
+                        assetsLogger.debug(`背景 SVG 无变化（跳过 ${skipped} 个）`);
                     }
                 } catch (error) {
-                    logger.warn(`Stalux: 同步背景 SVG 失败: ${String(error)}`);
+                    assetsLogger.warn(`同步背景 SVG 失败: ${describeError(error)}`);
                 }
 
                 // 3. 注入所有页面路由（仅插件模式，源码模式下使用文件路由）
@@ -210,9 +223,10 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     for (const route of routes) {
                         injectRoute(route);
                     }
-                    logger.debug(`Stalux: injected ${routes.length} routes`);
+                    routesLogger.debug(`injected ${routes.length} routes`);
+                    for (const route of routes) routesLogger.debug(`route=${route.pattern}`);
                 } else {
-                    logger.info("Stalux: running in source mode, file-based routing active");
+                    routesLogger.debug("source mode; file-based routing active");
                 }
 
                 // 4. 可选：添加 Dev Toolbar 应用
@@ -227,7 +241,9 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     });
                 }
 
-                logger.info(`Stalux initialized (contentDir: ${opt.contentDir})`);
+                configLogger.debug(
+                    `contentDir=${opt.contentDir}; toolbar=${opt.devToolbar}; pagefind=${opt.pagefind}`,
+                );
 
                 // 5. 注入 satteri 插件（Mermaid/字数统计/特性标记/数学公式/PhotoSwipe），按插件 name 去重
                 // 两种模式都由集成补齐默认插件。Astro 7 的 markdown.processor 默认为 satteri()，
@@ -241,7 +257,11 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     if (processorOptions) {
                         const seen = collectPluginNames(processorOptions);
                         appendUniquePlugin(processorOptions.mdastPlugins, mermaidMdast(), seen);
-                        appendUniquePlugin(processorOptions.mdastPlugins, temml(), seen);
+                        appendUniquePlugin(
+                            processorOptions.mdastPlugins,
+                            temml(undefined, markdownLogger),
+                            seen,
+                        );
                         appendUniquePlugin(processorOptions.mdastPlugins, featureFlagsMdast, seen);
                         appendUniquePlugin(
                             processorOptions.hastPlugins,
@@ -254,17 +274,17 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                         );
                         appendUniquePlugin(processorOptions.hastPlugins, photoswipe(), seen);
                         appendUniquePlugin(processorOptions.hastPlugins, featureFlagsHast, seen);
-                        logger.debug(
-                            "Stalux: injected satteri plugins (mermaid/temml/photoswipe/feature-flags)",
+                        markdownLogger.debug(
+                            "injected satteri plugins (mermaid/temml/photoswipe/feature-flags)",
                         );
                     } else {
-                        logger.warn(
-                            "Stalux: markdown.processor 不是 satteri，无法注入字数统计/数学公式/PhotoSwipe 插件。" +
+                        markdownLogger.warn(
+                            "markdown.processor 不是 satteri，无法注入字数统计/数学公式/PhotoSwipe 插件。" +
                                 "请在 astro.config 中配置 `processor: satteri({...})`。",
                         );
                     }
                 } catch (error) {
-                    logger.warn(`Stalux: 注入 markdown 插件失败: ${String(error)}`);
+                    markdownLogger.warn(`注入 markdown 插件失败: ${describeError(error)}`);
                 }
 
                 // 6. 站点 URL 单源化：以 stalux/config/site.yml 的 url 为准
@@ -302,14 +322,18 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             );
                         }
                     }
-                } catch {
-                    logger.debug("Stalux: site.yml not found, skip site sync");
+                } catch (error) {
+                    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                        configLogger.debug("site.yml not found; site sync skipped");
+                    } else {
+                        configLogger.warn(`site sync failed: ${describeError(error)}`);
+                    }
                 }
 
                 // 7. 字体：构建期把正文切成 unicode-range 分片，通过官方 Fonts API 注入
                 // （config:setup 阶段执行，保证 dev/build 都能生成；local provider 纯本地读文件）
                 try {
-                    const sliced = await runFontSlicing(process.cwd(), logger);
+                    const sliced = await runFontSlicing(process.cwd(), fontsLogger);
                     if (sliced) {
                         updateConfig({
                             fonts: buildFontsConfig(
@@ -318,16 +342,19 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                                 sliced.codeItalic,
                             ),
                         });
-                        logger.info(
-                            `Stalux: injected ${sliced.body.length} body font chunks + code font via Fonts API`,
+                        fontsLogger.debug(
+                            `injected ${sliced.body.length} body font chunks + code font via Fonts API`,
                         );
                     }
                 } catch (error) {
-                    logger.warn(`Stalux: font injection failed: ${String(error)}`);
+                    fontsLogger.warn(`font injection failed: ${describeError(error)}`);
                 }
+                configLogger.info(`initialized in ${(performance.now() - started).toFixed(1)}ms`);
             },
 
-            "astro:build:done": async ({ dir, logger }) => {
+            "astro:build:done": async ({ dir, logger: rootLogger }) => {
+                const logger = rootLogger.fork("stalux/pagefind");
+                const started = performance.now();
                 const outDir = fileURLToPath(dir);
 
                 // 后处理：Pagefind 搜索索引。启用时任何失败都必须让构建失败，
@@ -353,11 +380,15 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             outputPath: path.join(outDir, "pagefind"),
                         });
 
-                        logger.info(`Pagefind indexed ${page_count} pages → ${outputPath}`);
+                        logger.info(
+                            `indexed ${page_count} pages → ${outputPath} (${(performance.now() - started).toFixed(1)}ms)`,
+                        );
                     } catch (error) {
-                        logger.error(`Pagefind indexing failed: ${String(error)}`);
+                        logger.error(`Pagefind indexing failed: ${describeError(error)}`);
                         throw error;
                     }
+                } else {
+                    logger.debug("disabled; indexing skipped");
                 }
             },
         },

package/src/internal/components-plugin.ts

@@ -18,6 +18,7 @@
 
 import { fileURLToPath } from "node:url";
 
+import type { AstroIntegrationLogger } from "astro";
 import type { Plugin } from "vite";
 
 import type { ComponentOverrideMap } from "../config";
@@ -28,7 +29,10 @@ const VIRTUAL_PREFIX = "@stalux/component/";
 /**
  * 创建 Vite 别名插件，处理 `@stalux/component/*` → 实际组件路径
  */
-export function staluxComponentsAlias(overrides: ComponentOverrideMap = {}): Plugin {
+export function staluxComponentsAlias(
+    overrides: ComponentOverrideMap = {},
+    logger?: AstroIntegrationLogger,
+): Plugin {
     // 包内 components 目录的绝对路径
     const componentsDir = fileURLToPath(new URL("../components", import.meta.url));
 
@@ -42,6 +46,8 @@ export function staluxComponentsAlias(overrides: ComponentOverrideMap = {}): Plu
             // 使用 resolveComponentPath 获取实际路径
             const resolvedPath = resolveComponentPath(componentName, overrides, componentsDir);
 
+            logger?.debug(`${componentName}: ${overrides[componentName] ? "override" : "default"}`);
+
             // 如果是用户提供的相对路径，相对于项目根解析
             if (overrides[componentName]) {
                 return this.resolve(resolvedPath, importer, { skipSelf: true });

package/src/internal/font-slices.ts

@@ -1,3 +1,4 @@
+import { describeError } from "../utils/diagnostics";
 /**
  * Build-time CJK font slicing engine (Astro Fonts API variant).
  *
@@ -148,6 +149,10 @@ export async function runFontSlicing(
     projectRoot: string,
     logger: AstroIntegrationLogger,
 ): Promise<SlicedFonts | null> {
+    const started = performance.now();
+    let cached = 0;
+    let generated = 0;
+    logger.debug("locating font inputs");
     // 1. Locate fonts (check project root first, then stalux package dir)
     const fontPath = findFont(projectRoot, FONT_INPUT);
     if (!fontPath) {
@@ -177,17 +182,21 @@ export async function runFontSlicing(
         const filename = `lxgw-wenkai-slice-${def.id}-${hash}.woff2`;
         const outPath = join(outDir, filename);
 
-        if (!existsSync(outPath)) {
+        if (existsSync(outPath)) {
+            cached++;
+            logger.debug(`body slice ${def.id}: cache hit`);
+        } else {
             try {
                 const data = await subsetFont(fontBuffer, chars, { targetFormat: "woff2" });
                 if (data.length > 0) {
                     writeFileSync(outPath, data);
+                    generated++;
                     logger.debug(
                         `  body slice ${def.id}: ${(data.length / 1024).toFixed(1)} KB → ${filename}`,
                     );
                 }
             } catch (error) {
-                logger.warn(`  body slice ${def.id} failed: ${String(error)}`);
+                logger.warn(`  body slice ${def.id} failed: ${describeError(error)}`);
             }
         }
 
@@ -201,6 +210,9 @@ export async function runFontSlicing(
         return null;
     }
 
+    logger.debug(
+        `generated=${generated}; cached=${cached}; elapsed=${(performance.now() - started).toFixed(1)}ms`,
+    );
     logger.info(
         `Font slicing done: ${body.length} body chunks + code font ` +
             `(source ${(fontBuffer.length / 1024 / 1024).toFixed(1)} MB → woff2 chunks)`,

package/src/pages/api/posts.json.ts

@@ -10,7 +10,7 @@ export const prerender = true;
  * 相比 /api/post.abbrlink.json，包含完整元信息（日期/分类/标签/摘要/字数），
  * 是 stalux_get_post / stalux_random_post 等 WebMCP 工具的廉价数据源。
  */
-export const GET: APIRoute = async () => {
+export const GET: APIRoute = async ({ logger }) => {
     const posts = await getCollection("posts", ({ data }) => !data.draft);
 
     const payload = await Promise.all(
@@ -22,7 +22,7 @@ export const GET: APIRoute = async () => {
             tags: post.data.tags ?? [],
             categories: post.data.categories ?? [],
             desc: post.data.desc ?? "",
-            wordCount: (await analyzeFeatureFlags(post.body)).wordCount,
+            wordCount: (await analyzeFeatureFlags(post.body, logger)).wordCount,
             url: `/posts/${post.data.abbrlink}/`,
         })),
     );

package/src/pages/archives.md.ts

@@ -17,7 +17,7 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const lang = (config.get("site")?.lang as string) || "zh-CN";
     const { t } = createTranslator(lang);
-    const text = await renderArchivesMd(site, exportMd, t);
+    const text = await renderArchivesMd(site, exportMd, t, context.logger);
     return new Response(text, {
         headers: {
             "Content-Type": "text/markdown; charset=utf-8",

package/src/pages/atom.xml.ts

@@ -5,12 +5,12 @@ import { buildFeedItems } from "@utils/feed";
 import { createTranslator, langToFeedLanguage } from "@utils/i18n";
 import type { APIRoute } from "astro";
 
-export const GET: APIRoute = async () => {
+export const GET: APIRoute = async ({ logger }) => {
     const configCollection = await getCollection("config");
     const stalux = getSiteData(configCollection);
 
     const posts = await getCollection("posts", ({ data }) => !data.draft);
-    const items = await buildFeedItems(stalux, posts, "updated");
+    const items = await buildFeedItems(stalux, posts, "updated", logger);
 
     const lang = stalux?.lang || "zh-CN";
     const { t } = createTranslator(lang);

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

@@ -18,7 +18,7 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const lang = (config.get("site")?.lang as string) || "zh-CN";
     const { t } = createTranslator(lang);
-    const posts = await getPublishedPosts();
+    const posts = await getPublishedPosts(context.logger);
     const map = buildTaxonomyMap(posts, "categories");
     const text = renderTaxonomyListMd(map, site, "categories", t("ai.allCategories"));
     return new Response(text, {

package/src/pages/index.md.ts

@@ -11,7 +11,7 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const lang = (config.get("site")?.lang as string) || "zh-CN";
     const { t } = createTranslator(lang);
-    const text = await renderIndexMd(config, site, t);
+    const text = await renderIndexMd(config, site, t, context.logger);
     return new Response(text, {
         headers: {
             "Content-Type": "text/markdown; charset=utf-8",

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

@@ -15,7 +15,7 @@ export const GET: APIRoute = async (context) => {
     }
     const config = await loadConfig();
     const site = getSite(config, context.site?.toString());
-    const text = await renderLlmsFullTxt(config, site);
+    const text = await renderLlmsFullTxt(config, site, context.logger);
 
     return new Response(text, {
         headers: {

package/src/pages/llms.txt.ts

@@ -15,7 +15,7 @@ export const GET: APIRoute = async (context) => {
     }
     const config = await loadConfig();
     const site = getSite(config, context.site?.toString());
-    const text = await renderLlmsTxt(config, site);
+    const text = await renderLlmsTxt(config, site, context.logger);
 
     return new Response(text, {
         headers: {

package/src/pages/posts/[post].astro

@@ -20,7 +20,7 @@ const props = Astro.props as Props;
 const { Content, headings } = await render(props.post);
 
 // 文章统计完全由 Sätteri AST 分析，不读取 render metadata。
-const flags = await analyzeFeatureFlags(props.post.body);
+const flags = await analyzeFeatureFlags(props.post.body, Astro.logger);
 const autoDesc = props.post.data.desc || "";
 
 export async function getStaticPaths() {

package/src/pages/rss.xml.ts

@@ -5,12 +5,12 @@ import { buildFeedItems } from "@utils/feed";
 import { createTranslator, langToFeedLanguage } from "@utils/i18n";
 import type { APIRoute } from "astro";
 
-export const GET: APIRoute = async () => {
+export const GET: APIRoute = async ({ logger }) => {
     const configCollection = await getCollection("config");
     const stalux = getSiteData(configCollection);
 
     const posts = await getCollection("posts", ({ data }) => !data.draft);
-    const items = await buildFeedItems(stalux, posts, "atom:updated");
+    const items = await buildFeedItems(stalux, posts, "atom:updated", logger);
 
     const lang = stalux?.lang || "zh-CN";
     const { t } = createTranslator(lang);

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

@@ -18,7 +18,7 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const lang = (config.get("site")?.lang as string) || "zh-CN";
     const { t } = createTranslator(lang);
-    const posts = await getPublishedPosts();
+    const posts = await getPublishedPosts(context.logger);
     const map = buildTaxonomyMap(posts, "tags");
     const text = renderTaxonomyListMd(map, site, "tags", t("ai.allTags"));
     return new Response(text, {

package/src/plugins/feature-flags.ts

@@ -1,4 +1,5 @@
 import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
+import type { AstroRuntimeLogger } from "astro";
 import type { HastVisitorContext, MdastNode, MdastVisitorContext } from "satteri";
 /**
  * Sätteri 插件：在构建时完成字数统计和特性标记，
@@ -15,6 +16,7 @@ import type { HastVisitorContext, MdastNode, MdastVisitorContext } from "satteri
  * - 数学公式由 satteri-temml 插件直接输出 MathML，无需额外标记
  */
 import { defineHastPlugin, defineMdastPlugin } from "satteri";
+import { logDetail } from "../utils/diagnostics";
 
 declare module "satteri" {
     interface DataMap {
@@ -254,10 +256,17 @@ function getFeatureFlagsProcessor() {
  * 直接用 Sätteri AST 分析一篇文章，供文章页、全局统计和 API 复用。
  * 这里不复用内容集合的 data，也不读取 Astro 的渲染 metadata。
  */
-export function analyzeFeatureFlags(body: string | undefined): Promise<FeatureFlagsResult> {
+export function analyzeFeatureFlags(
+    body: string | undefined,
+    logger?: AstroRuntimeLogger,
+): Promise<FeatureFlagsResult> {
     const content = body ?? "";
     const cached = analysisCache.get(content);
-    if (cached) return cached;
+    if (cached) {
+        logDetail(logger, "markdown-analysis", "cache hit");
+        return cached;
+    }
+    logDetail(logger, "markdown-analysis", "cache miss; analyzing feature flags");
 
     const resultPromise = analyzeFeatureFlagsUncached(content);
     analysisCache.set(content, resultPromise);

package/src/plugins/satteri-temml.ts

@@ -7,6 +7,8 @@
  *
  * 输出纯 MathML，浏览器原生渲染，无需额外的 CSS/字体。
  */
+import type { AstroIntegrationLogger } from "astro";
+
 import { defineMdastPlugin, type MdastNode, type MdastVisitorContext } from "satteri";
 import temmlLib, { type Options as TemmlOptions } from "temml";
 
@@ -34,6 +36,7 @@ function renderMath(
     displayMode: boolean,
     options: TemmlOptions,
     ctx: MdastVisitorContext,
+    logger?: AstroIntegrationLogger,
 ): string {
     const value = node.value;
     try {
@@ -43,6 +46,9 @@ function renderMath(
             throwOnError: true,
         });
     } catch (error) {
+        logger?.debug(
+            "Temml render failed; reporting diagnostic through Markdown processor and trying tolerant rendering",
+        );
         const cause = error instanceof Error ? error : new Error(String(error));
         ctx.report({
             message: `Could not render math with Temml: ${cause.message}`,
@@ -57,6 +63,7 @@ function renderMath(
                 throwOnError: false,
             });
         } catch {
+            logger?.debug("Temml tolerant rendering failed; using error markup");
             return renderTemmlError(value, error, options);
         }
     }
@@ -66,17 +73,17 @@ function renderMath(
  * 创建一个 Sätteri temml mdast 插件。
  * @param options - 透传给 temml.renderToString 的选项（displayMode 除外）
  */
-export function temml(options?: TemmlOptions) {
+export function temml(options?: TemmlOptions, logger?: AstroIntegrationLogger) {
     const settings = options ?? emptyOptions;
     return defineMdastPlugin({
         name: "temml",
         math(node, ctx) {
-            return { rawHtml: renderMath(node, true, settings, ctx) };
+            return { rawHtml: renderMath(node, true, settings, ctx, logger) };
         },
         inlineMath(node, ctx) {
             return {
                 type: "html",
-                value: renderMath(node, false, settings, ctx),
+                value: renderMath(node, false, settings, ctx, logger),
             };
         },
     });