From 6bd85d33cfffdedb463d5468a17beb3058664431 Mon Sep 17 00:00:00 2001
From: Ivan Hanloth <ivan@hanloth.com>
Date: Wed, 22 Jul 2026 18:46:39 +0100
Subject: [PATCH 1/4] =?UTF-8?q?doc:=20=E6=9B=B4=E6=96=B0=E9=83=A8=E5=88=86?=
 =?UTF-8?q?=E6=96=87=E5=AD=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.en.md                                    | 2 +-
 README.md                                       | 2 +-
 README.zh-TW.md                                 | 2 +-
 apps/config/ui/src/components/AboutPanel.svelte | 4 ++--
 apps/config/ui/src/locales/en.js                | 2 +-
 apps/config/ui/src/locales/zh-CN.js             | 2 +-
 apps/config/ui/src/locales/zh-TW.js             | 2 +-
 7 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/README.en.md b/README.en.md
index a7007db..04f54e9 100644
--- a/README.en.md
+++ b/README.en.md
@@ -10,7 +10,7 @@
 
 <img src="https://img.shields.io/github/v/release/IvanHanloth/Boss-Key?style=flat-square" alt="Github Release Version">
 <img src="https://img.shields.io/github/license/IvanHanloth/Boss-Key?style=flat-square" alt="Github Repo License">
-<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/tag-release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
+<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
 <img src="https://img.shields.io/badge/Platform-Windows_10\+-cornflowerblue?style=flat-square" alt="Supported Platform">
 
 </p>
diff --git a/README.md b/README.md
index 8f65847..303d479 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
 
 <img src="https://img.shields.io/github/v/release/IvanHanloth/Boss-Key?style=flat-square" alt="Github Release Version">
 <img src="https://img.shields.io/github/license/IvanHanloth/Boss-Key?style=flat-square" alt="Github Repo License">
-<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/tag-release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
+<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
 <img src="https://img.shields.io/badge/Platform-Windows_10\+-cornflowerblue?style=flat-square" alt="Supported Platform">
 
 </p>
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 5bb00a4..448793e 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -10,7 +10,7 @@
 
 <img src="https://img.shields.io/github/v/release/IvanHanloth/Boss-Key?style=flat-square" alt="Github Release Version">
 <img src="https://img.shields.io/github/license/IvanHanloth/Boss-Key?style=flat-square" alt="Github Repo License">
-<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/tag-release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
+<img src="https://img.shields.io/github/actions/workflow/status/IvanHanloth/Boss-Key/release.yml?style=flat-square" alt="GitHub Actions Workflow Status">
 <img src="https://img.shields.io/badge/Platform-Windows_10\+-cornflowerblue?style=flat-square" alt="Supported Platform">
 
 </p>
diff --git a/apps/config/ui/src/components/AboutPanel.svelte b/apps/config/ui/src/components/AboutPanel.svelte
index 1e54f07..3f33a49 100644
--- a/apps/config/ui/src/components/AboutPanel.svelte
+++ b/apps/config/ui/src/components/AboutPanel.svelte
@@ -164,7 +164,7 @@
 
     <textarea
       class="fb"
-      rows="4"
+      rows="5"
       maxlength="4000"
       placeholder={t("about.feedbackPlaceholder")}
       bind:value={content}
@@ -326,7 +326,7 @@
 
   .fb {
     resize: vertical;
-    min-height: 84px;
+    min-height: 112px;
     font-family: inherit;
     line-height: 1.6;
   }
diff --git a/apps/config/ui/src/locales/en.js b/apps/config/ui/src/locales/en.js
index fe82141..34bdd73 100644
--- a/apps/config/ui/src/locales/en.js
+++ b/apps/config/ui/src/locales/en.js
@@ -268,7 +268,7 @@ export default {
   "about.starAria": "{n} stars",
   "about.stars": "{n} stars",
   "about.ratingOptional": "Rating (optional)",
-  "about.feedbackPlaceholder": "Tell us about a problem you hit or a feature you want…",
+  "about.feedbackPlaceholder": "The developer reads every note left here — feel free to ask for a feature, report what went wrong, or just say something nice ヾ(≧▽≦*)o~\nThat said, if you can, please file bugs and feature requests as GitHub Issues so they can all be followed up in one place (which leaves this box for compliments only ( •̀ ω •́ )✧ — kidding, of course).",
   "about.contactPlaceholder": "Contact (optional — email, QQ, etc.)",
   "about.submitting": "Submitting…",
   "about.submitFeedback": "Submit feedback",
diff --git a/apps/config/ui/src/locales/zh-CN.js b/apps/config/ui/src/locales/zh-CN.js
index cff6c08..66dbae1 100644
--- a/apps/config/ui/src/locales/zh-CN.js
+++ b/apps/config/ui/src/locales/zh-CN.js
@@ -254,7 +254,7 @@ export default {
   "about.starAria": "{n} 星",
   "about.stars": "{n} 星",
   "about.ratingOptional": "评分（可选）",
-  "about.feedbackPlaceholder": "说说遇到的问题、想要的功能…",
+  "about.feedbackPlaceholder": "开发者会认真阅读这里的每一条反馈，欢迎说说想要的功能、遇到的问题或者夸一夸开发者ヾ(≧▽≦*)o~\n不过，如果可以的话，推荐将 bug 和功能建议提交到 GitHub 的 Issue 区，方便开发者及时统一跟进（所以，这里只接受对开发者的夸奖( •̀ ω •́ )✧（开个玩笑））",
   "about.contactPlaceholder": "联系方式（可选，邮箱 / QQ 等）",
   "about.submitting": "提交中…",
   "about.submitFeedback": "提交反馈",
diff --git a/apps/config/ui/src/locales/zh-TW.js b/apps/config/ui/src/locales/zh-TW.js
index 2d2ba3c..e85b33e 100644
--- a/apps/config/ui/src/locales/zh-TW.js
+++ b/apps/config/ui/src/locales/zh-TW.js
@@ -258,7 +258,7 @@ export default {
   "about.starAria": "{n} 顆星",
   "about.stars": "{n} 顆星",
   "about.ratingOptional": "評分（選填）",
-  "about.feedbackPlaceholder": "說說遇到的問題、想要的功能…",
+  "about.feedbackPlaceholder": "開發者會認真閱讀這裡的每一則意見，歡迎說說想要的功能、遇到的問題或者誇一誇開發者ヾ(≧▽≦*)o~\n不過，如果可以的話，推薦將 bug 和功能建議提交到 GitHub 的 Issue 區，方便開發者及時統一追蹤（所以，這裡只接受對開發者的誇獎( •̀ ω •́ )✧（開個玩笑））",
   "about.contactPlaceholder": "聯絡方式（選填，電子郵件／通訊軟體等）",
   "about.submitting": "送出中…",
   "about.submitFeedback": "送出意見回饋",

From ed8dcc5f2da68bc2ff53ecc21f850ec840239f27 Mon Sep 17 00:00:00 2001
From: Ivan Hanloth <ivan@hanloth.com>
Date: Thu, 23 Jul 2026 19:53:09 +0100
Subject: [PATCH 2/4] =?UTF-8?q?feat:=E6=96=B0=E5=A2=9Emarkdown=E8=A7=A3?=
 =?UTF-8?q?=E6=9E=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../ui/src/components/AboutPanel.svelte       |   9 +-
 .../src/components/AnnouncementModal.svelte   |  11 +-
 apps/config/ui/src/components/Markdown.svelte | 140 ++++++++++++
 .../ui/src/components/UpdateModal.svelte      |   8 +-
 apps/config/ui/src/lib/ipc.js                 |   2 +-
 apps/config/ui/src/lib/markdown.js            | 213 ++++++++++++++++++
 apps/config/ui/src/lib/markdown.test.js       | 130 +++++++++++
 docs/dev/frontend.md                          |  16 ++
 docs/en/dev/frontend.md                       |  16 ++
 docs/zh-tw/dev/frontend.md                    |  16 ++
 10 files changed, 539 insertions(+), 22 deletions(-)
 create mode 100644 apps/config/ui/src/components/Markdown.svelte
 create mode 100644 apps/config/ui/src/lib/markdown.js
 create mode 100644 apps/config/ui/src/lib/markdown.test.js

diff --git a/apps/config/ui/src/components/AboutPanel.svelte b/apps/config/ui/src/components/AboutPanel.svelte
index 3f33a49..cf12f5c 100644
--- a/apps/config/ui/src/components/AboutPanel.svelte
+++ b/apps/config/ui/src/components/AboutPanel.svelte
@@ -7,6 +7,7 @@
   import IconRefreshCw from "~icons/lucide/refresh-cw";
   import IconStar from "~icons/lucide/star";
   import Card from "./Card.svelte";
+  import Markdown from "./Markdown.svelte";
   import SettingRow from "./SettingRow.svelte";
   import Toggle from "./Toggle.svelte";
   import {
@@ -129,7 +130,7 @@
               {#if a.is_pinned}<span class="pin">{t("about.pinned")}</span>{/if}
               <span class="adate">{formatTime(a.published_at)}</span>
             </div>
-            <pre class="acontent">{a.content}</pre>
+            <div class="acontent"><Markdown source={a.content} /></div>
           </li>
         {/each}
       </ul>
@@ -274,13 +275,9 @@
     color: var(--muted);
   }
   .acontent {
-    margin: 6px 0 0;
-    font-family: inherit;
+    margin-top: 6px;
     font-size: 12.5px;
-    line-height: 1.6;
     color: var(--muted);
-    white-space: pre-wrap;
-    word-break: break-word;
   }
   .empty,
   .card-hint {
diff --git a/apps/config/ui/src/components/AnnouncementModal.svelte b/apps/config/ui/src/components/AnnouncementModal.svelte
index ef31513..ea188d4 100644
--- a/apps/config/ui/src/components/AnnouncementModal.svelte
+++ b/apps/config/ui/src/components/AnnouncementModal.svelte
@@ -1,6 +1,7 @@
 <script>
   // 启动时弹出的未读公告。
   import IconMegaphone from "~icons/lucide/megaphone";
+  import Markdown from "./Markdown.svelte";
   import Modal from "./Modal.svelte";
   import { app, markAnnouncementSeen } from "../lib/state.svelte.js";
   import { formatTime } from "../lib/verhub.js";
@@ -31,7 +32,7 @@
         {#if item.author}{item.author} ·{/if}
         {formatTime(item.published_at)}
       </p>
-      <pre class="content">{item.content}</pre>
+      <Markdown source={item.content} />
     </div>
 
     {#snippet footer()}
@@ -65,12 +66,4 @@
     font-size: 12px;
     color: var(--muted);
   }
-  .content {
-    margin: 0;
-    font-family: inherit;
-    font-size: 13px;
-    line-height: 1.65;
-    white-space: pre-wrap;
-    word-break: break-word;
-  }
 </style>
diff --git a/apps/config/ui/src/components/Markdown.svelte b/apps/config/ui/src/components/Markdown.svelte
new file mode 100644
index 0000000..2d865d7
--- /dev/null
+++ b/apps/config/ui/src/components/Markdown.svelte
@@ -0,0 +1,140 @@
+<script>
+  // 渲染公告 / 更新日志里的 Markdown。样式取 GitHub 的观感，但按弹窗尺寸收紧了间距。
+  import { renderMarkdown } from "../lib/markdown.js";
+  import { toast } from "../lib/state.svelte.js";
+  import { openExternal } from "../lib/verhub.js";
+  import { t } from "../lib/i18n.svelte.js";
+
+  let { source = "" } = $props();
+
+  const html = $derived(renderMarkdown(source));
+
+  // 链接一律交给系统浏览器：webview 里真导航走了就回不到配置界面了。
+  function onClick(e) {
+    const a = e.target.closest?.("a[href]");
+    if (!a) return;
+    e.preventDefault();
+    openExternal(a.getAttribute("href")).catch((err) =>
+      toast(t("options.openLinkFailed", { err }), true),
+    );
+  }
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="md" onclick={onClick} onauxclick={(e) => e.preventDefault()}>
+  {@html html}
+</div>
+
+<style>
+  .md {
+    font-size: 13px;
+    line-height: 1.65;
+    word-break: break-word;
+  }
+  /* 渲染结果由 {@html} 注入，拿不到 Svelte 的作用域类名，只能用 :global。 */
+  .md :global(> *:first-child) {
+    margin-top: 0;
+  }
+  .md :global(> *:last-child) {
+    margin-bottom: 0;
+  }
+  .md :global(p),
+  .md :global(ul),
+  .md :global(ol),
+  .md :global(pre),
+  .md :global(blockquote) {
+    margin: 0 0 10px;
+  }
+  .md :global(h1),
+  .md :global(h2),
+  .md :global(h3),
+  .md :global(h4),
+  .md :global(h5),
+  .md :global(h6) {
+    margin: 16px 0 8px;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+  .md :global(h1) {
+    font-size: 17px;
+  }
+  .md :global(h2) {
+    font-size: 15px;
+  }
+  .md :global(h3) {
+    font-size: 14px;
+  }
+  .md :global(h4),
+  .md :global(h5),
+  .md :global(h6) {
+    font-size: 13px;
+  }
+  /* GitHub 的一二级标题带下边线 */
+  .md :global(h1),
+  .md :global(h2) {
+    padding-bottom: 5px;
+    border-bottom: 1px solid var(--border);
+  }
+  .md :global(ul),
+  .md :global(ol) {
+    padding-left: 1.6em;
+  }
+  .md :global(li) {
+    margin: 2px 0;
+  }
+  .md :global(li > ul),
+  .md :global(li > ol) {
+    margin: 2px 0;
+  }
+  .md :global(li.task) {
+    list-style: none;
+    margin-left: -1.4em;
+  }
+  .md :global(li.task > input) {
+    margin-right: 6px;
+    vertical-align: -1px;
+  }
+  .md :global(a) {
+    color: var(--accent);
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .md :global(a:hover) {
+    text-decoration: underline;
+  }
+  .md :global(code) {
+    padding: 0.15em 0.4em;
+    border-radius: 6px;
+    background: var(--hover);
+    font-family: ui-monospace, "Cascadia Mono", Consolas, monospace;
+    font-size: 0.9em;
+  }
+  .md :global(pre) {
+    padding: 10px 12px;
+    border-radius: 6px;
+    background: var(--surface-2);
+    border: 1px solid var(--border);
+    overflow-x: auto;
+  }
+  .md :global(pre code) {
+    padding: 0;
+    background: none;
+    border-radius: 0;
+    white-space: pre;
+  }
+  .md :global(blockquote) {
+    padding-left: 12px;
+    border-left: 3px solid var(--border);
+    color: var(--muted);
+  }
+  .md :global(hr) {
+    height: 1px;
+    margin: 14px 0;
+    border: 0;
+    background: var(--border);
+  }
+  .md :global(del) {
+    color: var(--muted);
+  }
+</style>
diff --git a/apps/config/ui/src/components/UpdateModal.svelte b/apps/config/ui/src/components/UpdateModal.svelte
index 25e2f40..c9af80a 100644
--- a/apps/config/ui/src/components/UpdateModal.svelte
+++ b/apps/config/ui/src/components/UpdateModal.svelte
@@ -5,6 +5,7 @@
   import IconDownload from "~icons/lucide/download";
   import IconTriangleAlert from "~icons/lucide/triangle-alert";
   import IconX from "~icons/lucide/x";
+  import Markdown from "./Markdown.svelte";
   import { win } from "../lib/ipc.js";
   import { app, toast } from "../lib/state.svelte.js";
   import { downloadUrl, formatTime, openExternal } from "../lib/verhub.js";
@@ -61,7 +62,7 @@
         </div>
 
         {#if target.title}<p class="title">{target.title}</p>{/if}
-        {#if target.content}<pre class="notes">{target.content}</pre>{/if}
+        {#if target.content}<div class="notes"><Markdown source={target.content} /></div>{/if}
 
         {#if forced}
           <p class="warn">{t("update.forcedNote")}</p>
@@ -164,16 +165,11 @@
     font-weight: 600;
   }
   .notes {
-    margin: 0;
     padding: 10px 12px;
     background: var(--surface-2);
     border: 1px solid var(--border);
     border-radius: 8px;
-    font-family: inherit;
     font-size: 12.5px;
-    line-height: 1.6;
-    white-space: pre-wrap;
-    word-break: break-word;
     max-height: 240px;
     overflow-y: auto;
   }
diff --git a/apps/config/ui/src/lib/ipc.js b/apps/config/ui/src/lib/ipc.js
index dfc5bce..e4f5973 100644
--- a/apps/config/ui/src/lib/ipc.js
+++ b/apps/config/ui/src/lib/ipc.js
@@ -147,7 +147,7 @@ function mockInvoke(cmd, args) {
         {
           id: "mock-1",
           title: "Boss Key 3.0 发布",
-          content: "全新界面与核心，鼠标按键触发、崩溃恢复、进程冻结。",
+          content: "全新界面与核心，**鼠标按键触发**、崩溃恢复、进程冻结。详见 [更新日志](https://boss-key.ivan-hanloth.cn/changelog/)。",
           is_pinned: true,
           is_hidden: false,
           author: "Ivan Hanloth",
diff --git a/apps/config/ui/src/lib/markdown.js b/apps/config/ui/src/lib/markdown.js
new file mode 100644
index 0000000..101eb92
--- /dev/null
+++ b/apps/config/ui/src/lib/markdown.js
@@ -0,0 +1,213 @@
+// 极简 Markdown 渲染，供公告与更新日志使用。只覆盖 GitHub 风格的常用子集，
+// 不引入任何依赖。
+//
+// 内容来自 Verhub 远端，因此这里**先转义再拼标签**：输出里出现的标签全部由本
+// 模块生成，源文本里的原始 HTML 只会被当成字面量显示，无需再过一遍消毒。
+
+const ESCAPE = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const HR = /^ {0,3}([-*_])[ \t]*(?:\1[ \t]*){2,}$/;
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$/;
+const QUOTE = /^ {0,3}> ?(.*)$/;
+const ITEM = /^([ \t]*)(?:([-*+])|(\d{1,9})[.)])[ \t]+(.*)$/;
+const TASK = /^\[([ xX])\][ \t]+/;
+
+// 行内解析的占位符哨兵。NUL 不会出现在正文里，也不属于 \s，因此裸链接之类的
+// 规则不会越过它去改写已经成型的标签。
+const SENTINEL = String.fromCharCode(0);
+const PLACEHOLDER = new RegExp(`${SENTINEL}(\\d+)${SENTINEL}`, "g");
+
+const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ESCAPE[c]);
+
+/** 只放行 http(s) 与 mailto：javascript: / data: 等一律按纯文本处理。 */
+function safeUrl(raw) {
+  const url = raw.trim();
+  return /^(?:https?:\/\/|mailto:)/i.test(url) ? url : null;
+}
+
+const startsBlock = (line) =>
+  FENCE.test(line) || HR.test(line) || HEADING.test(line) || QUOTE.test(line) || ITEM.test(line);
+
+/** 渲染行内标记，返回 HTML 片段。 */
+function inline(text) {
+  const stash = [];
+  // 已成型的标签先寄存成占位符，避免被后续规则二次改写。
+  const hold = (html) => `${SENTINEL}${stash.push(html) - 1}${SENTINEL}`;
+  let s = escapeHtml(text);
+
+  s = s.replace(/(`+)([^`]+?)\1/g, (_, __, code) => hold(`<code>${code}</code>`));
+
+  // CSP 只允许 self / data: 图源，远端图片加载不出来，统一退化成链接。
+  s = s.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (m, alt, dest) => anchor(dest, alt, hold) ?? m);
+  s = s.replace(/\[([^\]]*)\]\(([^)]+)\)/g, (m, label, dest) => anchor(dest, label, hold) ?? m);
+
+  // 裸链接。前面必须是行首/空白/左括号，因此紧挨占位符的文本不会被重复包裹。
+  s = s.replace(/(^|[\s(])(https?:\/\/\S+)/g, (_, pre, raw) => {
+    const trailing = raw.match(/[.,;:!?)]+$/)?.[0] ?? "";
+    const url = raw.slice(0, raw.length - trailing.length);
+    return pre + hold(`<a href="${url}">`) + url + hold("</a>") + trailing;
+  });
+
+  s = s
+    .replace(/\*\*([^\s*](?:[^*]*[^\s*])?)\*\*/g, "<strong>$1</strong>")
+    .replace(/__([^\s_](?:[^_]*[^\s_])?)__/g, "<strong>$1</strong>")
+    .replace(/(^|[^*])\*([^\s*](?:[^*]*[^\s*])?)\*/g, "$1<em>$2</em>")
+    .replace(/(^|[^\w_])_([^\s_](?:[^_]*[^\s_])?)_/g, "$1<em>$2</em>")
+    .replace(/~~([^~]+)~~/g, "<del>$1</del>");
+
+  return s.replace(PLACEHOLDER, (_, i) => stash[+i]);
+}
+
+/** 拼一个链接；目标协议不安全时返回 null，交由调用方原样保留。 */
+function anchor(dest, label, hold) {
+  const url = safeUrl(dest.split(/[ \t]/)[0]);
+  if (!url) return null;
+  return hold(`<a href="${url}">`) + (label || url) + hold("</a>");
+}
+
+/** 收集一段连续的列表行，返回 [html, 下一个未消费的行号]。 */
+function list(lines, start) {
+  const items = [];
+  let i = start;
+  while (i < lines.length) {
+    const m = lines[i].match(ITEM);
+    if (m) {
+      items.push({
+        indent: m[1].replace(/\t/g, "    ").length,
+        ordered: !!m[3],
+        start: m[3] ? Number(m[3]) : 0,
+        text: [m[4]],
+      });
+      i++;
+      continue;
+    }
+    if (!lines[i].trim()) {
+      // 列表项之间允许空行，空行之后不再是列表项才算结束。
+      if (lines[i + 1] && ITEM.test(lines[i + 1])) {
+        i++;
+        continue;
+      }
+      break;
+    }
+    if (items.length && /^[ \t]/.test(lines[i])) {
+      items[items.length - 1].text.push(lines[i].trim());
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  let html = "";
+  let pos = 0;
+  while (pos < items.length) {
+    const [chunk, next] = buildList(items, pos);
+    html += chunk;
+    pos = next;
+  }
+  return [html, i];
+}
+
+/** 把扁平的 items 按缩进还原成嵌套列表，返回 [html, 下一个未消费的下标]。 */
+function buildList(items, pos) {
+  const { indent, ordered, start } = items[pos];
+  const tag = ordered ? "ol" : "ul";
+  let html = ordered && start > 1 ? `<ol start="${start}">` : `<${tag}>`;
+  let i = pos;
+
+  while (i < items.length && items[i].indent >= indent) {
+    if (items[i].indent > indent) {
+      const [sub, next] = buildList(items, i);
+      // 子列表挂进上一个 <li> 内部。
+      html = html.endsWith("</li>") ? `${html.slice(0, -5)}${sub}</li>` : html + sub;
+      i = next;
+      continue;
+    }
+    if (items[i].ordered !== ordered) break; // 换了列表类型，交给上层另起一个
+    html += item(items[i]);
+    i++;
+  }
+  return [`${html}</${tag}>`, i];
+}
+
+function item(it) {
+  const task = it.text[0].match(TASK);
+  if (task) {
+    const rest = [it.text[0].slice(task[0].length), ...it.text.slice(1)];
+    const checked = task[1] === " " ? "" : " checked";
+    return `<li class="task"><input type="checkbox" disabled${checked}>${rest.map(inline).join("<br>")}</li>`;
+  }
+  return `<li>${it.text.map(inline).join("<br>")}</li>`;
+}
+
+function blocks(lines) {
+  const out = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (!line.trim()) {
+      i++;
+      continue;
+    }
+
+    const fence = line.match(FENCE);
+    if (fence) {
+      const close = fence[1][0].repeat(3);
+      const body = [];
+      i++;
+      while (i < lines.length && !lines[i].trim().startsWith(close)) body.push(lines[i++]);
+      i++; // 吃掉收尾栅栏；栅栏缺失时正好越界结束
+      out.push(`<pre><code>${escapeHtml(body.join("\n"))}</code></pre>`);
+      continue;
+    }
+
+    if (HR.test(line)) {
+      out.push("<hr>");
+      i++;
+      continue;
+    }
+
+    const h = line.match(HEADING);
+    if (h) {
+      out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`);
+      i++;
+      continue;
+    }
+
+    if (QUOTE.test(line)) {
+      const body = [];
+      while (i < lines.length && lines[i].trim()) {
+        const m = lines[i].match(QUOTE);
+        body.push(m ? m[1] : lines[i]); // 无 > 前缀的续行也算引用内容
+        i++;
+      }
+      out.push(`<blockquote>${blocks(body)}</blockquote>`);
+      continue;
+    }
+
+    if (ITEM.test(line)) {
+      const [html, next] = list(lines, i);
+      out.push(html);
+      i = next;
+      continue;
+    }
+
+    // 段落。软换行按 GitHub 评论的习惯渲染成 <br>，而不是并成一行。
+    const para = [];
+    while (i < lines.length && lines[i].trim() && !startsBlock(lines[i])) {
+      para.push(lines[i].trim());
+      i++;
+    }
+    out.push(`<p>${para.map(inline).join("<br>")}</p>`);
+  }
+
+  return out.join("");
+}
+
+/** 把 Markdown 源文本渲染成 HTML 字符串。 */
+export function renderMarkdown(source) {
+  if (!source) return "";
+  return blocks(String(source).replace(/\r\n?/g, "\n").split("\n"));
+}
diff --git a/apps/config/ui/src/lib/markdown.test.js b/apps/config/ui/src/lib/markdown.test.js
new file mode 100644
index 0000000..3a6bb41
--- /dev/null
+++ b/apps/config/ui/src/lib/markdown.test.js
@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import { renderMarkdown } from "./markdown.js";
+
+describe("renderMarkdown 块级", () => {
+  it("空输入返回空串", () => {
+    expect(renderMarkdown("")).toBe("");
+    expect(renderMarkdown(null)).toBe("");
+    expect(renderMarkdown(undefined)).toBe("");
+  });
+
+  it("标题按级数渲染", () => {
+    expect(renderMarkdown("# 大标题")).toBe("<h1>大标题</h1>");
+    expect(renderMarkdown("### 小标题")).toBe("<h3>小标题</h3>");
+    expect(renderMarkdown("####### 七个井号不是标题")).toBe("<p>####### 七个井号不是标题</p>");
+  });
+
+  it("段落内的软换行渲染成 <br>，空行分段", () => {
+    expect(renderMarkdown("第一行\n第二行\n\n另一段")).toBe("<p>第一行<br>第二行</p><p>另一段</p>");
+  });
+
+  it("分割线", () => {
+    expect(renderMarkdown("---")).toBe("<hr>");
+    expect(renderMarkdown("***")).toBe("<hr>");
+    expect(renderMarkdown("--")).toBe("<p>--</p>");
+  });
+
+  it("引用块内部继续解析", () => {
+    expect(renderMarkdown("> **重要**")).toBe("<blockquote><p><strong>重要</strong></p></blockquote>");
+  });
+
+  it("围栏代码块原样保留、不解析行内标记", () => {
+    expect(renderMarkdown("```js\nconst a = **1**;\n```")).toBe("<pre><code>const a = **1**;</code></pre>");
+  });
+
+  it("未闭合的围栏吃到结尾", () => {
+    expect(renderMarkdown("```\na\nb")).toBe("<pre><code>a\nb</code></pre>");
+  });
+});
+
+describe("renderMarkdown 列表", () => {
+  it("无序列表", () => {
+    expect(renderMarkdown("- 甲\n- 乙")).toBe("<ul><li>甲</li><li>乙</li></ul>");
+  });
+
+  it("有序列表，起始序号非 1 时带 start", () => {
+    expect(renderMarkdown("1. 甲\n2. 乙")).toBe("<ol><li>甲</li><li>乙</li></ol>");
+    expect(renderMarkdown("3. 丙")).toBe('<ol start="3"><li>丙</li></ol>');
+  });
+
+  it("缩进还原成嵌套列表", () => {
+    expect(renderMarkdown("- 甲\n  - 甲一\n- 乙")).toBe(
+      "<ul><li>甲<ul><li>甲一</li></ul></li><li>乙</li></ul>",
+    );
+  });
+
+  it("任务列表渲染成只读复选框", () => {
+    expect(renderMarkdown("- [x] 做完了\n- [ ] 还没做")).toBe(
+      '<ul><li class="task"><input type="checkbox" disabled checked>做完了</li>' +
+        '<li class="task"><input type="checkbox" disabled>还没做</li></ul>',
+    );
+  });
+
+  it("列表结束后回到段落", () => {
+    expect(renderMarkdown("- 甲\n\n收尾")).toBe("<ul><li>甲</li></ul><p>收尾</p>");
+  });
+});
+
+describe("renderMarkdown 行内", () => {
+  it("粗体、斜体、删除线、行内代码", () => {
+    expect(renderMarkdown("**粗** *斜* ~~删~~ `码`")).toBe(
+      "<p><strong>粗</strong> <em>斜</em> <del>删</del> <code>码</code></p>",
+    );
+  });
+
+  it("行内代码里的标记不再解析", () => {
+    expect(renderMarkdown("`**不是粗体**`")).toBe("<p><code>**不是粗体**</code></p>");
+  });
+
+  it("蛇形命名里的下划线不当成斜体", () => {
+    expect(renderMarkdown("some_var_name")).toBe("<p>some_var_name</p>");
+  });
+
+  it("链接与裸链接", () => {
+    expect(renderMarkdown("[官网](https://boss-key.ivan-hanloth.cn/)")).toBe(
+      '<p><a href="https://boss-key.ivan-hanloth.cn/">官网</a></p>',
+    );
+    expect(renderMarkdown("见 https://example.com 。")).toBe(
+      '<p>见 <a href="https://example.com">https://example.com</a> 。</p>',
+    );
+  });
+
+  it("裸链接不吞掉句末标点", () => {
+    expect(renderMarkdown("见 https://example.com.")).toBe(
+      '<p>见 <a href="https://example.com">https://example.com</a>.</p>',
+    );
+  });
+
+  it("图片退化成链接（CSP 不允许远端图源）", () => {
+    expect(renderMarkdown("![截图](https://example.com/a.png)")).toBe(
+      '<p><a href="https://example.com/a.png">截图</a></p>',
+    );
+  });
+});
+
+describe("renderMarkdown 安全", () => {
+  it("原始 HTML 一律转义", () => {
+    expect(renderMarkdown("<script>alert(1)</script>")).toBe(
+      "<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>",
+    );
+    expect(renderMarkdown('<img src=x onerror="alert(1)">')).toBe(
+      "<p>&lt;img src=x onerror=&quot;alert(1)&quot;&gt;</p>",
+    );
+  });
+
+  it("非 http/mailto 协议的链接不生成 <a>", () => {
+    expect(renderMarkdown("[点我](javascript:alert(1))")).toBe("<p>[点我](javascript:alert(1))</p>");
+    expect(renderMarkdown("[点我](data:text/html,<script>)")).toContain("[点我](data:text/html,");
+  });
+
+  it("链接目标里的引号被转义，无法逃出属性", () => {
+    // 目标在第一个右括号处截断（不做括号配对），多出来的括号留在正文里。
+    expect(renderMarkdown('[x](https://a.com/"onmouseover="alert(1))')).toBe(
+      '<p><a href="https://a.com/&quot;onmouseover=&quot;alert(1">x</a>)</p>',
+    );
+  });
+
+  it("代码块内容同样转义", () => {
+    expect(renderMarkdown("```\n<b>x</b>\n```")).toBe("<pre><code>&lt;b&gt;x&lt;/b&gt;</code></pre>");
+  });
+});
diff --git a/docs/dev/frontend.md b/docs/dev/frontend.md
index 948e207..af2938a 100644
--- a/docs/dev/frontend.md
+++ b/docs/dev/frontend.md
@@ -30,6 +30,7 @@ apps/config/ui/
 │       ├── grouping.js      窗口/进程规则的增删与过滤（配 grouping.test.js）
 │       ├── theme.js         主题切换（配 theme.test.js）
 │       ├── i18n.svelte.js   界面语言：catalog 查表 + 语言解析（配 i18n.test.js）
+│       ├── markdown.js      公告/更新日志的 Markdown 渲染（配 markdown.test.js）
 │       └── verhub.js        检查更新/公告/打开外链
 ├── locales/                 三语文案 catalog（zh-CN.js / en.js / zh-TW.js）
 ├── vite.config.js
@@ -82,6 +83,21 @@ t("restore.frozen", { n: 3 });        // → 已冻结 3 个进程
 `grouping.js` 的 `NO_TITLE`（`"无标题窗口"`）与核心 `bosskey_common::NO_TITLE` 一致，是写进 `config.json` 的跨进程哨兵值，**不可翻译**；仅在展示时用 `t("common.noTitleWindow")` 换成当前语言。
 :::
 
+## 公告与更新日志的 Markdown 渲染
+
+公告（列表与启动弹窗）与更新日志的正文按 Markdown 渲染，由 `lib/markdown.js`（纯函数，配 `markdown.test.js`）与 `components/Markdown.svelte`（样式 + 链接拦截）承担，不引入第三方依赖。
+
+支持 GitHub 风格的常用子集：标题、粗体 / 斜体 / 删除线、行内代码与围栏代码块、有序 / 无序 / 任务列表（含缩进嵌套）、引用、分割线、链接与裸链接。段落内的软换行渲染成 `<br>`，与 GitHub 评论一致。**不支持**表格、脚注、行内 HTML 与语法高亮。
+
+::: warning 正文来自远端，渲染前必须转义
+Verhub 返回的内容不可信。`renderMarkdown()` 先整体转义 `& < > "` 再拼标签，输出里出现的标签全部由渲染器自己生成，源文本中的 HTML 只会作为字面量显示；链接目标仅放行 `http(s)` 与 `mailto`，其余（`javascript:`、`data:` 等）按纯文本保留。改动该模块时勿绕过这两条。
+:::
+
+另有两处与运行环境相关的取舍：
+
+- **图片退化成链接**：Tauri 的 CSP 中 `img-src` 只允许 `self` 与 `data:`，远端图片加载不出来，因此 `![]()` 一律渲染为链接。
+- **链接不走 webview 导航**：`Markdown.svelte` 拦截点击并转交 `open_external`，由系统浏览器打开——webview 真导航走了就回不到配置界面。
+
 ## 状态轮询不卡界面
 
 - 状态获取合并为**单条 `GetStatus`** 管道命令，并使用**连接快速失败**（不重试）。
diff --git a/docs/en/dev/frontend.md b/docs/en/dev/frontend.md
index 17e7cce..c7b1e2b 100644
--- a/docs/en/dev/frontend.md
+++ b/docs/en/dev/frontend.md
@@ -30,6 +30,7 @@ apps/config/ui/
 │       ├── grouping.js      Adding, removing and filtering window/process rules (with grouping.test.js)
 │       ├── theme.js         Theme switching (with theme.test.js)
 │       ├── i18n.svelte.js   Display language: catalog lookup + language resolution (with i18n.test.js)
+│       ├── markdown.js      Markdown rendering for announcements/release notes (with markdown.test.js)
 │       └── verhub.js        Update checks / announcements / opening external links
 ├── locales/                 Three-language catalogs (zh-CN.js / en.js / zh-TW.js)
 ├── vite.config.js
@@ -82,6 +83,21 @@ t("restore.frozen", { n: 3 });        // → Froze 3 processes
 `grouping.js`'s `NO_TITLE` (`"无标题窗口"`) matches the core's `bosskey_common::NO_TITLE`. It is a cross-process sentinel written into `config.json` and **must not be translated**; only the display swaps it for the current language via `t("common.noTitleWindow")`.
 :::
 
+## Markdown in announcements and release notes
+
+The body text of announcements (both the list and the startup dialog) and of release notes is rendered as Markdown by `lib/markdown.js` (a pure function, with `markdown.test.js`) and `components/Markdown.svelte` (styling + link interception). No third-party dependency is involved.
+
+The supported subset covers the common GitHub-flavoured constructs: headings, bold / italic / strikethrough, inline code and fenced code blocks, ordered / unordered / task lists (nesting by indentation), blockquotes, horizontal rules, links and bare URLs. Soft line breaks inside a paragraph become `<br>`, as they do in GitHub comments. Tables, footnotes, inline HTML and syntax highlighting are **not** supported.
+
+::: warning The body comes from a remote server and must be escaped first
+Content returned by Verhub is untrusted. `renderMarkdown()` escapes `& < > "` across the whole input before assembling any tags, so every tag in the output is produced by the renderer itself and HTML in the source is only ever displayed literally; link targets are restricted to `http(s)` and `mailto`, and anything else (`javascript:`, `data:`, …) is kept as plain text. Do not work around either rule when changing this module.
+:::
+
+Two further trade-offs follow from the runtime environment:
+
+- **Images degrade to links.** Tauri's CSP allows only `self` and `data:` for `img-src`, so remote images cannot load and `![]()` is always rendered as a link.
+- **Links do not navigate the webview.** `Markdown.svelte` intercepts the click and hands the URL to `open_external` for the system browser — once the webview really navigates away, there is no way back to the settings window.
+
 ## Status polling without blocking the UI
 
 - Status retrieval is merged into a **single `GetStatus`** pipe command and uses **fail-fast connections** (no retries).
diff --git a/docs/zh-tw/dev/frontend.md b/docs/zh-tw/dev/frontend.md
index 8a523ed..1c9ee78 100644
--- a/docs/zh-tw/dev/frontend.md
+++ b/docs/zh-tw/dev/frontend.md
@@ -30,6 +30,7 @@ apps/config/ui/
 │       ├── grouping.js      視窗/程序規則的增刪與篩選（配 grouping.test.js）
 │       ├── theme.js         佈景主題切換（配 theme.test.js）
 │       ├── i18n.svelte.js   介面語言：catalog 查表 + 語言解析（配 i18n.test.js）
+│       ├── markdown.js      公告/更新記錄的 Markdown 算繪（配 markdown.test.js）
 │       └── verhub.js        檢查更新/公告/開啟外部連結
 ├── locales/                 三語文案 catalog（zh-CN.js / en.js / zh-TW.js）
 ├── vite.config.js
@@ -82,6 +83,21 @@ t("restore.frozen", { n: 3 });        // → 已凍結 3 個程序
 `grouping.js` 的 `NO_TITLE`（`"无标题窗口"`）與核心 `bosskey_common::NO_TITLE` 一致，是寫進 `config.json` 的跨程序哨兵值，**不可翻譯**；僅在顯示時用 `t("common.noTitleWindow")` 換成目前語言。
 :::
 
+## 公告與更新記錄的 Markdown 算繪
+
+公告（清單與啟動對話方塊）與更新記錄的內文按 Markdown 算繪，由 `lib/markdown.js`（純函式，配 `markdown.test.js`）與 `components/Markdown.svelte`（樣式 + 連結攔截）承擔，不引入第三方相依套件。
+
+支援 GitHub 風格的常用子集：標題、粗體／斜體／刪除線、行內程式碼與圍籬程式碼區塊、有序／無序／工作清單（含縮排巢狀）、引用、分隔線、連結與裸連結。段落內的軟換行算繪成 `<br>`，與 GitHub 留言一致。**不支援**表格、註腳、行內 HTML 與語法醒目提示。
+
+::: warning 內文來自遠端，算繪前必須逸出
+Verhub 回傳的內容不可信。`renderMarkdown()` 先整體逸出 `& < > "` 再組標籤，輸出裡出現的標籤全部由算繪器自己產生，原始文字中的 HTML 只會作為字面值顯示；連結目標僅放行 `http(s)` 與 `mailto`，其餘（`javascript:`、`data:` 等）按純文字保留。改動該模組時勿繞過這兩條。
+:::
+
+另有兩處與執行環境相關的取捨：
+
+- **圖片退化成連結**：Tauri 的 CSP 中 `img-src` 只允許 `self` 與 `data:`，遠端圖片載入不了，因此 `![]()` 一律算繪為連結。
+- **連結不走 webview 導覽**：`Markdown.svelte` 攔截點擊並轉交 `open_external`，由系統瀏覽器開啟——webview 真的導覽走了就回不到設定介面。
+
 ## 狀態輪詢不卡介面
 
 - 狀態取得合併為**單一 `GetStatus`** 管道命令，並使用**連線快速失敗**（不重試）。

From b87fb53dc2243d0a442a596a1df0fcadced74925 Mon Sep 17 00:00:00 2001
From: Ivan Hanloth <ivan@hanloth.com>
Date: Fri, 24 Jul 2026 23:50:13 +0100
Subject: [PATCH 3/4] =?UTF-8?q?feat:=20=E5=85=81=E8=AE=B8mailto=E5=8D=8F?=
 =?UTF-8?q?=E8=AE=AE=EF=BC=8C=E6=94=B9=E7=94=A8verhub=20SDK=E5=AF=B9?=
 =?UTF-8?q?=E6=8E=A5=E7=89=88=E6=9C=AC=E7=9B=B8=E5=85=B3=E6=9C=8D=E5=8A=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Cargo.lock                          | 395 +++++++++++++++++-----------
 Cargo.toml                          |   2 +-
 apps/config/src-tauri/Cargo.toml    |   1 +
 apps/config/src-tauri/src/lib.rs    |  58 ++--
 apps/config/src-tauri/src/verhub.rs | 235 +++++++++++++++++
 crates/common/Cargo.toml            |   1 -
 crates/common/src/lib.rs            |   1 -
 crates/common/src/verhub.rs         | 318 ----------------------
 crates/core/src/i18n.rs             |   6 +-
 docs/dev/architecture.md            |   4 +-
 docs/en/dev/architecture.md         |   4 +-
 docs/zh-tw/dev/architecture.md      |   4 +-
 12 files changed, 518 insertions(+), 511 deletions(-)
 create mode 100644 apps/config/src-tauri/src/verhub.rs
 delete mode 100644 crates/common/src/verhub.rs

diff --git a/Cargo.lock b/Cargo.lock
index 88aa831..962f2dc 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -295,7 +295,6 @@ dependencies = [
  "serde_json",
  "tempfile",
  "thiserror 2.0.18",
- "ureq",
 ]
 
 [[package]]
@@ -309,6 +308,7 @@ dependencies = [
  "tauri",
  "tauri-build",
  "tauri-plugin-single-instance",
+ "verhub-sdk",
 ]
 
 [[package]]
@@ -491,6 +491,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
 [[package]]
 name = "chrono"
 version = "0.4.45"
@@ -528,29 +534,10 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4ddef33a339a91ea89fb53151bd0a4689cfce27055c291dfa69945475d22c747"
 dependencies = [
- "percent-encoding",
  "time",
  "version_check",
 ]
 
-[[package]]
-name = "cookie_store"
-version = "0.22.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206"
-dependencies = [
- "cookie",
- "document-features",
- "idna",
- "indexmap 2.14.0",
- "log",
- "serde",
- "serde_derive",
- "serde_json",
- "time",
- "url",
-]
-
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
@@ -576,7 +563,7 @@ dependencies = [
  "bitflags 2.13.0",
  "core-foundation",
  "core-graphics-types",
- "foreign-types",
+ "foreign-types 0.5.0",
  "libc",
 ]
 
@@ -825,15 +812,6 @@ dependencies = [
  "syn 2.0.118",
 ]
 
-[[package]]
-name = "document-features"
-version = "0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
-dependencies = [
- "litrs",
-]
-
 [[package]]
 name = "dom_query"
 version = "0.27.0"
@@ -1048,6 +1026,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
+[[package]]
+name = "foreign-types"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1"
+dependencies = [
+ "foreign-types-shared 0.1.1",
+]
+
 [[package]]
 name = "foreign-types"
 version = "0.5.0"
@@ -1055,7 +1042,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
 dependencies = [
  "foreign-types-macros",
- "foreign-types-shared",
+ "foreign-types-shared 0.3.1",
 ]
 
 [[package]]
@@ -1069,6 +1056,12 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "foreign-types-shared"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b"
+
 [[package]]
 name = "foreign-types-shared"
 version = "0.3.1"
@@ -1564,6 +1557,22 @@ dependencies = [
  "want",
 ]
 
+[[package]]
+name = "hyper-tls"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0"
+dependencies = [
+ "bytes",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "native-tls",
+ "tokio",
+ "tokio-native-tls",
+ "tower-service",
+]
+
 [[package]]
 name = "hyper-util"
 version = "0.1.20"
@@ -1955,12 +1964,6 @@ version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
 
-[[package]]
-name = "litrs"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
-
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -2050,6 +2053,23 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "native-tls"
+version = "0.2.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2"
+dependencies = [
+ "libc",
+ "log",
+ "openssl",
+ "openssl-probe",
+ "openssl-sys",
+ "schannel",
+ "security-framework",
+ "security-framework-sys",
+ "tempfile",
+]
+
 [[package]]
 name = "ndk"
 version = "0.9.0"
@@ -2080,6 +2100,18 @@ version = "1.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
 
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags 2.13.0",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
 [[package]]
 name = "num-conv"
 version = "0.2.2"
@@ -2111,7 +2143,7 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
 dependencies = [
- "proc-macro-crate 1.3.1",
+ "proc-macro-crate 3.5.0",
  "proc-macro2",
  "quote",
  "syn 2.0.118",
@@ -2240,6 +2272,7 @@ checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
 dependencies = [
  "bitflags 2.13.0",
  "block2",
+ "libc",
  "objc2",
  "objc2-core-foundation",
 ]
@@ -2318,6 +2351,49 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "openssl"
+version = "0.10.81"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77823a27f0babb03091cb9ed9ef80af3b39dbc82f97e8fa530374b7dafd87a45"
+dependencies = [
+ "bitflags 2.13.0",
+ "cfg-if",
+ "foreign-types 0.3.2",
+ "libc",
+ "openssl-macros",
+ "openssl-sys",
+]
+
+[[package]]
+name = "openssl-macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "openssl-probe"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
+
+[[package]]
+name = "openssl-sys"
+version = "0.9.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b47e7e6bb2c38cd930d25a23b40fa52e068c10e85f3e03a7f5ba5aaca5713695"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "option-ext"
 version = "0.2.0"
@@ -2334,6 +2410,21 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "os_info"
+version = "3.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9cf20a545b305cf1da722b236b5155c9bb35f1d5ceb28c048bd96ca842f41b5b"
+dependencies = [
+ "android_system_properties",
+ "log",
+ "nix",
+ "objc2",
+ "objc2-foundation",
+ "objc2-ui-kit",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "pango"
 version = "0.18.3"
@@ -2713,50 +2804,72 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "reqwest"
-version = "0.13.4"
+version = "0.12.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
+checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
 dependencies = [
  "base64 0.22.1",
  "bytes",
  "futures-core",
- "futures-util",
  "http",
  "http-body",
  "http-body-util",
  "hyper",
+ "hyper-tls",
  "hyper-util",
  "js-sys",
  "log",
+ "native-tls",
  "percent-encoding",
  "pin-project-lite",
+ "rustls-pki-types",
  "serde",
  "serde_json",
+ "serde_urlencoded",
  "sync_wrapper",
  "tokio",
- "tokio-util",
+ "tokio-native-tls",
  "tower",
  "tower-http",
  "tower-service",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
- "wasm-streams",
  "web-sys",
 ]
 
 [[package]]
-name = "ring"
-version = "0.17.14"
+name = "reqwest"
+version = "0.13.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
 dependencies = [
- "cc",
- "cfg-if",
- "getrandom 0.2.17",
- "libc",
- "untrusted",
- "windows-sys 0.52.0",
+ "base64 0.22.1",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde",
+ "serde_json",
+ "sync_wrapper",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams",
+ "web-sys",
 ]
 
 [[package]]
@@ -2787,21 +2900,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "rustls"
-version = "0.23.42"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
-dependencies = [
- "log",
- "once_cell",
- "ring",
- "rustls-pki-types",
- "rustls-webpki",
- "subtle",
- "zeroize",
-]
-
 [[package]]
 name = "rustls-pki-types"
 version = "1.15.0"
@@ -2812,21 +2910,16 @@ dependencies = [
 ]
 
 [[package]]
-name = "rustls-webpki"
-version = "0.103.13"
+name = "rustversion"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
-dependencies = [
- "ring",
- "rustls-pki-types",
- "untrusted",
-]
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
-name = "rustversion"
+name = "ryu"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
 [[package]]
 name = "same-file"
@@ -2837,6 +2930,15 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "schannel"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "schemars"
 version = "0.8.22"
@@ -2894,6 +2996,29 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags 2.13.0",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "selectors"
 version = "0.36.1"
@@ -3018,6 +3143,18 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "serde_urlencoded"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"
+dependencies = [
+ "form_urlencoded",
+ "itoa",
+ "ryu",
+ "serde",
+]
+
 [[package]]
 name = "serde_with"
 version = "3.21.0"
@@ -3226,12 +3363,6 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
-[[package]]
-name = "subtle"
-version = "2.6.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
-
 [[package]]
 name = "swift-rs"
 version = "1.0.7"
@@ -3384,7 +3515,7 @@ dependencies = [
  "percent-encoding",
  "plist",
  "raw-window-handle",
- "reqwest",
+ "reqwest 0.13.4",
  "serde",
  "serde_json",
  "serde_repr",
@@ -3713,6 +3844,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "tokio-native-tls"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2"
+dependencies = [
+ "native-tls",
+ "tokio",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -3941,7 +4082,7 @@ dependencies = [
  "png 0.18.1",
  "serde",
  "thiserror 2.0.18",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4026,44 +4167,6 @@ version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
-[[package]]
-name = "untrusted"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
-
-[[package]]
-name = "ureq"
-version = "3.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dea7109cdcd5864d4eeb1b58a1648dc9bf520360d7af16ec26d0a9354bafcfc0"
-dependencies = [
- "base64 0.22.1",
- "cookie_store",
- "flate2",
- "log",
- "percent-encoding",
- "rustls",
- "rustls-pki-types",
- "serde",
- "serde_json",
- "ureq-proto",
- "utf8-zero",
- "webpki-roots",
-]
-
-[[package]]
-name = "ureq-proto"
-version = "0.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e994ba84b0bd1b1b0cf92878b7ef898a5c1760108fe7b6010327e274917a808c"
-dependencies = [
- "base64 0.22.1",
- "http",
- "httparse",
- "log",
-]
-
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -4089,12 +4192,6 @@ dependencies = [
  "url",
 ]
 
-[[package]]
-name = "utf8-zero"
-version = "0.8.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8c0a043c9540bae7c578c88f91dda8bd82e59ae27c21baca69c8b191aaf5a6e"
-
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -4113,6 +4210,28 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
+[[package]]
+name = "verhub-sdk"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61704ff45c9dd4e311e21b254be2405e8e3c9a81a5c1ad0ef8e8bb123fe65115"
+dependencies = [
+ "log",
+ "os_info",
+ "percent-encoding",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+]
+
 [[package]]
 name = "version-compare"
 version = "0.2.1"
@@ -4313,15 +4432,6 @@ dependencies = [
  "system-deps",
 ]
 
-[[package]]
-name = "webpki-roots"
-version = "1.0.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
-dependencies = [
- "rustls-pki-types",
-]
-
 [[package]]
 name = "webview2-com"
 version = "0.38.2"
@@ -4594,15 +4704,6 @@ dependencies = [
  "windows-targets 0.42.2",
 ]
 
-[[package]]
-name = "windows-sys"
-version = "0.52.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.59.0"
diff --git a/Cargo.toml b/Cargo.toml
index 437eb12..cdfa8d3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -17,7 +17,7 @@ regex = "1.11.1"
 tokio = { version = "1.52.3", features = ["rt-multi-thread", "macros", "net", "io-util", "sync", "time"] }
 windows = "0.62.2"
 tempfile = "3.27.0"
-ureq = { version = "3.1.2", default-features = false, features = ["json", "rustls", "gzip"] }
+verhub-sdk = { version = "0.2.5", default-features = false, features = ["native-tls"] }
 
 [profile.release]
 opt-level = "z"
diff --git a/apps/config/src-tauri/Cargo.toml b/apps/config/src-tauri/Cargo.toml
index 7b5bd84..6069384 100644
--- a/apps/config/src-tauri/Cargo.toml
+++ b/apps/config/src-tauri/Cargo.toml
@@ -20,3 +20,4 @@ serde_json = { workspace = true }
 bosskey-common = { path = "../../../crates/common" }
 bosskey-core = { path = "../../../crates/core" }
 tauri-plugin-single-instance = "2.4.2"
+verhub-sdk = { workspace = true }
diff --git a/apps/config/src-tauri/src/lib.rs b/apps/config/src-tauri/src/lib.rs
index 3f40c32..f8116fc 100644
--- a/apps/config/src-tauri/src/lib.rs
+++ b/apps/config/src-tauri/src/lib.rs
@@ -4,11 +4,12 @@ use std::time::Duration;
 use bosskey_common::Config;
 use bosskey_common::ipc::{Command, PipeClient, Response};
 use bosskey_common::model::WindowInfo;
-use bosskey_common::verhub;
 use bosskey_core::i18n::{self, Msg};
 use serde::Serialize;
 use tauri::{Emitter, Manager};
 
+mod verhub;
+
 const CORE_EXE: &str = "Boss Key.exe";
 
 fn exe_dir() -> PathBuf {
@@ -387,10 +388,10 @@ fn app_info() -> AppInfo {
     }
 }
 
-/// 用系统默认浏览器打开外部链接。仅放行 http/https。
+/// 用系统默认浏览器打开外部链接。仅放行 http/https/mailto（与前端 markdown 白名单一致）。
 #[tauri::command]
 async fn open_external(url: String) -> Result<(), String> {
-    if !url.starts_with("https://") && !url.starts_with("http://") {
+    if !url.starts_with("https://") && !url.starts_with("http://") && !url.starts_with("mailto:") {
         return Err(i18n::t(Msg::ErrUrlSchemeNotAllowed).to_string());
     }
     blocking(move || bosskey_core::shell::open(&url)).await
@@ -399,16 +400,17 @@ async fn open_external(url: String) -> Result<(), String> {
 /// 检查更新。`required=true` 即强制更新，界面须阻断使用。
 #[tauri::command]
 async fn verhub_check_update(include_preview: bool) -> Result<verhub::CheckUpdate, String> {
-    blocking(move || {
-        verhub::check_update(env!("CARGO_PKG_VERSION"), include_preview).map_err(|e| e.to_string())
-    })
-    .await
+    verhub::check_update(env!("CARGO_PKG_VERSION"), include_preview)
+        .await
+        .map_err(|e| e.to_string())
 }
 
 /// 公告列表（本平台可见的，从新到旧）。
 #[tauri::command]
 async fn verhub_announcements(limit: u32) -> Result<Vec<verhub::Announcement>, String> {
-    blocking(move || verhub::announcements(limit.clamp(1, 50)).map_err(|e| e.to_string())).await
+    verhub::announcements(limit.clamp(1, 50))
+        .await
+        .map_err(|e| e.to_string())
 }
 
 /// `contact` 可空——留了才好回复用户。
@@ -421,38 +423,26 @@ async fn verhub_submit_feedback(
     if content.trim().is_empty() {
         return Err(i18n::t(Msg::ErrFeedbackEmpty).to_string());
     }
-    blocking(move || {
-        let feedback = verhub::Feedback {
-            rating: rating.map(|r| r.clamp(1, 5)),
-            content,
-            platform: verhub::PLATFORM,
-            custom_data: serde_json::json!({
-                "app_version": env!("CARGO_PKG_VERSION"),
-                "os": os_description(),
-                "contact": contact.trim(),
-            }),
-        };
-        verhub::submit_feedback(&feedback).map_err(|e| e.to_string())
-    })
-    .await
+    let custom_data = serde_json::json!({
+        "app_version": env!("CARGO_PKG_VERSION"),
+        "os": os_description(),
+        "contact": contact.trim(),
+    });
+    verhub::submit_feedback(content, rating.map(|r| r.clamp(1, 5)), custom_data)
+        .await
+        .map_err(|e| e.to_string())
 }
 
 /// 上报一段日志
 #[tauri::command]
 async fn verhub_upload_log(content: String) -> Result<(), String> {
-    blocking(move || {
-        verhub::upload_log(
-            verhub::LogLevel::Error,
-            &content,
-            serde_json::json!({
-                "app_version": env!("CARGO_PKG_VERSION"),
-                "os": os_description(),
-
-            }),
-        )
+    let device_info = serde_json::json!({
+        "app_version": env!("CARGO_PKG_VERSION"),
+        "os": os_description(),
+    });
+    verhub::upload_log(&content, device_info)
+        .await
         .map_err(|e| e.to_string())
-    })
-    .await
 }
 
 /// 最新日志文件的末尾若干行。
diff --git a/apps/config/src-tauri/src/verhub.rs b/apps/config/src-tauri/src/verhub.rs
new file mode 100644
index 0000000..5f8e9b2
--- /dev/null
+++ b/apps/config/src-tauri/src/verhub.rs
@@ -0,0 +1,235 @@
+//! Verhub 客户端：版本 / 公告 / 反馈 / 日志，基于官方 verhub-sdk。
+//!
+//! 只用公开端点（无需凭据）。HTTP 由 SDK 完成；本模块把 SDK 的响应类型映射成
+//! 前端 IPC 契约所需的可序列化 DTO，字段名保持不变。
+
+use std::time::Duration;
+
+use serde::Serialize;
+use verhub_sdk::VerhubClient;
+use verhub_sdk::models::{
+    AnnouncementItem, CheckUpdateInput, CreateFeedbackInput, JsonObject, ListAnnouncementsOptions,
+    LogLevel, Platform, UploadLogInput, VersionDownloadLink, VersionItem,
+};
+
+/// Verhub 基础路径。
+pub const BASE_URL: &str = "https://verhub.hanloth.cn/api/v1";
+pub const PROJECT_KEY: &str = "ivanhanloth-boss-key";
+/// 客户端平台（本程序只发行 Windows 版）。
+pub const PLATFORM: Platform = Platform::Windows;
+
+const TIMEOUT: Duration = Duration::from_secs(10);
+const LOG_CONTENT_MAX: usize = 4096;
+
+type Result<T> = verhub_sdk::Result<T>;
+
+/// 构造公开接口客户端；User-Agent 追加 `BossKey/{版本}` 以便服务端识别。
+fn client() -> Result<VerhubClient> {
+    VerhubClient::builder(BASE_URL)
+        .project_key(PROJECT_KEY)
+        .platform(PLATFORM)
+        .timeout(TIMEOUT)
+        .app_identifier(concat!("BossKey/", env!("CARGO_PKG_VERSION")))
+        .build()
+}
+
+/// 把 `serde_json::Value` 收敛为 JSON 对象；非对象一律丢弃。
+fn json_object(value: serde_json::Value) -> Option<JsonObject> {
+    match value {
+        serde_json::Value::Object(map) => Some(map),
+        _ => None,
+    }
+}
+
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct DownloadLink {
+    pub url: String,
+    pub name: Option<String>,
+    pub platform: Option<String>,
+}
+
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct Version {
+    pub id: String,
+    pub version: String,
+    pub comparable_version: String,
+    pub title: Option<String>,
+    /// 更新说明（Markdown）。
+    pub content: Option<String>,
+    pub download_url: Option<String>,
+    pub download_links: Vec<DownloadLink>,
+    pub forced: bool,
+    pub is_latest: bool,
+    pub is_preview: bool,
+    pub is_milestone: bool,
+    pub is_deprecated: bool,
+    pub published_at: i64,
+}
+
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct CheckUpdate {
+    pub should_update: bool,
+    /// 强制更新。
+    pub required: bool,
+    pub reason_codes: Vec<String>,
+    pub current_version: Option<String>,
+    pub latest_version: Option<Version>,
+    /// 该升到哪个版本（可能是里程碑版本，而非最新版）。
+    pub target_version: Option<Version>,
+}
+
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct Announcement {
+    pub id: String,
+    pub title: String,
+    pub content: String,
+    pub is_pinned: bool,
+    pub is_hidden: bool,
+    pub author: Option<String>,
+    pub published_at: i64,
+}
+
+fn map_link(link: VersionDownloadLink) -> DownloadLink {
+    DownloadLink {
+        url: link.url,
+        name: link.name,
+        platform: link.platform,
+    }
+}
+
+fn map_version(version: VersionItem) -> Version {
+    Version {
+        id: version.id,
+        version: version.version,
+        comparable_version: version.comparable_version,
+        title: version.title,
+        content: version.content,
+        download_url: version.download_url,
+        download_links: version.download_links.into_iter().map(map_link).collect(),
+        forced: version.forced,
+        is_latest: version.is_latest,
+        is_preview: version.is_preview,
+        is_milestone: version.is_milestone,
+        is_deprecated: version.is_deprecated,
+        published_at: version.published_at,
+    }
+}
+
+fn map_announcement(item: AnnouncementItem) -> Announcement {
+    Announcement {
+        id: item.id,
+        title: item.title,
+        content: item.content,
+        is_pinned: item.is_pinned,
+        is_hidden: item.is_hidden,
+        author: item.author,
+        published_at: item.published_at,
+    }
+}
+
+/// 检查更新：把当前版本发给 Verhub，由服务端判断是否需要更新、是否强制。
+pub async fn check_update(current_version: &str, include_preview: bool) -> Result<CheckUpdate> {
+    let input = CheckUpdateInput {
+        current_version: Some(current_version.to_string()),
+        current_comparable_version: Some(current_version.to_string()),
+        include_preview: Some(include_preview),
+    };
+    let resp = client()?.public().check_update(&input).await?;
+    Ok(CheckUpdate {
+        should_update: resp.should_update,
+        required: resp.required,
+        reason_codes: resp.reason_codes,
+        current_version: resp.current_version,
+        latest_version: Some(map_version(resp.latest_version)),
+        target_version: resp.target_version.map(map_version),
+    })
+}
+
+/// 公告列表（只要本平台 / 全平台的），从新到旧，并滤掉隐藏公告。
+pub async fn announcements(limit: u32) -> Result<Vec<Announcement>> {
+    let options = ListAnnouncementsOptions {
+        limit: Some(limit),
+        platform: Some(PLATFORM),
+        ..Default::default()
+    };
+    let resp = client()?.public().list_announcements(&options).await?;
+    Ok(resp
+        .data
+        .into_iter()
+        .filter(|a| !a.is_hidden)
+        .map(map_announcement)
+        .collect())
+}
+
+/// 提交客户端反馈。`rating` 为 1..=5；`custom_data` 携带附加信息。
+pub async fn submit_feedback(
+    content: String,
+    rating: Option<u8>,
+    custom_data: serde_json::Value,
+) -> Result<()> {
+    let input = CreateFeedbackInput {
+        content,
+        rating,
+        platform: Some(PLATFORM),
+        custom_data: json_object(custom_data),
+        ..Default::default()
+    };
+    client()?.public().create_feedback(&input).await?;
+    Ok(())
+}
+
+/// 上报一条错误日志；内容超长会被截断到 Verhub 的上限内。
+pub async fn upload_log(content: &str, device_info: serde_json::Value) -> Result<()> {
+    let input = UploadLogInput {
+        level: LogLevel::Error.into(),
+        content: truncate_log(content),
+        device_info: json_object(device_info),
+        custom_data: None,
+    };
+    client()?.public().upload_log(&input).await?;
+    Ok(())
+}
+
+/// 截到上限以内，按字符边界切以避免切碎多字节字符。
+fn truncate_log(content: &str) -> String {
+    if content.len() <= LOG_CONTENT_MAX {
+        return content.to_string();
+    }
+    const MARK: &str = "…（日志过长，已截断前半部分）\n";
+    let budget = LOG_CONTENT_MAX - MARK.len();
+    // 保留末尾（出错现场）。
+    let start = content.len() - budget;
+    let start = (start..content.len())
+        .find(|i| content.is_char_boundary(*i))
+        .unwrap_or(content.len());
+    format!("{MARK}{}", &content[start..])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn truncate_keeps_tail_within_limit() {
+        let long = "错误".repeat(4000); // 远超 4096 字节
+        let out = truncate_log(&long);
+        assert!(
+            out.len() <= LOG_CONTENT_MAX,
+            "截断后仍超上限: {}",
+            out.len()
+        );
+        assert!(out.contains("已截断"));
+        assert!(out.ends_with('误')); // 保的是末尾（出错现场）
+    }
+
+    #[test]
+    fn truncate_leaves_short_content_alone() {
+        assert_eq!(truncate_log("崩了"), "崩了");
+    }
+
+    #[test]
+    fn log_level_maps_to_verhub_numbers() {
+        assert_eq!(u8::from(LogLevel::Debug), 0);
+        assert_eq!(u8::from(LogLevel::Error), 3);
+    }
+}
diff --git a/crates/common/Cargo.toml b/crates/common/Cargo.toml
index 6f531ad..0e2a4a7 100644
--- a/crates/common/Cargo.toml
+++ b/crates/common/Cargo.toml
@@ -11,7 +11,6 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 regex = { workspace = true }
-ureq = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }
diff --git a/crates/common/src/lib.rs b/crates/common/src/lib.rs
index 4ee710b..d6e44a4 100644
--- a/crates/common/src/lib.rs
+++ b/crates/common/src/lib.rs
@@ -3,7 +3,6 @@ pub mod i18n;
 pub mod ipc;
 pub mod matching;
 pub mod model;
-pub mod verhub;
 
 pub use config::{
     Config, ConfigError, Hotkey, MouseButton, MouseSetting, Notifications, Setting, Verhub,
diff --git a/crates/common/src/verhub.rs b/crates/common/src/verhub.rs
deleted file mode 100644
index 9091bf6..0000000
--- a/crates/common/src/verhub.rs
+++ /dev/null
@@ -1,318 +0,0 @@
-//! Verhub 客户端：版本 / 公告 / 反馈 / 日志。
-//!
-//! 只使用公开端点（`/public/{projectKey}/…`），不需要令牌。字段一律 `#[serde(default)]`。
-
-use std::time::Duration;
-
-use serde::{Deserialize, Serialize};
-
-/// Verhub 基础路径。
-pub const BASE_URL: &str = "https://verhub.hanloth.cn/api/v1";
-pub const PROJECT_KEY: &str = "ivanhanloth-boss-key";
-/// 客户端平台（本程序只发行 Windows 版）。
-pub const PLATFORM: &str = "windows";
-
-const TIMEOUT: Duration = Duration::from_secs(10);
-
-#[derive(Debug, thiserror::Error)]
-pub enum VerhubError {
-    #[error("网络请求失败: {0}")]
-    Http(String),
-    #[error("Verhub 返回 {status}: {message}")]
-    Api { status: u16, message: String },
-    #[error("响应解析失败: {0}")]
-    Decode(String),
-}
-
-type Result<T> = std::result::Result<T, VerhubError>;
-
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct DownloadLink {
-    pub url: String,
-    #[serde(default)]
-    pub name: Option<String>,
-    #[serde(default)]
-    pub platform: Option<String>,
-}
-
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct Version {
-    #[serde(default)]
-    pub id: String,
-    #[serde(default)]
-    pub version: String,
-    #[serde(default)]
-    pub comparable_version: String,
-    #[serde(default)]
-    pub title: Option<String>,
-    /// 更新说明（Markdown）。
-    #[serde(default)]
-    pub content: Option<String>,
-    #[serde(default)]
-    pub download_url: Option<String>,
-    #[serde(default)]
-    pub download_links: Vec<DownloadLink>,
-    #[serde(default)]
-    pub forced: bool,
-    #[serde(default)]
-    pub is_latest: bool,
-    #[serde(default)]
-    pub is_preview: bool,
-    #[serde(default)]
-    pub is_milestone: bool,
-    #[serde(default)]
-    pub is_deprecated: bool,
-    #[serde(default)]
-    pub published_at: i64,
-}
-
-impl Version {
-    /// 下载地址：优先取匹配 Windows 的链接，其次首个链接，最后回退到 download_url。
-    pub fn best_download_url(&self) -> Option<&str> {
-        self.download_links
-            .iter()
-            .find(|l| l.platform.as_deref() == Some(PLATFORM))
-            .or_else(|| self.download_links.first())
-            .map(|l| l.url.as_str())
-            .or(self.download_url.as_deref())
-    }
-}
-
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct CheckUpdate {
-    #[serde(default)]
-    pub should_update: bool,
-    /// 强制更新。
-    #[serde(default)]
-    pub required: bool,
-    #[serde(default)]
-    pub reason_codes: Vec<String>,
-    #[serde(default)]
-    pub current_version: Option<String>,
-    #[serde(default)]
-    pub latest_version: Option<Version>,
-    /// 该升到哪个版本（可能是里程碑版本，而非最新版）。
-    #[serde(default)]
-    pub target_version: Option<Version>,
-}
-
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct Announcement {
-    #[serde(default)]
-    pub id: String,
-    #[serde(default)]
-    pub title: String,
-    #[serde(default)]
-    pub content: String,
-    #[serde(default)]
-    pub is_pinned: bool,
-    #[serde(default)]
-    pub is_hidden: bool,
-    #[serde(default)]
-    pub author: Option<String>,
-    #[serde(default)]
-    pub published_at: i64,
-}
-
-#[derive(Debug, Clone, Default, Deserialize)]
-pub struct AnnouncementList {
-    #[serde(default)]
-    pub total: i64,
-    #[serde(default)]
-    pub data: Vec<Announcement>,
-}
-
-/// 客户端反馈。`rating` 为 1..=5；`custom_data` 携带附加信息。
-#[derive(Debug, Clone, Default, Serialize)]
-pub struct Feedback {
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub rating: Option<u8>,
-    pub content: String,
-    pub platform: &'static str,
-    pub custom_data: serde_json::Value,
-}
-
-/// 日志级别，与 Verhub 的 0..=3 对齐。
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "lowercase")]
-pub enum LogLevel {
-    Debug = 0,
-    Info = 1,
-    Warning = 2,
-    Error = 3,
-}
-
-const LOG_CONTENT_MAX: usize = 4096;
-
-fn agent() -> ureq::Agent {
-    ureq::Agent::config_builder()
-        .timeout_global(Some(TIMEOUT))
-        .user_agent(concat!("BossKey/", env!("CARGO_PKG_VERSION")))
-        // 不把 4xx/5xx 当传输错误，以便自行读取响应体中的报错信息。
-        .http_status_as_error(false)
-        .build()
-        .into()
-}
-
-fn url(path: &str) -> String {
-    format!("{BASE_URL}/public/{PROJECT_KEY}{path}")
-}
-
-fn map_err(e: ureq::Error) -> VerhubError {
-    VerhubError::Http(e.to_string())
-}
-
-/// 非 2xx 时把响应体读出来作为错误消息。
-fn check_status(resp: &mut ureq::http::Response<ureq::Body>) -> Result<()> {
-    let status = resp.status().as_u16();
-    if (200..300).contains(&status) {
-        return Ok(());
-    }
-    let body = resp.body_mut().read_to_string().unwrap_or_default();
-    let message = serde_json::from_str::<serde_json::Value>(&body)
-        .ok()
-        .and_then(|v| {
-            v.get("message").and_then(|m| {
-                // message 可能是字符串或字符串数组
-                m.as_str().map(str::to_string).or_else(|| {
-                    m.as_array().map(|a| {
-                        a.iter()
-                            .filter_map(|x| x.as_str())
-                            .collect::<Vec<_>>()
-                            .join("; ")
-                    })
-                })
-            })
-        })
-        .filter(|s| !s.is_empty())
-        .unwrap_or(body);
-    Err(VerhubError::Api { status, message })
-}
-
-fn read_json<T: serde::de::DeserializeOwned>(
-    mut resp: ureq::http::Response<ureq::Body>,
-) -> Result<T> {
-    check_status(&mut resp)?;
-    resp.body_mut()
-        .read_json::<T>()
-        .map_err(|e| VerhubError::Decode(e.to_string()))
-}
-
-/// 检查更新：把当前版本发给 Verhub，由服务端判断是否需要更新、是否强制。
-pub fn check_update(current_version: &str, include_preview: bool) -> Result<CheckUpdate> {
-    let resp = agent()
-        .post(url("/versions/check-update"))
-        .send_json(serde_json::json!({
-            "current_version": current_version,
-            "current_comparable_version": current_version,
-            "include_preview": include_preview,
-        }))
-        .map_err(map_err)?;
-    read_json(resp)
-}
-
-/// 公告列表（只要本平台 / 全平台的），从新到旧。
-pub fn announcements(limit: u32) -> Result<Vec<Announcement>> {
-    let resp = agent()
-        .get(url("/announcements"))
-        .query("platform", PLATFORM)
-        .query("limit", limit.to_string())
-        .call()
-        .map_err(map_err)?;
-    let list: AnnouncementList = read_json(resp)?;
-    // 再兜一层，滤掉隐藏公告。
-    Ok(list.data.into_iter().filter(|a| !a.is_hidden).collect())
-}
-
-pub fn submit_feedback(feedback: &Feedback) -> Result<()> {
-    let mut resp = agent()
-        .post(url("/feedbacks"))
-        .send_json(feedback)
-        .map_err(map_err)?;
-    check_status(&mut resp)
-}
-
-/// 上报一条日志；内容超长会被截断到 Verhub 的上限内。
-pub fn upload_log(level: LogLevel, content: &str, device_info: serde_json::Value) -> Result<()> {
-    let content = truncate_log(content);
-    let mut resp = agent()
-        .post(url("/logs"))
-        .send_json(serde_json::json!({
-            "level": level as u8,
-            "content": content,
-            "device_info": device_info,
-        }))
-        .map_err(map_err)?;
-    check_status(&mut resp)
-}
-
-/// 截到上限以内，按字符边界切以避免切碎多字节字符。
-fn truncate_log(content: &str) -> String {
-    if content.len() <= LOG_CONTENT_MAX {
-        return content.to_string();
-    }
-    const MARK: &str = "…（日志过长，已截断前半部分）\n";
-    let budget = LOG_CONTENT_MAX - MARK.len();
-    // 保留末尾（出错现场）。
-    let start = content.len() - budget;
-    let start = (start..content.len())
-        .find(|i| content.is_char_boundary(*i))
-        .unwrap_or(content.len());
-    format!("{MARK}{}", &content[start..])
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn truncate_keeps_tail_within_limit() {
-        let long = "错误".repeat(4000); // 远超 4096 字节
-        let out = truncate_log(&long);
-        assert!(
-            out.len() <= LOG_CONTENT_MAX,
-            "截断后仍超上限: {}",
-            out.len()
-        );
-        assert!(out.contains("已截断"));
-        assert!(out.ends_with('误')); // 保的是末尾（出错现场）
-    }
-
-    #[test]
-    fn truncate_leaves_short_content_alone() {
-        assert_eq!(truncate_log("崩了"), "崩了");
-    }
-
-    #[test]
-    fn download_url_prefers_windows_link() {
-        let v = Version {
-            download_url: Some("https://fallback".into()),
-            download_links: vec![
-                DownloadLink {
-                    url: "https://mac".into(),
-                    platform: Some("mac".into()),
-                    ..Default::default()
-                },
-                DownloadLink {
-                    url: "https://win".into(),
-                    platform: Some("windows".into()),
-                    ..Default::default()
-                },
-            ],
-            ..Default::default()
-        };
-        assert_eq!(v.best_download_url(), Some("https://win"));
-
-        let only_fallback = Version {
-            download_url: Some("https://fallback".into()),
-            ..Default::default()
-        };
-        assert_eq!(only_fallback.best_download_url(), Some("https://fallback"));
-    }
-
-    #[test]
-    fn log_level_maps_to_verhub_numbers() {
-        assert_eq!(LogLevel::Debug as u8, 0);
-        assert_eq!(LogLevel::Error as u8, 3);
-    }
-}
diff --git a/crates/core/src/i18n.rs b/crates/core/src/i18n.rs
index 0dc1c48..a1d4710 100644
--- a/crates/core/src/i18n.rs
+++ b/crates/core/src/i18n.rs
@@ -84,7 +84,7 @@ impl Msg {
             Msg::ErrCoreExeMissing => "未找到核心程序 {exe}",
             Msg::ErrFreezePartial => "{failed}/{total} 个进程冻结失败",
             Msg::ErrResumePartial => "{failed}/{total} 个进程解冻失败",
-            Msg::ErrUrlSchemeNotAllowed => "只允许打开 http/https 链接",
+            Msg::ErrUrlSchemeNotAllowed => "只允许打开 http/https/mailto 链接",
             Msg::ErrFeedbackEmpty => "请先填写反馈内容",
         }
     }
@@ -120,7 +120,7 @@ impl Msg {
             Msg::ErrCoreExeMissing => "Core program {exe} not found",
             Msg::ErrFreezePartial => "Failed to freeze {failed} of {total} processes",
             Msg::ErrResumePartial => "Failed to resume {failed} of {total} processes",
-            Msg::ErrUrlSchemeNotAllowed => "Only http/https links may be opened",
+            Msg::ErrUrlSchemeNotAllowed => "Only http/https/mailto links may be opened",
             Msg::ErrFeedbackEmpty => "Please write your feedback first",
         }
     }
@@ -156,7 +156,7 @@ impl Msg {
             Msg::ErrCoreExeMissing => "找不到核心程式 {exe}",
             Msg::ErrFreezePartial => "{failed}/{total} 個程序凍結失敗",
             Msg::ErrResumePartial => "{failed}/{total} 個程序解除凍結失敗",
-            Msg::ErrUrlSchemeNotAllowed => "僅允許開啟 http/https 連結",
+            Msg::ErrUrlSchemeNotAllowed => "僅允許開啟 http/https/mailto 連結",
             Msg::ErrFeedbackEmpty => "請先填寫意見回饋內容",
         }
     }
diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 0bee144..51f54c6 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -68,12 +68,11 @@ Boss-Key/
 ├── Cargo.toml                      workspace（含 release profile 调优）
 ├── crates/
 │   ├── common/                     共享库（无平台依赖，可跨平台编译）
-│   │   └── src/{model,config,matching,ipc,verhub,i18n}.rs
+│   │   └── src/{model,config,matching,ipc,i18n}.rs
 │   │       model     WindowInfo / WindowRule / ProcessRule（serde 兼容旧 config.json，PID 大写）
 │   │       config    Config/Setting/Hotkey（兼容读取旧配置 + 迁移）
 │   │       matching  窗口匹配逻辑
 │   │       ipc       Command/Response 协议 + PipeClient 客户端
-│   │       verhub    版本 / 公告 / 更新检查相关模型
 │   │       i18n      界面语言标签（Lang）与语言偏好解析，核心与配置程序共用
 │   └── core/                       常驻核心（lib + bin）
 │       └── src/
@@ -98,6 +97,7 @@ Boss-Key/
 │           single_instance.rs  命名互斥单实例
 └── apps/config/                    配置界面（Tauri 2 + Svelte 5）
     ├── src-tauri/  Rust 后端命令 + tauri.conf.json + capabilities
+    │   └── src/verhub.rs  Verhub 客户端（版本/公告/反馈/日志，基于 verhub-sdk）
     ├── ui/         前端源码（Vite + Svelte 5）
     │   └── src/    lib/（纯逻辑 + vitest 测试）+ components/（Svelte 组件）
     │                + locales/（三语文案 catalog，以 zh-CN.js 为基准）
diff --git a/docs/en/dev/architecture.md b/docs/en/dev/architecture.md
index 6175548..d1e4df7 100644
--- a/docs/en/dev/architecture.md
+++ b/docs/en/dev/architecture.md
@@ -68,12 +68,11 @@ Boss-Key/
 ├── Cargo.toml                      workspace (including release profile tuning)
 ├── crates/
 │   ├── common/                     Shared library (no platform dependency; builds cross-platform)
-│   │   └── src/{model,config,matching,ipc,verhub,i18n}.rs
+│   │   └── src/{model,config,matching,ipc,i18n}.rs
 │   │       model     WindowInfo / WindowRule / ProcessRule (serde-compatible with the old config.json; PID uppercase)
 │   │       config    Config/Setting/Hotkey (reads old configurations + migration)
 │   │       matching  Window matching logic
 │   │       ipc       Command/Response protocol + PipeClient
-│   │       verhub    Models for versions / announcements / update checks
 │   │       i18n      Language tags (Lang) and preference resolution, shared by core and settings
 │   └── core/                       Resident core (lib + bin)
 │       └── src/
@@ -98,6 +97,7 @@ Boss-Key/
 │           single_instance.rs  Named-mutex single instance
 └── apps/config/                    Settings window (Tauri 2 + Svelte 5)
     ├── src-tauri/  Rust backend commands + tauri.conf.json + capabilities
+    │   └── src/verhub.rs  Verhub client (versions/announcements/feedback/logs, built on verhub-sdk)
     ├── ui/         Frontend source (Vite + Svelte 5)
     │   └── src/    lib/ (pure logic + vitest tests) + components/ (Svelte components)
     │                + locales/ (three-language catalogs; zh-CN.js is the source of truth)
diff --git a/docs/zh-tw/dev/architecture.md b/docs/zh-tw/dev/architecture.md
index 5442f1c..3657e24 100644
--- a/docs/zh-tw/dev/architecture.md
+++ b/docs/zh-tw/dev/architecture.md
@@ -68,12 +68,11 @@ Boss-Key/
 ├── Cargo.toml                      workspace（含 release profile 調校）
 ├── crates/
 │   ├── common/                     共用程式庫（無平台相依，可跨平台編譯）
-│   │   └── src/{model,config,matching,ipc,verhub,i18n}.rs
+│   │   └── src/{model,config,matching,ipc,i18n}.rs
 │   │       model     WindowInfo / WindowRule / ProcessRule（serde 相容舊 config.json，PID 大寫）
 │   │       config    Config/Setting/Hotkey（相容讀取舊設定 + 移轉）
 │   │       matching  視窗比對邏輯
 │   │       ipc       Command/Response 協定 + PipeClient 用戶端
-│   │       verhub    版本／公告／更新檢查相關模型
 │   │       i18n      介面語言標籤（Lang）與語言偏好解析，核心與設定程式共用
 │   └── core/                       常駐核心（lib + bin）
 │       └── src/
@@ -98,6 +97,7 @@ Boss-Key/
 │           single_instance.rs  具名互斥鎖單一執行個體
 └── apps/config/                    設定介面（Tauri 2 + Svelte 5）
     ├── src-tauri/  Rust 後端命令 + tauri.conf.json + capabilities
+    │   └── src/verhub.rs  Verhub 用戶端（版本／公告／回饋／日誌，基於 verhub-sdk）
     ├── ui/         前端原始碼（Vite + Svelte 5）
     │   └── src/    lib/（純邏輯 + vitest 測試）+ components/（Svelte 元件）
     │                + locales/（三語文案 catalog，以 zh-CN.js 為基準）

From 9c23863989a9f5575bd2be0e53c827d897355bd6 Mon Sep 17 00:00:00 2001
From: Ivan Hanloth <ivan@hanloth.com>
Date: Sat, 25 Jul 2026 22:07:06 +0100
Subject: [PATCH 4/4] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E7=8B=AC?=
 =?UTF-8?q?=E7=AB=8B=E9=9A=90=E8=97=8F=E3=80=81=E7=8B=AC=E7=AB=8B=E6=81=A2?=
 =?UTF-8?q?=E5=A4=8D=E3=80=81=E4=BB=85=E9=9A=90=E8=97=8F=E5=BD=93=E5=89=8D?=
 =?UTF-8?q?=E7=AA=97=E5=8F=A3=E7=83=AD=E9=94=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../ui/src/components/HotkeysPanel.svelte     |  21 +++
 apps/config/ui/src/lib/ipc.js                 |   6 +
 apps/config/ui/src/locales/en.js              |   3 +
 apps/config/ui/src/locales/zh-CN.js           |   3 +
 apps/config/ui/src/locales/zh-TW.js           |   3 +
 crates/common/src/config.rs                   |  61 +++++++
 crates/core/src/agent.rs                      |  76 ++++++++-
 crates/core/src/hide.rs                       | 161 +++++++++++++++---
 docs/dev/config-reference.md                  |   6 +
 docs/en/dev/config-reference.md               |   6 +
 docs/en/guide/hotkeys.md                      |  29 +++-
 docs/guide/hotkeys.md                         |  29 +++-
 docs/zh-tw/dev/config-reference.md            |   6 +
 docs/zh-tw/guide/hotkeys.md                   |  29 +++-
 14 files changed, 393 insertions(+), 46 deletions(-)

diff --git a/apps/config/ui/src/components/HotkeysPanel.svelte b/apps/config/ui/src/components/HotkeysPanel.svelte
index f4bd224..606f8e3 100644
--- a/apps/config/ui/src/components/HotkeysPanel.svelte
+++ b/apps/config/ui/src/components/HotkeysPanel.svelte
@@ -38,6 +38,27 @@
       interceptLabel={t("hotkeys.interceptShort")}
       interceptTitle={t("hotkeys.interceptDesc")}
     />
+    <HotkeyRecorder
+      label={t("hotkeys.hideOnly")}
+      bind:value={app.config.hotkey.hide_only_hotkey}
+      bind:intercept={app.config.hotkey.hide_only_intercept}
+      interceptLabel={t("hotkeys.interceptShort")}
+      interceptTitle={t("hotkeys.interceptDesc")}
+    />
+    <HotkeyRecorder
+      label={t("hotkeys.showOnly")}
+      bind:value={app.config.hotkey.show_only_hotkey}
+      bind:intercept={app.config.hotkey.show_only_intercept}
+      interceptLabel={t("hotkeys.interceptShort")}
+      interceptTitle={t("hotkeys.interceptDesc")}
+    />
+    <HotkeyRecorder
+      label={t("hotkeys.hideForeground")}
+      bind:value={app.config.hotkey.hide_foreground_hotkey}
+      bind:intercept={app.config.hotkey.hide_foreground_intercept}
+      interceptLabel={t("hotkeys.interceptShort")}
+      interceptTitle={t("hotkeys.interceptDesc")}
+    />
     <HotkeyRecorder
       label={t("hotkeys.closeApp")}
       bind:value={app.config.hotkey.close_hotkey}
diff --git a/apps/config/ui/src/lib/ipc.js b/apps/config/ui/src/lib/ipc.js
index e4f5973..1dbed7e 100644
--- a/apps/config/ui/src/lib/ipc.js
+++ b/apps/config/ui/src/lib/ipc.js
@@ -14,8 +14,14 @@ const mockConfig = {
   hotkey: {
     hide_hotkey: "Ctrl+Q",
     close_hotkey: "Win+Esc",
+    hide_only_hotkey: "",
+    show_only_hotkey: "",
+    hide_foreground_hotkey: "",
     hide_intercept: false,
     close_intercept: false,
+    hide_only_intercept: false,
+    show_only_intercept: false,
+    hide_foreground_intercept: false,
   },
   setting: {
     mute_after_hide: true,
diff --git a/apps/config/ui/src/locales/en.js b/apps/config/ui/src/locales/en.js
index 34bdd73..183cd16 100644
--- a/apps/config/ui/src/locales/en.js
+++ b/apps/config/ui/src/locales/en.js
@@ -106,6 +106,9 @@ export default {
   "hotkeys.keyboardCard": "Keyboard hotkeys",
   "hotkeys.hideShow": "Hide / show windows",
   "hotkeys.closeApp": "Close the core",
+  "hotkeys.hideOnly": "Hide windows only",
+  "hotkeys.showOnly": "Show windows only",
+  "hotkeys.hideForeground": "Hide foreground window",
   "hotkeys.interceptShort": "Don't pass through",
   "hotkeys.interceptDesc": "With \"Don't pass through\" enabled, the key press never reaches the foreground app, so games or input boxes won't receive it.",
   "hotkeys.mouseCard": "Hide with mouse buttons",
diff --git a/apps/config/ui/src/locales/zh-CN.js b/apps/config/ui/src/locales/zh-CN.js
index 66dbae1..083eed5 100644
--- a/apps/config/ui/src/locales/zh-CN.js
+++ b/apps/config/ui/src/locales/zh-CN.js
@@ -105,6 +105,9 @@ export default {
   "hotkeys.keyboardCard": "键盘热键",
   "hotkeys.hideShow": "隐藏 / 显示窗口",
   "hotkeys.closeApp": "关闭核心",
+  "hotkeys.hideOnly": "仅隐藏窗口",
+  "hotkeys.showOnly": "仅显示窗口",
+  "hotkeys.hideForeground": "隐藏前台窗口",
   "hotkeys.interceptShort": "不传递",
   "hotkeys.interceptDesc": "开启「不传递」后，触发该热键时按键不会传给前台程序，避免游戏或输入框误收按键。",
   "hotkeys.mouseCard": "鼠标按键隐藏",
diff --git a/apps/config/ui/src/locales/zh-TW.js b/apps/config/ui/src/locales/zh-TW.js
index e85b33e..1e3ce1d 100644
--- a/apps/config/ui/src/locales/zh-TW.js
+++ b/apps/config/ui/src/locales/zh-TW.js
@@ -104,6 +104,9 @@ export default {
   "hotkeys.keyboardCard": "鍵盤快速鍵",
   "hotkeys.hideShow": "隱藏 / 顯示視窗",
   "hotkeys.closeApp": "關閉核心",
+  "hotkeys.hideOnly": "僅隱藏視窗",
+  "hotkeys.showOnly": "僅顯示視窗",
+  "hotkeys.hideForeground": "隱藏前景視窗",
   "hotkeys.interceptShort": "不傳遞",
   "hotkeys.interceptDesc": "開啟「不傳遞」後，觸發該快速鍵時按鍵不會傳給前景程式，避免遊戲或輸入框誤收按鍵。",
   "hotkeys.mouseCard": "滑鼠按鍵隱藏",
diff --git a/crates/common/src/config.rs b/crates/common/src/config.rs
index 042c5a4..b97659e 100644
--- a/crates/common/src/config.rs
+++ b/crates/common/src/config.rs
@@ -60,12 +60,30 @@ pub struct Hotkey {
     pub hide_hotkey: String,
     #[serde(default = "default_close_hotkey")]
     pub close_hotkey: String,
+    /// 只隐藏、不恢复的热键；默认置空（关闭）。
+    #[serde(default)]
+    pub hide_only_hotkey: String,
+    /// 只恢复、不隐藏的热键；默认置空（关闭）。
+    #[serde(default)]
+    pub show_only_hotkey: String,
+    /// 只隐藏当前前台窗口的热键，可连续触发逐个隐藏；默认置空（关闭）。
+    #[serde(default)]
+    pub hide_foreground_hotkey: String,
     /// 隐藏热键是否不传递给其他程序（核心改用键盘钩子拦截）。
     #[serde(default)]
     pub hide_intercept: bool,
     /// 关闭热键是否不传递给其他程序（核心改用键盘钩子拦截）。
     #[serde(default)]
     pub close_intercept: bool,
+    /// 仅隐藏热键是否不传递给其他程序。
+    #[serde(default)]
+    pub hide_only_intercept: bool,
+    /// 仅显示热键是否不传递给其他程序。
+    #[serde(default)]
+    pub show_only_intercept: bool,
+    /// 隐藏前台窗口热键是否不传递给其他程序。
+    #[serde(default)]
+    pub hide_foreground_intercept: bool,
 }
 
 impl Default for Hotkey {
@@ -73,8 +91,14 @@ impl Default for Hotkey {
         Self {
             hide_hotkey: default_hide_hotkey(),
             close_hotkey: default_close_hotkey(),
+            hide_only_hotkey: String::new(),
+            show_only_hotkey: String::new(),
+            hide_foreground_hotkey: String::new(),
             hide_intercept: false,
             close_intercept: false,
+            hide_only_intercept: false,
+            show_only_intercept: false,
+            hide_foreground_intercept: false,
         }
     }
 }
@@ -506,6 +530,43 @@ mod tests {
         assert!(!Hotkey::default().close_intercept);
     }
 
+    #[test]
+    fn separate_hide_show_hotkeys_default_to_disabled() {
+        let h = Hotkey::default();
+        assert!(h.hide_only_hotkey.is_empty(), "仅隐藏热键默认置空");
+        assert!(h.show_only_hotkey.is_empty(), "仅显示热键默认置空");
+        assert!(h.hide_foreground_hotkey.is_empty(), "隐藏前台热键默认置空");
+        assert!(!h.hide_only_intercept);
+        assert!(!h.show_only_intercept);
+        assert!(!h.hide_foreground_intercept);
+
+        let c = Config::from_json(r#"{"hotkey": {"hide_hotkey": "Ctrl+Q"}}"#).unwrap();
+        assert!(c.hotkey.hide_only_hotkey.is_empty(), "旧配置无此字段应置空");
+        assert!(c.hotkey.show_only_hotkey.is_empty());
+        assert!(c.hotkey.hide_foreground_hotkey.is_empty());
+    }
+
+    #[test]
+    fn separate_hide_show_hotkeys_round_trip() {
+        let c = Config::from_json(
+            r#"{"hotkey": {
+                "hide_only_hotkey": "Ctrl+Alt+H",
+                "show_only_hotkey": "Ctrl+Alt+S",
+                "hide_foreground_hotkey": "Ctrl+Alt+F",
+                "hide_foreground_intercept": true
+            }}"#,
+        )
+        .unwrap();
+        assert_eq!(c.hotkey.hide_only_hotkey, "Ctrl+Alt+H");
+        assert_eq!(c.hotkey.show_only_hotkey, "Ctrl+Alt+S");
+        assert_eq!(c.hotkey.hide_foreground_hotkey, "Ctrl+Alt+F");
+        assert!(c.hotkey.hide_foreground_intercept);
+        assert!(!c.hotkey.hide_only_intercept, "各热键的开关相互独立");
+
+        let back = Config::from_json(&c.to_json().unwrap()).unwrap();
+        assert_eq!(back.hotkey, c.hotkey, "写回后应保留");
+    }
+
     #[test]
     fn intercept_flags_round_trip_independently() {
         let c = Config::from_json(r#"{"hotkey": {"hide_intercept": true}}"#).unwrap();
diff --git a/crates/core/src/agent.rs b/crates/core/src/agent.rs
index 13e500e..211c201 100644
--- a/crates/core/src/agent.rs
+++ b/crates/core/src/agent.rs
@@ -23,7 +23,8 @@ use windows::core::{PCWSTR, w};
 use crate::effects::WinEffects;
 use crate::float_window::{FLOAT_MENU, FLOAT_TOGGLE, FloatWindow, WM_APP_FLOAT};
 use crate::hide::{
-    HideController, RuleOutcome, expand_descendants, freezable_pids, resolve_targets,
+    HideController, RuleOutcome, expand_descendants, foreground_target, freezable_pids,
+    resolve_targets,
 };
 use crate::hotkey::{MOD_NOREPEAT, ParsedHotkey, is_disabled, parse_hotkey};
 use crate::i18n::{self, Msg};
@@ -36,6 +37,9 @@ use crate::{idle, ipc_server, logging, recovery};
 
 const HK_HIDE: i32 = 1;
 const HK_CLOSE: i32 = 2;
+const HK_HIDE_ONLY: i32 = 3;
+const HK_SHOW_ONLY: i32 = 4;
+const HK_HIDE_FOREGROUND: i32 = 5;
 
 const WM_APP_IPC: u32 = WM_APP + 1;
 const WM_APP_TRAY: u32 = WM_APP + 2;
@@ -108,6 +112,24 @@ impl AgentState {
                 &self.config.hotkey.close_hotkey,
                 self.config.hotkey.close_intercept,
             ),
+            (
+                HK_HIDE_ONLY,
+                "仅隐藏",
+                &self.config.hotkey.hide_only_hotkey,
+                self.config.hotkey.hide_only_intercept,
+            ),
+            (
+                HK_SHOW_ONLY,
+                "仅显示",
+                &self.config.hotkey.show_only_hotkey,
+                self.config.hotkey.show_only_intercept,
+            ),
+            (
+                HK_HIDE_FOREGROUND,
+                "隐藏前台窗口",
+                &self.config.hotkey.hide_foreground_hotkey,
+                self.config.hotkey.hide_foreground_intercept,
+            ),
         ] {
             if is_disabled(raw) {
                 logging::info(&format!("{label}热键已置空，不注册"));
@@ -166,8 +188,15 @@ impl AgentState {
 
     fn unregister_hotkeys(&mut self, hwnd: HWND) {
         unsafe {
-            let _ = UnregisterHotKey(Some(hwnd), HK_HIDE);
-            let _ = UnregisterHotKey(Some(hwnd), HK_CLOSE);
+            for id in [
+                HK_HIDE,
+                HK_CLOSE,
+                HK_HIDE_ONLY,
+                HK_SHOW_ONLY,
+                HK_HIDE_FOREGROUND,
+            ] {
+                let _ = UnregisterHotKey(Some(hwnd), id);
+            }
         }
         keyboard_hook::set_hotkeys(&[]);
         self.keyboard_hook = None;
@@ -271,10 +300,41 @@ impl AgentState {
             self.balloon(APP_NAME, i18n::t(Msg::HiddenBody));
         }
     }
+    fn apply_hide_foreground(&mut self) {
+        let windows = self.controller.enumerate();
+        let foreground = self.controller.foreground();
+        let Some(target) = foreground_target(&windows, foreground) else {
+            logging::info("触发隐藏前台窗口：当前没有可隐藏的前台窗口，本次不隐藏");
+            return;
+        };
+
+        let targets = [target];
+        let freezable = freezable_pids(&targets, &windows);
+        let freeze_set = if self.config.setting.freeze_whole_tree {
+            expand_descendants(&freezable, &crate::freeze::process_tree())
+        } else {
+            freezable
+        };
+
+        let w = windows.iter().find(|w| w.hwnd == target.hwnd);
+        logging::info(&format!(
+            "触发隐藏前台窗口 hwnd={} pid={} process={} title=「{}」",
+            target.hwnd,
+            target.pid,
+            w.map(|w| w.process.as_str()).unwrap_or("未知进程"),
+            w.map(|w| w.title.as_str()).unwrap_or(""),
+        ));
+
+        self.controller
+            .apply_hide(&self.config.setting, &targets, &freeze_set);
+        self.persist_recovery();
+        self.sync_tray();
+        if self.config.notifications.on_hide {
+            self.balloon(APP_NAME, i18n::t(Msg::HiddenBody));
+        }
+    }
 
     fn apply_show(&mut self) {
-        // 计数须在 show() 清空隐藏集之前取，且不能假定必有窗口：
-        // 未隐藏任何窗口时触发恢复也会走到这里。
         let count = self.controller.hidden_count();
         self.controller.show();
         logging::info(&format!("已恢复显示 {count} 个窗口"));
@@ -631,9 +691,6 @@ unsafe extern "system" fn wndproc(hwnd: HWND, msg: u32, wparam: WPARAM, lparam:
     let Some(state) = state_mut(hwnd) else {
         return unsafe { DefWindowProcW(hwnd, msg, wparam, lparam) };
     };
-
-    // TaskbarCreated 是运行时注册的消息号，无法进 match 常量分支。
-    // explorer（重）建任务栏时广播，此时旧托盘图标已消失，须按期望状态重挂。
     if msg != 0 && msg == crate::tray::taskbar_created_msg() {
         if let Some(tray) = &mut state.tray {
             tray.on_taskbar_created();
@@ -647,6 +704,9 @@ unsafe extern "system" fn wndproc(hwnd: HWND, msg: u32, wparam: WPARAM, lparam:
             match wparam.0 as i32 {
                 HK_HIDE => state.apply_toggle(),
                 HK_CLOSE => quit(state, hwnd),
+                HK_HIDE_ONLY => state.apply_hide(),
+                HK_SHOW_ONLY => state.apply_show(),
+                HK_HIDE_FOREGROUND => state.apply_hide_foreground(),
                 _ => {}
             }
             LRESULT(0)
diff --git a/crates/core/src/hide.rs b/crates/core/src/hide.rs
index 866d0d2..5d391a6 100644
--- a/crates/core/src/hide.rs
+++ b/crates/core/src/hide.rs
@@ -96,6 +96,23 @@ pub fn resolve_targets(
     (result, outcomes)
 }
 
+/// 前台窗口对应的隐藏目标。
+///
+/// 只接受出现在枚举结果里且当前可见的顶层窗口：工具窗口不在枚举结果内，
+/// 已被隐藏的窗口 `visible` 为假，二者都不该再次成为隐藏目标。
+pub fn foreground_target(windows: &[WindowInfo], foreground: i64) -> Option<Target> {
+    if foreground == 0 {
+        return None;
+    }
+    windows
+        .iter()
+        .find(|w| w.hwnd == foreground && w.visible)
+        .map(|w| Target {
+            hwnd: w.hwnd,
+            pid: w.pid,
+        })
+}
+
 /// 可以安全冻结的进程 PID 集合：仅当某进程的全部可见窗口都在隐藏目标里时才纳入。
 pub fn freezable_pids(targets: &[Target], windows: &[WindowInfo]) -> Vec<u32> {
     let hidden: HashSet<i64> = targets.iter().map(|t| t.hwnd).collect();
@@ -196,43 +213,51 @@ impl<W: WindowManager, E: Effects> HideController<W, E> {
     /// 隐藏已解析出的目标：隐藏窗口并按设置应用静音 / 冻结 / 发送暂停键。
     /// `freeze_pids` 为最终要冻结的 PID 集（调用方算好，可能已含递归展开的子进程树，
     /// 见 [`freezable_pids`] 与 [`expand_descendants`]）；仅在 `freeze_after_hide` 开启时生效。
+    ///
+    /// 隐藏是累加的：先前隐藏的窗口留在隐藏集内，`show` 时一并恢复。已在隐藏集 /
+    /// 静音集 / 冻结集里的目标会被跳过——静音与挂起若重复施加，挂起尤其是计数式的，
+    /// 需要同样次数的解冻才能恢复。
     pub fn apply_hide(&mut self, setting: &Setting, targets: &[Target], freeze_pids: &[u32]) {
+        let known: HashSet<i64> = self.hidden.iter().map(|t| t.hwnd).collect();
+        let fresh: Vec<Target> = targets
+            .iter()
+            .copied()
+            .filter(|t| !known.contains(&t.hwnd))
+            .collect();
+
         // 隐藏前先发一次媒体「播放/暂停」键，暂停正在播放的音视频。
         // 只发一次：多目标时重复发送会把「播放/暂停」这个切换键又切回播放。
         // 仅当确有音视频在播放时才真正发键（由 effects 判断），此时才需等待其生效。
-        if setting.send_before_hide && !targets.is_empty() && self.effects.send_pause() {
+        if setting.send_before_hide && !fresh.is_empty() && self.effects.send_pause() {
             std::thread::sleep(SEND_PAUSE_DELAY);
         }
 
-        let mut muted = Vec::new();
-
-        for t in targets {
+        for t in &fresh {
             self.wm.hide(t.hwnd);
-            if setting.mute_after_hide && t.pid != 0 {
+            if setting.mute_after_hide && t.pid != 0 && !self.muted.contains(&t.pid) {
                 self.effects.mute(t.pid, true);
-                muted.push(t.pid);
+                self.muted.push(t.pid);
             }
         }
-        muted.sort_unstable();
-        muted.dedup();
 
         // 冻结与目标窗口解耦：freeze_pids 已是最终集合（含子进程树），逐个挂起。
-        let mut frozen = Vec::new();
         if setting.freeze_after_hide {
-            frozen = freeze_pids.to_vec();
-            frozen.retain(|pid| *pid != 0);
-            // 挂起是计数式的，去重以匹配解冻次数。
-            frozen.sort_unstable();
-            frozen.dedup();
-            self.used_enhanced = setting.enhanced_freeze;
-            for pid in &frozen {
-                self.effects.suspend(*pid, self.used_enhanced);
+            // 冻结方式在解冻时必须与冻结时一致，故只有冻结集为空（本轮是第一次冻结）
+            // 时才跟随当前设置，之后沿用同一方式。
+            if self.frozen.is_empty() {
+                self.used_enhanced = setting.enhanced_freeze;
+            }
+            for pid in freeze_pids {
+                if *pid != 0 && !self.frozen.contains(pid) {
+                    self.effects.suspend(*pid, self.used_enhanced);
+                    self.frozen.push(*pid);
+                }
             }
+            self.frozen.sort_unstable();
         }
 
-        self.frozen = frozen;
-        self.muted = muted;
-        self.hidden = targets.to_vec();
+        self.muted.sort_unstable();
+        self.hidden.extend(fresh);
     }
 
     pub fn show(&mut self) {
@@ -645,6 +670,102 @@ mod tests {
         );
     }
 
+    #[test]
+    fn successive_hides_accumulate_and_restore_together() {
+        let setting = Setting {
+            hide_current: false,
+            mute_after_hide: true,
+            freeze_after_hide: false,
+            ..Setting::default()
+        };
+
+        let wm = MockWm::new(
+            vec![
+                win("微信", 10, "WeChat.exe", "C:\\WeChat.exe"),
+                win("记事本", 20, "notepad.exe", "C:\\notepad.exe"),
+            ],
+            10,
+        );
+        let mut controller = HideController::new(wm, MockEffects::default());
+
+        controller.apply_hide(&setting, &[Target { hwnd: 10, pid: 10 }], &[]);
+        controller.apply_hide(&setting, &[Target { hwnd: 20, pid: 20 }], &[]);
+
+        assert_eq!(
+            controller.hidden_count(),
+            2,
+            "第二次隐藏不应挤掉第一次的窗口"
+        );
+        assert!(!controller.wm.is_visible(10) && !controller.wm.is_visible(20));
+
+        controller.show();
+        assert!(
+            controller.wm.is_visible(10) && controller.wm.is_visible(20),
+            "恢复应把累计隐藏的窗口一并放出来"
+        );
+        assert_eq!(
+            *controller.effects.mutes.borrow(),
+            vec![(10, true), (20, true), (10, false), (20, false)],
+            "两个进程都应取消静音"
+        );
+    }
+
+    #[test]
+    fn re_hiding_the_same_window_does_not_repeat_effects() {
+        let setting = Setting {
+            hide_current: false,
+            mute_after_hide: true,
+            freeze_after_hide: true,
+            ..Setting::default()
+        };
+
+        let wm = MockWm::new(vec![win("微信", 10, "WeChat.exe", "C:\\WeChat.exe")], 10);
+        let mut controller = HideController::new(wm, MockEffects::default());
+
+        let targets = [Target { hwnd: 10, pid: 10 }];
+        controller.apply_hide(&setting, &targets, &[10]);
+        controller.apply_hide(&setting, &targets, &[10]);
+
+        assert_eq!(controller.hidden_count(), 1, "同一窗口不应重复入集");
+        assert_eq!(
+            *controller.effects.suspends.borrow(),
+            vec![10],
+            "重复挂起会让解冻次数对不上，须跳过"
+        );
+        assert_eq!(*controller.effects.mutes.borrow(), vec![(10, true)]);
+
+        controller.show();
+        assert_eq!(
+            *controller.effects.resumes.borrow(),
+            vec![10],
+            "一次解冻即可"
+        );
+        assert!(controller.wm.is_visible(10));
+    }
+
+    #[test]
+    fn foreground_target_takes_the_visible_foreground_window() {
+        let windows = vec![
+            win_pid("微信", 10, "WeChat.exe", 500, "C:\\WeChat.exe"),
+            win_pid("已隐藏", 11, "app.exe", 600, "C:\\app.exe").with_visibility(false),
+        ];
+        assert_eq!(
+            foreground_target(&windows, 10),
+            Some(Target { hwnd: 10, pid: 500 })
+        );
+        assert_eq!(foreground_target(&windows, 0), None, "无前台窗口");
+        assert_eq!(
+            foreground_target(&windows, 11),
+            None,
+            "已隐藏的窗口不该再次成为目标"
+        );
+        assert_eq!(
+            foreground_target(&windows, 99),
+            None,
+            "枚举不到的窗口（如工具窗口）不作为目标"
+        );
+    }
+
     #[test]
     fn send_before_hide_fires_once_regardless_of_target_count() {
         let mut config = Config::default();
diff --git a/docs/dev/config-reference.md b/docs/dev/config-reference.md
index b24607b..90df20b 100644
--- a/docs/dev/config-reference.md
+++ b/docs/dev/config-reference.md
@@ -31,8 +31,14 @@ Boss Key 的配置保存在与可执行文件**同目录**的 `config.json` 中
 | --- | --- | --- |
 | `hide_hotkey` | `"Ctrl+Q"` | 隐藏 / 显示窗口 |
 | `close_hotkey` | `"Win+Esc"` | 关闭核心 |
+| `hide_only_hotkey` | `""` | [仅隐藏窗口](/guide/hotkeys#单向热键与隐藏前台窗口)，置空为关闭 |
+| `show_only_hotkey` | `""` | [仅显示窗口](/guide/hotkeys#单向热键与隐藏前台窗口)，置空为关闭 |
+| `hide_foreground_hotkey` | `""` | [隐藏前台窗口](/guide/hotkeys#单向热键与隐藏前台窗口)，置空为关闭 |
 | `hide_intercept` | `false` | [隐藏热键不传递](/guide/hotkeys#热键不传递)（键盘钩子拦截） |
 | `close_intercept` | `false` | [关闭热键不传递](/guide/hotkeys#热键不传递)（键盘钩子拦截） |
+| `hide_only_intercept` | `false` | 仅隐藏热键不传递 |
+| `show_only_intercept` | `false` | 仅显示热键不传递 |
+| `hide_foreground_intercept` | `false` | 隐藏前台窗口热键不传递 |
 
 ## `setting`
 
diff --git a/docs/en/dev/config-reference.md b/docs/en/dev/config-reference.md
index fca1bdd..0d073a5 100644
--- a/docs/en/dev/config-reference.md
+++ b/docs/en/dev/config-reference.md
@@ -31,8 +31,14 @@ The settings window reads and writes the configuration automatically. This page
 | --- | --- | --- |
 | `hide_hotkey` | `"Ctrl+Q"` | Hide / show windows |
 | `close_hotkey` | `"Win+Esc"` | Close the core |
+| `hide_only_hotkey` | `""` | [Hide windows only](/en/guide/hotkeys#one-way-hotkeys-and-hiding-the-foreground-window); empty means disabled |
+| `show_only_hotkey` | `""` | [Show windows only](/en/guide/hotkeys#one-way-hotkeys-and-hiding-the-foreground-window); empty means disabled |
+| `hide_foreground_hotkey` | `""` | [Hide foreground window](/en/guide/hotkeys#one-way-hotkeys-and-hiding-the-foreground-window); empty means disabled |
 | `hide_intercept` | `false` | [Don't pass the hide hotkey through](/en/guide/hotkeys#keeping-hotkeys-from-other-apps) (keyboard-hook interception) |
 | `close_intercept` | `false` | [Don't pass the close hotkey through](/en/guide/hotkeys#keeping-hotkeys-from-other-apps) (keyboard-hook interception) |
+| `hide_only_intercept` | `false` | Don't pass the hide-only hotkey through |
+| `show_only_intercept` | `false` | Don't pass the show-only hotkey through |
+| `hide_foreground_intercept` | `false` | Don't pass the hide-foreground hotkey through |
 
 ## `setting`
 
diff --git a/docs/en/guide/hotkeys.md b/docs/en/guide/hotkeys.md
index d1b2a3d..e3d9290 100644
--- a/docs/en/guide/hotkeys.md
+++ b/docs/en/guide/hotkeys.md
@@ -14,16 +14,33 @@ When the pointer enters the "Hotkeys & Mouse" settings area, the core **temporar
 
 ## Keyboard hotkeys
 
-There are two customisable global hotkeys:
+There are five customisable global hotkeys:
 
-| Function | Default |
-| --- | --- |
-| **Hide / show windows** | `Ctrl + Q` |
-| **Close the core** | `Win + Esc` |
+| Function | Default | What it does |
+| --- | --- | --- |
+| **Hide / show windows** | `Ctrl + Q` | Restores when hidden, hides otherwise |
+| **Hide windows only** | Disabled | Hides, never restores |
+| **Show windows only** | Disabled | Restores, never hides |
+| **Hide foreground window** | Disabled | Hides just the currently active window |
+| **Close the core** | `Win + Esc` | Quits the core (restoring every window first) |
 
 Click **Record**, then press the combination you want; it is recognised and filled in automatically.
 
-Click **Clear** to unset the hotkey. Once unset it reads "Disabled", the core no longer registers it, and that function cannot be triggered from the keyboard. The two hotkeys are independent and can be unset separately.
+Click **Clear** to unset the hotkey. Once unset it reads "Disabled", the core no longer registers it, and that function cannot be triggered from the keyboard. The five hotkeys are independent and can be unset separately.
+
+### One-way hotkeys and hiding the foreground window
+
+The last three are unset by default; record them when you need them:
+
+- **Hide windows only**: hides according to your rules, and never restores. Useful for splitting hide and restore across two keys so a stray press can't reveal what you just hid.
+- **Show windows only**: restores hidden windows, and never hides.
+- **Hide foreground window**: ignores your [window / process rules](/en/guide/binding) and hides just the currently active window. Press it repeatedly to hide one more window each time.
+
+Hiding is **cumulative**: no matter how a window was hidden, it goes into the same list and comes back with everything else. So windows hidden by these three hotkeys can only be brought back by **Show windows only**, **Hide / show windows** (which restores in that state), or another restore method such as the tray menu or a mouse gesture.
+
+::: tip
+**Hide foreground window** targets the ordinary top-level window that currently has focus. If focus is elsewhere — on the desktop or on certain tool windows — the press does nothing and says so in the log.
+:::
 
 ### Keeping hotkeys from other apps
 
diff --git a/docs/guide/hotkeys.md b/docs/guide/hotkeys.md
index 7f62259..2ce8864 100644
--- a/docs/guide/hotkeys.md
+++ b/docs/guide/hotkeys.md
@@ -14,16 +14,33 @@ Boss Key 提供多种触发隐藏 / 恢复的方式：键盘全局热键、鼠
 
 ## 键盘热键
 
-包含两个可自定义的全局热键：
+包含五个可自定义的全局热键：
 
-| 功能 | 默认值 |
-| --- | --- |
-| **隐藏 / 显示窗口** | `Ctrl + Q` |
-| **关闭核心** | `Win + Esc` |
+| 功能 | 默认值 | 说明 |
+| --- | --- | --- |
+| **隐藏 / 显示窗口** | `Ctrl + Q` | 已隐藏时恢复，未隐藏时隐藏 |
+| **仅隐藏窗口** | 已关闭 | 只隐藏，不恢复 |
+| **仅显示窗口** | 已关闭 | 只恢复，不隐藏 |
+| **隐藏前台窗口** | 已关闭 | 只隐藏当前活动的那一个窗口 |
+| **关闭核心** | `Win + Esc` | 退出核心（退出前会恢复所有窗口） |
 
 点击 **录制** 按钮，输入框提示"请按下组合键…"后按下想要的组合键，程序会自动识别并填入。
 
-点击 **清除** 按钮可置空该热键。置空后该项显示为"已关闭"，核心不再注册它，对应功能无法通过键盘触发；两个热键相互独立，可单独置空。
+点击 **清除** 按钮可置空该热键。置空后该项显示为"已关闭"，核心不再注册它，对应功能无法通过键盘触发；五个热键相互独立，可单独置空。
+
+### 单向热键与隐藏前台窗口
+
+后三个热键默认置空，需要时自行录制：
+
+- **仅隐藏窗口**：按规则隐藏，但绝不恢复。适合把隐藏与恢复拆成两个键，避免误按同一个键把刚藏好的窗口又放出来。
+- **仅显示窗口**：只恢复已隐藏的窗口，绝不触发隐藏。
+- **隐藏前台窗口**：**不套用**[窗口 / 进程规则](/guide/binding)，只隐藏当前活动的那一个窗口。可连续按下，每按一次多藏一个窗口。
+
+隐藏是**累加**的：无论用哪种方式隐藏，被隐藏的窗口都会记在同一份清单里，恢复时一并放出。因此上述三个热键隐藏的窗口，只能通过 **仅显示窗口**、**隐藏 / 显示窗口**（此时它执行恢复），或托盘菜单、鼠标手势等其他恢复方式放出来。
+
+::: tip
+**隐藏前台窗口** 隐藏的是当前获得焦点的普通顶层窗口。若焦点不在这类窗口上（例如停在桌面或某些工具窗口），该次触发不做任何事，并在日志中留下记录。
+:::
 
 ### 热键不传递
 
diff --git a/docs/zh-tw/dev/config-reference.md b/docs/zh-tw/dev/config-reference.md
index 05be4cd..79c2448 100644
--- a/docs/zh-tw/dev/config-reference.md
+++ b/docs/zh-tw/dev/config-reference.md
@@ -31,8 +31,14 @@ Boss Key 的設定儲存在與執行檔**同資料夾**的 `config.json` 中。*
 | --- | --- | --- |
 | `hide_hotkey` | `"Ctrl+Q"` | 隱藏／顯示視窗 |
 | `close_hotkey` | `"Win+Esc"` | 關閉核心 |
+| `hide_only_hotkey` | `""` | [僅隱藏視窗](/zh-tw/guide/hotkeys#單向快速鍵與隱藏前景視窗)，留空為關閉 |
+| `show_only_hotkey` | `""` | [僅顯示視窗](/zh-tw/guide/hotkeys#單向快速鍵與隱藏前景視窗)，留空為關閉 |
+| `hide_foreground_hotkey` | `""` | [隱藏前景視窗](/zh-tw/guide/hotkeys#單向快速鍵與隱藏前景視窗)，留空為關閉 |
 | `hide_intercept` | `false` | [隱藏快速鍵不傳遞](/zh-tw/guide/hotkeys#快速鍵不傳遞)（鍵盤掛鉤攔截） |
 | `close_intercept` | `false` | [關閉快速鍵不傳遞](/zh-tw/guide/hotkeys#快速鍵不傳遞)（鍵盤掛鉤攔截） |
+| `hide_only_intercept` | `false` | 僅隱藏快速鍵不傳遞 |
+| `show_only_intercept` | `false` | 僅顯示快速鍵不傳遞 |
+| `hide_foreground_intercept` | `false` | 隱藏前景視窗快速鍵不傳遞 |
 
 ## `setting`
 
diff --git a/docs/zh-tw/guide/hotkeys.md b/docs/zh-tw/guide/hotkeys.md
index 7ab91dd..d279e40 100644
--- a/docs/zh-tw/guide/hotkeys.md
+++ b/docs/zh-tw/guide/hotkeys.md
@@ -14,16 +14,33 @@ Boss Key 提供多種觸發隱藏／復原的方式：鍵盤全域快速鍵、
 
 ## 鍵盤快速鍵
 
-包含兩個可自訂的全域快速鍵：
+包含五個可自訂的全域快速鍵：
 
-| 功能 | 預設值 |
-| --- | --- |
-| **隱藏／顯示視窗** | `Ctrl + Q` |
-| **關閉核心** | `Win + Esc` |
+| 功能 | 預設值 | 說明 |
+| --- | --- | --- |
+| **隱藏／顯示視窗** | `Ctrl + Q` | 已隱藏時恢復，未隱藏時隱藏 |
+| **僅隱藏視窗** | 已關閉 | 只隱藏，不恢復 |
+| **僅顯示視窗** | 已關閉 | 只恢復，不隱藏 |
+| **隱藏前景視窗** | 已關閉 | 只隱藏目前作用中的那一個視窗 |
+| **關閉核心** | `Win + Esc` | 結束核心（結束前會恢復所有視窗） |
 
 按一下 **錄製** 按鈕，輸入框提示「請按下組合鍵…」後按下想要的組合鍵，程式會自動辨識並填入。
 
-按一下 **清除** 按鈕可清空該快速鍵。清空後該項顯示為「已關閉」，核心不再註冊它，對應功能無法透過鍵盤觸發；兩個快速鍵相互獨立，可單獨清空。
+按一下 **清除** 按鈕可清空該快速鍵。清空後該項顯示為「已關閉」，核心不再註冊它，對應功能無法透過鍵盤觸發；五個快速鍵相互獨立，可單獨清空。
+
+### 單向快速鍵與隱藏前景視窗
+
+後三個快速鍵預設留空，需要時自行錄製：
+
+- **僅隱藏視窗**：依規則隱藏，但絕不恢復。適合把隱藏與恢復拆成兩個鍵，避免誤按同一個鍵把剛藏好的視窗又放出來。
+- **僅顯示視窗**：只恢復已隱藏的視窗，絕不觸發隱藏。
+- **隱藏前景視窗**：**不套用**[視窗／處理程序規則](/zh-tw/guide/binding)，只隱藏目前作用中的那一個視窗。可連續按下，每按一次多藏一個視窗。
+
+隱藏是**累加**的：無論用哪種方式隱藏，被隱藏的視窗都會記在同一份清單裡，恢復時一併放出。因此上述三個快速鍵隱藏的視窗，只能透過 **僅顯示視窗**、**隱藏／顯示視窗**（此時它執行恢復），或系統匣選單、滑鼠手勢等其他恢復方式放出來。
+
+::: tip
+**隱藏前景視窗** 隱藏的是目前取得焦點的一般最上層視窗。若焦點不在這類視窗上（例如停在桌面或某些工具視窗），該次觸發不做任何事，並在記錄檔中留下紀錄。
+:::
 
 ### 快速鍵不傳遞