@izhimu/qq 0.1.1

package/dist/src/core/request.js

@@ -0,0 +1,115 @@
+import { Logger as log } from "../utils/index.js";
+import { setContextStatus, getContext, getConnection } from "./runtime.js";
+import { handleGroupMessage, handlePrivateMessage, handlePokeEvent } from "./dispatch.js";
+import { failResp } from "./connection.js";
+/**
+ * 事件监听
+ * @param event
+ */
+export async function eventListener(event) {
+    log.debug("request", `Received event: ${event.post_type}`);
+    const context = getContext();
+    if (!context) {
+        log.warn("request", `No gateway context`);
+        return;
+    }
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return;
+    }
+    switch (event.post_type) {
+        case "message":
+            setContextStatus({
+                lastInboundAt: Date.now(),
+            });
+            if (event.message_type === "group" && event.group_id) {
+                await handleGroupMessage({
+                    time: event.time,
+                    self_id: event.self_id,
+                    message_id: event.message_id ?? 0,
+                    group_id: event.group_id,
+                    user_id: event.user_id,
+                    message: event.message ?? [],
+                    raw_message: event.raw_message ?? '',
+                    sender: event.sender,
+                });
+            }
+            else if (event.message_type === "private") {
+                await handlePrivateMessage({
+                    time: event.time,
+                    self_id: event.self_id,
+                    message_id: event.message_id ?? 0,
+                    user_id: event.user_id,
+                    message: event.message ?? [],
+                    raw_message: event.raw_message ?? '',
+                    sender: event.sender,
+                });
+            }
+            break;
+        case "notice":
+            if (event.target_id) {
+                const isPokeEvent = event.notice_type === "poke" ||
+                    (event.notice_type === "notify" && event.sub_type === "poke");
+                if (isPokeEvent) {
+                    await handlePokeEvent({
+                        user_id: event.user_id,
+                        target_id: event.target_id,
+                        group_id: event.group_id,
+                        raw_info: event.raw_info,
+                    });
+                }
+            }
+            break;
+        default:
+            log.debug("request", `Unhandled event type: ${event.post_type}`);
+    }
+}
+/**
+ * 发送消息
+ * @param params
+ */
+export async function sendMsg(params) {
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return failResp();
+    }
+    return connection.sendRequest("send_msg", params);
+}
+/**
+ * 获取消息
+ * @param params
+ */
+export async function getMsg(params) {
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return failResp();
+    }
+    return connection.sendRequest("get_msg", params);
+}
+/**
+ * 获取文件
+ * @param params
+ */
+export async function getFile(params) {
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return failResp();
+    }
+    return connection.sendRequest("get_file", params);
+}
+/**
+ * 设置输入状态
+ * @param params
+ */
+export async function setInputStatus(params) {
+    const connection = getConnection();
+    if (!connection) {
+        log.warn("request", `No connection available`);
+        return failResp();
+    }
+    return connection.sendRequest("set_input_status", params);
+}

package/dist/src/core/runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plugin Runtime Storage
+ * Stores the PluginRuntime for access in gateway handlers
+ */
+import type { ChannelAccountSnapshot, ChannelGatewayContext, PluginRuntime } from "openclaw/plugin-sdk";
+import type { QQConfig } from "../types/index.js";
+import { ConnectionManager } from "./connection.js";
+export declare function setRuntime(next: PluginRuntime): void;
+export declare function getRuntime(): PluginRuntime | null;
+export declare function setContext(next: ChannelGatewayContext<QQConfig>): void;
+export declare function getContext(): ChannelGatewayContext<QQConfig> | null;
+export declare function clearContext(): void;
+export declare function setContextStatus(next: Omit<ChannelAccountSnapshot, 'accountId'>): void;
+export declare function setConnection(next: ConnectionManager): void;
+export declare function getConnection(): ConnectionManager | null;
+export declare function clearConnection(): void;

package/dist/src/core/runtime.js

@@ -0,0 +1,48 @@
+/**
+ * Plugin Runtime Storage
+ * Stores the PluginRuntime for access in gateway handlers
+ */
+// =============================================================================
+// Runtime
+// =============================================================================
+let runtime = null;
+export function setRuntime(next) {
+    runtime = next;
+}
+export function getRuntime() {
+    return runtime;
+}
+// =============================================================================
+// Context
+// =============================================================================
+let context = null;
+export function setContext(next) {
+    context = next;
+}
+export function getContext() {
+    return context;
+}
+export function clearContext() {
+    context = null;
+}
+export function setContextStatus(next) {
+    if (context) {
+        context.setStatus({
+            ...context.getStatus(),
+            ...next,
+        });
+    }
+}
+// =============================================================================
+// Connection
+// =============================================================================
+let connection = null;
+export function setConnection(next) {
+    connection = next;
+}
+export function getConnection() {
+    return connection;
+}
+export function clearConnection() {
+    connection = null;
+}

package/dist/src/onboarding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * QQ NapCat CLI Onboarding Adapter
+ *
+ * 提供 openclaw onboard 命令的交互式配置支持
+ */
+import type { ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+/**
+ * QQ NapCat Onboarding Adapter
+ */
+export declare const qqOnboardingAdapter: ChannelOnboardingAdapter;

package/dist/src/onboarding.js

@@ -0,0 +1,98 @@
+import { CHANNEL_ID, resolveQQAccount } from "./core/config.js";
+/**
+ * QQ NapCat Onboarding Adapter
+ */
+export const qqOnboardingAdapter = {
+    channel: CHANNEL_ID,
+    getStatus: async (ctx) => {
+        const { cfg } = ctx;
+        const config = cfg.channels?.[CHANNEL_ID];
+        const configured = Boolean(config.wsUrl);
+        return {
+            channel: CHANNEL_ID,
+            configured,
+            statusLines: configured
+                ? ["QQ (NapCat): 已配置"]
+                : ["QQ (NapCat): 未配置"],
+            selectionHint: configured ? "已配置" : "未配置",
+            quickstartScore: configured ? 1 : 10,
+        };
+    },
+    configure: async (ctx) => {
+        const { cfg, prompter } = ctx;
+        let next = cfg;
+        const resolvedAccount = resolveQQAccount({ cfg });
+        const accountConfigured = Boolean(resolvedAccount.wsUrl);
+        // 显示帮助
+        if (!accountConfigured) {
+            await prompter.note([
+                "1) 确保已安装 NapCat: https://github.com/NapNeko/NapCatQQ",
+                "2) 在 NapCat 配置中启用 WebSocket (正向 WS)",
+                "3) 默认地址: ws://localhost:3001",
+                "4) 如需访问控制，可设置 accessToken",
+                "",
+                "NapCat 文档: https://napneko.github.io/",
+            ].join("\n"), "QQ NapCat 配置");
+        }
+        let wsUrl = null;
+        let accessToken = null;
+        // 检查是否已配置
+        if (accountConfigured) {
+            const keep = await prompter.confirm({
+                message: "QQ NapCat 已配置，是否保留当前配置？",
+                initialValue: true,
+            });
+            if (!keep) {
+                wsUrl = String(await prompter.text({
+                    message: "请输入 NapCat WebSocket URL",
+                    placeholder: "ws://localhost:3001",
+                    initialValue: resolvedAccount.wsUrl,
+                    validate: (value) => (value?.trim() ? undefined : "WebSocket URL 不能为空"),
+                })).trim();
+                accessToken = String(await prompter.text({
+                    message: "请输入 Access Token (可选，直接回车跳过)",
+                    placeholder: "留空表示不使用 token",
+                    initialValue: resolvedAccount.accessToken || undefined,
+                })).trim();
+            }
+        }
+        else {
+            // 新配置
+            wsUrl = String(await prompter.text({
+                message: "请输入 NapCat WebSocket URL",
+                placeholder: "ws://localhost:3001",
+                validate: (value) => (value?.trim() ? undefined : "WebSocket URL 不能为空"),
+            })).trim();
+            accessToken = String(await prompter.text({
+                message: "请输入 Access Token (可选，直接回车跳过)",
+                placeholder: "留空表示不使用 token",
+            })).trim();
+        }
+        // 应用配置
+        if (wsUrl) {
+            next = {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    qq: {
+                        ...next.channels?.[CHANNEL_ID],
+                        enabled: true,
+                        wsUrl,
+                        ...(accessToken ? { accessToken } : {}),
+                    },
+                },
+            };
+        }
+        return { cfg: next };
+    },
+    disable: (cfg) => ({
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            qq: {
+                ...cfg.channels?.[CHANNEL_ID],
+                enabled: false,
+            }
+        },
+    }),
+};

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

@@ -0,0 +1,261 @@
+/**
+ * NapCat WebSocket API Types
+ * Based on NapCat OneBot 11 implementation
+ */
+export interface NapCatReq<T = unknown> {
+    action: NapCatAction;
+    params?: T;
+    echo?: string;
+}
+export interface NapCatResp<T = unknown> {
+    status: 'ok' | 'failed';
+    retcode: number;
+    msg: string;
+    data?: T;
+    echo?: string;
+}
+export type NapCatAction = 'send_msg' | 'get_msg' | 'get_status' | 'get_file' | 'set_input_status';
+export interface NapCatEvent {
+    time: number;
+    self_id: number;
+    post_type: NapCatPostType;
+}
+export type NapCatPostType = 'message' | 'message_sent' | 'message_sent_type' | 'message_private_sent_type' | 'notice' | 'request' | 'meta_event';
+export interface NapCatMetaEvent extends NapCatEvent {
+    post_type: 'meta_event';
+    meta_event_type: 'lifecycle' | 'heartbeat';
+    sub_type?: 'connect' | 'disconnect' | 'enable' | 'disable';
+}
+export type NapCatMessage = NapCatTextSegment | NapCatAtSegment | NapCatImageSegment | NapCatReplySegment | NapCatFaceSegment | NapCatRecordSegment | NapCatFileSegment | NapCatJsonSegment | NapCatUnknownSegment;
+export interface NapCatTextSegment {
+    type: 'text';
+    data: {
+        text: string;
+    };
+}
+export interface NapCatAtSegment {
+    type: 'at';
+    data: {
+        qq: string;
+        name?: string;
+    };
+}
+export interface NapCatImageSegment {
+    type: 'image';
+    data: {
+        file: string;
+        url?: string;
+        type?: string;
+        summary?: string;
+    };
+}
+export interface NapCatReplySegment {
+    type: 'reply';
+    data: {
+        id: string;
+    };
+}
+export interface NapCatFaceSegment {
+    type: 'face';
+    data: {
+        id: string;
+    };
+}
+export interface NapCatRecordSegment {
+    type: 'record';
+    data: {
+        file: string;
+        path?: string;
+        url?: string;
+        file_size?: string;
+    };
+}
+export interface NapCatFileSegment {
+    type: 'file';
+    data: {
+        file: string;
+        url?: string;
+        file_id?: string;
+        file_size?: string;
+    };
+}
+export interface NapCatJsonSegment {
+    type: 'json';
+    data: {
+        data: string;
+    };
+}
+export interface NapCatUnknownSegment {
+    type: string;
+    data: Record<string, unknown>;
+}
+export interface QQConfig {
+    wsUrl: string;
+    accessToken?: string;
+    enabled: boolean;
+}
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'failed';
+export interface ConnectionStatus {
+    state: ConnectionState;
+    lastConnected?: number;
+    lastAttempted?: number;
+    error?: string;
+    reconnectAttempts?: number;
+}
+export interface OpenClawTextContent {
+    type: 'text';
+    text: string;
+}
+export interface OpenClawAtContent {
+    type: 'at';
+    userId: string;
+    isAll?: boolean;
+}
+export interface OpenClawImageContent {
+    type: 'image';
+    url: string;
+    /** Optional summary/description (e.g., "[动画表情]" for animated stickers) */
+    summary?: string;
+}
+export interface OpenClawReplyContent {
+    type: 'reply';
+    messageId: string;
+}
+export interface OpenClawAudioContent {
+    type: 'audio';
+    /** Local file path to the audio file */
+    path: string;
+    /** Optional URL for downloading the audio */
+    url?: string;
+    /** File name */
+    file: string;
+    /** File size in bytes */
+    fileSize?: number;
+}
+export interface OpenClawJsonContent {
+    type: 'json';
+    /** Raw JSON data string */
+    data: string;
+    /** Optional display text/prompt from the JSON */
+    prompt?: string;
+}
+export interface OpenClawFileContent {
+    type: 'file';
+    fileId: string;
+    fileSize?: number;
+}
+export type OpenClawMessage = OpenClawTextContent | OpenClawAtContent | OpenClawImageContent | OpenClawReplyContent | OpenClawAudioContent | OpenClawJsonContent | OpenClawFileContent;
+export interface PendingRequest {
+    resolve: (response: NapCatResp) => void;
+    reject: (error: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+/**
+ * Runtime logger interface from OpenClaw plugin-sdk
+ * (Not exported from openclaw/package, defined locally)
+ */
+export interface RuntimeLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+/**
+ * Standard outbound delivery result
+ */
+export interface OutboundDeliveryResult {
+    /** Channel identifier */
+    channel: string;
+    /** Message ID returned by the channel */
+    messageId: string;
+    /** Error if delivery failed */
+    error?: Error;
+    /** Timestamp of delivery */
+    deliveredAt?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Health status for connection
+ */
+export interface HealthStatus {
+    healthy: boolean;
+    lastHeartbeatAt: number;
+    latencyMs?: number;
+    consecutiveFailures: number;
+}
+/**
+ * Sender information in get_msg response
+ */
+export interface GetMsgSender {
+    user_id: number;
+    nickname: string;
+    card?: string;
+}
+export interface SendMsgReq {
+    message_type: 'private' | 'group';
+    user_id?: string;
+    group_id?: string;
+    message: string | NapCatMessage[];
+}
+export interface SendMsgResp {
+    message_id: number;
+}
+export interface GetMsgReq {
+    message_id: number;
+}
+export interface GetMsgResp {
+    self_id: number;
+    user_id: string;
+    time: number;
+    message_id: number;
+    message_seq: number;
+    real_id: number;
+    real_seq: string;
+    message_type: 'private' | 'group';
+    sender: GetMsgSender;
+    raw_message: string;
+    font: number;
+    sub_type?: string;
+    message: string | NapCatMessage[];
+    message_format: string;
+    post_type: string;
+    group_id?: number;
+    emoji_likes_list?: unknown[];
+}
+export interface GetFileReq {
+    file?: string;
+    file_id?: string;
+}
+export interface GetFileResp {
+    file?: string;
+    url?: string;
+    file_size?: string;
+    file_name?: string;
+    base64?: string;
+}
+export interface SetInputStatusReq {
+    user_id: string;
+    event_type: 0 | 1 | 2;
+}
+export interface DispatchMessageMedia {
+    type?: string;
+    path?: string;
+    url?: string;
+}
+export interface DispatchMessageReply {
+    id?: string;
+    content?: string;
+    sender?: string;
+}
+export interface DispatchMessageParams {
+    chatType: 'direct' | 'group';
+    chatId: string;
+    senderId: string;
+    senderName?: string;
+    messageId: string;
+    content: string;
+    media?: DispatchMessageMedia;
+    reply?: DispatchMessageReply;
+    timestamp: number;
+}

package/dist/src/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * NapCat WebSocket API Types
+ * Based on NapCat OneBot 11 implementation
+ */
+export {};

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

@@ -0,0 +1,33 @@
+/**
+ * CQCode 节点接口
+ */
+export interface CQNode {
+    type: string;
+    data: Record<string, string>;
+}
+/**
+ * 生产级 CQCode 解析工具类
+ */
+export declare class CQCodeUtils {
+    private static readonly UNESCAPE_MAP;
+    private static readonly UNESCAPE_REGEX;
+    /**
+     * 反转义字符串
+     * 使用单次正则替换，避免多次遍历和嵌套转义带来的逻辑错误
+     */
+    private static unescape;
+    /**
+     * 解析 CQ 码字符串为 JSON 对象数组
+     * @param text 原始消息字符串
+     */
+    static parse(text: string): CQNode[];
+    /**
+     * 辅助方法：从解析结果中提取所有纯文本内容（去除 CQ 码）
+     * 场景：用于生成通知摘要、日志记录等
+     */
+    static getTextOnly(nodes: CQNode[]): string;
+    /**
+     * 辅助方法：判断消息是否提及了某个 QQ
+     */
+    static isMentioned(nodes: CQNode[], qq: string | number): boolean;
+}

package/dist/src/utils/cqcode.js

@@ -0,0 +1,102 @@
+/**
+ * 生产级 CQCode 解析工具类
+ */
+export class CQCodeUtils {
+    // 定义转义映射表
+    static UNESCAPE_MAP = {
+        '[': '[',
+        ']': ']',
+        ',': ',',
+        '&': '&',
+    };
+    // 定义转义正则（全局匹配）
+    static UNESCAPE_REGEX = /[|]|,|&/g;
+    /**
+     * 反转义字符串
+     * 使用单次正则替换，避免多次遍历和嵌套转义带来的逻辑错误
+     */
+    static unescape(str) {
+        if (!str)
+            return '';
+        return str.replace(this.UNESCAPE_REGEX, (match) => this.UNESCAPE_MAP[match] || match);
+    }
+    /**
+     * 解析 CQ 码字符串为 JSON 对象数组
+     * @param text 原始消息字符串
+     */
+    static parse(text) {
+        if (!text)
+            return [];
+        const nodes = [];
+        const regex = /\[CQ:([^\]]+)]/g;
+        let lastIndex = 0;
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            // 1. 提取 CQ 码前的纯文本
+            if (match.index > lastIndex) {
+                const textContent = text.substring(lastIndex, match.index);
+                nodes.push({
+                    type: 'text',
+                    data: { text: this.unescape(textContent) },
+                });
+            }
+            // 2. 解析 CQ 码主体
+            const content = match[1];
+            const parts = content.split(',');
+            const type = parts[0];
+            // 使用 Object.create(null) 防止原型污染，或者在赋值时做检查
+            const data = {};
+            for (let i = 1; i < parts.length; i++) {
+                const part = parts[i];
+                if (!part)
+                    continue; // 跳过空段（处理类似 [CQ:at,,qq=1] 的情况）
+                const eqIndex = part.indexOf('=');
+                let key;
+                let value;
+                if (eqIndex !== -1) {
+                    key = part.substring(0, eqIndex).trim(); // key 通常不含空格，安全起见 trim
+                    value = this.unescape(part.substring(eqIndex + 1));
+                }
+                else {
+                    key = part.trim();
+                    value = '';
+                }
+                // 🛡️ 安全检查：防止原型污染
+                if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                    continue;
+                }
+                if (key) {
+                    data[key] = value;
+                }
+            }
+            nodes.push({ type, data });
+            lastIndex = regex.lastIndex;
+        }
+        // 3. 提取剩余的纯文本
+        if (lastIndex < text.length) {
+            const textContent = text.substring(lastIndex);
+            nodes.push({
+                type: 'text',
+                data: { text: this.unescape(textContent) },
+            });
+        }
+        return nodes;
+    }
+    /**
+     * 辅助方法：从解析结果中提取所有纯文本内容（去除 CQ 码）
+     * 场景：用于生成通知摘要、日志记录等
+     */
+    static getTextOnly(nodes) {
+        return nodes
+            .filter(node => node.type === 'text')
+            .map(node => node.data.text)
+            .join('');
+    }
+    /**
+     * 辅助方法：判断消息是否提及了某个 QQ
+     */
+    static isMentioned(nodes, qq) {
+        const targetQQ = String(qq);
+        return nodes.some(node => node.type === 'at' && (node.data.qq === targetQQ || node.data.qq === 'all'));
+    }
+}