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

package/lib/service.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+import { createDeliveryTarget } from 'zhin.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+export const REMINDER_STATE_KEY = 'reminders/v1';
+export const MAX_DELAY_SECONDS = 365 * 24 * 60 * 60;
+export class ReminderInputError extends Error {
+}
+/** Generation-owned worker; saved state contains plain identities, never live objects. */
+export class ReminderService {
+    #state;
+    #outbound;
+    #config;
+    #working = false;
+    #stopped = false;
+    constructor(state, outbound, config) {
+        this.#state = state;
+        this.#outbound = outbound;
+        this.#config = config;
+    }
+    stop() { this.#stopped = true; }
+    async add(actor, text, at, intervalMs) {
+        this.#assertLive();
+        assertActor(actor);
+        const now = Date.now();
+        if (!text.trim() || text.length > 500)
+            throw new ReminderInputError('提醒内容须为 1–500 个字符');
+        if (!Number.isSafeInteger(at) || at <= now || at - now > MAX_DELAY_SECONDS * 1000)
+            throw new ReminderInputError('提醒时间须在未来一年内');
+        if (intervalMs !== null && (!Number.isSafeInteger(intervalMs) || intervalMs < 60_000 || intervalMs > MAX_DELAY_SECONDS * 1000))
+            throw new ReminderInputError('周期须为 60 秒至一年');
+        const task = { id: randomUUID(), senderId: actor.senderId, target: createDeliveryTarget({ conversation: actor.target }),
+            text, createdAt: now, nextRunAt: at, intervalMs, status: 'pending', claimId: null, lastRunAt: null, detail: '' };
+        await this.#state.update(REMINDER_STATE_KEY, current => {
+            const book = readBook(current);
+            // Completed history is disposable; unconfirmed tasks require an explicit
+            // user decision and continue to count against the storage quota.
+            const active = book.tasks.filter(item => item.status === 'pending' || item.status === 'unknown');
+            if (active.length >= this.#config.maxTasks)
+                throw new ReminderInputError('此插件实例的提醒数量已达上限，请先取消任务');
+            if (active.filter(item => sameActor(item, actor)).length >= this.#config.maxTasksPerSender)
+                throw new ReminderInputError('你在此会话的提醒数量已达上限，请先取消任务');
+            const historyLimit = Math.max(0, this.#config.maxTasks - active.length - 1);
+            const history = historyLimit > 0 ? book.tasks.filter(item => item.status !== 'pending' && item.status !== 'unknown').slice(-historyLimit) : [];
+            return boundedBook([...active, ...history, task]);
+        });
+        return task;
+    }
+    async list(actor) {
+        this.#assertLive();
+        assertActor(actor);
+        return readBook(await this.#state.get(REMINDER_STATE_KEY)).tasks.filter(item => sameActor(item, actor));
+    }
+    async cancel(actor, id) {
+        this.#assertLive();
+        assertActor(actor);
+        const book = await this.#state.update(REMINDER_STATE_KEY, current => ({ version: 1,
+            tasks: readBook(current).tasks.map(task => task.id === id && sameActor(task, actor)
+                ? { ...task, status: 'cancelled', detail: '用户取消；已经开始的投递无法撤销' } : task),
+        }));
+        return !!book?.tasks.some(task => task.id === id && sameActor(task, actor) && task.status === 'cancelled');
+    }
+    async tick() {
+        if (this.#working || this.#stopped)
+            return;
+        this.#working = true;
+        try {
+            for (let count = 0; count < this.#config.batchSize && !this.#stopped; count++) {
+                const now = Date.now();
+                const claimId = randomUUID();
+                const book = await this.#state.update(REMINDER_STATE_KEY, current => {
+                    let claimed = false;
+                    return { version: 1, tasks: readBook(current).tasks.map(task => {
+                            if (task.status !== 'pending' || task.nextRunAt > now)
+                                return task;
+                            if (task.intervalMs !== null && now - task.nextRunAt > this.#config.missedGraceSeconds * 1000) {
+                                return { ...task, nextRunAt: nextPeriodicTime(task.nextRunAt, task.intervalMs, now), detail: '已跳过错过的周期轮次' };
+                            }
+                            if (claimed)
+                                return task;
+                            claimed = true;
+                            // Persist the conservative disposition before touching the external
+                            // platform. A crash here cannot cause an automatic duplicate send.
+                            return { ...task, status: 'unknown', claimId, lastRunAt: now, detail: '投递中或未确认；不会自动重试' };
+                        }) };
+                });
+                const task = book?.tasks.find(item => item.claimId === claimId);
+                if (!task || this.#stopped)
+                    break;
+                let status = 'unknown';
+                let detail = '平台未返回确认的消息 ID；不会自动重试';
+                try {
+                    const id = await this.#outbound.sendTarget(task.target, `⏰ 提醒：${task.text}`);
+                    if (id) {
+                        status = task.intervalMs === null ? 'delivered' : 'pending';
+                        detail = '已确认投递';
+                    }
+                }
+                catch (error) {
+                    if (error instanceof EndpointDeliveryError && error.disposition !== 'unknown') {
+                        status = 'failed';
+                        detail = `投递失败：${error.code}；任务已停止`;
+                    }
+                    else
+                        detail = '投递结果未确认；请核对目标会话后取消或重新创建';
+                }
+                await this.#state.update(REMINDER_STATE_KEY, current => ({ version: 1,
+                    tasks: readBook(current).tasks.map(item => item.id === task.id && item.claimId === claimId && item.status === 'unknown'
+                        ? { ...item, status, detail, ...(status === 'pending' && task.intervalMs !== null
+                                ? { nextRunAt: nextPeriodicTime(task.nextRunAt, task.intervalMs, Date.now()) } : {}) } : item),
+                }));
+            }
+        }
+        finally {
+            this.#working = false;
+        }
+    }
+    describe(task) {
+        const date = new Intl.DateTimeFormat('zh-CN', { timeZone: this.#config.timezone, dateStyle: 'short', timeStyle: 'medium' }).format(task.nextRunAt);
+        const state = { pending: '待触发', unknown: '投递中或未确认', delivered: '已完成', failed: '投递失败', cancelled: '已取消' }[task.status];
+        return `${task.id} | ${state} | ${date} (${this.#config.timezone})${task.intervalMs === null ? '' : ` | 每 ${task.intervalMs / 1000} 秒`}`
+            + `\n${task.text}${task.detail ? `\n${task.detail}` : ''}`;
+    }
+    #assertLive() { if (this.#stopped)
+        throw new Error('提醒服务属于已停止的插件实例'); }
+}
+export function parseReminderInstant(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/u.test(value))
+        throw new TypeError('绝对时间须为带 Z 或 ±hh:mm 的 ISO 时间，例如 2026-10-14T09:00:00+08:00');
+    const [year = 0, month = 0, day = 0, hour = 0, minute = 0, second = 0] = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?/u).slice(1).map(item => Number(item ?? 0));
+    const calendar = new Date(0);
+    calendar.setUTCFullYear(year, month, 0);
+    const daysInMonth = calendar.getUTCDate();
+    if (month < 1 || month > 12 || day < 1 || day > daysInMonth || hour > 23 || minute > 59 || second > 59)
+        throw new TypeError('提醒时间无效');
+    const time = Date.parse(value);
+    if (!Number.isSafeInteger(time))
+        throw new TypeError('提醒时间无效');
+    return time;
+}
+function nextPeriodicTime(from, interval, now) {
+    return from + (Math.floor((now - from) / interval) + 1) * interval;
+}
+function sameActor(task, actor) {
+    return task.senderId === actor.senderId && JSON.stringify(task.target) === JSON.stringify(createDeliveryTarget({ conversation: actor.target }));
+}
+function readBook(value) {
+    if (value === undefined)
+        return { version: 1, tasks: [] };
+    try {
+        if (value.version !== 1 || !Array.isArray(value.tasks) || value.tasks.length > 32)
+            throw new Error('Invalid book');
+        for (const task of value.tasks) {
+            if (!task || typeof task.id !== 'string' || !task.id || typeof task.senderId !== 'string' || !task.senderId
+                || typeof task.text !== 'string' || !task.text.trim() || task.text.length > 500
+                || !Number.isSafeInteger(task.createdAt) || !Number.isSafeInteger(task.nextRunAt)
+                || (task.intervalMs !== null && (!Number.isSafeInteger(task.intervalMs) || task.intervalMs < 60_000 || task.intervalMs > MAX_DELAY_SECONDS * 1000))
+                || !['pending', 'unknown', 'delivered', 'failed', 'cancelled'].includes(task.status)
+                || (task.claimId !== null && typeof task.claimId !== 'string')
+                || (task.lastRunAt !== null && !Number.isSafeInteger(task.lastRunAt)) || typeof task.detail !== 'string')
+                throw new Error('Invalid task');
+            createDeliveryTarget({ conversation: task.target });
+        }
+        return boundedBook(value.tasks);
+    }
+    catch {
+        throw new Error('提醒持久状态格式无效，已停止投递');
+    }
+}
+function boundedBook(tasks) {
+    const book = { version: 1, tasks };
+    if (new TextEncoder().encode(JSON.stringify(book)).byteLength > 60 * 1024)
+        throw new ReminderInputError('提醒存储达到大小上限，请先取消旧任务');
+    return book;
+}
+function assertActor(actor) {
+    if (!actor.senderId)
+        throw new ReminderInputError('提醒需要真实发送者');
+    createDeliveryTarget({ conversation: actor.target });
+}
+//# sourceMappingURL=service.js.map

package/lib/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/lib/tool-actor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve a ReminderActor from an Agent Tool invocation (IM origin only).
+ */
+import { type DeliveryTarget } from "zhin.js";
+import { adapterFeatureId } from "zhin.js/adapter";
+import type { ToolInvocationOrigin } from "@zhin.js/tool";
+import { type ReminderActor } from "./service.js";
+export interface ToolActorContext {
+    readonly origin: ToolInvocationOrigin;
+    readonly principal: Readonly<{
+        subjectId: string;
+        roles: readonly string[];
+    }>;
+    project<T>(feature: typeof adapterFeatureId): T;
+}
+/** Build the exact conversation DeliveryTarget for the current tool turn. */
+export declare function toolDeliveryTarget(context: ToolActorContext): DeliveryTarget;
+/** Actor bound to the invoking principal and the current IM conversation. */
+export declare function reminderActorFromTool(context: ToolActorContext): ReminderActor;
+//# sourceMappingURL=tool-actor.d.ts.map

package/lib/tool-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-actor.d.ts","sourceRoot":"","sources":["../src/tool-actor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAqB,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC9E,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,gBAAgB,GAAG,CAAC,CAAC;CACjD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CA2B5E;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,GACxB,aAAa,CAIf"}

package/lib/tool-actor.js

@@ -0,0 +1,38 @@
+/**
+ * Resolve a ReminderActor from an Agent Tool invocation (IM origin only).
+ */
+import { createDeliveryTarget } from "zhin.js";
+import { adapterFeatureId } from "zhin.js/adapter";
+import { ReminderInputError } from "./service.js";
+/** Build the exact conversation DeliveryTarget for the current tool turn. */
+export function toolDeliveryTarget(context) {
+    const origin = context.origin;
+    if (origin.kind !== "im") {
+        throw new ReminderInputError("提醒工具只能在聊天会话中使用（不能用于 http/schedule 等来源）");
+    }
+    const index = context.project(adapterFeatureId);
+    const matches = index
+        .describe()
+        .filter((endpoint) => (String(endpoint.id) === origin.endpoint ||
+        endpoint.name === origin.endpoint) &&
+        index.clientAdapter(endpoint.id) === origin.platform);
+    if (matches.length !== 1) {
+        throw new ReminderInputError("无法确定当前会话所属的机器人账号");
+    }
+    return createDeliveryTarget({
+        conversation: {
+            endpoint: { id: String(matches[0].id), adapter: origin.platform },
+            kind: origin.scope,
+            id: origin.sceneId,
+            ...(origin.threadId !== undefined ? { threadId: origin.threadId } : {}),
+        },
+    });
+}
+/** Actor bound to the invoking principal and the current IM conversation. */
+export function reminderActorFromTool(context) {
+    const senderId = context.principal.subjectId?.trim();
+    if (!senderId)
+        throw new ReminderInputError("提醒工具需要真实发送者");
+    return { senderId, target: toolDeliveryTarget(context) };
+}
+//# sourceMappingURL=tool-actor.js.map

package/lib/tool-actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-actor.js","sourceRoot":"","sources":["../src/tool-actor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,oBAAoB,EAAuB,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAqB,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,kBAAkB,EAAsB,MAAM,cAAc,CAAC;AAQtE,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAAC,OAAyB;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,kBAAkB,CAC1B,wCAAwC,CACzC,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAe,gBAAgB,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,KAAK;SAClB,QAAQ,EAAE;SACV,MAAM,CACL,CAAC,QAAQ,EAAE,EAAE,CACX,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,QAAQ;QACtC,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,QAAQ,CAAC;QACpC,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,QAAQ,CACvD,CAAC;IACJ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,kBAAkB,CAAC,kBAAkB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,oBAAoB,CAAC;QAC1B,YAAY,EAAE;YACZ,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE;YAClE,IAAI,EAAE,MAAM,CAAC,KAAK;YAClB,EAAE,EAAE,MAAM,CAAC,OAAO;YAClB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE;KACF,CAAC,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CACnC,OAAyB;IAEzB,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACrD,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;AAC3D,CAAC"}

package/package.json

@@ -1,6 +1,105 @@
 {
   "name": "@zhin.js/plugin-reminder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Persistent personal reminders for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "commands",
+    "lib",
+    "plugin.js",
+    "schedules",
+    "skills",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/im-contract": "1.1.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "zhin.js": "^1.1.7",
+    "@zhin.js/command": "^1.1.5",
+    "@zhin.js/schedule-feature": "^1.1.3",
+    "@zhin.js/tool": "^1.1.4",
+    "@zhin.js/skill": "^1.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/schedule-feature": {
+      "optional": true
+    },
+    "@zhin.js/tool": {
+      "optional": true
+    },
+    "@zhin.js/skill": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "zhin.js": "1.1.7",
+    "@zhin.js/tool": "1.1.4",
+    "@zhin.js/schedule-feature": "1.1.3",
+    "@zhin.js/skill": "1.1.4"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/utils/reminder"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/schedule-feature",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc -p tsconfig.check.json",
+    "test": "vitest run --root ../../.. plugins/utils/reminder/tests"
+  }
 }

package/plugin.js

@@ -0,0 +1,41 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { databaseHostToken, definePlugin, outboundHostToken } from 'zhin.js';
+import { pluginVerificationToken } from 'zhin.js/plugin-runtime';
+import { randomUUID } from 'node:crypto';
+import { assertReminderTimezone, reminderConfig } from "./lib/config.js";
+import { ReminderService } from "./lib/service.js";
+import { reminderServiceToken } from "./lib/runtime.js";
+export default definePlugin({
+    name: 'reminder', config: reminderConfig,
+    metadata: { displayName: '持久提醒' },
+    requires: [databaseHostToken, outboundHostToken],
+    setup(context) {
+        const config = context.config.get();
+        assertReminderTimezone(config.timezone);
+        const state = context.resources.use(databaseHostToken).state;
+        const outbound = context.resources.use(outboundHostToken);
+        if (!outbound.sendTarget)
+            throw new Error('提醒需要支持精确 DeliveryTarget 的 Outbound Host');
+        const service = new ReminderService(state, outbound, config);
+        context.resources.provide(reminderServiceToken, service);
+        context.resources.provide(pluginVerificationToken, {
+            checks: () => [{ id: 'local-state', title: '持久状态读写检查', scope: 'local', effects: ['写入、读取并删除一个独立探针键；不创建提醒、不发送消息'] }],
+            async run(checkId) {
+                if (checkId !== 'local-state')
+                    throw new Error('Unknown reminder verification check');
+                const key = `verification/${randomUUID()}`;
+                try {
+                    await state.set(key, { probe: true }, { ttlMs: 60_000 });
+                    const value = await state.get(key);
+                    if (value?.probe !== true)
+                        throw new Error('持久状态读写结果不一致');
+                    return { status: 'passed', summary: '本地持久状态读写通过', evidence: ['独立探针写入并成功读回；清理后删除', '仅验证当前 owner 的数据库状态；不证明调度或平台投递健康'] };
+                }
+                finally {
+                    await state.delete(key);
+                }
+            },
+        });
+        return () => service.stop();
+    },
+});

package/schedules/poll/index.js

@@ -0,0 +1,8 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { reminderServiceToken } from "../../lib/runtime.js";
+export default defineSchedule({
+    cron: '*/5 * * * * *',
+    description: '扫描持久提醒；周期错过轮次不补发',
+    execute: context => context.use(reminderServiceToken).tick(),
+});

package/schedules/poll/index.ts

@@ -0,0 +1,8 @@
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { reminderServiceToken } from '../../src/runtime.js';
+
+export default defineSchedule({
+  cron: '*/5 * * * * *',
+  description: '扫描持久提醒；周期错过轮次不补发',
+  execute: context => context.use(reminderServiceToken).tick(),
+});

package/skills/reminder/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: reminder
+description: >-
+  在当前聊天会话创建/查看/取消个人提醒（到点向该会话发一条消息）。
+  Use when the user asks to be reminded later in this chat.
+  Do NOT use for agent re-invocation or workday/lunar cron jobs — those use schedule_add.
+  Triggers: 提醒我、定时、闹钟、过会儿叫我、取消提醒.
+keywords:
+  - 提醒
+  - reminder
+  - 定时
+  - 闹钟
+  - remind
+tags:
+  - reminder
+  - schedule
+tools:
+  - reminder_create
+  - reminder_list
+  - reminder_cancel
+---
+
+# 个人提醒
+
+## 何时使用本技能
+
+- 用户要「X 分钟后提醒我…」「每天每隔 N 秒…」（消息回到**当前会话**）
+- 查看或取消**自己**在当前会话的提醒
+
+## 何时改用 `schedule_add`
+
+- 需要到点**再次唤醒 Agent**（执行 prompt、跑工具），而不是只发一条提醒文案
+- 需要公历/农历 cron、工作日、节假日等日历语义（见原生 `schedule_*` 工具）
+
+## 工作流
+
+1. 确认提醒文案与时间。绝对时间必须带 `Z` 或 `±hh:mm`（例如 `2026-10-14T09:00:00+08:00`）。
+2. 一次性：`after`（`10m` / `600`）或 `at`；周期：`every_seconds`（≥ 60）。
+3. `reminder_create` / `reminder_cancel` 需要用户批准；创建前复述内容与时间。
+4. 用 `reminder_list` 核对；取消时带上 id。
+
+## 注意
+
+- 提醒绑定发送者 + 精确会话（含 endpoint / 线程）；别人看不见、取消不了你的任务。
+- 本插件没有 5 段 cron；周期只有固定间隔秒数。

package/skills/reminder/tools/reminder_cancel/index.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { replyReminder } from "../../../../lib/caller.js";
+import { reminderServiceToken } from "../../../../lib/runtime.js";
+import { reminderActorFromTool } from "../../../../lib/tool-actor.js";
+export default defineAgentTool({
+    description: "Cancel one of your reminders in the current chat by id from reminder_list.",
+    requiresApproval: "always",
+    tags: ["reminder"],
+    keywords: ["取消提醒", "cancel reminder"],
+    inputSchema: z.object({
+        id: z.string().min(1).describe("Reminder id"),
+    }),
+    async execute({ id }, context) {
+        return replyReminder(async () => {
+            const service = context.use(reminderServiceToken);
+            const ok = await service.cancel(reminderActorFromTool(context), id);
+            return ok
+                ? `已取消提醒 ${id}`
+                : `找不到提醒 ${id}（或不属于你在当前会话的任务）`;
+        });
+    },
+});

package/skills/reminder/tools/reminder_cancel/index.ts

@@ -0,0 +1,25 @@
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { replyReminder } from "../../../../src/caller.js";
+import { reminderServiceToken } from "../../../../src/runtime.js";
+import { reminderActorFromTool } from "../../../../src/tool-actor.js";
+
+export default defineAgentTool({
+  description:
+    "Cancel one of your reminders in the current chat by id from reminder_list.",
+  requiresApproval: "always",
+  tags: ["reminder"],
+  keywords: ["取消提醒", "cancel reminder"],
+  inputSchema: z.object({
+    id: z.string().min(1).describe("Reminder id"),
+  }),
+  async execute({ id }, context) {
+    return replyReminder(async () => {
+      const service = context.use(reminderServiceToken);
+      const ok = await service.cancel(reminderActorFromTool(context), id);
+      return ok
+        ? `已取消提醒 ${id}`
+        : `找不到提醒 ${id}（或不属于你在当前会话的任务）`;
+    });
+  },
+});

package/skills/reminder/tools/reminder_create/index.js

@@ -0,0 +1,57 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { replyReminder } from "../../../../lib/caller.js";
+import { parseRelativeDelayMs } from "../../../../lib/duration.js";
+import { reminderServiceToken } from "../../../../lib/runtime.js";
+import { ReminderInputError, parseReminderInstant, } from "../../../../lib/service.js";
+import { reminderActorFromTool } from "../../../../lib/tool-actor.js";
+export default defineAgentTool({
+    description: "Create a personal reminder that delivers a message back to the current chat. " +
+        "Use after (relative) or at (ISO with offset) for one-off; every_seconds for repeating. " +
+        "Do NOT use this for agent re-invocation jobs — use schedule_add instead.",
+    requiresApproval: "always",
+    tags: ["reminder"],
+    keywords: ["提醒", "reminder", "定时", "闹钟"],
+    inputSchema: z.object({
+        text: z.string().min(1).max(500).describe("Reminder message body"),
+        after: z.string().optional().describe("Relative delay: 600, 10m, 2h, 1d"),
+        at: z
+            .string()
+            .optional()
+            .describe("Absolute ISO time with Z or ±hh:mm, e.g. 2026-10-14T09:00:00+08:00"),
+        every_seconds: z
+            .number()
+            .int()
+            .min(60)
+            .max(365 * 24 * 60 * 60)
+            .optional()
+            .describe("Repeat interval in seconds (min 60). First fire is now+interval."),
+    }),
+    async execute(input, context) {
+        return replyReminder(async () => {
+            const modes = [
+                input.after,
+                input.at,
+                input.every_seconds !== undefined ? "every" : undefined,
+            ].filter(Boolean);
+            if (modes.length !== 1) {
+                throw new ReminderInputError("请在 after / at / every_seconds 中只选一种时间表达");
+            }
+            const service = context.use(reminderServiceToken);
+            const actor = reminderActorFromTool(context);
+            if (input.every_seconds !== undefined) {
+                const intervalMs = input.every_seconds * 1000;
+                const task = await service.add(actor, input.text, Date.now() + intervalMs, intervalMs);
+                return `已创建周期提醒\n${service.describe(task)}`;
+            }
+            if (input.after) {
+                const delayMs = parseRelativeDelayMs(input.after);
+                const task = await service.add(actor, input.text, Date.now() + delayMs, null);
+                return `已创建提醒\n${service.describe(task)}`;
+            }
+            const task = await service.add(actor, input.text, parseReminderInstant(input.at), null);
+            return `已创建提醒\n${service.describe(task)}`;
+        });
+    },
+});