@pynickle/koishi-plugin-adapter-onebot

v1.0.0

Published

a month ago

OneBot Adapter for Koishi with NapCat Extensions

0High
0Medium
0Low

pynickle

bot chatbot koishi plugin adapter onebot im chat

@wittf/koishi-plugin-adapter-onebot

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

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

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

NapCat 扩展

注意：以下 NapCat 扩展功能仅在使用 NapCat 作为 OneBot 实现时可用。使用其他实现（如 go-cqhttp、Lagrange）时，这些扩展 API 可能不可用。

扩展事件

群表情回应事件

ctx.on('notice', (session) => {
  if (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) - 设置输入状态

好友相关 (7)

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

群组相关 (6)

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) - 获取群扩展信息

消息相关 (3)

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

AI 相关 (3)

bot.internal.getAiCharacters(group_id, chat_type) - 获取 AI 角色列表
bot.internal.getAiRecord(character, group_id, text) - 获取 AI 回复记录
bot.internal.sendGroupAiRecord(character, group_id, text) - 发送群 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, OneBotBot } from '@wittf/koishi-plugin-adapter-onebot'

export function apply(ctx: Context) {
  // 调用 NapCat API
  ctx.command('poke <user:user>')
    .action(async ({ session }, user) => {
      if (session.platform !== 'onebot') return '此命令仅支持 OneBot 平台'
      const bot = session.bot as OneBotBot
      if (session.guildId) {
        await bot.internal.groupPoke(session.guildId, user)
      } else {
        await bot.internal.friendPoke(user)
      }
      return '已戳一戳~'
    })

  // 使用表情工具
  ctx.command('random-react')
    .action(async ({ session }) => {
      if (session.platform !== 'onebot') return '此命令仅支持 OneBot 平台'
      const bot = session.bot as OneBotBot
      const emoji = getRandomEmoji()
      if (session.quote) {
        await bot.internal.setMsgEmojiLike(session.quote.id, emoji.id)
        return `已用 /${emoji.name}/ 回应~`
      }
      return '请引用要回应的消息'
    })

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

内部 API

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

session.onebot 包含原始的 OneBot 事件数据（用于访问 NapCat 扩展字段等），而不是 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.