dsh-dfy-pet 2.7.0 → 2.9.0

package/index.js

@@ -7,13 +7,16 @@
  * filesystem work happens here so the browser never needs CORS access or a
  * writable local directory.
  */
-import { performCheck, readHistory, readStatus, KEY_REF } from './monitor.js'; // 监控实现与凭据引用
+import { performCheck, performUsageCheck, readHistory, readStatus, normalizeWebOrigin, KEY_REF } from './monitor.js'; // 监控实现、额度查询与凭据引用
+import { collectTokenUsage } from './token-usage.js'; // 会话日志里的 Token 用量聚合
 
 export const inject = ['connection', 'credentials']; // 认证路由与只读凭据服务
 
 const CHECK_PATH = '/api/deepseek-pet/opencode/check'; // 检查路由绝对路径
 const HISTORY_PATH = '/api/deepseek-pet/opencode/history'; // 历史路由绝对路径
 const STATUS_PATH = '/api/deepseek-pet/opencode/status'; // 当前状态路由绝对路径
+const USAGE_PATH = '/api/deepseek-pet/opencode/usage'; // OpenCode Go 剩余额度路由绝对路径
+const TOKEN_USAGE_PATH = '/api/deepseek-pet/tokens/usage'; // Token 用量统计路由绝对路径
 const MAX_KEY_LENGTH = 4096; // 限制请求体里的 Key 长度
 
 function jsonResponse(body, status = 200) { // 统一的 JSON 响应
@@ -29,6 +32,8 @@ function errorResponse(error, status) { // 统一的错误响应
 
 export function apply(ctx) { // 注册监控路由
   const credentials = ctx.credentials; // 凭据服务
+  // 会话查询服务不写进 inject：万一宿主没挂载这个服务，也只是用量面板不可用，桌宠本身照常工作。
+  const readSessionQuery = () => (typeof ctx.get === 'function' ? ctx.get('sessionQuery') : ctx.sessionQuery); // 延迟取会话查询服务
   const routes = ctx.connection.fetch; // Host 认证路由注册表
   let queue = Promise.resolve(); // 串行化检查，避免并发写快照
   const enqueue = (task) => { // 把任务接入串行队列
@@ -105,4 +110,53 @@ export function apply(ctx) { // 注册监控路由
       } // 结束异常
     }, // 结束状态处理器
   }); // 结束状态路由
+
+  routes.register({ // 剩余额度路由
+    path: USAGE_PATH, // 绝对注册路径
+    methods: ['POST'], // 用 POST 才能接收可选的 Key 与来源覆盖
+    requestBody: 'buffered', // 缓冲读取请求体
+    fetch: async (request) => { // 处理一次额度查询
+      try { // 统一捕获失败
+        const body = await readBody(request); // 读取请求体
+        const provided = typeof body.apiKey === 'string' ? body.apiKey.trim() : ''; // 提取请求中的 Key
+        if (provided.length > MAX_KEY_LENGTH) return errorResponse(new Error('API Key 过长'), 400); // 拒绝超长 Key
+        await storeKey(provided); // 保存非空 Key，与模型检查共用同一凭据
+        const apiKey = provided.length > 0 ? provided : await resolveKey(); // 本次使用的 Key
+        const usageUrl = typeof body.usageUrl === 'string' ? body.usageUrl.trim() : ''; // 自定义用量来源
+        const fallbackUrl = typeof body.fallbackUrl === 'string' ? body.fallbackUrl.trim() : ''; // 备用用量来源
+        const rawOrgId = typeof body.orgId === 'string' ? body.orgId.trim() : ''; // 团队工作区 id
+        const orgId = /^[A-Za-z0-9_-]{1,64}$/.test(rawOrgId) ? rawOrgId : ''; // 只接受安全的组织 id
+        if (usageUrl.length > MAX_KEY_LENGTH || fallbackUrl.length > MAX_KEY_LENGTH) return errorResponse(new Error('接口地址过长'), 400); // 限制地址长度
+        for (const candidate of [usageUrl, fallbackUrl]) { // 逐个校验地址
+          if (candidate.length === 0) continue; // 未填写就跳过
+          normalizeWebOrigin(candidate); // 非法地址直接抛 400
+        } // 结束地址校验
+        const result = await enqueue(() => performUsageCheck({ apiKey, signal: request.signal, usageUrl, fallbackUrl, orgId })); // 串行查询，避免与检查同时写目录
+        return jsonResponse({ ok: true, ...result }); // 返回三窗口额度与来源
+      } catch (error) { // 查询失败
+        const status = error instanceof Error && /接口地址|API Key/.test(error.message) ? 400 : 502; // 参数错误用 400，上游错误用 502
+        return errorResponse(error, status); // 返回可读原因
+      } // 结束异常
+    }, // 结束额度处理器
+  }); // 结束剩余额度路由
+
+  routes.register({ // Token 用量路由
+    path: TOKEN_USAGE_PATH, // 绝对注册路径
+    methods: ['GET'], // 只读
+    requestBody: 'buffered', // 与注册协议保持一致
+    fetch: async (request) => { // 处理一次用量统计
+      try { // 统一捕获失败
+        const sessionQuery = readSessionQuery(); // 取会话查询服务
+        if (sessionQuery === undefined) return errorResponse(new Error('当前 Harness 没有启用会话查询服务'), 501); // 没有数据源就直说
+        const url = new URL(request.url); // 解析查询参数
+        const rawTimeZone = url.searchParams.get('timeZone') ?? ''; // 客户端所在时区
+        const timeZone = /^[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+){0,2}$/.test(rawTimeZone) ? rawTimeZone : 'Asia/Shanghai'; // 只接受形状安全的时区名
+        const force = url.searchParams.get('force') === '1'; // 是否强制重算，跳过缓存
+        const result = await collectTokenUsage(sessionQuery, { timeZone, force }); // 聚合会话日志里的用量
+        return jsonResponse({ ok: true, ...result }); // 返回统计结果
+      } catch (error) { // 统计失败
+        return errorResponse(error, 500); // 以 500 返回原因
+      } // 结束异常
+    }, // 结束用量处理器
+  }); // 结束 Token 用量路由
 } // 结束 apply

package/monitor.js

@@ -3,6 +3,8 @@ import path from 'node:path'; // 路径拼接
 import os from 'node:os'; // 用户主目录
 
 export const MODELS_URL = 'https://opencode.ai/zen/go/v1/models'; // OpenCode Go 实时模型端点
+export const USAGE_URL = 'https://opencode.ai/zen/go/v1/usage'; // OpenCode Go 剩余额度端点，与桌面版同源
+export const CONSOLE_ORIGIN = 'https://opencode.ai/console'; // Console 站点根地址，用于替换接口来源与拼接用量页
 export const DOCS_URL = 'https://opencode.ai/docs/go/'; // 定价与月度配额文档
 export const SNAPSHOT_VERSION = 1; // 快照格式版本
 export const MAX_SNAPSHOTS = 50; // 本地最多保留的检查次数
@@ -398,3 +400,149 @@ export async function performCheck(options = {}) { // 执行一次检查
   const file = await writeSnapshot(snapshot, dir); // 原子写入
   return { ok: true, checkedAt: snapshot.checkedAt, baseline: diff.baseline, counts: diff.counts, added: diff.added, removed: diff.removed, changed: diff.changed, warnings: snapshot.warnings, models: snapshot.models, file, plans: (docs?.plans ?? []).map((plan) => plan.label) }; // 返回检查结果与当前模型
 } // 结束检查
+
+export const USAGE_WINDOWS = [ // 服务端返回的三个额度窗口，顺序即展示顺序
+  { key: 'rolling', labelKey: 'ocWindowRolling' }, // 5 小时滚动窗口
+  { key: 'weekly', labelKey: 'ocWindowWeekly' }, // 每周窗口
+  { key: 'monthly', labelKey: 'ocWindowMonthly' }, // 每月窗口
+]; // 结束窗口定义
+const MAX_CONSOLE_ORIGIN = 'https://console.opencode.ai'; // 旧版 Console 域名，需要改写到 opencode.ai 才能取到用量
+const USAGE_TIMEOUT_MS = 15000; // 用量接口超时，超时后仍要报出余额为空而不是整块失败
+
+function clampPercent(value) { // 把百分比收敛到 0-100
+  const number = numberOrNull(value); // 只接受有限数字
+  return number === null ? null : Math.max(0, Math.min(100, number)); // 越界值截断，非数字返回 null
+} // 结束百分比收敛
+
+function windowFromPayload(item) { // 解析单个额度窗口
+  const percent = clampPercent(item?.percent); // 已用百分比
+  if (percent === null) return null; // 缺字段视为该窗口无数据
+  const resetsAt = typeof item?.resetsAt === 'string' && Number.isFinite(Date.parse(item.resetsAt)) ? item.resetsAt : null; // 重置时刻，非法日期置空
+  return { percent, remaining: Math.max(0, Math.round((100 - percent) * 10) / 10), limited: item?.status === 'rate-limited', status: typeof item?.status === 'string' ? item.status : 'ok', resetsAt }; // 剩余百分比由已用推算
+} // 结束窗口解析
+
+export function parseUsagePayload(payload) { // 把 /zen/go/v1/usage 的响应转成内部结构
+  const usage = payload?.usage ?? {}; // 响应用 usage 包裹（实测为字符串百分比）
+  const windows = {}; // 三个窗口的结果
+  for (const window of USAGE_WINDOWS) { // 逐个窗口解析
+    windows[window.key] = windowFromPayload(usage[window.key]); // 缺数据时为 null
+  } // 结束窗口遍历
+  return { windows, fetchedAt: new Date().toISOString() }; // 附带抓取时间
+} // 结束用量解析
+
+export async function fetchUsage(apiKey, signal, options = {}) { // 读取 OpenCode Go 剩余额度
+  const key = typeof apiKey === 'string' ? apiKey.trim() : ''; // 统一 Key 输入
+  if (key.length === 0) throw new Error('还没有保存 OpenCode API Key，无法查询用量'); // 无 Key 直接给出可行动提示
+  const url = options.url ?? USAGE_URL; // 允许测试传入替身地址
+  const headers = { 'user-agent': 'deepseek-harness-opencode-go-monitor/1.0', accept: 'application/json', authorization: `Bearer ${key}` }; // 与桌面版相同的鉴权头
+  if (options.orgId) headers['x-opencode-org-id'] = options.orgId; // 团队工作区需要带上组织 id 才能看到本成员额度
+  const response = await fetchWithRetry(url, { headers, signal }, { timeoutMs: USAGE_TIMEOUT_MS, retries: 1 }); // 超时与一次重试
+  if (response.status === 401 || response.status === 403) { // 权限问题
+    await response.body?.cancel(); // 释放响应体
+    throw new Error(`用量查询认证失败（HTTP ${response.status}）：这个 Key 可能不是 Console 的 oc_sk_ 密钥，或当前 IP 被限制`); // 指向真正的失败原因
+  } // 结束权限分支
+  if (!response.ok) { // 其他状态码
+    await response.body?.cancel(); // 释放响应体
+    throw new Error(`用量接口返回 HTTP ${response.status}`); // 保留状态便于排查
+  } // 结束状态判断
+  const payload = await response.json().catch(() => null); // 解析 JSON，坏体按空处理
+  if (payload === null) throw new Error('用量接口返回了无法解析的内容'); // 明确失败而不是显示空白
+  const parsed = parseUsagePayload(payload); // 规范化结构
+  if (USAGE_WINDOWS.every((window) => parsed.windows[window.key] === null)) throw new Error('用量接口没有返回任何额度窗口'); // 结构变化时提示
+  return parsed; // 返回解析结果
+} // 结束用量抓取
+
+export function normalizeWebOrigin(raw) { // 校验并规范化用户填写的接口地址
+  const text = typeof raw === 'string' ? raw.trim() : ''; // 统一成字符串
+  if (text.length === 0) return null; // 空值表示未填写
+  let parsed; // 解析结果
+  try { // 解析 URL
+    parsed = new URL(text); // 构造 URL
+  } catch (error) { // 非法地址
+    throw new Error('接口地址不是合法的 URL'); // 明确错误
+  } // 结束解析
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') throw new Error('接口地址必须是 http 或 https'); // 只接受网页协议
+  if (parsed.username.length > 0 || parsed.password.length > 0) throw new Error('接口地址不能包含账号密码'); // 拒绝把凭据塞进地址
+  return parsed.origin.replace(/^https:\/\/console\.opencode\.ai$/, MAX_CONSOLE_ORIGIN); // 旧域名统一改写到主站
+} // 结束地址规范化
+
+export function usagePageUrl(origin) { // 拼接 Console 用量页
+  return `${origin ?? MAX_CONSOLE_ORIGIN}/console`; // 没有自定义地址时指向默认 Console
+} // 结束用量页地址
+
+function usageFilePath(dir) { // 剩余额度缓存的路径
+  return path.join(dir, 'usage.json'); // 与模型快照同目录，便于一起清理
+} // 结束路径解析
+
+export async function readUsage(dir = snapshotDir()) { // 读取上一次成功保存的额度
+  try { // 容错读取
+    const raw = await fs.readFile(usageFilePath(dir), 'utf8'); // 读取文本
+    const parsed = JSON.parse(raw); // 解析 JSON
+    if (parsed && typeof parsed === 'object' && parsed.windows && typeof parsed.windows === 'object') return parsed; // 只接受有窗口的结构
+    return null; // 结构不符视为无缓存
+  } catch (error) { // 文件不存在或损坏
+    return null; // 缓存缺失不影响主流程
+  } // 结束容错
+} // 结束额度读取
+
+export async function writeUsage(usage, dir = snapshotDir()) { // 原子写入额度缓存
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 }); // 保证目录存在且仅本人可读
+  const target = usageFilePath(dir); // 目标文件
+  const temp = path.join(dir, `.usage.json.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`); // 临时文件
+  try { // 写入过程
+    await fs.writeFile(temp, JSON.stringify(usage, null, 2), { mode: 0o600 }); // 只写额度，不含 Key
+    await fs.rename(temp, target); // 同目录原子替换
+  } catch (error) { // 写入失败
+    await fs.rm(temp, { force: true }); // 清理临时文件
+    throw error; // 继续抛出
+  } // 结束异常
+} // 结束额度写入
+
+export async function performUsageCheck(options = {}) { // 查询一次额度并缓存
+  const dir = options.dir ?? snapshotDir(); // 缓存目录
+  const apiKey = typeof options.apiKey === 'string' ? options.apiKey.trim() : ''; // 本次使用的 Key
+  const stored = await readUsage(dir); // 先取上次结果，失败时还能展示
+  const errors = []; // 各来源的失败原因
+  let usage = null; // 成功的额度
+  let source = 'models'; // 默认沿用上方的模型端点来源
+  let origin = null; // 实际使用的 Console 地址
+  const url = typeof options.usageUrl === 'string' && options.usageUrl.trim().length > 0 ? options.usageUrl.trim() : USAGE_URL; // 默认官方地址，可通过设置覆盖
+  try { // 允许使用自定义来源
+    origin = normalizeWebOrigin(url); // 自定义地址写入来源提示
+  } catch (error) { // 原始地址不是合法来源
+    origin = null; // 视为使用默认
+  } // 结束来源解析
+  if (apiKey.length > 0) { // 有 Key 才请求
+    try { // 主来源
+      const parsed = await fetchUsage(apiKey, options.signal, { url, orgId: options.orgId }); // 请求官方用量
+      usage = parsed; // 记录成功结果
+      source = url === USAGE_URL ? 'official' : 'custom'; // 标注来源
+    } catch (error) { // 主来源失败
+      errors.push(error instanceof Error ? error.message : String(error)); // 收集原因
+      if (options.fallbackUrl) { // 配置了备用地址才尝试
+        try { // 备用来源
+          const parsed = await fetchUsage(apiKey, options.signal, { url: options.fallbackUrl, orgId: options.orgId }); // 请求备用用量
+          usage = parsed; // 记录成功结果
+          source = 'fallback'; // 标注备用来源
+          origin = normalizeWebOrigin(options.fallbackUrl) ?? origin; // 成功来源用于拼接页面地址
+        } catch (fallbackError) { // 备用也失败
+          errors.push(fallbackError instanceof Error ? fallbackError.message : String(fallbackError)); // 追加原因
+        } // 结束备用异常
+      } // 结束备用分支
+    } // 结束主来源异常
+  } else { // 没有 Key
+    errors.push('还没有保存 OpenCode API Key，无法查询用量'); // 给出可行动提示
+  } // 结束 Key 判断
+  if (usage !== null) await writeUsage({ ...usage, source }, dir).catch(() => undefined); // 成功才覆盖缓存，写失败不影响返回
+  const current = usage ?? stored; // 本次或上次
+  return { // 汇总结果
+    windows: current?.windows ?? {}, // 三窗口额度
+    fetchedAt: current?.fetchedAt ?? null, // 额度的时间
+    stale: usage === null && current !== null, // 展示的是上次结果
+    source: usage === null ? (current?.source ?? null) : source, // 数据来源
+    origin, // 用于打开用量页的地址来源
+    pageUrl: usagePageUrl(origin), // Console 页面地址
+    errors, // 失败原因
+    hasKey: apiKey.length > 0, // Key 状态
+  }; // 结束汇总
+} // 结束额度检查

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-dfy-pet",
-  "version": "2.7.0",
-  "description": "A chibi DeepSeek whale-girl desktop pet with right-click AI relay provider configuration and an OpenCode Go model/pricing/quota monitor.",
+  "version": "2.9.0",
+  "description": "A chibi DeepSeek whale-girl desktop pet with right-click AI relay provider configuration, an OpenCode Go model/pricing/quota monitor, and a remaining-usage panel for the 5-hour, weekly and monthly Go allowance.",
   "license": "Apache-2.0",
   "keywords": [
     "deepseek-harness",
@@ -35,6 +35,7 @@
   "files": [
     "index.js",
     "monitor.js",
+    "token-usage.js",
     "client.js",
     "cordis.patch.yml",
     "locale/*.json",

package/token-usage.js

@@ -0,0 +1,367 @@
+/**
+ * Host 侧的 Token 用量聚合。
+ *
+ * 数据来自 DSH 自己的会话日志：每次模型调用都会在 `assistant/message` 事件里
+ * 记下 `data.usage`（inputTokens / cacheReadTokens / outputTokens / totalTokens）
+ * 与 `data.message.source`（provider / model）。这里把这些事件汇总成
+ * 「本日 / 本周 / 本月」三个周期，以及每个周期内各模型的用量。
+ *
+ * 关键点是去重：DSH 的「种子会话」（isSeeded）会把父会话的整段历史复制进子会话，
+ * 父子两份日志里同一批事件各出现一次，直接相加会翻倍。日志里 `session/end-seed`
+ * 事件标出了继承与自有的分界，据此可以只认领「自有事件」；但当父会话已被删除时，
+ * 继承来的那段历史就没人认领了，这时必须由子会话代为计入，否则用量会凭空少一截。
+ */
+
+/** 三个统计周期的键，顺序即界面上的展示顺序。 */
+export const TOKEN_PERIODS = ['day', 'week', 'month'];
+
+/** 聚合结果的默认缓存时长：会话日志重放不便宜，短时间内重复请求直接复用缓存。 */
+const DEFAULT_TTL_MS = 60_000;
+
+/** 超过这个天数的会话不再读取，避免历史会话把每次刷新拖慢。 */
+const MAX_SESSION_AGE_DAYS = 120;
+
+/** 每个周期回溯的天数：本日=0、本周=6（周一到今天共 7 天）、本月=29。 */
+const PERIOD_SPAN_DAYS = { day: 0, week: 6, month: 29 };
+
+/**
+ * 把毫秒时间戳换算成指定时区的日历日期。
+ * @param {number} ms - 毫秒时间戳。
+ * @param {string} timeZone - IANA 时区名，例如 Asia/Shanghai。
+ * @returns {{ y: number, m: number, d: number }} - 该时区下的年月日。
+ */
+export function localDate(ms, timeZone) {
+  const parts = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(new Date(ms)); // 取本地年月日各段
+  const lookup = {}; // 段类型到取值的映射
+  for (const part of parts) lookup[part.type] = part.value; // 逐段收集
+  return { y: Number(lookup.year), m: Number(lookup.month), d: Number(lookup.day) }; // 返回年月日
+}
+
+/**
+ * 把毫秒时间戳换算成指定时区的小时。
+ * @param {number} ms - 毫秒时间戳。
+ * @param {string} timeZone - IANA 时区名。
+ * @returns {number} - 0 到 23 的小时数。
+ */
+export function localHour(ms, timeZone) {
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone, hour12: false, hour: '2-digit' }).formatToParts(new Date(ms)); // 取本地小时
+  const lookup = {}; // 段类型到取值的映射
+  for (const part of parts) lookup[part.type] = part.value; // 逐段收集
+  return Number(lookup.hour) % 24; // 返回小时数
+}
+
+/**
+ * 求某个时区在给定瞬间相对 UTC 的偏移毫秒数。
+ * @param {number} ms - 毫秒时间戳。
+ * @param {string} timeZone - IANA 时区名。
+ * @returns {number} - 偏移毫秒，东八区为 -8 小时。
+ */
+function zoneOffset(ms, timeZone) {
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone, hour12: false, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' }).formatToParts(new Date(ms)); // 取本地时间各段
+  const lookup = {}; // 段类型到取值的映射
+  for (const part of parts) lookup[part.type] = part.value; // 逐段收集
+  const asUtc = Date.UTC(Number(lookup.year), Number(lookup.month) - 1, Number(lookup.day), Number(lookup.hour) % 24, Number(lookup.minute), Number(lookup.second)); // 把本地时间当作 UTC 拼出毫秒
+  return asUtc - ms; // 与真实 UTC 的差值就是时区偏移
+}
+
+/**
+ * 求指定时区里某个日历日期的零点时刻。
+ * @param {{ y: number, m: number, d: number }} date - 日历日期。
+ * @param {string} timeZone - IANA 时区名。
+ * @returns {number} - 该日零点的毫秒时间戳。
+ */
+export function startOfLocalDate(date, timeZone) {
+  const base = Date.UTC(date.y, date.m - 1, date.d); // 先把日历日期当成 UTC 零点，得到一个初值
+  let guess = base; // 当前猜测的零点时刻
+  for (let round = 0; round < 3; round += 1) { // 最多校正三轮，跨夏令时也能收敛
+    const offset = zoneOffset(guess, timeZone); // 该猜测时刻下的时区偏移
+    const next = base - offset; // 用偏移修正出新的零点
+    if (next === guess) break; // 已经收敛，无需继续
+    guess = next; // 继续用新猜测
+  } // 结束校正
+  return guess; // 返回本地零点
+}
+
+/**
+ * 在日历日期上加减天数，避免夏令时导致固定 24 小时步长偏移。
+ * @param {{ y: number, m: number, d: number }} date - 起始日期。
+ * @param {number} days - 要加的天数，可为负。
+ * @returns {{ y: number, m: number, d: number }} - 结果日期。
+ */
+export function addCalendarDays(date, days) {
+  const shifted = new Date(Date.UTC(date.y, date.m - 1, date.d) + days * 86_400_000); // 按 UTC 做日历加减
+  return { y: shifted.getUTCFullYear(), m: shifted.getUTCMonth() + 1, d: shifted.getUTCDate() }; // 转回年月日
+}
+
+/**
+ * 计算三个周期的起点。
+ * @param {number} now - 当前毫秒时间戳。
+ * @param {string} timeZone - IANA 时区名。
+ * @returns {Record<string, { start: number, startDate: { y: number, m: number, d: number } }>} - 各周期的起点。
+ */
+export function periodBounds(now, timeZone) {
+  const today = localDate(now, timeZone); // 今天的日历日期
+  const todayStart = startOfLocalDate(today, timeZone); // 今天零点的时刻
+  // 星期几必须按「本地日历日期」算：本地零点的那个瞬间在东八区落在前一个 UTC 日，
+  // 直接取 getUTCDay() 会把周一算成周日、周起点整整差一天。
+  const weekday = new Date(Date.UTC(today.y, today.m - 1, today.d)).getUTCDay(); // 用日历日期本身求星期几
+  const daysSinceMonday = (weekday + 6) % 7; // 距本周一过了几天
+  const weekStartDate = addCalendarDays(today, -daysSinceMonday); // 本周一
+  const monthStartDate = { y: today.y, m: today.m, d: 1 }; // 本月 1 号
+  return { // 三个周期的起点
+    day: { start: todayStart, startDate: today }, // 本日零点
+    week: { start: startOfLocalDate(weekStartDate, timeZone), startDate: weekStartDate }, // 本周周一零点
+    month: { start: startOfLocalDate(monthStartDate, timeZone), startDate: monthStartDate }, // 本月 1 号零点
+  }; // 结束返回
+}
+
+/**
+ * 造一个空的序列点位。
+ * @param {string} key - 点的标识（小时序号或日期）。
+ * @param {string} label - 界面上的标签。
+ * @returns {object} - 空的点位。
+ */
+function emptyPoint(key, label) {
+  return { key, label, input: 0, output: 0, cacheRead: 0, total: 0, calls: 0 }; // 各计数从零开始
+}
+
+/**
+ * 造一个与所选周期匹配的时间序列：本日按小时，本周与本月按天。
+ * 序列会补齐没有用量的时段，界面上才看得出空档。
+ * @param {Array<object>} records - 扁平的用量记录。
+ * @param {{ start: number, startDate: object }} bounds - 周期起点。
+ * @param {{ period: string, timeZone: string, now: number }} options - 周期、时区与当前时刻。
+ * @returns {{ unit: string, points: Array<object> }} - 序列单位与点位。
+ */
+function buildSeries(records, bounds, options) {
+  const { period, timeZone, now } = options; // 解出周期、时区与当前时刻
+  const points = []; // 序列点位
+  const index = new Map(); // 点位键到点位对象的映射
+  if (period === 'day') { // 本日按小时切：一天只有一根柱子看不出起伏
+    for (let hour = 0; hour < 24; hour += 1) { // 铺满 24 个小时
+      const point = emptyPoint(String(hour), `${hour}`); // 标签就是小时数
+      points.push(point); // 依次加入
+      index.set(point.key, point); // 登记索引
+    } // 结束铺满
+  } else { // 本周与本月按天切
+    const today = localDate(now, timeZone); // 今天的日历日期
+    let cursor = bounds.startDate; // 从周期起始日期开始
+    for (let guard = 0; guard < 400; guard += 1) { // 最多铺 400 天，防御异常起点
+      const key = `${cursor.y}-${String(cursor.m).padStart(2, '0')}-${String(cursor.d).padStart(2, '0')}`; // 日期键
+      const point = emptyPoint(key, `${cursor.m}/${cursor.d}`); // 标签是月/日
+      points.push(point); // 依次加入
+      index.set(key, point); // 登记索引
+      if (cursor.y === today.y && cursor.m === today.m && cursor.d === today.d) break; // 到今天为止
+      cursor = addCalendarDays(cursor, 1); // 往后一天
+    } // 结束铺日
+  } // 结束切分方式
+  for (const record of records) { // 逐条记录落到对应点位
+    if (record.time < bounds.start) continue; // 周期起点之前的记录不计入
+    const point = period === 'day' // 本日落到小时点位
+      ? index.get(String(localHour(record.time, timeZone))) // 按小时找点位
+      : index.get(`${localDate(record.time, timeZone).y}-${String(localDate(record.time, timeZone).m).padStart(2, '0')}-${String(localDate(record.time, timeZone).d).padStart(2, '0')}`); // 按日期找点位
+    if (point === undefined) continue; // 找不到对应点位就跳过
+    point.input += record.input; // 累加未缓存输入
+    point.output += record.output; // 累加输出
+    point.cacheRead += record.cacheRead; // 累加缓存读取
+    point.total += record.total; // 累加总量
+    point.calls += 1; // 累加调用次数
+  } // 结束逐条落点
+  return { unit: period === 'day' ? 'hour' : 'day', points }; // 返回序列
+}
+
+/**
+ * 把若干条用量记录按模型与周期汇总。
+ * @param {Array<object>} records - 扁平的用量记录。
+ * @param {{ start: number, startDate: object }} bounds - 周期起点。
+ * @param {{ period: string, timeZone: string, now: number }} options - 周期、时区与当前时刻。
+ * @returns {object} - 该周期的汇总结果。
+ */
+function summarize(records, bounds, options) {
+  const since = bounds.start; // 周期起点时刻
+  const models = new Map(); // 模型键到计数的映射
+  let input = 0; // 未缓存输入合计
+  let output = 0; // 输出合计
+  let cacheRead = 0; // 缓存读取合计
+  let total = 0; // 总量合计
+  let calls = 0; // 调用次数合计
+  for (const record of records) { // 逐条记录累加
+    if (record.time < since) continue; // 周期起点之前的记录不计入
+    input += record.input; // 累加未缓存输入
+    output += record.output; // 累加输出
+    cacheRead += record.cacheRead; // 累加缓存读取
+    total += record.total; // 累加总量
+    calls += 1; // 累加调用次数
+    const key = `${record.provider}::${record.model}`; // 模型键：提供方加模型名
+    let bucket = models.get(key); // 该模型的累计桶
+    if (bucket === undefined) { // 首次遇到这个模型
+      bucket = { provider: record.provider, model: record.model, calls: 0, input: 0, output: 0, cacheRead: 0, total: 0 }; // 新建桶
+      models.set(key, bucket); // 登记到映射里
+    } // 结束首次判断
+    bucket.calls += 1; // 累加该模型的调用次数
+    bucket.input += record.input; // 累加该模型的未缓存输入
+    bucket.output += record.output; // 累加该模型的输出
+    bucket.cacheRead += record.cacheRead; // 累加该模型的缓存读取
+    bucket.total += record.total; // 累加该模型的总量
+  } // 结束逐条累加
+  const modelList = [...models.values()].sort((a, b) => b.total - a.total); // 按总量降序
+  for (const bucket of modelList) { // 补上占比
+    bucket.share = total > 0 ? bucket.total / total : 0; // 该模型占本周期总量的比例
+  } // 结束补占比
+  const series = buildSeries(records, bounds, options); // 该周期自己的时间序列
+  return { since, totals: { input, output, cacheRead, total, calls }, models: modelList, series }; // 返回该周期汇总
+}
+
+/**
+ * 从一条会话日志里抽出带用量的模型调用。
+ * @param {Array<object>} events - 会话事件列表。
+ * @param {number} minSeq - 只认领 seq 大于该值的事件；传 -1 表示全认领。
+ * @returns {Array<object>} - 抽出的用量记录。
+ */
+function extractUsage(events, minSeq) {
+  const rows = []; // 抽出的用量记录
+  for (const event of events) { // 逐个事件检查
+    if (event === null || typeof event !== 'object') continue; // 跳过异常事件
+    if (event.type !== 'assistant/message') continue; // 只有助手消息带用量
+    const data = event.data; // 事件正文
+    if (data === null || typeof data !== 'object') continue; // 跳过没有正文的
+    const usage = data.usage; // 用量对象
+    if (usage === null || typeof usage !== 'object') continue; // 没用量说明这步没真正调用模型
+    const seq = typeof event.seq === 'number' ? event.seq : 0; // 事件序号
+    if (seq <= minSeq) continue; // 超出认领范围
+    const source = (data.message === null || typeof data.message !== 'object' ? {} : data.message.source) || {}; // 该步实际调用的供应商与模型
+    rows.push({ // 记一条用量
+      time: typeof event.time === 'number' ? event.time : 0, // 事件时间戳
+      provider: typeof source.provider === 'string' ? source.provider : 'unknown', // 供应商标识
+      model: typeof source.model === 'string' ? source.model : 'unknown', // 模型标识
+      input: usage.inputTokens || 0, // 未命中缓存的输入 token
+      output: usage.outputTokens || 0, // 输出 token
+      cacheRead: usage.cacheReadTokens || 0, // 命中缓存读取的 token
+      total: usage.totalTokens || 0, // 该次调用总量
+    }); // 结束记录
+  } // 结束逐事件检查
+  return rows; // 返回用量记录
+}
+
+/**
+ * 找到日志里继承与自有的分界序号。
+ * @param {Array<object>} events - 会话事件列表。
+ * @returns {number} - `session/end-seed` 事件的序号；没有则返回 -1 表示全部自有。
+ */
+function seedBoundary(events) {
+  let boundary = -1; // 默认没有继承
+  for (const event of events) { // 逐个事件检查
+    if (event === null || typeof event !== 'object') continue; // 跳过异常事件
+    if (event.type !== 'session/end-seed') continue; // 只认分界标记
+    if (typeof event.seq === 'number' && event.seq > boundary) boundary = event.seq; // 取最大的一个作为分界
+  } // 结束逐事件检查
+  return boundary; // 返回分界序号
+}
+
+/**
+ * 读取全部会话并汇总 Token 用量。
+ * @param {object} sessionQuery - DSH 的会话查询服务。
+ * @param {{ now?: number, timeZone?: string, ttlMs?: number, force?: boolean }} options - 可选项。
+ * @returns {Promise<object>} - 聚合结果。
+ */
+export async function collectTokenUsage(sessionQuery, options = {}) {
+  const now = typeof options.now === 'number' ? options.now : Date.now(); // 当前时刻
+  const timeZone = typeof options.timeZone === 'string' && options.timeZone.length > 0 ? options.timeZone : 'Asia/Shanghai'; // 统计时区
+  const ttlMs = typeof options.ttlMs === 'number' ? options.ttlMs : DEFAULT_TTL_MS; // 缓存时长
+  const force = options.force === true; // 是否跳过缓存
+  const state = collectTokenUsage.state; // 模块级缓存，跨请求复用
+  if (!force && state.cache !== null && now - state.cachedAt < ttlMs) { // 命中新鲜缓存
+    return state.cache; // 直接返回缓存结果
+  } // 结束缓存判断
+  const listed = await sessionQuery.listSessions(); // 列出全部逻辑会话，最新的在前
+  const records = Array.isArray(listed) ? listed : []; // 归一成数组
+  const listedIds = new Set(); // 已登记的会话 id 集合
+  for (const record of records) { // 逐条登记
+    const id = record?.header?.id; // 会话 id
+    if (typeof id === 'string' && id.length > 0) listedIds.add(id); // 登记 id
+  } // 结束登记
+  const oldestAllowed = now - MAX_SESSION_AGE_DAYS * 86_400_000; // 允许读取的最老会话时间
+  const rows = []; // 全部用量记录
+  let scanned = 0; // 实际读取的会话数
+  let skipped = 0; // 跳过的会话数
+  let failed = 0; // 读取失败的会话数
+  for (const record of records) { // 逐个会话处理
+    const header = record?.header; // 会话头
+    const id = header?.id; // 会话 id
+    if (typeof id !== 'string' || id.length === 0) { // 没有可用 id
+      skipped += 1; // 计入跳过
+      continue; // 继续下一个
+    } // 结束 id 检查
+    const createdAt = typeof header.createdAt === 'number' ? header.createdAt : 0; // 创建时间
+    if (createdAt > 0 && createdAt < oldestAllowed) { // 太老的会话不读
+      skipped += 1; // 计入跳过
+      continue; // 继续下一个
+    } // 结束时效检查
+    let events = null; // 读到的会话事件
+    let inheritedCount = 0; // 会话声明的继承事件条数
+    try { // 读取会话日志
+      const snapshot = await sessionQuery.readSession(id); // 重放整份日志
+      events = Array.isArray(snapshot?.events) ? snapshot.events : []; // 归一成事件数组
+      inheritedCount = typeof snapshot?.inheritedEventCount === 'number' ? snapshot.inheritedEventCount : 0; // 继承条数
+    } catch (error) { // 读取失败
+      failed += 1; // 计入失败
+      continue; // 继续下一个会话
+    } // 结束读取
+    scanned += 1; // 计入已扫描
+    const boundary = seedBoundary(events); // 继承与自有的分界
+    const parentId = typeof header.parentSession === 'string' ? header.parentSession : ''; // 父会话 id
+    const parentPresent = parentId.length > 0 && listedIds.has(parentId); // 父会话是否还在
+    const parentReadable = parentPresent && !state.unreadable.has(parentId); // 父会话是否读得动
+    // 父会话还在就只认自有事件；父会话没了就由子会话把继承的一段也认领，否则这段用量会凭空消失。
+    // 分界优先用日志里的 session/end-seed 标记；标记缺失时退回会话声明的继承条数。
+    let minSeq = -1; // 默认整份日志都认领
+    if (parentPresent && parentReadable) { // 只有父会话还在时才要剔除继承段
+      minSeq = boundary >= 0 ? boundary : (inheritedCount > 0 ? inheritedCount - 1 : -1); // 取分界序号
+    } // 结束剔除判断
+    for (const row of extractUsage(events, minSeq)) rows.push(row); // 抽出并汇总用量
+    if (parentPresent && !parentReadable) state.unreadable.add(id); // 记下这个会话自己也读不动，供后续判断
+  } // 结束逐会话处理
+  const bounds = periodBounds(now, timeZone); // 三个周期的起点
+  const periods = {}; // 各周期汇总
+  for (const period of TOKEN_PERIODS) periods[period] = summarize(rows, bounds[period], { period, timeZone, now }); // 逐周期汇总，各自带上匹配的时间序列
+  const daily = new Map(); // 日期到当日合计的映射
+  for (const row of rows) { // 逐条记录归到日期
+    const day = localDate(row.time, timeZone); // 该条记录的本地日期
+    const key = `${day.y}-${String(day.m).padStart(2, '0')}-${String(day.d).padStart(2, '0')}`; // 日期键
+    let bucket = daily.get(key); // 当天的合计桶
+    if (bucket === undefined) { // 首次见到这天
+      bucket = { day: key, input: 0, output: 0, cacheRead: 0, total: 0, calls: 0 }; // 新建桶
+      daily.set(key, bucket); // 登记
+    } // 结束首次判断
+    bucket.input += row.input; // 累加当天未缓存输入
+    bucket.output += row.output; // 累加当天输出
+    bucket.cacheRead += row.cacheRead; // 累加当天缓存读取
+    bucket.total += row.total; // 累加当天总量
+    bucket.calls += 1; // 累加当天调用次数
+  } // 结束按日归并
+  const dailyList = [...daily.values()].sort((a, b) => (a.day < b.day ? -1 : 1)).slice(-30); // 按日期升序，只保留最近 30 天给界面画趋势
+  const result = { // 组装返回结果
+    fetchedAt: now, // 抓取时间
+    timeZone, // 统计时区
+    sessions: { listed: records.length, scanned, skipped, failed }, // 会话统计
+    periods, // 三个周期的汇总
+    daily: dailyList, // 近 N 天的每日趋势
+    spanDays: PERIOD_SPAN_DAYS, // 周期跨度说明，供界面标注
+  }; // 结束组装
+  state.cache = result; // 写入缓存
+  state.cachedAt = now; // 记录缓存时间
+  state.unreadable = new Set(); // 重置读不动的会话集合
+  return result; // 返回结果
+}
+
+/** 模块级缓存：跨请求复用聚合结果，避免每次都重放会话日志。 */
+collectTokenUsage.state = { cache: null, cachedAt: 0, unreadable: new Set() };
+
+/**
+ * 清空聚合缓存，供调试或强制刷新使用。
+ * @returns {void}
+ */
+export function resetTokenUsageCache() {
+  collectTokenUsage.state.cache = null; // 丢掉缓存结果
+  collectTokenUsage.state.cachedAt = 0; // 把缓存时间归零
+}