@sliverp/qqbot 1.3.0

package/src/session-store.ts

@@ -0,0 +1,292 @@
+/**
+ * Session 持久化存储
+ * 将 WebSocket 连接状态（sessionId、lastSeq）持久化到文件
+ * 支持进程重启后通过 Resume 机制快速恢复连接
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// Session 状态接口
+export interface SessionState {
+  /** WebSocket Session ID */
+  sessionId: string | null;
+  /** 最后收到的消息序号 */
+  lastSeq: number | null;
+  /** 上次连接成功的时间戳 */
+  lastConnectedAt: number;
+  /** 上次成功的权限级别索引 */
+  intentLevelIndex: number;
+  /** 关联的机器人账户 ID */
+  accountId: string;
+  /** 保存时间 */
+  savedAt: number;
+}
+
+// Session 文件目录
+const SESSION_DIR = path.join(
+  process.env.HOME || "/tmp",
+  "clawd",
+  "qqbot-data"
+);
+
+// Session 过期时间（5分钟）- Resume 要求在断开后一定时间内恢复
+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 {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 获取 Session 文件路径
+ */
+function getSessionPath(accountId: string): string {
+  // 清理 accountId 中的特殊字符
+  const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(SESSION_DIR, `session-${safeId}.json`);
+}
+
+/**
+ * 加载 Session 状态
+ * @param accountId 账户 ID
+ * @returns Session 状态，如果不存在或已过期返回 null
+ */
+export function loadSession(accountId: string): SessionState | null {
+  const filePath = getSessionPath(accountId);
+  
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    
+    const data = fs.readFileSync(filePath, "utf-8");
+    const state = JSON.parse(data) as SessionState;
+    
+    // 检查是否过期
+    const now = Date.now();
+    if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+      console.log(`[session-store] Session expired for ${accountId}, age: ${Math.round((now - state.savedAt) / 1000)}s`);
+      // 删除过期文件
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+        // 忽略删除错误
+      }
+      return null;
+    }
+    
+    // 验证必要字段
+    if (!state.sessionId || state.lastSeq === null || state.lastSeq === undefined) {
+      console.log(`[session-store] Invalid session data for ${accountId}`);
+      return null;
+    }
+    
+    console.log(`[session-store] Loaded session for ${accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}, age=${Math.round((now - state.savedAt) / 1000)}s`);
+    return state;
+  } catch (err) {
+    console.error(`[session-store] Failed to load session for ${accountId}: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * 保存 Session 状态（带节流，避免频繁写入）
+ * @param state Session 状态
+ */
+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 && 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);
+  
+  try {
+    ensureDir();
+    
+    // 更新保存时间
+    const stateToSave: SessionState = {
+      ...state,
+      savedAt: Date.now(),
+    };
+    
+    fs.writeFileSync(filePath, JSON.stringify(stateToSave, null, 2), "utf-8");
+    console.log(`[session-store] Saved session for ${state.accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}`);
+  } catch (err) {
+    console.error(`[session-store] Failed to save session for ${state.accountId}: ${err}`);
+  }
+}
+
+/**
+ * 清除 Session 状态
+ * @param accountId 账户 ID
+ */
+export function clearSession(accountId: string): void {
+  const filePath = getSessionPath(accountId);
+  
+  // 清除节流状态
+  const throttle = throttleState.get(accountId);
+  if (throttle) {
+    if (throttle.throttleTimer) {
+      clearTimeout(throttle.throttleTimer);
+    }
+    throttleState.delete(accountId);
+  }
+  
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      console.log(`[session-store] Cleared session for ${accountId}`);
+    }
+  } catch (err) {
+    console.error(`[session-store] Failed to clear session for ${accountId}: ${err}`);
+  }
+}
+
+/**
+ * 更新 lastSeq（轻量级更新）
+ * @param accountId 账户 ID
+ * @param lastSeq 最新的消息序号
+ */
+export function updateLastSeq(accountId: string, lastSeq: number): void {
+  const existing = loadSession(accountId);
+  if (existing && existing.sessionId) {
+    saveSession({
+      ...existing,
+      lastSeq,
+    });
+  }
+}
+
+/**
+ * 获取所有保存的 Session 状态
+ */
+export function getAllSessions(): SessionState[] {
+  const sessions: SessionState[] = [];
+  
+  try {
+    ensureDir();
+    const files = fs.readdirSync(SESSION_DIR);
+    
+    for (const file of files) {
+      if (file.startsWith("session-") && file.endsWith(".json")) {
+        const filePath = path.join(SESSION_DIR, file);
+        try {
+          const data = fs.readFileSync(filePath, "utf-8");
+          const state = JSON.parse(data) as SessionState;
+          sessions.push(state);
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+  } catch {
+    // 目录不存在等错误
+  }
+  
+  return sessions;
+}
+
+/**
+ * 清理过期的 Session 文件
+ */
+export function cleanupExpiredSessions(): number {
+  let cleaned = 0;
+  
+  try {
+    ensureDir();
+    const files = fs.readdirSync(SESSION_DIR);
+    const now = Date.now();
+    
+    for (const file of files) {
+      if (file.startsWith("session-") && file.endsWith(".json")) {
+        const filePath = path.join(SESSION_DIR, file);
+        try {
+          const data = fs.readFileSync(filePath, "utf-8");
+          const state = JSON.parse(data) as SessionState;
+          
+          if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+            fs.unlinkSync(filePath);
+            cleaned++;
+            console.log(`[session-store] Cleaned expired session: ${file}`);
+          }
+        } catch {
+          // 忽略解析错误，但也删除损坏的文件
+          try {
+            fs.unlinkSync(filePath);
+            cleaned++;
+          } catch {
+            // 忽略
+          }
+        }
+      }
+    }
+  } catch {
+    // 目录不存在等错误
+  }
+  
+  return cleaned;
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+/**
+ * QQ Bot 配置类型
+ */
+export interface QQBotConfig {
+  appId: string;
+  clientSecret?: string;
+  clientSecretFile?: string;
+}
+
+/**
+ * 解析后的 QQ Bot 账户
+ */
+export interface ResolvedQQBotAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  appId: string;
+  clientSecret: string;
+  secretSource: "config" | "file" | "env" | "none";
+  /** 系统提示词 */
+  systemPrompt?: string;
+  /** 图床服务器公网地址 */
+  imageServerBaseUrl?: string;
+  /** 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用） */
+  markdownSupport?: boolean;
+  config: QQBotAccountConfig;
+}
+
+/**
+ * QQ Bot 账户配置
+ */
+export interface QQBotAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  appId?: string;
+  clientSecret?: string;
+  clientSecretFile?: string;
+  dmPolicy?: "open" | "pairing" | "allowlist";
+  allowFrom?: string[];
+  /** 系统提示词，会添加在用户消息前面 */
+  systemPrompt?: string;
+  /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
+  imageServerBaseUrl?: string;
+  /** 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用） */
+  markdownSupport?: boolean;
+}
+
+/**
+ * 富媒体附件
+ */
+export interface MessageAttachment {
+  content_type: string;  // 如 "image/png"
+  filename?: string;
+  height?: number;
+  width?: number;
+  size?: number;
+  url: string;
+}
+
+/**
+ * C2C 消息事件
+ */
+export interface C2CMessageEvent {
+  author: {
+    id: string;
+    union_openid: string;
+    user_openid: string;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  message_scene?: {
+    source: string;
+  };
+  attachments?: MessageAttachment[];
+}
+
+/**
+ * 频道 AT 消息事件
+ */
+export interface GuildMessageEvent {
+  id: string;
+  channel_id: string;
+  guild_id: string;
+  content: string;
+  timestamp: string;
+  author: {
+    id: string;
+    username?: string;
+    bot?: boolean;
+  };
+  member?: {
+    nick?: string;
+    joined_at?: string;
+  };
+  attachments?: MessageAttachment[];
+}
+
+/**
+ * 群聊 AT 消息事件
+ */
+export interface GroupMessageEvent {
+  author: {
+    id: string;
+    member_openid: string;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  group_id: string;
+  group_openid: string;
+  attachments?: MessageAttachment[];
+}
+
+/**
+ * WebSocket 事件负载
+ */
+export interface WSPayload {
+  op: number;
+  d?: unknown;
+  s?: number;
+  t?: string;
+}

package/src/utils/image-size.ts

@@ -0,0 +1,266 @@
+/**
+ * 图片尺寸工具
+ * 用于获取图片尺寸，生成 QQBot 的 markdown 图片格式
+ * 
+ * QQBot markdown 图片格式: ![#宽px #高px](url)
+ */
+
+import { Buffer } from "buffer";
+
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/** 默认图片尺寸（当无法获取时使用） */
+export const DEFAULT_IMAGE_SIZE: ImageSize = { width: 512, height: 512 };
+
+/**
+ * 从 PNG 文件头解析图片尺寸
+ * PNG 文件头结构: 前 8 字节是签名，IHDR 块从第 8 字节开始
+ * IHDR 块: 长度(4) + 类型(4, "IHDR") + 宽度(4) + 高度(4) + ...
+ */
+function parsePngSize(buffer: Buffer): ImageSize | null {
+  // PNG 签名: 89 50 4E 47 0D 0A 1A 0A
+  if (buffer.length < 24) return null;
+  if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4E || buffer[3] !== 0x47) {
+    return null;
+  }
+  // IHDR 块从第 8 字节开始，宽度在第 16-19 字节，高度在第 20-23 字节
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  return { width, height };
+}
+
+/**
+ * 从 JPEG 文件解析图片尺寸
+ * JPEG 尺寸在 SOF0/SOF2 块中
+ */
+function parseJpegSize(buffer: Buffer): ImageSize | null {
+  // JPEG 签名: FF D8 FF
+  if (buffer.length < 4) return null;
+  if (buffer[0] !== 0xFF || buffer[1] !== 0xD8) {
+    return null;
+  }
+  
+  let offset = 2;
+  while (offset < buffer.length - 9) {
+    if (buffer[offset] !== 0xFF) {
+      offset++;
+      continue;
+    }
+    
+    const marker = buffer[offset + 1];
+    // SOF0 (0xC0) 或 SOF2 (0xC2) 包含图片尺寸
+    if (marker === 0xC0 || marker === 0xC2) {
+      // 格式: FF C0 长度(2) 精度(1) 高度(2) 宽度(2)
+      if (offset + 9 <= buffer.length) {
+        const height = buffer.readUInt16BE(offset + 5);
+        const width = buffer.readUInt16BE(offset + 7);
+        return { width, height };
+      }
+    }
+    
+    // 跳过当前块
+    if (offset + 3 < buffer.length) {
+      const blockLength = buffer.readUInt16BE(offset + 2);
+      offset += 2 + blockLength;
+    } else {
+      break;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * 从 GIF 文件头解析图片尺寸
+ * GIF 文件头: GIF87a 或 GIF89a (6字节) + 宽度(2) + 高度(2)
+ */
+function parseGifSize(buffer: Buffer): ImageSize | null {
+  if (buffer.length < 10) return null;
+  const signature = buffer.toString("ascii", 0, 6);
+  if (signature !== "GIF87a" && signature !== "GIF89a") {
+    return null;
+  }
+  const width = buffer.readUInt16LE(6);
+  const height = buffer.readUInt16LE(8);
+  return { width, height };
+}
+
+/**
+ * 从 WebP 文件解析图片尺寸
+ * WebP 文件头: RIFF(4) + 文件大小(4) + WEBP(4) + VP8/VP8L/VP8X(4) + ...
+ */
+function parseWebpSize(buffer: Buffer): ImageSize | null {
+  if (buffer.length < 30) return null;
+  
+  // 检查 RIFF 和 WEBP 签名
+  const riff = buffer.toString("ascii", 0, 4);
+  const webp = buffer.toString("ascii", 8, 12);
+  if (riff !== "RIFF" || webp !== "WEBP") {
+    return null;
+  }
+  
+  const chunkType = buffer.toString("ascii", 12, 16);
+  
+  // VP8 (有损压缩)
+  if (chunkType === "VP8 ") {
+    // VP8 帧头从第 23 字节开始，检查签名 9D 01 2A
+    if (buffer.length >= 30 && buffer[23] === 0x9D && buffer[24] === 0x01 && buffer[25] === 0x2A) {
+      const width = buffer.readUInt16LE(26) & 0x3FFF;
+      const height = buffer.readUInt16LE(28) & 0x3FFF;
+      return { width, height };
+    }
+  }
+  
+  // VP8L (无损压缩)
+  if (chunkType === "VP8L") {
+    // VP8L 签名: 0x2F
+    if (buffer.length >= 25 && buffer[20] === 0x2F) {
+      const bits = buffer.readUInt32LE(21);
+      const width = (bits & 0x3FFF) + 1;
+      const height = ((bits >> 14) & 0x3FFF) + 1;
+      return { width, height };
+    }
+  }
+  
+  // VP8X (扩展格式)
+  if (chunkType === "VP8X") {
+    if (buffer.length >= 30) {
+      // 宽度和高度在第 24-26 和 27-29 字节（24位小端）
+      const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
+      const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
+      return { width, height };
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * 从图片数据 Buffer 解析尺寸
+ */
+export function parseImageSize(buffer: Buffer): ImageSize | null {
+  // 尝试各种格式
+  return parsePngSize(buffer) 
+    ?? parseJpegSize(buffer) 
+    ?? parseGifSize(buffer) 
+    ?? parseWebpSize(buffer);
+}
+
+/**
+ * 从公网 URL 获取图片尺寸
+ * 只下载前 64KB 数据，足够解析大部分图片格式的头部
+ */
+export async function getImageSizeFromUrl(url: string, timeoutMs = 5000): Promise<ImageSize | null> {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    
+    // 使用 Range 请求只获取前 64KB
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "Range": "bytes=0-65535",
+        "User-Agent": "QQBot-Image-Size-Detector/1.0",
+      },
+    });
+    
+    clearTimeout(timeoutId);
+    
+    if (!response.ok && response.status !== 206) {
+      console.log(`[image-size] Failed to fetch ${url}: ${response.status}`);
+      return null;
+    }
+    
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    
+    const size = parseImageSize(buffer);
+    if (size) {
+      console.log(`[image-size] Got size from URL: ${size.width}x${size.height} - ${url.slice(0, 60)}...`);
+    }
+    
+    return size;
+  } catch (err) {
+    console.log(`[image-size] Error fetching ${url.slice(0, 60)}...: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * 从 Base64 Data URL 获取图片尺寸
+ */
+export function getImageSizeFromDataUrl(dataUrl: string): ImageSize | null {
+  try {
+    // 格式: data:image/png;base64,xxxxx
+    const matches = dataUrl.match(/^data:image\/[^;]+;base64,(.+)$/);
+    if (!matches) {
+      return null;
+    }
+    
+    const base64Data = matches[1];
+    const buffer = Buffer.from(base64Data, "base64");
+    
+    const size = parseImageSize(buffer);
+    if (size) {
+      console.log(`[image-size] Got size from Base64: ${size.width}x${size.height}`);
+    }
+    
+    return size;
+  } catch (err) {
+    console.log(`[image-size] Error parsing Base64: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * 获取图片尺寸（自动判断来源）
+ * @param source - 图片 URL 或 Base64 Data URL
+ * @returns 图片尺寸，失败返回 null
+ */
+export async function getImageSize(source: string): Promise<ImageSize | null> {
+  if (source.startsWith("data:")) {
+    return getImageSizeFromDataUrl(source);
+  }
+  
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    return getImageSizeFromUrl(source);
+  }
+  
+  return null;
+}
+
+/**
+ * 生成 QQBot markdown 图片格式
+ * 格式: ![#宽px #高px](url)
+ * 
+ * @param url - 图片 URL
+ * @param size - 图片尺寸，如果为 null 则使用默认尺寸
+ * @returns QQBot markdown 图片字符串
+ */
+export function formatQQBotMarkdownImage(url: string, size: ImageSize | null): string {
+  const { width, height } = size ?? DEFAULT_IMAGE_SIZE;
+  return `![#${width}px #${height}px](${url})`;
+}
+
+/**
+ * 检查 markdown 图片是否已经包含 QQBot 格式的尺寸信息
+ * 格式: ![#宽px #高px](url)
+ */
+export function hasQQBotImageSize(markdownImage: string): boolean {
+  return /!\[#\d+px\s+#\d+px\]/.test(markdownImage);
+}
+
+/**
+ * 从已有的 QQBot 格式 markdown 图片中提取尺寸
+ * 格式: ![#宽px #高px](url)
+ */
+export function extractQQBotImageSize(markdownImage: string): ImageSize | null {
+  const match = markdownImage.match(/!\[#(\d+)px\s+#(\d+)px\]/);
+  if (match) {
+    return { width: parseInt(match[1], 10), height: parseInt(match[2], 10) };
+  }
+  return null;
+}