@gakr-gakr/qqbot 0.1.0

package/src/engine/tools/remind-logic.ts

@@ -0,0 +1,377 @@
+/**
+ * QQBot reminder tool core logic.
+ * QQBot 提醒工具核心逻辑。
+ *
+ * Pure functions for time parsing, cron detection, job building,
+ * and remind execution. The framework registration shell
+ * (bridge/tools/remind.ts) delegates all business logic here and
+ * supplies request-level context fallbacks (`to`, `accountId`).
+ */
+
+/**
+ * Reminder tool input parameters.
+ * 提醒工具的输入参数。
+ */
+export interface RemindParams {
+  action: "add" | "list" | "remove";
+  content?: string;
+  to?: string;
+  time?: string;
+  timezone?: string;
+  name?: string;
+  jobId?: string;
+}
+
+/**
+ * Context supplied by the bridge layer so the engine can remain free of
+ * framework / AsyncLocalStorage dependencies. `fallbackTo` and
+ * `fallbackAccountId` are consulted only when the corresponding AI-supplied
+ * parameter is missing.
+ */
+interface RemindExecuteContext {
+  fallbackTo?: string;
+  fallbackAccountId?: string;
+}
+
+export type RemindCronAction =
+  | { action: "list" }
+  | { action: "remove"; jobId: string }
+  | {
+      action: "add";
+      job: ReturnType<typeof buildOnceJob>["job"] | ReturnType<typeof buildCronJob>["job"];
+    };
+
+type RemindCronScheduler = (params: RemindCronAction) => Promise<unknown>;
+
+type RemindCronPlan =
+  | {
+      ok: true;
+      action: RemindParams["action"];
+      cronAction: RemindCronAction;
+      summary?: string;
+    }
+  | {
+      ok: false;
+      error: string;
+    };
+
+const PREPARED_CRON_PARAMS_INSTRUCTION =
+  "Gateway cron action prepared for internal QQ reminder scheduling.";
+
+/**
+ * JSON Schema for AI tool parameters (used by framework registration).
+ * AI Tool 参数的 JSON Schema 定义（供框架注册使用）。
+ */
+export const RemindSchema = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      description:
+        "Action type. add=create a reminder, list=show reminders, remove=delete a reminder.",
+      enum: ["add", "list", "remove"],
+    },
+    content: {
+      type: "string",
+      description:
+        'Reminder content, for example "drink water" or "join the meeting". Required when action=add.',
+    },
+    to: {
+      type: "string",
+      description:
+        "Optional delivery target. The runtime automatically resolves the current " +
+        "conversation target, so you usually do not need to supply this. " +
+        "Direct-message format: qqbot:c2c:user_openid. Group format: qqbot:group:group_openid.",
+    },
+    time: {
+      type: "string",
+      description:
+        "Time description. Supported formats:\n" +
+        '1. Relative time, for example "5m", "1h", "1h30m", or "2d"\n' +
+        '2. Cron expression, for example "0 8 * * *" or "0 9 * * 1-5"\n' +
+        "Values containing spaces are treated as cron expressions; everything else is treated as a one-shot relative delay.\n" +
+        "Required when action=add.",
+    },
+    timezone: {
+      type: "string",
+      description: 'Timezone used for cron reminders. Defaults to "Asia/Shanghai".',
+    },
+    name: {
+      type: "string",
+      description: "Optional reminder job name. Defaults to the first 20 characters of content.",
+    },
+    jobId: {
+      type: "string",
+      description: "Job ID to remove. Required when action=remove; fetch it with list first.",
+    },
+  },
+  required: ["action"],
+} as const;
+
+/**
+ * Parse a relative time string into milliseconds.
+ * 解析相对时间字符串为毫秒数。
+ *
+ * Supports: "5m", "1h", "1h30m", "2d", "45s", plain number (as minutes).
+ *
+ * @returns Milliseconds or null if unparseable.
+ */
+export function parseRelativeTime(timeStr: string): number | null {
+  const s = timeStr.toLowerCase();
+  if (/^\d+$/.test(s)) {
+    return Number.parseInt(s, 10) * 60_000;
+  }
+
+  let totalMs = 0;
+  let matched = false;
+  const regex = /(\d+(?:\.\d+)?)\s*(d|h|m|s)/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(s)) !== null) {
+    matched = true;
+    const value = Number.parseFloat(match[1]);
+    const unit = match[2];
+    switch (unit) {
+      case "d":
+        totalMs += value * 86_400_000;
+        break;
+      case "h":
+        totalMs += value * 3_600_000;
+        break;
+      case "m":
+        totalMs += value * 60_000;
+        break;
+      case "s":
+        totalMs += value * 1_000;
+        break;
+    }
+  }
+  return matched ? Math.round(totalMs) : null;
+}
+
+/**
+ * Check whether a time string is a cron expression (3–6 space-separated fields).
+ * 判断时间字符串是否为 cron 表达式。
+ */
+export function isCronExpression(timeStr: string): boolean {
+  const parts = timeStr.trim().split(/\s+/);
+  if (parts.length < 3 || parts.length > 6) {
+    return false;
+  }
+  return parts.every((p) => /^[0-9*?/,LW#-]/.test(p));
+}
+
+/**
+ * Generate a cron job name from reminder content (first 20 chars).
+ * 根据提醒内容生成 cron job 名称。
+ */
+export function generateJobName(content: string): string {
+  const trimmed = content.trim();
+  const short = trimmed.length > 20 ? `${trimmed.slice(0, 20)}…` : trimmed;
+  return `Reminder: ${short}`;
+}
+
+/** Build the reminder system prompt sent to the AI. */
+export function buildReminderPrompt(content: string): string {
+  return (
+    `You are a warm reminder assistant. Please remind the user about: ${content}. ` +
+    `Requirements: (1) do not reply with HEARTBEAT_OK (2) do not explain who you are ` +
+    `(3) output a direct and caring reminder message (4) you may add a short encouraging line ` +
+    `(5) keep it within 2-3 sentences (6) use a small amount of emoji.`
+  );
+}
+
+/** Build cron job params for a one-shot delayed reminder. */
+function buildOnceJob(params: RemindParams, delayMs: number, to: string, accountId: string) {
+  const atMs = Date.now() + delayMs;
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+  return {
+    action: "add" as const,
+    job: {
+      name,
+      schedule: { kind: "at" as const, atMs },
+      sessionTarget: "isolated" as const,
+      wakeMode: "now" as const,
+      deleteAfterRun: true,
+      payload: {
+        kind: "agentTurn" as const,
+        message: buildReminderPrompt(content),
+      },
+      delivery: {
+        mode: "announce" as const,
+        channel: "qqbot" as const,
+        to,
+        accountId,
+      },
+    },
+  };
+}
+
+/** Build cron job params for a recurring cron reminder. */
+function buildCronJob(params: RemindParams, to: string, accountId: string) {
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+  const tz = params.timezone || "Asia/Shanghai";
+  return {
+    action: "add" as const,
+    job: {
+      name,
+      schedule: { kind: "cron" as const, expr: params.time!.trim(), tz },
+      sessionTarget: "isolated" as const,
+      wakeMode: "now" as const,
+      payload: {
+        kind: "agentTurn" as const,
+        message: buildReminderPrompt(content),
+      },
+      delivery: {
+        mode: "announce" as const,
+        channel: "qqbot" as const,
+        to,
+        accountId,
+      },
+    },
+  };
+}
+
+/** Format a delay in milliseconds as a short string (e.g. "5m", "1h30m"). */
+export function formatDelay(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  const totalMinutes = Math.round(ms / 60_000);
+  if (totalMinutes < 60) {
+    return `${totalMinutes}m`;
+  }
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (minutes === 0) {
+    return `${hours}h`;
+  }
+  return `${hours}h${minutes}m`;
+}
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function formatSchedulerError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function prepareRemindCronAction(
+  params: RemindParams,
+  ctx: RemindExecuteContext = {},
+): RemindCronPlan {
+  if (params.action === "list") {
+    return { ok: true, action: "list", cronAction: { action: "list" } };
+  }
+
+  if (params.action === "remove") {
+    if (!params.jobId) {
+      return { ok: false, error: "jobId is required when action=remove. Use action=list first." };
+    }
+    return {
+      ok: true,
+      action: "remove",
+      cronAction: { action: "remove", jobId: params.jobId },
+    };
+  }
+
+  if (!params.content) {
+    return { ok: false, error: "content is required when action=add" };
+  }
+  const resolvedTo = params.to || ctx.fallbackTo;
+  if (!resolvedTo) {
+    return {
+      ok: false,
+      error:
+        "Unable to determine delivery target for action=add. " +
+        "The reminder can only be scheduled from within an active conversation.",
+    };
+  }
+  if (!params.time) {
+    return { ok: false, error: "time is required when action=add" };
+  }
+  const resolvedAccountId = ctx.fallbackAccountId || "default";
+
+  if (isCronExpression(params.time)) {
+    return {
+      ok: true,
+      action: "add",
+      cronAction: buildCronJob(params, resolvedTo, resolvedAccountId),
+      summary: `⏰ Recurring reminder: "${params.content}" (${params.time}, tz=${params.timezone || "Asia/Shanghai"})`,
+    };
+  }
+
+  const delayMs = parseRelativeTime(params.time);
+  if (delayMs == null) {
+    return {
+      ok: false,
+      error: `Could not parse time format: ${params.time}. Use values like 5m, 1h, 1h30m, or a cron expression.`,
+    };
+  }
+  if (delayMs < 30_000) {
+    return { ok: false, error: "Reminder delay must be at least 30 seconds" };
+  }
+
+  return {
+    ok: true,
+    action: "add",
+    cronAction: buildOnceJob(params, delayMs, resolvedTo, resolvedAccountId),
+    summary: `⏰ Reminder in ${formatDelay(delayMs)}: "${params.content}"`,
+  };
+}
+
+/**
+ * Execute the reminder tool logic.
+ * 执行提醒工具逻辑。
+ *
+ * Validates params, parses time, and returns a structured result
+ * containing cron job params that the framework shell passes back
+ * as the tool output.
+ *
+ * When the AI omits `to` / `accountId`, the bridge layer can supply
+ * `ctx.fallbackTo` / `ctx.fallbackAccountId` (typically resolved from
+ * the request-scoped AsyncLocalStorage) to fill them in.
+ */
+export function executeRemind(params: RemindParams, ctx: RemindExecuteContext = {}) {
+  const plan = prepareRemindCronAction(params, ctx);
+  if (!plan.ok) {
+    return json({ error: plan.error });
+  }
+  return json({
+    _instruction: PREPARED_CRON_PARAMS_INSTRUCTION,
+    action: plan.action,
+    summary: plan.summary,
+  });
+}
+
+export async function executeScheduledRemind(
+  params: RemindParams,
+  ctx: RemindExecuteContext,
+  scheduler: RemindCronScheduler,
+) {
+  const plan = prepareRemindCronAction(params, ctx);
+  if (!plan.ok) {
+    return json({ error: plan.error });
+  }
+
+  try {
+    const cronResult = await scheduler(plan.cronAction);
+    return json({
+      ok: true,
+      action: plan.action,
+      summary: plan.summary,
+      cronResult,
+    });
+  } catch (error) {
+    return json({
+      error: `Failed to run Gateway cron action: ${formatSchedulerError(error)}`,
+      action: plan.action,
+    });
+  }
+}

package/src/engine/types.ts

@@ -0,0 +1,313 @@
+/**
+ * Core API layer public types.
+ *
+ * These types are independent of the root `src/types.ts` and only define
+ * what the `core/api/` modules need.  The old `src/types.ts` remains
+ * untouched for backward compatibility.
+ */
+
+// ============ Structured API Error ============
+
+/**
+ * Structured API error with HTTP status, path, and optional business error code.
+ *
+ * Compared to the old `api.ts` which throws plain `Error`, this carries
+ * machine-readable fields for downstream retry/fallback decisions.
+ */
+export class ApiError extends Error {
+  override readonly name = "ApiError";
+
+  constructor(
+    message: string,
+    /** HTTP status code returned by the QQ Open Platform. */
+    public readonly httpStatus: number,
+    /** API path that produced the error (e.g. `/v2/users/{id}/messages`). */
+    public readonly path: string,
+    /** Business error code from the response body (`code` or `err_code`). */
+    public readonly bizCode?: number,
+    /** Original error message from the response body. */
+    public readonly bizMessage?: string,
+  ) {
+    super(message);
+  }
+}
+
+// ============ Logger ============
+
+/**
+ * Unified logger interface used across all engine/ modules.
+ *
+ * Replaces the previously fragmented ApiLogger, GatewayLogger, ReconnectLogger,
+ * MessageRefLogger, PathLogger, and SenderLogger interfaces.
+ *
+ * `info` and `error` are required; `warn` and `debug` are optional because
+ * some callers (e.g. the framework-injected `ctx.log`) may not provide them.
+ */
+export interface EngineLogger {
+  info: (msg: string, meta?: Record<string, unknown>) => void;
+  error: (msg: string, meta?: Record<string, unknown>) => void;
+  warn?: (msg: string, meta?: Record<string, unknown>) => void;
+  debug?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+
+// ============ Chat Scope ============
+
+/** Chat scope used to unify C2C/Group path construction. */
+export type ChatScope = "c2c" | "group";
+
+// ============ Message Response ============
+
+/** Standard message send response from the QQ Open Platform. */
+export interface MessageResponse {
+  id: string;
+  timestamp: number | string;
+  /** Reference index for future quoting. */
+  ext_info?: {
+    ref_idx?: string;
+  };
+}
+
+// ============ Media Types ============
+
+/** QQ Open Platform media file type codes. */
+export enum MediaFileType {
+  IMAGE = 1,
+  VIDEO = 2,
+  VOICE = 3,
+  FILE = 4,
+}
+
+/** Media upload response from the QQ Open Platform. */
+export interface UploadMediaResponse {
+  file_uuid: string;
+  file_info: string;
+  ttl: number;
+  id?: string;
+}
+
+/** Structured metadata recorded for outbound messages. */
+export interface OutboundMeta {
+  /** Message text content. */
+  text?: string;
+  /** Media type tag. */
+  mediaType?: "image" | "voice" | "video" | "file";
+  /** Remote URL of the media source. */
+  mediaUrl?: string;
+  /** Local file path of the media source. */
+  mediaLocalPath?: string;
+  /** Original TTS text (voice messages only). */
+  ttsText?: string;
+}
+
+// ============ API Client Config ============
+
+/** Configuration for the core HTTP client. */
+export interface ApiClientConfig {
+  /** Base URL for the QQ Open Platform REST API. */
+  baseUrl?: string;
+  /** Default request timeout in milliseconds. */
+  defaultTimeoutMs?: number;
+  /** File upload request timeout in milliseconds. */
+  fileUploadTimeoutMs?: number;
+  /** Logger instance. */
+  logger?: EngineLogger;
+  /** User-Agent header value, or a getter function for dynamic resolution. */
+  userAgent?: string | (() => string);
+}
+
+// ============ Chunked Upload Types ============
+
+/** Individual upload part metadata. */
+export interface UploadPart {
+  /** Part index (1-based). */
+  index: number;
+  /** Pre-signed upload URL. */
+  presigned_url: string;
+}
+
+/** Response from the upload_prepare endpoint. */
+export interface UploadPrepareResponse {
+  /** Upload task identifier. */
+  upload_id: string;
+  /** Block size in bytes. */
+  block_size: number;
+  /** Pre-signed upload parts. */
+  parts: UploadPart[];
+  /** Server-suggested upload concurrency. */
+  concurrency?: number;
+  /** Server-suggested retry timeout for upload_part_finish (seconds). */
+  retry_timeout?: number;
+}
+
+/** File hash information for upload_prepare. */
+export interface UploadPrepareHashes {
+  /** Whole-file MD5 (hex). */
+  md5: string;
+  /** Whole-file SHA1 (hex). */
+  sha1: string;
+  /** MD5 of the first 10,002,432 bytes (hex). */
+  md5_10m: string;
+}
+
+// ============ Stream Message Types ============
+
+/** Stream message input mode (C2C stream_messages API). */
+export const StreamInputMode = {
+  /** Each chunk replaces full message content. */
+  REPLACE: "replace",
+} as const;
+export type StreamInputMode = (typeof StreamInputMode)[keyof typeof StreamInputMode];
+
+/** Stream message input state (numeric per QQ Open Platform). */
+export const StreamInputState = {
+  GENERATING: 1,
+  DONE: 10,
+} as const;
+export type StreamInputState = (typeof StreamInputState)[keyof typeof StreamInputState];
+
+/** Stream message content type. */
+export const StreamContentType = {
+  MARKDOWN: "markdown",
+} as const;
+export type StreamContentType = (typeof StreamContentType)[keyof typeof StreamContentType];
+
+/** Stream message request body for `/v2/users/{openid}/stream_messages`. */
+export interface StreamMessageRequest {
+  input_mode: StreamInputMode;
+  input_state: StreamInputState;
+  content_type: StreamContentType;
+  content_raw: string;
+  event_id: string;
+  msg_id: string;
+  stream_msg_id?: string;
+  msg_seq: number;
+  index: number;
+}
+
+// ============ Inline Keyboard Types ============
+
+/** Inline keyboard button for approval/interaction flows. */
+export interface KeyboardButton {
+  id: string;
+  render_data: {
+    label: string;
+    visited_label: string;
+    style: number;
+  };
+  action: {
+    type: number;
+    permission: { type: number };
+    data: string;
+    click_limit?: number;
+  };
+  group_id?: string;
+}
+
+/**
+ * Inline keyboard structure attached to messages.
+ * Sent as the `keyboard` field in the message body:
+ * `{ "keyboard": { "content": { "rows": [...] } } }`
+ */
+export interface InlineKeyboard {
+  content: {
+    rows: Array<{ buttons: KeyboardButton[] }>;
+  };
+}
+
+// ============ Interaction Event Types ============
+
+/** Button interaction event (INTERACTION_CREATE). */
+export interface InteractionEvent {
+  /** Event ID — used to acknowledge the interaction (PUT /interactions/{id}). */
+  id: string;
+  /** Event sub-type: 11=message button, 12=c2c quick menu. */
+  type: number;
+  /** Scene identifier: c2c / group / guild. */
+  scene?: string;
+  /** Chat type: 0=guild, 1=group, 2=c2c. */
+  chat_type?: number;
+  timestamp?: string;
+  guild_id?: string;
+  channel_id?: string;
+  /** C2C user openid (c2c scene only). */
+  user_openid?: string;
+  /** Group openid (group scene only). */
+  group_openid?: string;
+  /** Group member openid (group scene only). */
+  group_member_openid?: string;
+  version: number;
+  data: {
+    type: number;
+    resolved: {
+      button_data?: string;
+      button_id?: string;
+      user_id?: string;
+      feature_id?: string;
+      message_id?: string;
+    };
+  };
+}
+
+// ============ Account Config View ============
+
+import type { QQBotDmPolicy, QQBotGroupPolicy } from "./access/types.js";
+
+/**
+ * Typed view of known per-account configuration fields.
+ *
+ * Used for `as QQBotAccountConfigView` casts when reading fields from
+ * the raw `Record<string, unknown>` config. The actual config type
+ * stays `Record<string, unknown>` to avoid schema incompatibility.
+ */
+export interface QQBotAccountConfigView {
+  allowFrom?: Array<string | number>;
+  groupAllowFrom?: Array<string | number>;
+  dmPolicy?: QQBotDmPolicy;
+  groupPolicy?: QQBotGroupPolicy;
+  groups?: Record<string, Record<string, unknown>>;
+  streaming?:
+    | boolean
+    | {
+        mode?: string;
+        c2cStreamApi?: boolean;
+      };
+  audioFormatPolicy?: {
+    uploadDirectFormats?: string[];
+    transcodeEnabled?: boolean;
+  };
+  voiceDirectUploadFormats?: string[];
+}
+
+// ============ Gateway Account ============
+
+/**
+ * Resolved account configuration — shared across gateway/ and messaging/ layers.
+ *
+ * Lifted here from gateway/types.ts to eliminate the circular type dependency
+ * where messaging/ had to import from gateway/.
+ */
+export interface GatewayAccount {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  markdownSupport: boolean;
+  systemPrompt?: string;
+  config: Record<string, unknown> & {
+    allowFrom?: Array<string | number>;
+    groupAllowFrom?: Array<string | number>;
+    dmPolicy?: "open" | "allowlist" | "disabled";
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    streaming?:
+      | boolean
+      | {
+          mode?: string;
+          /** When true, use QQ C2C `stream_messages` for DMs. Boolean `true` is equivalent. */
+          c2cStreamApi?: boolean;
+        };
+    audioFormatPolicy?: {
+      uploadDirectFormats?: string[];
+      transcodeEnabled?: boolean;
+    };
+    voiceDirectUploadFormats?: string[];
+  };
+}