@gehennawu/dsh-service 1.9.2 → 1.9.4

package/index.js

@@ -112,8 +112,20 @@ const MAX_BACKUP_COMPRESSED_BYTES = 512 * 1024 * 1024
 const instanceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
 const backupIdSecret = randomBytes(32)
 const BACKUP_NAME = /^dsh-backup-\d{8}-\d{6}\.tar\.gz$/
-const USAGE_INDEX_VERSION = 5
+const USAGE_INDEX_VERSION = 7
 const USAGE_INDEX_FILE = 'dsh-service-usage-index.json'
+// 桶口径已对齐（= 当前折叠口径）的最低索引版本：口径在 v5 定稿，v5/v6 的折叠函数与当前
+// **逐字节相同**（v6 只加了 detached / failedSessions 记账字段），故加载 v5 及以后的桶可
+// 直接沿用；**低于它的必须重折**（v4 及更早把「无 usage 的步骤」也计为步骤）。
+// 反向写法（「非当前版本就重折」「不在已知表里就重折」）会把纯记账升版当成口径变更：
+// v5→v6 那次折叠函数一字未改，却把全部会话拖进全量重读，旧日志读不动时就变成每次刷新都
+// 重读重报（真机 132 会话全量重读、44 个误报——它们 revision 未变，本可安全跳过）。
+// 新增索引版本号时**无需**改动本常量：新版本默认落在「已对齐」一侧。
+const USAGE_FOLD_ALIGNED_FROM_INDEX_VERSION = 5
+// 报错滚动窗口：一个常量同时约束「折叠时是否收录」（recentErrorTime）、「出参前修剪」
+// （publicUsage）与「落盘前修剪」（refreshUsageIndex），三者必须一致，否则会出现
+// 收录了却被下一轮清掉的半衰状态。窗口只影响报错计数，与永久保留的用量无关。
+const USAGE_ERROR_WINDOW_MS = 48 * 60 * 60 * 1000
 // 官方右栏文件编辑（v1.6 用户点名）：浏览器只送资源地址，宿主解析会话后按 ctx.fs +
 // sandboxPolicy 读写；单文件上限双向生效（读取、保存、撤销通道都受它约束）。
 const FILE_RESOURCE_PREFIX = 'dsh-resource://file/session/'
@@ -1045,6 +1057,27 @@ function localDayForHour(hour, timezoneOffsetMinutes = 0) {
   return new Date(utcTime - offset * 60 * 1000).toISOString().slice(0, 10)
 }
 
+// 小时桶 → 本地「星期 × 小时」格键（打卡图）。与 localDayForHour 同一套时区折算：
+// 先按客户端偏移平移 UTC 时刻，再用 getUTC* 读取平移后的本地分量，不依赖宿主所在时区。
+// weekday 以周一为 0，与客户端热力日历的行序一致。
+function localWeekdayHourForHour(hour, timezoneOffsetMinutes = 0) {
+  const offset = Number.isFinite(Number(timezoneOffsetMinutes)) ? Math.max(-840, Math.min(840, Number(timezoneOffsetMinutes))) : 0
+  const utcTime = Date.parse(`${hour}:00:00.000Z`)
+  if (!Number.isFinite(utcTime)) return undefined
+  const shifted = new Date(utcTime - offset * 60 * 1000)
+  return { weekday: (shifted.getUTCDay() + 6) % 7, hour: shifted.getUTCHours() }
+}
+
+// 项目文件夹被删时只在「按项目」维度隐藏其入口；总量、日期桶与模型明细仍保留该段历史用量。
+function usageProjectMissing(project) {
+  if (typeof project?.path !== 'string' || project.path.length === 0) return false
+  try {
+    return !existsSync(project.path)
+  } catch (_) {
+    return false
+  }
+}
+
 function emptyUsageTotals() {
   return { steps: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }
 }
@@ -1091,13 +1124,42 @@ function revisionKey(revision) {
 }
 
 function createUsageIndex() {
-  return { version: USAGE_INDEX_VERSION, updatedAt: 0, sessions: {} }
+  return { version: USAGE_INDEX_VERSION, updatedAt: 0, sessions: {}, failedSessions: [] }
+}
+
+// 版本迁移：**只在确知折叠口径落后时才重折**（见 USAGE_FOLD_ALIGNED_FROM_INDEX_VERSION）。
+// 所有旧摘要一律保留——未标记 detached 的条目可能源文件已在升级前被删除（此前未标 detached），
+// 也可能源文件仍在；绝不能在迁移时丢弃，更不能无差别重折。口径已对齐的版本直接沿用旧桶
+// （revision 未变的会话连读都不读）；只有口径落后才打 rebuildPending 强制从 seq 0 重折。标记
+// 跨重启保留：源已删则转 detached 留全历史，源仍在则重折成功才替换、失败保留旧摘要下次再试。
+function migrateUsageIndex(parsed) {
+  const fromIndexVersion = Number.isSafeInteger(parsed?.version) ? parsed.version : 0
+  const needsRefold = fromIndexVersion < USAGE_FOLD_ALIGNED_FROM_INDEX_VERSION
+  const sessions = {}
+  if (parsed?.sessions !== null && typeof parsed?.sessions === 'object') {
+    for (const [id, session] of Object.entries(parsed.sessions)) {
+      if (session !== null && typeof session === 'object') {
+        const migrated = structuredClone(session)
+        // detached 条目没有重折材料（源文件已删），永远只保留不重折。
+        if (needsRefold && migrated.detached !== true) {
+          migrated.rebuildPending = true
+        } else {
+          // 口径未变（或条目不可重折）：清掉历史升级可能残留的待重建标记，否则它会让这个
+          // 会话在每次刷新时被反复全量重读——旧日志读不动时正是「每次刷新都报失败」的来源。
+          delete migrated.rebuildPending
+        }
+        sessions[id] = migrated
+      }
+    }
+  }
+  return { version: USAGE_INDEX_VERSION, updatedAt: 0, sessions, failedSessions: [] }
 }
 
 async function loadUsageIndex(dshHome) {
   try {
     const parsed = JSON.parse(await readFile(join(dshHome, USAGE_INDEX_FILE), 'utf8'))
-    if (parsed?.version !== USAGE_INDEX_VERSION || typeof parsed.sessions !== 'object' || parsed.sessions === null) return createUsageIndex()
+    if (typeof parsed?.sessions !== 'object' || parsed.sessions === null) return createUsageIndex()
+    if (parsed.version !== USAGE_INDEX_VERSION) return migrateUsageIndex(parsed)
     return parsed
   } catch (error) {
     if (error?.code === 'ENOENT') return createUsageIndex()
@@ -1160,42 +1222,130 @@ function normalizeQuotaAllowedHosts(raw) {
   return out
 }
 
+// 重置卡到期串的两种「无时区」写法：纯日期与 datetime-local（面板录入格式）。
+// 两者都不带偏移，intl 语义是「用户墙上时间的这个点」，因此必须有客户端时区才能换算成绝对时刻。
+const RESET_CARD_DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+const RESET_CARD_NAIVE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?$/
+
+/** 客户端时区偏移（分钟，JS getTimezoneOffset 语义）→ 合法范围整数；非法一律视为「未知」（undefined）。 */
+function quotaTimezoneOffset(value) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || Math.abs(value) > 840) return undefined
+  return value
+}
+
+function quotaTimeZone(value) {
+  if (typeof value !== 'string' || value.length > 100) return undefined
+  try { return new Intl.DateTimeFormat('en', { timeZone: value }).resolvedOptions().timeZone } catch (_) { return undefined }
+}
+
+// 用目标日期的 IANA 时区规则解释存量墙上时间；不存在的 DST 跳跃时刻保留待人工修正。
+function resetCardWallTimeMs(raw, timeZone) {
+  const wallText = raw.length === 10 ? `${raw}T23:59:59.999` : raw
+  const wall = Date.parse(`${wallText}Z`)
+  if (!Number.isFinite(wall)) return null
+  const formatter = new Intl.DateTimeFormat('en-GB', {
+    timeZone, year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23',
+  })
+  const wallAt = (at) => {
+    const p = Object.fromEntries(formatter.formatToParts(new Date(at)).map(({ type, value }) => [type, value]))
+    return Date.parse(`${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}Z`) + ((at % 1000) + 1000) % 1000
+  }
+  const candidates = []
+  // 在目标墙上时刻两侧采样候选偏移，覆盖 DST 两档；反向映射相等才接受，避免跳跃日静默纠正。
+  for (const delta of [-36, 0, 36]) {
+    const sample = wall + delta * 3600000
+    const candidate = wall - (wallAt(sample) - sample)
+    if (wallAt(candidate) === wall) candidates.push(candidate)
+  }
+  return candidates.length === 0 ? null : Math.min(...candidates)
+}
+
 /**
  * 重置卡到期时刻（毫秒）：
- *   - 带时刻的 ISO 串（`2026-09-30T08:00` / 含秒、时区）→ Date.parse 的真实时刻；
- *   - 只到日的串（`2026-09-30`）→ **该自然日的 23:59:59.999**。裸日期被 Date.parse 当作当日
- *     零点 UTC，会让「9-30 到期」的卡在 9-30 零点刚过就判过期，与用户「当天还有效」的直觉相反。
+ *   - 带偏移/时区的绝对串（`2026-09-30T08:00:00Z`、`+08:00`）→ Date.parse 的真实时刻，与时区无关；
+ *   - 只到日的串（`2026-09-30`）→ **该自然日在客户端时区里的 23:59:59.999**。裸日期被 Date.parse
+ *     当作当日零点 UTC，会让「9-30 到期」的卡在 9-30 零点刚过就判过期，与「当天还有效」的直觉相反。
+ *   - datetime-local 串（`2026-09-30T08:00`）→ 该墙上时间在**客户端时区**里的绝对时刻。
+ *     此前按宿主时区（容器 UTC）解释，与浏览器渲染各算一套：UTC+8 用户在界面上看到「已过期」，
+ *     宿主却仍判未过期——既不自动移除，还继续当临期卡提示。
+ *   - 优先使用客户端 IANA 时区的目标日期规则；仅旧客户端缺时区名时兼容合法固定偏移。
+ *   - 无时区形态且没有合法时区信息 → null（宁可留着也不按宿主时区删卡/标过期）。
  *   - 缺失/无法解析 → null（永不过期，只手动移除）。
  */
-function resetCardExpiryMs(expiresAt) {
+function resetCardExpiryMs(expiresAt, timezoneOffsetMinutes, timeZone) {
   if (typeof expiresAt !== 'string') return null
   const raw = expiresAt.trim()
   if (raw === '') return null
+  if (RESET_CARD_DATE_RE.test(raw) || RESET_CARD_NAIVE_RE.test(raw)) {
+    // 显式提供的时区非法时不得降级成可能错误的偏移，更不能触发删除。
+    if (timeZone !== undefined) {
+      const zone = quotaTimeZone(timeZone)
+      return zone === undefined ? null : resetCardWallTimeMs(raw, zone)
+    }
+    const offset = quotaTimezoneOffset(timezoneOffsetMinutes)
+    if (offset === undefined) return null
+    // 把「墙上时间」按 offset 平移成 UTC：getTimezoneOffset 是「本地→UTC 需要加的分钟数」，
+    // 故 UTC = 墙上时间 + offset（UTC+8 → -480 → 减 8 小时）。
+    const wall = Date.parse(raw.length === 10 ? `${raw}T00:00:00.000Z` : `${raw}Z`)
+    if (!Number.isFinite(wall)) return null
+    const endOfDay = raw.length === 10 ? 24 * 60 * 60 * 1000 - 1 : 0
+    return wall + endOfDay + offset * 60 * 1000
+  }
+  // 非标准无偏移串不得落回宿主本地 Date.parse（例如空格代替 T）。
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/i.test(raw)) return null
   const parsed = Date.parse(raw)
-  if (!Number.isFinite(parsed)) return null
-  // 纯日期形态（YYYY-MM-DD，无 T/时刻）：顺延到当日末尾。
-  if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) return parsed + 24 * 60 * 60 * 1000 - 1
-  return parsed
+  return Number.isFinite(parsed) ? parsed : null
 }
 
 /** 已过期（到期时刻严格早于 now）的重置卡：宿主读配置时自动剔除。 */
-function isResetCardExpired(card, now = Date.now()) {
-  const at = resetCardExpiryMs(card?.expiresAt)
+function isResetCardExpired(card, now = Date.now(), timezoneOffsetMinutes, timeZone) {
+  const at = resetCardExpiryMs(card?.expiresAt, timezoneOffsetMinutes, timeZone)
   return at !== null && at < now
 }
 
 /**
  * 自动移除已过期的重置卡。读路径（refreshQuotaConfigCache）在加载后调用：
  * 有剔除才落盘，避免每次读都写文件。返回值同时告诉调用方「是否发生过变更」。
+ * 无时区形态的卡必须带上客户端偏移才参与判定，否则会按宿主时区误删。
  */
-function pruneExpiredResetCards(config, now = Date.now()) {
+function pruneExpiredResetCards(config, now = Date.now(), timezoneOffsetMinutes, timeZone) {
   if (!Array.isArray(config?.resetCards) || config.resetCards.length === 0) return false
-  const kept = config.resetCards.filter((card) => !isResetCardExpired(card, now))
+  const kept = config.resetCards.filter((card) => !isResetCardExpired(card, now, timezoneOffsetMinutes, timeZone))
   if (kept.length === config.resetCards.length) return false
   config.resetCards = kept
   return true
 }
 
+/**
+ * 把无时区的 datetime-local 到期串固化成绝对时刻（ISO，带 Z）：一次迁移，之后任何时区都读得一致。
+ * 纯日期串刻意保持原样——「9-30 到期」是本地日期承诺，改成绝对时刻会在界面上多出一个时间点，
+ * 且它每次判定都用客户端时区的目标日期规则算当日末尾，无需固化。
+ * 拿不到时区信息时原样返回，无法解析时同样原样返回（保留人工可核查的原文）。
+ */
+function canonicalResetCardExpiresAt(expiresAt, timezoneOffsetMinutes, timeZone) {
+  if (typeof expiresAt !== 'string') return expiresAt
+  const raw = expiresAt.trim()
+  if (!RESET_CARD_NAIVE_RE.test(raw)) return expiresAt
+  const at = resetCardExpiryMs(raw, timezoneOffsetMinutes, timeZone)
+  return at === null ? expiresAt : new Date(at).toISOString()
+}
+
+/** 把配置里所有无时区 datetime 卡固化为绝对时刻。有改写才返回 true（调用方据此落盘）。 */
+function normalizeResetCardInstants(config, timezoneOffsetMinutes, timeZone) {
+  if (!Array.isArray(config?.resetCards)) return false
+  let changed = false
+  for (const card of config.resetCards) {
+    if (card === null || typeof card !== 'object') continue
+    const next = canonicalResetCardExpiresAt(card.expiresAt, timezoneOffsetMinutes, timeZone)
+    if (next !== card.expiresAt) {
+      card.expiresAt = next
+      changed = true
+    }
+  }
+  return changed
+}
+
 // 重置卡条目（v0.19 手填过渡方案：官方无 API Key 可查的端点）：provider 必填，label/expiresAt 可选；
 // id 缺失时按原始位置合成稳定 id（老数据兼容），写入口生成的 id 原样保留。
 // v1.9.1 起另可带 account（CLIProxyAPI 多账号细分），缺省 = 整 provider 共享的卡，老数据零迁移。
@@ -1954,7 +2104,7 @@ function usageFailure(event) {
 }
 
 function recentErrorTime(time) {
-  return Number.isFinite(time) && time >= Date.now() - 24 * 60 * 60 * 1000
+  return Number.isFinite(time) && time >= Date.now() - USAGE_ERROR_WINDOW_MS
 }
 
 function addUsageError(session, event, model) {
@@ -2064,8 +2214,14 @@ function validSessionOffset(value) {
 // 不感知运行时差异。backup 的 readRaw 物理字节 seam 新公共面不再提供（物理整树 tar 回退
 // 即 0.1.5 语义），不做双形态。
 function persistenceListSnapshots(persistence) {
-  if (typeof persistence.list === 'function') return persistence.list()
-  return persistence.listSnapshots()
+  // 两个方法在 0.1.1-rc.2 ~ 0.1.2-rc.1 上**同时在位且语义不同**：listSnapshots() 给
+  // {header, revision}，list() 只给裸 header（当时 list 的契约就是「只列 metadata」）。
+  // 先探测 list() 会拿到裸 header，消费方读 record.header.id 即 undefined.id 抛错——
+  // 旧宿主上表现为模型统计永远建不起索引（其余功能不依赖这个形状，故只有统计坏掉）。
+  // 0.1.3-alpha.2 起反过来：listSnapshots 移除，list() 的返回值升级成
+  // {header, revision, sizeBytes}。故按「语义正确者优先」探测，与版本号无关。
+  if (typeof persistence.listSnapshots === 'function') return persistence.listSnapshots()
+  return persistence.list()
 }
 
 async function persistenceReadSlice(persistence, header, fromSeq) {
@@ -2145,14 +2301,21 @@ function usageFailedSessions(index) {
 
 function publicUsage(index, timezoneOffsetMinutes = 0) {
   const failedSessions = usageFailedSessions(index)
-  const indexedSessions = Object.keys(index.sessions).length
-  const result = { updatedAt: index.updatedAt, indexedSessions, successfulSessions: indexedSessions - failedSessions.filter((failure) => failure.stale).length, failedSessions, totals: emptyUsageTotals(), days: {}, errors: { models: [], tools: [] } }
+  const allSessions = Object.values(index.sessions)
+  // 保留条目仍计入总量与日期桶（它们就是历史用量），但在会话计数里单列，
+  // 否则界面上的「已索引 N 个会话」会包含磁盘上已不存在的会话。
+  const detachedSessions = allSessions.filter((session) => session.detached === true).length
+  const indexedSessions = allSessions.length
+  const result = { updatedAt: index.updatedAt, indexedSessions, detachedSessions, successfulSessions: indexedSessions - failedSessions.filter((failure) => failure.stale).length, failedSessions, totals: emptyUsageTotals(), days: {}, hours: {}, errors: { models: [], tools: [] } }
   const projects = new Map()
+  const projectVisibility = new Map()
   const modelErrors = new Map()
   const toolErrors = new Map()
-  const recentCutoff = Date.now() - 24 * 60 * 60 * 1000
-  for (const session of Object.values(index.sessions)) {
+  const recentCutoff = Date.now() - USAGE_ERROR_WINDOW_MS
+  for (const session of allSessions) {
     projects.set(session.project.id, session.project)
+    // 项目文件夹被删只影响「按项目」筛选入口的可见性；用量本身照旧进总量与日期桶。
+    if (!projectVisibility.has(session.project.id)) projectVisibility.set(session.project.id, !usageProjectMissing(session.project))
     pruneSessionErrors(session, recentCutoff)
     for (const error of Object.values(session.modelErrors || {})) {
       const count = error.recentTimes.length
@@ -2181,6 +2344,17 @@ function publicUsage(index, timezoneOffsetMinutes = 0) {
         projectBucket.models.set(model.id, modelBucket)
       }
       dayBucket.projects.set(session.project.id, projectBucket)
+      // 打卡图（星期 × 小时）：与 days 同为「已有原始数据的一次重排」，不新增持久化字段。
+      // 只带 totals 与项目拆分（不带模型明细），实测体积约为带模型版本的 1/2。
+      const slot = localWeekdayHourForHour(hour, timezoneOffsetMinutes)
+      if (slot !== undefined) {
+        const key = `${slot.weekday}-${slot.hour}`
+        const hourBucket = result.hours[key] || (result.hours[key] = { weekday: slot.weekday, hour: slot.hour, totals: emptyUsageTotals(), projects: new Map() })
+        addUsageTotals(hourBucket.totals, source.totals)
+        const hourProject = hourBucket.projects.get(session.project.id) || { id: session.project.id, title: session.project.title, totals: emptyUsageTotals() }
+        addUsageTotals(hourProject.totals, source.totals)
+        hourBucket.projects.set(session.project.id, hourProject)
+      }
     }
   }
   const errorSort = (a, b) => b.count - a.count || a.key.localeCompare(b.key) || a.projectId.localeCompare(b.projectId)
@@ -2197,6 +2371,13 @@ function publicUsage(index, timezoneOffsetMinutes = 0) {
       models: [...project.models.values()].map((model) => ({ ...model, totals: finishTotals(model.totals) })).sort((a, b) => a.id.localeCompare(b.id)),
     })).sort((a, b) => a.title.localeCompare(b.title))
   }
+  result.hours = Object.values(result.hours).map((bucket) => ({
+    ...bucket,
+    totals: finishTotals(bucket.totals),
+    projects: [...bucket.projects.values()].map((project) => ({ ...project, totals: finishTotals(project.totals) })).sort((a, b) => a.id.localeCompare(b.id)),
+  })).sort((a, b) => a.weekday - b.weekday || a.hour - b.hour)
+  // missing 只对「项目文件夹已不存在」的条目为真，客户端据此隐藏项目分页按钮。
+  result.projects = result.projects.map((project) => ({ ...project, missing: projectVisibility.get(project.id) === false }))
   return result
 }
 
@@ -2216,23 +2397,45 @@ async function refreshUsageIndex(ctx, dshHome, currentIndex) {
   const index = structuredClone(currentIndex)
   index.failedSessions = []
   const liveIds = new Set(snapshots.map((record) => String(record.header.id)))
-  for (const id of Object.keys(index.sessions)) if (!liveIds.has(id)) delete index.sessions[id]
-  const recentCutoff = Date.now() - 24 * 60 * 60 * 1000
+  // 保留策略：会话被删（或项目文件夹被删）都不再扣减已统计的贡献——条目永久留在索引里，
+  // 只打 detached 标记供界面区分，hours/lastSeq 等桶数据一字不动；会话回来时自动摘掉标记。
+  // 这样总量与热力图始终是「索引建立以来的完整历史」，不再随删除缩水。
+  const detachedAt = Date.now()
+  for (const [id, session] of Object.entries(index.sessions)) {
+    if (liveIds.has(id)) {
+      if (session.detached === true) {
+        delete session.detached
+        delete session.detachedAt
+      }
+      continue
+    }
+    if (session.detached !== true) {
+      session.detached = true
+      session.detachedAt = detachedAt
+    }
+    if (session.rebuildPending) {
+      delete session.rebuildPending
+    }
+  }
+  const recentCutoff = Date.now() - USAGE_ERROR_WINDOW_MS
   for (const session of Object.values(index.sessions)) pruneSessionErrors(session, recentCutoff)
   for (const record of snapshots) {
     const id = String(record.header.id)
     const revision = revisionKey(record.revision)
     const previous = index.sessions[id]
-    if (previous?.revision === revision) continue
-    const fromSeq = usageReadStart(previous)
+    const isRebuild = previous?.rebuildPending === true
+    if (previous?.revision === revision && !isRebuild) continue
+    const fromSeq = isRebuild ? 0 : usageReadStart(previous)
     let stage = 'read'
     try {
       const read = await persistenceReadSlice(persistence, record.header, fromSeq)
       const inheritedEventCount = inheritedEventCountFor(record, read)
       const events = usageReadEvents(read)
       stage = 'fold'
-      const next = foldUsageEvents(ctx, record, previous === undefined ? undefined : structuredClone(previous), events, inheritedEventCount)
+      const foldBase = isRebuild ? undefined : (previous === undefined ? undefined : structuredClone(previous))
+      const next = foldUsageEvents(ctx, record, foldBase, events, inheritedEventCount)
       next.revision = revision
+      delete next.rebuildPending
       index.sessions[id] = next
     } catch (error) {
       index.failedSessions.push(usageSessionFailure(id, error, stage, previous !== undefined))
@@ -2607,7 +2810,7 @@ function runtimeEnvCheck(runtimeEnv) {
   return { id: 'runtime-env', status: 'info', detail: 'unknown' }
 }
 
-async function collectDiagnostics(ctx, dshHome, runtimeEnv) {
+async function collectDiagnostics(ctx, dshHome, runtimeEnv, options = {}) {
   const checks = []
   const add = (id, status, detail) => checks.push({ id, status, ...(detail === undefined ? {} : { detail: String(detail) }) })
 
@@ -2689,6 +2892,27 @@ async function collectDiagnostics(ctx, dshHome, runtimeEnv) {
   if (!compatReport.available) add('plugin-compat', 'info', 'unavailable')
   else checks.push(pluginCompatCheckItem(compatReport))
 
+  // 使用统计索引（工作区实现，未发布）：统计链路自身的健康度。单会话折读失败会让用量静默少算，
+  // 此前只在模型统计页的全局警告里可见，诊断清单没有任何一项覆盖它。
+  // 功能关闭时宿主根本不刷新索引（usage/usage-refresh 均受 modelUsage 门控），报「失败」
+  // 只会是陈旧误导，故整项省略而不是降级成 info 行。
+  // 追加在清单尾部：不动前五项 id 顺序契约（既有测试与客户端渲染顺序都依赖它）。
+  if (options.usageEnabled === true) {
+    let index = null
+    try { index = await options.usageIndex } catch (_) { index = null }
+    if (index === null || typeof index !== 'object') add('usage-index', 'info', 'unavailable')
+    else {
+      const failed = usageFailedSessions(index).length
+      const indexed = index.sessions !== null && typeof index.sessions === 'object' ? Object.keys(index.sessions).length : 0
+      const updatedAt = Number.isFinite(Number(index.updatedAt)) ? Number(index.updatedAt) : 0
+      // updatedAt=0 = 从未建立索引（用户还没打开过模型统计页）：不是故障，报 info。
+      // 失败会话是「部分成功」语义（沿用 usage 页同款口径）：warning 而非 error——统计仍可用，
+      // 只是少算了这些会话，不点亮诊断标签 ⚠ 的 error 档。
+      if (updatedAt === 0) add('usage-index', 'info', 'never')
+      else add('usage-index', failed > 0 ? 'warning' : 'ok', `${failed}:${indexed}:${updatedAt}`)
+    }
+  }
+
   let status = 'ok'
   // advisory 警告（手动启动环境的黄色提示）只做行内呈现：不把 overall 拉成 warning。
   if (checks.some((check) => check.status === 'error')) status = 'error'
@@ -2724,41 +2948,6 @@ async function collectHealth(ctx) {
   }
 }
 
-/**
- * 概览重置卡到期提示的窗口（设计定稿参数，只写这一处）：到期时刻距今 **≤24 小时** 即提示。
- * 用剩余时长而不是「当天」日历窗：纯日期卡本就顺延到当日 23:59:59.999、当天窗 ≈24h，
- * 但精确时刻卡（datetime-local）在当天窗下只剩 0:00 到到期时刻的一截（可能仅几十分钟），
- * 错过即被读路径自动清理、再无补看机会；剩余时长窗让两种录入方式都保证 ≥24h 曝光。
- */
-const QUOTA_RESET_CARD_EXPIRING_WINDOW_MS = 24 * 60 * 60 * 1000
-
-/**
- * 剩余 ≤24h 到期的重置卡清单（概览 info 提示的数据源）。读路径的 prune 正常时不会剩下
- * 过期卡，这里再防御性排除一次（at < now 与 isResetCardExpired 同口径）——宁可少提示，
- * 绝不把已过期的卡当「即将到期」展示。返回 [{ provider, label }]；无命中返回空数组。
- */
-async function collectResetCardsExpiringSoon(refreshQuotaConfigCache, now = Date.now()) {
-  let config
-  try {
-    config = await refreshQuotaConfigCache()
-  } catch (_) {
-    return []
-  }
-  const cards = Array.isArray(config?.resetCards) ? config.resetCards : []
-  if (cards.length === 0) return []
-  const horizon = now + QUOTA_RESET_CARD_EXPIRING_WINDOW_MS
-  const hits = []
-  for (const card of cards) {
-    const at = resetCardExpiryMs(card?.expiresAt)
-    if (at === null || at < now || at > horizon) continue
-    hits.push({
-      provider: typeof card.provider === 'string' ? card.provider : '',
-      label: typeof card.label === 'string' ? card.label : '',
-    })
-  }
-  return hits
-}
-
 function collectActiveWork(ctx) {
   const agentsService = ctx.get('agents')
   const jobsService = ctx.get('jobs')
@@ -4954,12 +5143,29 @@ function apply(ctx) {
   let quotaConfigLastCheckedAt = 0
   let quotaConfigMtimeMs = 0
   const quotaConfigPath = join(dshHome, QUOTA_CONFIG_FILE)
+  // 最近一次请求上带的客户端时区偏移：无时区形态的重置卡到期串（纯日期 / datetime-local）
+  // 必须按「用户墙上时间」解释，宿主容器时区（多为 UTC）不是用户的时区。额度/健康等读路径
+  // 都带这个字段，记录最后一次即可；拿不到时宁可不判定（见 resetCardExpiryMs），也不按错时区删卡。
+  let quotaClientOffset
+  let quotaClientTimeZone
+  const rememberQuotaClientOffset = (payload) => {
+    if (payload?.timeZone !== undefined || payload?.timezoneOffsetMinutes !== undefined) {
+      quotaClientOffset = quotaTimezoneOffset(payload?.timezoneOffsetMinutes)
+      // 显式非法时区留给判定器拒绝；旧客户端只带偏移时不得沿用另一客户端的时区。
+      quotaClientTimeZone = payload?.timeZone
+    }
+    return quotaClientOffset
+  }
   // 过期重置卡自动移除：剔除内存快照里的过期条目，有变更才落盘（避免每次读都写文件）。
   // 读失败不影响本次结果——内存已剔除，下次读再试。TTL 快路径、TTL 到期后 mtime 未变、
   // 重新加载三条路都要过这关：mtime 未变就永远不会重新加载，缺了这一路，「停在概览页
   // 只靠 health 轮询」时运行期到点的卡在内存里清不掉。
   const pruneExpiredQuotaResetCards = async () => {
-    if (!pruneExpiredResetCards(quotaConfig)) return
+    const offset = quotaClientOffset
+    // 先固化无时区 datetime 卡（一次迁移，之后任何时区都读得一致），再按偏移剔除过期卡。
+    const canonicalized = normalizeResetCardInstants(quotaConfig, offset, quotaClientTimeZone)
+    const pruned = pruneExpiredResetCards(quotaConfig, Date.now(), offset, quotaClientTimeZone)
+    if (!canonicalized && !pruned) return
     try {
       await saveQuotaConfig(dshHome, quotaConfig)
       quotaConfigMtimeMs = (await stat(quotaConfigPath)).mtimeMs
@@ -5255,16 +5461,16 @@ function apply(ctx) {
     } },
     'health': { handle: async (payload, rpcEndpoint) => {
       const value = await collectHealth(ctx)
-      // 剩余 24 小时内到期的重置卡（额度功能开启时才算）：概览「可行动项」的 info 提示数据源。
-      // 走 health 而非 quota，是因为概览不打开额度页也该看到提醒，而 health 是面板的常驻轮询。
-      if (featureEnabled('quotaLookup')) {
-        value.resetCardsExpiringSoon = await collectResetCardsExpiringSoon(refreshQuotaConfigCache)
-      }
+      // 概览不再提示重置卡到期（用户裁决整条去掉）。但 health 仍是面板最常打的读路径，
+      // 借它推进「过期卡自动移除」：额度功能开启时读一次配置（内部按客户端时区固化+剔除）。
+      if (featureEnabled('quotaLookup')) await refreshQuotaConfigCache()
       return { ok: true, value }
 
     } },
     'diagnostics': { feature: 'healthDiagnostics', handle: async (payload, rpcEndpoint) => {
-      return { ok: true, value: await collectDiagnostics(ctx, dshHome, runtimeEnv) }
+      // usageIndex 传的是闭包里的同一个 promise（不在检查里重读磁盘 JSON——索引可达数百 KB）；
+      // modelUsage 关闭时整个 usage-index 检查项缺席，避免用陈旧索引报假故障。
+      return { ok: true, value: await collectDiagnostics(ctx, dshHome, runtimeEnv, { usageEnabled: featureEnabled('modelUsage'), usageIndex: usageIndexPromise }) }
 
     } },
     'plugin-restart': { feature: 'healthDiagnostics', audit: true, handle: async (payload, rpcEndpoint) => {
@@ -5410,12 +5616,17 @@ function apply(ctx) {
     coreRoutes,
     createSkillsRoutes({ ctx, describeJobs, dshHome, makeDescribeJobLogger, registerSkillCall, serializeSkillsIndexWrite, skillFileCache, skillsActiveControllers, skillsBatchRef, skillsIndexRef, SKILL_DESCRIPTION_MAX_CHARS, SKILL_USAGE_MAX_CHARS, bodyHashOf, describeSkillDraft, evaluateSkillFile, fixLegacySkillInvocationKeys, listSkillModels, locateSkillFrontmatter, mutateSkillEntryById, name, normalizeSkillDescribeLang, publicSkillEntry, rpcTechnicalFailure, sanitizeSkillDraftText, scanSkillEntries, selectSkillBatchCandidates, setSkillInvocationKey }),
     createSessionsRoutes({ ctx, dshHome, sessionBytesCache, sessionDeletePlans, sessionTitleCache, sessionTitlesReady, sessionViewCache, SESSIONS_BYTES_MAX_IDS, SESSIONS_DELETE_PLAN_TTL_MS, SESSIONS_VIEW_PAGE_SIZE, listSessionsForManage, loadDeletedSessions, name, resolveSessionBytesForIds, resolveSessionForDelete, rpcFailure, rpcTechnicalFailure, saveDeletedSessions, searchSessionsContent, sessionExists, sessionIsLive, viewSessionPage }),
-    createQuotaRoutes({ ctx, kickQuotaRefresh, quotaThrottle, refreshQuotaConfigCache, serializeQuotaConfigWrite, MAX_QUOTA_PROVIDER_NAME, MAX_QUOTA_RESET_CARDS, MAX_QUOTA_RESET_CARDS_PER_PROVIDER, MAX_QUOTA_RESET_CARD_ACCOUNT, QUOTA_ADAPTER_BY_KIND, name, quotaCredentialConfigured, quotaCredentialEndpoint, quotaCredentialHintNames, readQuotaProfiles, resolveQuotaKind, rpcTechnicalFailure }),
+    createQuotaRoutes({ ctx, kickQuotaRefresh, quotaThrottle, refreshQuotaConfigCache, serializeQuotaConfigWrite, MAX_QUOTA_PROVIDER_NAME, MAX_QUOTA_RESET_CARDS, MAX_QUOTA_RESET_CARDS_PER_PROVIDER, MAX_QUOTA_RESET_CARD_ACCOUNT, canonicalResetCardExpiresAt, QUOTA_ADAPTER_BY_KIND, name, quotaCredentialConfigured, quotaCredentialEndpoint, quotaCredentialHintNames, readQuotaProfiles, resolveQuotaKind, rpcTechnicalFailure }),
     createSubagentRoutes({ ctx, dispatchRing, serializeSubagentRouteWrite, subagentRouteRef, subagentRouteLoadPromise, subagentSeamRef, MAX_SUBAGENT_ROUTE_FIELD, SUBAGENT_ROUTE_FALLBACK_MAX, SUBAGENT_ROUTE_MODES, listSubagentDispatches, listSubagentModels, rpcTechnicalFailure }),
     createBackupRoutes({ ctx, backupIntegrity, backupProgress, clearBackupProgress, downloadTokens, dshHome, setBackupProgress, withBackupLock, createBackup, deleteBackup, exportBackup, formatBackupTimestamp, importBackup, listBackups, name, rpcFailure }),
   ])
 
-  const dispatchRpc = createRpcDispatcher({ endpoints: rpcEndpoints, featureEnabled, logger: ctx.logger })
+  const dispatchEndpoint = createRpcDispatcher({ endpoints: rpcEndpoints, featureEnabled, logger: ctx.logger })
+  // 只接受额度时区端点的上下文；usage 的固定偏移不能覆盖额度的 IANA 时区规则。
+  const dispatchRpc = (endpoint, payload) => {
+    if (endpoint === 'quota' || endpoint === 'quota-reset-card' || endpoint === 'health') rememberQuotaClientOffset(payload)
+    return dispatchEndpoint(endpoint, payload)
+  }
   try {
     ensureConnectionRpcWebServerSeam(ctx)
     ctx.connection.rpc.handle('/dsh-service', dispatchRpc, { authority: 'loopback' })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gehennawu/dsh-service",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "DSH Web 运维面板：安全重启、健康监控、备份和 Linux 权限维护。",
   "type": "module",
   "scripts": {

package/quota-routes.js

@@ -17,6 +17,7 @@ export function createQuotaRoutes({
   MAX_QUOTA_RESET_CARDS,
   MAX_QUOTA_RESET_CARDS_PER_PROVIDER,
   MAX_QUOTA_RESET_CARD_ACCOUNT,
+  canonicalResetCardExpiresAt,
   QUOTA_ADAPTER_BY_KIND,
   name,
   quotaCredentialConfigured,
@@ -207,7 +208,15 @@ export function createQuotaRoutes({
             const card = { id: `rc-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}`, provider: providerName }
             if (accountName !== '') card.account = accountName
             if (typeof payload?.label === 'string' && payload.label.trim() !== '') card.label = payload.label.trim().slice(0, 40)
-            if (typeof payload?.expiresAt === 'string' && payload.expiresAt.trim() !== '') card.expiresAt = payload.expiresAt.trim().slice(0, 32)
+            // 新客户端发送按目标日期解析的 ISO；存量客户端裸串按请求时区固化，不能依赖宿主时区。
+            // 缺少时区信息或无法解析时保留原文，不做无依据的改写。
+            if (typeof payload?.expiresAt === 'string' && payload.expiresAt.trim() !== '') {
+              card.expiresAt = String(canonicalResetCardExpiresAt(
+                payload.expiresAt.trim(),
+                payload?.timezoneOffsetMinutes,
+                payload?.timeZone,
+              )).slice(0, 32)
+            }
             config.resetCards = [...allCards, card]
           }
           return { value: { ok: true } }