@wittf/koishi-plugin-adapter-onebot

v1.0.0

Published

2 months ago

OneBot Adapter for Koishi with NapCat Extensions

0High
0Medium
0Low

wittf

bot chatbot koishi plugin adapter onebot im chat

@wittf/koishi-plugin-adapter-onebot

适用于 Koishi 的 OneBot 适配器（含 NapCat 扩展）。

OneBot 是一个聊天机器人应用接口标准。

本适配器在标准 OneBot 协议基础上，扩展支持 NapCat 提供的非标准 API 和事件。

NapCat 扩展

扩展事件

群表情回应事件

ctx.on('internal/session', (session) => {
  if (session.type === 'notice' && session.subtype === 'group-msg-emoji-like') {
    const data = session.onebot
    console.log('消息ID:', data.message_id)
    console.log('回应用户:', data.user_id)
    console.log('群号:', data.group_id)
    console.log('表情列表:', data.likes)
    // likes: [{ emoji_id: '107', count: 1 }, ...]
  }
})

扩展 API

账号相关 (6)

bot.internal.setSelfLongnick(longNick) - 设置个性签名
bot.internal.setOnlineStatus(status, ext_status, battery_status) - 设置在线状态
bot.internal.setQqProfile(nickname, company, email, college, personal_note) - 设置 QQ 资料
bot.internal.setQqAvatar(file) - 设置 QQ 头像
bot.internal.getClientkey() - 获取客户端密钥
bot.internal.setInputStatus(user_id, event_type) - 设置输入状态

好友相关 (9)

bot.internal.markPrivateMsgAsRead(user_id) - 标记私聊消息已读
bot.internal.getFriendMsgHistory(user_id, message_seq, count, reverseOrder) - 获取私聊消息历史
bot.internal.friendPoke(user_id) - 好友戳一戳
bot.internal.fetchEmojiLike(user_id) - 获取表情点赞信息
bot.internal.getFriendsWithCategory() - 获取分类好友列表
bot.internal.getUnidirectionalFriendList() - 获取单向好友列表
bot.internal.deleteFriend(user_id) - 删除好友
bot.internal.forwardFriendSingleMsg(message_id, user_id) - 转发单条好友消息
bot.internal.ncGetUserStatus(user_id) - 获取用户状态

群组相关 (11)

bot.internal.markGroupMsgAsRead(group_id) - 标记群消息已读
bot.internal.groupPoke(group_id, user_id) - 群内戳一戳
bot.internal.getGroupShutList(group_id) - 获取群禁言列表
bot.internal.setGroupRemark(group_id, remark) - 设置群备注
bot.internal.forwardGroupSingleMsg(message_id, group_id) - 转发单条群消息
bot.internal.getGroupInfoEx(group_id) - 获取群扩展信息
bot.internal.setGroupPortrait(group_id, file, cache) - 设置群头像
bot.internal.sendGroupNotice(group_id, content, image) - 发送群公告
bot.internal.getGroupNotice(group_id) - 获取群公告
bot.internal.getGroupAtAllRemain(group_id) - 获取 @全体成员剩余次数
bot.internal.setGroupSign(group_id) - 群签到

消息相关 (4)

bot.internal.setMsgEmojiLike(message_id, emoji_id) - 设置表情回应
bot.internal.markAllAsRead() - 标记所有消息已读
bot.internal.getRecentContact(count) - 获取最近联系人
bot.internal.ocrImage(image) - 图片 OCR 识别

文件相关 (7)

bot.internal.uploadGroupFile(group_id, file, name, folder) - 上传群文件
bot.internal.deleteGroupFile(group_id, file_id, busid) - 删除群文件
bot.internal.getGroupFileSystemInfo(group_id) - 获取群文件系统信息
bot.internal.getGroupRootFiles(group_id) - 获取群根目录文件列表
bot.internal.getGroupFilesByFolder(group_id, folder_id) - 获取群子目录文件列表
bot.internal.getGroupFileUrl(group_id, file_id, busid) - 获取群文件链接
bot.internal.uploadPrivateFile(user_id, file, name) - 上传私聊文件

AI 相关 (3)

bot.internal.aiTextToImage(chat_type, prompt, model_index) - AI 文本转图片
bot.internal.aiSummarizeChat(group_id) - AI 总结聊天记录
bot.internal.aiVoiceToText(file_id) - AI 语音转文字

完整 API 类型定义见 src/types.ts

表情工具函数

提供 QQ 表情查询和随机选择功能（260 个可用表情）。

import { getRandomEmoji, getAllEmojis, getEmojiById, getEmojiByName } from '@wittf/koishi-plugin-adapter-onebot'

// 获取随机表情（从260个QQ表情中）
const emoji = getRandomEmoji()
console.log(emoji.id, emoji.name)  // '107' 'doge'

// 获取所有可用表情
const allEmojis = getAllEmojis()

// 根据 ID 查找
const doge = getEmojiById('107')

// 根据名称查找
const smile = getEmojiByName('微笑')

表情对象结构：

interface QQEmoji {
  id: string        // 表情 ID，用于 setMsgEmojiLike
  name: string      // 表情名称（已去除 / 前缀）
  QSid?: string     // 原始 QQ 表情 ID
  QDes?: string     // 原始描述
  IQLid?: string    // iOS QQ 表情 ID
  AQLid?: string    // Android QQ 表情 ID
  EMCode?: string   // 表情代码
  Input?: string[]  // 输入提示
}

使用示例

import { Context } from 'koishi'
import { getRandomEmoji } from '@wittf/koishi-plugin-adapter-onebot'

export function apply(ctx: Context) {
  // 调用 NapCat API
  ctx.command('poke <user:user>')
    .action(async ({ session }, user) => {
      const bot = session.bot as any
      if (session.guildId) {
        await bot.internal.groupPoke(session.guildId, user)
      } else {
        await bot.internal.friendPoke(user)
      }
      return '已戳一戳~'
    })

  // 使用表情工具
  ctx.command('random-react')
    .action(async ({ session }) => {
      const bot = session.bot as any
      const emoji = getRandomEmoji()
      if (session.quote) {
        await bot.internal.setMsgEmojiLike(session.quote.id, emoji.id)
        return `已用 /${emoji.name}/ 回应~`
      }
      return '请引用要回应的消息'
    })

  // 监听扩展事件
  ctx.on('internal/session', (session) => {
    if (session.type === 'notice' && session.subtype === 'group-msg-emoji-like') {
      const data = session.onebot
      console.log(`收到表情回应: ${data.message_id}`)
    }
  })
}

内部 API

你可以通过 bot.internal 或 session.onebot 访问内部 API，参见访问内部接口。

OneBot v11 标准 API

go-cqhttp 扩展 API

频道 API

许可证

使用 MIT 许可证发布。

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@wittf/koishi-plugin-adapter-onebot

NapCat 扩展

扩展事件

群表情回应事件

扩展 API

账号相关 (6)

好友相关 (9)

群组相关 (11)

消息相关 (4)

文件相关 (7)

AI 相关 (3)

表情工具函数

使用示例

内部 API

OneBot v11 标准 API

go-cqhttp 扩展 API

频道 API

许可证