插件权限与使用范围

← 团队与权限 · 所有分区

插件权限

在「扩展」的插件卡片点击「权限」。内置关键词回复和导入的 JSON 规则插件可设置：

权限	生效范围
发送群消息	总开关；关闭后不发送任何插件回复或通知
群命令 / 关键词回复	群内指令和关键词响应
游戏事件	入服、退服通知
读取绑定玩家名	回复模板中的绑定玩家名；关闭后不提供绑定姓名
读取服务器状态	在线人数、在线列表、在线状态；关闭后模板显示“未授权”
服务器 / 群范围	指定服务器 ID、QQ 群号；留空允许所有已关联范围
使用者	所有成员、已绑定成员、机器人管理员
QQ 允许名单	填写后，只有名单内 QQ 能使用群命令
QQ 拒绝名单	始终拒绝名单中的 QQ，即使同时在允许名单或是管理员

群命令同时受插件规则里的 admin_only / bound_only 限制，面板授权不能绕过规则。使用者和 QQ 名单针对群命令；游戏事件通知按事件权限及服务器、群范围筛选。插件始终只在已配置的服务器关联群运行，授权不会增加任意代码、网络、文件或控制台执行能力。

升级时已有插件保留原有权限。新导入插件仍默认停用，启用前可以先调整权限。权限单独保存并立即生效，重启、重新加载、备份恢复都保留；导入的 JSON 文件不能自行修改授权。

权限字段与 API

每个插件卡片提供「权限」，可以限制发送群消息、群命令、游戏事件、绑定玩家名和服务器状态读取，以及服务器、群、使用者、QQ 允许 / 拒绝名单。权限由管理员保存到 data/plugin-state.json，不属于插件声明，插件导入文件不能自行授权。已有插件升级保留原行为，新导入插件仍停用。

PUT /api/extensions/{id} 可增加 permissions，省略时保留已有授权，例如：

{
  "revision": "当前插件 revision",
  "permissions": {
    "send_group": true, "group_commands": true, "game_events": false,
    "read_bindings": false, "read_server": true,
    "servers": ["survival"], "groups": ["123456789"],
    "user_mode": "bound", "allow_users": [], "deny_users": []
  }
}

permissions 省略的子字段使用默认值（能力开关 true，名单空，user_mode 为 all）。更新授权时建议发送完整对象。名单最多 100 项，空名单不额外限制，QQ 拒绝名单优先。面板授权与规则的身份限制需同时满足；游戏通知不使用 QQ 身份名单。读取绑定关闭后不提供绑定姓名，读取状态关闭后对应模板显示“未授权”。完整行为见 定时任务与白名单申请。

权限字段	生效范围
send_group	向关联群发送文字；与对应事件能力同时检查
group_commands	处理导入插件群命令与内置关键词回复
game_events	处理真实入退服事件通知
read_bindings	在群命令模板中提供绑定玩家名，不授予绑定或解绑能力
read_server	在模板中提供桥接状态、在线人数与玩家列表；服务器 ID / 名称仍可使用
servers / groups	限制可用服务器 ID / 群号，使用字符串数组
user_mode	all 所有成员、bound 当前服务器已绑定成员、admins 机器人管理员
allow_users / deny_users	QQ 允许 / 拒绝名单，拒绝优先；空允许名单不额外限制
send_game / execute_commands / create_backups	内置定时任务使用，外部 JSON 规则不能据此创建游戏动作、执行命令或备份

QQ 官机身份

QQ 官机同样使用此规则接口。群范围使用完整 qg:AppID:group_openid，用户范围使用 qug:AppID:member_openid 或 qup:AppID:user_openid。身份按应用与场景分别检查，消息还受平台回复上下文和主动发送权限限制，见QQ 官机接入。

团队账号权限与插件能力授权分别检查：plugins.manage 授权管理员修改插件，不会绕过群规则的身份和范围限制。