@izhimu/qq 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 izhimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# @izhimu/qq
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
+  </a>
+  <a href="https://docs.openclaw.ai/">
+    <img src="https://img.shields.io/badge/OpenClaw-Plugin-blueviolet.svg" alt="OpenClaw">
+  </a>
+  <a href="https://github.com/botuniverse/onebot-11">
+    <img src="https://img.shields.io/badge/Protocol-OneBot_11-yellow.svg" alt="Protocol">
+  </a>
+  <a href="https://www.typescriptlang.org/">
+    <img src="https://img.shields.io/badge/Language-TypeScript-blue.svg" alt="TypeScript">
+  </a>
+</p>
+
+<p align="center">
+  <strong>QQ Channel Plugin for OpenClaw</strong>
+</p>
+
+<p align="center">
+  通过 NapCat WebSocket API 连接 QQ 机器人，支持私聊、群聊、图片、回复等多种消息类型
+</p>
+
+---
+
+## 目录
+
+- [功能特性](#功能特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [配置](#配置)
+- [使用方法](#使用方法)
+- [架构设计](#架构设计)
+- [API 文档](#api-文档)
+- [开发指南](#开发指南)
+- [故障排查](#故障排查)
+
+---
+
+## 功能特性
+
+- **多渠道支持** - 同时支持 QQ 私聊和群聊
+- **消息类型** - 文本、@提及、图片、表情、语音、文件、回复
+- **实时通信** - WebSocket 全双工连接，支持自动重连
+- **心跳监测** - 内置健康检查和连接状态监控
+- **交互式配置** - 提供向导式配置界面
+- **TypeScript** - 完整的类型定义和类型安全
+
+---
+
+## 安装
+
+### 前提条件
+
+1. 安装 [OpenClaw](https://docs.openclaw.ai/) >= 2026.2.1
+2. 安装并配置 [NapCat](https://github.com/NapNeko/NapCatQQ) WebSocket 服务
+
+### 通过 OpenClaw CLI 安装
+
+```bash
+# 安装插件
+openclaw plugins install @izhimu/qq
+```
+
+### 本地开发安装
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd openclaw-channel-qq
+
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+
+# 安装到 OpenClaw
+openclaw plugins install /path/to/openclaw-channel-qq 
+```
+
+---
+
+## 快速开始
+
+### 1. 配置 NapCat
+
+在 NapCat 的 `config.yml` 中启用 WebSocket：
+
+```yaml
+ws:
+  servers:
+    - url: ws://0.0.0.0:3001
+      token: ""  # 如需认证请设置
+      enableHeart: true
+```
+
+### 2. 配置 OpenClaw
+
+运行交互式配置向导：
+
+```bash
+openclaw onboard
+```
+
+或手动编辑配置：
+
+```json
+{
+  "channels": {
+    "qq": {
+      "wsUrl": "ws://127.0.0.1:3001",
+      "accessToken": "",
+      "enabled": true
+    }
+  }
+}
+```
+
+### 3. 启动 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## 配置
+
+### 配置选项
+
+| 属性 | 类型 | 必填 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `wsUrl` | `string` | 是 | - | NapCat WebSocket 地址 |
+| `accessToken` | `string` | 否 | `""` | 访问令牌（如配置了认证） |
+| `enabled` | `boolean` | 否 | `true` | 是否启用该账号 |
+
+### 配置示例
+
+```json
+{
+  "channels": {
+    "qq": {
+      "wsUrl": "ws://127.0.0.1:3001",
+      "accessToken": "your-token",
+      "enabled": true
+    }
+  }
+}
+```
+
+---
+
+## 使用方法
+
+### 发送消息
+
+```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
+```
+
+### 消息目标格式
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 私聊 | `private:<QQ号>` | `qq:private:123456789` |
+| 群聊 | `group:<群号>` | `qq:group:123456` |
+
+---
+
+## 架构设计
+
+### 项目结构
+
+```
+openclaw-channel-qq/
+├── src/
+│   ├── channel.ts              # 插件主入口
+│   ├── core/
+│   │   ├── connection.ts       # WebSocket 连接管理
+│   │   ├── dispatch.ts         # 事件分发器
+│   │   ├── request.ts          # API 请求处理
+│   │   ├── runtime.ts          # 运行时状态管理
+│   │   └── config.ts           # 配置解析
+│   ├── adapters/
+│   │   └── message.ts          # 消息格式转换
+│   ├── types/
+│   │   └── index.ts            # TypeScript 类型定义
+│   ├── utils/
+│   │   ├── index.ts            # 工具函数
+│   │   ├── log.ts              # 日志工具
+│   │   ├── markdown.ts         # Markdown 处理
+│   │   └── cqcode.ts           # CQ 码解析
+│   └── onboarding.ts           # 交互式配置向导
+├── docs/
+│   ├── napcat-websocket-api.md # NapCat API 文档
+│   └── plugin-development-guide.md # 插件开发指南
+├── openclaw.plugin.json        # 插件清单
+├── package.json
+└── tsconfig.json
+```
+
+### 核心组件
+
+#### 1. ConnectionManager
+
+负责 WebSocket 连接的生命周期管理：
+- 连接建立和断开
+- 自动重连机制（指数退避）
+- 心跳监测
+- 请求/响应关联
+
+#### 2. MessageAdapter
+
+处理 NapCat 与 OpenClaw 消息格式的双向转换：
+- 入站消息解析（NapCat → OpenClaw）
+- 出站消息构建（OpenClaw → NapCat）
+- 支持多种消息段类型
+
+#### 3. EventDispatcher
+
+处理 NapCat 上报的各类事件：
+- 消息事件（私聊、群聊）
+- 通知事件（戳一戳、撤回等）
+- 元事件（心跳、生命周期）
+
+---
+
+## API 文档
+
+### 支持的消息类型
+
+| 类型 | 入站 | 出站 | 说明 |
+|------|------|------|------|
+| `text` | ✓ | ✓ | 文本消息 |
+| `at` | ✓ | ✓ | @提及 |
+| `image` | ✓ | ✓ | 图片 |
+| `face` | ✓ | - | QQ 表情 |
+| `reply` | ✓ | ✓ | 消息回复 |
+| `record` | ✓ | - | 语音消息 |
+| `file` | ✓ | - | 文件 |
+| `json` | ✓ | - | JSON 富文本 |
+
+### OneBot 11 接口
+
+```typescript
+// 发送消息
+{
+  action: 'send_msg',
+  params: {
+    message_type: 'private' | 'group',
+    user_id?: string,      // 私聊时必填
+    group_id?: string,     // 群聊时必填
+    message: NapCatMessage[] | string
+  }
+}
+
+// 获取消息
+{
+  action: 'get_msg',
+  params: {
+    message_id: number
+  }
+}
+
+// 获取运行状态
+{
+  action: 'get_status',
+  params: {}
+}
+```
+
+完整 API 文档请参考 [NapCat WebSocket API 文档](./docs/napcat-websocket-api.md)。
+
+---
+
+## 开发指南
+
+### 开发环境设置
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式（热重载）
+npm run dev
+
+# 构建
+npm run build
+```
+
+### 目录结构说明
+
+| 目录 | 说明 |
+|------|------|
+| `src/core/` | 核心功能模块 |
+| `src/adapters/` | 适配器（消息转换等） |
+| `src/types/` | TypeScript 类型定义 |
+| `src/utils/` | 工具函数 |
+| `docs/` | 文档 |
+| `openspec/` | OpenSpec 规范 |
+
+### 插件开发参考
+
+详细开发指南请参考 [插件开发指南](./docs/plugin-development-guide.md)。
+
+---
+
+## 故障排查
+
+### 连接问题
+
+1. **检查 NapCat 是否运行**
+   ```bash
+   # 检查服务状态
+   curl http://localhost:3001/get_status
+   ```
+
+2. **验证 WebSocket 配置**
+   - 确认 `wsUrl` 与 NapCat 配置一致
+   - 检查访问令牌是否正确
+
+3. **防火墙设置**
+   - 确保 WebSocket 端口未被防火墙拦截
+
+### 消息发送失败
+
+1. **检查账号状态**
+   ```bash
+   openclaw channels
+   ```
+
+2. **查看日志**
+   ```bash
+   openclaw logs --channel qq --verbose
+   ```
+
+3. **验证消息格式**
+   - 确保目标格式正确：`private:<QQ>` 或 `group:<群号>`
+
+### 常见问题
+
+| 问题 | 可能原因 | 解决方案 |
+|------|----------|----------|
+| 连接失败 | NapCat 未启动 | 启动 NapCat 服务 |
+| 认证失败 | accessToken 错误 | 检查配置中的令牌 |
+| 消息未收到 | 账号被禁用 | 检查 `enabled: true` |
+| 图片发送失败 | URL 不可访问 | 确保图片 URL 可公网访问 |
+
+---
+
+## 相关链接
+
+- [OpenClaw 官方文档](https://docs.openclaw.ai/)
+- [OpenClaw 插件开发指南](https://docs.openclaw.ai/plugin)
+- [NapCat GitHub](https://github.com/NapNeko/NapCatQQ)
+- [OneBot 11 协议标准](https://github.com/botuniverse/onebot-11)
+
+---
+
+## 开源协议
+
+[MIT](LICENSE) © izhimu
+
+---
+
+<p align="center">
+  如有问题或建议，欢迎提交 Issue 或 PR
+</p>

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: typeof emptyPluginConfigSchema;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * 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,
+    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;

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

@@ -0,0 +1,8 @@
+/**
+ * Message Type Adapters for NapCat <-> OpenClaw conversion
+ *
+ * Optimized for maintainability with clear structure and minimal duplication.
+ */
+import type { NapCatMessage, OpenClawMessage } from '../types/index.js';
+export declare function openClawToNapCatMessage(content: OpenClawMessage[], replyToId?: string): NapCatMessage[];
+export declare function napCatToOpenClawMessage(segments: NapCatMessage[] | string): Promise<OpenClawMessage[]>;

package/dist/src/adapters/message.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { CQCodeUtils } from '../utils/cqcode.js';
+// =============================================================================
+// CQ Code Parsing
+// =============================================================================
+/**
+ * Convert CQNode to NapCatMessageSegment
+ */
+function cqNodeToNapCat(node) {
+    return {
+        type: node.type,
+        data: node.data,
+    };
+}
+/**
+ * Parse CQ codes using CQCodeUtils and convert to NapCatMessageSegment[]
+ */
+function parseCQCode(text) {
+    const nodes = CQCodeUtils.parse(text);
+    return nodes.map(cqNodeToNapCat);
+}
+/**
+ * Normalize message to segments array (handles string or array format)
+ */
+function normalizeMessage(message) {
+    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;
+}
+function parseJsonSegment(segment) {
+    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;
+        }
+        return result;
+    }
+    catch (error) {
+        log.warn('adapters', `Failed to parse JSON message: ${error}`);
+        return null;
+    }
+}
+// =============================================================================
+// NapCat -> OpenClaw Adapters (Inbound)
+// =============================================================================
+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':
+            return { type: 'reply', messageId: String(data.id || '') };
+        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;
+    }
+}
+// =============================================================================
+// 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 'audio':
+            // These types are inbound-only for now
+            log.warn('adapters', `Unsupported outbound type: ${content.type}`);
+            return null;
+        default:
+            log.warn('adapters', `Unknown content type (outbound): ${content.type}`);
+            return null;
+    }
+}
+export function openClawToNapCatMessage(content, replyToId) {
+    const segments = [];
+    if (replyToId) {
+        segments.push({ type: 'reply', data: { id: replyToId } });
+    }
+    for (const item of content) {
+        const segment = openClawSegmentToNapCat(item);
+        if (segment) {
+            segments.push(segment);
+        }
+    }
+    return segments;
+}
+export async function napCatToOpenClawMessage(segments) {
+    const normalized = normalizeMessage(segments);
+    const content = [];
+    for (const segment of normalized) {
+        const result = napCatToOpenClaw(segment);
+        if (result) {
+            content.push(result);
+        }
+    }
+    return content;
+}

package/dist/src/channel.d.ts

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