@izhimu/qq 0.5.1 → 0.6.0

package/dist/src/channel.js

@@ -1,259 +1,54 @@
-/**
- * QQ NapCat Plugin for OpenClaw
- * Main plugin entry point
- */
-import { DEFAULT_ACCOUNT_ID, buildChannelConfigSchema, setAccountEnabledInConfigSection, deleteAccountFromConfigSection, applyAccountNameToChannelSection, migrateBaseNameToDefaultAccount, normalizeAccountId, waitUntilAbort } from "openclaw/plugin-sdk";
-import { messageIdToString, markdownToText, buildMediaMessage, Logger as log } from "./utils/index.js";
-import { setContext, setContextStatus, clearContext, setConnection, getConnection, clearConnection, setLoginInfo, getContext } from "./core/runtime.js";
-import { ConnectionManager } from "./core/connection.js";
-import { openClawToNapCatMessage } from "./adapters/message.js";
-import { listQQAccountIds, resolveQQAccount, QQConfigSchema, CHANNEL_ID } from "./core/config.js";
+import { DEFAULT_ACCOUNT_ID, createChatChannelPlugin, } from "openclaw/plugin-sdk/core";
+import { createPatchedAccountSetupAdapter } from "openclaw/plugin-sdk/setup";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+import { createScopedChannelConfigAdapter, adaptScopedAccountAccessor, } from "openclaw/plugin-sdk/channel-config-helpers";
+import { formatNormalizedAllowFromEntries } from "openclaw/plugin-sdk/allow-from";
+import { createChannelDirectoryAdapter } from "openclaw/plugin-sdk/directory-runtime";
+import { createAccountStatusSink, runPassiveAccountLifecycle } from "openclaw/plugin-sdk/channel-lifecycle";
+import { createComputedAccountStatusAdapter, createDefaultChannelRuntimeState, } from "openclaw/plugin-sdk/status-helpers";
+import { listQQAccountIds, QQ_CHANNEL, QQConfigSchema, resolveQQAccount } from "./core/config";
 import { eventListener, sendMsg, getStatus, getLoginInfo, getFriendList, getGroupList } from "./core/request.js";
-import { qqOnboardingAdapter } from "./onboarding.js";
-export const qqPlugin = {
-    id: CHANNEL_ID,
-    meta: {
-        id: CHANNEL_ID,
-        label: "QQ",
-        selectionLabel: "QQ",
-        docsPath: "extensions/qq",
-        blurb: "通过 NapCat WebSocket 连接 QQ 机器人",
-        quickstartAllowFrom: true,
-    },
-    capabilities: {
-        chatTypes: ["direct", "group"],
-        reactions: true,
-        reply: true,
-        media: true,
-        blockStreaming: true,
-    },
-    reload: { configPrefixes: [`channels.${CHANNEL_ID}`] },
-    onboarding: qqOnboardingAdapter,
-    config: {
-        listAccountIds: (cfg) => listQQAccountIds(cfg),
-        resolveAccount: (cfg) => resolveQQAccount({ cfg }),
-        isConfigured: (account) => !!account.accessToken?.trim(),
-        setAccountEnabled: ({ cfg, accountId, enabled }) => setAccountEnabledInConfigSection({
-            cfg,
-            sectionKey: "qq",
-            accountId,
-            enabled,
-            allowTopLevel: true,
-        }),
-        deleteAccount: ({ cfg, accountId }) => deleteAccountFromConfigSection({
-            cfg,
-            sectionKey: "qq",
-            accountId,
-        }),
-        describeAccount: (account) => ({
-            accountId: DEFAULT_ACCOUNT_ID,
-            tokenSource: account.accessToken ? "config" : "none"
-        }),
-    },
-    configSchema: buildChannelConfigSchema(QQConfigSchema),
-    setup: {
-        resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
-        applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({
-            cfg: cfg,
-            channelKey: "qq",
-            accountId,
-            name,
-        }),
-        applyAccountConfig: ({ cfg, accountId, input }) => {
-            const namedConfig = applyAccountNameToChannelSection({
-                cfg,
-                channelKey: "qq",
-                accountId,
-                name: input.name,
-            });
-            const next = accountId !== DEFAULT_ACCOUNT_ID ? migrateBaseNameToDefaultAccount({
-                cfg: namedConfig,
-                channelKey: "qq",
-            }) : namedConfig;
-            if (accountId === DEFAULT_ACCOUNT_ID) {
-                return {
-                    ...next,
-                    channels: {
-                        ...next.channels,
-                        qq: {
-                            ...next.channels?.["qq"],
-                            enabled: true,
-                        },
-                    },
-                };
-            }
-            return {
-                ...next,
-                channels: {
-                    ...next.channels,
-                    qq: {
-                        ...next.channels?.["qq"],
-                        enabled: true,
-                        accounts: {
-                            ...next.channels?.["qq"]?.accounts,
-                            [accountId]: {
-                                ...next.channels?.["qq"]?.accounts?.[accountId],
-                                enabled: true,
-                            },
-                        },
-                    },
-                },
-            };
-        }
-    },
-    messaging: {
-        normalizeTarget: (target) => {
-            return target.replace(/^qq:/i, "");
-        },
-        targetResolver: {
-            looksLikeId: (id) => {
-                const normalized = id.replace(/^qq:/i, "");
-                // 支持 private:xxx, group:xxx 格式
-                if (normalized.startsWith("private:") || normalized.startsWith("group:"))
-                    return true;
-                // 支持纯数字QQ号或群号
-                return /^\d+$/.test(normalized);
-            },
-            hint: "private:<qqId> or group:<groupId>",
-        },
-    },
-    outbound: {
-        deliveryMode: "direct",
-        sendText: outboundSend,
-        sendMedia: outboundSend,
-    },
-    status: {
-        defaultRuntime: {
-            accountId: DEFAULT_ACCOUNT_ID,
-            name: "QQ",
-            running: false,
-            connected: false,
-            reconnectAttempts: 0,
-            lastConnectedAt: null,
-            lastDisconnect: null,
-            lastStartAt: null,
-            lastStopAt: null,
-            lastError: null,
-        },
-        buildChannelSummary: ({ snapshot }) => ({
-            configured: snapshot.configured ?? false,
-            running: snapshot.running ?? false,
-            lastStartAt: snapshot.lastStartAt ?? null,
-            lastStopAt: snapshot.lastStopAt ?? null,
-            lastError: snapshot.lastError ?? null,
-            probe: snapshot.probe,
-            lastProbeAt: snapshot.lastProbeAt ?? null,
-        }),
-        probeAccount: async () => {
-            const status = await getStatus();
-            log.debug('gateway', `Probe status: ${status.status}`);
-            setContextStatus({
-                lastProbeAt: Date.now(),
-            });
-            return {
-                ok: status.status === "ok",
-                status: status.retcode,
-                error: status.status === "failed" ? status.msg : null,
-            };
-        },
-        buildAccountSnapshot: ({ account, runtime, probe }) => {
-            return {
-                accountId: DEFAULT_ACCOUNT_ID,
-                name: "QQ",
-                enabled: account.enabled,
-                configured: Boolean(account.wsUrl?.trim()),
-                linked: Boolean(account.wsUrl?.trim()),
-                running: runtime?.running ?? false,
-                connected: runtime?.connected ?? false,
-                lastStartAt: runtime?.lastStartAt ?? null,
-                lastStopAt: runtime?.lastStopAt ?? null,
-                lastError: runtime?.lastError ?? null,
-                lastInboundAt: runtime?.lastInboundAt ?? null,
-                lastOutboundAt: runtime?.lastOutboundAt ?? null,
-                probe,
-                lastProbeAt: runtime?.lastProbeAt ?? null,
-            };
-        },
-    },
-    gateway: {
-        startAccount: async (ctx) => {
-            setContext(ctx);
-            const { account, abortSignal } = ctx;
-            log.info('gateway', `Starting gateway`);
-            setContextStatus({
-                running: true,
-                lastStartAt: Date.now(),
-            });
-            // 检查是否已存在连接
-            const existingConnection = getConnection();
-            if (existingConnection) {
-                log.debug('gateway', `A connection is already running`);
-                return waitUntilAbort(abortSignal);
-            }
-            try {
-                const connection = new ConnectionManager(account);
-                onEvent(connection);
-                await connection.start();
-                setConnection(connection);
-                await loadLoginInfo();
-                log.info('gateway', `Started gateway`);
-                return waitUntilAbort(abortSignal);
-            }
-            catch (error) {
-                log.error('gateway', `Failed to start gateway:`, error);
-                setContextStatus({
-                    lastError: error instanceof Error ? error.message : 'Failed to start gateway',
-                });
-                throw error;
-            }
-        },
-        stopAccount: async (_ctx) => {
-            const connection = getConnection();
-            if (connection) {
-                await connection.stop();
-                clearConnection();
-            }
-            setContextStatus({
-                running: false,
-                lastStopAt: Date.now(),
-            });
-            clearContext();
-        },
-    },
-    directory: {
-        self: async () => {
-            const info = await getLoginInfo();
-            if (!info.data) {
-                return null;
-            }
-            log.debug('directory', `self: ${JSON.stringify(info.data)}`);
-            return {
-                kind: "user",
-                id: info.data.user_id.toString(),
-                name: info.data.nickname,
-            };
-        },
-        listPeers: getFriends,
-        listPeersLive: getFriends,
-        listGroups: getGroups,
-        listGroupsLive: getGroups,
-    },
-    heartbeat: {
-        checkReady: async ({ cfg }) => {
-            const account = resolveQQAccount({ cfg });
-            if (!account.wsUrl) {
-                return { ok: false, reason: "not-configured" };
-            }
-            const connection = getConnection();
-            if (!connection?.isConnected) {
-                return { ok: false, reason: "not-connected" };
-            }
-            return { ok: true, reason: "ok" };
-        },
-    },
-};
+import { buildMediaMessage, Logger as log, markdownToText } from "./utils";
+import { clearConnection, getConnection, setConnection, setLoginInfo } from "./core/runtime";
+import { outboundMessageAdapter } from "./adapters/message";
+import { ConnectionManager } from "./core/connection";
+import { qqSetupWizard } from "./setup-surface";
+import { createInboundHandler } from "./core/dispatch";
+import { getQQRuntime } from "./runtime";
+const formatAllowFromEntry = (entry) => entry
+    .trim()
+    .replace(/^(qq):/i, "")
+    .toLowerCase();
+async function getFriends() {
+    const friendList = await getFriendList();
+    log.debug('directory', `friendList: ${JSON.stringify(friendList.data)}`);
+    return (friendList.data || []).map((friend) => ({
+        kind: "user",
+        id: friend.user_id.toString(),
+        name: friend.nickname,
+    }));
+}
+async function getGroups() {
+    const groupList = await getGroupList();
+    log.debug('directory', `groupList: ${JSON.stringify(groupList.data)}`);
+    return (groupList.data || []).map((group) => ({
+        kind: "group",
+        id: group.group_id.toString(),
+        name: group.group_name,
+    }));
+}
+async function loadLoginInfo() {
+    // 获取登录信息
+    const info = await getLoginInfo();
+    if (info.data) {
+        setLoginInfo({
+            userId: info.data.user_id.toString(),
+            nickname: info.data.nickname,
+        });
+    }
+}
 async function outboundSend(ctx) {
-    const { to, text, mediaUrl, accountId, replyToId } = ctx;
+    const { cfg, to, text, mediaUrl, accountId, replyToId } = ctx;
     log.debug("outbound", `send called - accountId: ${accountId}, to: ${to}, mediaUrl: ${mediaUrl ?? "null"}, replyToId: ${replyToId ?? "none"}`);
     // Parse target (format: private:xxx or group:xxx)
     const parts = to.split(":");
@@ -261,18 +56,9 @@ async function outboundSend(ctx) {
     const chatType = type === "group" ? "group" : "private";
     const chatId = id || to;
     const content = [];
-    const context = getContext();
-    if (!context) {
-        log.warn('dispatch', `No gateway context`);
-        return {
-            channel: CHANNEL_ID,
-            messageId: "",
-            error: new Error(`No gateway context`),
-            deliveredAt: Date.now(),
-        };
-    }
+    const account = resolveQQAccount({ cfg, accountId });
     if (text) {
-        content.push({ type: "text", text: context.account.markdownFormat ? markdownToText(text) : text });
+        content.push({ type: "text", text: account.markdownFormat ? markdownToText(text) : text });
     }
     if (mediaUrl) {
         content.push(buildMediaMessage(mediaUrl));
@@ -283,7 +69,7 @@ async function outboundSend(ctx) {
     if (content.length === 0) {
         log.warn("outbound", `send called with no content - accountId: ${accountId}, to: ${to}, mediaUrl: ${mediaUrl ?? "null"}, replyToId: ${replyToId ?? "none"}`);
         return {
-            channel: CHANNEL_ID,
+            channel: QQ_CHANNEL,
             messageId: "",
             error: new Error(`No content to send`),
             deliveredAt: Date.now(),
@@ -293,58 +79,44 @@ async function outboundSend(ctx) {
         message_type: chatType,
         user_id: chatType === "private" ? chatId : undefined,
         group_id: chatType === "group" ? chatId : undefined,
-        message: openClawToNapCatMessage(content),
+        message: await outboundMessageAdapter(content, account),
     });
     if (response.status === "ok" && response.data) {
-        setContextStatus({ lastOutboundAt: Date.now() });
-        const data = response.data;
-        log.debug("outbound", `send successfully, messageId: ${data.message_id}`);
+        const { message_id } = response.data;
+        log.debug("outbound", `send successfully, messageId: ${message_id}`);
         return {
-            channel: CHANNEL_ID,
-            messageId: messageIdToString(data.message_id),
+            channel: QQ_CHANNEL,
+            messageId: message_id.toString(),
             deliveredAt: Date.now(),
         };
     }
     else {
         log.warn("outbound", `send failed, status: ${response.status}, retcode: ${response.retcode}, msg: ${response.msg ?? "none"}`);
         return {
-            channel: CHANNEL_ID,
+            channel: QQ_CHANNEL,
             messageId: "",
             error: new Error(response.msg || "Send failed"),
             deliveredAt: Date.now(),
         };
     }
 }
-async function getFriends() {
-    const friendList = await getFriendList();
-    log.debug('directory', `friendList: ${JSON.stringify(friendList.data)}`);
-    return (friendList.data || []).map((friend) => ({
-        kind: "user",
-        id: friend.user_id.toString(),
-        name: friend.nickname,
-    }));
-}
-async function getGroups() {
-    const groupList = await getGroupList();
-    log.debug('directory', `groupList: ${JSON.stringify(groupList.data)}`);
-    return (groupList.data || []).map((group) => ({
-        kind: "group",
-        id: group.group_id.toString(),
-        name: group.group_name,
-    }));
-}
-function onEvent(connection) {
-    connection.on("event", (event) => eventListener(event));
+function onEvent(cfg, account, connection, statusSink) {
+    const handleInbound = createInboundHandler({
+        cfg,
+        account,
+        runtime: getQQRuntime(),
+    });
+    connection.on("event", (event) => eventListener(account, event, handleInbound));
     connection.on("state-changed", (status) => {
         log.info('gateway', `Connection state: ${status.state}`);
         if (status.state === "connected") {
-            setContextStatus({
+            statusSink({
                 connected: true,
                 lastConnectedAt: Date.now(),
             });
         }
         else if (status.state === "disconnected" || status.state === "failed") {
-            setContextStatus({
+            statusSink({
                 connected: false,
                 lastError: status.error,
                 lastDisconnect: {
@@ -354,21 +126,168 @@ function onEvent(connection) {
             });
         }
     });
-    connection.on("reconnecting", (info) => {
-        log.info('gateway', `Reconnecting: ${info.reason}, attempt ${info.totalAttempts}`);
-        setContextStatus({
-            lastError: `Reconnecting (${info.reason})`,
-            reconnectAttempts: info.totalAttempts,
-        });
-    });
-}
-async function loadLoginInfo() {
-    // 获取登录信息
-    const info = await getLoginInfo();
-    if (info.data) {
-        setLoginInfo({
-            userId: info.data.user_id.toString(),
-            nickname: info.data.nickname,
-        });
-    }
 }
+export const qqPlugin = createChatChannelPlugin({
+    base: {
+        id: QQ_CHANNEL,
+        meta: {
+            id: QQ_CHANNEL,
+            label: "QQ",
+            selectionLabel: "QQ",
+            detailLabel: "QQ",
+            docsPath: "extensions/qq",
+            docsLabel: "qq",
+            blurb: "Connect OpenClaw to QQ Chat",
+            systemImage: "message",
+            quickstartAllowFrom: true,
+        },
+        capabilities: {
+            chatTypes: ["direct", "group"],
+            reactions: true,
+            reply: true,
+            media: true,
+            blockStreaming: true,
+        },
+        reload: { configPrefixes: [`channels.${QQ_CHANNEL}`] },
+        config: {
+            ...createScopedChannelConfigAdapter({
+                sectionKey: QQ_CHANNEL,
+                listAccountIds: listQQAccountIds,
+                resolveAccount: adaptScopedAccountAccessor(resolveQQAccount),
+                defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+                clearBaseFields: ["name"],
+                resolveAllowFrom: (account) => account.messageDirect.allowFrom,
+                formatAllowFrom: (allowFrom) => formatNormalizedAllowFromEntries({
+                    allowFrom,
+                    normalizeEntry: formatAllowFromEntry,
+                }),
+            }),
+            isConfigured: (account) => !!account.accessToken?.trim(),
+        },
+        configSchema: buildChannelConfigSchema(QQConfigSchema),
+        setup: createPatchedAccountSetupAdapter({
+            channelKey: QQ_CHANNEL,
+            validateInput: ({ input }) => {
+                if (input.useEnv) {
+                    return "The use of environment variables is not supported at this time.";
+                }
+                if (!input.useEnv && !input.token) {
+                    return "QQ Chat requires token";
+                }
+                return null;
+            },
+            buildPatch: (input) => input.token ? { botToken: input.token } : {},
+        }),
+        setupWizard: qqSetupWizard,
+        messaging: {
+            normalizeTarget: (target) => {
+                return target.replace(/^qq:/i, "");
+            },
+            targetResolver: {
+                looksLikeId: (id) => {
+                    const normalized = id.replace(/^qq:/i, "");
+                    // 支持 private:xxx, group:xxx 格式
+                    if (normalized.startsWith("private:") || normalized.startsWith("group:"))
+                        return true;
+                    // 支持纯数字QQ号或群号
+                    return /^\d+$/.test(normalized);
+                },
+                hint: "private:<qqId> or group:<groupId>",
+            },
+        },
+        status: createComputedAccountStatusAdapter({
+            defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+            buildChannelSummary: ({ snapshot }) => ({
+                configured: snapshot.configured ?? false,
+                running: snapshot.running ?? false,
+                lastStartAt: snapshot.lastStartAt ?? null,
+                lastStopAt: snapshot.lastStopAt ?? null,
+                lastError: snapshot.lastError ?? null,
+                probe: snapshot.probe,
+                lastProbeAt: snapshot.lastProbeAt ?? null,
+            }),
+            probeAccount: async () => {
+                const status = await getStatus();
+                log.debug('gateway', `Probe status: ${status.status}`);
+                return {
+                    ok: status.status === "ok",
+                    status: status.retcode,
+                    error: status.status === "failed" ? status.msg : null,
+                };
+            },
+            resolveAccountSnapshot: ({ account }) => ({
+                accountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+                name: "QQ",
+                enabled: account.enabled,
+                configured: Boolean(account.wsUrl?.trim()),
+            })
+        }),
+        gateway: {
+            startAccount: async (ctx) => {
+                const account = ctx.account;
+                const statusSink = createAccountStatusSink({
+                    accountId: account.accountId,
+                    setStatus: ctx.setStatus,
+                });
+                log.info('gateway', `Starting QQ Chat`);
+                statusSink({
+                    running: true,
+                    lastStartAt: Date.now(),
+                });
+                await runPassiveAccountLifecycle({
+                    abortSignal: ctx.abortSignal,
+                    start: async () => {
+                        const connection = new ConnectionManager(account);
+                        onEvent(ctx.cfg, account, connection, statusSink);
+                        await connection.start();
+                        setConnection(connection);
+                        await loadLoginInfo();
+                        log.info('gateway', `Started gateway`);
+                    },
+                    stop: async () => {
+                        const connection = getConnection();
+                        if (connection) {
+                            await connection.stop();
+                            clearConnection();
+                        }
+                    },
+                    onStop: async () => {
+                        statusSink({
+                            running: false,
+                            lastStopAt: Date.now(),
+                        });
+                    },
+                });
+            },
+        },
+        directory: createChannelDirectoryAdapter({
+            self: async () => {
+                const info = await getLoginInfo();
+                if (!info.data) {
+                    return null;
+                }
+                log.debug('directory', `self: ${JSON.stringify(info.data)}`);
+                return {
+                    kind: "user",
+                    id: info.data.user_id.toString(),
+                    name: info.data.nickname,
+                };
+            },
+            listPeers: getFriends,
+            listPeersLive: getFriends,
+            listGroups: getGroups,
+            listGroupsLive: getGroups,
+        }),
+        security: {},
+    },
+    outbound: {
+        base: {
+            deliveryMode: "direct",
+        },
+        attachedResults: {
+            channel: QQ_CHANNEL,
+            sendText: outboundSend,
+            sendMedia: outboundSend,
+        }
+    },
+});

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

@@ -0,0 +1,67 @@
+/**
+ * QQ 频道授权模块
+ *
+ * 使用三明治模式 (Sandwich Pattern) 集成 OpenClaw 原生授权系统:
+ *
+ * 1. 预处理层 (QQ 特有): denyFrom, policy='deny'
+ * 2. SDK 层 (OpenClaw 原生): commands.allowFrom 检查
+ * 3. 后处理层 (QQ 特有): allowFrom 覆盖, policy='allowlist'
+ *
+ * 授权优先级链 (从高到低):
+ * 1. denyFrom - 绝对拒绝
+ * 2. policy='deny' - 频道级全局拒绝
+ * 3. allowFrom - 频道级白名单 (最高优先授权)
+ * 4. commands.allowFrom.qq - 全局 QQ 专属授权
+ * 5. commands.allowFrom["*"] - 全局通配授权
+ * 6. policy='allow' - 频道级全局允许
+ * 7. policy='allowlist' 未匹配 - 拒绝
+ * 8. 默认 - 拒绝
+ */
+import type { QQAccount, QQAllowConfig, QQGroupConfig } from "../types";
+/**
+ * QQ 命令授权拒绝原因
+ */
+export type QQDenialReason = "denyFrom" | "policy_deny" | "not_in_allowlist" | "default_deny";
+/**
+ * QQ 命令授权匹配来源
+ */
+export type QQMatchedBy = "channel_allowFrom" | "commands_qq" | "commands_wildcard" | "policy_allow";
+/**
+ * QQ 命令授权结果
+ */
+export interface QQCommandAuthorization {
+    /** QQ 频道标识 */
+    providerId: "qq";
+    /** Owner 列表 */
+    ownerList: string[];
+    /** 发送者 ID */
+    senderId: string;
+    /** 发送者是否是 Owner */
+    senderIsOwner: boolean;
+    /** 是否授权 */
+    isAuthorizedSender: boolean;
+    /** 拒绝原因（如果被拒绝） */
+    denialReason?: QQDenialReason;
+    /** 授权匹配来源（如果被授权） */
+    matchedBy?: QQMatchedBy;
+}
+/**
+ * resolveQQCommandAuthorization 参数
+ */
+export interface ResolveQQCommandAuthorizationParams {
+    /** 发送者 ID */
+    senderId: string;
+    /** QQ 频道配置 (群组或私聊) */
+    qqConfig: QQAllowConfig;
+}
+/**
+ * 解析 QQ 频道命令授权
+ *
+ * 使用三明治模式整合 QQ 特有配置与 OpenClaw 全局授权系统
+ */
+export declare function resolveQQCommandAuthorization(params: ResolveQQCommandAuthorizationParams): QQCommandAuthorization;
+/**
+ * 根据 chatType 获取对应的 QQ 配置
+ * 统一返回 QQGroupConfig 类型，私聊时使用默认值填充群组特有字段
+ */
+export declare function getQQConfigByChatType(isGroup: boolean, groupId: string | undefined, config: QQAccount): QQGroupConfig;