dsh-session-guard 4.1.16 → 4.2.1

package/src/holiday-store.js

@@ -0,0 +1,196 @@
+/**
+ * dsh-session-guard — 修正表的 IO 层：按年缓存落盘 + 自动抓取 + 启动指纹校验。
+ *
+ * 数据链路（全部 fail-open，任何失败只降级不抛错）：
+ * 1. 内置快照（holidays.js BUILTIN_TABLES，已定稿年份）；
+ * 2. 磁盘缓存 `$DSH_HOME/.dsh/session-guard/holidays/<year>.json`
+ *    （`DSH_SESSION_GUARD_HOLIDAY_DIR` 可覆盖根目录）——**启动时校验指纹**：
+ *    重算内容 sha256 与文件内记录比对，不一致视为损坏，弃用并触发重抓；
+ * 3. 远端 holiday-cn（jsDelivr 主源、raw.githubusercontent 备源）——
+ *    抓取成功且指纹有变化才原子写缓存（tmp + rename）；指纹一致只刷新
+ *    checkedAt，不写盘（2026 已定稿，日常核对几乎恒等）。
+ *
+ * 「按年自动尝试抓取」：启动核对一次，之后每小时 ensureFresh；相关年份 =
+ * 北京时间当年 + 12 月追加次年（国务院公告一般 11–12 月发布）。内置表
+ * 覆盖的年份仍会被远端覆盖更新（公告修正 / 补录），但抓取节奏不变。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { storeRoot } from './store.js'
+import { wallClock, BILLING_TIMEZONE } from './time.js'
+import { BUILTIN_TABLES, buildMap, fingerprint, parseHolidayCn } from './holidays.js'
+
+/** 单轮远端抓取超时（ms）。 */
+const FETCH_TIMEOUT_MS = 10_000
+/** 已到手年份表的复核间隔：24h。 */
+const REFRESH_MS = 24 * 3600 * 1000
+
+/** 缓存根目录（独立于 pause / 队列锁子目录）。 */
+export function holidaysRoot() {
+  return process.env.DSH_SESSION_GUARD_HOLIDAY_DIR || join(storeRoot(), 'holidays')
+}
+
+/** 某年缓存文件路径。 */
+export function holidayFilePath(year, root = holidaysRoot()) {
+  return join(root, `${Number(year)}.json`)
+}
+
+/** 远端候选源：jsDelivr 主源（国内可达性好），GitHub raw 备源。 */
+export function holidayUrls(year) {
+  const y = Number(year)
+  return [
+    `https://cdn.jsdelivr.net/gh/NateScarlet/holiday-cn@master/${y}.json`,
+    `https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/${y}.json`,
+  ]
+}
+
+/**
+ * 创建修正表存储。
+ * @param {object} [deps] { logger, fetchImpl, now, builtinTables, root }
+ *        root 供单测注入临时目录；fetchImpl 供 mock。
+ * @returns {{
+ *   loadAll: () => void,
+ *   ensureFresh: (opts?: { autoFetch?: boolean }) => Promise<void>,
+ *   map: () => Map<string, boolean>,
+ *   info: () => object[],
+ * }}
+ */
+export function createHolidayStore(deps = {}) {
+  const logger = deps.logger
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch
+  const now = deps.now ?? (() => Date.now())
+  const builtin = deps.builtinTables ?? BUILTIN_TABLES
+  const root = deps.root ?? holidaysRoot()
+
+  /** @type {Map<number, {days: {date:string,isOffDay:boolean}[], sha:string, source:'builtin'|'cache'|'live', fetchedAt:number|null, checkedAt:number|null}>} */
+  const tables = new Map()
+  /** map() 的惰性合并缓存：任何表更新时置 null。 */
+  let merged = null
+
+  const warn = (msg, e) => {
+    const line = `[session-guard] ${msg}`
+    if (logger?.warn) logger.warn(e ? `${line}: ${String(e && e.message || e)}` : line)
+    else console.warn(e ? `${line}: ${String(e && e.message || e)}` : line)
+  }
+
+  function putTable(year, days, source, fetchedAt) {
+    tables.set(year, { days, sha: fingerprint(days), source, fetchedAt, checkedAt: now() })
+    merged = null
+  }
+
+  /** 装载单年：内置打底，缓存指纹校验通过则覆盖内置。 */
+  function loadYear(year) {
+    const seed = builtin.find((t) => t.year === year)
+    if (seed) putTable(year, seed.days.slice(), 'builtin', null)
+    let cached
+    try {
+      const f = holidayFilePath(year, root)
+      if (!existsSync(f)) return
+      cached = JSON.parse(readFileSync(f, 'utf8'))
+    } catch (e) {
+      warn('holiday cache unreadable (ignored)', e)
+      return
+    }
+    try {
+      const parsed = parseHolidayCn(cached)
+      if (parsed.year !== year) throw new Error(`cache year ${parsed.year} != file slot ${year}`)
+      const sha = fingerprint(parsed.days)
+      if (cached.sha !== sha) {
+        // 启动指纹校验失败：内容损坏/被改，弃用缓存（ensureFresh 会重抓）。
+        warn(`holiday cache fingerprint mismatch for ${year}, discarding`)
+        return
+      }
+      putTable(year, parsed.days, 'cache', Number(cached.fetchedAt) || null)
+    } catch (e) {
+      warn(`holiday cache invalid for ${year} (ignored)`, e)
+    }
+  }
+
+  /** 相关年份：北京当年 +（11/12 月）次年——国务院一般年底公布来年安排。 */
+  function relevantYears() {
+    const wc = wallClock(BILLING_TIMEZONE, new Date(now()))
+    const years = [wc.year]
+    if (wc.month >= 11) years.push(wc.year + 1)
+    return years
+  }
+
+  async function fetchYear(year) {
+    if (typeof fetchImpl !== 'function') return false
+    for (const url of holidayUrls(year)) {
+      try {
+        const res = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+        if (!res || res.ok !== true) continue
+        const parsed = parseHolidayCn(await res.json())
+        if (parsed.year !== year) throw new Error(`payload year ${parsed.year} != requested ${year}`)
+        const sha = fingerprint(parsed.days)
+        const cur = tables.get(year)
+        if (cur && cur.sha === sha) {
+          cur.checkedAt = now() // 指纹一致：不写盘，只记核对时间
+          return true
+        }
+        try {
+          mkdirSync(dirname(holidayFilePath(year, root)), { recursive: true })
+          const tmp = `${holidayFilePath(year, root)}.tmp`
+          writeFileSync(tmp, JSON.stringify({
+            year, sha, fetchedAt: now(), sourceUrl: url,
+            days: parsed.days,
+          }, null, 2))
+          renameSync(tmp, holidayFilePath(year, root))
+        } catch (e) {
+          warn(`holiday cache write failed for ${year} (memory table still updated)`, e)
+        }
+        putTable(year, parsed.days, 'live', now())
+        warn(`holiday table updated for ${year} (${cur ? 'fingerprint changed' : 'new'}, ${sha.slice(0, 17)}…)`)
+        return true
+      } catch (e) {
+        warn(`holiday fetch failed via ${url}`, e)
+      }
+    }
+    return false
+  }
+
+  return {
+    /** 启动装载（同步）：内置 + 缓存 + 指纹校验。 */
+    loadAll() {
+      for (const year of relevantYears()) loadYear(year)
+    },
+
+    /**
+     * 按年自动抓取核对：缺表的年份立即抓；已有表超 24h 复核。
+     * autoFetch=false（设置关）时只补缺年（缓存/内置仍生效），不发请求。
+     */
+    async ensureFresh(opts = {}) {
+      const autoFetch = opts.autoFetch !== false
+      for (const year of relevantYears()) {
+        const cur = tables.get(year)
+        const anchor = Math.max((cur && cur.fetchedAt) || 0, (cur && cur.checkedAt) || 0)
+        if (cur && now() - anchor <= REFRESH_MS) continue // 24h 内已抓/已核对
+        if (autoFetch !== true) continue // 关自动抓取时纯靠内置 + 缓存，不发请求
+        await fetchYear(year)
+      }
+    },
+
+    /** 合并所有已装载年份的查表 Map（'YYYY-MM-DD' → 是否放假日）。 */
+    map() {
+      if (merged) return merged
+      const days = []
+      for (const t of tables.values()) days.push(...t.days)
+      merged = buildMap(days)
+      return merged
+    },
+
+    /** 诊断输出（/session-guard/status 透出用）。 */
+    info() {
+      return [...tables.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([year, t]) => ({
+          year,
+          source: t.source,
+          fingerprint: t.sha,
+          fetchedAt: t.fetchedAt,
+          checkedAt: t.checkedAt,
+          entries: t.days.length,
+        }))
+    },
+  }
+}

package/src/holidays.js

@@ -0,0 +1,159 @@
+/**
+ * dsh-session-guard — 法定节假日 / 调休修正表（纯逻辑，零 IO，可单测）。
+ *
+ * 数据源：holiday-cn（NateScarlet/holiday-cn，每日自动解析国务院公告），
+ * 全年 JSON：`{ year, papers: [...], days: [{ name, date, isOffDay }] }`。
+ * `isOffDay: true` = 放假（含落在周末的假日）；`false` = 调休补班日
+ * （本来是周六日但要上班）。表外日期回退自然周末判定。
+ *
+ * 内置快照只覆盖已定稿年份（2026，39 条 = 33 放假日 + 6 调休补班日）；
+ * 未覆盖年份由 holiday-store.js 按年自动抓取，抓不到即退化为纯自然周末
+ * （fail-open，与插件一贯风格一致）。
+ */
+import { createHash } from 'node:crypto'
+
+/** 'YYYY-MM-DD' 严格形态（月/日补零），也是 Map 键与指纹序列化的唯一形态。 */
+const DATE_RE = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/
+
+/**
+ * 2026 年国务院放假安排（公告 content_7047091，经 holiday-cn 机读）。
+ * 只保留判定需要的 date / isOffDay 两键；name 仅注释性内嵌于分组注释。
+ */
+export const BUILTIN_2026 = Object.freeze({
+  year: 2026,
+  paper: 'https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm',
+  days: Object.freeze([
+    // 元旦：1/1(四)-1/3(六) 放假，1/4(日) 补班
+    { date: '2026-01-01', isOffDay: true },
+    { date: '2026-01-02', isOffDay: true },
+    { date: '2026-01-03', isOffDay: true },
+    { date: '2026-01-04', isOffDay: false },
+    // 春节：2/15-2/23 放假，2/14(六)、2/28(六) 补班
+    { date: '2026-02-14', isOffDay: false },
+    { date: '2026-02-15', isOffDay: true },
+    { date: '2026-02-16', isOffDay: true },
+    { date: '2026-02-17', isOffDay: true },
+    { date: '2026-02-18', isOffDay: true },
+    { date: '2026-02-19', isOffDay: true },
+    { date: '2026-02-20', isOffDay: true },
+    { date: '2026-02-21', isOffDay: true },
+    { date: '2026-02-22', isOffDay: true },
+    { date: '2026-02-23', isOffDay: true },
+    { date: '2026-02-28', isOffDay: false },
+    // 清明：4/4-4/6 放假，无补班
+    { date: '2026-04-04', isOffDay: true },
+    { date: '2026-04-05', isOffDay: true },
+    { date: '2026-04-06', isOffDay: true },
+    // 劳动节：5/1-5/5 放假，5/9(六) 补班
+    { date: '2026-05-01', isOffDay: true },
+    { date: '2026-05-02', isOffDay: true },
+    { date: '2026-05-03', isOffDay: true },
+    { date: '2026-05-04', isOffDay: true },
+    { date: '2026-05-05', isOffDay: true },
+    { date: '2026-05-09', isOffDay: false },
+    // 端午：6/19-6/21 放假，无补班
+    { date: '2026-06-19', isOffDay: true },
+    { date: '2026-06-20', isOffDay: true },
+    { date: '2026-06-21', isOffDay: true },
+    // 中秋：9/25-9/27 放假，9/20(日) 补班
+    { date: '2026-09-20', isOffDay: false },
+    { date: '2026-09-25', isOffDay: true },
+    { date: '2026-09-26', isOffDay: true },
+    { date: '2026-09-27', isOffDay: true },
+    // 国庆：10/1-10/7 放假，10/10(六) 补班
+    { date: '2026-10-01', isOffDay: true },
+    { date: '2026-10-02', isOffDay: true },
+    { date: '2026-10-03', isOffDay: true },
+    { date: '2026-10-04', isOffDay: true },
+    { date: '2026-10-05', isOffDay: true },
+    { date: '2026-10-06', isOffDay: true },
+    { date: '2026-10-07', isOffDay: true },
+    { date: '2026-10-10', isOffDay: false },
+  ]),
+})
+
+/** 内置快照数组（新定稿年份在此追加）。 */
+export const BUILTIN_TABLES = Object.freeze([BUILTIN_2026])
+
+/**
+ * 校验并归一化 holiday-cn `days` 数组。
+ * 逐条要求 `date` 为补零 'YYYY-MM-DD' 且 `isOffDay` 为布尔；
+ * 排序去重（同日重复以末条为准，与上游「后公告覆盖前公告」一致）。
+ * @param {unknown} raw days 原始数组
+ * @returns {{date:string, isOffDay:boolean}[]} 归一化条目（新数组）
+ * @throws {Error} 非数组 / 空条目 / 形态非法
+ */
+export function normalizeDays(raw) {
+  if (!Array.isArray(raw)) throw new Error('holiday days: not an array')
+  const byDate = new Map()
+  for (const item of raw) {
+    const date = item && typeof item === 'object' ? item.date : undefined
+    if (typeof date !== 'string' || !DATE_RE.test(date)) {
+      throw new Error(`holiday days: bad date ${JSON.stringify(date)}`)
+    }
+    if (typeof item.isOffDay !== 'boolean') {
+      throw new Error(`holiday days: bad isOffDay for ${date}`)
+    }
+    byDate.set(date, { date, isOffDay: item.isOffDay })
+  }
+  return [...byDate.values()].sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0))
+}
+
+/**
+ * 解析 holiday-cn 全年 JSON（远端响应 / 缓存文件通吃）。
+ * @param {unknown} json 已 parse 的对象
+ * @returns {{year:number, days:{date:string, isOffDay:boolean}[]}}
+ * @throws {Error} 形态不合 schema（year 与条目日期必须一致）
+ */
+export function parseHolidayCn(json) {
+  if (json === null || typeof json !== 'object') throw new Error('holiday json: not an object')
+  const year = Number(json.year)
+  if (!Number.isInteger(year) || year < 2000 || year > 2100) throw new Error('holiday json: bad year')
+  const days = normalizeDays(json.days)
+  for (const d of days) {
+    if (Number(d.date.slice(0, 4)) !== year) throw new Error(`holiday json: day ${d.date} outside ${year}`)
+  }
+  return { year, days }
+}
+
+/**
+ * 修正表指纹：对归一化（排序去重）后的 `date=isOffDay` 序列做 sha256。
+ * 只哈希判定语义相关字段——name / papers / 抓取时间不参与，
+ * 上游改文案不会引起伪变化。
+ * @param {{date:string, isOffDay:boolean}[]} days normalizeDays / parseHolidayCn 产物
+ * @returns {string} 'sha256:<hex>'
+ */
+export function fingerprint(days) {
+  const canon = days.map((d) => `${d.date}=${d.isOffDay ? 1 : 0}`).join(';')
+  return `sha256:${createHash('sha256').update(canon).digest('hex')}`
+}
+
+/**
+ * 归一化 days → 查表 Map：'YYYY-MM-DD' → 是否放假日。
+ * @param {{date:string, isOffDay:boolean}[]} days
+ * @returns {Map<string, boolean>}
+ */
+export function buildMap(days) {
+  const m = new Map()
+  for (const d of days) m.set(d.date, d.isOffDay)
+  return m
+}
+
+/** wallClock 分量 → 补零 'YYYY-MM-DD'。 */
+export function ymdOf(wc) {
+  return `${wc.year}-${String(wc.month).padStart(2, '0')}-${String(wc.day).padStart(2, '0')}`
+}
+
+/**
+ * 修正表感知的「当天是否休息日」：
+ * - 表内条目：`isOffDay` 直接定乾坤（true 放假 / false 调休补班——周末也算上班）；
+ * - 表外 / 无表（map 为 null 或空）：回退自然周末（0=周日、6=周六）。
+ * @param {Map<string, boolean>|null|undefined} map buildMap 产物
+ * @param {string} ymd 补零日期串
+ * @param {number} weekday 该日期在用户时区的星期（0-6，同 wallClock 约定）
+ * @returns {boolean}
+ */
+export function isRestDay(map, ymd, weekday) {
+  if (map instanceof Map && map.has(ymd)) return map.get(ymd) === true
+  return weekday === 0 || weekday === 6
+}

package/src/index.js

@@ -3,16 +3,19 @@
  *
  * 高峰自动会话门：
  * - 每 30s tick 判定状态（NORMAL ↔ PAUSED_PEAK），纯状态机见 scheduler.js。
- * - 入峰（且非周末）：对所有 running root session 调 gate.stopNextTurn
+ * - 入峰（且非周末/休息日）：对所有 running root session 调 gate.stopNextTurn
  *   （有 taskControl → 会话门 safe+wait；无 → 回退锁等待队列）。
- * - 退峰/周末：gate.resume 全部。
+ * - 退峰/休息日：gate.resume 全部。
+ * - 法定假/调休修正表（holidayMode）：内置快照 + 启动校验缓存指纹 + 按年自动
+ *   抓取 holiday-cn（holiday-store.js）；法定假视同周末，调休补班周末按工作日。
  * - `ctx.provide('sessionGuard')` 冗余端口，input-traffic 冻结按钮透传接入。
  * - 设置：设置 → 插件 → session-guard 子板块，简单开关（enabled / weekendMode / queueFallback）。
  *   schemastery 为常规 dependency，设置经 `ctx.inject(['settings'])` 本地接口注册（src/settings.js，
  *   对齐 dsh-thinking-levels；不 value-import dsh-settings）；设置服务缺失时 fail-open 用默认配置照常运行。
  */
 import { computeState, transition } from './scheduler.js'
-import { wallClock, isWeekend, isInPeak, BILLING_TIMEZONE } from './time.js'
+import { wallClock, isRestForSettings, isInPeak, BILLING_TIMEZONE } from './time.js'
+import { createHolidayStore } from './holiday-store.js'
 import { createStore } from './store.js'
 import { createGate } from './gate.js'
 import { createBridge } from './bridge.js'
@@ -43,6 +46,21 @@ export function apply(ctx, config = {}) {
   const store = createStore()
   let lastState = null
 
+  // ── 法定假/调休修正表：内置快照打底，启动校验缓存指纹，按年自动抓取 ──
+  // holidayMap 只在 holidayMode 开启时挂进 cfg（readCfg）；消费方（time.shouldPause
+  // 及其全部调用链）无感知：表缺席即退回自然周末。fail-open：抓取/解析失败只
+  // warn，不阻断 tick / 暂停主链路。DSH_SESSION_GUARD_HOLIDAY_FETCH=0 可断网
+  // （单测/离线环境）：退化为纯内置 + 已缓存，不发起任何请求。
+  const holidays = createHolidayStore({
+    logger: ctx.logger,
+    fetchImpl: process.env.DSH_SESSION_GUARD_HOLIDAY_FETCH === '0' ? null : globalThis.fetch,
+  })
+  try {
+    holidays.loadAll() // 同步：内置 + 缓存（含启动指纹校验）
+  } catch (e) {
+    ctx.logger?.warn?.(`[session-guard] holiday load failed (weekend-only fallback): ${String(e)}`)
+  }
+
   /** 读实时设置（settings 服务不可用时回退默认）。 */
   let configSource = config
   /** 组合条目快照：volatile 字段解引，供默认值合并。 */
@@ -56,7 +74,10 @@ export function apply(ctx, config = {}) {
   function readCfg() {
     try {
       const v = resolveEntryConfig()
-      return v && typeof v === 'object' ? { ...DEFAULT_SETTINGS, ...v } : { ...DEFAULT_SETTINGS }
+      const cfg = v && typeof v === 'object' ? { ...DEFAULT_SETTINGS, ...v } : { ...DEFAULT_SETTINGS }
+      // 修正表活引用：holidayMode 开启才挂；每次重组装取最新合并表（抓取更新后自然生效）
+      if (cfg.holidayMode === true) cfg.holidayMap = holidays.map()
+      return cfg
     } catch {
       return { ...DEFAULT_SETTINGS }
     }
@@ -273,6 +294,15 @@ export function apply(ctx, config = {}) {
   ctx.effect(() => ctx.timer.interval(tick, 30_000), 'session-guard: tick')
   tick()
 
+  // ── 修正表自动刷新：启动后立即核对一次，之后每小时 ensureFresh ──
+  // 当年 +（11/12 月）次年；已有表 24h 内不重抓，指纹一致不写盘（见 holiday-store.js）。
+  const holidayRefresh = () => {
+    void holidays.ensureFresh({ autoFetch: readCfg().holidayAutoFetch === true })
+      .catch((e) => ctx.logger?.warn?.(`[session-guard] holiday refresh failed: ${String(e)}`))
+  }
+  ctx.effect(() => ctx.timer.interval(holidayRefresh, 3_600_000), 'session-guard: holiday refresh')
+  holidayRefresh()
+
   // ── HTTP 路由 ──
   // 0.1.5 compat：注册失败只记日志，不让 apply 抛错炸掉宿主插件加载（#5926 教训）。
   // webServer.register 前缀路由 + SSE 在 0.1.5 契约不变（packages/host/webserver WebRoute）。
@@ -353,19 +383,21 @@ export function apply(ctx, config = {}) {
           }
           // GET /session-guard/status —— 全局当前阶段（状态徽标轮询用）
           // 峰谷判定：固定北京时间（BILLING_TIMEZONE），与 DeepSeek 官方计费一致
-          // 周末判定：用配置时区（用户本地的周末）
+          // 周末/休息日判定：用配置时区；holidayMode 开启时查修正表（法定假=休，补班周末=工作）
           if (method === 'GET' && url.pathname === '/session-guard/status') {
             const cfg = readCfg()
             const now = new Date()
             const wcUser = wallClock(cfg.timezone, now)
             const wcBilling = wallClock(BILLING_TIMEZONE, now)
-            const weekend = isWeekend(wcUser.weekday)
+            const weekend = isRestForSettings(cfg, wcUser)
             const peak = cfg.enabled && !weekend && isInPeak(wcBilling, cfg.peakWindows || [])
             return json(200, {
               ok: true,
               status: {
                 phase: weekend ? 'weekend' : peak ? 'peak' : 'off-peak',
                 weekend,
+                holidayMode: cfg.holidayMode === true,
+                holidays: holidays.info(),
                 peak,
                 state: lastState,
                 enabled: cfg.enabled,

package/src/settings.js

@@ -20,7 +20,9 @@ export const NS = 'session-guard'
 export const DEFAULT_SETTINGS = Object.freeze({
   enabled: true, // 高峰自动处理开关（简单开关）
   offPeakAutoResume: true, // 低谷自动恢复开关：低峰时段自动恢复被高峰暂停的会话
-  weekendMode: true, // 周末模式开关：识别周末，无视峰谷（简单开关）
+  weekendMode: true, // 周末模式开关：识别周末/休息日，无视峰谷（简单开关）
+  holidayMode: true, // 法定节假日修正表：法定假视同周末，调休补班周末按工作日（简单开关）
+  holidayAutoFetch: true, // 按年自动抓取 holiday-cn 修正表（关=只用内置+已缓存；启动仍校验缓存指纹）
   timezone: 'Asia/Shanghai',
   peakWindows: [
     { start: '09:00', end: '12:00' },
@@ -57,6 +59,8 @@ export const SettingsSchema = z.object({
   enabled: z.boolean().default(DEFAULT_SETTINGS.enabled).volatile(),
   offPeakAutoResume: z.boolean().default(DEFAULT_SETTINGS.offPeakAutoResume).volatile(),
   weekendMode: z.boolean().default(DEFAULT_SETTINGS.weekendMode).volatile(),
+  holidayMode: z.boolean().default(DEFAULT_SETTINGS.holidayMode).volatile(),
+  holidayAutoFetch: z.boolean().default(DEFAULT_SETTINGS.holidayAutoFetch).volatile(),
   timezone: z.string().default(DEFAULT_SETTINGS.timezone).volatile(),
   peakWindows: z
     .array(z.object({ start: z.string(), end: z.string() }))

package/src/time.js

@@ -6,11 +6,16 @@
  *
  * 周末判定基于用户配置时区（settings.timezone），因为"周末"是用户本地概念。
  *
+ * 修正表（settings.holidayMap，holiday-cn 语义）存在时，"周末"升级为
+ * "休息日"：法定节假日（含落在工作日的）视同周末；调休补班周末
+ * 视同工作日（峰谷窗口照常生效）。无表时退回纯自然周末。
+ *
  * 两者都通过 `Intl.DateTimeFormat(timeZone)` 投影，避免裸 `getUTCDay()`
  * 导致北京周末边界错 8 小时的 bug。
  *
  * 高峰时段为左闭右开 [start, end)；跨午夜窗口（start > end）安全。
  */
+import { isRestDay, ymdOf } from './holidays.js'
 
 /**
  * DeepSeek 峰谷计费基准时区（固定北京时间 UTC+8）。
@@ -67,6 +72,18 @@ export function isWeekend(weekday) {
   return weekday === 0 || weekday === 6
 }
 
+/**
+ * 用户时区"当天是否休息日"：holidayMap 存在则查修正表（含调休补班），
+ * 缺省退回自然周末。settings.holidayMap 由 host 装配层（readCfg）挂载，
+ * holidayMode 关闭时不挂——本函数只看表的存在性。
+ * @param {object} settings 同 shouldPause
+ * @param {{year:number,month:number,day:number,weekday:number}} wc wallClock 分量（用户时区）
+ * @returns {boolean}
+ */
+export function isRestForSettings(settings, wc) {
+  return isRestDay(settings.holidayMap, ymdOf(wc), wc.weekday)
+}
+
 /** 某墙钟分钟是否处于任一高峰窗口内。 */
 export function isInPeak(wc, windows) {
   return windows.some((w) => {
@@ -80,19 +97,20 @@ export function isInPeak(wc, windows) {
 /**
  * 主判定：此刻是否应触发高峰暂停。
  *
- * - 峰谷判定：固定使用 BILLING_TIMEZONE（北京时间），与 DeepSeek 官方计费一致；
- * - 周末判定：使用 settings.timezone（用户本地时区），因为周末是用户本地概念。
+ * - 周末/休息日判定：使用 settings.timezone（用户本地时区），周末是用户本地概念；
+ *   holidayMap 存在时升级为修正表语义（法定假=休，调休补班周末=工作）；
+ * - 峰谷判定：固定使用 BILLING_TIMEZONE（北京时间），与 DeepSeek 官方计费一致。
  *
- * @param {object} settings { enabled, weekendMode, timezone, peakWindows }
+ * @param {object} settings { enabled, weekendMode, timezone, peakWindows, holidayMap? }
  * @param {Date} date
  * @returns {{pause:boolean, reason:string}}
- *          reason: 'disabled' | 'weekend' | 'peak' | 'off-peak'
+ *          reason: 'disabled' | 'weekend'（休息日，含法定假） | 'peak' | 'off-peak'
  */
 export function shouldPause(settings, date) {
   if (!settings || settings.enabled !== true) return { pause: false, reason: 'disabled' }
-  // 周末判定：用用户配置时区（用户本地的周末）
+  // 周末/休息日判定：用用户配置时区（用户本地的周末）
   const wcUser = wallClock(settings.timezone, date)
-  if (settings.weekendMode === true && isWeekend(wcUser.weekday)) {
+  if (settings.weekendMode === true && isRestForSettings(settings, wcUser)) {
     return { pause: false, reason: 'weekend' }
   }
   // 峰谷判定：固定北京时间（DeepSeek 官方计费基准）
@@ -127,7 +145,8 @@ export function localMidnight(tz, year, month, day) {
  * 从 `date` 出发、下一个「确定非峰」的时刻；找不到返回 null。
  * 取两个候选的最小值：
  * (a) 当前所在高峰窗口的结束时刻（计费时区，跨午夜安全）；
- * (b) 下一个周末日的本地 00:00（周末整天非峰，仅 weekendMode 开启时）。
+ * (b) 下一个休息日的本地 00:00（周末/法定假整天非峰，仅 weekendMode 开启时；
+ *     holidayMap 存在时同步识别法定假起点与调休补班周末）。
  * @param {object} settings
  * @param {Date} date 已知处于高峰
  * @returns {number|null}
@@ -154,9 +173,11 @@ function nextOffPeakInstant(settings, date) {
   }
   if (settings.weekendMode === true) {
     const wcUser = wallClock(settings.timezone, date)
-    for (let k = 1; k <= 7; k++) {
+    // 往后找第一个"休息日"（自然周末或法定假）；上限 14 天覆盖长假前的补班周末。
+    for (let k = 1; k <= 14; k++) {
       const day = new Date(Date.UTC(wcUser.year, wcUser.month - 1, wcUser.day + k))
-      if (!isWeekend(day.getUTCDay())) continue
+      const ymd = `${day.getUTCFullYear()}-${String(day.getUTCMonth() + 1).padStart(2, '0')}-${String(day.getUTCDate()).padStart(2, '0')}`
+      if (!isRestDay(settings.holidayMap, ymd, day.getUTCDay())) continue
       candidates.push(localMidnight(settings.timezone, day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate()))
       break
     }