dsh-later 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,59 @@
 
 ## 未发布
 
+## 1.3.0 — 2026-10-10
+
+- **feat** `/later` 附件支持：带图提交不再被拦截，附件写进 sidecar，到点按记录顺序拼在文本块之后代发。
+- **feat** 多次写法（Beta，默认开启）：`+1h*3`（等间隔×N）、`+1h+1h+0.5h`（相对链式）、`15:32+16:32`（绝对锚点）展开成 N 条独立 one-shot 任务。上限 10 条、最小间隔 60 秒。
+- **feat** 残片守卫：`+1h*3 x` 不再静默误解析成单条，一律显式报错。
+- **fix** 时区墙钟修复：UTC 负偏移时区（如 `America/Los_Angeles`）整体错一天的问题。
+- **refactor** UI 图标全部改用官方图标集 `@deepseek-ai/dsh-client-ui-primitives`（issue #19）：删掉 8 处手写内联 SVG 与 3 处文本符号，统一换 `<IconXxxRegular />`。dock 操作按钮改为 portal 化的 `DockTip` tooltip。
+- **fix** 定时配置面板抬升面对齐官方风格（issue #24）：背景/描边/阴影/圆角/层级对齐官方 PickerPopover，面板 portal 到 document.body，定位改用官方 `useAnchoredPosition`。
+- **docs** README 与微文案补上多次写法、附件与设置项说明。
+
+## 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

@@ -36,7 +36,7 @@ Click the **"Schedule send"** button to the right of the input box. The panel us
 
 ### Time formats
 
-All of these are accepted (`/schedule`, `/later`, and the panel's custom time share the same parser):
+All of these are accepted (`/schedule`, `/later`, and the panel's custom time share the same parser; the rows marked *commands only* are rejected by the panel):
 
 | Kind | Examples |
 |---|---|
@@ -44,23 +44,55 @@ All of these are accepted (`/schedule`, `/later`, and the panel's custom time sh
 | Time today | `15:32` · `9点` · `9点半` · `1532` |
 | Relative day + time | `明天9点` · `后天 10:00` |
 | Date + time | `8月21日 15:32` · `2026-08-21 15:32` · `0821-1532` |
+| Repeat, fixed interval (*commands only*) | `+1h*3 drink water` · `+30m×2 check build` |
+| Repeat, chained sequence (*commands only*) | `+1h+1h+0.5h watch the rollout` · `+1h +30m submit report` |
+| Anchor sequence (*commands only*) | `15:32+16:32+17:32 three meetings` · `9:00+1d+1d standup` · `明天9点+1h` |
+
+The three bolded rows above are **[Advanced syntax (Beta)](#configuration)** and can be switched off together in settings; every other form is unaffected.
 
 A bare time (like `1532`) rolls over to tomorrow if it has already passed today (up to 7 days). Writing `明天`/`后天` is taken literally — if that time has passed you are told to use a concrete date instead. A month/day only (like `8月21日`) rolls over to next year when this year's has passed.
 
+Multi-shot rules — **the first occurrence lands after the first interval**:
+
+| Input | Expands to |
+|---|---|
+| `+1h*3` | t+1h, t+2h, t+3h |
+| `+1h+1h+0.5h` | t+1h, t+2h, t+2.5h (chained — good for "2 h → 1 h → 30 min before the deadline" nagging) |
+| `15:32+16:32+17:32` | those three clock times today |
+| `23:00+01:00` | 23:00 today, **tomorrow** 01:00 (an earlier time in the chain rolls over, same rule as a single shot) |
+| `9:00+1d+1d` | 09:00 on three consecutive days |
+
+At most **10 tasks** per command, and multi-shot intervals must be **≥ 60 seconds** (single shots are unrestricted — `/later +5s` still works). `*`, `×` and `x` all work, an optional Chinese counter suffix is accepted (`*3次`), and the count must be followed by a space. Every occurrence is an **independent task**: cancel it, edit it or send it early on its own, and `/later` attachments are carried by each one. Absolute times (`15:32`, `明天9点`) do **not** accept `*count` — you get an explicit error instead of a silently wrong single task.
+
+Chains allow exactly **one direction: an absolute anchor, then forward accumulation.** `+1h+15:32` (a clock time after a duration) is rejected rather than guessed.
+
+One difference between anchor and relative chains (deliberate, not a bug):
+
+| Form | Stored as | Pausable | Across DST |
+|---|---|---|---|
+| `+1h*3` / `+1h+30m` (relative) | `after` | ✅ | —— |
+| `15:32+16:32` / `9:00+1d` (anchor) | `at` | ❌ (button disabled with a reason) | ✅ wall clock holds: on a fall-back day `9:00+1d` is **25 h** later and still 09:00, whereas adding 86400 s would drift to 08:00 |
+
+`+1d` advances by **calendar day**, not 86400 seconds — which is why `+1d*3` and `9:00+1d+1d` differ in zones with DST (the former counts real seconds, the latter counts wall clock). A wall clock that does not exist (the hour skipped by the spring-forward) is an error, never a silently shifted time.
+
 ### Commands
 
 | Command | Effect |
 |---|---|
 | `/schedule <time> <content>` | Create a reminder (shows up in the conversation when due) |
 | `/later <time> <content>` | Delayed send: deliver the content later as yourself |
-| `/schedule every <interval> <content>` | Recurring reminder (interval ≥ 5 min) |
+| `/later <time>*<count> <content>` | Same, expanded into N delayed sends (`+1h*3`) |
+| `/schedule <time>+<time> <content>` | Same, a chained sequence expanded into N reminders (`+1h+30m`) |
+| `/later <clock>+<clock> <content>` | Anchor sequence: expand by wall-clock instants (`15:32+16:32`, `9:00+1d+1d`) |
 
 ```
 /schedule 明天9点 提交周报
 /later 1532 提醒团队同步进度
+/later +1h*3 起来喝水
+/later +2h+1h+30m 催我交周报
 ```
 
-The model can also call user tools on your behalf to create/inspect/delete/edit reminders (`user_schedule_create` / `user_schedule_list` / `user_schedule_delete` / `user_schedule_edit`).
+The model can also call user tools on your behalf to create/inspect/delete/edit reminders (`user_schedule_create` / `user_schedule_list` / `user_schedule_delete` / `user_schedule_edit`). **Endlessly recurring** reminders (every hour, forever) are only reachable this way: ask the model "每小时提醒我喝水" and it creates an `every_seconds` schedule — such a task has no end condition and must be deleted by hand.
 
 ### Pending dock
 
@@ -186,11 +218,64 @@ Works out of the box. Adjust in **DSH Settings → Plugins → Session Scheduler
 | Allow long prompts | Lift the 1000-character default cap | Off |
 | Custom cap | Character cap when `allowLongPrompts` is on | 1000 |
 | Work hours / lunch / night quiet | Five HH:mm fields driving smart slots and auto-scheduling | See settings page |
+| Interjection delivery | Which queue "Send interjection" uses: own turn (default, safe) / current turn (faster, can drop in an edge case) | Own turn |
+| Delivery confirmation / on unconfirmed | Whether to verify a reminder really landed, and what to do when it isn't confirmed | On / keep |
+| Clock icon style | `auto` (by kernel version) / `modern` / `classic` | auto |
+| **Advanced syntax** (Beta) | Master switch for multi-shot forms: `+1h*3`, `+1h+1h+0.5h`, `15:32+16:32`, `9:00+1d`. When off, those forms are rejected with a pointer back to settings | **On** |
+
+> Advanced syntax is marked Beta not because it is untested (43 new unit tests cover it) but because **the expanded result still needs real-world observation**: whether 10 tasks flood the dock, and whether the 60-second floor and 10-task cap are the right sizes.
+> Turning it off does **not** restore the old silent mis-parse (`+1h*3 x` creating one task whose content is `*3 x`) — that was a bug, not a fallback. The residual-token guard is independent of this switch and always on.
 
 > Advanced: defaults can also be overridden at startup via `cordis.patch.yml` (e.g. `maxSchedules`) — see `docs/` and the schema.
 
 ---
 
+## 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

@@ -36,7 +36,7 @@
 
 ### 时间格式
 
-以下写法都认（`/schedule`、`/later` 与面板自定义时间共用）：
+以下写法都认（`/schedule`、`/later` 与面板自定义时间共用；标了「仅 `/later` `/schedule`」的写法面板不收）：
 
 | 类型 | 示例 |
 |---|---|
@@ -44,23 +44,55 @@
 | 当天时刻 | `15:32` · `9点` · `9点半` · `1532` |
 | 相对日 + 时刻 | `明天9点` · `后天 10:00` |
 | 日期 + 时刻 | `8月21日 15:32` · `2026-08-21 15:32` · `0821-1532` |
+| **重复 · 等间隔**（仅 `/later` `/schedule`） | `+1h*3 喝水` · `+30m×2 看构建` · `两小时后×3次` |
+| **重复 · 链式序列**（仅 `/later` `/schedule`） | `+1h+1h+0.5h 盯发布` · `+1h +30m 交周报` |
+| **锚点序列**（仅 `/later` `/schedule`） | `15:32+16:32+17:32 三会` · `9:00+1d+1d 打卡` · `明天9点+1h` |
+
+上表三行加粗的都属于 **[高级语法（Beta）](#配置)**，可在设置里一键关闭；其余写法不受开关影响。
 
 只写时刻（如 `1532`）时，若今天已过会自动顺延到明天（最多 7 天）；写了 `明天`/`后天` 则按字面理解，该时刻已过会提示改用具体日期；只写月日（如 `8月21日`）时，今年已过则顺延到明年。
 
+多次写法的规则（**首次落在第一个间隔之后**）：
+
+| 写法 | 展开成 |
+|---|---|
+| `+1h*3` | t+1h、t+2h、t+3h |
+| `+1h+1h+0.5h` | t+1h、t+2h、t+2.5h（链式累加，用来写「提前 2h→1h→30m」这类梯度催办） |
+| `15:32+16:32+17:32` | 今天 15:32、16:32、17:32（三个挂钟时刻） |
+| `23:00+01:00` | 今天 23:00、**次日** 01:00（后一个时刻更早则自动顺延，规则同单条） |
+| `9:00+1d+1d` | 连续三天都是 9:00 |
+
+一次最多 **10 条**，多次写法的间隔不低于 **60 秒**（单条不受此限，`/later +5s` 照旧）。`*` `×` `x` 都认，可跟中文量词（`*3次`），次数后面要留空格。每条都是**独立任务**：可单独取消、编辑、插话发送（暂停见下表）。
+
+序列里只允许**「绝对时刻开头，往后累加」**这一个方向：`+1h+15:32` 会明确报错，不会猜。
+
+**锚点序列与相对序列的一处差别**（有意为之，不是 bug）：
+
+| 写法 | 落库类型 | 能暂停 | 跨夏令时 |
+|---|---|---|---|
+| `+1h*3` / `+1h+30m`（相对） | `after` | ✅ | —— |
+| `15:32+16:32` / `9:00+1d`（锚点） | `at` | ❌（按钮置灰并说明原因） | ✅ 墙钟不变：`9:00+1d` 在回拨日相隔 **25 小时**仍是 9:00，按 86400 秒累加会漂成 8:00 |
+
+`9:00+1d` 里的「一天」按**日历日**推进（不是 86400 秒），所以 `+1d*3` 与 `9:00+1d+1d` 在有夏令时的时区结果不同——前者按真实秒数、后者按墙钟。落到不存在的墙钟（前拨跳过的那一小时）会报错而不是悄悄挪时刻。绝对时刻（`15:32`、`明天9点`）不支持 `*次数`，会明确报错而不是悄悄变成一条。
+
 ### 命令
 
 | 命令 | 作用 |
 |---|---|
 | `/schedule <时间> <内容>` | 创建一条定时提醒（到点出现在对话里） |
 | `/later <时间> <内容>` | 延迟发送：到点以你的身份发出该内容 |
-| `/schedule every <周期> <内容>` | 周期性提醒（周期 ≥ 5 分钟） |
+| `/later <时间>*<次数> <内容>` | 同上，展开成 N 条代发（`+1h*3`） |
+| `/schedule <时间>+<时间> <内容>` | 同上，链式序列展开成 N 条提醒（`+1h+30m`） |
+| `/later <时刻>+<时刻> <内容>` | 锚点序列：按挂钟时刻展开（`15:32+16:32`、`9:00+1d+1d`） |
 
 ```
 /schedule 明天9点 提交周报
 /later 1532 提醒团队同步进度
+/later +1h*3 起来喝水
+/later +2h+1h+30m 催我交周报
 ```
 
-模型也可以直接调用用户工具为你创建/查询/修改提醒（`user_schedule_create` / `user_schedule_list` / `user_schedule_delete` / `user_schedule_edit`）。
+模型也可以直接调用用户工具为你创建/查询/修改提醒（`user_schedule_create` / `user_schedule_list` / `user_schedule_delete` / `user_schedule_edit`）。**无限周期**提醒（每 1 小时一直发下去）只有这条路：让模型说「每小时提醒我喝水」，它会用 `every_seconds` 建一条周期任务；周期任务没有结束条件，需要你手动删。
 
 ### 待发送 dock
 
@@ -186,11 +218,62 @@ dsh plugin --profile web add "file:/path/to/dsh-later"
 | 允许长文本 | 解除 1000 字符默认下限 | 关闭 |
 | 自定义上限 | `allowLongPrompts` 开启时的字符上限 | 1000 |
 | 工作时间 / 午休 / 晚间静默 | 智能时段 5 个 HH:mm 字段，决定快捷芯片与智能排期 | 见设置页 |
+| 插话投递方式 | 「插话发送」进哪个队列：独立成一轮（默认，安全）/ 当前轮（更快，极端情况下会丢） | 独立成一轮 |
+| 投递确认 / 未确认处理 | 是否核对提醒真的送达，以及未确认时保留还是丢弃 | 开 / 保留 |
+| 时钟图标风格 | `auto`（按内核版本）/ `modern` / `classic` | auto |
+| **高级语法** <span>Beta</span> | 多次写法总开关：`+1h*3`、`+1h+1h+0.5h`、`15:32+16:32`、`9:00+1d`。关闭后这些写法被明确拒绝并提示回设置开启 | **开启** |
+
+> 「高级语法」标 Beta 的原因不是没测（43 个新单测覆盖），而是**展开后的观感仍需观察**：一次命令写 10 条会不会刷屏、60 秒地板与 10 条上限是否合适。
+> 关闭它**不会**退回旧版的静默误解析（`+1h*3 x` 建成一条内容为 `*3 x` 的任务）——那是 bug，不在可回退的功能面里；残片守卫与本开关无关，始终生效。
 
 > 进阶：也可以用 `cordis.patch.yml` 在启动期覆盖默认值（如 `maxSchedules`），见 `docs/` 与 schema。
 
 ---
 
+## 给插件开发者：定时摘要 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：