dsh-plugin-update 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 格式为 Keep-a-Changelog 子集：`Added/Fixed/Changed` 必写，`Deprecated/Removed/Security` 有则透传，`Unreleased` 面板忽略，禁止 git-log 直倒。面板缺日志时中性提示，不挡安装。
 
+## [0.7.0] - 2026-10-06
+
+### Added
+- 主题变量覆盖 `themeTokens`（第三方换肤一等口径）：单面板、批量面板、入口件、批量入口件四个挂载口同收同语义（35 个语义键对 `--dsh-update-*` 变量，颜色收 hex 或英文名，其余走注入检查，非法挂载即抛）；内联写根、变量继承，入口件打开的 dialog 同步透传，批量展开的详情行经继承生效；控制器同步新增 `setThemeTokens`（传 `undefined` 即清掉覆盖）；被覆盖的 token 不再跟随深色媒体查询。README 补换肤章节与键表。
 ## [0.6.0] - 2026-10-06
 
 ### Changed

package/README.md

@@ -142,8 +142,30 @@ mountUpdatePanel(slot, { pluginId: 'my-notes-plugin', prefix: 'notes', call: hos
 
 面板画成档案五章：**01 检查与安装、02 更新日志、03 更新队列、04 错误信息、05 手工命令**（五章恒在，缺内容给中性提示，不跳号）。档案头一行是「插件名 + 使用范围 + `profile` 牌」：使用范围由面板自动向宿主索取（电话入参 `includeEnv`，宿主只回**范围名与宿主种类**、不回任何路径），显示的就是更新要落到的那个 profile——`web` 与 `desktop` 各装一份，装错范围是严重故障，所以这一栏宁可显示“未知”也不猜。调用方知道得更准时可以用 `profileName` 显式覆盖。
 
-可选档案卷主题（纸面浅色案卷风，不替换默认）：挂载时加 `theme: 'archive'` 即换肤（右上大印章「待查/可装/安装中/待重启/受阻/已最新」+ 横幅小印章一字 + profile 牌 + 待重启衬线横幅配手绘 SVG 标 + 窄屏印章固定 + 省略号逐字折叠 + 浅深双主题跟随系统），内核 DOM 顺序不动、复制诊断常在；不传即最小可用默认深色样式。运行时用 `panel.setTheme('archive' | 'default')` 可切。旧值 `theme: 'archive'` 仍可用（同一套渲染）。入口件与批量面板是同一个 `theme` 参数，取值同一套。
-
+可选档案卷主题（纸面浅色案卷风，不替换默认）：挂载时加 `theme: 'archive'` 即换肤（右上大印章「待查/可装/安装中/待重启/受阻/已最新」+ 横幅小印章一字 + profile 牌 + 待重启衬线横幅配手绘 SVG 标 + 窄屏印章固定 + 省略号逐字折叠 + 浅深双主题跟随系统），内核 DOM 顺序不动、复制诊断常在；不传即最小可用默认深色样式。运行时用 `panel.setTheme('archive' | 'default')` 可切。入口件与批量面板是同一个 `theme` 参数，取值同一套。
+
+主题变量覆盖（第三方换肤）：四个 UI 口（单面板、批量面板、入口件、批量入口件）都收 `themeTokens`，键为语义名，一次传入即换肤，不传即零回归。入口件打开的 dialog 面板同步透传；运行时用 `setThemeTokens({...})` 即时换肤，传 `undefined` 即清掉覆盖：
+
+```js
+mountUpdatePanel(el, { pluginId: 'p', prefix: 'notes', call,
+  theme: 'archive',
+  themeTokens: { primary: '#c8402a', bg: '#fffdf6', radiusButton: '3px' },
+})
+```
+
+键与样式表里的 `--dsh-update-*` 变量一一对应（括号里是变量名），手写 CSS 变量等价生效：
+
+| 组 | 键（变量） |
+|---|---|
+| 文字背景边线 | `text`、`textMuted`、`bg`、`bgSoft`、`border`、`borderStrong`、`buttonBg` |
+| 主色焦点 | `primary`、`primaryDeep`、`focus` |
+| 状态四组 | `okBg / okBorder / okText`、`warnBg / warnBorder / warnText`、`badBg / badBorder / badText`、`busyBg / busyBorder / busyText` |
+| 字体阴影 | `fontSans`、`fontSerif`、`fontMono`、`shadow` |
+| 圆角 | `radiusPanel`、`radiusButton`、`radiusBadge` |
+| 入口件尺寸 | `entryFontSize`、`entryPadding`、`entryBorderRadius`、`entryScale`（数字，大于 0） |
+
+三条约束：颜色只收 hex（`#rgb`／`#rrggbb`／`#rrggbbaa`）或英文名单词（含 `transparent`），`rgb()`／`color-mix()` 请自行换算成 hex；其余值走注入检查（分号引号括号等不许过，见 `sizing` 同口径）；未知键与非法值挂载即抛错，不静默吞掉。被覆盖的 token 不再跟随深色模式（内联值固定，调用方自己保证深浅可读）。
+
 类型定义随包分发（`dsh-plugin-update/panel` 的 `.d.ts`），不用自编译；面板离线可读，与包版本绑定。
 
 整组件 HTTP 版（无 `host.call` 环境即跑：浏览器面板经 HTTP POST 直达宿主网关，只传三样）：

package/dist/entry-batch.d.ts

@@ -1,7 +1,7 @@
 import { type BilingualKey } from './bilingual.js';
 import { type AppLang, type LocaleOption } from './lang.js';
 import { type BatchRowView } from './panel-batch.js';
-import { type UpdatePanelTheme } from './panel.js';
+import { type UpdatePanelTheme, type UpdateThemeTokens } from './panel.js';
 /** 批量入口件的形态（与单入口同一套取值）。 */
 export type BatchEntryVariant = 'button' | 'badge' | 'inline';
 /** 什么时候主动查一次（只读；与单入口同一口径）。 */
@@ -42,6 +42,8 @@ export interface UpdateBatchEntryOptions {
     variant?: BatchEntryVariant;
     /** 主题：与单入口/面板同一套（default/archive）。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 panel 的 UpdateThemeTokens；批量入口根 + 打开的批量面板同步生效，不传即零回归。 */
+    themeTokens?: UpdateThemeTokens;
     /** 缺省 'mount'：进页面静默查一次（只调 .batchStatus，只读）。'never' 则只在用户点击时查。 */
     autoCheck?: BatchEntryAutoCheck;
     /** 打开面板自动查（#59 D3，透传给批量面板）：缺省 true；面板按用户偏好 > 本选项 > 缺省，并与入口预查共用知识时间戳去重（一击只查一次）。 */
@@ -82,6 +84,8 @@ export interface UpdateBatchEntryController {
     /** 当前聚合读数（含七档计数，接入方排版与 onActivate 共用）。 */
     summary(): BatchEntrySummary;
     setTheme(theme: UpdatePanelTheme): void;
+    /** 换一套主题变量（重绘；打开的批量面板同步；传 undefined 即清掉覆盖）。 */
+    setThemeTokens(tokens: UpdateThemeTokens | undefined): void;
     unmount(): void;
 }
 /**

package/dist/entry-batch.js

@@ -11,7 +11,8 @@ import {
 } from "./panel-batch.js";
 import {
   failureCodeOf,
-  normalizePanelTheme
+  normalizePanelTheme,
+  themeTokensStyleFor
 } from "./panel.js";
 function isObject(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -149,6 +150,8 @@ function mountUpdateBatchEntry(container, options) {
     throw new Error("[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 archive\uFF08\u6536\u5230 " + JSON.stringify(options.theme) + "\uFF09");
   }
   let theme = normalizePanelTheme(options.theme ?? "default");
+  themeTokensStyleFor(options.themeTokens ?? void 0);
+  let themeTokens = options.themeTokens;
   const pollMs = options.pollMs;
   if (pollMs !== void 0 && (typeof pollMs !== "number" || !Number.isFinite(pollMs) || pollMs < MIN_PANEL_POLL_MS)) {
     throw new Error("[dsh-plugin-update] \u9762\u677F\u8F6E\u8BE2\u95F4\u9694\u975E\u6CD5\uFF1A\u4E0D\u5F97\u5C0F\u4E8E 250 \u6BEB\u79D2\uFF08\u6536\u5230 " + JSON.stringify(options.pollMs) + "\uFF09");
@@ -220,9 +223,11 @@ function mountUpdateBatchEntry(container, options) {
     const labelText = labelOverride ?? (activating ? copyText("batch-entry.action.checking", lang) : copyText(batchEntryBilingualKeyFor(stateOf()), lang, batchEntryBilingualValuesFor(stateOf())));
     const busyAttr = activating ? ' disabled aria-busy="true"' : "";
     const themeAttr = theme === "archive" ? ' data-theme="archive"' : "";
+    const tokensStyle = themeTokensStyleFor(themeTokens ?? void 0);
+    const tokensAttr = tokensStyle ? ' style="' + tokensStyle + '"' : "";
     const control = variant === "badge" ? '<button type="button" class="dsh-upd-entry-dot" ' + ENTRY_ATTR + '="activate" title="' + escapeHtml(labelText) + '" aria-label="' + escapeHtml(labelText) + '"' + busyAttr + "></button>" : '<button type="button" class="dsh-upd-entry-btn" ' + ENTRY_ATTR + '="activate"' + busyAttr + ">" + labelHTML + "</button>";
     const noteHTML = note ? '<span class="dsh-upd-entry-note" data-dsh-upd-note="1">' + escapeHtml(note) + "</span>" : "";
-    return "<style>" + UPDATE_ENTRY_CSS + "\n" + BILINGUAL_CSS + '</style>\n<span class="dsh-upd-entry" data-variant="' + variant + '" data-state="' + summary.kind + '"' + themeAttr + ">" + control + noteHTML + "</span>";
+    return "<style>" + UPDATE_ENTRY_CSS + "\n" + BILINGUAL_CSS + '</style>\n<span class="dsh-upd-entry" data-variant="' + variant + '" data-state="' + summary.kind + '"' + themeAttr + tokensAttr + ">" + control + noteHTML + "</span>";
   }
   function render() {
     if (!mounted) return;
@@ -267,6 +272,7 @@ function mountUpdateBatchEntry(container, options) {
       prefix: options.prefix,
       mode,
       theme,
+      themeTokens,
       pollMs,
       titles,
       onRestartRequested: options.onRestartRequested,
@@ -346,6 +352,12 @@ function mountUpdateBatchEntry(container, options) {
     if (panel) void panel.setTheme(theme);
     else render();
   }
+  function setThemeTokens(next) {
+    themeTokensStyleFor(next ?? void 0);
+    themeTokens = next ?? void 0;
+    if (panel) void panel.setThemeTokens(themeTokens);
+    else render();
+  }
   function onClick(ev) {
     if (!mounted) return;
     try {
@@ -408,7 +420,7 @@ function mountUpdateBatchEntry(container, options) {
   if (variant === "inline") mountPanel("embedded");
   else render();
   if (autoCheck === "mount") void refresh();
-  return { refresh, open, close, label: currentLabel, summary: summaryOf, setTheme, unmount };
+  return { refresh, open, close, label: currentLabel, summary: summaryOf, setTheme, setThemeTokens, unmount };
 }
 export {
   batchEntryBilingualHTMLFor,

package/dist/entry.d.ts

@@ -1,4 +1,4 @@
-import { type UpdatePanelContainer, type UpdatePanelTheme } from './panel.js';
+import { type UpdatePanelContainer, type UpdatePanelTheme, type UpdateThemeTokens } from './panel.js';
 import type { UpdateSnapshot } from './ports.js';
 import { type BilingualKey } from './bilingual.js';
 import { type AppLang, type LocaleOption } from './lang.js';
@@ -24,7 +24,7 @@ export interface UpdateEntryState {
 /**
  * 入口件按钮尺寸覆盖（#69）：只影响 button 本体（字号/内边距/圆角/整体缩放），不碰 dialog 面板。
  * 缺省（不传）保持现状、零回归；badge 圆点与 inline 内嵌不读这些变量，天然不受影响。
- * 实现口径与现有 `--dsh-upd-*` 颜色变量一致：本选项只是把同样的 CSS 变量以内联方式写到容器上，
+ * 实现口径与现有 `--dsh-update-*` 颜色变量一致：本选项只是把同样的 CSS 变量以内联方式写到容器上，
  * 手写 CSS 变量（`--dsh-update-entry-font-size` / `--dsh-update-entry-padding` /
  * `--dsh-update-entry-border-radius` / `--dsh-update-entry-scale`）同样生效，两者等价。
  * `scale` 即宿主临时方案里容器 `zoom: 1` 开关的正式形态：改一个数即缩放（默认 1）。
@@ -46,7 +46,7 @@ export interface UpdateEntryOptions {
     /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
     call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     variant?: EntryVariant;
-    /** 主题：`default` 最小可用深色，`archive` 档案卷纸面浅色（仍可用）。 */
+    /** 主题：与面板同一套（`default` 最小可用，`archive` 档案卷纸面浅色）。 */
     theme?: UpdatePanelTheme;
     /** 缺省 'mount'：进页面静默查一次（只读）。'never' 则只在用户点击时查。 */
     autoCheck?: EntryAutoCheck;
@@ -56,6 +56,8 @@ export interface UpdateEntryOptions {
     label?: string;
     /** 按钮尺寸覆盖（#69）：见 EntrySizing；不传即零回归，badge/inline 不受影响。 */
     sizing?: EntrySizing;
+    /** 主题变量覆盖：见 panel 的 UpdateThemeTokens；入口件根 + 打开的 dialog 面板同步生效，不传即零回归。 */
+    themeTokens?: UpdateThemeTokens;
     /** 语言覆盖（#60 v2）：'zh' | 'en' | { getActive(): string; subscribe?(cb): () => void }，不传即跟随 html[lang] > navigator > zh。 */
     locale?: LocaleOption;
     profileName?: string;
@@ -82,6 +84,8 @@ export interface UpdateEntryController {
     /** 当前按钮上的状态文案（接入方做自定义排版时读它）。 */
     label(): string;
     setTheme(theme: UpdatePanelTheme): void;
+    /** 换一套主题变量（重绘；打开的 dialog 面板同步；传 undefined 即清掉覆盖）。 */
+    setThemeTokens(tokens: UpdateThemeTokens | undefined): void;
     unmount(): void;
 }
 /**

package/dist/entry.js

@@ -3,7 +3,8 @@ import { DEFAULT_PREFIX, MIN_PANEL_POLL_MS, buildPhoneNames } from "./config.js"
 import {
   failureCodeOf,
   mountUpdatePanel,
-  normalizePanelTheme
+  normalizePanelTheme,
+  themeTokensStyleFor
 } from "./panel.js";
 import { BILINGUAL_CSS, copyHTML, copyText } from "./bilingual.js";
 import { resolveLang, subscribeLang } from "./lang.js";
@@ -188,7 +189,8 @@ function mountUpdateEntry(container, options) {
   }
   const labelOverride = typeof options.label === "string" && options.label ? options.label : null;
   const sizingStyle = entrySizingStyleFor(options.sizing ?? void 0);
-  const sizingAttr = sizingStyle ? ` style="${sizingStyle}"` : "";
+  themeTokensStyleFor(options.themeTokens ?? void 0);
+  let themeTokens = options.themeTokens;
   const localeOpt = options.locale ?? void 0;
   if (localeOpt !== void 0 && localeOpt !== null) {
     const isStr = typeof localeOpt === "string";
@@ -250,11 +252,14 @@ function mountUpdateEntry(container, options) {
     const labelText = labelOverride ?? (activating ? copyText("entry.action.checking", lang) : copyText(entryBilingualKeyFor(stateOf()), lang, entryBilingualValuesFor(stateOf())));
     const busyAttr = activating ? ' disabled aria-busy="true"' : "";
     const themeAttr = theme === "archive" ? ' data-theme="archive"' : "";
+    const tokensStyle = themeTokensStyleFor(themeTokens ?? void 0);
+    const styleBody = [sizingStyle, tokensStyle].filter((part) => part).join(";");
+    const styleAttr = styleBody ? ` style="${styleBody}"` : "";
     const control = variant === "badge" ? `<button type="button" class="dsh-upd-entry-dot" ${ENTRY_ATTR}="activate" title="${escapeHtml(labelText)}" aria-label="${escapeHtml(labelText)}"${busyAttr}></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate"${busyAttr}>${labelHTML}</button>`;
     const noteHTML = noteVersion ? `<span class="dsh-upd-entry-note" data-dsh-upd-note="1">${copyHTML("entry.note.up-to-date", lang, { version: noteVersion })}</span>` : "";
     return `<style>${UPDATE_ENTRY_CSS}
 ${BILINGUAL_CSS}</style>
-<span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}${sizingAttr}>${control}${noteHTML}</span>`;
+<span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}${styleAttr}>${control}${noteHTML}</span>`;
   }
   function render() {
     if (!mounted) return;
@@ -299,6 +304,7 @@ ${BILINGUAL_CSS}</style>
       prefix,
       mode,
       theme,
+      themeTokens,
       pollMs,
       profileName,
       autoChangelog: options.autoChangelog,
@@ -366,6 +372,12 @@ ${BILINGUAL_CSS}</style>
     if (panel) void panel.setTheme(theme);
     else render();
   }
+  function setThemeTokens(next) {
+    themeTokensStyleFor(next ?? void 0);
+    themeTokens = next ?? void 0;
+    if (panel) void panel.setThemeTokens(themeTokens);
+    else render();
+  }
   function onClick(ev) {
     if (!mounted) return;
     try {
@@ -424,7 +436,7 @@ ${BILINGUAL_CSS}</style>
   if (variant === "inline") mountPanel("embedded");
   else render();
   if (autoCheck === "mount") void refresh();
-  return { refresh, open, close, label: currentLabel, setTheme, unmount };
+  return { refresh, open, close, label: currentLabel, setTheme, setThemeTokens, unmount };
 }
 export {
   UPDATE_ENTRY_CSS,

package/dist/panel-batch.d.ts

@@ -1,4 +1,4 @@
-import { type UpdatePanelTheme } from './panel.js';
+import { type UpdatePanelTheme, type UpdateThemeTokens } from './panel.js';
 /** 一行要画的东西（宿主回包里的形状）。 */
 export interface BatchRowView {
     key: string;
@@ -32,6 +32,8 @@ export interface BatchPanelOptions {
     call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     /** 主题：与单插件面板同一套（缺省 default）。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 panel 的 UpdateThemeTokens；批量根 + 展开详情行全继承，不传即零回归。 */
+    themeTokens?: UpdateThemeTokens;
     /** 摆放形态：内嵌或弹窗（缺省 embedded）。 */
     mode?: BatchPanelMode;
     /** 轮询间隔（毫秒，缺省 1500，下限 250）。 */
@@ -82,6 +84,8 @@ export interface BatchPanelController {
     refresh(): Promise<void>;
     act(action: BatchPanelActionKind, key?: string): Promise<void>;
     setTheme(theme: UpdatePanelTheme): void;
+    /** 换一套主题变量（重绘；传 undefined 即清掉覆盖，回主题默认）。 */
+    setThemeTokens(tokens: UpdateThemeTokens | undefined): void;
     setMode(mode: BatchPanelMode): void;
     unmount(): void;
 }
@@ -159,6 +163,8 @@ export declare function batchRowKnowledgeText(row: BatchRowView, entry: BatchKno
 export interface BatchPanelRenderInput {
     rows?: readonly BatchRowView[];
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 panel 的 UpdateThemeTokens；写到批量根上，详情行经继承生效。 */
+    themeTokens?: UpdateThemeTokens;
     mode?: BatchPanelMode;
     /** 当前展开的那一家（键）；null 即全部收起。 */
     expandedKey?: string | null;

package/dist/panel-batch.js

@@ -16,7 +16,8 @@ import {
   failureCopy,
   isKnownFailureCode,
   normalizePanelTheme,
-  renderUpdatePanelHTML
+  renderUpdatePanelHTML,
+  themeTokensStyleFor
 } from "./panel.js";
 const BATCH_PANEL_POLL = {
   defaultMs: 1500,
@@ -198,6 +199,7 @@ function renderBatchPanelHTML(input) {
     busy: installing,
     inFlight: input.inFlight === true,
     theme,
+    themeTokens: input.themeTokens ?? void 0,
     titles,
     skipped: null,
     notice: null,
@@ -285,8 +287,10 @@ function renderBatchPanelHTML(input) {
   const kernel = parts.join(String.fromCharCode(10));
   const archive = normalizePanelTheme(theme) === "archive";
   const attr = archive ? ' data-theme="archive"' : "";
+  const tokensStyle = themeTokensStyleFor(input.themeTokens ?? void 0);
+  const tokensAttr = tokensStyle ? ' style="' + tokensStyle + '"' : "";
   const seal = batchSealOf(counts, lang);
-  const root = '<div class="dsh-upd dsh-upd-batch" data-mode="' + mode + '" data-seal="' + escapeHtml(seal.text) + '" data-seal-tone="' + seal.tone + '"' + attr + ">\n" + kernel + "\n</div>";
+  const root = '<div class="dsh-upd dsh-upd-batch" data-mode="' + mode + '" data-seal="' + escapeHtml(seal.text) + '" data-seal-tone="' + seal.tone + '"' + attr + tokensAttr + ">\n" + kernel + "\n</div>";
   const body = mode === "dialog" ? '<div class="dsh-upd-overlay" data-mode="dialog">' + root + "</div>" : root;
   const css = archive ? [UPDATE_PANEL_CSS, UPDATE_BATCH_PANEL_CSS, UPDATE_PANEL_ARCHIVE_CSS, UPDATE_BATCH_PANEL_ARCHIVE_CSS].join(String.fromCharCode(10)) : [UPDATE_PANEL_CSS, UPDATE_BATCH_PANEL_CSS].join(String.fromCharCode(10));
   return "<style>" + css + "</style>\n" + body;
@@ -411,6 +415,7 @@ function detailHTML(row, ctx) {
     pluginId: pluginIdOf(row),
     copyNotice: null,
     theme: ctx.theme,
+    themeTokens: ctx.themeTokens,
     profileName: typeof row.profileName === "string" && row.profileName ? row.profileName : null,
     actions: "none"
   }, ctx.lang);
@@ -762,6 +767,8 @@ function mountUpdateBatchPanel(container, options) {
     throw new Error("[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 archive\uFF08\u6536\u5230 " + JSON.stringify(options.theme) + "\uFF09");
   }
   let theme = normalizePanelTheme(options.theme ?? "default");
+  themeTokensStyleFor(options.themeTokens ?? void 0);
+  let themeTokens = options.themeTokens;
   const call = options.call;
   const titles = options.titles && typeof options.titles === "object" ? options.titles : {};
   const onRestartRequested = options.onRestartRequested;
@@ -952,6 +959,7 @@ function mountUpdateBatchPanel(container, options) {
     const nextHTML = renderBatchPanelHTML({
       rows,
       theme,
+      themeTokens,
       mode,
       expandedKey,
       lastError,
@@ -1273,6 +1281,11 @@ function mountUpdateBatchPanel(container, options) {
     theme = normalizePanelTheme(next);
     render();
   }
+  function setThemeTokens(next) {
+    themeTokensStyleFor(next ?? void 0);
+    themeTokens = next ?? void 0;
+    render();
+  }
   function setMode(next) {
     if (next !== "embedded" && next !== "dialog") {
       throw new Error("[dsh-plugin-update] \u6446\u653E\u5F62\u6001\u975E\u6CD5\uFF1A\u53EA\u6536 embedded \u6216 dialog\uFF08\u6536\u5230 " + JSON.stringify(next) + "\uFF09");
@@ -1396,7 +1409,7 @@ function mountUpdateBatchPanel(container, options) {
   void refresh().then(() => {
     void autoOnce();
   });
-  return { refresh, act, setTheme, setMode, unmount };
+  return { refresh, act, setTheme, setThemeTokens, setMode, unmount };
 }
 export {
   BATCH_PANEL_POLL,

package/dist/panel.d.ts

@@ -6,7 +6,6 @@ export type UpdatePanelMode = 'embedded' | 'dialog';
 /** 面板主题：默认最小可用样式；`archive` 为档案卷纸面浅色（只换肤，不换 DOM 顺序）。 */
 /**
  * 面板主题：`default` 最小可用深色；`archive` 档案卷纸面浅色（原型敲定的案卷风格，只换肤）。
- * `archive` 是 archive 的旧别名（历史取值），仍可用，渲染逐字相同。
  */
 export type UpdatePanelTheme = 'default' | 'archive';
 /**
@@ -14,6 +13,50 @@ export type UpdatePanelTheme = 'default' | 'archive';
  * 其余一律回 default（纯渲染函数永不抛；挂载/setTheme 的非法值另行抛错）。
  */
 export declare function normalizePanelTheme(value: unknown): 'default' | 'archive';
+/** 第三方主题变量覆盖：键为语义名；颜色收 hex（#rgb/#rrggbb/#rrggbbaa）或英文名单词；其余收安全 CSS 值；缺省即主题默认值，零回归。 */
+export interface UpdateThemeTokens {
+    text?: string;
+    textMuted?: string;
+    bg?: string;
+    bgSoft?: string;
+    border?: string;
+    borderStrong?: string;
+    buttonBg?: string;
+    primary?: string;
+    primaryDeep?: string;
+    focus?: string;
+    okBg?: string;
+    okBorder?: string;
+    okText?: string;
+    warnBg?: string;
+    warnBorder?: string;
+    warnText?: string;
+    badBg?: string;
+    badBorder?: string;
+    badText?: string;
+    busyBg?: string;
+    busyBorder?: string;
+    busyText?: string;
+    fontSans?: string;
+    fontSerif?: string;
+    fontMono?: string;
+    shadow?: string;
+    radiusPanel?: string;
+    radiusButton?: string;
+    radiusBadge?: string;
+    entryFontSize?: string;
+    entryPadding?: string;
+    entryBorderRadius?: string;
+    /** 入口件整体缩放（对应 CSS `zoom`），须为大于 0 的有限数。 */
+    entryScale?: number;
+}
+/** CSS 值最小安全检查（与入口件 sizing 同口径）：放 style 属性前先拦掉注入。 */
+export declare function isSafeThemeCssValue(value: string): boolean;
+/**
+ * `themeTokens` → 根 style 属性体（纯函数：同一输入永远算出同一串；空/缺省回空串，即不写 style）。
+ * 非法即抛（未知键、空串、注入字符、颜色形状不对、非正有限 entryScale 都不收）。
+ */
+export declare function themeTokensStyleFor(tokens: UpdateThemeTokens | null | undefined): string;
 /** 与宿主通话的传输函数：面板只认这个签名，不认任何宿主对象的具体形状。 */
 export type UpdatePanelCall = (phoneName: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 复制文本的出口：不传即尝试浏览器剪贴板，都没有则只留“已生成、请手动复制”提示。 */
@@ -29,6 +72,8 @@ export interface UpdatePanelOptions {
     mode?: UpdatePanelMode;
     /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `archive` 切档案卷。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 UpdateThemeTokens；两个主题通用，不传即零回归。 */
+    themeTokens?: UpdateThemeTokens;
     /** 是否看他人排队明细：默认只看自己的（他人仅露正忙占位，位置照给）。 */
     showOthers?: boolean;
     /** 是否显示深挖日志指引：默认显示；面向纯终端用户的嵌入可关（失败证据行不受影响）。 */
@@ -90,6 +135,8 @@ export interface UpdatePanelController {
     setMode(mode: UpdatePanelMode): Promise<void>;
     /** 切换主题（同一内核重绘，只换肤；默认主题输出与旧版一字不差）。 */
     setTheme(theme: UpdatePanelTheme): Promise<void>;
+    /** 换一套主题变量（同一内核重绘，只换变量；传 undefined 即清掉覆盖，回主题默认）。 */
+    setThemeTokens(tokens: UpdateThemeTokens | undefined): Promise<void>;
     /** 切换排队可见性（重查一次，位置口径不变）。 */
     setShowOthers(show: boolean): Promise<void>;
     /** 收起/展开更新日志（纯视图态，不调电话；轮询与换肤不丢）。 */
@@ -256,6 +303,8 @@ export interface PanelRenderInput extends PanelViewInput {
     lang?: AppLang | string | null;
     /** 可选主题：不传即默认（输出与旧版一字不差）；`archive` 切档案卷。 */
     theme?: UpdatePanelTheme;
+    /** 主题变量覆盖：见 UpdateThemeTokens；写到面板根上，不传即无 style 属性。 */
+    themeTokens?: UpdateThemeTokens;
     /** 使用范围名（profile）：面板「使用范围」一栏的唯一来源，缺省显示“未知”，不猜。 */
     profileName?: string | null;
     /** 宿主种类：进诊断文本；缺省显示“未知”。 */

package/dist/panel.js

@@ -15,6 +15,106 @@ import { normalizeLangTag, resolveLang, subscribeLang } from "./lang.js";
 function normalizePanelTheme(value) {
   return value === "archive" ? "archive" : "default";
 }
+const THEME_TOKEN_VARS = {
+  text: "--dsh-update-text",
+  textMuted: "--dsh-update-text-muted",
+  bg: "--dsh-update-bg",
+  bgSoft: "--dsh-update-bg-soft",
+  border: "--dsh-update-border",
+  borderStrong: "--dsh-update-border-strong",
+  buttonBg: "--dsh-update-button-bg",
+  primary: "--dsh-update-primary",
+  primaryDeep: "--dsh-update-primary-deep",
+  focus: "--dsh-update-focus",
+  okBg: "--dsh-update-ok-bg",
+  okBorder: "--dsh-update-ok-border",
+  okText: "--dsh-update-ok-text",
+  warnBg: "--dsh-update-warn-bg",
+  warnBorder: "--dsh-update-warn-border",
+  warnText: "--dsh-update-warn-text",
+  badBg: "--dsh-update-bad-bg",
+  badBorder: "--dsh-update-bad-border",
+  badText: "--dsh-update-bad-text",
+  busyBg: "--dsh-update-busy-bg",
+  busyBorder: "--dsh-update-busy-border",
+  busyText: "--dsh-update-busy-text",
+  fontSans: "--dsh-update-font-sans",
+  fontSerif: "--dsh-update-font-serif",
+  fontMono: "--dsh-update-font-mono",
+  shadow: "--dsh-update-shadow",
+  radiusPanel: "--dsh-update-radius-panel",
+  radiusButton: "--dsh-update-radius-button",
+  radiusBadge: "--dsh-update-radius-badge",
+  entryFontSize: "--dsh-update-entry-font-size",
+  entryPadding: "--dsh-update-entry-padding",
+  entryBorderRadius: "--dsh-update-entry-border-radius",
+  entryScale: "--dsh-update-entry-scale"
+};
+const THEME_TOKEN_COLOR_KEYS = /* @__PURE__ */ new Set([
+  "text",
+  "textMuted",
+  "bg",
+  "bgSoft",
+  "border",
+  "borderStrong",
+  "buttonBg",
+  "primary",
+  "primaryDeep",
+  "focus",
+  "okBg",
+  "okBorder",
+  "okText",
+  "warnBg",
+  "warnBorder",
+  "warnText",
+  "badBg",
+  "badBorder",
+  "badText",
+  "busyBg",
+  "busyBorder",
+  "busyText"
+]);
+function themeTokensError(raw) {
+  return new Error(`[dsh-plugin-update] \u4E3B\u9898\u53C2\u6570 themeTokens \u975E\u6CD5\uFF1A\u53EA\u6536\u5DF2\u77E5 token \u952E\uFF08\u989C\u8272\u7528 hex \u6216\u82F1\u6587\u540D\uFF0C\u5B57\u4F53/\u5706\u89D2/\u9634\u5F71/\u5C3A\u5BF8\u4E3A\u5B89\u5168 CSS \u503C\uFF0CentryScale \u4E3A\u5927\u4E8E 0 \u7684\u6709\u9650\u6570\uFF09\uFF08\u6536\u5230 ${JSON.stringify(raw ?? null)})`);
+}
+function isSafeThemeCssValue(value) {
+  const v = value.trim();
+  if (!v || v.length > 200) return false;
+  if (/[;"'<>\`{}!&]/.test(v)) return false;
+  if (/url\s*\(/i.test(v)) return false;
+  if (/expression\s*\(/i.test(v)) return false;
+  if (/javascript\s*:/i.test(v)) return false;
+  return true;
+}
+function isThemeColorValue(value) {
+  const v = value.trim();
+  if (!v || v.length > 100) return false;
+  return /^(?:#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8}|[a-zA-Z]+)$/.test(v);
+}
+function themeTokensStyleFor(tokens) {
+  if (tokens === void 0 || tokens === null) return "";
+  if (typeof tokens !== "object" || Array.isArray(tokens)) throw themeTokensError(tokens);
+  for (const key of Object.keys(tokens)) {
+    if (!Object.prototype.hasOwnProperty.call(THEME_TOKEN_VARS, key)) throw themeTokensError(tokens);
+  }
+  const parts = [];
+  for (const key of Object.keys(THEME_TOKEN_VARS)) {
+    const value = tokens[key];
+    if (value === void 0) continue;
+    if (key === "entryScale") {
+      if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw themeTokensError(tokens);
+      parts.push(THEME_TOKEN_VARS[key] + ":" + String(value));
+      continue;
+    }
+    if (typeof value !== "string") throw themeTokensError(tokens);
+    const text = value.trim();
+    if (THEME_TOKEN_COLOR_KEYS.has(key)) {
+      if (!isThemeColorValue(text)) throw themeTokensError(tokens);
+    } else if (!isSafeThemeCssValue(text)) throw themeTokensError(tokens);
+    parts.push(THEME_TOKEN_VARS[key] + ":" + text);
+  }
+  return parts.join(";");
+}
 const BLOCKED_KEYS = {
   "unknown-profile": { title: "panel.blocked.unknown-profile.title", action: "panel.blocked.unknown-profile.action" },
   "source-install": { title: "panel.blocked.source-install.title", action: "panel.blocked.source-install.action" },
@@ -1005,10 +1105,12 @@ function renderUpdatePanelHTML(input, lang) {
   const kernel = renderUpdatePanelKernel(input, view, l);
   const archive = normalizePanelTheme(input.theme) === "archive";
   const attr = archive ? ' data-theme="archive"' : "";
+  const tokensStyle = themeTokensStyleFor(input.themeTokens ?? void 0);
+  const tokensAttr = tokensStyle ? ` style="${tokensStyle}"` : "";
   const sealAttr = ` data-seal="${escapeHtml(view.seal.text)}" data-seal-tone="${view.seal.tone}"`;
-  const body = input.mode === "dialog" ? `<div class="dsh-upd-overlay" data-mode="dialog"><div class="dsh-upd" data-mode="dialog" data-plugin="${escapeHtml(input.pluginId)}"${sealAttr}${attr}>
+  const body = input.mode === "dialog" ? `<div class="dsh-upd-overlay" data-mode="dialog"><div class="dsh-upd" data-mode="dialog" data-plugin="${escapeHtml(input.pluginId)}"${sealAttr}${attr}${tokensAttr}>
 ${kernel}
-</div></div>` : `<div class="dsh-upd" data-mode="embedded" data-plugin="${escapeHtml(input.pluginId)}"${sealAttr}${attr}>
+</div></div>` : `<div class="dsh-upd" data-mode="embedded" data-plugin="${escapeHtml(input.pluginId)}"${sealAttr}${attr}${tokensAttr}>
 ${kernel}
 </div>`;
   const css = archive ? `${UPDATE_PANEL_CSS}
@@ -1110,6 +1212,8 @@ function mountUpdatePanel(container, options) {
     throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 archive\uFF08\u6536\u5230 ${JSON.stringify(options.theme)}\uFF09`);
   }
   let theme = normalizePanelTheme(options.theme ?? "default");
+  themeTokensStyleFor(options.themeTokens ?? void 0);
+  let themeTokens = options.themeTokens;
   const localeOpt = options.locale ?? void 0;
   if (localeOpt !== void 0 && localeOpt !== null) {
     const isStr = typeof localeOpt === "string";
@@ -1426,6 +1530,7 @@ function mountUpdatePanel(container, options) {
       pluginId,
       copyNotice,
       theme,
+      themeTokens,
       // 使用范围与宿主种类：调用方显式传的优先，否则用宿主回的真值。
       profileName: profileNameOption ?? envProfileName,
       hostKind: hostKind ?? envHostKind
@@ -1807,6 +1912,11 @@ function mountUpdatePanel(container, options) {
     theme = normalizePanelTheme(next);
     render();
   }
+  async function setThemeTokens(next) {
+    themeTokensStyleFor(next ?? void 0);
+    themeTokens = next ?? void 0;
+    render();
+  }
   async function setShowOthers(show) {
     showOthers = show === true;
     await refresh();
@@ -1899,7 +2009,7 @@ function mountUpdatePanel(container, options) {
     } catch {
     }
   })();
-  return { refresh, act, setMode, setTheme, setShowOthers, setChangelogCollapsed, setChangelogMarkdown, unmount };
+  return { refresh, act, setMode, setTheme, setThemeTokens, setShowOthers, setChangelogCollapsed, setChangelogMarkdown, unmount };
 }
 import { buildPhoneNames as buildPhoneNames2 } from "./config.js";
 import { buildChangelogPhoneName as buildChangelogPhoneName2 } from "./config.js";
@@ -1968,6 +2078,7 @@ export {
   isHeadOfQueue,
   isKnownFailureCode,
   isQueueBusy,
+  isSafeThemeCssValue,
   isUnreleasedVersion,
   mountUpdatePanel,
   normalizePanelTheme,
@@ -1985,5 +2096,6 @@ export {
   renderUpdatePanelHTML,
   renderUpdatePanelKernel,
   selectChangelogEntries,
+  themeTokensStyleFor,
   visibleQueueFor2 as visibleQueueFor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",