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

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

@@ -0,0 +1,77 @@
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { replyReminder } from "../../../../src/caller.js";
+import { parseRelativeDelayMs } from "../../../../src/duration.js";
+import { reminderServiceToken } from "../../../../src/runtime.js";
+import {
+  ReminderInputError,
+  parseReminderInstant,
+} from "../../../../src/service.js";
+import { reminderActorFromTool } from "../../../../src/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({ text, after, at, every_seconds }, context) {
+    return replyReminder(async () => {
+      const modes = [
+        after,
+        at,
+        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 (every_seconds !== undefined) {
+        const intervalMs = every_seconds * 1000;
+        const task = await service.add(
+          actor,
+          text,
+          Date.now() + intervalMs,
+          intervalMs
+        );
+        return `已创建周期提醒\n${service.describe(task)}`;
+      }
+      if (after) {
+        const delayMs = parseRelativeDelayMs(after);
+        const task = await service.add(actor, text, Date.now() + delayMs, null);
+        return `已创建提醒\n${service.describe(task)}`;
+      }
+      const task = await service.add(
+        actor,
+        text,
+        parseReminderInstant(at!),
+        null
+      );
+      return `已创建提醒\n${service.describe(task)}`;
+    });
+  },
+});

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

@@ -0,0 +1,22 @@
+// 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: "List pending personal reminders for the current sender in the current chat.",
+    requiresApproval: "never",
+    tags: ["reminder"],
+    keywords: ["提醒列表", "list reminders"],
+    inputSchema: z.object({}),
+    async execute(_input, context) {
+        return replyReminder(async () => {
+            const service = context.use(reminderServiceToken);
+            const tasks = await service.list(reminderActorFromTool(context));
+            if (tasks.length === 0)
+                return "当前会话没有提醒";
+            return tasks.map((task) => service.describe(task)).join("\n---\n");
+        });
+    },
+});

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

@@ -0,0 +1,22 @@
+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:
+    "List pending personal reminders for the current sender in the current chat.",
+  requiresApproval: "never",
+  tags: ["reminder"],
+  keywords: ["提醒列表", "list reminders"],
+  inputSchema: z.object({}),
+  async execute(_input, context) {
+    return replyReminder(async () => {
+      const service = context.use(reminderServiceToken);
+      const tasks = await service.list(reminderActorFromTool(context));
+      if (tasks.length === 0) return "当前会话没有提醒";
+      return tasks.map((task) => service.describe(task)).join("\n---\n");
+    });
+  },
+});

package/src/caller.ts

@@ -0,0 +1,13 @@
+import { createDeliveryTarget } from 'zhin.js';
+import type { CommandMessage } from '@zhin.js/command';
+import { ReminderInputError, type ReminderActor } from './service.js';
+
+export function reminderActor(input: CommandMessage | undefined): ReminderActor {
+  if (!input?.sender?.id) throw new ReminderInputError('提醒指令需要真实会话和发送者');
+  return { senderId: input.sender.id, target: createDeliveryTarget(input) };
+}
+
+export async function replyReminder(operation: () => Promise<string>): Promise<string> {
+  try { return await operation(); }
+  catch (error) { if (error instanceof ReminderInputError) return error.message; throw error; }
+}

package/src/config.ts

@@ -0,0 +1,16 @@
+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 type ReminderConfig = Schema.Output<typeof reminderConfig>;
+
+export function assertReminderTimezone(timezone: string): void {
+  try { new Intl.DateTimeFormat('zh-CN', { timeZone: timezone }).format(0); }
+  catch { throw new TypeError(`提醒 timezone 必须是有效的 IANA 时区：${timezone}`); }
+}

package/src/duration.ts

@@ -0,0 +1,31 @@
+/** Relative durations for Agent tools: `10m`, `2h`, `1d`, or plain seconds. */
+import { ReminderInputError } from "./service.js";
+
+export function parseRelativeDelayMs(value: string): number {
+  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;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { reminderConfig, type ReminderConfig } from "./config.js";
+export { reminderServiceToken } from "./runtime.js";
+export { reminderActorFromTool, toolDeliveryTarget } from "./tool-actor.js";
+export { parseRelativeDelayMs } from "./duration.js";

package/src/runtime.ts

@@ -0,0 +1,4 @@
+import { createToken } from 'zhin.js';
+import type { ReminderService } from './service.js';
+
+export const reminderServiceToken = createToken<ReminderService>('zhin.reminder.service', 'Owner-scoped persistent reminders');

package/src/service.ts

@@ -0,0 +1,171 @@
+import { randomUUID } from 'node:crypto';
+import { createDeliveryTarget, type DeliveryTarget, type OutboundHost, type PluginStateStore } from 'zhin.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { ReminderConfig } from './config.js';
+
+export const REMINDER_STATE_KEY = 'reminders/v1';
+export const MAX_DELAY_SECONDS = 365 * 24 * 60 * 60;
+export 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 class ReminderService {
+  readonly #state: PluginStateStore;
+  readonly #outbound: OutboundHost;
+  readonly #config: ReminderConfig;
+  #working = false;
+  #stopped = false;
+
+  constructor(state: PluginStateStore, outbound: OutboundHost, config: ReminderConfig) {
+    this.#state = state;
+    this.#outbound = outbound;
+    this.#config = config;
+  }
+
+  stop(): void { this.#stopped = true; }
+
+  async add(actor: ReminderActor, text: string, at: number, intervalMs: number | null): Promise<ReminderTask> {
+    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: ReminderTask = { 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<ReminderBook>(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: ReminderActor): Promise<readonly ReminderTask[]> {
+    this.#assertLive();
+    assertActor(actor);
+    return readBook(await this.#state.get<ReminderBook>(REMINDER_STATE_KEY)).tasks.filter(item => sameActor(item, actor));
+  }
+
+  async cancel(actor: ReminderActor, id: string): Promise<boolean> {
+    this.#assertLive();
+    assertActor(actor);
+    const book = await this.#state.update<ReminderBook>(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(): Promise<void> {
+    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<ReminderBook>(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: TaskStatus = '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<ReminderBook>(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: ReminderTask): string {
+    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(): void { if (this.#stopped) throw new Error('提醒服务属于已停止的插件实例'); }
+}
+
+export function parseReminderInstant(value: string): number {
+  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: number, interval: number, now: number): number {
+  return from + (Math.floor((now - from) / interval) + 1) * interval;
+}
+function sameActor(task: ReminderTask, actor: ReminderActor): boolean {
+  return task.senderId === actor.senderId && JSON.stringify(task.target) === JSON.stringify(createDeliveryTarget({ conversation: actor.target }));
+}
+function readBook(value: ReminderBook | undefined): ReminderBook {
+  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: readonly ReminderTask[]): ReminderBook {
+  const book: ReminderBook = { version: 1, tasks };
+  if (new TextEncoder().encode(JSON.stringify(book)).byteLength > 60 * 1024) throw new ReminderInputError('提醒存储达到大小上限，请先取消旧任务');
+  return book;
+}
+
+function assertActor(actor: ReminderActor): void {
+  if (!actor.senderId) throw new ReminderInputError('提醒需要真实发送者');
+  createDeliveryTarget({ conversation: actor.target });
+}

package/src/tool-actor.ts

@@ -0,0 +1,52 @@
+/**
+ * Resolve a ReminderActor from an Agent Tool invocation (IM origin only).
+ */
+import { createDeliveryTarget, type DeliveryTarget } from "zhin.js";
+import { adapterFeatureId, type AdapterIndex } from "zhin.js/adapter";
+import type { ToolInvocationOrigin } from "@zhin.js/tool";
+import { ReminderInputError, 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 function toolDeliveryTarget(context: ToolActorContext): DeliveryTarget {
+  const origin = context.origin;
+  if (origin.kind !== "im") {
+    throw new ReminderInputError(
+      "提醒工具只能在聊天会话中使用（不能用于 http/schedule 等来源）"
+    );
+  }
+  const index = context.project<AdapterIndex>(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: ToolActorContext
+): ReminderActor {
+  const senderId = context.principal.subjectId?.trim();
+  if (!senderId) throw new ReminderInputError("提醒工具需要真实发送者");
+  return { senderId, target: toolDeliveryTarget(context) };
+}