koishijs神秘bug （其实是bare-trigger插件实现

我用 koishi 搭 QQ bot，QQ 号和 AstrBot、Luna 共享一个 NapCat（v4.18.9）实例，三个 bot 通过不同的 reverse WebSocket 接 NapCat：

AstrBot：ws://127.0.0.1:8997
Luna (NoneBot2)：ws://127.0.0.1:6199
Koishi：ws://127.0.0.1:6700 music-voice 插件的命令名是 163，私聊发 163 wannacry 能正常返回搜索结果，群聊发同样的消息却完全没反应。NapCat 日志清楚显示 koishi 收不到任何 发送 -> 输出，但群里的 help 又能正常响应，这个差异让我意识到是它根本没把群消息当指令

koishi 默认群里要 prefix 或 @bot 本体#

翻 koishi core（@koishijs/core/lib/index.cjs:1275）：

1
ctx.before("attach", (session) => {
2
const { hasAt, appel } = session.stripped;
3
if (!appel && hasAt) return;
4
let content = session.stripped.content;
5
for (const prefix of this._resolvePrefixes(session)) {
6

7
          .tina-code-block .hljs-comment,
8
          .tina-code-block .hljs-code,
9
          .tina-code-block .hljs-formula { color: #6a737d; }
10
          .tina-code-block .hljs-keyword,
11
          .tina-code-block .hljs-doctag,
12
          .tina-code-block .hljs-template-tag,
13
          .tina-code-block .hljs-template-variable,
14
          .tina-code-block .hljs-type,
15
          .tina-code-block .hljs-variable.language_ { color: #d73a49; }
16
          .tina-code-block .hljs-title,
17
          .tina-code-block .hljs-title.class_,
18
          .tina-code-block .hljs-title.class_.inherited__,
19
          .tina-code-block .hljs-title.function_ { color: #6f42c1; }
20
          .tina-code-block .hljs-attr,
21
          .tina-code-block .hljs-attribute,
22
          .tina-code-block .hljs-literal,
23
          .tina-code-block .hljs-meta,
24
          .tina-code-block .hljs-number,
25
          .tina-code-block .hljs-operator,
26
          .tina-code-block .hljs-selector-attr,
27
          .tina-code-block .hljs-selector-class,
28
          .tina-code-block .hljs-selector-id,
29
          .tina-code-block .hljs-variable { color: #005cc5; }
30
          .tina-code-block .hljs-regexp,
31
          .tina-code-block .hljs-string,
32
          .tina-code-block .hljs-meta_.hljs-string { color: #0366d6; }
33
          .tina-code-block .hljs-built_in,
34
          .tina-code-block .hljs-symbol { color: #e36209; }
35
          .tina-code-block .hljs-name,
36
          .tina-code-block .hljs-quote,
37
          .tina-code-block .hljs-selector-tag,
38
          .tina-code-block .hljs-selector-pseudo { color: #22863a; }
39
          .tina-code-block .hljs-emphasis { font-style: italic; }
40
          .tina-code-block .hljs-strong { font-weight: bold; }
41
          .tina-code-block .hljs-section { font-weight: bold; color: #005cc5; }
42
          .tina-code-block .hljs-bullet { color: #735c0f; }
43
          .tina-code-block .hljs-addition { background: #f0fff4; color: #22863a; }
44
          .tina-code-block .hljs-deletion { background: #ffeef0; color: #b31d28; }
45
          .slate-code_line > span:last-child {margin-right: 1rem;}
46
        if (!content.startsWith(prefix)) continue;
47

48

49
session.stripped.prefix = prefix;
50

51

52
content = content.slice(prefix.length);
53

54

55
break;
56

57
Plain Text
58

59

60
}
61
...
62
});

紧接着是 inferCommand（index.cjs:1446）：

1
inferCommand(argv) {
2
if (!argv) return;
3
if (argv.command) return argv.command;
4
...
5
const isStrict = this.config.prefixMode === "strict" || !isDirect && !stripped.appel;
6
if (argv.root && stripped.prefix === null && isStrict) return;  // ← 群里裸消息栽在这
7
...
8
}

逻辑链是这样的：

场景	`isDirect`	`stripped.prefix`	`stripped.appel`	`inferCommand` 行为
私聊裸 `163`	`true`	`null`	`false`	直接走 token 匹配 → ✅
群聊裸 `163`	`false`	`null`	`false`	`isStrict=true && prefix===null` → return → ❌
群聊 `/163`	`false`	`'/'`	`false`	prefix 已经被 attach 剥过 → ✅
群聊 `@bot 163`	`false`	`null`	`true`	appel=true 短路掉 isStrict → ✅
`help` 在群里能用，是因为 plugin-help 用了 `cmd.shortcut('help', { fuzzy: true })`，注册到了 koishi 的 matcher 池里，绕开了 `inferCommand` 的 prefix 判定 `music-voice` 这种用 `ctx.command('163 ...')` 正常注册的命令，必须走 `inferCommand`，于是踩坑
我先把 `koishi.yml` 顶层的 `prefix: []` 改成 `prefix: ''` / `prefix: ['']`，想给所有消息加个”空前缀”——配置加载确实生效了（`commander.config.prefix` = `[""]`），但 `stripped.prefix` 依然是 `null`。

attach hook 在多 ctx 下被 filter 掉了#

koishi 用的是 cordis 作为 hook 框架，每个 plugin 都活在独立 ctx scope 里。Commander 是在 koishi app 启动时（provide("$commander", new Commander(this, ...))）注册 hook，hook 的 ctx 落在 root scope 上但 session（每个 message event 的 thisArg）是从 adapter-onebot 来的，session 的 ctx 落在 adapter 的 ctx scope 下。 cordis 的 Lifecycle.filterHooks（@cordisjs/core/lib/index.cjs:500）：

1
filterHooks(hooks, thisArg) {
2
thisArg = getTraceable(this.ctx, thisArg);
3
return hooks.slice().filter((hook) => {
4

5
          .tina-code-block .hljs-comment,
6
          .tina-code-block .hljs-code,
7
          .tina-code-block .hljs-formula { color: #6a737d; }
8
          .tina-code-block .hljs-keyword,
9
          .tina-code-block .hljs-doctag,
10
          .tina-code-block .hljs-template-tag,
11
          .tina-code-block .hljs-template-variable,
12
          .tina-code-block .hljs-type,
13
          .tina-code-block .hljs-variable.language_ { color: #d73a49; }
14
          .tina-code-block .hljs-title,
15
          .tina-code-block .hljs-title.class_,
16
          .tina-code-block .hljs-title.class_.inherited__,
17
          .tina-code-block .hljs-title.function_ { color: #6f42c1; }
18
          .tina-code-block .hljs-attr,
19
          .tina-code-block .hljs-attribute,
20
          .tina-code-block .hljs-literal,
21
          .tina-code-block .hljs-meta,
22
          .tina-code-block .hljs-number,
23
          .tina-code-block .hljs-operator,
24
          .tina-code-block .hljs-selector-attr,
25
          .tina-code-block .hljs-selector-class,
26
          .tina-code-block .hljs-selector-id,
27
          .tina-code-block .hljs-variable { color: #005cc5; }
28
          .tina-code-block .hljs-regexp,
29
          .tina-code-block .hljs-string,
30
          .tina-code-block .hljs-meta_.hljs-string { color: #0366d6; }
31
          .tina-code-block .hljs-built_in,
32
          .tina-code-block .hljs-symbol { color: #e36209; }
33
          .tina-code-block .hljs-name,
34
          .tina-code-block .hljs-quote,
35
          .tina-code-block .hljs-selector-tag,
36
          .tina-code-block .hljs-selector-pseudo { color: #22863a; }
37
          .tina-code-block .hljs-emphasis { font-style: italic; }
38
          .tina-code-block .hljs-strong { font-weight: bold; }
39
          .tina-code-block .hljs-section { font-weight: bold; color: #005cc5; }
40
          .tina-code-block .hljs-bullet { color: #735c0f; }
41
          .tina-code-block .hljs-addition { background: #f0fff4; color: #22863a; }
42
          .tina-code-block .hljs-deletion { background: #ffeef0; color: #b31d28; }
43
          .slate-code_line > span:last-child {margin-right: 1rem;}
44
        const filter = thisArg?.\[Context.filter];
45

46

47
return hook.global || !filter || filter.call(thisArg, hook.ctx);
48

49
Plain Text
50

51

52
});
53
}

当 thisArg（session）带 Context.filter 时，hook.ctx 必须落在 session ctx 的可达 scope 里才会执行。我直接 patch @koishijs/core/lib/index.cjs 在 Commander 的 attach hook 里塞 console.log，启动 koishi、群聊发消息——日志一条都没打出来。但我自己写的 plugin 注册的 ctx.before('attach', ...) 在同一条消息上能触发也就是说：Commander 的 attach hook 在群消息路径上从来没被调用过。这就把 stripped.prefix 一直留在初始的 null，后续所有逻辑都被短路 koishi 1.0 时代 core 自己直接 root 注册 hook 应该没问题，2.x/4.x 把 ctx 隔离做细之后，这个 hook 的注册 scope 看起来需要被显式 patch 上去。社区里搜到的所有”群消息不响应”issue，最后都是用户加 prefix 或 @bot 凑合过去，没人去诊断 filterHooks 的细节

解决方法是写一个本地插件做一个类似裸触发器的东西 dispatch 掉它#

绕开 cordis 的 filter 链最干净的做法：在 plugin 自己的 ctx 里直接接管 message 分发，不依赖 koishi core 的 attach/inferCommand 流程 /opt/koishi-app/plugins/koishi-plugin-bare-trigger/package.json：

1
{
2
"name": "koishi-plugin-bare-trigger",
3
"version": "0.0.1",
4
"main": "index.js",
5
"koishi": {
6

7
          .tina-code-block .hljs-comment,
8
          .tina-code-block .hljs-code,
9
          .tina-code-block .hljs-formula { color: #6a737d; }
10
          .tina-code-block .hljs-keyword,
11
          .tina-code-block .hljs-doctag,
12
          .tina-code-block .hljs-template-tag,
13
          .tina-code-block .hljs-template-variable,
14
          .tina-code-block .hljs-type,
15
          .tina-code-block .hljs-variable.language_ { color: #d73a49; }
16
          .tina-code-block .hljs-title,
17
          .tina-code-block .hljs-title.class_,
18
          .tina-code-block .hljs-title.class_.inherited__,
19
          .tina-code-block .hljs-title.function_ { color: #6f42c1; }
20
          .tina-code-block .hljs-attr,
21
          .tina-code-block .hljs-attribute,
22
          .tina-code-block .hljs-literal,
23
          .tina-code-block .hljs-meta,
24
          .tina-code-block .hljs-number,
25
          .tina-code-block .hljs-operator,
26
          .tina-code-block .hljs-selector-attr,
27
          .tina-code-block .hljs-selector-class,
28
          .tina-code-block .hljs-selector-id,
29
          .tina-code-block .hljs-variable { color: #005cc5; }
30
          .tina-code-block .hljs-regexp,
31
          .tina-code-block .hljs-string,
32
          .tina-code-block .hljs-meta_.hljs-string { color: #0366d6; }
33
          .tina-code-block .hljs-built_in,
34
          .tina-code-block .hljs-symbol { color: #e36209; }
35
          .tina-code-block .hljs-name,
36
          .tina-code-block .hljs-quote,
37
          .tina-code-block .hljs-selector-tag,
38
          .tina-code-block .hljs-selector-pseudo { color: #22863a; }
39
          .tina-code-block .hljs-emphasis { font-style: italic; }
40
          .tina-code-block .hljs-strong { font-weight: bold; }
41
          .tina-code-block .hljs-section { font-weight: bold; color: #005cc5; }
42
          .tina-code-block .hljs-bullet { color: #735c0f; }
43
          .tina-code-block .hljs-addition { background: #f0fff4; color: #22863a; }
44
          .tina-code-block .hljs-deletion { background: #ffeef0; color: #b31d28; }
45
          .slate-code_line > span:last-child {margin-right: 1rem;}
46
        "description": { "zh": "让群消息像私聊一样裸触发 koishi 已注册命令" }
47

48
Plain Text
49

50

51
}
52
}

/opt/koishi-app/plugins/koishi-plugin-bare-trigger/index.js：

1
const k = require('@koishijs/core')
2
module.exports = {
3
apply(ctx) {
4

5
          .tina-code-block .hljs-comment,
6
          .tina-code-block .hljs-code,
7
          .tina-code-block .hljs-formula { color: #6a737d; }
8
          .tina-code-block .hljs-keyword,
9
          .tina-code-block .hljs-doctag,
10
          .tina-code-block .hljs-template-tag,
11
          .tina-code-block .hljs-template-variable,
12
          .tina-code-block .hljs-type,
13
          .tina-code-block .hljs-variable.language_ { color: #d73a49; }
14
          .tina-code-block .hljs-title,
15
          .tina-code-block .hljs-title.class_,
16
          .tina-code-block .hljs-title.class_.inherited__,
17
          .tina-code-block .hljs-title.function_ { color: #6f42c1; }
18
          .tina-code-block .hljs-attr,
19
          .tina-code-block .hljs-attribute,
20
          .tina-code-block .hljs-literal,
21
          .tina-code-block .hljs-meta,
22
          .tina-code-block .hljs-number,
23
          .tina-code-block .hljs-operator,
24
          .tina-code-block .hljs-selector-attr,
25
          .tina-code-block .hljs-selector-class,
26
          .tina-code-block .hljs-selector-id,
27
          .tina-code-block .hljs-variable { color: #005cc5; }
28
          .tina-code-block .hljs-regexp,
29
          .tina-code-block .hljs-string,
30
          .tina-code-block .hljs-meta_.hljs-string { color: #0366d6; }
31
          .tina-code-block .hljs-built_in,
32
          .tina-code-block .hljs-symbol { color: #e36209; }
33
          .tina-code-block .hljs-name,
34
          .tina-code-block .hljs-quote,
35
          .tina-code-block .hljs-selector-tag,
36
          .tina-code-block .hljs-selector-pseudo { color: #22863a; }
37
          .tina-code-block .hljs-emphasis { font-style: italic; }
38
          .tina-code-block .hljs-strong { font-weight: bold; }
39
          .tina-code-block .hljs-section { font-weight: bold; color: #005cc5; }
40
          .tina-code-block .hljs-bullet { color: #735c0f; }
41
          .tina-code-block .hljs-addition { background: #f0fff4; color: #22863a; }
42
          .tina-code-block .hljs-deletion { background: #ffeef0; color: #b31d28; }
43
          .slate-code_line > span:last-child {margin-right: 1rem;}
44
        ctx.on('message', async (session) => {
45

46

47
  //私聊不需要这个插件（私聊本身就能裸触发）
48
  if (session.stripped?.isDirect) return
49
  //已经有 prefix 或 @bot，走 koishi 自带路径
50
  if (session.stripped?.prefix !== null) return
51
  if (session.stripped?.hasAt || session.stripped?.appel) return
52
  let content = session.stripped?.content
53
  if (!content) return
54
  if (content.startsWith('/')) content = content.slice(1)
55
  const at = content.match(/^@\S+\s+/)
56
  if (at) content = content.slice(at\[0].length)
57
  const first = content.split(/\s+/, 1)\[0]
58
  if (!first) return
59
  if (!ctx.app.$commander.get(first, session)) return
60
  try {
61
    //关键：把 prefix 临时设为空字符串，
62
    //否则 inferCommand 里的 "stripped.prefix === null && isStrict" 会 return
63
    session.stripped.prefix = ''
64
    const argv = k.Argv.parse(content)
65
    argv.session = session
66
    argv.root = true
67
    ctx.app.$commander.inferCommand(argv)
68
    await session.execute(argv)
69
  } catch {}
70
})
71
Plain Text
72

73

74
}
75
}

symlink + koishi.yml 注册：

1
ln -s ../plugins/koishi-plugin-bare-trigger /opt/koishi-app/node_modules/koishi-plugin-bare-trigger

koishi.yml 里在 adapter-onebot 后面加一行：

1
adapter-onebot:8fxdaw:
2
selfId: '32******38'
3
protocol: ws
4
endpoint: ws://127.0.0.1:6700
5
token: '***'
6
bare-trigger:bare01: {}

重启 koishi：

1
systemctl restart koishi-app.service

效果#

napcat 日志里看到：

1
08:04:45 [info] OwO | 接收 <- 群聊 [...rin's lab...] [Rin] 163 1
2
08:04:46 [info] OwO | 发送 -> 群聊 [...rin's lab...] [OwO(32******38)] [图片] 退出选择请发送 [0, 不听了] 中的任意内容 ...

群消息裸触发 100% 跟私聊一致，私聊行为不变，已有 prefix / @bot 的命令也不冲突（plugin 在第一步 return 掉了）。

后话#

回过头看，prefix: [''] 这个修复其实方向是对的，但被 koishi core attach hook 没触发的事实掩盖了——配置生效了但路径走不到。如果哪天 koishi 修了 attach hook 的 scope 问题，这条 prefix: [''] 也能独立工作。但裸触发这个用例，最好的实现还是 plugin：它更显式更可控不依赖 koishi 内部的 hook 拓扑如果你也遇到群里自定义命令不响应的问题，可以照上面三步走 (o´・ω・)

音乐

音乐

koishi 默认群里要 prefix 或 @bot 本体#

attach hook 在多 ctx 下被 filter 掉了#

解决方法是写一个本地插件做一个类似裸触发器的东西 dispatch 掉它#

效果#

后话#

文章分享

评论区

音乐

文章目录