AstrBot自定义触发器插件

支持多平台适配(snowluma/napcat/llbot/aiocqhttp)、沙箱执行、反重复触发、动态方法管理的自定义触发器插件。

兼容性

• AstrBot: >= 4.16.0, < 5.0.0
• 后端协议: OneBot V11 (snowluma/NapCat/LLBot/aiocqhttp 等)
• 最低版本: AstrBot 4.16.0

功能特性

• 多平台适配: 自动检测 snowluma、NapCat、LLBot、aiocqhttp 等 OneBot V11 适配器
• 沙箱执行: 支持 none/sandbox/local 三种执行模式，自定义 Python/Node 路径
• 反重复触发: 半分钟内同一用户同一触发器连续触发超过阈值自动忽略
• 动态方法管理: 初始化时检测异常方法并标记，防止内存泄漏
• 增强日志: 分级日志过滤（debug/info/warning/error），支持日志转发到群
• 线程池执行: 脚本在线程池中运行，不阻塞 AstrBot 主事件循环
• UTF-8编码兼容: 读取失败自动移除不兼容字符，写入失败 ASCII 回退
• 群管理功能: 禁言、踢人、名片、头衔、公告等 OneBot V11 API
• 被动监听: keyword/fullmatch/regex/command 触发器无需 @ 机器人
• Cron 定时触发: 支持定时任务（需安装 croniter）
• 紧急控制: 支持全局/群级紧急锁定，投票机制

目录结构

astrbot_plugin_custom_trigger/
├── main.py              # 主入口
├── metadata.yaml        # 插件元数据
├── _conf_schema.json    # WebUI 配置定义
├── adapter_manager.py   # 适配器管理
├── platform_api.py      # 平台 API 封装
├── sandbox.py           # 沙箱执行器
├── anti_spam.py         # 反重复触发
├── handler.py           # 事件处理器
├── executor.py          # 脚本执行器
├── parser.py            # 消息解析器
├── config_loader.py     # 配置加载器
├── commands.py          # /cf 命令
├── log.py               # 日志封装
├── emergency.py         # 紧急控制
├── security.py          # 运行时安全检查
├── config/              # 主配置缓存
│   └── triggers.json
├── plugins/             # 插件式配置文件夹
│   ├── greeting.json
│   └── 123456/          # 群专属配置（数字文件夹）
│       └── group_triggers.json
└── venv/                # 默认沙箱环境

快速开始

1. 将插件放入 AstrBot/data/plugins/astrbot_plugin_custom_trigger/
2. 安装依赖：pip install -r requirements.txt
3. 在 plugins/ 目录下创建 .json 配置文件
4. 重启 AstrBot 或在 WebUI 重载插件
5. 插件自动合并所有配置

配置文件格式

{
  "plugin_name": "greeting",
  "author": "你的名字",
  "description": "问候插件",
  "triggers": [
    {
      "name": "say_hello",
      "trigger_type": "keyword",
      "trigger_pattern": "你好",
      "response_type": "text",
      "response_content": "你好 {user_name}！",
      "permission": "all",
      "cooldown": 5,
      "enabled": true
    }
  ]
}

触发类型

类型	说明	示例
keyword	关键词包含匹配	"你好"
fullmatch	全匹配或前缀+参数	"签到"
regex	正则表达式匹配	`"^(hello
command	命令触发（/开头）	"help" → /help
cron	定时触发	"0 8 * * *"

响应类型

类型	说明
text	纯文本，支持变量插值
script	内联 Python 脚本（受限环境）
script_file	执行 .py 或 .js 文件
system	系统命令（需白名单+管理员）

脚本执行模式

在触发器配置或全局配置中设置 execution_mode：

• none: 禁用脚本执行
• sandbox: 在 venv 沙箱中执行
• local: 本地执行（非管理员强制使用 venv）

支持 script_type: python / node / inline

管理命令

命令	权限	说明
/cf	所有人	主命令
/cf 帮助	所有人	显示帮助
/cf 查询 <名称>	所有人	查询触发器详情
/cf 重载	管理员	手动重载配置
/cf 重载api	管理员	重载 API 方法注册表
/cf 群添加 ...	群管	添加群专属触发器
/cf 群删除 <名称>	群管	删除群专属触发器
/cf 群列表	所有人	列出群专属触发器
/cf 强制解锁群 [群号]	管理员	强制解锁指定群
/cf 强制解锁全局	管理员	强制解除全局锁定
/cf 紧急停止	群管	发起紧急停止投票
/cf 紧急清除 [群号]	管理员	紧急清除群触发器
/cf 支持	所有人	支持当前投票
/cf 反对	所有人	反对当前投票
/cf 状态	所有人	查看紧急状态和去重统计

环境变量

脚本执行时自动注入：

• CT_user_id, CT_user_name, CT_group_id, CT_time, CT_date
• CT_args, CT_match, CT_message
• 以及所有 OneBot V11 API 函数

注意事项

• 沙箱路径自动检测失败时需手动设置 sandbox_path
• 系统命令仅限 AstrBot 管理员调用
• 隐私相关操作（如获取好友列表）会转发给 AB 管理员私聊
• Cron 定时触发需安装 croniter

---

📝 关于隐藏功能

本插件在代码中内置了一些额外命令，如需启用或修改这些功能，请直接编辑 commands.py 文件。

掺杂私料，可以在文件中更改。