@izhimu/qq 0.4.0 → 0.5.0

package/README.md

@@ -144,6 +144,10 @@ openclaw gateway restart
 | `wsUrl` | `string` | 是 | - | NapCat WebSocket 地址 |
 | `accessToken` | `string` | 否 | `""` | 访问令牌（如配置了认证） |
 | `enabled` | `boolean` | 否 | `true` | 是否启用该账号 |
+| `markdownFormat` | `boolean` | 否 | `true` | 是否启用 Markdown 格式化转换 |
+| `messageDirect` | `object` | 否 | - | 私聊全局配置（策略、黑白名单） |
+| `messageGroup` | `object` | 否 | - | 群组全局配置（@响应、戳一戳、唤醒词等） |
+| `messageGroupsCustom` | `object` | 否 | `{}` | 特定群组的独立配置 |
 
 ### 配置示例
 
@@ -153,7 +157,19 @@ openclaw gateway restart
     "qq": {
       "wsUrl": "ws://127.0.0.1:3001",
       "accessToken": "your-token",
-      "enabled": true
+      "enabled": true,
+      "markdownFormat": true,
+      "messageDirect": {
+        "policy": "allow",
+        "denyFrom": ["12345678"]
+      },
+      "messageGroup": {
+        "requireMention": true,
+        "requirePoke": true,
+        "policy": "allowlist",
+        "allowFrom": ["123456"],
+        "wakeWord": "小艺"
+      }
     }
   }
 }
@@ -262,6 +278,7 @@ openclaw-channel-qq/
 | `reply` | ✓ | ✓ | 消息回复 |
 | `record` | ✓ | ✓ | 语音消息 |
 | `file` | ✓ | ✓ | 文件 |
+| `video` | ✓ | - | 视频消息 |
 | `json` | ✓ | - | JSON 富文本 |
 
 ### OneBot 11 接口
@@ -374,6 +391,24 @@ npm run build
 
 ## 更新日志
 
+### [0.5.0] - 2026-03-11
+
+#### 新增
+- **多媒体支持增强**：新增对视频（`video`）消息类型的入站支持。
+- **细粒度访问控制**：
+    - 新增 `messageDirect` 和 `messageGroup` 配置项，支持私聊和群组的独立策略控制（`allow`, `deny`, `allowlist`）。
+    - 支持基于用户 ID 的黑白名单过滤。
+- **群组触发增强**：
+    - 支持自定义群组唤醒词（`wakeWord`）。
+    - 支持开启/关闭戳一戳（`requirePoke`）响应。
+    - 支持针对特定群组进行独立配置（`messageGroupsCustom`）。
+- **Markdown 优化**：新增 `markdownFormat` 开关，可选择是否将 Markdown 转换为纯文本。
+
+#### 优化
+- **配置结构重构**：重构了配置解析逻辑，提高了配置项的灵活性。
+- **消息文本转换**：优化了多媒体消息（图片、视频、音频、文件等）在日志和历史记录中的纯文本展示效果。
+- **稳定性**：增加了 Gateway Context 的预检，提升了系统的健壮性。
+
 ### [0.4.0] - 2026-03-07
 
 #### 新增

package/dist/src/channel.js

@@ -4,7 +4,7 @@
  */
 import { DEFAULT_ACCOUNT_ID, buildChannelConfigSchema, setAccountEnabledInConfigSection, deleteAccountFromConfigSection } from "openclaw/plugin-sdk";
 import { messageIdToString, markdownToText, buildMediaMessage, Logger as log } from "./utils/index.js";
-import { setContext, setContextStatus, clearContext, setConnection, getConnection, clearConnection, setLoginInfo } from "./core/runtime.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";
@@ -250,8 +250,18 @@ 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(),
+        };
+    }
     if (text) {
-        content.push({ type: "text", text: markdownToText(text) });
+        content.push({ type: "text", text: context.account.markdownFormat ? markdownToText(text) : text });
     }
     if (mediaUrl) {
         content.push(buildMediaMessage(mediaUrl));

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

@@ -15,10 +15,66 @@ export declare function listQQAccountIds(cfg: OpenClawConfig): string[];
 export declare function resolveQQAccount(params: {
     cfg: OpenClawConfig;
 }): QQConfig;
+export declare const QQDirectConfigSchema: z.ZodObject<{
+    policy: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        allowlist: "allowlist";
+    }>>;
+    allowFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    denyFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export declare const QQGroupConfigSchema: z.ZodObject<{
+    requireMention: z.ZodDefault<z.ZodBoolean>;
+    requirePoke: z.ZodDefault<z.ZodBoolean>;
+    historyLimit: z.ZodDefault<z.ZodNumber>;
+    policy: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        allowlist: "allowlist";
+    }>>;
+    allowFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    denyFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    wakeWord: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const QQConfigSchema: z.ZodObject<{
     wsUrl: z.ZodDefault<z.ZodString>;
     accessToken: z.ZodDefault<z.ZodString>;
     enable: z.ZodDefault<z.ZodBoolean>;
-    groupAtMode: z.ZodDefault<z.ZodBoolean>;
-    groupHistoryLimit: z.ZodDefault<z.ZodNumber>;
+    markdownFormat: z.ZodDefault<z.ZodBoolean>;
+    messageDirect: z.ZodObject<{
+        policy: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            allowlist: "allowlist";
+        }>>;
+        allowFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        denyFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>;
+    messageGroup: z.ZodObject<{
+        requireMention: z.ZodDefault<z.ZodBoolean>;
+        requirePoke: z.ZodDefault<z.ZodBoolean>;
+        historyLimit: z.ZodDefault<z.ZodNumber>;
+        policy: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            allowlist: "allowlist";
+        }>>;
+        allowFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        denyFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        wakeWord: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    messageGroupsCustom: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        requireMention: z.ZodDefault<z.ZodBoolean>;
+        requirePoke: z.ZodDefault<z.ZodBoolean>;
+        historyLimit: z.ZodDefault<z.ZodNumber>;
+        policy: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            allowlist: "allowlist";
+        }>>;
+        allowFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        denyFrom: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        wakeWord: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;

package/dist/src/core/config.js

@@ -23,8 +23,22 @@ export function resolveQQAccount(params) {
         enabled: config?.enabled !== false,
         wsUrl: config?.wsUrl ?? "",
         accessToken: config?.accessToken,
-        groupAtMode: config?.groupAtMode ?? true,
-        groupHistoryLimit: config?.groupHistoryLimit ?? 20,
+        markdownFormat: config?.markdownFormat ?? true,
+        messageDirect: {
+            policy: config?.messageDirect?.policy ?? "allow",
+            allowFrom: config?.messageDirect?.allowFrom ?? [],
+            denyFrom: config?.messageDirect?.denyFrom ?? [],
+        },
+        messageGroup: {
+            requireMention: config?.messageGroup?.requireMention ?? true,
+            requirePoke: config?.messageGroup?.requirePoke ?? true,
+            policy: config?.messageGroup?.policy ?? "allow",
+            historyLimit: config?.messageGroup?.historyLimit ?? 20,
+            allowFrom: config?.messageGroup?.allowFrom ?? [],
+            denyFrom: config?.messageGroup?.denyFrom ?? [],
+            wakeWord: config?.messageGroup?.wakeWord ?? undefined,
+        },
+        messageGroupsCustom: config?.messageGroupsCustom ?? {},
     };
 }
 /**
@@ -35,10 +49,26 @@ const wsUrlSchema = z.string()
     .regex(wsUrlRegex, { message: "Invalid WebSocket URL format. Expected: ws://host:port or wss://host:port" })
     .default("ws://127.0.0.1:3001")
     .describe("NapCat Websocket 连接地址");
+export const QQDirectConfigSchema = z.object({
+    policy: z.enum(["allow", "deny", "allowlist"]).default("allow").describe("私聊策略"),
+    allowFrom: z.array(z.string()).default([]).describe("允许的用户").optional(),
+    denyFrom: z.array(z.string()).default([]).describe("拒绝的用户").optional(),
+}).describe("私聊全局配置");
+export const QQGroupConfigSchema = z.object({
+    requireMention: z.boolean().default(true).describe("群组是否需要@响应"),
+    requirePoke: z.boolean().default(true).describe("群组支持戳一戳响应"),
+    historyLimit: z.number().default(20).describe("群组历史记录信息条数"),
+    policy: z.enum(["allow", "deny", "allowlist"]).default("allow").describe("群组策略"),
+    allowFrom: z.array(z.string()).default([]).describe("群组允许的用户").optional(),
+    denyFrom: z.array(z.string()).default([]).describe("群组拒绝的用户").optional(),
+    wakeWord: z.string().describe("群组唤醒词").optional(),
+}).describe("群组全局配置");
 export const QQConfigSchema = z.object({
     wsUrl: wsUrlSchema,
     accessToken: z.string().default("access-token").describe("NapCat Websocket Token"),
     enable: z.boolean().default(true).describe("是否启用"),
-    groupAtMode: z.boolean().default(true).describe("群组响应模式：默认启用，只有在被@时才会响应"),
-    groupHistoryLimit: z.number().default(20).describe("群组历史记录信息条数限制"),
+    markdownFormat: z.boolean().default(true).describe("是否启动 Markdown 格式化转换"),
+    messageDirect: QQDirectConfigSchema,
+    messageGroup: QQGroupConfigSchema,
+    messageGroupsCustom: z.record(z.string(), QQGroupConfigSchema).default({}).describe("特定群组配置").optional(),
 });

package/dist/src/core/dispatch.js

@@ -20,7 +20,7 @@ async function contentToPlainText(content) {
                 return c.text;
             case 'at':
                 const target = c.isAll ? '@全体成员' : `@${c.userId}`;
-                return `[AT]${target}`;
+                return `[提及]${target}`;
             case 'image':
                 return `[图片]${c.url}`;
             case 'audio':
@@ -83,8 +83,16 @@ async function contextToMedia(content) {
     return;
 }
 async function sendText(isGroup, chatId, text) {
-    const cleanText = text.replace(/NO_REPLY\s*$/, '');
-    const messageSegments = [{ type: 'text', data: { text: markdownToText(cleanText) } }];
+    const contextText = text.replace(/NO_REPLY\s*$/, '');
+    const context = getContext();
+    if (!context) {
+        log.warn('dispatch', `No gateway context`);
+        return;
+    }
+    const messageSegments = [{
+            type: 'text',
+            data: { text: context.account.markdownFormat ? markdownToText(contextText) : contextText }
+        }];
     try {
         await sendMsg({
             message_type: isGroup ? 'group' : 'private',
@@ -131,17 +139,15 @@ export async function dispatchMessage(params) {
     const isGroup = chatType === 'group';
     const config = context.account;
     // At 模式处理
-    if (isGroup && config.groupAtMode) {
-        const loginInfo = getLoginInfo();
-        const hasAtAll = content.includes('[AT]@全体成员');
-        const hasAtMe = loginInfo.userId && content.includes(`[AT]@${loginInfo.userId}`);
-        const hasPoke = content.includes('[动作]') && targetId === loginInfo.userId;
-        if (!hasAtAll && !hasAtMe && !hasPoke) {
+    if (isGroup) {
+        const isMention = mention(content, chatId, targetId);
+        if (!isMention) {
             log.debug('dispatch', `Skipping group message (not mentioned)`);
+            const groupConfig = getGroupConfig(chatId, config);
             recordPendingHistoryEntry({
                 historyMap: historyCache,
                 historyKey: chatId,
-                limit: config.groupHistoryLimit,
+                limit: groupConfig.historyLimit ?? 20,
                 entry: {
                     sender: `${senderName}(${senderId})`,
                     body: content,
@@ -171,10 +177,11 @@ export async function dispatchMessage(params) {
         log.info('dispatch', `Aborted previous session`);
     }
     if (isGroup) {
+        const groupConfig = getGroupConfig(chatId, config);
         content = buildPendingHistoryContextFromMap({
             historyMap: historyCache,
             historyKey: chatId,
-            limit: config.groupHistoryLimit,
+            limit: groupConfig.historyLimit ?? 20,
             currentMessage: content,
             formatEntry: (e) => `${e.sender}: ${e.body}`,
         });
@@ -295,6 +302,10 @@ export async function dispatchMessage(params) {
  * Handle group message event
  */
 export async function handleGroupMessage(event) {
+    if (!allow(event.user_id.toString(), event.group_id.toString())) {
+        log.debug('dispatch', `Ignoring group message from ${event.user_id}`);
+        return;
+    }
     const content = await napCatToOpenClawMessage(event.message);
     const plainText = await contentToPlainText(content);
     const media = await contextToMedia(content);
@@ -314,6 +325,10 @@ export async function handleGroupMessage(event) {
  * Handle private message event
  */
 export async function handlePrivateMessage(event) {
+    if (!allow(event.user_id.toString())) {
+        log.debug('dispatch', `Ignoring message from ${event.user_id}`);
+        return;
+    }
     const content = await napCatToOpenClawMessage(event.message);
     const plainText = await contentToPlainText(content);
     const media = await contextToMedia(content);
@@ -339,6 +354,10 @@ function extractPokeActionText(rawInfo) {
     return actionItem?.txt || '戳了戳';
 }
 export async function handlePokeEvent(event) {
+    if (!allow(event.user_id.toString(), event.group_id?.toString())) {
+        log.debug('dispatch', `Poke from ${event.user_id} is not allowed`);
+        return;
+    }
     const actionText = extractPokeActionText(event.raw_info);
     log.info('dispatch', `Poke from ${event.user_id}: ${actionText}`);
     const pokeMessage = actionText || '戳了戳';
@@ -355,3 +374,72 @@ export async function handlePokeEvent(event) {
         targetId: String(event.target_id),
     });
 }
+function getGroupConfig(groupId, config) {
+    log.debug('dispatch', `All Custom config: ${JSON.stringify(config.messageGroupsCustom)}`);
+    let groupConfig = config.messageGroupsCustom[groupId];
+    if (!groupConfig) {
+        groupConfig = config.messageGroup;
+        log.debug('dispatch', `Use global config: ${JSON.stringify(groupConfig)}`);
+    }
+    else {
+        groupConfig = {
+            ...config.messageGroup,
+            ...groupConfig,
+        };
+    }
+    log.debug('dispatch', `Final config: ${JSON.stringify(groupConfig)}`);
+    return groupConfig;
+}
+function allow(userId, groupId) {
+    const context = getContext();
+    if (!context) {
+        log.warn('dispatch', `No gateway context`);
+        return false;
+    }
+    let config = groupId ? getGroupConfig(groupId, context.account) : context.account.messageDirect;
+    return allowJudgment(config, userId);
+}
+function allowJudgment(config, userId) {
+    if (config.denyFrom?.includes(userId)) {
+        log.debug('dispatch', `User ${userId} is denied`);
+        return false;
+    }
+    if (config.policy === 'allow') {
+        log.debug('dispatch', `User ${userId} is allowed`);
+        return true;
+    }
+    if (config.policy === 'deny') {
+        log.debug('dispatch', `User ${userId} is denied`);
+        return false;
+    }
+    if (config.allowFrom?.includes(userId)) {
+        log.debug('dispatch', `User ${userId} is allowed`);
+        return true;
+    }
+    return false;
+}
+function mention(content, groupId, targetId) {
+    const context = getContext();
+    if (!context) {
+        log.warn('dispatch', `No gateway context`);
+        return false;
+    }
+    let config = getGroupConfig(groupId, context.account);
+    const loginInfo = getLoginInfo();
+    const isMentionEnabled = !!config?.requireMention;
+    const isPokeEnabled = !!config?.requirePoke;
+    const isWakeEnabled = !!config?.wakeWord?.trim();
+    if (!isMentionEnabled && !isPokeEnabled && !isWakeEnabled) {
+        log.debug('dispatch', 'All requires are disabled, returning true by default.');
+        return true;
+    }
+    const requireMention = isMentionEnabled &&
+        (content.includes('[提及]@全体成员') ||
+            (!!loginInfo?.userId && content.includes(`[提及]@${loginInfo.userId}`)));
+    const requirePoke = isPokeEnabled &&
+        (content.includes('[动作]') && targetId === loginInfo?.userId);
+    const requireWake = isWakeEnabled &&
+        content.includes(config.wakeWord ?? "");
+    log.debug('dispatch', `Require mention: ${requireMention}, require poke: ${requirePoke}, require wake: ${requireWake}`);
+    return requireMention || requirePoke || requireWake;
+}

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

@@ -280,8 +280,21 @@ export interface QQConfig {
     wsUrl: string;
     accessToken?: string;
     enabled: boolean;
-    groupAtMode: boolean;
-    groupHistoryLimit: number;
+    markdownFormat: boolean;
+    messageDirect: QQAllowConfig;
+    messageGroup: QQGroupConfig;
+    messageGroupsCustom: Record<string, QQGroupConfig>;
+}
+export interface QQGroupConfig extends QQAllowConfig {
+    requireMention: boolean;
+    requirePoke: boolean;
+    historyLimit: number;
+    wakeWord?: string;
+}
+export interface QQAllowConfig {
+    policy: "allow" | "deny" | "allowlist";
+    allowFrom: string[];
+    denyFrom: string[];
 }
 export type QQProbe = {
     ok: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izhimu/qq",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A QQ channel plugin for OpenClaw using NapCat WebSocket",
   "type": "module",
   "main": "dist/index.js",