Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

lc-cn/onebots

Repository files navigation

OneBots - 多平台多协议机器人应用框架

使用 TypeScript 实现的多平台多协议机器人应用框架,支持 QQ、ICQQ、微信、钉钉、飞书、企业微信、Telegram、Slack、Discord、Kook、Microsoft Teams、Line、Email、WhatsApp、Zulip 等 15+ 平台

Build Package Build Docs License

npm dm node engine TypeScript

GitHub stars GitHub forks GitHub issues PRs Welcome

oneBot V11 oneBot V12 Satori Milky

qq group

📚 文档 Docs

📖 简介

OneBots 是一个基于 TypeScript 开发的多平台、多协议机器人应用框架。它提供了统一的接口来连接和管理不同平台的机器人,支持 OneBot V11/V12、Satori、Milky 等多种协议。

✨ 核心特性

  • 🎯 多平台支持 - 支持 QQ、ICQQ、微信、钉钉、飞书、企业微信、Telegram、Slack、Discord、Kook、Microsoft Teams、Line、Email、WhatsApp、Zulip 等 15+ 平台
  • 📡 多协议支持 - 支持 OneBot V11/V12、Satori、Milky 等协议
  • 🔌 插件化架构 - 适配器和协议可动态加载
  • 🏗️ 模块化设计 - 清晰的代码结构,易于扩展和维护
  • 📦 Monorepo 管理 - 使用 pnpm workspace 统一管理
  • 🎨 Web 管理界面 - 内置可视化管理界面(可选)
  • 🔄 事件驱动 - 基于事件的通信机制
  • 📝 TypeScript - 完整的类型支持

📦 项目结构

本项目采用 pnpm workspace 管理的 Monorepo 结构:

onebots/
├── packages/ # 核心包
│ ├── core/ # @onebots/core - 核心抽象层
│ ├── onebots/ # onebots - 主应用包
│ ├── web/ # @onebots/web - Web 管理界面
│ └── imhelper/ # imhelper - 客户端SDK核心
├── adapters/ # 适配器包
│ ├── adapter-qq/ # @onebots/adapter-qq - QQ官方机器人适配器
│ ├── adapter-kook/ # @onebots/adapter-kook - Kook适配器
│ ├── adapter-wechat/ # @onebots/adapter-wechat - 微信适配器
│ ├── adapter-discord/ # @onebots/adapter-discord - Discord适配器
│ ├── adapter-telegram/ # @onebots/adapter-telegram - Telegram适配器
│ ├── adapter-feishu/ # @onebots/adapter-feishu - 飞书适配器
│ ├── adapter-dingtalk/ # @onebots/adapter-dingtalk - 钉钉适配器
│ ├── adapter-slack/ # @onebots/adapter-slack - Slack适配器
│ ├── adapter-wecom/ # @onebots/adapter-wecom - 企业微信适配器
│ ├── adapter-teams/ # @onebots/adapter-teams - Microsoft Teams适配器
│ ├── adapter-line/ # @onebots/adapter-line - Line适配器
│ ├── adapter-email/ # @onebots/adapter-email - 邮件适配器
│ ├── adapter-whatsapp/ # @onebots/adapter-whatsapp - WhatsApp适配器
│ ├── adapter-zulip/ # @onebots/adapter-zulip - Zulip适配器
│ └── adapter-icqq/ # @onebots/adapter-icqq - ICQQ适配器(私有包)
├── protocols/ # 协议包
│ ├── onebot-v11/
│ │ ├── protocol/ # @onebots/protocol-onebot-v11 - OneBot V11协议实现
│ │ └── sdk/ # @imhelper/onebot-v11 - OneBot V11客户端SDK
│ ├── onebot-v12/
│ │ ├── protocol/ # @onebots/protocol-onebot-v12 - OneBot V12协议实现
│ │ └── sdk/ # @imhelper/onebot-v12 - OneBot V12客户端SDK
│ ├── satori-v1/
│ │ ├── protocol/ # @onebots/protocol-satori-v1 - Satori协议实现
│ │ └── sdk/ # @imhelper/satori-v1 - Satori客户端SDK
│ └── milky-1/
│ ├── protocol/ # @onebots/protocol-milky-v1 - Milky协议实现
│ └── sdk/ # @imhelper/milky-v1 - Milky客户端SDK
├── development/ # 开发环境配置
├── docs/ # 文档
└── pnpm-workspace.yaml # workspace 配置

📚 包名规范

服务器端包(@onebots/*)

  • @onebots/core - 核心抽象层,提供适配器、协议、账号等基础接口
  • onebots - 主应用包,提供命令行工具和完整应用功能
  • @onebots/web - Web 管理界面
  • @onebots/adapter-* - 各平台适配器(qq、kook、wechat、discord、telegram、feishu、dingtalk、slack、wecom、teams、line、email、whatsapp、zulip、icqq)
  • @onebots/protocol-* - 各协议实现(onebot-v11、onebot-v12、satori-v1、milky-v1)

客户端SDK包(imhelper / @imhelper/*)

  • imhelper - 客户端SDK核心包,提供统一的客户端接口和接收器
  • @imhelper/onebot-v11 - OneBot V11 客户端SDK
  • @imhelper/onebot-v12 - OneBot V12 客户端SDK
  • @imhelper/satori-v1 - Satori 客户端SDK
  • @imhelper/milky-v1 - Milky 客户端SDK

🚀 快速开始

安装

# 克隆项目
git clone https://github.com/liucl-cn/onebots.git
cd onebots
# 安装依赖
pnpm install

开发模式

# 运行服务器(开发环境)
pnpm dev
# 运行 Web 管理界面(可选)
pnpm web:dev
# 运行客户端SDK开发测试(可选)
pnpm sdk:dev
# 运行文档(可选)
pnpm docs:dev

构建

# 构建所有包
pnpm build
# 仅构建核心包
pnpm build:packages
# 仅构建适配器和协议
pnpm build:rest

测试

# 运行所有测试
pnpm test
# 监听模式
pnpm test:watch
# 测试UI
pnpm test:ui
# 测试覆盖率
pnpm test:coverage

📖 使用指南

服务器端使用

1. 安装主应用包

npm install onebots
# 或
pnpm add onebots

2. 安装所需适配器

# QQ官方机器人适配器
npm install @onebots/adapter-qq
# Kook适配器
npm install @onebots/adapter-kook
# 微信适配器
npm install @onebots/adapter-wechat
# Discord适配器
npm install @onebots/adapter-discord
# Telegram适配器
npm install @onebots/adapter-telegram
# 飞书适配器
npm install @onebots/adapter-feishu
# 钉钉适配器
npm install @onebots/adapter-dingtalk
# Slack适配器
npm install @onebots/adapter-slack
# 企业微信适配器
npm install @onebots/adapter-wecom
# Microsoft Teams适配器
npm install @onebots/adapter-teams
# Line适配器
npm install @onebots/adapter-line
# 邮件适配器
npm install @onebots/adapter-email
# WhatsApp适配器
npm install @onebots/adapter-whatsapp
# Zulip适配器
npm install @onebots/adapter-zulip

3. 创建配置文件

创建 config.yaml:

# 全局配置
port: 6727 # HTTP 服务器端口
log_level: info # 日志级别
# 通用配置(协议默认配置)
general:
 onebot.v11:
 use_http: true
 use_ws: true
 access_token: ''
 heartbeat_interval: 5000
 onebot.v12:
 use_http: true
 use_ws: true
 access_token: ''
 heartbeat_interval: 5000
 satori.v1:
 use_http: true
 use_ws: true
 token: ''
 milky.v1:
 use_http: true
 use_ws: true
# 账号配置
kook.zhin:
 token: 'your_kook_token'
 onebot.v11:
 access_token: 'kook_v11_token'
 onebot.v12:
 access_token: 'kook_v12_token'

4. 启动应用

# 使用命令行工具
npx onebots -r kook -r qq -p onebot-v11 -p onebot-v12 -c config.yaml
# 或使用 Node.js
import { App } from 'onebots';
const app = new App();
await app.start();

客户端SDK使用

1. 安装客户端SDK核心包

npm install imhelper
# 或
pnpm add imhelper

2. 安装协议客户端包

# OneBot V11 客户端
npm install @imhelper/onebot-v11
# OneBot V12 客户端
npm install @imhelper/onebot-v12
# Satori 客户端
npm install @imhelper/satori-v1
# Milky 客户端
npm install @imhelper/milky-v1

3. 使用示例

import { createImHelper } from 'imhelper';
import { createOnebot11Adapter } from '@imhelper/onebot-v11';
// 创建适配器
const adapter = createOnebot11Adapter({
 baseUrl: 'http://localhost:6727',
 selfId: 'zhin',
 accessToken: 'your_token',
 receiveMode: 'ws', // 'ws' | 'wss' | 'webhook' | 'sse'
 path: '/kook/zhin/onebot/v11',
 wsUrl: 'ws://localhost:6727/kook/zhin/onebot/v11',
 platform: 'kook',
});
// 创建 ImHelper 实例
const helper = createImHelper(adapter);
// 监听消息事件
helper.on('message.private', (message) => {
 console.log('收到私聊消息:', message.content);
 message.reply('收到!');
});
// 连接
await adapter.connect();
// 发送消息
await helper.sendPrivateMessage('123456', 'Hello!');

更多客户端SDK使用示例,请查看 客户端SDK使用指南

🎯 支持的平台

  • ✅ QQ官方机器人 - 通过 @onebots/adapter-qq
  • ✅ ICQQ - 通过 @onebots/adapter-icqq(私有包,需配置 GitHub Packages 访问)
  • ✅ Kook - 通过 @onebots/adapter-kook
  • ✅ 微信公众号 - 通过 @onebots/adapter-wechat
  • ✅ Discord - 通过 @onebots/adapter-discord
  • ✅ Telegram - 通过 @onebots/adapter-telegram
  • ✅ 飞书/Lark - 通过 @onebots/adapter-feishu
  • ✅ 钉钉 - 通过 @onebots/adapter-dingtalk
  • ✅ Slack - 通过 @onebots/adapter-slack
  • ✅ 企业微信 - 通过 @onebots/adapter-wecom
  • ✅ Microsoft Teams - 通过 @onebots/adapter-teams
  • ✅ Line - 通过 @onebots/adapter-line
  • ✅ 邮件 - 通过 @onebots/adapter-email
  • ✅ WhatsApp - 通过 @onebots/adapter-whatsapp
  • ✅ Zulip - 通过 @onebots/adapter-zulip

📡 支持的协议

  • ✅ OneBot V11 - 标准 OneBot V11 协议
  • ✅ OneBot V12 - 标准 OneBot V12 协议
  • ✅ Satori - Satori 协议
  • ✅ Milky - Milky 协议

📚 文档

🔧 开发

项目结构说明

  • packages/core - 核心抽象层,定义适配器、协议、账号等基础接口
  • packages/onebots - 主应用包,提供命令行工具和应用逻辑
  • packages/web - Web 管理界面
  • packages/client - 客户端SDK核心包
  • adapters/ - 各平台适配器实现
  • protocols/ - 各协议实现和客户端SDK

添加新适配器

  1. 在 adapters/ 目录下创建新适配器目录
  2. 实现 Adapter 基类的抽象方法
  3. 在 adapters/*/package.json 中配置包名和依赖
  4. 在主应用的 optionalDependencies 中添加新适配器

添加新协议

  1. 在 protocols/ 目录下创建新协议目录
  2. 在 protocol/ 子目录中实现协议服务端逻辑
  3. 在 client/ 子目录中实现协议客户端SDK
  4. 在 protocols/*/protocol/package.json 和 protocols/*/client/package.json 中配置包名

🤝 贡献

欢迎贡献代码!请查看 CONTRIBUTING.md 了解贡献指南。

📄 许可证

MIT License - 查看 LICENSE 文件了解详情

🙏 鸣谢

  1. icqqjs/icqq - 底层服务支持
  2. takayama-lily/onebot - OneBot V11 参考实现
  3. zhinjs/kook-client - Kook 客户端参考
  4. zhinjs/qq-official-bot - QQ官方机器人参考

📞 联系方式

☕ 赞助支持

如果这个项目对你有帮助,欢迎赞助支持!

支付宝
支付宝 微信
微信

爱发电

Made with ❤️ by 凉菜

About

基于icqq的多例oneBot管理应用

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published

AltStyle によって変換されたページ (->オリジナル) /