@izhimu/qq 0.1.1

package/dist/src/utils/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions for QQ NapCat plugin
+ */
+/**
+ * Generate a unique message ID for OpenClaw
+ */
+export declare function generateMessageId(): string;
+/**
+ * Generate a unique echo ID for request correlation
+ */
+export declare function generateEchoId(): string;
+/**
+ * Convert NapCat integer message ID to string
+ */
+export declare function messageIdToString(messageId: number | string): string;
+/**
+ * Map common QQ face IDs to emoji
+ */
+export declare const FACE_ID_TO_EMOJI: Record<string, string>;
+/**
+ * Get emoji for QQ face ID
+ * For unknown IDs, shows the ID for reference
+ */
+export declare function getEmojiForFaceId(faceId: string): string;
+/**
+ * Check if a string is a valid URL
+ */
+export declare function isValidUrl(str: string): boolean;
+/**
+ * Extract URL from image data
+ * Returns the URL if valid, otherwise returns undefined
+ */
+export declare function extractImageUrl(data: {
+    url?: string;
+    file?: string;
+}): string | undefined;
+/**
+ * Calculate exponential backoff delay
+ */
+export declare function calculateBackoff(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Chunk an array into smaller arrays
+ */
+export declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * Get a human-readable message for a WebSocket close code
+ */
+export declare function getCloseCodeMessage(code: number): string;
+export { CQCodeUtils, CQNode } from './cqcode.js';
+export { Logger } from './log.js';
+export { MarkdownToText, markdownToText, } from './markdown.js';

package/dist/src/utils/index.js

@@ -0,0 +1,250 @@
+/**
+ * Utility functions for QQ NapCat plugin
+ */
+// =============================================================================
+// ID Generation
+// =============================================================================
+let idCounter = 0;
+/**
+ * Generate a unique message ID for OpenClaw
+ */
+export function generateMessageId() {
+    return `qq-${Date.now()}-${++idCounter}`;
+}
+/**
+ * Generate a unique echo ID for request correlation
+ */
+export function generateEchoId() {
+    return `echo-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+// =============================================================================
+// Message ID Conversion
+// =============================================================================
+/**
+ * Convert NapCat integer message ID to string
+ */
+export function messageIdToString(messageId) {
+    return String(messageId);
+}
+// =============================================================================
+// Face/Emoji Mapping
+// =============================================================================
+/**
+ * Map common QQ face IDs to emoji
+ */
+export const FACE_ID_TO_EMOJI = {
+    '0': '😊',
+    '1': '😅',
+    '2': '☺️',
+    '3': '😄',
+    '4': '😁',
+    '5': '😆',
+    '6': '😃',
+    '7': '😂',
+    '8': '🤣',
+    '9': '😊',
+    '10': '😍',
+    '11': '🥰',
+    '12': '😘',
+    '13': '😗',
+    '14': '😙',
+    '15': '😚',
+    '16': '🥲',
+    '17': '🙂',
+    '18': '🙃',
+    '19': '😉',
+    '20': '😌',
+    '21': '😍',
+    '22': '🥰',
+    '23': '😘',
+    '24': '😗',
+    '25': '😙',
+    '26': '😚',
+    '27': '😋',
+    '28': '😛',
+    '29': '😝',
+    '30': '😜',
+    '31': '🤪',
+    '32': '🤨',
+    '33': '🧐',
+    '34': '🤓',
+    '35': '😎',
+    '36': '🤩',
+    '37': '🥳',
+    '38': '😏',
+    '39': '😒',
+    '40': '😞',
+    '41': '😔',
+    '42': '😟',
+    '43': '😕',
+    '44': '🙁',
+    '45': '😣',
+    '46': '😖',
+    '47': '😫',
+    '48': '😩',
+    '49': '🥺',
+    '50': '😢',
+    '51': '😭',
+    '52': '😤',
+    '53': '😠',
+    '54': '😡',
+    '55': '🤬',
+    '56': '🤯',
+    '57': '😳',
+    '58': '🥵',
+    '59': '🥶',
+    '60': '😱',
+    '61': '😨',
+    '62': '😰',
+    '63': '😥',
+    '64': '😓',
+    '65': '🤗',
+    '66': '🤔',
+    '67': '🤭',
+    '68': '🤫',
+    '69': '🤥',
+    '70': '😶',
+    '71': '😐',
+    '72': '😑',
+    '73': '😬',
+    '74': '🙄',
+    '75': '😯',
+    '76': '😦',
+    '77': '😧',
+    '78': '😮',
+    '79': '😲',
+    '80': '🥱',
+    '81': '😴',
+    '82': '🤤',
+    '83': '😪',
+    '84': '😵',
+    '85': '🤐',
+    '86': '🥴',
+    '87': '🤢',
+    '88': '🤮',
+    '89': '🤧',
+    '90': '😷',
+    '91': '🤒',
+    '92': '🤕',
+    '93': '🤑',
+    '94': '🤠',
+    '95': '😈',
+    '96': '👿',
+    '97': '👹',
+    '98': '👺',
+    '99': '🤡',
+    '100': '💩',
+    '101': '👻',
+    '102': '💀',
+    '103': '☠️',
+    '104': '👽',
+    '105': '👾',
+    '106': '🤖',
+    '107': '🎃',
+    '108': '😺',
+    '109': '😸',
+    '110': '😹',
+    '111': '😻',
+    '112': '😼',
+    '113': '😽',
+    '114': '🙀',
+    '115': '😿',
+    '116': '😾',
+};
+/**
+ * Get emoji for QQ face ID
+ * For unknown IDs, shows the ID for reference
+ */
+export function getEmojiForFaceId(faceId) {
+    return FACE_ID_TO_EMOJI[faceId] || `[表情:${faceId}]`;
+}
+// =============================================================================
+// URL Validation
+// =============================================================================
+/**
+ * Check if a string is a valid URL
+ */
+export function isValidUrl(str) {
+    try {
+        new URL(str);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract URL from image data
+ * Returns the URL if valid, otherwise returns undefined
+ */
+export function extractImageUrl(data) {
+    if (data.url && isValidUrl(data.url)) {
+        return data.url;
+    }
+    if (data.file && isValidUrl(data.file)) {
+        return data.file;
+    }
+    return undefined;
+}
+// =============================================================================
+// Delay Helpers
+// =============================================================================
+/**
+ * Calculate exponential backoff delay
+ */
+export function calculateBackoff(attempt, baseMs = 1000, maxMs = 30000) {
+    const delay = baseMs * Math.pow(2, attempt);
+    return Math.min(delay, maxMs);
+}
+// =============================================================================
+// Array Helpers
+// =============================================================================
+/**
+ * Chunk an array into smaller arrays
+ */
+export function chunk(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+// =============================================================================
+// WebSocket Helpers
+// =============================================================================
+/**
+ * Get a human-readable message for a WebSocket close code
+ */
+export function getCloseCodeMessage(code) {
+    const messages = {
+        1000: 'Normal closure',
+        1001: 'Going away',
+        1002: 'Protocol error',
+        1003: 'Unsupported data',
+        1004: 'Reserved',
+        1005: 'No status received',
+        1006: 'Abnormal closure',
+        1007: 'Invalid frame payload data',
+        1008: 'Policy violation',
+        1009: 'Message too big',
+        1010: 'Missing extension',
+        1011: 'Internal error',
+        1012: 'Service restart',
+        1013: 'Try again later',
+        1014: 'Bad gateway',
+        1015: 'TLS handshake',
+    };
+    return messages[code] ?? `Unknown close code: ${code}`;
+}
+// =============================================================================
+// CQ Code Utilities
+// =============================================================================
+export { CQCodeUtils } from './cqcode.js';
+// =============================================================================
+// Log Utilities
+// =============================================================================
+export { Logger } from './log.js';
+// =============================================================================
+// Markdown Utilities
+// =============================================================================
+export { MarkdownToText, markdownToText, } from './markdown.js';

package/dist/src/utils/log.d.ts

@@ -0,0 +1,6 @@
+export declare class Logger {
+    static debug(category: string, message: string, ...args: unknown[]): void;
+    static info(category: string, message: string, ...args: unknown[]): void;
+    static warn(category: string, message: string, ...args: unknown[]): void;
+    static error(category: string, message: string, ...args: unknown[]): void;
+}

package/dist/src/utils/log.js

@@ -0,0 +1,23 @@
+import { getRuntime } from "../core/runtime.js";
+function log() {
+    return getRuntime()?.logging.getChildLogger({ module: 'channel/qq' }) ?? console;
+}
+function param(args) {
+    if (args.length === 0)
+        return '';
+    return ' ' + args.map(arg => typeof arg === 'string' ? arg : JSON.stringify(arg)).join(' ');
+}
+export class Logger {
+    static debug(category, message, ...args) {
+        log().debug?.(`[${category}] ${message}${param(args)}`);
+    }
+    static info(category, message, ...args) {
+        log().info?.(`[${category}] ${message}${param(args)}`);
+    }
+    static warn(category, message, ...args) {
+        log().warn?.(`[${category}] ${message}${param(args)}`);
+    }
+    static error(category, message, ...args) {
+        log().error?.(`[${category}] ${message}${param(args)}`);
+    }
+}

package/dist/src/utils/markdown.d.ts

@@ -0,0 +1,29 @@
+export declare class MarkdownToText {
+    private codeBlockStore;
+    private maskPrefix;
+    private maskCounter;
+    /**
+     * 主入口：将 Markdown 转换为纯文本
+     * @param markdown 原始 Markdown 字符串
+     */
+    convert(markdown: string): string;
+    /**
+     * 保护代码块
+     * 支持 ```language 和 ~~~ 两种写法
+     */
+    private maskCodeBlocks;
+    /**
+     * 保护行内代码
+     * `code` -> 使用单引号包裹，区别于普通文本
+     */
+    private maskInlineCode;
+    /**
+     * 还原被掩码的内容
+     */
+    private unmaskContent;
+    /**
+     * HTML 实体解码
+     */
+    private decodeHtmlEntities;
+}
+export declare const markdownToText: (md: string) => string;

package/dist/src/utils/markdown.js

@@ -0,0 +1,137 @@
+export class MarkdownToText {
+    // 用于暂存被保护的代码块，防止被正则误伤
+    codeBlockStore = new Map();
+    maskPrefix = '%%MD_MASK_';
+    maskCounter = 0;
+    /**
+     * 主入口：将 Markdown 转换为纯文本
+     * @param markdown 原始 Markdown 字符串
+     */
+    convert(markdown) {
+        if (!markdown)
+            return '';
+        // 1. 初始化
+        this.codeBlockStore.clear();
+        this.maskCounter = 0;
+        let text = markdown;
+        // --- 阶段 1: 保护性预处理 (Protect) ---
+        // 必须最先执行，防止代码里的注释 # 被当成标题，或 ** 被当成粗体
+        text = this.maskCodeBlocks(text);
+        text = this.maskInlineCode(text);
+        // --- 阶段 2: 结构化转换 (Structure) ---
+        // 2.1 清理 HTML 标签 (保留 <br> 的换行效果)
+        text = text.replace(/<br\s*\/?>/gi, '\n');
+        text = text.replace(/<hr\s*\/?>/gi, '\n────────────────────\n');
+        text = text.replace(/<[^>]+>/g, ''); // 移除剩余所有标签
+        // 2.2 标题 (Headers) -> 转换为视觉醒目的文本
+        // H1/H2 使用双线/单线分隔，H3+ 使用括号包裹
+        text = text.replace(/^#\s+(.*)$/gm, '\n$1\n════════════════════\n');
+        text = text.replace(/^##\s+(.*)$/gm, '\n$1\n────────────────────\n');
+        text = text.replace(/^(#{3,6})\s+(.*)$/gm, '\n【 $2 】\n');
+        // 2.3 水平分割线 (---, ***, ___)
+        text = text.replace(/^(-\s*?|\*\s*?|_\s*?){3,}\s*$/gm, '────────────────────');
+        // 2.4 引用 (Blockquotes) -> 使用竖线前缀
+        // 处理多级引用 >> Text
+        text = text.replace(/^(>+)\s?(.*)$/gm, (_match, _arrows, content) => {
+            return `▎ ${content}`;
+        });
+        // 2.5 任务列表 (Task Lists)
+        text = text.replace(/^(\s*)-\s\[x]\s/gim, '$1✅ '); // 完成
+        text = text.replace(/^(\s*)-\s\[\s]\s/gim, '$1⬜ '); // 未完成
+        // 2.6 无序与有序列表 (Lists)
+        // 保留 $1 (缩进空格)，将 -/*/+ 替换为 •
+        text = text.replace(/^(\s*)[-*+]\s+(.*)$/gm, '$1• $2');
+        // 有序列表 1. 2. 通常不需要改动，保留原样即可
+        // 2.7 表格 (Tables)
+        // 移除对齐行 |---|---|
+        text = text.replace(/^\s*\|?[\s\-:|]+\|?\s*$/gm, '');
+        // 将 | Cell | Cell | 转换为空格分隔，尽量保持一行
+        text = text.replace(/^\|(.*)\|$/gm, (_match, content) => {
+            // 移除首尾管道符，中间管道符变为空格
+            return content.split('|').map((s) => s.trim()).join('  ');
+        });
+        // --- 阶段 3: 行内格式清理 (Inline Formatting) ---
+        // 3.1 粗体 (Bold) -> 使用中文引号或双星号强调
+        // 使用 [\s\S] 确保匹配跨行粗体
+        text = text.replace(/(\*\*|__)([\s\S]*?)\1/g, '“$2”');
+        // 3.2 斜体 (Italic) -> 直接移除符号，纯文本很难表现斜体
+        // 注意：必须在处理完粗体后处理斜体
+        text = text.replace(/([*_])([\s\S]*?)\1/g, '$2');
+        // 3.3 删除线 (Strikethrough) -> 移除内容或仅移除符号？通常仅移除符号
+        text = text.replace(/~~([\s\S]*?)~~/g, '$1');
+        // 3.4 图片 (Images) -> 转换为占位符
+        text = text.replace(/!\[([^\]]*)]\(([^)]+)\)/g, (_match, alt) => {
+            return `[图片: ${alt || 'Image'}]`;
+        });
+        // 3.5 链接 (Links) -> Text (URL)
+        // 排除锚点链接或空链接
+        text = text.replace(/\[([^\]]+)]\(([^)]+)\)/g, '$1 ($2)');
+        // 处理自动链接 <http://example.com>
+        text = text.replace(/<((?:https?|ftp|email):[^>]+)>/g, '$1');
+        // --- 阶段 4: 还原与收尾 (Restore & Finalize) ---
+        // 4.1 还原代码块
+        text = this.unmaskContent(text);
+        // 4.2 解码 HTML 实体 (&amp; -> &)
+        text = this.decodeHtmlEntities(text);
+        // 4.3 最终排版优化
+        // 移除段首段尾多余空白，将连续3个以上换行压缩为2个（段落间距）
+        text = text.replace(/\n{3,}/g, '\n\n').trim();
+        return text;
+    }
+    /**
+     * 保护代码块
+     * 支持 ```language 和 ~~~ 两种写法
+     */
+    maskCodeBlocks(text) {
+        // 匹配 3个或更多反引号/波浪线
+        const codeBlockRegex = /(`{3,}|~{3,})(\w*)\n([\s\S]*?)\1/g;
+        return text.replace(codeBlockRegex, (_match, _fence, lang, code) => {
+            const key = `${this.maskPrefix}BLOCK_${this.maskCounter++}`;
+            const langTag = lang ? ` [${lang}]` : '';
+            // 构造美观的代码块样式
+            const formatted = `\n────────────────────${langTag}\n${code.replace(/^\n+|\n+$/g, '')}\n────────────────────\n`;
+            this.codeBlockStore.set(key, formatted);
+            return key;
+        });
+    }
+    /**
+     * 保护行内代码
+     * `code` -> 使用单引号包裹，区别于普通文本
+     */
+    maskInlineCode(text) {
+        return text.replace(/`([^`]+)`/g, (_match, code) => {
+            const key = `${this.maskPrefix}INLINE_${this.maskCounter++}`;
+            this.codeBlockStore.set(key, ` ‘${code}’ `); // 加空格防止粘连
+            return key;
+        });
+    }
+    /**
+     * 还原被掩码的内容
+     */
+    unmaskContent(text) {
+        // 使用正则全局匹配所有 mask key
+        const maskRegex = new RegExp(`${this.maskPrefix}\\w+_\\d+`, 'g');
+        return text.replace(maskRegex, (key) => {
+            return this.codeBlockStore.get(key) || '';
+        });
+    }
+    /**
+     * HTML 实体解码
+     */
+    decodeHtmlEntities(text) {
+        const entities = {
+            '&nbsp;': ' ',
+            '&amp;': '&',
+            '&lt;': '<',
+            '&gt;': '>',
+            '&quot;': '"',
+            '&apos;': "'",
+            '&#39;': "'",
+            '&copy;': '©',
+            '&reg;': '®'
+        };
+        return text.replace(/&[a-z0-9#]+;/gi, (entity) => entities[entity] || entity);
+    }
+}
+// 导出单例辅助函数，方便直接调用
+export const markdownToText = (md) => new MarkdownToText().convert(md);

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "qq",
+  "name": "QQ",
+  "channels": ["qq"],
+  "description": "QQ channel plugin for OpenClaw using NapCat WebSocket API",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@izhimu/qq",
+  "version": "0.1.1",
+  "description": "A QQ channel plugin for OpenClaw using NapCat WebSocket",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "openclaw.plugin.json"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public",
+    "release": "npm run release:patch"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "qq"
+  ],
+  "author": "izhimu",
+  "license": "MIT",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "install": {
+      "npmSpec": "@izhimu/qq",
+      "localPath": "extensions/qq",
+      "defaultChoice": "npm"
+    }
+  },
+  "peerDependencies": {
+    "openclaw": "^2026.2.1"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.0",
+    "openclaw": "^2026.2.1",
+    "typescript": "^5.0.0"
+  }
+}