bingyue
bingyue
文章64
标签42
分类27
首页
归档
笔记
赞助
关于

文章分类

最新文章

© 2026 bingyue Powered by Hexo & Nexmoe
Koishi从0入门 02 编写插件

Koishi从0入门 02 编写插件

2025年05月31日 Koishi 约1.5k字 预计需要7分钟

创建新插件

在上一次的教程中，我们讲了如何部署Koishi

我们回到我们的工作区，目录内容如下

在这里打开cmd/powershell，输入如下命令创建插件

1
npm run setup 插件名字

然后回车

返回文件夹下，打开external->插件名字->src

这是你插件的代码目录，其中index.ts是你插件的main

注意:建议找一个没多少群的账号，因为前期我们还没写过滤群聊功能，这样会导致bot全局触发，由于我这里出了一点麻烦，所以就用沙盒测试了

1
2
3
4
5
6
7
8
9
10
11
12
import { Context, Schema } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
  // write your plugin here
  // 从这里开始编写插件
}

启用插件

打开Koishi控制台，选择插件管理

点右边哪个图标添加插件，添加我们刚刚创建的插件

然后启用插件

启用成功之后，下面会变成绿色的小图标

编写Hello World

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { Context, Schema } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
 ctx.on('message', (session) => {
    if (session.content === '你好') {
      session.send('Hello World')
    }
  })
}

效果

消息格式详解

1
2
3
4
5
6
7
8
9
10
11
12
13
import { Context, Schema } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
 ctx.on('message', (session) => {
   console.log(session) // 打印事件信息
  })
}

以下是事件信息的解析

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
{
  "id": "9***7",
  "sn": "9***7",
  "event": {
    "selfId": "5***1", // 机器人账号
    "platform": "onebot",
    "timestamp": 1748660785000,
    "type": "message-created",
    "message": {
      "messageId": "1***1", // 消息id
      "id": "1***4",
      "elements": [],
      "content": "test",
      "user": {
        "id": "3***7",
        "name": "小*",
        "userId": "3***7", // qq号
        "avatar": "http://q.qlogo.cn/headimg_dl?dst_uin=3***7&spec=640", // 头像
        "username": "小*", // 昵称
        "member": {
          "user": {},
          "nick": "",
          "roles": []
        }
      },
      "guild": {
        "id": "9***1", // 群号
        "channel": {
          "id": "9***1",
          "type": 0
        }
      },
      "subtype": "group", // 消息类型
      "subsubtype": "group"
    }
  },
  "type": "onebot",
  "data": {
    "self_id": "5***1",
    "user_id": "3***7",
    "time": 1748660785,
    "message_id": "1***4",
    "message_seq": "1***4",
    "real_id": "1***4",
    "real_seq": "4***0",
    "message_type": "group",
    "sender": {},
    "raw_message": "test",
    "font": 14,
    "sub_type": "normal",
    "message": [],
    "message_format": "array",
    "post_type": "message",
    "group_id": "9***1"
  },
  "Locales": [],
  "stripped": {
    "hasAt": false, // 是否有艾特
    "content": "test",
    "appel": false,
    "atSelf": false, // 有艾特机器人
    "prefix": "",
    "guild": {
      "flag": 0,
      "assignee": "5***1",
      "guildId": "9***1",
      "permissions": [],
      "Locales": [],
      "platform": "onebot",
      "id": "9***1"
    },
    "channel": {
      "flag": 0,
      "assignee": "5***1",
      "guildId": "9***1",
      "permissions": [],
      "Locales": [],
      "platform": "onebot",
      "id": "9***1"
    },
    "user": {
      "id": 2,
      "flag": 0,
      "authority": 1,
      "permissions": [],
      "Locales": []
    }
  },
  "scope": "commands.test.messages"
}

以下是一些写法

获取一些基本信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { Context, Schema } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
 ctx.on('message', (session) => {
   	console.log(session.userId) // 获取qq号
    console.log(session.guildId) // 获取群号
    console.log(session.event.user.name) // 获取昵称
  })
}

你可以根据上面那个示例事件进行取值，下面加上触发语句来尝试一下

示例 获取我的id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { Context, Schema } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
 ctx.on('message', async(session) => {
   if(session.content == "我的id"){
    await session.send(session.userId)
   }
  })
}

发送多元素消息

现在我们学会获取基本信息后，那么一个机器人只能发送文字肯定不够的，如何发送图片，艾特，表情，等其他内容

我这里将一一进行讲解

从文档这里给出了发送的方式，我们可以使用koishi准备好的api

1
2
3
4
5
6
7
8
9
10
11
// 第一个参数是元素名称 (必选)
h('message')

// 你可以传入一个由属性构成的对象作为第二个参数
h('quote', { id })

// 后续参数是元素的内容，可以是字符串或其他元素
h('p', {}, 'hello')

// 没有属性时二参数可以忽略不写
h('p', 'hello', h('img', { src }))

发送图片

1
await session.send(h.image("https://koishi.chat/logo.png")) // 这里可以换成链接，本地路径

发送艾特

1
await session.send(h.at(session.userId)) // 你也可以换成其他人的id

测试文字+图片

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { Context, Schema, h } from 'koishi'

export const name = 'test' // 插件名字

export interface Config {} // 插件的配置项

export const Config: Schema<Config> = Schema.object({})

export function apply(ctx: Context) {
 ctx.on('message', async(session) => {
   if(session.content == "测试"){
    await session.send(h.image("https://koishi.chat/logo.png")+"这是一个koishi的图标")
   }
  })
}

最后

学会了使用api发送消息后，下节课我们编写一个签到插件

本文作者：bingyue
本文链接：http://blog.bingyue.top/2025/05/31/koishi_02_teach/
版权声明：本文采用 CC BY-NC-SA 3.0 CN 协议进行许可
×