@windcoder/astro-theme-orchid 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@windcoder/astro-theme-orchid",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "清新简约的 Astro 博客主题，以 Integration 形式提供，支持版本化升级与组件覆盖",
 	"type": "module",
 	"keywords": [

package/src/components/PostCard.astro

@@ -30,6 +30,11 @@ const { cover: rawCover, retries } = resolveCover(
    下）构建期解析为产物 URL，public / 外链原样直通 */
 const resolvedCover = rawCover ? await resolveSiteImage(rawCover) : rawCover;
 const cover = config.postList.showCover ? resolvedCover : null;
+/* §4.114：普通封面图失效的客户端兜底（api 文章 retries 末尾已含 fallbackCover，无需重复） */
+const coverFallback =
+	!retries && config.postList.fallbackCover
+		? await resolveSiteImage(config.postList.fallbackCover)
+		: "";
 /* §4.106：列表封面用缩略图（外链/未命中自动回退原图；点击进文章页看正文原图） */
 const thumb = cover ? getThumbInfo(cover) : null;
 const classes = [
@@ -59,6 +64,7 @@ const excerpt = d.excerpt || d.description;
           loading="lazy"
           data-lqip
           data-api-retries={retries ? JSON.stringify(retries) : undefined}
+          data-cover-fallback={coverFallback || undefined}
         />
       </a>
     )

package/src/components/PostResources.astro

@@ -0,0 +1,75 @@
+---
+/**
+ * 文章资源区：frontmatter resources（name/url/password）在正文后渲染资源卡。
+ * 按 url 域名识别品牌图标（gitee/github），其余地址用通用外链图标；
+ * password 有值时展示提取码。新地址类型无需改组件，直接复用 name/url 展示。
+ */
+import { t } from "../i18n/index.js";
+
+interface ResourceItem {
+	name: string;
+	url: string;
+	password?: string;
+}
+
+interface Props {
+	resources?: ResourceItem[];
+}
+
+const { resources } = Astro.props;
+const items = (resources ?? []).filter((r) => r.url && r.url.trim() !== "");
+
+type IconKind = "gitee" | "github" | "link";
+function iconFor(url: string): IconKind {
+	let host = "";
+	try {
+		host = new URL(url).hostname.replace(/^www\./, "");
+	} catch {
+		return "link";
+	}
+	if (host === "gitee.com") return "gitee";
+	if (host === "github.com") return "github";
+	return "link";
+}
+---
+
+{
+  items.length > 0 && (
+    <section class="post-resources card reveal" aria-label={t("postResources")}>
+      <h2 class="post-resources-title">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></svg>
+        {t("postResources")}
+      </h2>
+      <ul class="post-resources-list">
+        {items.map((r) => {
+          const kind = iconFor(r.url);
+          return (
+            <li class="post-resources-item">
+              <a href={r.url} target="_blank" rel="noopener">
+                <span class="post-resources-icon" aria-hidden="true">
+                  {kind === "gitee" && (
+                    <svg viewBox="0 0 1024 1024" fill="currentColor"><path d="M512 1024C229.222 1024 0 794.778 0 512S229.222 0 512 0s512 229.222 512 512-229.222 512-512 512zm259.149-568.883h-290.74a25.293 25.293 0 0 0-25.292 25.293l-0.081 63.206c0 13.952 11.315 25.293 25.267 25.293h177.024c13.978 0 25.293 11.315 25.293 25.267v12.646a75.853 75.853 0 0 1-75.853 75.853h-240.23a25.293 25.293 0 0 1-25.267-25.293V417.203a75.853 75.853 0 0 1 75.827-75.853h353.946a25.293 25.293 0 0 0 25.267-25.292l0.077-63.207a25.293 25.293 0 0 0-25.268-25.293H417.152a189.62 189.62 0 0 0-189.62 189.645V771.15c0 13.977 11.316 25.293 25.294 25.293h372.94a170.65 170.65 0 0 0 170.65-170.65V480.384a25.293 25.293 0 0 0-25.267-25.267z"/></svg>
+                  )}
+                  {kind === "github" && (
+                    <svg viewBox="0 0 16 16" fill="currentColor"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
+                  )}
+                  {kind === "link" && (
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>
+                  )}
+                </span>
+                <span class="post-resources-name">{r.name}</span>
+                {r.password && r.password.trim() !== "" && (
+                  <span class="post-resources-password">
+                    {t("resourcePassword")}
+                    <code>{r.password}</code>
+                  </span>
+                )}
+                <svg class="post-resources-ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/></svg>
+              </a>
+            </li>
+          );
+        })}
+      </ul>
+    </section>
+  )
+}

package/src/i18n/en.ts

@@ -146,6 +146,9 @@ const en: Record<UiKey, string> = {
 		"No series yet. Add a series field to a post's frontmatter to create one.",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "Series catalog",
+	/* Post resources: resource card rendered from frontmatter resources */
+	postResources: "Related resources",
+	resourcePassword: "Code",
 	/* Music player (§4.36) */
 	musicOpen: "Music player",
 	musicClose: "Collapse player",

package/src/i18n/ja.ts

@@ -150,6 +150,9 @@ const ja: Record<UiKey, string> = {
 		"シリーズがまだありません。記事の frontmatter に series を記入すると作成できます。",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "シリーズ目次",
+	/* 記事リソース：frontmatter resources から描画されるリソースカード */
+	postResources: "関連リソース",
+	resourcePassword: "パスワード",
 	/* 音楽プレイヤー */
 	musicOpen: "音楽プレイヤー",
 	musicClose: "プレイヤーを閉じる",

package/src/i18n/ko.ts

@@ -149,6 +149,9 @@ const ko: Record<UiKey, string> = {
 		"아직 시리즈가 없습니다. 글 frontmatter에 series를 입력하면 생성됩니다.",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "시리즈 목차",
+	/* 게시글 리소스: frontmatter resources 로 렌더링되는 리소스 카드 */
+	postResources: "관련 자료",
+	resourcePassword: "추출 코드",
 	/* 음악 플레이어 */
 	musicOpen: "음악 플레이어",
 	musicClose: "플레이어 접기",

package/src/i18n/ru.ts

@@ -150,6 +150,9 @@ const ru: Record<UiKey, string> = {
 		"Серий пока нет. Заполните поле series в frontmatter записи, чтобы создать.",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "Содержание серии",
+	/* Ресурсы статьи: карточка из frontmatter resources */
+	postResources: "Материалы",
+	resourcePassword: "Код доступа",
 	/* Музыкальный плеер */
 	musicOpen: "Музыкальный плеер",
 	musicClose: "Свернуть плеер",

package/src/i18n/zh-CN.ts

@@ -166,6 +166,9 @@ const zhCN = {
 	seriesEmpty: "还没有专题，在文章 frontmatter 中填写 series 字段即可创建。",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "专题目录",
+	/* 文章资源区：frontmatter resources 渲染的资源卡 */
+	postResources: "相关资源",
+	resourcePassword: "提取码",
 	/* 音乐播放器（§4.36）：data-labels 经组件 data-labels 属性带入客户端 */
 	musicOpen: "音乐播放器",
 	musicClose: "收起播放器",

package/src/i18n/zh-TW.ts

@@ -145,6 +145,9 @@ const zhTW: Record<UiKey, string> = {
 	seriesEmpty: "還沒有專題，在文章 frontmatter 中填寫 series 欄位即可建立。",
 	seriesProgress: "{cur} / {total}",
 	seriesCatalog: "專題目錄",
+	/* 文章資源區：frontmatter resources 渲染的資源卡 */
+	postResources: "相關資源",
+	resourcePassword: "提取碼",
 	/* 音樂播放器 */
 	musicOpen: "音樂播放器",
 	musicClose: "收起播放器",

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

@@ -2,18 +2,19 @@
 import { getCollection } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
 import Pagination from "virtual:theme/components/Pagination.astro";
+import PostCard from "virtual:theme/components/PostCard.astro";
+import Sidebar from "virtual:theme/components/Sidebar.astro";
 import config from "virtual:theme/config";
 import { t } from "../../../i18n/index.js";
-import {
-	collectCategories,
-	formatDate,
-	getSortedPosts,
-} from "../../../utils.js";
+import { collectCategories, getSortedPosts } from "../../../utils.js";
+import { hydratePosts } from "../../_hydrate.js";
 
 /**
  * 分类详情（§4.87 分页）：每分类按 postList.pageSize 分页，第一页
- * /categories/<category>/（page 段省略），后续 /categories/<category>/2/ 起。
- * paginate() helper 生成 Page 对象（props.page），Page.data 即当前页文章。
+ * /categories/<category>/（page 段省略），后续 /categories/<category>/page/N/。
+ * 注意：分页段必须是 page/N/（§4.113）——Pagination 组件按此约定生成 href，
+ * paginate() 默认产出的 /N/ 会与组件链接错位导致 404，这里统一 remap。
+ * 布局与首页同构（§4.113）：PostCard 列表 + Sidebar，替代原单列窄卡片。
  */
 export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const all = await getCollection("posts", ({ data }) =>
@@ -24,30 +25,40 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	return [...collectCategories(sorted).entries()].flatMap(([category, posts]) =>
 		paginate(posts, {
 			params: { category },
-			props: { category },
+			props: { category, sorted },
 			pageSize: config.postList.pageSize,
-		}),
+		}).map((entry: any, i: number) => ({
+			params: { category, page: i > 0 ? `page/${i + 1}` : undefined },
+			props: entry.props,
+		})),
 	);
 }
 
-const { page, category } = Astro.props;
-const posts = page.data;
+const { page, category, sorted } = Astro.props;
+const pagePosts = await hydratePosts(page.data);
 ---
 
 <BaseLayout title={t('categoryTitle', { category })} page="categories">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{category}</h1>
-    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post: any) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">{formatDate(post.data.published)}</div>
-        </a>
-      ))
-    }
+  <div class="home-layout">
+    {/* 文章列表：与首页同一容器约定，供 app.ts 恢复与切换网格/列表形态 */}
+    <div
+      class="post-list"
+      id="postList"
+      data-allow-switch={config.postList.allowSwitch ? "true" : undefined}
+      data-default-layout={config.postList.defaultLayout}
+      data-grid-col={config.postList.gridColumnWidth}
+    >
+      <header class="archive-head reveal">
+        <h1 class="page-title">{category}</h1>
+        <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+      </header>
+      {
+        pagePosts.map((post: any) => (
+          <PostCard post={post} featured={post.data.pinned} />
+        ))
+      }
+      <Pagination page={page.currentPage} total={page.lastPage} basePath={`/categories/${category}/`} />
+    </div>
+    <Sidebar posts={sorted} />
   </div>
-  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/categories/${category}/`} />
 </BaseLayout>

package/src/routes/friends.astro

@@ -1,6 +1,7 @@
 ---
 import { getEntry, render } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
+import Comment from "virtual:theme/components/Comment.astro";
 import config from "virtual:theme/config";
 import { t } from "../i18n/index.js";
 import { resolveSiteImage } from "../utils/image.js";
@@ -88,4 +89,7 @@ const apply = config.friends.apply;
       </section>
     )
   }
+
+  <!-- §4.113：友链页评论区，支持直接留言申请友链（provider 未启用时自动 no-op） -->
+  <Comment path="/friends" />
 </BaseLayout>

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

@@ -8,7 +8,9 @@ import { formatDate } from "../../utils.js";
 
 /**
  * 说说页（§4.87）：moments collection 时间流，按 published 新→旧，
- * 每页 20 条（第一页 /moments/，后续 /moments/2/）。
+ * 每页 20 条（第一页 /moments/，后续 /moments/page/N/）。
+ * 分页段必须是 page/N/（§4.113）——Pagination 组件按此约定生成 href，
+ * paginate() 默认产出的 /N/ 会与组件链接错位导致 404，这里统一 remap。
  * 正文走主题统一 markdown processor（全部增强语法可用）；配图 images 网格
  * 展示并接入通用灯箱（data-lightbox-group 组浏览）。
  */
@@ -19,7 +21,10 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const sorted = [...all].sort(
 		(a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
 	);
-	return paginate(sorted, { pageSize: 20 });
+	return paginate(sorted, { pageSize: 20 }).map((entry: any, i: number) => ({
+		params: { page: i > 0 ? `page/${i + 1}` : undefined },
+		props: entry.props,
+	}));
 }
 
 const { page } = Astro.props;

package/src/routes/posts/[...slug].astro

@@ -10,6 +10,7 @@ import EncryptedContent from "virtual:theme/components/EncryptedContent.astro";
 import License from "virtual:theme/components/License.astro";
 import OutdatedCard from "virtual:theme/components/OutdatedCard.astro";
 import PostNav from "virtual:theme/components/PostNav.astro";
+import PostResources from "virtual:theme/components/PostResources.astro";
 import RecommendedPost from "virtual:theme/components/RecommendedPost.astro";
 import Sidebar from "virtual:theme/components/Sidebar.astro";
 import Toc from "virtual:theme/components/Toc.astro";
@@ -111,6 +112,11 @@ const { cover: rawArticleCover, retries: coverRetries } = resolveCover(
 const articleCover = rawArticleCover
 	? await resolveSiteImage(rawArticleCover)
 	: rawArticleCover;
+/* §4.114：普通封面图失效的客户端兜底（api 文章 retries 末尾已含 fallbackCover，无需重复） */
+const coverFallback =
+	!coverRetries && config.postList.fallbackCover
+		? await resolveSiteImage(config.postList.fallbackCover)
+		: "";
 const { Content, headings, remarkPluginFrontmatter } = await render(post);
 const { words, minutes } = remarkPluginFrontmatter as {
 	words?: number;
@@ -240,6 +246,7 @@ const jsonLd = {
           loading="eager"
           data-lqip
           data-api-retries={coverRetries ? JSON.stringify(coverRetries) : undefined}
+          data-cover-fallback={coverFallback || undefined}
         />
       </figure>
     )
@@ -297,6 +304,8 @@ const jsonLd = {
     {/* 过时提醒（§4.11）：许可卡之前展示；加密文章不渲染 */}
     {!d.password && <OutdatedCard updated={d.updated ?? d.published} published={d.published} />}
     <License licenseName={d.licenseName} licenseUrl={d.licenseUrl} enabled={d.license} />
+    {/* 文章资源区：frontmatter resources 非空时渲染；加密文章随正文语义一并隐藏 */}
+    {!d.password && <PostResources resources={d.resources} />}
     <PostNav prev={prev ?? undefined} next={next ?? undefined} />
   {/* 支持卡（P2）：打赏入口 + 分享海报（share-poster.ts 仍按 #qy-share-btn 与 data-* 绑定） */}
   {

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

@@ -2,13 +2,17 @@
 import { getCollection } from "astro:content";
 import BaseLayout from "virtual:theme/components/BaseLayout.astro";
 import Pagination from "virtual:theme/components/Pagination.astro";
+import PostCard from "virtual:theme/components/PostCard.astro";
+import Sidebar from "virtual:theme/components/Sidebar.astro";
 import config from "virtual:theme/config";
 import { t } from "../../../i18n/index.js";
-import { collectTags, formatDate, getSortedPosts } from "../../../utils.js";
+import { collectTags, getSortedPosts } from "../../../utils.js";
+import { hydratePosts } from "../../_hydrate.js";
 
 /**
  * 标签详情（§4.87 分页）：每标签按 postList.pageSize 分页，第一页
- * /tags/<tag>/（page 段省略），后续 /tags/<tag>/2/ 起。结构与分类详情页一致。
+ * /tags/<tag>/（page 段省略），后续 /tags/<tag>/page/N/。结构与分类详情页一致。
+ * 分页段 page/N/ 与布局同构改造见分类详情页注释（§4.113）。
  */
 export async function getStaticPaths({ paginate }: { paginate: any }) {
 	const all = await getCollection("posts", ({ data }) =>
@@ -19,33 +23,40 @@ export async function getStaticPaths({ paginate }: { paginate: any }) {
 	return [...collectTags(sorted).entries()].flatMap(([tag, posts]) =>
 		paginate(posts, {
 			params: { tag },
-			props: { tag },
+			props: { tag, sorted },
 			pageSize: config.postList.pageSize,
-		}),
+		}).map((entry: any, i: number) => ({
+			params: { tag, page: i > 0 ? `page/${i + 1}` : undefined },
+			props: entry.props,
+		})),
 	);
 }
 
-const { page, tag } = Astro.props;
-const posts = page.data;
+const { page, tag, sorted } = Astro.props;
+const pagePosts = await hydratePosts(page.data);
 ---
 
 <BaseLayout title={t('tagTitle', { tag })} page="tags">
-  <header class="archive-head reveal">
-    <h1 class="page-title">{tag}</h1>
-    <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
-  </header>
-  <div class="tag-list">
-    {
-      posts.map((post: any) => (
-        <a class="related-card card tag-item reveal" href={`/posts/${post.id}/`}>
-          <div class="rc-title">{post.data.title}</div>
-          <div class="rc-meta">
-            {formatDate(post.data.published)}
-            {post.data.category ? ` · ${post.data.category}` : ''}
-          </div>
-        </a>
-      ))
-    }
+  <div class="home-layout">
+    {/* 文章列表：与首页同一容器约定，供 app.ts 恢复与切换网格/列表形态 */}
+    <div
+      class="post-list"
+      id="postList"
+      data-allow-switch={config.postList.allowSwitch ? "true" : undefined}
+      data-default-layout={config.postList.defaultLayout}
+      data-grid-col={config.postList.gridColumnWidth}
+    >
+      <header class="archive-head reveal">
+        <h1 class="page-title">{tag}</h1>
+        <p class="page-sub">{t('totalPosts', { n: page.total })}</p>
+      </header>
+      {
+        pagePosts.map((post: any) => (
+          <PostCard post={post} featured={post.data.pinned} />
+        ))
+      }
+      <Pagination page={page.currentPage} total={page.lastPage} basePath={`/tags/${tag}/`} />
+    </div>
+    <Sidebar posts={sorted} />
   </div>
-  <Pagination page={page.currentPage} total={page.lastPage} basePath={`/tags/${tag}/`} />
 </BaseLayout>

package/src/schema.ts

@@ -368,9 +368,10 @@ export const themeConfigSchema = z.object({
 			fallbackCover: z.string().optional(),
 			/**
 			 * 随机封面图源（§4.33）：apis 非空时，frontmatter 显式 image:"api" 的文章
-			 * 从该列表取封面。URL 支持 {slug} 占位符（替换为文章 id），
+			 * 按 slug 确定性轮转选一条（§4.113，可传本地 public 路径列表做多源随机；
+			 * 单条时恒为第一条）。URL 支持 {slug} 占位符（替换为文章 id），
 			 * 并自动追加 ?v=<hash>（Java hashCode(slug)），同 slug 每次构建稳定同图。
-			 * 客户端加载失败时按列表顺序依次重试，全部失败显示本地 fallbackCover。
+			 * 客户端加载失败时按其余图源顺序依次重试，全部失败显示本地 fallbackCover。
 			 */
 			randomCover: z
 				.object({
@@ -1638,6 +1639,20 @@ export function definePostSchema(extensions: z.ZodRawShape = {}) {
 			 * 组名直接来自本字段文本，无 i18n 参与。
 			 */
 			seriesGroup: z.string().optional(),
+			/**
+			 * 文章相关资源：正文后渲染资源卡区。name 展示名、url 跳转地址、
+			 * password 提取码（可空）。按 url 域名识别品牌图标（gitee/github），
+			 * 其余地址类型直接复用通用外链图标展示，无需再改 schema。
+			 */
+			resources: z
+				.array(
+					z.object({
+						name: z.string(),
+						url: z.string(),
+						password: z.string().optional(),
+					}),
+				)
+				.optional(),
 		})
 		.extend(extensions);
 }

package/src/scripts/app.ts

@@ -1110,8 +1110,9 @@ doc.addEventListener("click", (e) => {
 	}
 });
 
-/* 随机封面加载失败重试（§4.33）：img error 不冒泡，捕获阶段 document 级委托
-   （bundled 一次性执行，VT 换页后仍有效）。按 data-api-retries 顺序换源，
+/* 封面加载失败兜底（§4.33 随机重试 + §4.114 普通图兜底）：img error 不冒泡，捕获阶段
+   document 级委托（bundled 一次性执行，VT 换页后仍有效）。优先按 data-api-retries
+   顺序换源；无重试列表的普通封面图按 data-cover-fallback 换兜底图（仅试一次）；
    全部失败加 cover-broken 藏 img，露出底层 LQIP 渐变占位。 */
 doc.addEventListener(
 	"error",
@@ -1119,20 +1120,26 @@ doc.addEventListener(
 		const img = e.target as HTMLImageElement | null;
 		if (img?.tagName !== "IMG") return;
 		const raw = img.dataset.apiRetries;
-		if (!raw) return;
-		let list: string[] = [];
-		try {
-			list = JSON.parse(raw);
-		} catch {
-			return;
+		if (raw) {
+			try {
+				const list: string[] = JSON.parse(raw);
+				const idx = Number(img.dataset.retryIdx ?? "1");
+				if (idx >= 0 && idx < list.length) {
+					img.dataset.retryIdx = String(idx + 1);
+					img.src = list[idx];
+					return;
+				}
+			} catch {
+				/* 列表损坏则落到兜底分支 */
+			}
 		}
-		const idx = Number(img.dataset.retryIdx ?? "1");
-		if (idx >= 0 && idx < list.length) {
-			img.dataset.retryIdx = String(idx + 1);
-			img.src = list[idx];
-		} else {
-			img.classList.add("cover-broken");
+		const fb = img.dataset.coverFallback;
+		if (fb && !img.dataset.fallbackTried) {
+			img.dataset.fallbackTried = "1";
+			img.src = fb;
+			return;
 		}
+		if (raw || fb) img.classList.add("cover-broken");
 	},
 	true,
 );

package/src/scripts/share-poster.ts

@@ -451,6 +451,8 @@ export async function openSharePoster(btn: HTMLElement) {
 			img.src = poster;
 			img.hidden = false;
 		}
+		/* 生成完成：移除 loading（否则转圈常驻在海报上方） */
+		modal.querySelector<HTMLElement>(".poster-loading")?.remove();
 		if (saveBtn) {
 			saveBtn.disabled = false;
 			saveBtn.addEventListener("click", () => {

package/src/styles/global.css

@@ -3339,6 +3339,94 @@ html.dark .outdated-warning {
 	border-radius: var(--radius-sm);
 	background: var(--bg-soft);
 }
+/* 文章资源区：frontmatter resources 渲染的资源卡（License 之后、上下篇之前） */
+.post-resources {
+	margin-top: 28px;
+	padding: 16px 20px;
+}
+.post-resources-title {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	margin: 0 0 10px;
+	font-size: 15.5px;
+	font-weight: 700;
+	color: var(--ink);
+}
+.post-resources-title svg {
+	width: 16px;
+	height: 16px;
+	color: var(--accent);
+}
+.post-resources-list {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: grid;
+	gap: 4px;
+}
+.post-resources-item a {
+	display: flex;
+	align-items: center;
+	gap: 10px;
+	padding: 7px 8px;
+	border-radius: var(--radius-sm);
+	font-size: 14px;
+	color: var(--ink-2);
+	transition: background 0.15s ease, color 0.15s ease;
+}
+.post-resources-item a:hover {
+	background: var(--bg-soft);
+	color: var(--accent-deep);
+}
+.post-resources-icon {
+	flex: none;
+	display: inline-flex;
+	width: 18px;
+	height: 18px;
+	color: var(--muted);
+}
+.post-resources-item a:hover .post-resources-icon {
+	color: var(--accent);
+}
+.post-resources-icon svg {
+	width: 100%;
+	height: 100%;
+}
+.post-resources-name {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+.post-resources-password {
+	flex: none;
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	margin-left: auto;
+	font-size: 12.5px;
+	color: var(--muted);
+}
+.post-resources-password code {
+	padding: 1px 6px;
+	border-radius: 4px;
+	border: 1px solid var(--border);
+	background: var(--bg-soft);
+	font-size: 12px;
+	color: var(--ink-2);
+}
+.post-resources-ext {
+	flex: none;
+	width: 14px;
+	height: 14px;
+	color: var(--muted);
+	opacity: 0.6;
+}
+.post-resources-item a:hover .post-resources-ext {
+	color: var(--accent);
+	opacity: 1;
+}
 .post-nav {
 	margin-top: 24px;
 	display: grid;
@@ -5592,6 +5680,10 @@ a[data-encoded-email] {
 	height: auto;
 	border-radius: var(--radius-sm);
 }
+/* display:block 会覆盖 [hidden] 的 UA 样式，显式声明防生成前空框露出 */
+.poster-img[hidden] {
+	display: none;
+}
 .poster-loading {
 	display: flex;
 	align-items: center;

package/src/utils.ts

@@ -212,8 +212,9 @@ export function randomCoverUrl(template: string, slug: string): string {
 
 /**
  * 解析文章封面（§4.33）：frontmatter image 为 "api" 且配置了图源时，
- * 返回 { cover, retries }——cover 为主图 URL，retries 为客户端
- * 加载失败时的依次重试列表（图源全量 + fallbackCover 兜底）。
+ * 返回 { cover, retries }——cover 按 slug 确定性轮转选一条（§4.113，
+ * 支持本地图片列表做多源随机；单图源退化为恒取第一条，行为不变），
+ * retries 为客户端加载失败时的依次重试列表（其余图源 + fallbackCover 兜底）。
  * 非 "api" 或未配置图源时原样返回，行为与之前一致。
  */
 export function resolveCover(
@@ -226,8 +227,9 @@ export function resolveCover(
 	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))];
+	const urls = apis.map((u) => randomCoverUrl(u, slug));
+	const idx = seedHash(slug) % urls.length;
+	const retries = [...urls.slice(idx + 1), ...urls.slice(0, idx)];
 	if (fallbackCover) retries.push(fallbackCover);
-	return { cover, retries };
+	return { cover: urls[idx], retries };
 }