dsh-later 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@
 
 ## 未发布
 
+## 1.2.0 — 2026-10-09
+
+- **feat** 暴露跨插件「定时任务摘要」公共 API（issue #17）。
+  - 新增 `src/schedule-summary.ts`（纯函数，宿主/浏览器/`node --test` 共用）：
+    `buildScheduleSummary` 把 `sessions.list` 折叠成
+    `Map<SessionId, { count, pausedCount, nextAt, state }>`；`summarizeScheduleGroup`
+    按分组聚合（会话数/任务数/最早触发/最高优先级，`overdue > urgent > scheduled`）。
+  - 新增 `src/schedule-summary-store.ts`：可订阅 store（`getSnapshot` / `subscribe` /
+    `reload` / `dispose`）+ 全局登记表，**唯一数据权威**——内部负责 `sessions.list`
+    订阅、30s 状态 tick 与 60s `session.list` 读 RPC（仅页面可见时）。
+  - 新增 `src/client/useScheduleSummary.ts`：React 订阅 hook（`useSyncExternalStore`，
+    store 迟到时自动重渲染）。
+  - `lib/client.js` 导出 `getScheduleSummaryStore` / `subscribeScheduleSummaryStore` /
+    `useScheduleSummary` / `buildScheduleSummary` / `schedulesOfProjection` /
+    `summarizeScheduleGroup` / `createScheduleSummaryStore` 及类型；消费方（如
+    dsh-group-status）声明 `dsh.client.external: ["dsh-later"]` 后
+    `require('dsh-later/client')` 即可使用。契约见
+    [API 参考 §7](./docs/technical/03-api-reference.md)。
+  - **refactor** 侧栏 badge 不再自己读 `sessions.list` / 周期 `refresh()`，改为消费同一个
+    store：外部插件读到的摘要与本插件行内 badge 必然同源，且 `session.list` 读 RPC
+    不再被拉两次。
+  - 新增 15 个单测：纯逻辑（数量/状态分档/暂停语义/分组聚合/判等）、store
+    （列表变化、状态 tick、refresh 闸门、dispose、登记表）与构建产物契约
+    （`lib/client.js` 导出面 + apply 登记/注销 store）。
+
+- **feat** 侧栏 badge 进度环（方案 A：track + prog 双环）。
+  - 新版时钟 glyph 从单环改为双环：`ss-clock-track` 恒定底环（总窗口参照），
+    `ss-clock-prog` 进度弧从 12 点顺时针填充（`stroke-dashoffset` 驱动）。
+  - 新增 `progressFrom` 字段（`PresenceSummary`）：窗口起点时刻（epoch ms），
+    只跟随 `nextAt` 那条任务。
+  - 新增 `windowStartOf` 推导逻辑，按优先级取窗口跨度：
+    1. `window_seconds`（宿主/投影显式给）→ 最权威
+    2. `after_seconds` / `every_seconds`（按 `kind` 推）
+    3. `created_at`（`at` 类型回退）
+    推不出则 `progressFrom` 缺省，视觉退回恒定整环（旧形状即退化态）。
+  - `progressOf(entry, now)` 返回 0–1 比例；超时停满环（不绕出去）。
+  - urgent 只脉冲底环（进度弧跟着闪会让比例不可读）。
+  - 减少动效模式：进度弧位移过渡一并停。
+  - 新增 11 个单测：after/every/at 窗口推导、window_seconds 优先、退化/非法值、
+    多任务窗口跟随 nextAt、暂停项排除、camelCase 兼容、无窗口时形状不变。
+  - `sameScheduleSummary` 补 `progressFrom` 比对（暂停→恢复窗口换了但 nextAt 未变时
+    仍需通知订阅者刷新进度环）。
+
 ## 1.1.0 — 2026-10-09
 
 - **feat** 设置页 UI 对齐官方 `SettingsForm`：从折叠卡片改为裸表单，字段直接平铺。

package/README.en.md

@@ -191,6 +191,52 @@ Works out of the box. Adjust in **DSH Settings → Plugins → Session Scheduler
 
 ---
 
+## For plugin developers: the schedule summary API (cross-plugin)
+
+dsh-later exposes a workspace-wide schedule summary as a public data face
+([issue #17](http://192.168.4.77:3000/dsh-plugins/dsh-later/issues/17)), so other client
+plugins (e.g. dsh-group-status) can aggregate schedule state on folders/sidebar rows
+**without** parsing the `userSchedules` projection themselves — and without drifting
+from the inline row badge.
+
+Declare the external module in `package.json` first:
+
+```json
+{ "dsh": { "client": { "platform": "web", "external": ["dsh-later"] } } }
+```
+
+Then `require('dsh-later/client')` inside the client factory:
+
+```js
+const { getScheduleSummaryStore, summarizeScheduleGroup, useScheduleSummary } = require('dsh-later/client')
+
+// 1) Read the store directly: session id → { count, pausedCount, nextAt, state }
+const store = getScheduleSummaryStore() // undefined when dsh-later is not loaded
+const summary = store?.getSnapshot() ?? new Map()
+
+// 2) Aggregate per group (used by the folded-folder badge)
+const group = summarizeScheduleGroup(summary, groupSessionIds)
+// → { sessions, count, pausedCount, nextAt?, state? }
+
+// 3) Subscribe inside a React component (re-renders if the store arrives late)
+const live = useScheduleSummary()
+```
+
+| Field | Meaning |
+|---|---|
+| `count` | Number of schedules (**including** paused ones) |
+| `pausedCount` | Paused schedules (they count toward `count` but **not** toward `nextAt`) |
+| `nextAt` | Earliest fire time (epoch ms); `undefined` when everything is paused |
+| `state` | `scheduled` / `urgent` (≤5 min) / `overdue` (due but not dispatched), judged at snapshot time |
+
+Contract notes:
+
+- The summary contains **only sessions with schedules**; consumers look up their own `sessionIds`.
+- The store is the **single source of truth**: dsh-later's own sidebar badge reads it too, so the
+  two can never disagree. It owns the `sessions.list` subscription, the 30s state tick and the
+  60s `session.list` read RPC (visible-page only).
+- Consumers must tolerate `undefined` (dsh-later not installed/enabled) and degrade silently.
+
 ## Technical documentation
 
 Developer- and maintainer-oriented content has moved out of this README:

package/README.md

@@ -191,6 +191,50 @@ dsh plugin --profile web add "file:/path/to/dsh-later"
 
 ---
 
+## 给插件开发者：定时摘要 API（跨插件）
+
+dsh-later 把「全会话定时任务摘要」作为公共数据面暴露出来
+（[issue #17](http://192.168.4.77:3000/dsh-plugins/dsh-later/issues/17)），其它客户端插件
+（如 dsh-group-status）据此在分组/侧栏聚合显示定时状态，**无需**自己解析
+`userSchedules` 投影，也不会与行内 badge 漂移。
+
+消费方先在 `package.json` 声明外部模块：
+
+```json
+{ "dsh": { "client": { "platform": "web", "external": ["dsh-later"] } } }
+```
+
+然后在客户端 factory 里 `require('dsh-later/client')`：
+
+```js
+const { getScheduleSummaryStore, summarizeScheduleGroup, useScheduleSummary } = require('dsh-later/client')
+
+// 1) 直接读 store：会话 id → { count, pausedCount, nextAt, state }
+const store = getScheduleSummaryStore() // dsh-later 未加载时为 undefined
+const summary = store?.getSnapshot() ?? new Map()
+
+// 2) 按分组聚合（折叠分组徽标直接用它）
+const group = summarizeScheduleGroup(summary, groupSessionIds)
+// → { sessions, count, pausedCount, nextAt?, state? }
+
+// 3) React 组件内订阅（store 迟到也会自动重渲染）
+const live = useScheduleSummary()
+```
+
+| 字段 | 含义 |
+|---|---|
+| `count` | 任务数（**含**暂停项） |
+| `pausedCount` | 暂停项数量（暂停项计入 count，但**不参与** `nextAt`） |
+| `nextAt` | 最早触发时刻（epoch ms）；全部暂停时为 `undefined` |
+| `state` | `scheduled` / `urgent`（≤5 分钟）/ `overdue`（已到期未派发），按快照时刻判定 |
+
+契约要点：
+
+- 摘要**只包含有任务的会话**，无任务的会话不出现；消费方按自己的 `sessionIds` 查表即可。
+- store 是**唯一数据权威**：dsh-later 侧栏 badge 也读它，因此两边必然同源；它内部负责
+  `sessions.list` 订阅、30s 状态 tick 与 60s `session.list` 读 RPC（仅页面可见时）。
+- 消费方必须容忍 `undefined`（dsh-later 未安装/未启用时静默降级）。
+
 ## 技术文档
 
 以下内容面向开发者与维护者，已移出本 README：

package/lib/client.js

@@ -26,8 +26,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   apply: () => apply,
+  buildScheduleSummary: () => buildScheduleSummary,
+  createScheduleSummaryStore: () => createScheduleSummaryStore,
+  getScheduleSummaryStore: () => getScheduleSummaryStore,
   inject: () => inject,
-  name: () => name
+  name: () => name,
+  schedulesOfProjection: () => schedulesOfProjection,
+  subscribeScheduleSummaryStore: () => subscribeScheduleSummaryStore,
+  summarizeScheduleGroup: () => summarizeScheduleGroup,
+  useScheduleSummary: () => useScheduleSummary
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -419,15 +426,22 @@ var COMPONENTS = [
   '.ss-presence[data-state="overdue"] .ss-presence-ring { animation: none; }',
   "",
   "/*  \u65B0\u7248\u63CF\u8FB9\u65F6\u949F\uFF08modern\uFF09\u2014 \u5BF9\u9F50 DSH \u5B98\u65B9 spinner \u6837\u5F0F \u2500\u2500 */",
-  ".ss-presence .ss-clock-face {",
+  "/* \u53CC\u73AF\uFF1Atrack \u6052\u5B9A\u4E3A\u5E95\uFF08\u7ED9\u51FA\u300C\u603B\u7A97\u53E3\u300D\u7684\u89C6\u89C9\u53C2\u7167\uFF09\uFF0Cprog \u662F\u4ECE 12 \u70B9\u8D77\u7684\u8FDB\u5EA6\u5F27\u3002",
+  "   \u65E0\u4ECE\u7B97\u8FDB\u5EA6\u65F6 JS \u628A prog \u7F6E\u4E3A display:none \u2014\u2014 \u6B64\u65F6\u89C6\u89C9\u4E0E\u6539\u9020\u524D\u7684\u5355\u73AF\u5B8C\u5168\u4E00\u81F4\u3002 */",
+  ".ss-presence .ss-clock-track {",
   "  fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round;",
   "  opacity: 0.25; animation: ss-clock-breathe 2.4s var(--ds-ease-in-out, ease-in-out) infinite;",
   "}",
+  ".ss-presence .ss-clock-prog {",
+  "  fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round;",
+  "  opacity: 1; transition: stroke-dashoffset 0.5s var(--ds-ease-in-out, ease-in-out);",
+  "}",
   ".ss-presence .ss-clock-hand { stroke: currentColor; stroke-width: 2; stroke-linecap: round; }",
   ".ss-presence .ss-clock-hand-h { opacity: 1; }",
   ".ss-presence .ss-clock-hand-m { opacity: 0.85; }",
-  '.ss-presence[data-state="urgent"] .ss-clock-face { animation-name: ss-clock-pulse; animation-duration: 0.9s; }',
-  '.ss-presence[data-state="overdue"] .ss-clock-face { animation: none; opacity: 1; }',
+  "/* urgent \u53EA\u8109\u51B2\u5E95\u73AF\uFF1A\u8FDB\u5EA6\u5F27\u627F\u8F7D\u786E\u5B9A\u4FE1\u606F\uFF0C\u8DDF\u7740\u95EA\u4F1A\u8BA9\u6BD4\u4F8B\u4E0D\u53EF\u8BFB\u3002 */",
+  '.ss-presence[data-state="urgent"] .ss-clock-track { animation-name: ss-clock-pulse; animation-duration: 0.9s; }',
+  '.ss-presence[data-state="overdue"] .ss-clock-track { animation: none; opacity: 1; }',
   "",
   "/* \u2500\u2500 \u4E09\u6001\u989C\u8272 \u2500\u2500 */",
   '.ss-presence[data-state="urgent"] { color: var(--dsw-alias-state-warn-secondary); }',
@@ -440,7 +454,9 @@ var COMPONENTS = [
   "@keyframes ss-clock-pulse { 0%, 100% { opacity: 0.5; } 50% { opacity: 1; } }",
   "@media (prefers-reduced-motion: reduce) {",
   "  .ss-presence .ss-presence-ring { animation: none; }",
-  "  .ss-presence .ss-clock-face { animation: none; }",
+  "  .ss-presence .ss-clock-track { animation: none; }",
+  '  /* \u51CF\u5C11\u52A8\u6548\uFF1A\u8FDB\u5EA6\u5F27\u7684\u4F4D\u79FB\u8FC7\u6E21\u4E5F\u4E00\u5E76\u505C\uFF0C\u907F\u514D"\u8FDB\u5EA6\u81EA\u5DF1\u5728\u722C"\u7684\u89C2\u611F\u3002 */',
+  "  .ss-presence .ss-clock-prog { transition: none; }",
   "}",
   "",
   "/* ==================== \u60AC\u6D6E\u5361\u7247\u72B6\u6001\u884C\u589E\u8865\uFF08issue #4\uFF09 ==================== */",
@@ -2594,6 +2610,7 @@ function SchedulerSettingsCard({ scope, t }) {
 var PRESENCE_URGENT_WINDOW_MS = 5 * 6e4;
 function summarizeSchedules(schedules) {
   let nextAt;
+  let progressFrom;
   let count = 0;
   let pausedCount = 0;
   for (const item of schedules ?? []) {
@@ -2606,10 +2623,44 @@ function summarizeSchedules(schedules) {
       pausedCount += 1;
       continue;
     }
-    if (nextAt === void 0 || epoch < nextAt) nextAt = epoch;
+    if (nextAt === void 0 || epoch < nextAt) {
+      nextAt = epoch;
+      progressFrom = windowStartOf(item, epoch);
+    }
   }
   if (count === 0) return { count: 0, pausedCount: 0 };
-  return nextAt === void 0 ? { count, pausedCount } : { count, nextAt, pausedCount };
+  return nextAt === void 0 ? { count, pausedCount } : { count, nextAt, pausedCount, ...progressFrom !== void 0 ? { progressFrom } : {} };
+}
+function windowStartOf(item, scheduledEpoch) {
+  const explicit = toFiniteSeconds(item.window_seconds ?? item.windowSeconds);
+  if (explicit !== void 0) return scheduledEpoch - explicit * 1e3;
+  const afterSec = toFiniteSeconds(item.after_seconds ?? item.afterSeconds);
+  const everySec = toFiniteSeconds(item.every_seconds ?? item.everySeconds);
+  const span = item.kind === "every" ? everySec : afterSec ?? everySec;
+  if (span !== void 0) return scheduledEpoch - span * 1e3;
+  const created = toEpochMs(item.created_at) ?? toEpochMs(item.createdAt);
+  if (created !== null) return created;
+  return void 0;
+}
+function toFiniteSeconds(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function toEpochMs(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string" && value.length > 0) {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function progressOf(entry, now) {
+  const { nextAt, progressFrom } = entry;
+  if (nextAt === void 0 || progressFrom === void 0) return void 0;
+  const span = nextAt - progressFrom;
+  if (!(span > 0)) return void 0;
+  const ratio = (now - progressFrom) / span;
+  if (!Number.isFinite(ratio)) return void 0;
+  return ratio <= 0 ? 0 : ratio >= 1 ? 1 : ratio;
 }
 function badgeStateFor(nextAt, now) {
   if (nextAt === void 0) return "scheduled";
@@ -2659,9 +2710,10 @@ var HOVER_ROW_CLASS = "ss-hover-status";
 var FIBER_MAX_DEPTH = 8;
 var SCAN_DEBOUNCE_MS = 60;
 var STATE_TICK_MS = 3e4;
-var REFRESH_INTERVAL_MS = 6e4;
 var CLOCK_SVG_CLASSIC = '<svg width="10" height="10" viewBox="0 0 10 10" shape-rendering="crispEdges" aria-hidden="true"><g class="ss-presence-ring"><rect x="0" y="0" width="2" height="2"/><rect x="4" y="0" width="2" height="2"/><rect x="8" y="0" width="2" height="2"/><rect x="8" y="4" width="2" height="2"/><rect x="8" y="8" width="2" height="2"/><rect x="4" y="8" width="2" height="2"/><rect x="0" y="8" width="2" height="2"/><rect x="0" y="4" width="2" height="2"/></g><g class="ss-presence-hand"><rect x="4" y="2" width="2" height="2"/><rect x="6" y="4" width="2" height="2"/></g></svg>';
-var CLOCK_SVG_MODERN = '<svg width="14" height="14" viewBox="0 0 24 24" aria-hidden="true"><circle class="ss-clock-face" cx="12" cy="12" r="9.5"/><g class="ss-clock-hand"><line class="ss-clock-hand-h" x1="12" y1="12" x2="12" y2="6.5"/><line class="ss-clock-hand-m" x1="12" y1="12" x2="17" y2="12"/></g></svg>';
+var CLOCK_FACE_R = 9.5;
+var CLOCK_FACE_CIRCUMFERENCE = 2 * Math.PI * CLOCK_FACE_R;
+var CLOCK_SVG_MODERN = `<svg width="14" height="14" viewBox="0 0 24 24" aria-hidden="true"><circle class="ss-clock-track" cx="12" cy="12" r="${CLOCK_FACE_R}"/><circle class="ss-clock-prog" cx="12" cy="12" r="${CLOCK_FACE_R}" stroke-dasharray="${CLOCK_FACE_CIRCUMFERENCE.toFixed(3)}" stroke-dashoffset="${CLOCK_FACE_CIRCUMFERENCE.toFixed(3)}" transform="rotate(-90 12 12)"/><g class="ss-clock-hand"><line class="ss-clock-hand-h" x1="12" y1="12" x2="12" y2="6.5"/><line class="ss-clock-hand-m" x1="12" y1="12" x2="17" y2="12"/></g></svg>`;
 var hhmmFormatter = new Intl.DateTimeFormat(void 0, { hour: "2-digit", minute: "2-digit", hour12: false });
 var dateFormatter = new Intl.DateTimeFormat(void 0, { month: "short", day: "numeric" });
 var formatHhmm2 = (epoch) => hhmmFormatter.format(epoch);
@@ -2684,14 +2736,9 @@ function sessionIdOfNode(element) {
   }
   return void 0;
 }
-function buildIndex(state) {
-  const index = /* @__PURE__ */ new Map();
-  for (const [sessionId, summary] of Object.entries(state.byId)) {
-    const schedules = summary.projectionValues?.["userSchedules"]?.schedules;
-    const entry = summarizeSchedules(schedules);
-    if (entry.count > 0) index.set(sessionId, entry);
-  }
-  return index;
+function currentIndex(summary) {
+  summary.reload();
+  return summary.getSnapshot();
 }
 function findBadge(row) {
   for (const child of Array.from(row.children)) {
@@ -2712,7 +2759,7 @@ function labelsFor(dict) {
   };
 }
 function mountSessionPresence(options) {
-  const { sessions, locale, getClockIconStyle } = options;
+  const { summary, locale, getClockIconStyle } = options;
   if (typeof document === "undefined" || typeof MutationObserver === "undefined") {
     return () => void 0;
   }
@@ -2726,7 +2773,7 @@ function mountSessionPresence(options) {
   const dictForNow = () => dictFor(locale?.getSnapshot().active);
   const scan = () => {
     if (disposed) return;
-    index = buildIndex(sessions.list.getSnapshot());
+    index = currentIndex(summary);
     const dict = dictForNow();
     const now = Date.now();
     for (const row of Array.from(document.querySelectorAll('[role="treeitem"][draggable="true"]'))) {
@@ -2756,10 +2803,12 @@ function mountSessionPresence(options) {
     const allPaused = entry.nextAt === void 0 && entry.pausedCount > 0;
     const aria = allPaused ? format(dict.presencePausedAria, { n: entry.count }) : state === "overdue" ? format(dict.presenceOverdueAria, { n: entry.count }) : format(dict.presenceBadgeAria, { n: entry.count, time });
     const tooltip = allPaused ? format(dict.presencePausedTooltip, { n: entry.count }) : state === "overdue" ? format(dict.presenceOverdueTooltip, { n: entry.count }) : format(dict.presenceTooltip, { n: entry.count, time });
+    const progress = progressOf(entry, now);
     if (existing !== null) {
       if (existing.dataset.state !== state) existing.dataset.state = state;
       if (existing.getAttribute("aria-label") !== aria) existing.setAttribute("aria-label", aria);
       if (existing.getAttribute("title") !== tooltip) existing.setAttribute("title", tooltip);
+      applyProgress(existing, progress);
       return;
     }
     const slot = row.firstElementChild;
@@ -2772,9 +2821,20 @@ function mountSessionPresence(options) {
     badge.setAttribute("aria-label", aria);
     badge.setAttribute("title", tooltip);
     badge.innerHTML = getClockSvg();
+    applyProgress(badge, progress);
     if (beside) slot.after(badge);
     else slot.append(badge);
   }
+  function applyProgress(badge, ratio) {
+    const arc = badge.querySelector(".ss-clock-prog");
+    if (arc === null) return;
+    if (ratio === void 0) {
+      arc.style.display = "none";
+      return;
+    }
+    if (arc.style.display === "none") arc.style.display = "";
+    arc.style.strokeDashoffset = String(CLOCK_FACE_CIRCUMFERENCE * (1 - ratio));
+  }
   function findHoverCard() {
     for (const card of Array.from(document.body.children)) {
       if (!(card instanceof HTMLElement)) continue;
@@ -2820,46 +2880,201 @@ function mountSessionPresence(options) {
     row.append(dot, text);
     statusHost.append(row);
   }
-  const unsubscribeList = sessions.list.subscribe(scheduleScan);
+  const unsubscribeSummary = summary.subscribe(scheduleScan);
   const unsubscribeLocale = locale?.subscribe(scheduleScan);
   const observer = new MutationObserver(scheduleScan);
   observer.observe(document.body, { childList: true, subtree: true });
-  const refreshNow = () => {
-    if (disposed) return;
-    try {
-      void sessions.refresh().catch(() => void 0);
-    } catch {
-    }
-  };
-  const onVisible = () => {
-    if (document.visibilityState === "visible") {
-      refreshNow();
-      scheduleScan();
-    }
-  };
-  document.addEventListener("visibilitychange", onVisible);
-  window.addEventListener("online", onVisible);
   const stateTick = setInterval(scheduleScan, STATE_TICK_MS);
-  const refreshTick = setInterval(() => {
-    if (document.visibilityState === "visible") refreshNow();
-  }, REFRESH_INTERVAL_MS);
-  refreshNow();
   scheduleScan();
   return () => {
     disposed = true;
     if (scanTimer !== void 0) clearTimeout(scanTimer);
     clearInterval(stateTick);
-    clearInterval(refreshTick);
     observer.disconnect();
-    unsubscribeList();
+    unsubscribeSummary();
     unsubscribeLocale?.();
-    document.removeEventListener("visibilitychange", onVisible);
-    window.removeEventListener("online", onVisible);
     for (const badge of Array.from(document.querySelectorAll(`.${BADGE_CLASS}`))) badge.remove();
     for (const row of Array.from(document.querySelectorAll(`.${HOVER_ROW_CLASS}`))) row.remove();
   };
 }
 
+// src/schedule-summary.ts
+var SCHEDULE_PROJECTION_KEY = "userSchedules";
+function schedulesOfProjection(projectionValues) {
+  const value = projectionValues?.[SCHEDULE_PROJECTION_KEY];
+  if (typeof value !== "object" || value === null) return void 0;
+  const schedules = value.schedules;
+  return Array.isArray(schedules) ? schedules : void 0;
+}
+function buildScheduleSummary(source, now) {
+  const summary = /* @__PURE__ */ new Map();
+  for (const [sessionId, row] of Object.entries(source.byId)) {
+    if (row === void 0) continue;
+    const entry = summarizeSchedules(schedulesOfProjection(row.projectionValues));
+    if (entry.count === 0) continue;
+    summary.set(sessionId, { ...entry, state: badgeStateFor(entry.nextAt, now) });
+  }
+  return summary;
+}
+function sameScheduleSummary(a, b) {
+  if (a === b) return true;
+  if (a.size !== b.size) return false;
+  for (const [sessionId, left] of a) {
+    const right = b.get(sessionId);
+    if (right === void 0) return false;
+    if (left.count !== right.count || left.pausedCount !== right.pausedCount || left.nextAt !== right.nextAt || left.progressFrom !== right.progressFrom || left.state !== right.state) {
+      return false;
+    }
+  }
+  return true;
+}
+var STATE_RANK = { scheduled: 0, urgent: 1, overdue: 2 };
+function summarizeScheduleGroup(summary, sessionIds) {
+  let sessions = 0;
+  let count = 0;
+  let pausedCount = 0;
+  let nextAt;
+  let state;
+  for (const sessionId of sessionIds) {
+    const entry = summary.get(sessionId);
+    if (entry === void 0) continue;
+    sessions += 1;
+    count += entry.count;
+    pausedCount += entry.pausedCount;
+    if (entry.nextAt !== void 0 && (nextAt === void 0 || entry.nextAt < nextAt)) nextAt = entry.nextAt;
+    if (state === void 0 || STATE_RANK[entry.state] > STATE_RANK[state]) state = entry.state;
+  }
+  return nextAt === void 0 ? { sessions, count, pausedCount, state } : { sessions, count, pausedCount, nextAt, state };
+}
+
+// src/schedule-summary-store.ts
+var SUMMARY_STATE_TICK_MS = 3e4;
+var SUMMARY_REFRESH_INTERVAL_MS = 6e4;
+function documentOf() {
+  const doc = globalThis.document;
+  return typeof doc === "object" && doc !== null ? doc : void 0;
+}
+function createScheduleSummaryStore(sessions, options = {}) {
+  const now = options.now ?? Date.now;
+  const stateTickMs = options.stateTickMs ?? SUMMARY_STATE_TICK_MS;
+  const refreshIntervalMs = options.refreshIntervalMs ?? SUMMARY_REFRESH_INTERVAL_MS;
+  const autoRefresh = options.autoRefresh ?? true;
+  const canRefresh = options.canRefresh ?? (() => {
+    const doc2 = documentOf();
+    return doc2?.visibilityState === void 0 || doc2.visibilityState === "visible";
+  });
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const notify = () => {
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  };
+  const reload = () => {
+    if (disposed) return;
+    const next = buildScheduleSummary(sessions.list.getSnapshot(), now());
+    if (sameScheduleSummary(snapshot, next)) return;
+    snapshot = next;
+    notify();
+  };
+  const unsubscribeList = sessions.list.subscribe(reload);
+  const stateTick = setInterval(reload, stateTickMs);
+  let refreshTick;
+  let onVisible;
+  const doc = documentOf();
+  const target = globalThis;
+  const refreshNow = () => {
+    if (disposed || !canRefresh()) return;
+    try {
+      void sessions.refresh().catch(() => void 0);
+    } catch {
+    }
+  };
+  if (autoRefresh) {
+    onVisible = () => {
+      if (!disposed && canRefresh()) {
+        refreshNow();
+        reload();
+      }
+    };
+    refreshTick = setInterval(() => {
+      if (canRefresh()) refreshNow();
+    }, refreshIntervalMs);
+    doc?.addEventListener?.("visibilitychange", onVisible);
+    target.addEventListener?.("online", onVisible);
+    refreshNow();
+  }
+  reload();
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    clearInterval(stateTick);
+    if (refreshTick !== void 0) clearInterval(refreshTick);
+    if (onVisible !== void 0) {
+      doc?.removeEventListener?.("visibilitychange", onVisible);
+      target.removeEventListener?.("online", onVisible);
+    }
+    unsubscribeList();
+    listeners.clear();
+  };
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    reload,
+    dispose
+  };
+}
+var activeStore;
+var registryListeners = /* @__PURE__ */ new Set();
+function setActiveScheduleSummaryStore(store) {
+  if (activeStore === store) return;
+  activeStore = store;
+  for (const listener of [...registryListeners]) {
+    try {
+      listener();
+    } catch {
+    }
+  }
+}
+function getScheduleSummaryStore() {
+  return activeStore;
+}
+function subscribeScheduleSummaryStore(listener) {
+  registryListeners.add(listener);
+  return () => {
+    registryListeners.delete(listener);
+  };
+}
+
+// src/client/useScheduleSummary.ts
+var import_react9 = require("react");
+var EMPTY_SUMMARY = /* @__PURE__ */ new Map();
+var noopSubscribe2 = () => () => void 0;
+var emptySnapshot = () => EMPTY_SUMMARY;
+var missingSnapshot = () => void 0;
+function useScheduleSummary(store) {
+  const registered = (0, import_react9.useSyncExternalStore)(subscribeScheduleSummaryStore, getScheduleSummaryStore, missingSnapshot);
+  const target = store ?? registered;
+  const subscribe = (0, import_react9.useMemo)(
+    () => target === void 0 ? noopSubscribe2 : (listener) => target.subscribe(listener),
+    [target]
+  );
+  const getSnapshot = (0, import_react9.useMemo)(
+    () => target === void 0 ? emptySnapshot : () => target.getSnapshot(),
+    [target]
+  );
+  return (0, import_react9.useSyncExternalStore)(subscribe, getSnapshot, emptySnapshot);
+}
+
 // src/client/index.tsx
 var INPUT_RIGHT_SLOT = "conversation.input.right";
 var inject = ["slots", "sessions", "conversation", "locale"];
@@ -2874,9 +3089,18 @@ function apply(ctx) {
   ctx.effect(() => injectStyles(), "dsh-later: styles");
   let detectedVersion = "classic";
   let getClockIconStyle = () => "auto";
+  const summary = createScheduleSummaryStore(sessions);
+  setActiveScheduleSummaryStore(summary);
+  ctx.effect(
+    () => () => {
+      if (getScheduleSummaryStore() === summary) setActiveScheduleSummaryStore(void 0);
+      summary.dispose();
+    },
+    "dsh-later: schedule summary"
+  );
   ctx.effect(
     () => mountSessionPresence({
-      sessions,
+      summary,
       ...locale === void 0 ? {} : { locale },
       getClockIconStyle: () => {
         const style = getClockIconStyle();

package/lib/presence.js

@@ -30,6 +30,7 @@ export const PRESENCE_URGENT_WINDOW_MS = 5 * 60_000;
  */
 export function summarizeSchedules(schedules) {
     let nextAt;
+    let progressFrom;
     let count = 0;
     let pausedCount = 0;
     for (const item of schedules ?? []) {
@@ -44,12 +45,81 @@ export function summarizeSchedules(schedules) {
             pausedCount += 1;
             continue; // 冻结项没有排定的触发时刻，不参与 nextAt
         }
-        if (nextAt === undefined || epoch < nextAt)
+        if (nextAt === undefined || epoch < nextAt) {
             nextAt = epoch;
+            // 窗口起点只跟随被选中的那一条；并列最早时保留先出现者的窗口。
+            progressFrom = windowStartOf(item, epoch);
+        }
     }
     if (count === 0)
         return { count: 0, pausedCount: 0 };
-    return nextAt === undefined ? { count, pausedCount } : { count, nextAt, pausedCount };
+    // 字段用条件展开：无进度时不产生 `progressFrom: undefined`，保持既有
+    // deepEqual 测试与 wire 形状不变。
+    return nextAt === undefined
+        ? { count, pausedCount }
+        : { count, nextAt, pausedCount, ...(progressFrom !== undefined ? { progressFrom } : {}) };
+}
+/**
+ * 推导进度窗口的起点时刻（epoch ms）；无从推导时返回 `undefined`。
+ *
+ * 口径按优先级：
+ *  1. `window_seconds` —— 宿主/投影直接给的总窗口，最权威（暂停项的 wire 正是
+ *     用它携带"原 after 间隔"，见 projection.ts 的 `pausedWireItemOf`）。
+ *  2. 按 `kind` 推：`after` 用 `after_seconds`，`every` 用 `every_seconds`。
+ *     两者都是"从触发时刻往回推一整个窗口"，天然得到本周期起点。
+ *  3. `created_at` —— `at` 类型没有周期，只能拿任务创建时刻当起点。
+ *
+ * **推不出就返回 `undefined`**，绝不拿 `scheduledAt` 兜底：那会让 span 为 0，
+ * 进度恒为 100%，把"算不出来"伪装成"已经走完"。
+ */
+function windowStartOf(item, scheduledEpoch) {
+    const explicit = toFiniteSeconds(item.window_seconds ?? item.windowSeconds);
+    if (explicit !== undefined)
+        return scheduledEpoch - explicit * 1000;
+    const afterSec = toFiniteSeconds(item.after_seconds ?? item.afterSeconds);
+    const everySec = toFiniteSeconds(item.every_seconds ?? item.everySeconds);
+    const span = item.kind === 'every' ? everySec : (afterSec ?? everySec);
+    if (span !== undefined)
+        return scheduledEpoch - span * 1000;
+    const created = toEpochMs(item.created_at) ?? toEpochMs(item.createdAt);
+    if (created !== null)
+        return created;
+    return undefined;
+}
+/** 秒数归一：只接受有限正数（0 / 负数 / NaN 一律视为"没给"）。 */
+function toFiniteSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** epoch ms（number）或 ISO 字符串统一成 epoch ms；无法解析返回 `null`。 */
+function toEpochMs(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * 进度环比例（0–1）：`now` 在 `[progressFrom, nextAt]` 中的位置。
+ *
+ * 返回 `undefined` 表示**无从算起**（缺窗口起点，或窗口已退化），调用方此时应
+ * 退回「恒定整环」的旧表现，而不是画一个 0% 的空环 —— 后者是错误信息：
+ * 0% 是"刚开始"，`undefined` 是"算不出来"。
+ *
+ * 两端夹住：`overdue` 时 `now > nextAt`，环停在满环而不是绕出去。
+ */
+export function progressOf(entry, now) {
+    const { nextAt, progressFrom } = entry;
+    if (nextAt === undefined || progressFrom === undefined)
+        return undefined;
+    const span = nextAt - progressFrom;
+    if (!(span > 0))
+        return undefined;
+    const ratio = (now - progressFrom) / span;
+    if (!Number.isFinite(ratio))
+        return undefined;
+    return ratio <= 0 ? 0 : ratio >= 1 ? 1 : ratio;
 }
 /** 由当前时刻判定 badge 状态。 */
 export function badgeStateFor(nextAt, now) {

package/lib/schedule-summary-store.js

@@ -0,0 +1,160 @@
+/**
+ * 定时摘要 store：把 {@link buildScheduleSummary} 的纯计算接到宿主 `sessions`
+ * 服务上，得到一个**可订阅的公共数据源**。
+ *
+ * 为什么需要它（issue #17）：dsh-later 自己的侧栏 badge 与外部插件（如
+ * dsh-group-status）都需要「全会话定时任务摘要」。两条独立通路会各自订阅
+ * `sessions.list`、各自周期 `refresh()`，既浪费 RPC 又容易漂移。本 store 是
+ * **唯一**的数据权威：内部负责列表订阅、状态 tick（scheduled→urgent→overdue）
+ * 与 `session.list` 读 RPC 补时效；外部只读 {@link ScheduleSummaryStore.getSnapshot}
+ * 或订阅变更。
+ *
+ * 跨插件使用方式（消费方声明 `dsh.client.external: ["dsh-later"]` 后）：
+ * ```js
+ * const later = require('dsh-later/client')
+ * const store = later.getScheduleSummaryStore()
+ * ```
+ *
+ * 本模块零 DOM / 零 React 依赖（`document` / `window` 一律经 `globalThis`
+ * 结构化探测），宿主 tsc 与浏览器 esbuild 都能编译，`node --test` 也能直接跑。
+ * @module dsh-later/schedule-summary-store
+ */
+import { buildScheduleSummary, sameScheduleSummary } from './schedule-summary.js';
+/** 摘要状态重算周期（本地时钟，零网络）。 */
+export const SUMMARY_STATE_TICK_MS = 30_000;
+/** `session.list` 重拉周期（读 RPC；仅页面可见时执行）。 */
+export const SUMMARY_REFRESH_INTERVAL_MS = 60_000;
+/** 取 `globalThis.document`（不引 DOM 类型，宿主编译期无 document 也能通过）。 */
+function documentOf() {
+    const doc = globalThis.document;
+    return typeof doc === 'object' && doc !== null ? doc : undefined;
+}
+/**
+ * 创建定时摘要 store（宿主 `apply` 内创建一次，全插件共享）。
+ * @param sessions - 宿主 `sessions` 服务。
+ * @param options - 周期/时钟/刷新策略覆盖（单测用）。
+ * @returns 可订阅 store。
+ */
+export function createScheduleSummaryStore(sessions, options = {}) {
+    const now = options.now ?? Date.now;
+    const stateTickMs = options.stateTickMs ?? SUMMARY_STATE_TICK_MS;
+    const refreshIntervalMs = options.refreshIntervalMs ?? SUMMARY_REFRESH_INTERVAL_MS;
+    const autoRefresh = options.autoRefresh ?? true;
+    const canRefresh = options.canRefresh ??
+        (() => {
+            const doc = documentOf();
+            return doc?.visibilityState === undefined || doc.visibilityState === 'visible';
+        });
+    const listeners = new Set();
+    let snapshot = new Map();
+    let disposed = false;
+    const notify = () => {
+        // 快照一份再遍历：订阅者可能在回调里退订。
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                /* 单个订阅者异常不影响其余订阅者与主流程 */
+            }
+        }
+    };
+    const reload = () => {
+        if (disposed)
+            return;
+        const next = buildScheduleSummary(sessions.list.getSnapshot(), now());
+        if (sameScheduleSummary(snapshot, next))
+            return;
+        snapshot = next;
+        notify();
+    };
+    const unsubscribeList = sessions.list.subscribe(reload);
+    const stateTick = setInterval(reload, stateTickMs);
+    let refreshTick;
+    let onVisible;
+    const doc = documentOf();
+    const target = globalThis;
+    const refreshNow = () => {
+        if (disposed || !canRefresh())
+            return;
+        try {
+            void sessions.refresh().catch(() => undefined);
+        }
+        catch {
+            /* 刷新失败不影响既有摘要 */
+        }
+    };
+    if (autoRefresh) {
+        onVisible = () => {
+            if (!disposed && canRefresh()) {
+                refreshNow();
+                reload();
+            }
+        };
+        refreshTick = setInterval(() => {
+            if (canRefresh())
+                refreshNow();
+        }, refreshIntervalMs);
+        doc?.addEventListener?.('visibilitychange', onVisible);
+        target.addEventListener?.('online', onVisible);
+        refreshNow();
+    }
+    reload();
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearInterval(stateTick);
+        if (refreshTick !== undefined)
+            clearInterval(refreshTick);
+        if (onVisible !== undefined) {
+            doc?.removeEventListener?.('visibilitychange', onVisible);
+            target.removeEventListener?.('online', onVisible);
+        }
+        unsubscribeList();
+        listeners.clear();
+    };
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        reload,
+        dispose,
+    };
+}
+/** 当前生效的 store（client 插件 `apply` 挂载时登记；跨插件只读入口）。 */
+let activeStore;
+/** store 登记变化的订阅者（消费方可能在 store 就绪前先渲染）。 */
+const registryListeners = new Set();
+/**
+ * 登记/撤销当前 store（由 dsh-later 自身 `apply` 调用；外部插件不要调用）。
+ * @param store - 生效的 store；undefined 表示撤销。
+ */
+export function setActiveScheduleSummaryStore(store) {
+    if (activeStore === store)
+        return;
+    activeStore = store;
+    for (const listener of [...registryListeners]) {
+        try {
+            listener();
+        }
+        catch {
+            /* 忽略单个订阅者异常 */
+        }
+    }
+}
+/** 读取当前生效的 store；dsh-later 未加载时为 undefined。 */
+export function getScheduleSummaryStore() {
+    return activeStore;
+}
+/** 订阅 store 登记变化（供 React hook 在 store 迟到时仍能重渲染）。 */
+export function subscribeScheduleSummaryStore(listener) {
+    registryListeners.add(listener);
+    return () => {
+        registryListeners.delete(listener);
+    };
+}

package/lib/schedule-summary.js

@@ -0,0 +1,113 @@
+/**
+ * 定时任务摘要：dsh-later 对外暴露的**公共数据面**（跨会话 / 跨插件）。
+ *
+ * 关键事实（本插件「路线 B」的数据源）：`userSchedules` 是 client-visible 投影，
+ * 宿主在 `session.list` 基线里为**每个**会话携带 projections 块（live 会话走注册
+ * 表现值、冷会话走持久化投影缓存），客户端把它合入
+ * `SessionSummary.projectionValues`。因此**任何**持有 `sessions` 服务的客户端插件
+ * 都能读到全会话的定时任务，本模块只负责把它折叠成稳定形状。
+ *
+ * 契约形状（issue #17）：`Map<SessionId, { count, nextAt, state }>`——即
+ * {@link ScheduleSummaryMap}。dsh-later 通过 `dsh-later/client` 导出
+ * {@link buildScheduleSummary}（纯函数）、`createScheduleSummaryStore`（可订阅
+ * store）与 `useScheduleSummary`（React hook），消费方按需选用。
+ *
+ * 本模块零 DOM / 零 React 依赖：宿主、浏览器与 `node --test` 都能直接跑。
+ * @module dsh-later/schedule-summary
+ */
+import { badgeStateFor, summarizeSchedules, } from './presence.js';
+/** `userSchedules` 投影值在 `projectionValues` 里的键名。 */
+export const SCHEDULE_PROJECTION_KEY = 'userSchedules';
+/**
+ * 从 `projectionValues` 里取出任务数组（容错：形状不对一律当作无任务）。
+ * @param projectionValues - 会话行的投影现值集合。
+ * @returns 任务数组；缺失或形状非法时 undefined。
+ */
+export function schedulesOfProjection(projectionValues) {
+    const value = projectionValues?.[SCHEDULE_PROJECTION_KEY];
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const schedules = value.schedules;
+    return Array.isArray(schedules) ? schedules : undefined;
+}
+/**
+ * 全会话归纳：把会话列表快照折叠成 {@link ScheduleSummaryMap}。
+ * @param source - 会话列表快照（`sessions.list.getSnapshot()`）。
+ * @param now - 判定 `state` 的当前时刻（epoch ms）。
+ * @returns 会话 id → 摘要；无任务的会话不出现在 map 里。
+ */
+export function buildScheduleSummary(source, now) {
+    const summary = new Map();
+    for (const [sessionId, row] of Object.entries(source.byId)) {
+        if (row === undefined)
+            continue;
+        const entry = summarizeSchedules(schedulesOfProjection(row.projectionValues));
+        if (entry.count === 0)
+            continue;
+        summary.set(sessionId, { ...entry, state: badgeStateFor(entry.nextAt, now) });
+    }
+    return summary;
+}
+/**
+ * 两份摘要是否等价（逐条比对五个字段）。store 用它决定是否需要通知订阅者，
+ * 避免每次重算都产生新的 Map 引用导致 React 无谓重渲染。
+ *
+ * `progressFrom` 一并比对：它虽然通常随 `nextAt` 同进同退，但暂停→恢复会让
+ * 同一条任务重新拥有窗口起点，此时 `nextAt` 可能未变而窗口已换 —— 漏比会
+ * 让进度环停在上一个窗口的比例上。
+ * @param a - 旧摘要。
+ * @param b - 新摘要。
+ * @returns 键集合与每条内容都相同时为 true。
+ */
+export function sameScheduleSummary(a, b) {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [sessionId, left] of a) {
+        const right = b.get(sessionId);
+        if (right === undefined)
+            return false;
+        if (left.count !== right.count ||
+            left.pausedCount !== right.pausedCount ||
+            left.nextAt !== right.nextAt ||
+            left.progressFrom !== right.progressFrom ||
+            left.state !== right.state) {
+            return false;
+        }
+    }
+    return true;
+}
+/** 状态优先级（越大越紧急）。 */
+const STATE_RANK = { scheduled: 0, urgent: 1, overdue: 2 };
+/**
+ * 按**分组**聚合摘要：给定组内会话 id，折叠出可直接渲染的分组事实。
+ *
+ * 消费方（如 dsh-group-status 的 `GroupLiveStatus`）只需把组内会话 id 传进来，
+ * 无需理解 `nextAt`/暂停语义。
+ * @param summary - {@link ScheduleSummaryMap}。
+ * @param sessionIds - 组内会话 id（顺序无关；不在摘要里的会被忽略）。
+ * @returns 分组级摘要；组内无任务时 `sessions`/`count` 为 0、`state` 缺省。
+ */
+export function summarizeScheduleGroup(summary, sessionIds) {
+    let sessions = 0;
+    let count = 0;
+    let pausedCount = 0;
+    let nextAt;
+    let state;
+    for (const sessionId of sessionIds) {
+        const entry = summary.get(sessionId);
+        if (entry === undefined)
+            continue;
+        sessions += 1;
+        count += entry.count;
+        pausedCount += entry.pausedCount;
+        if (entry.nextAt !== undefined && (nextAt === undefined || entry.nextAt < nextAt))
+            nextAt = entry.nextAt;
+        if (state === undefined || STATE_RANK[entry.state] > STATE_RANK[state])
+            state = entry.state;
+    }
+    return nextAt === undefined
+        ? { sessions, count, pausedCount, state }
+        : { sessions, count, pausedCount, nextAt, state };
+}

package/lib/types/presence.d.ts

@@ -23,6 +23,20 @@ export interface PresenceScheduleLike {
     readonly status?: string;
     /** 暂停冻结的剩余秒数；仅在 `status === 'paused'` 时有意义。 */
     readonly remaining_seconds?: number;
+    /** 任务类型。决定进度窗口起点按哪个口径推导（见 {@link windowStartOf}）。 */
+    readonly kind?: string;
+    /** `after` 类型的总倒计时秒数（进度起点 = 触发时刻 − 该值）。 */
+    readonly after_seconds?: number;
+    readonly afterSeconds?: number;
+    /** `every` 类型的周期间隔秒数（进度起点 = 触发时刻 − 该值，即本周期起点）。 */
+    readonly every_seconds?: number;
+    readonly everySeconds?: number;
+    /** 宿主/投影直接给的显式总窗口秒数；给了就优先于按 kind 推导。 */
+    readonly window_seconds?: number;
+    readonly windowSeconds?: number;
+    /** `at` 类型的进度起点（任务创建时刻，ISO）。`at` 没有天然周期，只能用它。 */
+    readonly created_at?: string;
+    readonly createdAt?: number;
 }
 /** 由一组活动任务归纳的 badge 概要。 */
 export interface PresenceSummary {
@@ -32,6 +46,14 @@ export interface PresenceSummary {
     readonly nextAt?: number;
     /** 暂停中的任务数（用于文案区分「已冻结」与「等待发送」）。 */
     readonly pausedCount: number;
+    /**
+     * 进度环起点（epoch ms）：`nextAt` 那条任务的窗口开始时刻。
+     *
+     * **只跟随 `nextAt` 那条**：环表达的是"距离最近一次触发还剩多少"，若取别条
+     * 任务的窗口就与 `nextAt` 对不上了。无从推导时缺省，此时调用方应退回恒定
+     * 整环（{@link progressOf} 返回 `undefined`）。
+     */
+    readonly progressFrom?: number;
 }
 /**
  * 归纳：取最早触发时刻 + 任务数量。
@@ -49,6 +71,16 @@ export interface PresenceSummary {
  * 「已到期」或"下次 X 分后"。
  */
 export declare function summarizeSchedules(schedules: readonly PresenceScheduleLike[] | undefined): PresenceSummary;
+/**
+ * 进度环比例（0–1）：`now` 在 `[progressFrom, nextAt]` 中的位置。
+ *
+ * 返回 `undefined` 表示**无从算起**（缺窗口起点，或窗口已退化），调用方此时应
+ * 退回「恒定整环」的旧表现，而不是画一个 0% 的空环 —— 后者是错误信息：
+ * 0% 是"刚开始"，`undefined` 是"算不出来"。
+ *
+ * 两端夹住：`overdue` 时 `now > nextAt`，环停在满环而不是绕出去。
+ */
+export declare function progressOf(entry: PresenceSummary, now: number): number | undefined;
 /** 由当前时刻判定 badge 状态。 */
 export declare function badgeStateFor(nextAt: number | undefined, now: number): PresenceBadgeState;
 /**

package/lib/types/schedule-summary-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 定时摘要 store：把 {@link buildScheduleSummary} 的纯计算接到宿主 `sessions`
+ * 服务上，得到一个**可订阅的公共数据源**。
+ *
+ * 为什么需要它（issue #17）：dsh-later 自己的侧栏 badge 与外部插件（如
+ * dsh-group-status）都需要「全会话定时任务摘要」。两条独立通路会各自订阅
+ * `sessions.list`、各自周期 `refresh()`，既浪费 RPC 又容易漂移。本 store 是
+ * **唯一**的数据权威：内部负责列表订阅、状态 tick（scheduled→urgent→overdue）
+ * 与 `session.list` 读 RPC 补时效；外部只读 {@link ScheduleSummaryStore.getSnapshot}
+ * 或订阅变更。
+ *
+ * 跨插件使用方式（消费方声明 `dsh.client.external: ["dsh-later"]` 后）：
+ * ```js
+ * const later = require('dsh-later/client')
+ * const store = later.getScheduleSummaryStore()
+ * ```
+ *
+ * 本模块零 DOM / 零 React 依赖（`document` / `window` 一律经 `globalThis`
+ * 结构化探测），宿主 tsc 与浏览器 esbuild 都能编译，`node --test` 也能直接跑。
+ * @module dsh-later/schedule-summary-store
+ */
+import { type ScheduleSummaryMap, type ScheduleSummarySource } from './schedule-summary.js';
+/** 摘要状态重算周期（本地时钟，零网络）。 */
+export declare const SUMMARY_STATE_TICK_MS = 30000;
+/** `session.list` 重拉周期（读 RPC；仅页面可见时执行）。 */
+export declare const SUMMARY_REFRESH_INTERVAL_MS = 60000;
+/** 宿主 `sessions` 服务的结构子集（只用到列表快照与 refresh）。 */
+export interface ScheduleSummarySessionsLike {
+    /** 会话列表 store（快照 + 变更订阅）。 */
+    readonly list: {
+        getSnapshot(): ScheduleSummarySource;
+        subscribe(listener: () => void): () => void;
+    };
+    /** 重拉会话列表（读 RPC，不写会话日志）。 */
+    refresh(): Promise<unknown>;
+}
+/** 可订阅的定时摘要 store。 */
+export interface ScheduleSummaryStore {
+    /** 当前摘要（引用稳定；内容变化时才换成新对象）。 */
+    getSnapshot(): ScheduleSummaryMap;
+    /** 订阅变更；返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /** 立即按最新会话列表快照重算（内容有变化才通知）。 */
+    reload(): void;
+    /** 释放订阅/定时器（宿主卸载时调用）。 */
+    dispose(): void;
+}
+export interface ScheduleSummaryStoreOptions {
+    /** 状态重算周期（毫秒）；缺省 {@link SUMMARY_STATE_TICK_MS}。 */
+    readonly stateTickMs?: number;
+    /** 会话列表重拉周期（毫秒）；缺省 {@link SUMMARY_REFRESH_INTERVAL_MS}。 */
+    readonly refreshIntervalMs?: number;
+    /** 当前时刻注入（单测用）；缺省 `Date.now`。 */
+    readonly now?: () => number;
+    /** 是否允许发起 refresh RPC；缺省「页面可见时允许」。 */
+    readonly canRefresh?: () => boolean;
+    /** 是否自动周期 refresh；缺省 true（单测可关）。 */
+    readonly autoRefresh?: boolean;
+}
+/**
+ * 创建定时摘要 store（宿主 `apply` 内创建一次，全插件共享）。
+ * @param sessions - 宿主 `sessions` 服务。
+ * @param options - 周期/时钟/刷新策略覆盖（单测用）。
+ * @returns 可订阅 store。
+ */
+export declare function createScheduleSummaryStore(sessions: ScheduleSummarySessionsLike, options?: ScheduleSummaryStoreOptions): ScheduleSummaryStore;
+/**
+ * 登记/撤销当前 store（由 dsh-later 自身 `apply` 调用；外部插件不要调用）。
+ * @param store - 生效的 store；undefined 表示撤销。
+ */
+export declare function setActiveScheduleSummaryStore(store: ScheduleSummaryStore | undefined): void;
+/** 读取当前生效的 store；dsh-later 未加载时为 undefined。 */
+export declare function getScheduleSummaryStore(): ScheduleSummaryStore | undefined;
+/** 订阅 store 登记变化（供 React hook 在 store 迟到时仍能重渲染）。 */
+export declare function subscribeScheduleSummaryStore(listener: () => void): () => void;

package/lib/types/schedule-summary.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 定时任务摘要：dsh-later 对外暴露的**公共数据面**（跨会话 / 跨插件）。
+ *
+ * 关键事实（本插件「路线 B」的数据源）：`userSchedules` 是 client-visible 投影，
+ * 宿主在 `session.list` 基线里为**每个**会话携带 projections 块（live 会话走注册
+ * 表现值、冷会话走持久化投影缓存），客户端把它合入
+ * `SessionSummary.projectionValues`。因此**任何**持有 `sessions` 服务的客户端插件
+ * 都能读到全会话的定时任务，本模块只负责把它折叠成稳定形状。
+ *
+ * 契约形状（issue #17）：`Map<SessionId, { count, nextAt, state }>`——即
+ * {@link ScheduleSummaryMap}。dsh-later 通过 `dsh-later/client` 导出
+ * {@link buildScheduleSummary}（纯函数）、`createScheduleSummaryStore`（可订阅
+ * store）与 `useScheduleSummary`（React hook），消费方按需选用。
+ *
+ * 本模块零 DOM / 零 React 依赖：宿主、浏览器与 `node --test` 都能直接跑。
+ * @module dsh-later/schedule-summary
+ */
+import { type PresenceBadgeState, type PresenceScheduleLike, type PresenceSummary } from './presence.js';
+/** `userSchedules` 投影值在 `projectionValues` 里的键名。 */
+export declare const SCHEDULE_PROJECTION_KEY = "userSchedules";
+/**
+ * 一条会话的定时摘要：数量 + 下次触发 + 视觉状态。
+ *
+ * `state` 是**快照时刻**由 {@link badgeStateFor} 判定的结果（`scheduled` /
+ * `urgent` ≤5min / `overdue` 已到期未派发），因此 store 每次重算/定时 tick 都会
+ * 刷新它；暂停项计入 `count`/`pausedCount`，但**不参与** `nextAt`（见 presence 模块
+ * 对暂停语义的说明）。
+ */
+export interface ScheduleSummaryEntry extends PresenceSummary {
+    /** 该会话的 badge 状态（按快照时刻判定）。 */
+    readonly state: PresenceBadgeState;
+}
+/** 会话 id → 该会话的定时摘要（**仅**包含有任务的会话）。 */
+export type ScheduleSummaryMap = ReadonlyMap<string, ScheduleSummaryEntry>;
+/** 摘要所需的最小会话列表快照面（`SessionListState` 的结构子集）。 */
+export interface ScheduleSummarySource {
+    /** 会话 id → 会话行事实（只用到 `projectionValues`）。 */
+    readonly byId: Readonly<Record<string, ScheduleSummaryRowLike | undefined>>;
+}
+/** 会话行事实的结构子集。 */
+export interface ScheduleSummaryRowLike {
+    /** 该会话的投影现值（含 `userSchedules`）。 */
+    readonly projectionValues?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 从 `projectionValues` 里取出任务数组（容错：形状不对一律当作无任务）。
+ * @param projectionValues - 会话行的投影现值集合。
+ * @returns 任务数组；缺失或形状非法时 undefined。
+ */
+export declare function schedulesOfProjection(projectionValues: Readonly<Record<string, unknown>> | undefined): readonly PresenceScheduleLike[] | undefined;
+/**
+ * 全会话归纳：把会话列表快照折叠成 {@link ScheduleSummaryMap}。
+ * @param source - 会话列表快照（`sessions.list.getSnapshot()`）。
+ * @param now - 判定 `state` 的当前时刻（epoch ms）。
+ * @returns 会话 id → 摘要；无任务的会话不出现在 map 里。
+ */
+export declare function buildScheduleSummary(source: ScheduleSummarySource, now: number): ScheduleSummaryMap;
+/**
+ * 两份摘要是否等价（逐条比对五个字段）。store 用它决定是否需要通知订阅者，
+ * 避免每次重算都产生新的 Map 引用导致 React 无谓重渲染。
+ *
+ * `progressFrom` 一并比对：它虽然通常随 `nextAt` 同进同退，但暂停→恢复会让
+ * 同一条任务重新拥有窗口起点，此时 `nextAt` 可能未变而窗口已换 —— 漏比会
+ * 让进度环停在上一个窗口的比例上。
+ * @param a - 旧摘要。
+ * @param b - 新摘要。
+ * @returns 键集合与每条内容都相同时为 true。
+ */
+export declare function sameScheduleSummary(a: ScheduleSummaryMap, b: ScheduleSummaryMap): boolean;
+/** 分组聚合结果（折叠的工作区分组徽标直接用这一份）。 */
+export interface GroupScheduleSummary {
+    /** 组内**有任务**的会话数。 */
+    readonly sessions: number;
+    /** 组内任务总数（含暂停项）。 */
+    readonly count: number;
+    /** 组内暂停项数量。 */
+    readonly pausedCount: number;
+    /** 组内最早触发时刻（epoch ms）；全部暂停或缺省时为 undefined。 */
+    readonly nextAt?: number;
+    /** 组内最高优先级状态（overdue > urgent > scheduled）；无任务时为 undefined。 */
+    readonly state?: PresenceBadgeState;
+}
+/**
+ * 按**分组**聚合摘要：给定组内会话 id，折叠出可直接渲染的分组事实。
+ *
+ * 消费方（如 dsh-group-status 的 `GroupLiveStatus`）只需把组内会话 id 传进来，
+ * 无需理解 `nextAt`/暂停语义。
+ * @param summary - {@link ScheduleSummaryMap}。
+ * @param sessionIds - 组内会话 id（顺序无关；不在摘要里的会被忽略）。
+ * @returns 分组级摘要；组内无任务时 `sessions`/`count` 为 0、`state` 缺省。
+ */
+export declare function summarizeScheduleGroup(summary: ScheduleSummaryMap, sessionIds: Iterable<string>): GroupScheduleSummary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-later",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "给 DSH 加上定时发送：输入一句话，到点自动以你的身份送出，关掉网页也准时触发。定时发送 / 定时提醒 / 延迟发送。",
   "icon": "./icon.svg",
   "keywords": [