@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/tools/channel-api.ts

@@ -0,0 +1,244 @@
+/**
+ * QQ Channel API proxy tool core logic.
+ * QQ 频道 API 代理工具核心逻辑。
+ *
+ * Provides an authenticated HTTP proxy for the QQ Open Platform channel
+ * APIs. The caller (old tools/channel.ts shell) resolves the access
+ * token and passes it in; this module handles URL building, path
+ * validation, fetch, and structured response formatting.
+ */
+
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+
+const API_BASE = "https://api.sgroup.qq.com";
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Channel API call parameters.
+ * 频道 API 调用参数。
+ */
+export interface ChannelApiParams {
+  method: string;
+  path: string;
+  body?: Record<string, unknown>;
+  query?: Record<string, string>;
+}
+
+/**
+ * JSON Schema for AI tool parameters (used by framework registration).
+ * AI Tool 参数的 JSON Schema 定义（供框架注册使用）。
+ */
+export const ChannelApiSchema = {
+  type: "object",
+  properties: {
+    method: {
+      type: "string",
+      description: "HTTP method. Allowed values: GET, POST, PUT, PATCH, DELETE.",
+      enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+    },
+    path: {
+      type: "string",
+      description:
+        "API path without the host. Replace placeholders with concrete values. " +
+        "Examples: /users/@me/guilds, /guilds/{guild_id}/channels, /channels/{channel_id}.",
+    },
+    body: {
+      type: "object",
+      description:
+        "JSON request body for POST/PUT/PATCH requests. GET/DELETE usually do not need it.",
+    },
+    query: {
+      type: "object",
+      description:
+        "URL query parameters as key/value pairs appended to the path. " +
+        'For example, { "limit": "100", "after": "0" } becomes ?limit=100&after=0.',
+      additionalProperties: { type: "string" },
+    },
+  },
+  required: ["method", "path"],
+} as const;
+
+/**
+ * Build the full API URL from base + path + query params.
+ * 拼接 API 基地址 + 路径 + 查询参数。
+ */
+function buildUrl(path: string, query?: Record<string, string>): string {
+  let url = `${API_BASE}${path}`;
+  if (query && Object.keys(query).length > 0) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") {
+        params.set(key, value);
+      }
+    }
+    const qs = params.toString();
+    if (qs) {
+      url += `?${qs}`;
+    }
+  }
+  return url;
+}
+
+/**
+ * Validate API path format; returns an error string or null if valid.
+ * 校验 API 路径格式，返回错误描述或 null（合法）。
+ */
+function validatePath(path: string): string | null {
+  if (!path.startsWith("/")) {
+    return "path must start with /";
+  }
+  if (path.includes("..") || path.includes("//")) {
+    return "path must not contain .. or //";
+  }
+  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") {
+    return "path contains unsupported characters";
+  }
+  return null;
+}
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+/**
+ * Options provided by the caller when executing a channel API request.
+ * 执行频道 API 请求时由调用方提供的选项。
+ */
+interface ChannelApiExecuteOptions {
+  accessToken: string;
+}
+
+/**
+ * Execute a channel API proxy request.
+ * 执行频道 API 代理请求。
+ *
+ * The caller provides the access token; this function handles
+ * URL building, path validation, HTTP fetch, and structured
+ * response formatting suitable for AI tool output.
+ */
+export async function executeChannelApi(
+  params: ChannelApiParams,
+  options: ChannelApiExecuteOptions,
+) {
+  if (!params.method) {
+    return json({ error: "method is required" });
+  }
+  if (!params.path) {
+    return json({ error: "path is required" });
+  }
+
+  const method = params.method.toUpperCase();
+  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+    return json({
+      error: `Unsupported HTTP method: ${method}. Allowed values: GET, POST, PUT, PATCH, DELETE`,
+    });
+  }
+
+  const pathError = validatePath(params.path);
+  if (pathError) {
+    return json({ error: pathError });
+  }
+
+  if (
+    (method === "GET" || method === "DELETE") &&
+    params.body &&
+    Object.keys(params.body).length > 0
+  ) {
+    debugLog(`[qqbot-channel-api] ${method} request with body, body will be ignored`);
+  }
+
+  try {
+    const url = buildUrl(params.path, params.query);
+    const headers: Record<string, string> = {
+      Authorization: `QQBot ${options.accessToken}`,
+      "Content-Type": "application/json",
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers,
+      signal: controller.signal,
+    };
+
+    if (params.body && ["POST", "PUT", "PATCH"].includes(method)) {
+      fetchOptions.body = JSON.stringify(params.body);
+    }
+
+    debugLog(`[qqbot-channel-api] >>> ${method} ${url} (timeout: ${DEFAULT_TIMEOUT_MS}ms)`);
+
+    let res: Response;
+    try {
+      res = await fetch(url, fetchOptions);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        debugError(`[qqbot-channel-api] <<< Request timeout after ${DEFAULT_TIMEOUT_MS}ms`);
+        return json({
+          error: `Request timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+          path: params.path,
+        });
+      }
+      debugError("[qqbot-channel-api] <<< Network error:", err);
+      return json({
+        error: `Network error: ${formatErrorMessage(err)}`,
+        path: params.path,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    debugLog(`[qqbot-channel-api] <<< Status: ${res.status} ${res.statusText}`);
+
+    const rawBody = await res.text();
+    if (!rawBody || rawBody.trim() === "") {
+      if (res.ok) {
+        return json({ success: true, status: res.status, path: params.path });
+      }
+      return json({
+        error: `API returned ${res.status} ${res.statusText}`,
+        status: res.status,
+        path: params.path,
+      });
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+      parsed = rawBody;
+    }
+
+    if (!res.ok) {
+      const errMsg =
+        typeof parsed === "object" && parsed && "message" in parsed
+          ? String((parsed as { message?: unknown }).message)
+          : `${res.status} ${res.statusText}`;
+      debugError(`[qqbot-channel-api] Error [${method} ${params.path}]: ${errMsg}`);
+      return json({
+        error: errMsg,
+        status: res.status,
+        path: params.path,
+        details: parsed,
+      });
+    }
+
+    return json({
+      success: true,
+      status: res.status,
+      path: params.path,
+      data: parsed,
+    });
+  } catch (err) {
+    return json({
+      error: formatErrorMessage(err),
+      path: params.path,
+    });
+  }
+}

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

@@ -0,0 +1,280 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseRelativeTime,
+  isCronExpression,
+  formatDelay,
+  generateJobName,
+  buildReminderPrompt,
+  executeRemind,
+  executeScheduledRemind,
+  prepareRemindCronAction,
+} from "./remind-logic.js";
+
+describe("engine/tools/remind-logic", () => {
+  describe("parseRelativeTime", () => {
+    it("parses minutes shorthand", () => {
+      expect(parseRelativeTime("5m")).toBe(5 * 60_000);
+    });
+
+    it("parses hours shorthand", () => {
+      expect(parseRelativeTime("1h")).toBe(3_600_000);
+    });
+
+    it("parses combined hours and minutes", () => {
+      expect(parseRelativeTime("1h30m")).toBe(90 * 60_000);
+    });
+
+    it("parses days", () => {
+      expect(parseRelativeTime("2d")).toBe(2 * 86_400_000);
+    });
+
+    it("parses seconds", () => {
+      expect(parseRelativeTime("45s")).toBe(45_000);
+    });
+
+    it("treats plain numbers as minutes", () => {
+      expect(parseRelativeTime("10")).toBe(10 * 60_000);
+    });
+
+    it("returns null for unparseable input", () => {
+      expect(parseRelativeTime("never")).toBeNull();
+    });
+
+    it("is case insensitive", () => {
+      expect(parseRelativeTime("5M")).toBe(5 * 60_000);
+    });
+  });
+
+  describe("isCronExpression", () => {
+    it("detects standard 5-field cron", () => {
+      expect(isCronExpression("0 8 * * *")).toBe(true);
+    });
+
+    it("detects weekday range cron", () => {
+      expect(isCronExpression("0 9 * * 1-5")).toBe(true);
+    });
+
+    it("rejects short input", () => {
+      expect(isCronExpression("5m")).toBe(false);
+    });
+
+    it("rejects too many fields", () => {
+      expect(isCronExpression("0 0 0 0 0 0 0")).toBe(false);
+    });
+  });
+
+  describe("formatDelay", () => {
+    it("formats seconds", () => {
+      expect(formatDelay(45_000)).toBe("45s");
+    });
+
+    it("formats minutes", () => {
+      expect(formatDelay(300_000)).toBe("5m");
+    });
+
+    it("formats hours", () => {
+      expect(formatDelay(3_600_000)).toBe("1h");
+    });
+
+    it("formats hours and minutes", () => {
+      expect(formatDelay(5_400_000)).toBe("1h30m");
+    });
+  });
+
+  describe("generateJobName", () => {
+    it("returns short content as-is", () => {
+      expect(generateJobName("drink water")).toBe("Reminder: drink water");
+    });
+
+    it("truncates long content", () => {
+      const long = "a very long reminder content that exceeds twenty characters";
+      const name = generateJobName(long);
+      expect(name.length).toBeLessThan(40);
+      expect(name).toContain("…");
+    });
+  });
+
+  describe("buildReminderPrompt", () => {
+    it("includes the content in the prompt", () => {
+      const prompt = buildReminderPrompt("drink water");
+      expect(prompt).toContain("drink water");
+    });
+  });
+
+  describe("executeRemind", () => {
+    it("renders internal scheduling output without exposing cronParams", () => {
+      const result = executeRemind({ action: "list" });
+      expect(result.details).toEqual({
+        _instruction: "Gateway cron action prepared for internal QQ reminder scheduling.",
+        action: "list",
+        summary: undefined,
+      });
+      expect((result.details as { _instruction: string })._instruction).not.toContain(
+        "Use the cron tool",
+      );
+      expect(result.details).not.toHaveProperty("cronParams");
+    });
+  });
+
+  describe("prepareRemindCronAction", () => {
+    it("returns error when removing without jobId", () => {
+      const result = prepareRemindCronAction({ action: "remove" });
+      expect(result).toEqual({
+        ok: false,
+        error: "jobId is required when action=remove. Use action=list first.",
+      });
+    });
+
+    it("returns error when content is missing for add", () => {
+      const result = prepareRemindCronAction({ action: "add", to: "qqbot:c2c:123", time: "5m" });
+      expect(result).toEqual({ ok: false, error: "content is required when action=add" });
+    });
+
+    it("returns error when delay is too short", () => {
+      const result = prepareRemindCronAction({
+        action: "add",
+        content: "test",
+        to: "qqbot:c2c:123",
+        time: "10s",
+      });
+      expect(result).toEqual({ ok: false, error: "Reminder delay must be at least 30 seconds" });
+    });
+
+    it("builds once job with delivery envelope for relative time", () => {
+      const result = prepareRemindCronAction({
+        action: "add",
+        content: "test reminder",
+        to: "qqbot:c2c:123",
+        time: "5m",
+      });
+      expect(result.ok).toBe(true);
+      expect(result.ok ? result.cronAction.action : undefined).toBe("add");
+      const job = result.ok && result.cronAction.action === "add" ? result.cronAction.job : null;
+      expect(job?.schedule.kind).toBe("at");
+      expect(job?.payload.kind).toBe("agentTurn");
+      expect(job?.delivery).toEqual({
+        mode: "announce",
+        channel: "qqbot",
+        to: "qqbot:c2c:123",
+        accountId: "default",
+      });
+    });
+
+    it("builds cron job with delivery envelope for cron expression", () => {
+      const result = prepareRemindCronAction({
+        action: "add",
+        content: "test reminder",
+        to: "qqbot:c2c:123",
+        time: "0 8 * * *",
+      });
+      expect(result.ok).toBe(true);
+      const job = result.ok && result.cronAction.action === "add" ? result.cronAction.job : null;
+      expect(job?.schedule.kind).toBe("cron");
+      expect(job?.delivery.to).toBe("qqbot:c2c:123");
+    });
+
+    it("falls back to ctx.fallbackTo when to is omitted", () => {
+      const result = prepareRemindCronAction(
+        { action: "add", content: "test", time: "5m" },
+        { fallbackTo: "qqbot:c2c:ctx-target", fallbackAccountId: "alt" },
+      );
+      expect(result.ok).toBe(true);
+      const job = result.ok && result.cronAction.action === "add" ? result.cronAction.job : null;
+      expect(job?.delivery.to).toBe("qqbot:c2c:ctx-target");
+      expect(job?.delivery.accountId).toBe("alt");
+    });
+
+    it("prefers AI-supplied to over ctx fallback", () => {
+      const result = prepareRemindCronAction(
+        { action: "add", content: "test", time: "5m", to: "qqbot:group:ai-chosen" },
+        { fallbackTo: "qqbot:c2c:ctx-target", fallbackAccountId: "alt" },
+      );
+      expect(result.ok).toBe(true);
+      const job = result.ok && result.cronAction.action === "add" ? result.cronAction.job : null;
+      expect(job?.delivery.to).toBe("qqbot:group:ai-chosen");
+      expect(job?.delivery.accountId).toBe("alt");
+    });
+
+    it("returns error when neither AI nor ctx provides a target", () => {
+      const result = prepareRemindCronAction({ action: "add", content: "test", time: "5m" });
+      expect(result).toEqual({
+        ok: false,
+        error:
+          "Unable to determine delivery target for action=add. " +
+          "The reminder can only be scheduled from within an active conversation.",
+      });
+    });
+  });
+
+  describe("executeScheduledRemind", () => {
+    it("runs cron.add directly for relative reminders", async () => {
+      const calls: unknown[] = [];
+      const result = await executeScheduledRemind(
+        { action: "add", content: "test reminder", to: "qqbot:c2c:123", time: "5m" },
+        {},
+        async (params) => {
+          calls.push(params);
+          return { id: "job-1" };
+        },
+      );
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0]).toMatchObject({
+        action: "add",
+        job: {
+          sessionTarget: "isolated",
+          payload: { kind: "agentTurn" },
+          delivery: {
+            mode: "announce",
+            channel: "qqbot",
+            to: "qqbot:c2c:123",
+            accountId: "default",
+          },
+        },
+      });
+      expect(result.details).toEqual({
+        ok: true,
+        action: "add",
+        summary: '⏰ Reminder in 5m: "test reminder"',
+        cronResult: { id: "job-1" },
+      });
+    });
+
+    it("runs cron list and remove through the scheduler", async () => {
+      const calls: unknown[] = [];
+      await executeScheduledRemind({ action: "list" }, {}, async (params) => {
+        calls.push(params);
+        return { jobs: [] };
+      });
+      await executeScheduledRemind({ action: "remove", jobId: "job-1" }, {}, async (params) => {
+        calls.push(params);
+        return { ok: true };
+      });
+
+      expect(calls).toEqual([{ action: "list" }, { action: "remove", jobId: "job-1" }]);
+    });
+
+    it("does not call scheduler when validation fails", async () => {
+      const result = await executeScheduledRemind({ action: "add", time: "5m" }, {}, async () => {
+        throw new Error("should not run");
+      });
+
+      expect((result.details as { error: string }).error).toContain("content");
+    });
+
+    it("returns a clear error when Gateway cron fails", async () => {
+      const result = await executeScheduledRemind(
+        { action: "remove", jobId: "job-1" },
+        {},
+        async () => {
+          throw new Error("gateway unavailable");
+        },
+      );
+
+      expect(result.details).toEqual({
+        error: "Failed to run Gateway cron action: gateway unavailable",
+        action: "remove",
+      });
+    });
+  });
+});