@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/plugin-runtime/plugin-client-tools.ts

@@ -17,57 +17,40 @@
 
 // 客户端工具工厂：为 useHarnessChat 提供 client tool 实现
 // 插件生命周期五工具的 client 半（plugin_run/stop/undefine）+ 动态插件工具
+//
+// 定义单源：全部经 lib/plugin-runtime/plugin-tool-defs.ts 的 toolDefinition
+// 导出以 .client() 形态实例化（官方 client-tools 模式）——1.0 硬约束：客户端
+// 工具仅在与服务端 tool schema 一致（含 outputSchema）时执行，不一致会静默
+// 退化为 generic interrupt（无报错、工具不执行）。执行体沿用
+// executePluginClientTool 分派，行为与手写 JSON-Schema 桩时期零变化。
 
+import type { AnyClientTool } from "@tanstack/ai/client";
 import {
   stopPlugin,
   invokeTool,
   getLoadedPlugins,
 } from "@/lib/plugin-runtime/plugin-client";
+import {
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  buildPluginDynamicToolDef,
+} from "@/lib/plugin-runtime/plugin-tool-defs";
 
-export interface ClientToolStub {
-  name: string;
-  description: string;
-  parameters: any;
-}
-
-const pluginRunClientTool: ClientToolStub = {
-  name: "plugin_run",
-  description: "启动一个已定义的插件，在浏览器 Worker 中求值源码并注册工具",
-  parameters: {
-    type: "object",
-    properties: {
-      name: { type: "string", description: "插件名称" },
-    },
-    required: ["name"],
-  },
-};
+const pluginRunClientTool = pluginRunDef.client((args) =>
+  executePluginClientTool("plugin_run", args)
+);
 
-const pluginStopClientTool: ClientToolStub = {
-  name: "plugin_stop",
-  description: "停止一个正在运行的插件",
-  parameters: {
-    type: "object",
-    properties: {
-      name: { type: "string", description: "插件名称" },
-    },
-    required: ["name"],
-  },
-};
+const pluginStopClientTool = pluginStopDef.client((args) =>
+  executePluginClientTool("plugin_stop", args)
+);
 
-const pluginUndefineClientTool: ClientToolStub = {
-  name: "plugin_undefine",
-  description: "删除一个插件（软删除）",
-  parameters: {
-    type: "object",
-    properties: {
-      name: { type: "string", description: "插件名称" },
-    },
-    required: ["name"],
-  },
-};
+const pluginUndefineClientTool = pluginUndefineDef.client((args) =>
+  executePluginClientTool("plugin_undefine", args)
+);
 
-export function buildPluginClientTools(): ClientToolStub[] {
-  const tools: ClientToolStub[] = [
+export function buildPluginClientTools(): AnyClientTool[] {
+  const tools: AnyClientTool[] = [
     pluginRunClientTool,
     pluginStopClientTool,
     pluginUndefineClientTool,
@@ -76,11 +59,10 @@ export function buildPluginClientTools(): ClientToolStub[] {
   const loadedPlugins = getLoadedPlugins();
   for (const plugin of loadedPlugins) {
     for (const tool of plugin.tools) {
-      tools.push({
-        name: `plugin__${plugin.pluginId}__${tool.name}`,
-        description: `[${plugin.pluginId}] ${tool.description}`,
-        parameters: tool.inputSchema,
-      });
+      const def = buildPluginDynamicToolDef(plugin.pluginId, tool);
+      tools.push(
+        def.client((args) => executePluginClientTool(def.name, args))
+      );
     }
   }
 

package/src/lib/plugin-runtime/plugin-tool-defs.ts

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 插件工具定义单源（isomorphic 纯净模块）：服务端注册表（server/ai-gateway
+// tools）与客户端执行工厂（lib/plugin-runtime/plugin-client-tools.ts）都从
+// 本模块取 toolDefinition 导出，保证 inputSchema + outputSchema 双侧一致。
+// 1.0 硬约束：客户端工具仅在与服务端 tool schema 一致（含 outputSchema）时
+// 才执行，不一致会静默退化为 generic interrupt（无报错、工具不执行）。
+//
+// ⚠ 客户端纯净性硬规则：本模块只准 import zod 与 @tanstack/ai，零
+// prisma/auth 等 server-only 依赖——客户端 bundle 会经
+// plugin-client-tools.ts 拉入本模块。服务端 execute 装配见
+// server/ai-gateway/tools/plugin-lifecycle-server.ts（.server() 形态）。
+
+import { toolDefinition } from "@tanstack/ai";
+import { z } from "zod";
+
+export const pluginDefineDef = toolDefinition({
+  name: "plugin_define",
+  description:
+    "定义或更新一个 dsh 兼容插件。插件源码会在用户浏览器 Worker 中求值，" +
+    "支持 host/client 双半源码、自定义工具注册。提交后需用户审批才会生效。",
+  needsApproval: true,
+  inputSchema: z.object({
+    name: z.string().min(1).max(64).describe("插件名称，唯一标识"),
+    purpose: z.string().min(1).max(512).describe("插件用途说明"),
+    codeHost: z
+      .string()
+      .max(64_000)
+      .optional()
+      .describe("服务端半源码（浏览器 Worker 内求值，ctx/harness 契约面）"),
+    codeClient: z
+      .string()
+      .max(64_000)
+      .optional()
+      .describe("客户端半源码（UI 侧交互逻辑）"),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    version: z.number(),
+    status: z.string(),
+  }),
+});
+
+export const pluginRunDef = toolDefinition({
+  name: "plugin_run",
+  description: "启动一个已定义的插件，在浏览器 Worker 中求值源码并注册工具",
+  needsApproval: true,
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    started: z.boolean(),
+    tools: z.array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+        inputSchema: z.any(),
+      })
+    ),
+    error: z.string().optional(),
+  }),
+});
+
+export const pluginStopDef = toolDefinition({
+  name: "plugin_stop",
+  description: "停止一个正在运行的插件",
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    stopped: z.boolean(),
+  }),
+});
+
+export const pluginUndefineDef = toolDefinition({
+  name: "plugin_undefine",
+  description: "删除一个插件（软删除，标记 isDeleted）",
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    deleted: z.boolean(),
+  }),
+});
+
+export const pluginInspectListDef = toolDefinition({
+  name: "plugin_inspect_list",
+  description: "列出当前用户的所有插件及其状态",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    plugins: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        purpose: z.string(),
+        version: z.number(),
+        status: z.string(),
+        tools: z.array(
+          z.object({
+            name: z.string(),
+            description: z.string(),
+          })
+        ),
+      })
+    ),
+  }),
+});
+
+export const pluginLifecycleDefs = [
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+];
+
+// ---- 动态插件工具（plugin__<pluginName>__<toolName>）----
+
+/** 插件在 Worker/DB 侧声明的工具规格（与 plugin-client.ts 的 PluginToolDef 同形） */
+export interface PluginDynamicToolSpec {
+  name: string;
+  description: string;
+  inputSchema?: any;
+}
+
+// 三段前缀：plugin__<pluginName>__<toolName>（运行期与内置工具名隔离）
+export function buildPluginDynamicToolDef(
+  pluginName: string,
+  tool: PluginDynamicToolSpec
+) {
+  return toolDefinition({
+    name: `plugin__${pluginName}__${tool.name}`,
+    description: `[${pluginName}] ${tool.description}`,
+    // 同源回落口径：与服务端注册一致，缺 schema 时回落空对象 JSON Schema
+    inputSchema: tool.inputSchema || { type: "object", properties: {} },
+  });
+}

package/src/lib/project-module-meta.ts

@@ -21,14 +21,13 @@ import {
   Palette,
   FlaskConical,
   Bug,
-  CircleCheckBig,
 } from "lucide-react";
 import type {
   ProjectModuleKey,
   ProjectModuleOverview,
 } from "@/types/project";
 
-// 6 个板块元数据（key 与路由 $module 对应）
+// 5 个板块元数据（key 与路由 $module 对应）
 export const PROJECT_MODULE_META: Record<
   ProjectModuleKey,
   Omit<ProjectModuleOverview, "count" | "lastUpdatedAt" | "link">
@@ -63,12 +62,6 @@ export const PROJECT_MODULE_META: Record<
     description: "缺陷跟踪与修复进度",
     icon: Bug,
   },
-  acceptance: {
-    key: "acceptance",
-    title: "验收",
-    description: "交付验收与上线检查",
-    icon: CircleCheckBig,
-  },
 };
 
 export const PROJECT_MODULE_KEYS = Object.keys(

package/src/lib/rate-limit.ts

@@ -22,18 +22,27 @@
 const rateLimitMap = new Map<string, { count: number; resetTime: number }>()
 
 const CLEANUP_INTERVAL = 60_000
-setInterval(() => {
-  const now = Date.now()
-  for (const [key, entry] of rateLimitMap) {
-    if (now > entry.resetTime) rateLimitMap.delete(key)
-  }
-}, CLEANUP_INTERVAL)
+// 清扫定时器懒启动：workerd 禁止 global scope（模块顶层）设定时器，
+// 首次 rateLimit() 调用时才开启（浏览器/Node 行为不变）。
+let cleanupStarted = false
+function ensureCleanupTimer() {
+  if (cleanupStarted) return
+  cleanupStarted = true
+  const timer = setInterval(() => {
+    const now = Date.now()
+    for (const [key, entry] of rateLimitMap) {
+      if (now > entry.resetTime) rateLimitMap.delete(key)
+    }
+  }, CLEANUP_INTERVAL)
+  timer.unref?.()
+}
 
 export function rateLimit(
   key: string,
   limit: number,
   windowMs: number = 60_000
 ): { success: boolean; remaining: number } {
+  ensureCleanupTimer()
   const now = Date.now()
   const entry = rateLimitMap.get(key)
 

package/src/lib/sanitize.ts

@@ -1,18 +1,130 @@
-import DOMPurify from 'isomorphic-dompurify'
+import sanitizeHtml from 'sanitize-html'
 
-// HTML 清理：默认配置（html + svg + mathMl profile 均启用），
-// 覆盖富文本 diff、附件预览等 7 处 HTML 渲染场景。
+// HTML/SVG 清理：sanitize-html 纯 JS 实现（htmlparser2，无 DOM 依赖），
+// 浏览器 / Node(Vercel) / workerd(Cloudflare) 三端通用。
+//
+// 替换 isomorphic-dompurify 的原因：其服务端分支拉起 jsdom，而 jsdom 在
+// workerd 无法加载（实测 `__dirname is not defined`；jsdom-on-serverless
+// 在 Vercel 端也已累计两个运行时补丁——长期负债）。SSR 渲染的客户端组件
+// （富文本 diff、附件预览、NotionAvatar）会让该链进入服务端 bundle。
+//
+// 白名单镜像 DOMPurify 默认 profile（html + svg）的语义：
+// - 脚本/iframe/事件处理器/javascript: 协议由 allowedTags/allowedAttributes/
+//   allowedSchemes 清除（script 属 sanitize-html 默认 nonTextTags，内容整体丢弃）
+// - SVG 滤镜链（fe* 系列）显式放行，NotionAvatar 头像辉光依赖
+//   （对齐 __tests__/security/xss-sanitize.test.ts 的双向断言）
+// - 标签/属性名输出为小写：HTML 解析层对内联 SVG 有大小写自适应表
+//   （viewbox→viewBox、filterunits→filterUnits 等），渲染语义不变
+const SVG_TAGS = [
+  'svg', 'defs', 'filter', 'g', 'path', 'circle', 'rect', 'line', 'ellipse',
+  'polyline', 'polygon', 'text', 'tspan', 'use', 'symbol', 'title', 'desc',
+  'stop', 'lineargradient', 'radialgradient', 'clippath', 'mask', 'pattern',
+  'marker', 'femorphology', 'feflood', 'fecomposite', 'femerge', 'femergenode',
+  'feblend', 'fecolormatrix', 'fegaussianblur', 'feoffset',
+]
+
+const ALLOWED_TAGS = [
+  ...sanitizeHtml.defaults.allowedTags,
+  'img',
+  ...SVG_TAGS,
+]
+
+const SVG_ATTRS = [
+  'viewbox', 'fill', 'fill-opacity', 'fill-rule', 'stroke', 'stroke-width',
+  'stroke-linecap', 'stroke-linejoin', 'stroke-opacity', 'stroke-dasharray',
+  'stroke-dashoffset', 'd', 'x', 'y', 'x1', 'x2', 'y1', 'y2', 'cx', 'cy', 'r',
+  'rx', 'ry', 'width', 'height', 'points', 'transform', 'transform-origin',
+  'opacity', 'offset', 'stddeviation', 'operator', 'radius', 'in', 'in2',
+  'result', 'values', 'type', 'from', 'to', 'dur', 'repeatcount',
+  'flood-color', 'flood-opacity',
+  'filterunits', 'primitiveunits', 'color-interpolation-filters', 'filter',
+  'mask', 'clip-path', 'clip-rule', 'clippathunits', 'maskunits',
+  'maskcontentunits', 'patternunits', 'patterncontentunits', 'gradientunits',
+  'gradienttransform', 'spreadmethod', 'fx', 'fy', 'xmlns',
+  'xmlns:xlink', 'preserveaspectratio', 'version', 'encoding', 'pathlength',
+  'textlength', 'lengthadjust', 'startoffset', 'dominant-baseline',
+  'basefrequency', 'numoctaves', 'seed', 'surfacescale', 'specularconstant',
+  'specularexponent', 'k1', 'k2', 'k3', 'k4', 'xchannelselector',
+  'ychannelselector', 'zoomandpan', 'stroke-miterlimit',
+]
+
+const GLOBAL_ATTRS = [
+  'class', 'id', 'style', 'title', 'hidden', 'dir', 'lang', 'role',
+  'aria-hidden', 'aria-label', 'aria-labelledby',
+]
+
+const OPTIONS: sanitizeHtml.IOptions = {
+  allowedTags: ALLOWED_TAGS,
+  allowedAttributes: {
+    ...sanitizeHtml.defaults.allowedAttributes,
+    '*': GLOBAL_ATTRS,
+    a: ['href', 'name', 'target', 'rel'],
+    img: ['src', 'srcset', 'alt', 'width', 'height', 'loading'],
+    svg: SVG_ATTRS,
+    ...Object.fromEntries(SVG_TAGS.map((t) => [t, SVG_ATTRS])),
+  },
+  // SVG 自闭合元素（<feX .../>）：htmlparser2 非 XML 模式默认把 `/>` 当开标签，
+  // 未闭合的元素会被整体吞掉——selfClosing 列表必须全小写（解析器先小写化再匹配）
+  selfClosing: [
+    ...sanitizeHtml.defaults.selfClosing,
+    'path', 'circle', 'rect', 'line', 'ellipse', 'polyline', 'polygon',
+    'stop', 'use', 'femorphology', 'feflood', 'fecomposite', 'feblend',
+    'fecolormatrix', 'fegaussianblur', 'feoffset', 'femergenode',
+  ],
+  allowedSchemes: sanitizeHtml.defaults.allowedSchemes,
+  allowedSchemesByTag: {
+    ...sanitizeHtml.defaults.allowedSchemesByTag,
+    img: ['http', 'https', 'data'],
+  },
+  // htmlparser2 v9 不再小写化标签/属性名，而白名单按小写匹配——驼峰 SVG 标签
+  // （feMorphology 等）会整体连子树丢弃。transformTags 统一小写化；
+  // 浏览器 HTML 解析层对内联 SVG 有大小写自适应表，渲染语义不受影响。
+  transformTags: {
+    "*": (tagName: string, attribs: Record<string, string>) => {
+      const lowerAttribs: Record<string, string> = {}
+      for (const [k, v] of Object.entries(attribs)) lowerAttribs[k.toLowerCase()] = v
+      return { tagName: tagName.toLowerCase(), attribs: lowerAttribs }
+    },
+  },
+  // style 属性交给上面的白名单后，sanitize-html 会对 CSS 做解析过滤
+  // （javascript: 等危险表达式被清除）；无需 parseStyleAttributes 关闭
+}
+
+/**
+ * 结果缓存：sanitize-html 每次都要完整解析 + 遍历 DOM，而调用点普遍在渲染期
+ * （NotionAvatar 把 `sanitizeSvg(svgContent)` 直接放进 dangerouslySetInnerHTML →
+ * 组件每次重渲染都重解析一只头像的整段 SVG；看板一次拖拽起手会触发几十张卡重渲染，
+ * 实测命中 100ms+ 主线程）。输入相同时结果必然相同，故可安全缓存。
+ */
+const SANITIZE_CACHE_MAX = 512
+const htmlCache = new Map<string, string>()
+const svgCache = new Map<string, string>()
+
+function cachedSanitize(
+  cache: Map<string, string>,
+  input: string,
+  compute: () => string,
+): string {
+  const hit = cache.get(input)
+  if (hit !== undefined) return hit
+  const value = compute()
+  if (cache.size >= SANITIZE_CACHE_MAX) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+  cache.set(input, value)
+  return value
+}
+
+// HTML 清理：默认配置覆盖富文本 diff、附件预览等 7 处 HTML 渲染场景。
 export function sanitize(html: string): string {
-  return DOMPurify.sanitize(html)
+  return cachedSanitize(htmlCache, html, () => sanitizeHtml(html, OPTIONS))
 }
 
-// SVG 清理：头像渲染（NotionAvatar）专用。
-// 显式复用默认配置——DOMPurify 默认 profile 已包含 SVG 滤镜元素
-// （<defs>/<filter>/<feMorphology>/<feFlood>/<feComposite>/<feMerge>/<feMergeNode>），
-// 同时清除 <script>/on*/javascript: 等 XSS 载荷。
-// 禁止改成 USE_PROFILES: { svg: true }——严格 SVG profile 会移除全部 fe* 滤镜元素，
+// SVG 清理：头像渲染（NotionAvatar）专用，与 sanitize 同一白名单。
+// SVG 滤镜元素（fe* 系列）显式保留——严格白名单会移除全部滤镜元素，
 // 头像轮廓辉光（feMorphology+feFlood+feComposite+feMerge）会失效渲染白屏。
 // 结构完整性由 __tests__/security/xss-sanitize.test.ts 的双向断言锁定。
 export function sanitizeSvg(svg: string): string {
-  return DOMPurify.sanitize(svg)
+  return cachedSanitize(svgCache, svg, () => sanitizeHtml(svg, OPTIONS))
 }

package/src/lib/share-events.ts

@@ -22,23 +22,32 @@ const MAX_CLIENTS_PER_Design = 20;
 const CLEANUP_INTERVAL = 60_000;
 const IDLE_TIMEOUT = 5 * 60_000;
 
-setInterval(() => {
-  const now = Date.now();
-  for (const [designId, set] of clients) {
-    for (const controller of set) {
-      try {
-        controller.enqueue(new TextEncoder().encode(":cleanup-ping\n\n"));
-      } catch {
-        set.delete(controller);
+// 清扫定时器懒启动：workerd 禁止 global scope（模块顶层）设定时器，
+// 首个 SSE 客户端注册（handler 上下文）时才开启（Node 行为不变）。
+let cleanupStarted = false;
+function ensureCleanupTimer() {
+  if (cleanupStarted) return;
+  cleanupStarted = true;
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const [designId, set] of clients) {
+      for (const controller of set) {
+        try {
+          controller.enqueue(new TextEncoder().encode(":cleanup-ping\n\n"));
+        } catch {
+          set.delete(controller);
+        }
       }
+      if (set.size === 0) clients.delete(designId);
     }
-    if (set.size === 0) clients.delete(designId);
-  }
-}, CLEANUP_INTERVAL);
+  }, CLEANUP_INTERVAL);
+  timer.unref?.();
+}
 
 const controllerMeta = new WeakMap<ReadableStreamDefaultController, number>();
 
 export function addClient(designId: string, controller: ReadableStreamDefaultController) {
+  ensureCleanupTimer();
   const set = clients.get(designId);
   if (set && set.size >= MAX_CLIENTS_PER_Design) {
     throw new Error("连接数已达上限");

package/src/lib/sidebar-utils.ts

@@ -20,7 +20,7 @@ export function isParentActive(pathname: string, parentLink: string): boolean {
   return pathname === parentLink;
 }
 
-// 用于没有列出子菜单项的父级（如 /tags：子路由 /tags/settings、/tags/$id 不是菜单项）。
+// 用于没有列出子菜单项的父级（如 /knowledge：子路由详情页不是菜单项）。
 // 精确匹配会让这些页面下父级完全不高亮，故子路径同样视为激活。
 export function isPathActive(pathname: string, link: string): boolean {
   if (!link || link === "#") return false;

package/src/lib/theme/__tests__/theme-mode.test.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { describe, it, expect } from "vitest";
+import {
+  isTimeDark,
+  resolveAutoTheme,
+  resolveTheme,
+  parseStoredMode,
+  DEFAULT_MODE,
+  TIME_DARK_START,
+  TIME_DARK_END,
+} from "../theme-mode";
+
+// 用本地时间构造日期：isTimeDark 读取 getHours/getMinutes（本地时区）
+const at = (h: number, m = 0) => new Date(2026, 0, 1, h, m, 0);
+
+describe("isTimeDark", () => {
+  it("默认时段 18:00–次日 06:00：夜间为深色", () => {
+    expect(isTimeDark(at(20))).toBe(true);
+    expect(isTimeDark(at(23, 59))).toBe(true);
+    expect(isTimeDark(at(3))).toBe(true);
+  });
+
+  it("默认时段：白天为浅色（06:00–18:00）", () => {
+    expect(isTimeDark(at(12))).toBe(false);
+    expect(isTimeDark(at(8))).toBe(false);
+  });
+
+  it("边界：起点 18:00 含、终点 06:00 不含", () => {
+    expect(isTimeDark(at(TIME_DARK_START))).toBe(true);
+    expect(isTimeDark(at(TIME_DARK_END))).toBe(false);
+    expect(isTimeDark(at(TIME_DARK_END - 1))).toBe(true);
+  });
+
+  it("非跨午夜时段（9:00–17:00）按常规区间判定", () => {
+    expect(isTimeDark(at(10), 9, 17)).toBe(true);
+    expect(isTimeDark(at(20), 9, 17)).toBe(false);
+    expect(isTimeDark(at(17), 9, 17)).toBe(false);
+    expect(isTimeDark(at(9), 9, 17)).toBe(true);
+  });
+});
+
+describe("resolveAutoTheme（自动规则：系统 + 时间，任一为深即深色）", () => {
+  it("深色时段内即便系统为浅色也走深色", () => {
+    expect(resolveAutoTheme(false, at(22))).toBe("dark");
+  });
+
+  it("白天跟随系统外观", () => {
+    expect(resolveAutoTheme(true, at(10))).toBe("dark");
+    expect(resolveAutoTheme(false, at(10))).toBe("light");
+  });
+});
+
+describe("resolveTheme（手动优先）", () => {
+  it("手动 light/dark 不受系统与时间影响", () => {
+    expect(resolveTheme("light", true, at(23))).toBe("light");
+    expect(resolveTheme("dark", false, at(12))).toBe("dark");
+  });
+
+  it("auto 走自动规则", () => {
+    expect(resolveTheme("auto", false, at(22))).toBe("dark");
+    expect(resolveTheme("auto", false, at(10))).toBe("light");
+  });
+});
+
+describe("parseStoredMode", () => {
+  it("只认手动明暗", () => {
+    expect(parseStoredMode("light")).toBe("light");
+    expect(parseStoredMode("dark")).toBe("dark");
+  });
+
+  it("缺失 / 旧值 / 垃圾值回落 auto", () => {
+    expect(parseStoredMode(null)).toBe(DEFAULT_MODE);
+    expect(parseStoredMode(undefined)).toBe(DEFAULT_MODE);
+    expect(parseStoredMode("")).toBe(DEFAULT_MODE);
+    expect(parseStoredMode("garbage")).toBe(DEFAULT_MODE);
+    expect(parseStoredMode("system")).toBe(DEFAULT_MODE);
+    expect(parseStoredMode("time")).toBe(DEFAULT_MODE);
+    expect(DEFAULT_MODE).toBe("auto");
+  });
+});