dsh-later 1.0.0 → 1.1.0

package/lib/schedule-compat.js

@@ -0,0 +1,179 @@
+/**
+ * dsh-schedule 0.1.5 → 0.1.7 的版本桥接层。
+ *
+ * 0.1.7 对 `dsh-schedule` 做了三处破坏性变更，本模块把差异收敛为三个函数，
+ * 使 `user-tools.ts` / `runtime.ts` 不必写版本分支：
+ *
+ * 1. `allocateScheduleId(folded)` → 删除。0.1.5 用确定性递增
+ *    （`schedule-1`、`schedule-2`…，靠 `seenIds` 避让），0.1.7 内联改为
+ *    `ScheduleId(\`schedule-${randomUUID()}\`)`（见 0.1.7 `ScheduleService.create`）。
+ *    本插件的 `ownership-store` 把 id 当**不透明字符串**处理（无排序、无数字
+ *    解析，见 docs/verification.md），故行为差异对功能无影响。
+ *
+ * 2. `createAfterScheduleRecord` 新增第 5 个必填参数 `title`。0.1.7 起
+ *    `decodeStoredTitle` 会在读取时校验：缺失 / 未 trim / 超长（>120）的
+ *    存量记录抛 `ScheduleLogError`——**不是跳过，是整份日志拒读**。
+ *
+ * 3. `renderEveryReminderBatchFraming` → 改名
+ *    `renderRecurringReminderBatchFraming`（语义与参数不变）。
+ *
+ * @module dsh-later/schedule-compat
+ */
+import * as sched from '@deepseek-ai/dsh-schedule';
+import { randomUUID } from 'node:crypto';
+const { ScheduleId } = sched;
+/** 0.1.7 `MAX_TITLE_LENGTH`；0.1.5 无此概念，该常量在此仅作截断阈值。 */
+export const SCHEDULE_TITLE_MAX = 120;
+/**
+ * 读取一个**可能不存在**的导出。
+ *
+ * 必须走 namespace + 属性访问，不能用具名 import：ESM 具名 import 在目标导出
+ * 缺失时是**链接期硬失败**（`SyntaxError: does not provide an export named …`），
+ * 无法用 `as unknown as` 兜底。0.1.7 删掉 `renderEveryReminderBatchFraming` 后，
+ * 具名 import 会让整个插件在 0.1.5 上也无法加载——正好与支持区间相反。
+ */
+function pick(name) {
+    return sched[name];
+}
+/**
+ * 0.1.7 的 `allocateScheduleId` 等价物。
+ *
+ * 随机 UUID 而非递增序号：与官方 `ScheduleService.create` 行为一致，且并发
+ * 创建时天然无碰撞。0.1.5 下也可用（`ScheduleId` 是纯 brand 校验，任意
+ * 非空字符串通过），因此本函数在两个代次上语义相同，无需双轨。
+ *
+ * @param _folded 仅为**保持调用点不变**而接受 0.1.5 的 `folded` 参数；0.1.7
+ *   不再需要它来避让碰撞（UUID 本身唯一），故不使用。
+ */
+export function allocateScheduleIdCompat(
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_folded) {
+    return ScheduleId(`schedule-${randomUUID()}`);
+}
+/**
+ * 从提醒正文派生 `title`。
+ *
+ * 0.1.7 要求 title 非空、已 trim、≤120 字符。实测本插件历史 496 条提醒中
+ * 最长 575 字符（27 条超限，占 5.4%），故**必须截断**而非直接透传 prompt。
+ * 截断在词边界优先，找不到合适边界时按字符硬切并补省略号，保证结果始终
+ * 是合法 title（`scheduleTitle` 不会抛）。
+ */
+export function deriveScheduleTitle(prompt) {
+    const normalized = prompt.trim();
+    if (normalized.length === 0)
+        return '定时提醒';
+    if (normalized.length <= SCHEDULE_TITLE_MAX)
+        return normalized;
+    const clipped = normalized.slice(0, SCHEDULE_TITLE_MAX - 1);
+    const lastBreak = Math.max(clipped.lastIndexOf(' '), clipped.lastIndexOf('　'));
+    const body = lastBreak >= SCHEDULE_TITLE_MAX * 0.6 ? clipped.slice(0, lastBreak) : clipped;
+    return `${body.trimEnd()}…`;
+}
+/**
+ * 调用一个 `create*ScheduleRecord`，按目标代次决定是否追加 `title`。
+ *
+ * 0.1.5 签名为 `(id, prompt, selector, now)`；0.1.7 追加第 5 位必填 `title`。
+ * 0.1.7 的 `scheduleTitle` 对空 / 未 trim / >120 字符一律抛错，故 title 必须
+ * 由 `deriveScheduleTitle` 保证合法。
+ */
+function createRecord(name, id, prompt, selector, now) {
+    const fn = pick(name);
+    if (typeof fn !== 'function') {
+        throw new Error(`dsh-later: dsh-schedule does not export ${name} — unsupported kernel generation.`);
+    }
+    // 0.1.7 的 arity 为 5；0.1.5 为 4。按 arity 择一，无需版本号判断。
+    return fn.length >= 5
+        ? fn(id, prompt, selector, now, deriveScheduleTitle(prompt))
+        : fn(id, prompt, selector, now);
+}
+/** `createAfterScheduleRecord` 的跨版本包装。 */
+export function createAfterRecord(id, prompt, afterSeconds, now) {
+    return createRecord('createAfterScheduleRecord', id, prompt, afterSeconds, now);
+}
+/** `createAtScheduleRecord` 的跨版本包装。 */
+export function createAtRecord(id, prompt, scheduledAt, now) {
+    return createRecord('createAtScheduleRecord', id, prompt, scheduledAt, now);
+}
+/** `createEveryScheduleRecord` 的跨版本包装。 */
+export function createEveryRecord(id, prompt, everySeconds, now) {
+    return createRecord('createEveryScheduleRecord', id, prompt, everySeconds, now);
+}
+/**
+ * 周期提醒批次的 framing 渲染。
+ *
+ * 0.1.5 导出 `renderEveryReminderBatchFraming`，0.1.7 改名为
+ * `renderRecurringReminderBatchFraming`（并扩展到 daily/weekly/cron，本插件
+ * 只产生 `every` 记录）。两代参数与返回结构一致，按存在性择一。
+ */
+export function renderRecurringBatchFraming(reminders) {
+    const render = pick('renderEveryReminderBatchFraming') ??
+        pick('renderRecurringReminderBatchFraming');
+    if (typeof render !== 'function') {
+        throw new Error('dsh-later: dsh-schedule exposes neither renderEveryReminderBatchFraming ' +
+            'nor renderRecurringReminderBatchFraming — unsupported kernel generation.');
+    }
+    return render(reminders);
+}
+/**
+ * 提醒注入消息的 `source`。
+ *
+ * 0.1.5 的 `MessageSourceMap` 含 `plugin: { kind:'plugin'; plugin:string }`；
+ * 0.1.7 **删除了 `plugin` 与 `host` 两个 kind**，改由内核为每个生产者登记
+ * 具名 kind。官方 `dsh-schedule` 在 0.1.7 里注入提醒用的正是
+ * `source: { kind: 'schedule' }`（见其 `lib/index.js` 的 `agent.followup` 调用点）
+ * —— 与本插件投递的语义一致，故 0.1.7 走 `schedule`。
+ *
+ * `form:'notice'` + `summary` 两代都在（`ContextFormed` 未变），保留。
+ *
+ * 不能用具名类型断言跨代：source 的字面量 union 在两代不同，断言只会把
+ * 编译错误推迟到运行期。
+ */
+export function scheduleMessageSource(boundedSummary) {
+    const base = { form: 'notice', summary: boundedSummary };
+    // 0.1.7 已删除 'plugin'；`schedule` 与 renderRecurringReminderBatchFraming
+    // 同属 0.1.7 引入，二者同时存在即为 0.1.7+。
+    const isV17 = pick('renderRecurringReminderBatchFraming') !== undefined;
+    return isV17
+        ? { kind: 'schedule', ...base }
+        : { kind: 'plugin', plugin: PLUGIN_LABEL, ...base };
+}
+/**
+ * `foldScheduleEvents` 结果的读视图收窄。
+ *
+ * 0.1.5 的 `FoldedSchedules.active` 是 `ScheduleRecord[]`；0.1.7 改为
+ * `LegacyScheduleRecord[]`（title 可选）。本插件只消费 `id` / `kind` /
+ * `prompt` / `afterSeconds` / `everySeconds` / `scheduledAt`，这些字段在
+ * `Legacy*` 视图中全部存在，故收窄无损。
+ */
+export function asLegacySchedules(folded) {
+    return folded;
+}
+/** 本插件在 0.1.5 时代的 source 标签（0.1.7 已无 plugin kind，仅作回退标识）。 */
+const PLUGIN_LABEL = '定时提醒';
+/**
+ * `schedule/change` 事件里 `create` 操作的载荷类型。
+ *
+ * 0.1.7 起内核把「事件载荷」与「内部记录」拆成两个类型：
+ * - `ScheduleCreateChange.schedule` 是 **`LegacyScheduleRecord`**（title 可选）
+ * - `ScheduleRecord` 是 Host 内部的新格式（title 必填，且含 daily/weekly/cron）
+ *
+ * 本插件只产生 `after` / `at` / `every` 三种（见 buildScheduleRecord），三者都是
+ * `Legacy*` 的对应分支去掉「title 必填」后的结果，故结构兼容。
+ *
+ * 但 TS 层面 `ScheduleRecord`（6 变体联合）对 `LegacyScheduleRecord`（3 变体）
+ * 不可赋值——**这不是运行时问题，是联合宽度问题**。故在此显式收窄：本插件
+ * 的产出已经过 `createAfter/At/EveryRecord` 限定，不含 daily/weekly/cron。
+ */
+export function toChangePayload(record) {
+    return record;
+}
+/**
+ * `foldScheduleEvents().active` 元素的读取侧类型。
+ *
+ * 0.1.5 直接返回 `ScheduleRecord`；0.1.7 返回 `LegacyScheduleRecord`
+ * （title 可选，因为历史事件没有）。本插件读路径只在 title 存在时展示，
+ * 缺失时回退到 prompt——故按 Legacy 收窄是**语义正确**的，而非绕过检查。
+ */
+export function asLegacyRecords(records) {
+    return records;
+}

package/lib/types/bar-geometry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 进度条几何：活动期与暂停冻结期**共用同一套时间基准**。
+ *
+ * 为什么要单独成模块并写清楚：进度条在「活动 ↔ 暂停 ↔ 恢复」之间切换时，
+ * 稍有不一致就会让用户看到条长跳变。历史上有两类真实缺陷：
+ *
+ *  1. 两套基准：冻结比曾由 `remaining_seconds`（整数秒、ceil）反推，与活动期
+ *     精确 ms 的 `now` 恒差一个取整 → 非整秒暂停必然变长。
+ *  2. 两个时刻：`paused_at` 是**宿主**处理暂停命令的时刻，比用户点下暂停时最后
+ *     渲染的那一帧晚（命令通道往返，实测约 0.3–0.5s）。直接用它做冻结帧，条长
+ *     会比前一帧更长 → 「点暂停，条忽然变长」。
+ *
+ * 现在统一为：`barWindow()` 求窗口，冻结帧只把 `now` 换成冻结时刻，并把冻结
+ * 时刻**钳到 ≤ 客户端已渲染时刻**。因此暂停瞬间条长与点击前严格一致。
+ *
+ * 本模块被 host 与 client 两侧共用（与 command-outcome / smart-window /
+ * time-utils 同款：同时列出在 tsconfig.json 与 tsconfig.client.json 的 include 中）。
+ *
+ * @module dsh-later/bar-geometry
+ */
+/** 每根进度条代表的时长（1 小时 = 一根满管）。 */
+export declare const BAR_UNIT_MS = 3600000;
+/** 参与几何计算的 schedule 最小视图（与 client `ClientSchedule` 结构兼容）。 */
+export interface BarScheduleView {
+    readonly id: string;
+    readonly kind: 'after' | 'at' | 'every';
+    readonly scheduled_at: string;
+    readonly after_seconds?: number;
+    readonly every_seconds?: number;
+    readonly created_at?: string;
+    /** 进度条总窗口（秒）；resume 后 after_seconds 只是剩余，此字段保留原间隔。 */
+    readonly window_seconds?: number;
+    readonly paused_at?: string;
+}
+/**
+ * 推导进度条起点与总窗口（暂停/活动期共用同一套时间基准）。
+ * - `after`：`window_seconds`（resume 后保留的原间隔）→ `after_seconds` → `created_at` → 首见时刻
+ * - `every`：`every_seconds` 反推
+ * - 其余：`created_at` → 首见时刻
+ */
+export declare function barWindow(item: BarScheduleView, end: number, now: number, firstSeen: ReadonlyMap<string, number>): {
+    readonly start: number;
+    readonly totalMs: number;
+};
+/** 活动期进度比：elapsed / total。 */
+export declare function barSegments(item: BarScheduleView, now: number, firstSeen: ReadonlyMap<string, number>): {
+    readonly totalRatio: number;
+    readonly count: number;
+};
+/**
+ * 暂停冻结进度比。
+ *
+ * ⚠️ 关键：**不能用 `scheduled_at` 反推**。暂停后 wire 的 `scheduled_at` 会从
+ * 「resume 后的新目标」换成 `originalScheduledAt`（原目标），而 `window_seconds`
+ * 始终是原窗口。若沿用活动期那套 `end - window` 的算法，暂停瞬间窗口基准整体
+ * 跳变，条长会剧烈塌缩（实测 25.7% → 3.3%）。
+ *
+ * 因此冻结帧改成**自洽的纯算术**，不依赖任何可能变义的字段：
+ *   ratio = (window - remaining) / window
+ * 其中 window 取 `window_seconds ?? after_seconds`，remaining 取
+ * `max(0, frozenLeftMs)`（即 `remaining_seconds * 1000`）。
+ *
+ * 这样冻结比例天然等于「暂停那一刻已经过掉的部分」，与暂停前后用的是同一个
+ * 窗口；`paused_at` 只用于可选的上界钳制（见 `renderedAt`）。
+ *
+ * @param frozenLeftMs - 冻结剩余毫秒（`remaining_seconds * 1000`）。
+ * @param renderedAt - 可选：客户端已渲染过的最新时刻上界；提供且早于暂停时刻时，
+ *   按该上界折算，保证冻结帧不超过用户已看到的进度。
+ */
+export declare function frozenBarSegments(item: BarScheduleView, frozenLeftMs: number, firstSeen: ReadonlyMap<string, number>, renderedAt?: number): {
+    readonly totalRatio: number;
+    readonly count: number;
+};
+/**
+ * 活动期「CSS 动画」计划：把进度条的推进交给 CSS，而不是每秒一次 JS 重渲染。
+ *
+ * 为什么需要：旧实现由 `useNow(1000)` 每秒更新一次 `now`，宽度随之每秒跳一次，
+ * 再用 `transition: width 1s linear` 补间。1 分钟任务的轨道上每秒要跳约 8px，
+ * 形成肉眼可见的锯齿/顿挫（长条上尤其明显）。
+ *
+ * ⚠️ 关键约束一：参数必须**只依赖任务自身的时间轴**（`start` / `end`），
+ * 不能依赖「当前渲染时刻」。否则每次 tick 重渲染都会改变参数 → 浏览器重启动画
+ * → 每秒一次固定跳变（实测 deltas 呈 `1.7×5, 10.2` 周期尖峰）。
+ *
+ * ⚠️ 关键约束二：**CSS 动画在元素被重建时会从头播放**。切到别的会话再切回来，
+ * dock 会卸载并重新挂载，动画 `currentTime` 归零——若只靠"动画自己走"，进度条
+ * 会退回 0% 附近（实测：真实已过 184s/600s 应为 30.7%，切回后却显示 2.55%，
+ * 恰好等于「重挂载后流逝的 15.3s / 600s」）。因此必须用**负 `animation-delay`**
+ * 在挂载瞬间就把播放头**定位到正确的绝对相位**：
+ *
+ *   delay = -(已过去时长)   →   一上屏就处在 elapsed/total 处
+ *
+ * 这样无论挂载多少次、间隔多久，画面都落在任务真实时间轴的正确位置。
+ *
+ * 由于负 delay 只由 `start`/`end`/`now` 决定，而这三者都是绝对时间，
+ * 「切走再切回」与「一直看着」得到的相位完全一致。
+ */
+export interface BarAnimationPlan {
+    /** 动画总时长（ms）＝ 完整窗口，保证播放头按绝对进度线性推进。 */
+    readonly durationMs: number;
+    /** 负延迟（ms）：把播放头定位到「已过去」处，抵消重挂载导致的归零。 */
+    readonly delayMs: number;
+}
+/**
+ * 依据窗口与当前时刻推导动画计划。
+ *
+ * @param totalMs - 总窗口毫秒（> 0）。
+ * @param elapsedMs - 已过去毫秒（钳到 [0, totalMs]）。
+ * @returns 计划；`totalMs <= 0`、非有限值、或已到点（剩余为 0）时返回 `undefined`。
+ */
+export declare function planBarAnimation(totalMs: number, elapsedMs: number): BarAnimationPlan | undefined;

package/lib/types/command-outcome.d.ts

@@ -0,0 +1,19 @@
+/**
+ * slash 命令的执行结果：**只表达「是否被受理」**。
+ *
+ * 为什么单独成模块并写清楚：`dsh-commands` 的 admission 语义只回
+ * `RemoteResult<{matched}>`，handler 的业务结果不从这里返回（它落在会话记录 /
+ * 投影里）。因此客户端**不得**用本类型判断「业务是否真的发生了」——例如删除
+ * 暂停项时 host 可能返回 `deleted:false`，而这里照样是 `matched: true`。
+ * 需要业务事实时以 `userSchedules` 投影为准（见 ScheduleDock 的观察窗对账）。
+ *
+ * 本模块被 host 与 client 两侧共用（与 smart-window / time-utils 同款：
+ * 同时列出在 tsconfig.json 与 tsconfig.client.json 的 include 中）。
+ *
+ * @module dsh-later/command-outcome
+ */
+/** 一条命令的执行结果。 */
+export interface CommandOutcome {
+    /** 命令是否被受理（matched）。false 表示未受理（无会话面 / 网络异常 / 无此命令）。 */
+    readonly matched: boolean;
+}

package/lib/types/delivery.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 插话投递的「投递 + 送达确认」原语。
+ *
+ * 为什么需要：`agent.steer()` 把消息放进 `next-step`，语义是「下一个 step 边界
+ * 消费」。若插话恰好撞上 `turn/start`，核心的 `inbox.claim('next-step', …)` 会把
+ * **整批** `next-step` 取走交给一个**请求上下文已定**的 step —— 消息落进 surface
+ * （日志里确有一条 `user/message`）却不进实际请求，即**静默丢失**。实测时序：
+ *
+ *   t+0ms   agent/inbox/spliced  → 插入 next-step
+ *   t+1ms   turn/start           → turn 17 开始（同一毫秒）
+ *   t+1ms   agent/inbox/spliced  → removedCount:1, inserted:[]  ← 被 claim 吞掉
+ *   t+17ms  request/header       → 请求已按旧上下文构造
+ *
+ * `agent.followup()` 入 `next-turn`，与 `next-step` 是两条独立队列，
+ * `claim('next-step', …)` 不触碰它，**结构上不存在**这个竞态 —— 故默认用它。
+ *
+ * 送达确认**只读会话日志**，不监听 `inbox/claimed` / `request/header` 等运行时
+ * 事件：那些事件的顺序是核心内部实现细节，监听它们等于把插件耦合到核心时序上，
+ * 核心一改就静默失效。日志格式是插件已经在依赖的稳定面（`foldUserState` 同源）。
+ * @module dsh-later/delivery
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+/** 投递方式（与 settings 的 steerDelivery 同源，避免循环依赖故在此重述）。 */
+export type DeliveryMode = 'followup' | 'steer';
+/**
+ * 投递确认的超时预算。
+ *
+ * 正常核对在**毫秒级**完成（消息 append 后同一次宏任务内即可读到）；2s 是留给
+ * 极端调度延迟的宽裕上限，超时即判「未确认」——宁可让用户看到可重试的提示，
+ * 也不要静默当成成功。
+ */
+export declare const DELIVERY_CONFIRM_TIMEOUT_MS = 2000;
+/**
+ * 日志中是否出现该 message id。
+ *
+ * 判据是消息**真的进了会话日志**。这里刻意不进一步区分「进了 surface」与
+ * 「进了实际请求」：`agent.followup` 路径下二者由核心保证一致（消息成为独立一轮
+ * 的唯一条消息）；而 `steer` 路径的丢失发生在**插入后同毫秒被 claim 移除**，
+ * 那种情况下连 `user/message` 都不会留下，本判据足以识别。
+ */
+export declare function hasMessageInLog(session: Session, messageId: string): boolean;
+/** 等待投递被日志确认；超时返回 false。 */
+export declare function confirmDelivery(session: Session, messageId: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * 取消息 id（`createUserMessage` 会生成 uuid）。
+ *
+ * `UserMessage.id` 在类型上是必填，但运行时若某代内核未填则这里回落空串，
+ * 调用方的确认逻辑对空 id 一律判「无法确认」。
+ */
+export declare function messageIdOf(message: UserMessage): string;

package/lib/types/domain.d.ts

@@ -16,6 +16,12 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 /** 插件名（与 cordis 条目 id / manifest 一致）。 */
 export declare const name = "dsh-later";
+/**
+ * settings 命名空间。0.1.1 要求 branded `SettingsNamespace`、0.1.2 已删除
+ * `settingsNamespace()` helper——调用处以 `'dsh-later' as SettingsNamespace`
+ * 断言注册（见 index.ts），字面量只在这里维护一份。
+ */
+export declare const SETTINGS_NAMESPACE = "dsh-later";
 /** 会话投影键：GUI 通过 `useProjection` / `faceOf` 读取用户任务列表。 */
 export declare const PROJECTION_KEY = "userSchedules";
 /**
@@ -49,6 +55,7 @@ export type UserScheduleDelivery = 'context' | 'user';
  * 字段用 snake_case，与 `user_schedule_list` 工具响应保持一致。
  */
 export interface UserScheduleWireItem {
+    /** 稳定身份：active 优先 ownership.uid，否则 scheduleId；paused 恒为 uid。 */
     readonly id: string;
     readonly kind: 'after' | 'at' | 'every';
     readonly prompt: string;
@@ -58,6 +65,19 @@ export interface UserScheduleWireItem {
     /** 创建时刻（来自 create 事件的 time；旧日志/未知时缺省）。 */
     readonly created_at?: string;
     readonly delivery_mode: 'session-local';
+    /** active 可省略（旧客户端）；paused 必带。 */
+    readonly status?: 'active' | 'paused';
+    /** 暂停冻结的剩余秒数（整数秒，仅用于倒计时文案）。 */
+    readonly remaining_seconds?: number;
+    /** 暂停时刻（ISO；客户端据此冻结进度条，避免整数秒取整造成的长度跳变）。 */
+    readonly paused_at?: string;
+    /** 日志 schedule id（pause 前 / active 当前）。 */
+    readonly schedule_id?: string;
+    /**
+     * 进度条总窗口（秒）。resume 后 `after_seconds` 只是剩余时长；
+     * 此字段保留原 after 间隔，使进度条从冻结处继续而不是从 0 重跑。
+     */
+    readonly window_seconds?: number;
 }
 /** 投影输出值。 */
 export interface UserScheduleProjectionValue {
@@ -102,6 +122,18 @@ export interface UserScheduleProjectionState {
         createdAt?: number;
     }[];
     readonly seedSeq: number;
+    /** sidecar 暂停留档的 plain-JSON 镜像（init/事件后刷新）。 */
+    readonly paused: readonly {
+        uid: string;
+        prompt: string;
+        delivery: UserScheduleDelivery;
+        kind: 'after';
+        remainingSeconds: number;
+        originalScheduledAt: string;
+        originalAfterSeconds?: number;
+        lastScheduleId: string;
+        pausedAt: number;
+    }[];
 }
 /** 判断事件是否属于本插件所有权流。 */
 export declare function isOwnedEvent(event: SessionEvent): event is SessionEvent & {

package/lib/types/index.d.ts

@@ -12,16 +12,24 @@
  * @module dsh-later
  */
 import type { Context } from '@deepseek-ai/cordis';
-import s from '@deepseek-ai/schemastery';
+import type z from '@deepseek-ai/schemastery';
 import { name } from './domain.js';
 /** 插件配置 schema（全可选，默认开箱即用；经 cordis config 覆盖）。 */
-export declare const Config: s<Schemastery.ObjectS<{
-    /** 单 session 用户任务上限。 */
-    maxSchedules: s<number, number>;
-}>, Schemastery.ObjectT<{
-    /** 单 session 用户任务上限。 */
-    maxSchedules: s<number, number>;
-}>>;
+/**
+ * 插件配置 schema（**单一事实来源**）。
+ *
+ * 0.2.0 起 `ctx.settings.describe()` 直接读 `entry.fiber.runtime.Config`
+ * （见 dsh-settings `schema(entry)`：「`entry.fiber?.runtime?.Config`，且需有
+ * `toJSON`」），据此生成该插件设置页的表单。因此**可编辑字段必须全部声明在
+ * `Config` 上**——只放在 `SchedulerSettingsSchema` 里的字段在 0.2.0 下不会
+ * 出现在设置 UI 中。
+ *
+ * 历史：0.1.5 用 `settingsProvider.register(ns, schema, …)` 注册一个**独立于
+ * Config 的** schema（即 `SchedulerSettingsSchema`），0.1.7 删除了该 API。
+ * 两代并存期间两份 schema 内容一致，现统一为 `Config` 一份，`SchedulerSettingsSchema`
+ * 保留为别名以免大范围改动调用点。
+ */
+export declare const Config: z;
 /** 所需服务（延后激活，缺失时插件不加载）。 */
 export declare const inject: string[];
 /** 宿主持有的 settings 形状（settings getter 返回值与 register* 接受入参）。 */
@@ -29,7 +37,19 @@ export interface SchedulerSettings {
     readonly maxSchedules: number;
     readonly allowLongPrompts: boolean;
     readonly maxPromptChars: number;
+    /** 插话投递方式（见 Config.steerDelivery）。 */
+    readonly steerDelivery: UserScheduleSteerDelivery;
+    /** 是否核对投递是否真正送达。 */
+    readonly confirmDelivery: boolean;
+    /** 投递未确认时：保留可重试 / 丢弃。 */
+    readonly onUnconfirmed: UserScheduleOnUnconfirmed;
+    /** 时钟图标风格（auto / modern / classic）。 */
+    readonly clockIconStyle: 'auto' | 'modern' | 'classic';
 }
+/** 插话投递方式。 */
+export type UserScheduleSteerDelivery = 'followup' | 'steer';
+/** 投递未确认时的处理。 */
+export type UserScheduleOnUnconfirmed = 'keep' | 'discard';
 export declare function apply(ctx: Context, config?: {
     maxSchedules?: number;
 }): void;

package/lib/types/ownership-store.d.ts

@@ -5,6 +5,32 @@ export interface OwnedEntry {
     readonly delivery: UserScheduleDelivery;
     /** 创建时刻（epoch ms，诊断用）。 */
     readonly createdAt: number;
+    /**
+     * 稳定插件身份（跨 pause/resume/日志 id 变更）。创建时生成；
+     * 旧条目可缺省（wire 回退用 scheduleId）。
+     */
+    readonly uid?: string;
+    /**
+     * 进度条总窗口（秒）。resume 后日志里的 `afterSeconds` 只是剩余时长，
+     * 若直接当窗口会从 0 重跑；此处保留原 after 间隔供 wire/进度条使用。
+     */
+    readonly windowSeconds?: number;
+}
+/** 暂停留档（仅 kind==='after'；不进会话日志）。 */
+export interface PausedEntry {
+    /** 稳定身份；resume 后仍用此 uid。 */
+    readonly uid: string;
+    readonly prompt: string;
+    readonly delivery: UserScheduleDelivery;
+    readonly kind: 'after';
+    /** 暂停瞬间的剩余秒数（resume 时 after_seconds）。 */
+    readonly remainingSeconds: number;
+    /** 原目标时刻（仅展示「原点 HH:MM」）。 */
+    readonly originalScheduledAt: string;
+    readonly originalAfterSeconds?: number;
+    /** 暂停前的日志 schedule id（审计/关联）。 */
+    readonly lastScheduleId: string;
+    readonly pausedAt: number;
 }
 /** 读取某会话的全部所有权记录（缓存优先；返回副本语义，调用方不得变更）。 */
 export declare function allOwnership(sessionId: string): Readonly<Record<string, OwnedEntry>>;
@@ -12,9 +38,23 @@ export declare function allOwnership(sessionId: string): Readonly<Record<string,
 export declare function hasOwnership(sessionId: string, id: string): boolean;
 /** 某条所有权记录（缺失返回 undefined）。 */
 export declare function getOwnership(sessionId: string, id: string): OwnedEntry | undefined;
-/** 记录（新增或覆盖）一条所有权；幂等。 */
-export declare function recordOwnership(sessionId: string, id: string, delivery: UserScheduleDelivery): void;
+/** 生成稳定插件 uid（pause/resume 跨日志 id 变更）。 */
+export declare function newTaskUid(): string;
+/** 记录（新增或覆盖）一条所有权；幂等。仅显式传入 `uid` 时写入稳定身份。 */
+export declare function recordOwnership(sessionId: string, id: string, delivery: UserScheduleDelivery, uid?: string, windowSeconds?: number): OwnedEntry;
 /** 撤销一条所有权；幂等（不存在时无操作）。 */
 export declare function removeOwnership(sessionId: string, id: string): void;
+/** 按 uid 找当前仍 active 的 schedule id（缺失 undefined）。 */
+export declare function findScheduleIdByUid(sessionId: string, uid: string): string | undefined;
+/** 全部暂停留档（uid → entry）。 */
+export declare function allPaused(sessionId: string): Readonly<Record<string, PausedEntry>>;
+/** 一条暂停留档。 */
+export declare function getPaused(sessionId: string, uid: string): PausedEntry | undefined;
+/** 按暂停前 schedule id 找留档（pause 刚写完、投影 fold 见 delete 时用）。 */
+export declare function findPausedByScheduleId(sessionId: string, scheduleId: string): PausedEntry | undefined;
+/** 写入/覆盖一条暂停留档。 */
+export declare function recordPaused(sessionId: string, entry: PausedEntry): void;
+/** 移除一条暂停留档；幂等。 */
+export declare function removePaused(sessionId: string, uid: string): void;
 /** 测试辅助：清空进程内缓存（不删文件）。 */
 export declare function resetCacheForTests(): void;

package/lib/types/presence.d.ts

@@ -19,21 +19,60 @@ export declare const PRESENCE_URGENT_WINDOW_MS: number;
 export interface PresenceScheduleLike {
     readonly scheduled_at?: string;
     readonly scheduledAt?: string;
+    /** `'paused'` 时该任务**没有排定的触发时刻**（冻结剩余秒数，等待恢复）。 */
+    readonly status?: string;
+    /** 暂停冻结的剩余秒数；仅在 `status === 'paused'` 时有意义。 */
+    readonly remaining_seconds?: number;
 }
 /** 由一组活动任务归纳的 badge 概要。 */
 export interface PresenceSummary {
-    /** 可解析触发时刻的活动任务数量。 */
+    /** 计入提醒数量的任务数（**含**暂停项）。 */
     readonly count: number;
-    /** 最早触发时刻（epoch ms）；全部不可解析时缺省。 */
+    /** 最早触发时刻（epoch ms）；没有任何"会触发"的任务时缺省。 */
     readonly nextAt?: number;
+    /** 暂停中的任务数（用于文案区分「已冻结」与「等待发送」）。 */
+    readonly pausedCount: number;
 }
 /**
- * 归纳：取最早触发时刻 + 可解析数量。`every` 类任务在投影里携带推进后的
- * `scheduledAt`（下次触发点），与一次性任务同构参与排序。
+ * 归纳：取最早触发时刻 + 任务数量。
+ *
+ * ⚠️ **暂停项不得参与 `nextAt`**（这是一个真实缺陷的根因）。暂停 = 日志 delete +
+ * sidecar 留档；wire 里的 `scheduled_at` 是 `originalScheduledAt`（**原目标时刻**），
+ * 而该时刻在暂停时通常已成过去。若照常参与取最小值，侧栏会算出 `nextAt <= now`
+ * → 显示「有 N 条定时提醒已到期，等待发送」，但这其实是一条**已冻结、不会触发**的
+ * 提醒，用户看到的是自相矛盾的状态（实测复现）。
+ *
+ * 正确语义：暂停项**计入 `count`**（它确实是待办提醒），但**不参与 `nextAt`**
+ * ——它没有排定的触发时刻，只在恢复后才重新拥有。
+ *
+ * 全部都是暂停项时 `nextAt` 为 undefined：调用方据此显示中性的「已暂停」而非
+ * 「已到期」或"下次 X 分后"。
  */
 export declare function summarizeSchedules(schedules: readonly PresenceScheduleLike[] | undefined): PresenceSummary;
 /** 由当前时刻判定 badge 状态。 */
 export declare function badgeStateFor(nextAt: number | undefined, now: number): PresenceBadgeState;
+/**
+ * 悬浮卡片状态行的完整文案（与宿主 `.hoverStatus` 行同构：一个状态点 + 一句
+ * 描述）。宿主的状态链对定时任务无感知，本插件**只追加**这样一行，不改写也
+ * 不替换宿主已有的 `空闲` / `进行中` 等行，因此既有状态优先级天然不变。
+ *
+ * @param entry - 该会话的定时概要（调用方保证 count > 0）。
+ * @param now - 当前时刻（epoch ms），用于判定 overdue 与相对时间。
+ * @param labels - 相对时间文案槽位。
+ * @param strings - 当前语言的字典。
+ * @param formatHhmm - 时钟面格式化（注入以便单测）。
+ * @param formatDate - 日期面格式化（注入以便单测）。
+ * @returns 状态文案 + 视觉状态（`done` 为中性信息态，与宿主同款状态点）。
+ */
+export declare function hoverScheduleStatus(entry: PresenceSummary, now: number, labels: RelativeFireLabels, strings: {
+    readonly hoverScheduleStatus: string;
+    readonly hoverScheduleOverdue: string;
+    /** 全部任务暂停时的文案；缺省回退到 overdue 文案，保持向后兼容。 */
+    readonly hoverSchedulePaused?: string;
+}, formatHhmm: (epoch: number) => string, formatDate: (epoch: number) => string): {
+    readonly label: string;
+    readonly tone: PresenceBadgeState;
+};
 /** 相对触发时间的文案槽位（由调用方按语言准备；时间串经 formatHhmm 注入）。 */
 export interface RelativeFireLabels {
     /** ≤1 分钟：即将发送。 */