TS3AudioBot 插件加载机制与 !bili 命令实现分析

Source: ts3audiobot/02-plugin-loading-and-bili-command.md

文档日期：2026-07-08 适用对象：当前 TS3AudioBot Docker 部署与自定义 <Bilibili 命令插件> 插件

1. 核心结论

!bili 不是 TS3AudioBot 原生命令，而是 <Bilibili 命令插件> 插件注册出来的自定义命令。

因此排障时要先区分两件事：

TS3AudioBot 本体是否启动。
<Bilibili 命令插件> 插件是否加载。

只要插件没有加载，即使 <Bilibili 命令插件> 文件存在，!bili 也不会生效。

2. 文件位置

宿主机：

bash

<TS3AudioBot compose 目录>/data/plugins/<Bilibili 命令插件>

容器内：

bash

<TS3AudioBot 数据目录>/plugins/<Bilibili 命令插件>

检查：

bash

docker exec ts3audiobot sh -c 'ls -l <TS3AudioBot 数据目录>/plugins/<Bilibili 命令插件>'

3. 正常工作链路

text

用户输入 !bili BV号
-> TS3AudioBot 收到聊天命令
-> <Bilibili 命令插件> 插件匹配 bili 命令
-> 插件调用 yt-dlp / yt-dlp-bili
-> 使用 <Bilibili cookies 文件> 解析 Bilibili
-> 下载音频到 bots/default/music/bili/
-> TS3AudioBot 播放本地音频

这条链路里，任何一步失败都会表现为 !bili 不可用。

4. 插件未加载时的现象

TeamSpeak 内输入：

text

!bili BV1gK4y1a7yZ

如果返回类似：

text

Error: The command contains the following subfunctions: unsubscribe, version, volume, ...

通常说明 bot 根本不认识 bili 命令，原因是插件没有加载。

5. 手动加载方式

TeamSpeak 聊天中执行：

text

!plugin load <Bilibili 命令插件>

然后检查：

text

!plugin list

正常应看到：

text

#0|+ON|BiliUrlPlugin (BotPlugin)

再测试：

text

!bili BV1gK4y1a7yZ

正常回复应类似：

text

Downloading and will play when ready: BV1gK4y1a7yZ

6. API 加载方式

直接调用全局插件接口可能报错：

bash

curl -i 'http://127.0.0.1:<TS3AudioBot Web API 端口>/api/plugin/load/<Bilibili 命令插件>'

常见错误：

json

{"ErrorName":"CommandError","ErrorMessage":"Plugin error: MissingContext"}

原因是插件加载需要 bot 上下文。当前可使用 bot id 0：

bash

curl -s 'http://127.0.0.1:<TS3AudioBot Web API 端口>/api/bot/use/0/(/plugin/load/<Bilibili 命令插件>)'

检查插件列表：

bash

curl -s 'http://127.0.0.1:<TS3AudioBot Web API 端口>/api/plugin/list'

7. 自动加载建议

entrypoint.sh 可以在 TS3AudioBot 启动后等待 Web API 可用，再执行一次插件加载。

关键点：

先启动 TS3AudioBot。
等 <TS3AudioBot Web API 端口> API 可用。
使用 bot 上下文加载插件。
把加载结果写入 plugin-load.log。
不要让加载脚本替代 TS3AudioBot 主进程。

最小流程：

text

启动代理
启动 TS3AudioBot
循环等待 API
调用 /api/bot/use/0/(/plugin/load/<Bilibili 命令插件>)
记录日志
wait TS3AudioBot 进程

8. 权限文件注意事项

普通用户要使用 !bili，<TS3AudioBot 权限文件> 中需要允许：

toml

"cmd.bili",
"cmd.bili.*"

如果日志出现：

text

Right "cmd.bili" is not registered.

优先检查插件是否加载，而不是先改权限。

9. 排障顺序

建议按这个顺序查：

text

1. docker ps 看容器是否运行
2. docker logs 看 TS3AudioBot 是否连接 TeamSpeak
3. ls 看 <Bilibili 命令插件> 是否存在
4. !plugin list 看插件是否加载
5. <TS3AudioBot 权限文件> 看权限是否放行
6. command -v yt-dlp 看解析工具是否存在
7. ls 看 <Bilibili cookies 文件> 是否存在
8. ls -ld 看下载目录是否可写

10. 最小恢复流程

bash

cd <TS3AudioBot compose 目录>
docker compose up -d --build --force-recreate
sleep 15
docker logs --tail=120 ts3audiobot
tail -100 data/plugin-load.log

TeamSpeak 内：

text

!plugin list
!plugin load <Bilibili 命令插件>
!plugin list
!bili BV1gK4y1a7yZ