tavern-harness 0.1.13 → 0.1.14

package/src/components/NewSessionMenu.tsx

@@ -153,7 +153,7 @@ export function NewSessionMenu({ onClose, editingSession }: { onClose: () => voi
   const canCreate = selectedNpcIds.length > 0;
 
   return (
-    <Modal onClose={onClose} width={460} className="new-session-modal">
+    <Modal onClose={onClose} className="new-session-modal">
       <div className="modal-head">
         <span style={{ fontWeight: 800, fontSize: 15 }}>{isEditing ? t('nav.editSession') : t('newSession.title')}</span>
         <button className="icon-btn" onClick={onClose}><Icon name="x" /></button>

package/src/components/SettingsView.tsx

@@ -1,6 +1,6 @@
-import { useState } from 'react';
+import { memo, useState } from 'react';
 import { useStore } from '../store/store';
-import { db } from '../db/database';
+import { db, DEFAULT_GENERATION_SETTINGS } from '../db/database';
 import { type ThemeMode } from '../theme/theme';
 import { type ApiProvider, type AppLanguage, type ReasoningEffort, enabledModelIds, modelAliases } from '../types/models';
 import { Icon, Modal } from './shared';
@@ -14,9 +14,10 @@ import { VersionHistoryModal } from './VersionHistoryModal';
 // 设置视图（模型服务 / 超参数 / 主题）
 // ============================================================
 
-export function SettingsView() {
+export const SettingsView = memo(function SettingsView() {
   const settings = useStore((s) => s.settings);
   const setSettings = useStore((s) => s.setSettings);
+  const addToast = useStore((s) => s.addToast);
   const resetTavern = useStore((s) => s.resetTavern);
   const providers = useStore((s) => s.providers);
   const refreshProviders = useStore((s) => s.refreshProviders);
@@ -43,6 +44,15 @@ export function SettingsView() {
     </label>
   );
 
+  const generationDefaults = DEFAULT_GENERATION_SETTINGS;
+  const isGenerationDefault = (Object.keys(generationDefaults) as Array<keyof typeof generationDefaults>)
+    .every((key) => settings[key] === generationDefaults[key]);
+
+  const resetGenerationParams = async () => {
+    await setSettings({ ...generationDefaults });
+    addToast(t('toast.genParamsReset'));
+  };
+
   return (
     <div className="view-page">
       <div className="view-col">
@@ -76,7 +86,18 @@ export function SettingsView() {
 
         {/* 生成参数 */}
         <div className="set-section">
-          <h3>{t('settings.genParams')}</h3>
+          <div className="settings-section-head">
+            <h3>{t('settings.genParams')}</h3>
+            <button
+              className="btn btn-sm settings-gen-reset"
+              title={t('settings.genParamsResetTitle')}
+              aria-label={t('settings.genParamsResetTitle')}
+              disabled={isGenerationDefault}
+              onClick={() => void resetGenerationParams()}
+            >
+              <Icon name="refresh" size={12} /> {t('settings.genParamsReset')}
+            </button>
+          </div>
           <table className="table param-table">
             <tbody>
               <tr>
@@ -229,7 +250,7 @@ export function SettingsView() {
       {showVersionHistory && <VersionHistoryModal onClose={() => setShowVersionHistory(false)} />}
 
       {showResetConfirm && (
-        <Modal onClose={() => !resetting && setShowResetConfirm(false)} width="min(420px, calc(100vw - 32px))">
+        <Modal onClose={() => !resetting && setShowResetConfirm(false)} size="compact">
           <div className="modal-head">
             <span style={{ fontWeight: 800, fontSize: 15 }}>{t('settings.resetConfirmTitle')}</span>
             <button className="icon-btn" disabled={resetting} onClick={() => setShowResetConfirm(false)}><Icon name="x" /></button>
@@ -257,7 +278,7 @@ export function SettingsView() {
       )}
     </div>
   );
-}
+});
 
 // ---------------- Providers ----------------
 
@@ -381,30 +402,26 @@ function ProviderManager({ providers, onChanged }: { providers: ApiProvider[]; o
       </div>
 
       {editing && (
-        <div className="overlay" onClick={() => setEditing(null)}>
-          <div className="modal-root" onClick={(e) => e.stopPropagation()}>
-            <div className="modal card">
-              <div className="modal-head">
-                <span style={{ fontWeight: 800, fontSize: 15 }}>{editing.id != null ? t('settings.editProvider') : t('settings.addProvider')}</span>
-                <button className="icon-btn" onClick={() => setEditing(null)}><Icon name="x" /></button>
-              </div>
-              <ProviderForm
-                initial={editing}
-                onSave={async (data) => {
-                  if (editing.id != null) {
-                    await db.providers.update(editing.id, data);
-                    addToast(t('toast.providerUpdated'));
-                  } else {
-                    await db.providers.add(data);
-                    addToast(t('toast.providerAdded'));
-                  }
-                  setEditing(null);
-                  onChanged();
-                }}
-              />
-            </div>
+        <Modal onClose={() => setEditing(null)}>
+          <div className="modal-head">
+            <span style={{ fontWeight: 800, fontSize: 15 }}>{editing.id != null ? t('settings.editProvider') : t('settings.addProvider')}</span>
+            <button className="icon-btn" onClick={() => setEditing(null)}><Icon name="x" /></button>
           </div>
-        </div>
+          <ProviderForm
+            initial={editing}
+            onSave={async (data) => {
+              if (editing.id != null) {
+                await db.providers.update(editing.id, data);
+                addToast(t('toast.providerUpdated'));
+              } else {
+                await db.providers.add(data);
+                addToast(t('toast.providerAdded'));
+              }
+              setEditing(null);
+              onChanged();
+            }}
+          />
+        </Modal>
       )}
 
       {pendingDelete && (

package/src/components/Sidebar.tsx

@@ -12,8 +12,11 @@ import { useTouchLongPress } from '../core/longPress';
 import { fixedViewportPoint } from '../core/viewport';
 import { useHasUnseenVersion } from '../core/version';
 import { PopoverMenu } from './PopoverMenu';
+import { unlockAchievement } from '../core/achievements';
 
 const SIDEBAR_MIN = 240;
+const SHAREHOLDER_CLICK_COUNT = 5;
+const SHAREHOLDER_CLICK_WINDOW_MS = 5_000;
 const SIDEBAR_MAX = 520;
 
 /** 触发 App 级全局游戏导出弹窗（会话右键菜单共用） */
@@ -50,6 +53,7 @@ export function Sidebar() {
   // 群聊会话 → 参与者中的 NPC 角色
   const [groupMembers, setGroupMembers] = useState<Record<number, NpcCharacter[]>>({});
   const sessionLongPressTarget = useRef<ChatSession | null>(null);
+  const homeClickTimes = useRef<number[]>([]);
   const sessionLongPressProps = useTouchLongPress(
     (point) => {
       const session = sessionLongPressTarget.current;
@@ -221,6 +225,20 @@ export function Sidebar() {
       colorOrdinal: n.avatarColorOrdinal,
       imageUrl: n.avatarDataUrl,
     }));
+
+  const returnHome = () => {
+    const now = Date.now();
+    homeClickTimes.current = [...homeClickTimes.current, now]
+      .filter((time) => now - time <= SHAREHOLDER_CLICK_WINDOW_MS)
+      .slice(-SHAREHOLDER_CLICK_COUNT);
+    if (homeClickTimes.current.length === SHAREHOLDER_CLICK_COUNT) {
+      homeClickTimes.current = [];
+      void unlockAchievement('th-shareholder').then(() => useStore.getState().refreshAchievements());
+    }
+    setActiveSession(null);
+    setActiveView('chat');
+  };
+
   return (
     <>
       <div className="mobile-topbar">
@@ -234,6 +252,15 @@ export function Sidebar() {
           <Icon name={mobileOpen ? 'x' : 'menu'} size={22} />
         </button>
         <nav className="mobile-topbar-nav" aria-label={t('nav.chat')}>
+          <button
+            className="mobile-home-button"
+            type="button"
+            title={t('nav.home')}
+            aria-label={t('nav.home')}
+            onClick={returnHome}
+          >
+            <img src="/tavern-harness-logo.png" alt="" />
+          </button>
           <button className={`nav-chip ${activeView === 'chat' ? 'active' : ''}`} onClick={() => setActiveView('chat')}>
             <Icon name="send" size={15} /> <span>{t('nav.chat')}</span>
           </button>
@@ -257,11 +284,11 @@ export function Sidebar() {
           role="button"
           tabIndex={0}
           title={t('nav.home')}
-          onClick={() => setActiveSession(null)}
+          onClick={returnHome}
           onKeyDown={(e) => {
             if (e.key === 'Enter' || e.key === ' ') {
               e.preventDefault();
-              setActiveSession(null);
+              returnHome();
             }
           }}
         >
@@ -436,7 +463,7 @@ export function Sidebar() {
 
       {/* 删除会话确认弹窗 */}
       {confirmDelete && (
-        <Modal onClose={() => setConfirmDelete(null)} width="min(400px, calc(100vw - 32px))">
+        <Modal onClose={() => setConfirmDelete(null)} size="compact">
           <div className="modal-head">
             <span style={{ fontWeight: 800, fontSize: 15, display: 'flex', alignItems: 'center', gap: 8 }}>
               <Icon name="trash" size={15} /> {t('nav.deleteSession')}

package/src/components/StatsView.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { memo, useCallback, useEffect, useState } from 'react';
 import { useStore } from '../store/store';
 import { getCareerStats, resetCareerStats } from '../core/stats';
 import { Icon } from './shared';
@@ -18,19 +18,22 @@ interface StatsData {
   npcStats: Array<{ npcId: number; npcName: string; rounds: number }>;
 }
 
-export function StatsView() {
+export const StatsView = memo(function StatsView({ active = true }: { active?: boolean }) {
   const addToast = useStore((s) => s.addToast);
   const t = useT();
   const [data, setData] = useState<StatsData | null>(null);
 
-  const refresh = async () => {
+  const refresh = useCallback(async () => {
     const d = await getCareerStats();
     setData(d);
-  };
+  }, []);
 
+  // 视图常驻不卸载（见 App.tsx 的 ViewSlot），所以每次重新显示时刷新一次，
+  // 否则聊完天回来看生涯统计会看到旧数字。
   useEffect(() => {
-    refresh();
-  }, []);
+    if (!active) return;
+    void refresh();
+  }, [active, refresh]);
 
   if (!data) {
     return <div className="view-page"><div className="spinner" /></div>;
@@ -39,13 +42,24 @@ export function StatsView() {
   return (
     <div className="view-page">
       <div className="view-col">
-        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: 12 }}>
+        <div>
+          <h2 className="view-title">{t('stats.title')}</h2>
+          <p className="view-sub">{t('stats.sub')}</p>
+        </div>
+
+        {/* 成就陈列柜 */}
+        <AchievementShelf />
+
+        {/* 生涯统计 */}
+        <StatCards data={data} />
+
+        <div className="stats-reset-card">
           <div>
-            <h2 className="view-title">{t('stats.title')}</h2>
-            <p className="view-sub">{t('stats.sub')}</p>
+            <h3>{t('stats.resetTitle')}</h3>
+            <p>{t('stats.resetDesc')}</p>
           </div>
           <button
-            className="btn btn-sm btn-danger"
+            className="btn btn-danger settings-reset-button"
             onClick={async () => {
               if (!confirm(t('stats.resetConfirm'))) return;
               await resetCareerStats();
@@ -56,16 +70,10 @@ export function StatsView() {
             <Icon name="refresh" size={12} /> {t('stats.resetBtn')}
           </button>
         </div>
-
-        {/* 成就陈列柜 */}
-        <AchievementShelf />
-
-        {/* 生涯统计 */}
-        <StatCards data={data} />
       </div>
     </div>
   );
-}
+});
 
 /** 成就陈列柜：已解锁的奖杯点亮，未解锁的只展示锁定状态 */
 function AchievementShelf() {
@@ -95,7 +103,9 @@ function AchievementCard({ data }: { data: AchievementState }) {
   return (
     <div className={`ach-card ${unlocked ? 'unlocked' : ''}`} title={unlocked ? t('stats.unlockedStatus') : t('stats.locked')}>
       <div className="ach-card-head">
-        <span className="ach-card-icon">{unlocked ? data.def.icon : '🔒'}</span>
+        <span className="ach-card-icon">
+          {unlocked && data.def.iconUrl ? <img className="ach-card-image" src={data.def.iconUrl} alt="" /> : unlocked ? data.def.icon : '🔒'}
+        </span>
         <span className="ach-card-status">{unlocked ? t('stats.unlockedStatus') : t('stats.locked')}</span>
       </div>
       <div className="ach-card-name">{unlocked ? t(`ach.${idToKey(data.def.id)}.name`) : t('stats.hidden')}</div>
@@ -117,33 +127,6 @@ function StatCards({ data }: { data: StatsData }) {
 
   return (
     <>
-      <div className="stat-grid">
-        <div className="stat-card">
-          <div className="v">{totalTokens.toLocaleString()}</div>
-          <div className="k">{t('stats.totalTokens')}</div>
-        </div>
-        <div className="stat-card">
-          <div className="v">{data.inputTokens.toLocaleString()}</div>
-          <div className="k">{t('stats.inputTokens')}</div>
-        </div>
-        <div className="stat-card">
-          <div className="v">{data.outputTokens.toLocaleString()}</div>
-          <div className="k">{t('stats.outputTokens')}</div>
-        </div>
-        <div className="stat-card">
-          <div className="v">{data.totalRounds}</div>
-          <div className="k">{t('stats.rounds')}</div>
-        </div>
-        <div className="stat-card">
-          <div className="v">{data.sessionCount}</div>
-          <div className="k">{t('stats.sessions')}</div>
-        </div>
-        <div className="stat-card">
-          <div className="v">{data.totalRounds && data.sessionCount ? (data.totalRounds / data.sessionCount).toFixed(1) : '0'}</div>
-          <div className="k">{t('stats.avgRounds')}</div>
-        </div>
-      </div>
-
       <div className="set-section">
         <h3>{t('stats.mostActive')}</h3>
         {data.npcStats.length > 0 ? (
@@ -184,6 +167,33 @@ function StatCards({ data }: { data: StatsData }) {
           </table>
         </div>
       )}
+
+      <div className="stat-grid">
+        <div className="stat-card">
+          <div className="v">{totalTokens.toLocaleString()}</div>
+          <div className="k">{t('stats.totalTokens')}</div>
+        </div>
+        <div className="stat-card">
+          <div className="v">{data.inputTokens.toLocaleString()}</div>
+          <div className="k">{t('stats.inputTokens')}</div>
+        </div>
+        <div className="stat-card">
+          <div className="v">{data.outputTokens.toLocaleString()}</div>
+          <div className="k">{t('stats.outputTokens')}</div>
+        </div>
+        <div className="stat-card">
+          <div className="v">{data.totalRounds}</div>
+          <div className="k">{t('stats.rounds')}</div>
+        </div>
+        <div className="stat-card">
+          <div className="v">{data.sessionCount}</div>
+          <div className="k">{t('stats.sessions')}</div>
+        </div>
+        <div className="stat-card">
+          <div className="v">{data.totalRounds && data.sessionCount ? (data.totalRounds / data.sessionCount).toFixed(1) : '0'}</div>
+          <div className="k">{t('stats.avgRounds')}</div>
+        </div>
+      </div>
     </>
   );
 }

package/src/components/VersionHistoryModal.tsx

@@ -91,7 +91,7 @@ export function VersionHistoryModal({ onClose }: { onClose: () => void }) {
   }, []);
 
   return (
-    <Modal onClose={onClose} width="min(720px, calc(100vw - 24px))">
+    <Modal onClose={onClose} size="wide">
       <div className="modal-head">
         <span style={{ fontWeight: 800, fontSize: 15 }}>{t('changelog.title')}</span>
         <button className="icon-btn" onClick={onClose} aria-label={t('common.close')}>

package/src/components/WorkspaceFileManagerModal.tsx

@@ -126,7 +126,7 @@ export function WorkspaceFileManagerModal({ sessionId, onClose }: { sessionId: n
   };
 
   return (
-    <Modal onClose={onClose} width="min(640px, calc(100vw - 32px))" className="ws-fm-modal">
+    <Modal onClose={onClose} className="ws-fm-modal">
       <div className="modal-head ws-fm-head">
         <span className="ws-fm-title">
           <Icon name="folder" size={15} />

package/src/components/shared.tsx

@@ -1,30 +1,33 @@
-import { Children, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { Children, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import DOMPurify from 'dompurify';
 import { renderMarkdown, highlightMentions } from '../core/markdown';
 import { useT } from '../core/i18n';
+import { useAvatarImageUrl } from '../core/avatarThumbnail';
 
 // ============================================================
 // 通用弹窗容器（Portal 到 body，避开祖先 backdrop-filter 产生的
 // 包含块，保证全页面居中、遮罩覆盖全屏、点击可用）
 // ============================================================
 
+type ModalSize = 'compact' | 'standard' | 'wide';
+
 export function Modal({
-  onClose,
-  width,
+  onClose: _onClose,
+  size = 'standard',
   className,
   children,
 }: {
   onClose: () => void;
-  width?: string | number;
+  size?: ModalSize;
   className?: string;
   children: React.ReactNode;
 }) {
   return createPortal(
     <>
-      <div className="overlay" onClick={onClose} />
+      <div className="overlay" />
       <div className="modal-root" onClick={(e) => e.stopPropagation()}>
-        <div className={`modal card fade-up ${className ?? ''}`.trim()} style={width != null ? { width } : undefined}>
+        <div className={`modal modal-size-${size} card fade-up ${className ?? ''}`.trim()}>
           {children}
         </div>
       </div>
@@ -43,15 +46,60 @@ interface MdProps {
   mentionNames?: string[];
 }
 
+/** LRU cache for sanitized Markdown. */
+const MARKDOWN_CACHE_LIMIT = 500;
+const MARKDOWN_CACHE_MAX_CHARS = 8 * 1024 * 1024;
+const MARKDOWN_CACHE_MAX_TEXT = 100_000;
+const markdownCache = new Map<string, string>();
+let markdownCacheChars = 0;
+const MENTION_SEPARATOR = '\u0000';
+
+function trimMarkdownCache(): void {
+  while (
+    (markdownCache.size > MARKDOWN_CACHE_LIMIT || markdownCacheChars > MARKDOWN_CACHE_MAX_CHARS)
+    && markdownCache.size > 1
+  ) {
+    const oldest = markdownCache.keys().next().value;
+    if (oldest == null) break;
+    const html = markdownCache.get(oldest);
+    if (html != null) markdownCacheChars -= oldest.length + html.length;
+    markdownCache.delete(oldest);
+  }
+}
+
+function renderSanitizedMarkdown(text: string, mathEnabled: boolean, mentionKey: string): string {
+  const key = `${mathEnabled ? 1 : 0}\u0001${mentionKey}\u0001${text}`;
+  const cached = markdownCache.get(key);
+  if (cached != null) {
+    // 刷新 LRU 顺序。
+    markdownCache.delete(key);
+    markdownCache.set(key, cached);
+    return cached;
+  }
+  let html = renderMarkdown(text, { mathEnabled });
+  const mentionNames = mentionKey ? mentionKey.split(MENTION_SEPARATOR) : [];
+  if (mentionNames.length > 0) html = highlightMentions(html, mentionNames);
+  const sanitized = DOMPurify.sanitize(html, {
+    USE_PROFILES: { html: true },
+    ALLOW_UNKNOWN_PROTOCOLS: false,
+  });
+  // 超长文本（例如大段工具输出）只渲染不缓存：重新解析一次比长期占内存划算。
+  if (text.length <= MARKDOWN_CACHE_MAX_TEXT) {
+    markdownCache.set(key, sanitized);
+    markdownCacheChars += key.length + sanitized.length;
+    trimMarkdownCache();
+  }
+  return sanitized;
+}
+
 export function Markdown({ text, mathEnabled = true, mentionNames = [] }: MdProps) {
-  const html = useMemo(() => {
-    let h = renderMarkdown(text, { mathEnabled });
-    if (mentionNames.length > 0) h = highlightMentions(h, mentionNames);
-    return DOMPurify.sanitize(h, {
-      USE_PROFILES: { html: true },
-      ALLOW_UNKNOWN_PROTOCOLS: false,
-    });
-  }, [text, mathEnabled, mentionNames]);
+  // 调用方每次渲染都会新建 mentionNames 数组，直接用数组做依赖会让缓存永远失效；
+  // 这里把它折叠成内容键（成员名按调用方顺序拼接）。
+  const mentionKey = mentionNames.join(MENTION_SEPARATOR);
+  const html = useMemo(
+    () => renderSanitizedMarkdown(text, mathEnabled, mentionKey),
+    [text, mathEnabled, mentionKey],
+  );
 
   return <div className="md" dangerouslySetInnerHTML={{ __html: html }} />;
 }
@@ -76,6 +124,7 @@ export function MasonryGrid({ children }: { children: React.ReactNode }) {
   const updateColumnCount = useCallback(() => {
     const grid = gridRef.current;
     if (!grid) return;
+    if (grid.clientWidth === 0) return;
     const styles = getComputedStyle(grid);
     const minColumnWidth = Number.parseFloat(styles.getPropertyValue('--masonry-column-min-width'));
     const gap = Number.parseFloat(styles.getPropertyValue('--masonry-gap'));
@@ -95,6 +144,7 @@ export function MasonryGrid({ children }: { children: React.ReactNode }) {
   useLayoutEffect(() => {
     const grid = gridRef.current;
     if (!grid) return;
+    if (grid.clientWidth === 0) return;
     const gap = Number.parseFloat(getComputedStyle(grid).getPropertyValue('--masonry-gap'));
     const heights = Array.from({ length: columnCount }, () => 0);
     const nextLayout = Array.from({ length: columnCount }, () => [] as number[]);
@@ -142,7 +192,13 @@ export function MasonryGrid({ children }: { children: React.ReactNode }) {
 // 头像（彩色首字母 / 图片）
 // ============================================================
 
-export function Avatar({
+/** Convert an image URL to a CSS `url()` value. */
+function cssImageUrl(url: string): string {
+  return /^data:[^,]*;base64,/i.test(url) ? `url("${url}")` : `url(${JSON.stringify(url)})`;
+}
+
+/** Avatar with image-thumbnail support. */
+export const Avatar = memo(function Avatar({
   name,
   colorOrdinal,
   imageUrl,
@@ -155,7 +211,8 @@ export function Avatar({
 }) {
   const cls = size === 'lg' ? 'avatar' : size === 'xs' ? 'avatar xs' : 'avatar sm';
   const hue = (colorOrdinal ?? 0) % 6;
-  if (imageUrl) {
+  const displayUrl = useAvatarImageUrl(imageUrl);
+  if (displayUrl) {
     // 用背景图而不是 <img>：微信 Android 内置浏览器会对 <img> 的长按弹出
     // “发送给朋友 / 保存图片”。命中测试落在宿主 div 上就不会触发原生菜单；
     // pointer-events: none 再让点击/滚动继续冒泡给外层（见 global.css）。
@@ -164,12 +221,12 @@ export function Avatar({
         className={`${cls} avatar-image`}
         role="img"
         aria-label={name}
-        style={{ backgroundImage: `url(${JSON.stringify(imageUrl)})` }}
+        style={{ backgroundImage: cssImageUrl(displayUrl) }}
       />
     );
   }
   return <div className={`${cls} avatar-hue-${hue}`}>{name.slice(0, 1)}</div>;
-}
+});
 
 // ============================================================
 // 附件卡片：仅展示文件名（去掉图片/视频缩略图）
@@ -285,13 +342,16 @@ export function Collapse({
 
   useEffect(() => {
     const el = contentRef.current;
-    if (el) {
-      setOverflow(el.scrollHeight > el.clientHeight + 4);
+    if (!el) return;
+    const measure = () => {
+      if (el.clientHeight > 0) setOverflow(el.scrollHeight > el.clientHeight + 4);
       // 流式进行中：实时跟随最新内容（钉在底部，展示最新的一行/一段）
-      if (live && open) {
-        el.scrollTop = el.scrollHeight;
-      }
-    }
+      if (live && open) el.scrollTop = el.scrollHeight;
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
   }, [preview, children, live, open]);
 
   const cls = `collp ${accent !== 'default' ? `collp-${accent}` : ''}`;

package/src/core/achievements.ts

@@ -8,8 +8,10 @@ export interface AchievementDef {
   id: string;
   name: string;
   icon: string;
-  /** 达成所需累计 Token 数（输入 + 输出） */
-  threshold: number;
+  /** 应用图标类成就使用的图片地址。 */
+  iconUrl?: string;
+  /** 达成所需累计 Token 数（输入 + 输出）；手动触发的彩蛋成就不设置此项。 */
+  threshold?: number;
   description: string;
 }
 
@@ -19,6 +21,7 @@ export const ACHIEVEMENTS: AchievementDef[] = [
   { id: 'bard', name: '吟游诗人', icon: '🎻', threshold: 100_000, description: '累计使用 100,000 Token' },
   { id: 'night-owl', name: '午夜不归人', icon: '🌙', threshold: 1_000_000, description: '累计使用 1,000,000 Token' },
   { id: 'legend', name: '酒馆传奇', icon: '🏆', threshold: 100_000_000, description: '累计使用 100,000,000 Token' },
+  { id: 'th-shareholder', name: 'TH股东', icon: '📈', iconUrl: '/tavern-harness-logo.png', description: '连续点击首页图标 5 次' },
 ];
 
 /** 生涯总 token（输入 + 输出） */
@@ -44,6 +47,21 @@ export function registerUnlockDispatcher(
   unlockDispatcher.push = dispatcher;
 }
 
+/** 解锁指定成就（幂等），用于不依赖 Token 门槛的彩蛋成就。 */
+export async function unlockAchievement(id: string): Promise<void> {
+  const def = ACHIEVEMENTS.find((achievement) => achievement.id === id);
+  if (!def) return;
+  const exists = await db.achievementUnlocks.where('achievementId').equals(id).first();
+  if (exists) return;
+
+  await db.achievementUnlocks.add({ achievementId: id, unlockedAt: Date.now() });
+  try {
+    await unlockDispatcher.push(def, await getTotalTokens());
+  } catch {
+    // 忽略 UI 展示层的错误，不影响成就记录。
+  }
+}
+
 let checkLock: Promise<void> | null = null;
 
 /**
@@ -61,7 +79,7 @@ export async function checkAchievementUnlocks(): Promise<void> {
     const newly: Array<{ def: AchievementDef; total: number }> = [];
 
     for (const def of ACHIEVEMENTS) {
-      if (unlocked.has(def.id)) continue;
+      if (unlocked.has(def.id) || def.threshold == null) continue;
       if (total >= def.threshold) {
         await db.achievementUnlocks.add({ achievementId: def.id, unlockedAt: Date.now() });
         newly.push({ def, total });
@@ -69,7 +87,7 @@ export async function checkAchievementUnlocks(): Promise<void> {
     }
     if (newly.length > 0) {
       // 由高到低依次展示（若多级同时达成）
-      for (const { def, total } of newly.sort((a, b) => b.def.threshold - a.def.threshold)) {
+      for (const { def, total } of newly.sort((a, b) => (b.def.threshold ?? 0) - (a.def.threshold ?? 0))) {
         try {
           await unlockDispatcher.push(def, total);
         } catch {