@izhimu/qq 0.5.0 → 0.6.0

package/README.md

@@ -27,7 +27,7 @@
 </p>
 
 ---
-![demo.png](docs/demo.png)
+![demo.jpg](docs/demo.jpg)
 ## 目录
 
 - [功能特性](#功能特性)
@@ -69,7 +69,7 @@
 openclaw plugins install @izhimu/qq
 
 # 更新插件
-openclaw plugins update @izhimu/qq
+openclaw plugins update qq
 ```
 
 ### 本地开发安装
@@ -175,31 +175,17 @@ openclaw gateway restart
 }
 ```
 
+![config.png](docs/config.png)
+
 ---
 
 ## 使用方法
 
-### 发送消息
-
-```bash
-# 发送私聊消息
-openclaw message send "你好！" --to qq:private:123456789
-
-# 发送群消息
-openclaw message send "大家好！" --to qq:group:123456
-
-# 带回复的消息
-openclaw message send "回复你的消息" --to qq:private:123456789 --reply-to <message-id>
-```
-
 ### 检查状态
 
 ```bash
 # 查看频道状态
 openclaw channels
-
-# 查看日志
-openclaw logs --channel qq
 ```
 
 ### 消息目标格式
@@ -391,6 +377,23 @@ npm run build
 
 ## 更新日志
 
+### [0.6.0] - 2026-03-25
+
+#### ⚠️ 重大变更
+- **OpenClaw SDK 升级**：适配 OpenClaw SDK `2026.3.22` 版本，低于此版本的 OpenClaw 将无法使用本插件。
+
+#### 重构
+- **连接管理**：重构连接管理逻辑，优化 WebSocket 连接生命周期。
+- **消息处理**：重构消息处理逻辑，优化适配器结构。
+- **配置管理**：统一配置管理和健康状态处理。
+- **频道模块**：重构频道模块代码结构。
+- **授权系统**：重构 QQ 频道授权和配置系统。
+
+### [0.5.1] - 2026-03-12
+
+#### 修复
+- **连接状态显示**：修复了插件面板中连接状态及错误信息显示不准确的问题。
+
 ### [0.5.0] - 2026-03-11
 
 #### 新增

package/dist/index.d.ts

@@ -1,14 +1,8 @@
-/**
- * QQ NapCat Plugin Entry Point
- * Exports the plugin for OpenClaw to load
- */
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-declare const plugin: {
+declare const _default: {
     id: string;
     name: string;
     description: string;
-    configSchema: typeof emptyPluginConfigSchema;
-    register(api: OpenClawPluginApi): void;
-};
-export default plugin;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition, "kind">;
+export default _default;

package/dist/index.js

@@ -1,19 +1,10 @@
-/**
- * QQ NapCat Plugin Entry Point
- * Exports the plugin for OpenClaw to load
- */
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-import { qqPlugin } from "./src/channel.js";
-import { setRuntime } from "./src/core/runtime.js";
-import { CHANNEL_ID } from "./src/core/config.js";
-const plugin = {
-    id: CHANNEL_ID,
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { qqPlugin } from "./src/channel";
+import { setQQRuntime } from "./src/runtime";
+export default defineChannelPluginEntry({
+    id: "qq",
     name: "QQ",
-    description: "QQ channel plugin for OpenClaw using NapCat WebSocket API",
-    configSchema: emptyPluginConfigSchema,
-    register(api) {
-        setRuntime(api.runtime);
-        api.registerChannel({ plugin: qqPlugin });
-    },
-};
-export default plugin;
+    description: "QQ Chat channel plugin",
+    plugin: qqPlugin,
+    setRuntime: setQQRuntime,
+});

package/dist/src/adapters/message.d.ts

@@ -1,8 +1,19 @@
 /**
  * Message Type Adapters for NapCat <-> OpenClaw conversion
  *
- * Optimized for maintainability with clear structure and minimal duplication.
+ * 使用映射表驱动的统一消息转换系统
  */
-import type { NapCatMessage, OpenClawMessage } from '../types';
-export declare function openClawToNapCatMessage(content: OpenClawMessage[]): NapCatMessage[];
-export declare function napCatToOpenClawMessage(segments: NapCatMessage[] | string): Promise<OpenClawMessage[]>;
+import type { NapCatMessage, OpenClawMessage, QQAccount } from '../types';
+export declare function outboundMessageAdapter(content: OpenClawMessage[], account: QQAccount): Promise<NapCatMessage[]>;
+export declare function inboundMessageAdapter(segments: NapCatMessage[] | string): Promise<OpenClawMessage[]>;
+export type TextFormatter = (content: OpenClawMessage) => string | null;
+/** 将 OpenClaw 消息内容转换为纯文本 */
+export declare function formatContentToText(content: OpenClawMessage[]): string;
+/** 检查是否包含媒体 */
+export declare function hasMediaContent(content: OpenClawMessage[]): boolean;
+/** 从消息内容提取媒体信息 */
+export declare function extractMedia(content: OpenClawMessage[]): {
+    type: string;
+    path?: string;
+    url?: string;
+} | undefined;

package/dist/src/adapters/message.js

@@ -1,171 +1,226 @@
 /**
  * Message Type Adapters for NapCat <-> OpenClaw conversion
  *
- * Optimized for maintainability with clear structure and minimal duplication.
+ * 使用映射表驱动的统一消息转换系统
  */
-import { Logger as log, extractImageUrl, getEmojiForFaceId } from '../utils/index.js';
+import { Logger as log, extractImageUrl, getEmojiForFaceId, markdownToText } from '../utils/index.js';
 import { CQCodeUtils } from '../utils';
 import { getMsg } from "../core/request.js";
 // =============================================================================
+// 工具函数
+// =============================================================================
+/** 安全提取字符串字段 */
+const str = (data, key) => String(data[key] ?? '');
+/** 安全提取数字字段 */
+const num = (data, key) => {
+    const v = data[key];
+    return v != null ? parseInt(String(v), 10) : undefined;
+};
+// =============================================================================
 // CQ Code Parsing
 // =============================================================================
-/**
- * Convert CQNode to NapCatMessageSegment
- */
+/** 将 CQNode 转换为 NapCatMessageSegment */
 function cqNodeToNapCat(node) {
-    return {
-        type: node.type,
-        data: node.data,
-    };
+    return { type: node.type, data: node.data };
 }
-/**
- * Parse CQ codes using CQCodeUtils and convert to NapCatMessageSegment[]
- */
+/** 解析 CQ 码 */
 function parseCQCode(text) {
-    const nodes = CQCodeUtils.parse(text);
-    return nodes.map(cqNodeToNapCat);
+    return CQCodeUtils.parse(text).map(cqNodeToNapCat);
 }
-/**
- * Normalize message to segments array (handles string or array format)
- */
+/** 标准化消息格式 */
 function normalizeMessage(message) {
-    if (typeof message === 'string') {
+    if (typeof message === 'string')
         return parseCQCode(message);
-    }
     if (!Array.isArray(message)) {
         log.warn('adapters', `Invalid message format: ${typeof message}`);
         return [{ type: 'text', data: { text: String(message) } }];
     }
     return message;
 }
+// =============================================================================
+// JSON 消息解析
+// =============================================================================
 function parseJsonSegment(segment) {
+    const rawData = segment.data.data.trim();
+    let prompt;
     try {
-        const rawData = segment.data.data.trim();
-        let jsonData;
-        try {
-            jsonData = JSON.parse(rawData);
-        }
-        catch (error) {
-            log.warn('adapters', `Failed to parse JSON message: ${error}`);
-        }
-        const result = {
-            type: 'json',
-            data: rawData,
-        };
-        if (jsonData?.prompt && jsonData.prompt.trim() !== '') {
-            result.prompt = jsonData.prompt;
+        const jsonData = JSON.parse(rawData);
+        if (jsonData?.prompt?.trim()) {
+            prompt = jsonData.prompt;
         }
-        return result;
     }
-    catch (error) {
-        log.warn('adapters', `Failed to parse JSON message: ${error}`);
-        return null;
+    catch {
+        log.warn('adapters', 'Failed to parse JSON message');
     }
+    return { type: 'json', data: rawData, ...(prompt && { prompt }) };
 }
-// =============================================================================
-// NapCat -> OpenClaw Adapters (Inbound)
-// =============================================================================
+const inboundConverters = {
+    text: (data) => ({ type: 'text', text: str(data, 'text') }),
+    at: (data) => ({
+        type: 'at',
+        userId: str(data, 'qq'),
+        isAll: data.qq === 'all',
+    }),
+    image: (data) => {
+        const url = extractImageUrl(data);
+        return url ? { type: 'image', url, summary: data.summary } : null;
+    },
+    reply: async (data) => {
+        const response = await getMsg({ message_id: Number(data.id) });
+        if (!response.data?.message)
+            return null;
+        return {
+            type: 'reply',
+            messageId: str(data, 'id'),
+            message: response.data.raw_message,
+            senderId: String(response.data.sender.user_id),
+            sender: response.data.sender.nickname,
+        };
+    },
+    video: (data) => ({
+        type: 'video',
+        url: str(data, 'url'),
+        fileSize: num(data, 'file_size'),
+    }),
+    face: (data) => ({ type: 'text', text: getEmojiForFaceId(str(data, 'id')) }),
+    record: (data) => data.path ? {
+        type: 'audio',
+        path: str(data, 'path'),
+        file: str(data, 'file'),
+        url: data.url,
+        fileSize: num(data, 'file_size'),
+    } : null,
+    file: (data) => ({
+        type: 'file',
+        fileId: str(data, 'file'),
+        fileSize: num(data, 'file_size'),
+    }),
+    json: (data) => parseJsonSegment({ type: 'json', data: { data: str(data, 'data') } }),
+};
 async function napCatToOpenClaw(segment) {
     const data = segment.data;
-    switch (segment.type) {
-        case 'text':
-            return { type: 'text', text: String(data.text || '') };
-        case 'at':
-            return {
-                type: 'at',
-                userId: String(data.qq || ''),
-                isAll: data.qq === 'all',
-            };
-        case 'image': {
-            const url = extractImageUrl(data);
-            return url ? { type: 'image', url, summary: data.summary } : null;
-        }
-        case 'reply':
-            const response = await getMsg({
-                message_id: Number(data.id),
-            });
-            if (response.data?.message == undefined) {
-                return null;
-            }
-            return {
-                type: 'reply',
-                messageId: String(data.id),
-                message: response.data.raw_message,
-                senderId: String(response.data.sender.user_id),
-                sender: response.data.sender.nickname
-            };
-        case 'video':
-            return {
-                type: 'video',
-                url: String(data.url || ''),
-                fileSize: data.file_size ? parseInt(String(data.file_size), 10) : undefined,
-            };
-        case 'face':
-            return { type: 'text', text: getEmojiForFaceId(String(data.id || '')) };
-        case 'record':
-            return data.path ? {
-                type: 'audio',
-                path: String(data.path),
-                file: String(data.file || ''),
-                url: data.url,
-                fileSize: data.file_size ? parseInt(String(data.file_size), 10) : undefined,
-            } : null;
-        case 'file':
-            return {
-                type: 'file',
-                fileId: String(data.file || ''),
-                fileSize: data.file_size ? parseInt(String(data.file_size), 10) : undefined
-            };
-        case 'json':
-            return parseJsonSegment(segment);
-        default:
-            log.warn('adapters', `Unknown message type (inbound): ${segment.type}`);
-            return null;
+    const converter = inboundConverters[segment.type];
+    if (!converter) {
+        log.warn('adapters', `Unknown message type (inbound): ${segment.type}`);
+        return null;
     }
+    return converter(data);
 }
-// =============================================================================
-// OpenClaw -> NapCat Adapters (Outbound)
-// =============================================================================
-function openClawSegmentToNapCat(content) {
-    switch (content.type) {
-        case 'text':
-            return { type: 'text', data: { text: content.text } };
-        case 'at':
-            return { type: 'at', data: { qq: content.isAll ? 'all' : content.userId } };
-        case 'image':
-            return { type: 'image', data: { file: content.url, url: content.url } };
-        case 'reply':
-            return { type: 'reply', data: { id: content.messageId } };
-        case 'file':
-            return { type: 'file', data: { file: content.file, url: content.url, file_size: content.fileSize } };
-        case 'audio':
-            return {
-                type: 'record',
-                data: { file: content.file, path: content.path, url: content.url, file_size: content.fileSize }
-            };
-        default:
-            log.warn('adapters', `Unknown content type (outbound): ${content.type}`);
-            return null;
+const outboundConverters = {
+    text: (content, account) => ({
+        type: 'text',
+        data: { text: account.markdownFormat ? markdownToText(content.text) : content.text },
+    }),
+    at: (content) => {
+        const { isAll, userId } = content;
+        return { type: 'at', data: { qq: isAll ? 'all' : userId } };
+    },
+    image: (content) => {
+        const { url } = content;
+        return { type: 'image', data: { file: url, url } };
+    },
+    reply: (content) => ({
+        type: 'reply',
+        data: { id: content.messageId },
+    }),
+    file: (content) => {
+        const c = content;
+        return { type: 'file', data: { file: c.file, url: c.url, file_size: c.fileSize } };
+    },
+    audio: (content) => {
+        const c = content;
+        return { type: 'record', data: { file: c.file, path: c.path, url: c.url, file_size: c.fileSize } };
+    },
+};
+function openClawToNapCat(content, account) {
+    const converter = outboundConverters[content.type];
+    if (!converter) {
+        log.warn('adapters', `Unknown content type (outbound): ${content.type}`);
+        return null;
     }
+    return converter(content, account);
 }
-export function openClawToNapCatMessage(content) {
+// =============================================================================
+// 导出 API
+// =============================================================================
+export async function outboundMessageAdapter(content, account) {
     const segments = [];
     for (const item of content) {
-        const segment = openClawSegmentToNapCat(item);
-        if (segment) {
+        const segment = openClawToNapCat(item, account);
+        if (segment)
             segments.push(segment);
-        }
     }
     return segments;
 }
-export async function napCatToOpenClawMessage(segments) {
+export async function inboundMessageAdapter(segments) {
     const normalized = normalizeMessage(segments);
     const content = [];
     for (const segment of normalized) {
         const result = await napCatToOpenClaw(segment);
-        if (result) {
+        if (result)
             content.push(result);
-        }
     }
     return content;
 }
+const textFormatters = {
+    text: (c) => c.text,
+    at: (c) => {
+        const { isAll, userId } = c;
+        return `[提及]${isAll ? '@全体成员' : `@${userId || 'unknown'}`}`;
+    },
+    image: (c) => `[图片]${c.url || ''}`,
+    audio: (c) => `[音频]${c.path || ''}`,
+    video: (c) => `[视频]${c.url || ''}`,
+    file: (c) => `[文件]${c.fileId || ''}`,
+    json: (c) => `[JSON]\n\n\`\`\`json\n${c.data || ''}\n\`\`\``,
+    reply: (c) => {
+        const { sender, senderId, message } = c;
+        const senderInfo = sender && senderId ? `${sender}(${senderId})` : '(未知用户)';
+        const replyMsg = message ?? '(无法获取原消息)';
+        const quotedContent = `${senderInfo}:\n${replyMsg}`.replace(/^/gm, '> ');
+        return `[回复]\n\n${quotedContent}`;
+    },
+};
+/** 将 OpenClaw 消息内容转换为纯文本 */
+export function formatContentToText(content) {
+    return content
+        .map(c => textFormatters[c.type]?.(c) ?? null)
+        .filter((v) => v !== null)
+        .join('\n');
+}
+const mediaExtractors = [
+    {
+        check: (c) => c.some(x => x.type === 'image'),
+        extract: (c) => {
+            const img = c.find(x => x.type === 'image');
+            return img ? { type: 'image/jpeg', path: img.url, url: img.url } : undefined;
+        },
+    },
+    {
+        check: (c) => c.some(x => x.type === 'audio'),
+        extract: (c) => {
+            const audio = c.find(x => x.type === 'audio');
+            return audio ? { type: 'audio/amr', path: audio.path, url: audio.url } : undefined;
+        },
+    },
+    {
+        check: (c) => c.some(x => x.type === 'file'),
+        extract: (c) => {
+            const file = c.find(x => x.type === 'file');
+            return file ? { type: 'application/octet-stream', path: file.file, url: file.url } : undefined;
+        },
+    },
+];
+/** 检查是否包含媒体 */
+export function hasMediaContent(content) {
+    return content.some(c => c.type === 'image' || c.type === 'audio' || c.type === 'file');
+}
+/** 从消息内容提取媒体信息 */
+export function extractMedia(content) {
+    for (const extractor of mediaExtractors) {
+        if (extractor.check(content)) {
+            return extractor.extract(content);
+        }
+    }
+    return undefined;
+}

package/dist/src/channel.d.ts

@@ -1,7 +1,2 @@
-/**
- * QQ NapCat Plugin for OpenClaw
- * Main plugin entry point
- */
-import type { ChannelPlugin } from "openclaw/plugin-sdk";
-import type { QQConfig } from "./types";
-export declare const qqPlugin: ChannelPlugin<QQConfig>;
+import type { QQAccount } from "./types";
+export declare const qqPlugin: import("openclaw/plugin-sdk").ChannelPlugin<QQAccount, unknown, unknown>;