@zhin.js/plugin-reminder 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# 持久提醒
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+使用 Plugin Runtime、持久状态与精确 DeliveryTarget 的个人提醒插件。任务绑定创建者和原会话；群聊其他用户、其他 Endpoint、频道父级或线程不能查看和取消。
+
+## 安装
+
+```bash
+pnpm add @zhin.js/command @zhin.js/schedule-feature
+zhin install @zhin.js/plugin-reminder
+```
+
+在项目根 `package.json#zhin` 合并以下挂载（保留已有条目）：
+
+```json
+{
+  "features": [{ "package": "@zhin.js/schedule-feature" }],
+  "plugins": [
+    { "package": "@zhin.js/plugin-reminder", "instanceKey": "reminder" }
+  ]
+}
+```
+
+根应用从 `zhin.js` 继承 Stable Command Feature；上面的直接 Command 依赖确保子插件解析到同一物理 provider。安装命令会添加插件挂载；手动维护时同样使用上述清单。启用支持持久状态原子更新的 Database Host。缺少持久数据库或精确目标投递 Host 时启动明确失败，不会降级为内存保存。SQLite、PostgreSQL、MySQL 的状态能力由框架 Database Host 提供；本插件回归使用真实 SQLite 文件。
+
+```yaml
+plugins:
+  reminder:
+    timezone: UTC
+    maxTasks: 20
+    maxTasksPerSender: 10
+    batchSize: 5
+    missedGraceSeconds: 15
+```
+
+配置统一由 Schema 校验；修改仅重载插件。timezone 是有效的 IANA 时区，只影响显示，默认 UTC。绝对时间必须显式包含 `Z` 或 `±hh:mm`，没有隐式本地时间转换。多个实例应显式配置不同的 `commandNamespace`，例如 `personal` 和 `work`；使用时在指令前添加对应命名空间。Endpoint 的 `commandPrefix` 决定指令前缀。
+
+## 指令
+
+以下示例省略 Endpoint 前缀与插件显式命名空间。各指令的 `--help` 提供参数说明。
+
+```text
+remind after 600 十分钟后休息
+remind at 2027-01-01T09:00:00+08:00 新年会议
+remind every 3600 喝水
+remind list
+remind cancel <任务 ID>
+```
+
+延迟是 1 秒至一年；周期是 60 秒至一年；内容是 1–500 字符。时间必须在未来一年内。指令权限经过框架 PermissionHost；插件没有额外权限旁路或取消其他发送者任务的管理员接口。
+
+## 执行与恢复
+
+`schedules/poll/index.ts` 每 5 秒通过当前 owner 的 ScheduleContext 解析服务，没有队列积压时通常在目标时间后 5 秒内扫描；平台投递耗时不计入此保证。服务不保存 Message、客户端或旧 snapshot。周期是固定秒数的间隔，不是墙上时钟的 cron，不受夏令时跳变影响。
+
+- 一次性任务：停机错过后恢复时补发至多一次。
+- 周期任务：超过 `missedGraceSeconds` 的轮次跳过，推进至未来，停机后不连发遗漏轮次。
+- 每轮最多投递 `batchSize` 条，逐条执行；同一服务扫描不重叠，持久原子 claim 防止同一任务并发领取。
+- 投递前持久记录为“投递中或未确认”。平台返回非空消息 ID 才记为完成；明确未发送或拒绝会停止任务。未知错误、没有 ID、进程在 claim 后崩溃、投递成功但状态落盘失败都保持未确认，**不自动重试**。用户核对原会话后取消或重新创建。
+- 取消不撤销已开始的外部投递。完成回写不会覆盖在途取消。重启或热重载保留未知状态，避免重复消息。
+
+这是保守的至多一次尝试策略，不是 outbox 或 exactly-once 投递。claim 后、实际发送前崩溃可能丢失一次提醒；周期任务遇未知投递也会暂停，需要用户处理。
+
+`maxTasks` 限制新建时每实例的活跃任务（待触发或未确认），不是降低配置后立即裁剪的记录总数；状态硬上限为 32 条记录，每发送者在会话内最多 10 条活跃任务；总编码大小限制为 60 KiB。完成或取消记录在新建任务时优先淘汰，未知任务持续占用限额，直到显式取消。减少配置上限不删除既有活跃任务，只限制继续创建。
+
+## 显式本地检查
+
+插件通过正式 `pluginVerificationToken` 暴露 `local-state` 检查。inspect/checks 只显示副作用，只有用户显式 verify 才写入、读回并删除独立探针键。探针 TTL 为 60 秒。验证被取消或热重载打断时，清理拒绝会使检查明确失败，短 TTL 使残留探针失效；不能将被打断的旧代结果视为当前验证通过。检查不创建可投递任务、不发送消息，仅证明当前 owner 的数据库状态可读写；不证明平台投递或调度健康。
+
+## 目录
+
+```text
+plugin.ts                 # Schema、owner 服务资源及显式检查
+src/                      # 服务、状态契约与指令 helper
+commands/remind/*/index.ts # 集中参数声明与标准 Command dispatcher
+schedules/poll/index.ts   # 正式 Schedule Feature 入口
+```
+
+## Agent 工具与技能
+
+启用 `@zhin.js/tool` 与 `@zhin.js/skill` Feature 后，本插件提供技能 `reminder` 与工具：
+
+| 工具              | 说明                                                              |
+| ----------------- | ----------------------------------------------------------------- |
+| `reminder_create` | 创建一次性（`after` / `at`）或周期（`every_seconds`）提醒；需批准 |
+| `reminder_list`   | 列出当前发送者在当前会话的提醒                                    |
+| `reminder_cancel` | 按 id 取消；需批准                                                |
+
+与原生 `schedule_add` 的区别：本插件到点**向会话发送提醒文案**；`schedule_*` 到点**再次唤醒 Agent**（可带 cron / 工作日等）。绝对时间仍须带 `Z` 或 `±hh:mm`。

package/commands/remind/after/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from "../../../lib/runtime.js";
+import { reminderActor, replyReminder } from "../../../lib/caller.js";
+import { MAX_DELAY_SECONDS } from "../../../lib/service.js";
+export default defineCommand({
+    description: '创建一次性延迟提醒',
+    params: { seconds: { type: 'integer', min: 1, max: MAX_DELAY_SECONDS, description: '延迟秒数' }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+    async execute({ input, params, use }) {
+        return replyReminder(async () => {
+            const service = use(reminderServiceToken);
+            const task = await service.add(reminderActor(input), params.text, Date.now() + params.seconds * 1000, null);
+            return `已创建提醒\n${service.describe(task)}`;
+        });
+    },
+});

package/commands/remind/after/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from '../../../src/runtime.js';
+import { reminderActor, replyReminder } from '../../../src/caller.js';
+import { MAX_DELAY_SECONDS } from '../../../src/service.js';
+
+export default defineCommand({
+  description: '创建一次性延迟提醒',
+  params: { seconds: { type: 'integer', min: 1, max: MAX_DELAY_SECONDS, description: '延迟秒数' }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+  async execute({ input, params, use }) {
+    return replyReminder(async () => {
+      const service = use(reminderServiceToken);
+      const task = await service.add(reminderActor(input), params.text, Date.now() + params.seconds * 1000, null);
+      return `已创建提醒\n${service.describe(task)}`;
+    });
+  },
+});

package/commands/remind/at/index.js

@@ -0,0 +1,22 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from "../../../lib/runtime.js";
+import { reminderActor, replyReminder } from "../../../lib/caller.js";
+import { parseReminderInstant } from "../../../lib/service.js";
+export default defineCommand({
+    description: '创建绝对时间提醒',
+    params: { time: { type: 'string', description: '包含 Z 或 ±hh:mm 的 ISO 时间', validate: (value) => { try {
+                parseReminderInstant(String(value));
+                return true;
+            }
+            catch {
+                return '绝对时间须为有效的 ISO 时间并包含时区 offset';
+            } } }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+    async execute({ input, params, use }) {
+        return replyReminder(async () => {
+            const service = use(reminderServiceToken);
+            const task = await service.add(reminderActor(input), params.text, parseReminderInstant(params.time), null);
+            return `已创建提醒\n${service.describe(task)}`;
+        });
+    },
+});

package/commands/remind/at/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand, type CommandParameterValue } from 'zhin.js/command';
+import { reminderServiceToken } from '../../../src/runtime.js';
+import { reminderActor, replyReminder } from '../../../src/caller.js';
+import { parseReminderInstant } from '../../../src/service.js';
+
+export default defineCommand({
+  description: '创建绝对时间提醒',
+  params: { time: { type: 'string', description: '包含 Z 或 ±hh:mm 的 ISO 时间', validate: (value: CommandParameterValue) => { try { parseReminderInstant(String(value)); return true; } catch { return '绝对时间须为有效的 ISO 时间并包含时区 offset'; } } }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+  async execute({ input, params, use }) {
+    return replyReminder(async () => {
+      const service = use(reminderServiceToken);
+      const task = await service.add(reminderActor(input), params.text, parseReminderInstant(params.time), null);
+      return `已创建提醒\n${service.describe(task)}`;
+    });
+  },
+});

package/commands/remind/cancel/index.js

@@ -0,0 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from "../../../lib/runtime.js";
+import { reminderActor, replyReminder } from "../../../lib/caller.js";
+export default defineCommand({
+    description: '取消本人在当前会话的提醒',
+    params: { id: { type: 'string', description: 'remind list 中的任务 ID' } },
+    async execute({ input, params, use }) {
+        return replyReminder(async () => await use(reminderServiceToken).cancel(reminderActor(input), params.id) ? '已取消提醒；已经开始的投递无法撤销' : '未找到你在此会话的提醒');
+    },
+});

package/commands/remind/cancel/index.ts

@@ -0,0 +1,11 @@
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from '../../../src/runtime.js';
+import { reminderActor, replyReminder } from '../../../src/caller.js';
+
+export default defineCommand({
+  description: '取消本人在当前会话的提醒',
+  params: { id: { type: 'string', description: 'remind list 中的任务 ID' } },
+  async execute({ input, params, use }) {
+    return replyReminder(async () => await use(reminderServiceToken).cancel(reminderActor(input), params.id) ? '已取消提醒；已经开始的投递无法撤销' : '未找到你在此会话的提醒');
+  },
+});

package/commands/remind/every/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from "../../../lib/runtime.js";
+import { reminderActor, replyReminder } from "../../../lib/caller.js";
+import { MAX_DELAY_SECONDS } from "../../../lib/service.js";
+export default defineCommand({
+    description: '创建固定周期提醒',
+    params: { seconds: { type: 'integer', min: 60, max: MAX_DELAY_SECONDS, description: '周期秒数（至少 60）' }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+    async execute({ input, params, use }) {
+        return replyReminder(async () => {
+            const service = use(reminderServiceToken);
+            const task = await service.add(reminderActor(input), params.text, Date.now() + params.seconds * 1000, params.seconds * 1000);
+            return `已创建周期提醒\n${service.describe(task)}`;
+        });
+    },
+});

package/commands/remind/every/index.ts

@@ -0,0 +1,16 @@
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from '../../../src/runtime.js';
+import { reminderActor, replyReminder } from '../../../src/caller.js';
+import { MAX_DELAY_SECONDS } from '../../../src/service.js';
+
+export default defineCommand({
+  description: '创建固定周期提醒',
+  params: { seconds: { type: 'integer', min: 60, max: MAX_DELAY_SECONDS, description: '周期秒数（至少 60）' }, text: { type: 'text', min: 1, max: 500, description: '提醒内容' } },
+  async execute({ input, params, use }) {
+    return replyReminder(async () => {
+      const service = use(reminderServiceToken);
+      const task = await service.add(reminderActor(input), params.text, Date.now() + params.seconds * 1000, params.seconds * 1000);
+      return `已创建周期提醒\n${service.describe(task)}`;
+    });
+  },
+});

package/commands/remind/list/index.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from "../../../lib/runtime.js";
+import { reminderActor, replyReminder } from "../../../lib/caller.js";
+export default defineCommand({
+    description: '查看本人在当前会话的提醒',
+    async execute({ input, use }) {
+        return replyReminder(async () => {
+            const service = use(reminderServiceToken);
+            const tasks = await service.list(reminderActor(input));
+            return tasks.length ? tasks.map(task => service.describe(task)).join('\n\n') : '你在此会话没有提醒任务';
+        });
+    },
+});

package/commands/remind/list/index.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from 'zhin.js/command';
+import { reminderServiceToken } from '../../../src/runtime.js';
+import { reminderActor, replyReminder } from '../../../src/caller.js';
+
+export default defineCommand({
+  description: '查看本人在当前会话的提醒',
+  async execute({ input, use }) {
+    return replyReminder(async () => {
+      const service = use(reminderServiceToken);
+      const tasks = await service.list(reminderActor(input));
+      return tasks.length ? tasks.map(task => service.describe(task)).join('\n\n') : '你在此会话没有提醒任务';
+    });
+  },
+});

package/lib/caller.d.ts

@@ -0,0 +1,5 @@
+import type { CommandMessage } from '@zhin.js/command';
+import { type ReminderActor } from './service.js';
+export declare function reminderActor(input: CommandMessage | undefined): ReminderActor;
+export declare function replyReminder(operation: () => Promise<string>): Promise<string>;
+//# sourceMappingURL=caller.d.ts.map

package/lib/caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.d.ts","sourceRoot":"","sources":["../src/caller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEtE,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,aAAa,CAG9E;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAGrF"}

package/lib/caller.js

@@ -0,0 +1,18 @@
+import { createDeliveryTarget } from 'zhin.js';
+import { ReminderInputError } from './service.js';
+export function reminderActor(input) {
+    if (!input?.sender?.id)
+        throw new ReminderInputError('提醒指令需要真实会话和发送者');
+    return { senderId: input.sender.id, target: createDeliveryTarget(input) };
+}
+export async function replyReminder(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof ReminderInputError)
+            return error.message;
+        throw error;
+    }
+}
+//# sourceMappingURL=caller.js.map

package/lib/caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.js","sourceRoot":"","sources":["../src/caller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAsB,MAAM,cAAc,CAAC;AAEtE,MAAM,UAAU,aAAa,CAAC,KAAiC;IAC7D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAAE,MAAM,IAAI,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACvE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAAgC;IAClE,IAAI,CAAC;QAAC,OAAO,MAAM,SAAS,EAAE,CAAC;IAAC,CAAC;IACjC,OAAO,KAAK,EAAE,CAAC;QAAC,IAAI,KAAK,YAAY,kBAAkB;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC;QAAC,MAAM,KAAK,CAAC;IAAC,CAAC;AAC/F,CAAC"}

package/lib/config.d.ts

@@ -0,0 +1,17 @@
+import { Schema } from 'zhin.js';
+export declare const reminderConfig: Schema<Schema.InputRecord<{
+    timezone: Schema<string, string> & Schema.Present;
+    maxTasks: Schema<number, number> & Schema.Present;
+    maxTasksPerSender: Schema<number, number> & Schema.Present;
+    batchSize: Schema<number, number> & Schema.Present;
+    missedGraceSeconds: Schema<number, number> & Schema.Present;
+}>, {
+    timezone: string;
+    maxTasks: number;
+    maxTasksPerSender: number;
+    batchSize: number;
+    missedGraceSeconds: number;
+} & {}>;
+export type ReminderConfig = Schema.Output<typeof reminderConfig>;
+export declare function assertReminderTimezone(timezone: string): void;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,eAAO,MAAM,cAAc;;;;;;;;;;;;OAMzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAElE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG7D"}

package/lib/config.js

@@ -0,0 +1,17 @@
+import { Schema } from 'zhin.js';
+export const reminderConfig = Schema.object({
+    timezone: Schema.string().default('UTC').description('显示提醒时间的 IANA 时区；绝对时间仍必须提供 ISO offset').effect('reload'),
+    maxTasks: Schema.number().min(1).max(32).step(1).default(20).description('每个插件实例新建时允许的活跃任务上限（待触发或未确认）；降低上限不删除既有任务').effect('reload'),
+    maxTasksPerSender: Schema.number().min(1).max(10).step(1).default(10).description('同一发送者在同一会话的任务上限').effect('reload'),
+    batchSize: Schema.number().min(1).max(5).step(1).default(5).description('每次扫描最多投递的任务数').effect('reload'),
+    missedGraceSeconds: Schema.number().min(5).max(60).step(1).default(15).description('周期轮次超过此延迟后跳过；停机期间不补历史轮次').effect('reload'),
+});
+export function assertReminderTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('zh-CN', { timeZone: timezone }).format(0);
+    }
+    catch {
+        throw new TypeError(`提醒 timezone 必须是有效的 IANA 时区：${timezone}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,sCAAsC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC7G,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,yCAAyC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IACpI,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IACrH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IACxG,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;CAC/H,CAAC,CAAC;AAIH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,CAAC;QAAC,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAAC,CAAC;IAC3E,MAAM,CAAC;QAAC,MAAM,IAAI,SAAS,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;IAAC,CAAC;AAC1E,CAAC"}

package/lib/duration.d.ts

@@ -0,0 +1,2 @@
+export declare function parseRelativeDelayMs(value: string): number;
+//# sourceMappingURL=duration.d.ts.map

package/lib/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAGA,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA2B1D"}

package/lib/duration.js

@@ -0,0 +1,31 @@
+/** Relative durations for Agent tools: `10m`, `2h`, `1d`, or plain seconds. */
+import { ReminderInputError } from "./service.js";
+export function parseRelativeDelayMs(value) {
+    const text = value.trim().toLowerCase();
+    if (/^\d+$/.test(text)) {
+        const seconds = Number(text);
+        if (!Number.isSafeInteger(seconds) || seconds < 1) {
+            throw new ReminderInputError("延迟秒数无效");
+        }
+        return seconds * 1000;
+    }
+    const match = /^(\d+)\s*(s|m|h|d|秒|分|分钟|小时|天)$/u.exec(text);
+    if (!match) {
+        throw new ReminderInputError("时长格式无效（示例：600、10m、2h、1d）");
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    const factor = {
+        s: 1000,
+        秒: 1000,
+        m: 60_000,
+        分: 60_000,
+        分钟: 60_000,
+        h: 3_600_000,
+        小时: 3_600_000,
+        d: 86_400_000,
+        天: 86_400_000,
+    }[unit];
+    return amount * factor;
+}
+//# sourceMappingURL=duration.js.map

package/lib/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,OAAO,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,MAAM,KAAK,GAAG,kCAAkC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAAC,0BAA0B,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACvB,MAAM,MAAM,GAAG;QACb,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,MAAM;QACT,EAAE,EAAE,MAAM;QACV,CAAC,EAAE,SAAS;QACZ,EAAE,EAAE,SAAS;QACb,CAAC,EAAE,UAAU;QACb,CAAC,EAAE,UAAU;KACd,CAAC,IAAI,CAAE,CAAC;IACT,OAAO,MAAM,GAAG,MAAM,CAAC;AACzB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { reminderConfig, type ReminderConfig } from "./config.js";
+export { reminderServiceToken } from "./runtime.js";
+export { reminderActorFromTool, toolDeliveryTarget } from "./tool-actor.js";
+export { parseRelativeDelayMs } from "./duration.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/lib/index.js

@@ -0,0 +1,5 @@
+export { reminderConfig } from "./config.js";
+export { reminderServiceToken } from "./runtime.js";
+export { reminderActorFromTool, toolDeliveryTarget } from "./tool-actor.js";
+export { parseRelativeDelayMs } from "./duration.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/lib/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { ReminderService } from './service.js';
+export declare const reminderServiceToken: import("zhin.js").Token<ReminderService>;
+//# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,eAAO,MAAM,oBAAoB,0CAA6F,CAAC"}

package/lib/runtime.js

@@ -0,0 +1,3 @@
+import { createToken } from 'zhin.js';
+export const reminderServiceToken = createToken('zhin.reminder.service', 'Owner-scoped persistent reminders');
+//# sourceMappingURL=runtime.js.map

package/lib/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAkB,uBAAuB,EAAE,mCAAmC,CAAC,CAAC"}

package/lib/service.d.ts

@@ -0,0 +1,42 @@
+import { type DeliveryTarget, type OutboundHost, type PluginStateStore } from 'zhin.js';
+import type { ReminderConfig } from './config.js';
+export declare const REMINDER_STATE_KEY = "reminders/v1";
+export declare const MAX_DELAY_SECONDS: number;
+export declare class ReminderInputError extends Error {
+}
+type TaskStatus = 'pending' | 'unknown' | 'delivered' | 'failed' | 'cancelled';
+export type ReminderActor = {
+    readonly senderId: string;
+    readonly target: DeliveryTarget;
+};
+export type ReminderTask = {
+    readonly id: string;
+    readonly senderId: string;
+    readonly target: DeliveryTarget;
+    readonly text: string;
+    readonly createdAt: number;
+    readonly nextRunAt: number;
+    readonly intervalMs: number | null;
+    readonly status: TaskStatus;
+    readonly claimId: string | null;
+    readonly lastRunAt: number | null;
+    readonly detail: string;
+};
+export type ReminderBook = {
+    readonly version: 1;
+    readonly tasks: readonly ReminderTask[];
+};
+/** Generation-owned worker; saved state contains plain identities, never live objects. */
+export declare class ReminderService {
+    #private;
+    constructor(state: PluginStateStore, outbound: OutboundHost, config: ReminderConfig);
+    stop(): void;
+    add(actor: ReminderActor, text: string, at: number, intervalMs: number | null): Promise<ReminderTask>;
+    list(actor: ReminderActor): Promise<readonly ReminderTask[]>;
+    cancel(actor: ReminderActor, id: string): Promise<boolean>;
+    tick(): Promise<void>;
+    describe(task: ReminderTask): string;
+}
+export declare function parseReminderInstant(value: string): number;
+export {};
+//# sourceMappingURL=service.d.ts.map

package/lib/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AACpD,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD,KAAK,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC/E,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAC3F,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC7F,CAAC;AACF,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,CAAC;AAE5F,0FAA0F;AAC1F,qBAAa,eAAe;;gBAOd,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc;IAMnF,IAAI,IAAI,IAAI;IAEN,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBrG,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAM5D,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C3B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;CAQrC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU1D"}