@gakr-gakr/qqbot 0.1.0

package/src/engine/session/session-store.ts

@@ -0,0 +1,207 @@
+/**
+ * Gateway session persistence — JSONL file-based store.
+ *
+ * Migrated from src/session-store.ts. Dependencies are only Node.js
+ * built-ins + log + platform (both zero plugin-sdk).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { privateFileStoreSync } from "autobot/plugin-sdk/security-runtime";
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+import { getQQBotDataDir, getQQBotDataPath } from "../utils/platform.js";
+
+/** Persisted gateway session state. */
+export interface SessionState {
+  sessionId: string | null;
+  lastSeq: number | null;
+  lastConnectedAt: number;
+  intentLevelIndex: number;
+  accountId: string;
+  savedAt: number;
+  appId?: string;
+}
+
+const SESSION_EXPIRE_TIME = 5 * 60 * 1000;
+const SAVE_THROTTLE_MS = 1000;
+
+const throttleState = new Map<
+  string,
+  {
+    pendingState: SessionState | null;
+    lastSaveTime: number;
+    throttleTimer: ReturnType<typeof setTimeout> | null;
+  }
+>();
+
+function ensureDir(): void {
+  getQQBotDataDir("sessions");
+}
+
+function getSessionDir(): string {
+  return getQQBotDataPath("sessions");
+}
+
+function encodeAccountIdForFileName(accountId: string): string {
+  return Buffer.from(accountId, "utf8").toString("base64url");
+}
+
+function getLegacySessionPath(accountId: string): string {
+  const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(getSessionDir(), `session-${safeId}.json`);
+}
+
+function getSessionPath(accountId: string): string {
+  const encodedId = encodeAccountIdForFileName(accountId);
+  return path.join(getSessionDir(), `session-${encodedId}.json`);
+}
+
+function getCandidateSessionPaths(accountId: string): string[] {
+  const primaryPath = getSessionPath(accountId);
+  const legacyPath = getLegacySessionPath(accountId);
+  return primaryPath === legacyPath ? [primaryPath] : [primaryPath, legacyPath];
+}
+
+/** Load a saved session, rejecting expired or mismatched appId entries. */
+export function loadSession(accountId: string, expectedAppId?: string): SessionState | null {
+  try {
+    let filePath: string | null = null;
+    let state: SessionState | null = null;
+    for (const candidatePath of getCandidateSessionPaths(accountId)) {
+      state = privateFileStoreSync(path.dirname(candidatePath)).readJsonIfExists<SessionState>(
+        path.basename(candidatePath),
+      );
+      if (state) {
+        filePath = candidatePath;
+        break;
+      }
+    }
+    if (!filePath || !state) {
+      return null;
+    }
+
+    const now = Date.now();
+
+    if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+      debugLog(
+        `[session-store] Session expired for ${accountId}, age: ${Math.round((now - state.savedAt) / 1000)}s`,
+      );
+      try {
+        fs.unlinkSync(filePath);
+      } catch {}
+      return null;
+    }
+
+    if (expectedAppId && state.appId && state.appId !== expectedAppId) {
+      debugLog(
+        `[session-store] appId mismatch for ${accountId}: saved=${state.appId}, current=${expectedAppId}. Discarding stale session.`,
+      );
+      try {
+        fs.unlinkSync(filePath);
+      } catch {}
+      return null;
+    }
+
+    if (!state.sessionId || state.lastSeq === null || state.lastSeq === undefined) {
+      debugLog(`[session-store] Invalid session data for ${accountId}`);
+      return null;
+    }
+
+    debugLog(
+      `[session-store] Loaded session for ${accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}, appId=${state.appId ?? "unknown"}, age=${Math.round((now - state.savedAt) / 1000)}s`,
+    );
+    return state;
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to load session for ${accountId}: ${formatErrorMessage(err)}`,
+    );
+    return null;
+  }
+}
+
+/** Save session state with throttling. */
+export function saveSession(state: SessionState): void {
+  const { accountId } = state;
+  let throttle = throttleState.get(accountId);
+  if (!throttle) {
+    throttle = { pendingState: null, lastSaveTime: 0, throttleTimer: null };
+    throttleState.set(accountId, throttle);
+  }
+
+  const now = Date.now();
+  const timeSinceLastSave = now - throttle.lastSaveTime;
+
+  if (timeSinceLastSave >= SAVE_THROTTLE_MS) {
+    doSaveSession(state);
+    throttle.lastSaveTime = now;
+    throttle.pendingState = null;
+    if (throttle.throttleTimer) {
+      clearTimeout(throttle.throttleTimer);
+      throttle.throttleTimer = null;
+    }
+  } else {
+    throttle.pendingState = state;
+    if (!throttle.throttleTimer) {
+      const delay = SAVE_THROTTLE_MS - timeSinceLastSave;
+      throttle.throttleTimer = setTimeout(() => {
+        const t = throttleState.get(accountId);
+        if (t?.pendingState) {
+          doSaveSession(t.pendingState);
+          t.lastSaveTime = Date.now();
+          t.pendingState = null;
+        }
+        if (t) {
+          t.throttleTimer = null;
+        }
+      }, delay);
+    }
+  }
+}
+
+function doSaveSession(state: SessionState): void {
+  const filePath = getSessionPath(state.accountId);
+  const legacyPath = getLegacySessionPath(state.accountId);
+  try {
+    ensureDir();
+    const stateToSave: SessionState = { ...state, savedAt: Date.now() };
+    privateFileStoreSync(path.dirname(filePath)).writeJson(path.basename(filePath), stateToSave);
+    if (legacyPath !== filePath && fs.existsSync(legacyPath)) {
+      fs.unlinkSync(legacyPath);
+    }
+    debugLog(
+      `[session-store] Saved session for ${state.accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}`,
+    );
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to save session for ${state.accountId}: ${formatErrorMessage(err)}`,
+    );
+  }
+}
+
+/** Clear a saved session and any pending throttle state. */
+export function clearSession(accountId: string): void {
+  const throttle = throttleState.get(accountId);
+  if (throttle) {
+    if (throttle.throttleTimer) {
+      clearTimeout(throttle.throttleTimer);
+    }
+    throttleState.delete(accountId);
+  }
+  try {
+    let cleared = false;
+    for (const filePath of getCandidateSessionPaths(accountId)) {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        cleared = true;
+      }
+    }
+    if (cleared) {
+      debugLog(`[session-store] Cleared session for ${accountId}`);
+    }
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to clear session for ${accountId}: ${formatErrorMessage(err)}`,
+    );
+  }
+}

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,
+    });
+  }
+}