Van词库

基于原Van词库，专为AstrBot框架适配的智能关键词响应系统

📋 目录

• 🎯 现有功能
• ✨ 新添功能
• 📝 更新日志
• 🏗️ 核心架构
• 📁 目录结构
• 🔧 适配说明
• 🚀 快速开始
• ⚙️ 配置说明

🎯 现有功能

1. 核心响应系统

• ✅ 多模式关键词匹配

  • 精确匹配（关键词完全一致）
  • 模糊匹配（关键词包含在消息中）
  • 管理员模式（仅限管理员触发）
  • 通配符匹配 [n.1] 到 [n.5]

• ✅ 智能变量替换

  • [qq] - 触发者QQ号
  • [group] - 群组ID（私聊为空）
  • [name] - 发送者昵称
  • [card] - 群名片
  • [id] - 消息ID
  • [ai] - 机器人ID

• ✅ 特殊语法支持

  • 随机数生成 (1-100)
  • 安全数学计算 (+1+2*3)
  • 冷却时间控制 (3600~)
  • 条件判断 {Y>10}

2. 媒体消息支持

• ✅ 图片消息 - [图片.url] 或 [image.url]
• ✅ @提及 - [艾特.QQ号] 或 [at.QQ号]
• ✅ 表情包 - [表情.id] 或 [face.id]
• ✅ 回复消息 - [回复] 或 [reply]
• ✅ 语音消息 - [语音.url] 或 [record.url]
• ✅ 戳一戳 - [poke.QQ号]

3. 词库管理系统

• ✅ 多词库支持

  • 个人词库（私聊独立）
  • 群组词库（群聊共享）
  • 自定义词库（按需切换）

• ✅ 词库操作

  • 关键词添加/删除
  • 回复选项增删
  • 词条批量导入导出
  • 词库备份恢复

• ✅ 配置管理

  • 开关配置（switch.txt）
  • 选择配置（select.txt）
  • 管理员权限控制

4. 性能优化

• ✅ 内存缓存 - 减少文件IO操作
• ✅ 异步处理 - 非阻塞式响应
• ✅ 冷却系统 - 防止消息刷屏
• ✅ 防抖保存 - 避免文件竞态条件

✨ 新添功能

1. AstrBot专属功能

• 🆕 内置词库系统

  • 7个预设互动关键词
  • 开箱即用的趣味对话
  • 可导入到任意词库

• 🆕 统一指令系统

  • /keyword 命令组管理
  • 支持别名（关键词、词库）
  • 层级清晰的子命令

• 🆕 可视化配置

  • WebUI配置支持
  • 实时配置生效
  • 友好的配置界面

• 🆕 标准化权限管理

  • AstrBot原生权限系统
  • 管理员列表配置
  • 群组/用户忽略名单

2. 增强的管理功能

• 🆕 内置词库管理

  • 查看内置词条列表
  • 一键导入到指定词库
  • 内置词库版本控制

• 🆕 增强的备份功能

  • 自动备份带时间戳
  • 备份文件大小显示
  • 备份目录结构化管理

• 🆕 命令别名支持

  • /关键词 - 中文命令支持
  • /词库 - 更直观的命令名称

3. 安全增强

• 🆕 数学表达式安全求值

  • 使用simpleeval库
  • 限制可用的运算符
  • 防止代码注入攻击

• 🆕 异步冷却管理器

  • 避免文件锁问题
  • 定时清理过期数据
  • 内存与文件双缓存

4. 开发者体验

• 🆕 结构化日志

  • 分级日志输出
  • 详细的调试信息
  • 错误追踪定位

• 🆕 模块化设计

  • 清晰的类职责分离
  • 易于扩展的新功能
  • 可维护的代码结构

📝 更新日志

版本 1.1.0 (当前版本)

发布日期: 2025年月28日

🚀 新增功能

• ✅ 完整内置词库系统（7个预设关键词）
• ✅ AstrBot指令组集成（解决指令冲突）
• ✅ 内置词库管理命令（list/import）
• ✅ 增强的备份功能（时间戳+文件大小）
• ✅ 安全的数学表达式求值器

🔧 技术改进

• ✅ 重构搜索逻辑（优先内置词库）
• ✅ 优化冷却管理器（异步防抖）
• ✅ 改进变量替换系统
• ✅ 增强错误处理和日志

🐛 问题修复

• ✅ 修复指令冲突问题
• ✅ 修复文件路径问题
• ✅ 修复冷却时间计算
• ✅ 修复词库加载异常

🏗️ 核心架构

核心类说明

1. KeywordManager - 词库管理器

职责: 词库的加载、保存、搜索和切换逻辑
核心功能:

• 🔄 多词库管理（内置、用户、群组）
• 🔍 智能关键词搜索（精确/模糊/通配符）
• 💾 词库持久化（JSON文件存储）
• 🔧 配置管理（switch.txt/select.txt）
• 📦 内置词库系统（预设互动内容）

2. SafeMathEvaluator - 安全计算器

职责: 数学表达式的安全求值
核心功能:

• 🛡️ 安全运算符限制
• 🧮 基础四则运算支持
• 🔒 防止代码注入攻击
• 💾 表达式结果缓存
• ⚡ 高性能求值算法

3. CoolingManager - 冷却管理器

职责: 异步冷却时间控制
核心功能:

• ⏰ 冷却时间检查
• 🔄 异步数据持久化
• 🧹 过期数据自动清理
• 🔒 避免文件竞态条件
• ⚡ 防抖保存机制

4. KeywordPlugin - 主插件类

职责: 消息处理和命令接口
核心功能:

• 📨 消息事件处理（群聊/私聊）
• 🎮 管理员指令系统
• 📋 AstrBot命令组集成
• 🔒 权限验证管理
• 🔌 插件生命周期管理

数据流程图

• 用户消息 → KeywordPlugin → KeywordManager → 搜索词库
• ↓ ↓
• 权限验证 内置词库 → 用户词库 → 群组词库
• ↓ ↓
• 冷却检查 关键词匹配
• ↓ ↓
• 变量替换 SafeMathEvaluator
• ↓ ↓
• 特殊语法 冷却设置
• ↓ ↓
• 媒体组件 CoolingManager
• ↓ ↓
• 发送响应 保存

📁 目录结构

Van词库插件/
├── 📁 data/plugin_data/keyword_astrbot/
│ ├── 📁 lexicon/ # 词库存储目录
│ │ ├── builtin_default.json # 内置默认词库
│ │ ├── private_{QQ号}.json # 用户个人词库
│ │ ├── {群号}.json # 群组默认词库
│ │ └── {自定义词库名}.json # 自定义词库
│ ├── 📁 config/ # 配置文件目录
│ │ ├── switch.txt # 群组词库开关配置
│ │ └── select.txt # 用户词库选择配置
│ ├── 📁 cooling/ # 冷却数据目录
│ │ └── {词库名}.json # 冷却时间记录
│ ├── 📁 backups/ # 备份文件目录
│ │ └── {词库名}_{时间戳}.json # 自动备份文件
│ └── 📁 filecache/ # 文件缓存目录
│ └── {图片名}.jpg # 本地图片缓存
│
├── 📁 plugins/
│ └── keyword_plugin.py # 主插件文件
│
├── 📄 _conf_schema.json # 插件元数据
└── 📄 README.md # 使用说明文档

目录说明

lexicon/ - 词库存储

• builtin_default.json: 系统内置词库，包含预设互动
• private_{QQ号}.json: 私聊用户的个人词库
• {群号}.json: 群组的默认词库
• 按需创建的自定义词库

config/ - 配置管理

• switch.txt: 群组词库开关配置（群号=词库名）
• select.txt: 用户词库选择配置（QQ号=词库名）

cooling/ - 冷却系统

• 按词库存储冷却时间数据
• 异步保存避免阻塞
• 自动清理过期记录

backups/ - 备份系统

• 按时间戳自动命名
• 保持原始数据结构
• 支持手动恢复

🔧 平台兼容性

✅ QQ 个人号（OneBot v11）
✅ QQ 官方机器人
🔄 支持AstrBot其他平台（按需适配）

🔧 保留的功能

✅ 所有关键词匹配模式
✅ 变量替换系统
✅ 特殊语法处理
✅ 媒体消息支持
✅ 冷却时间控制
✅ 词库管理功能

🚀 快速开始

安装插件

⚙️ 配置说明

插件配置（WebUI）

内置词库内容

1. 喵撒娇 - 喵系撒娇互动
2. 早安 - 早安问候
3. 晚安 - 晚安问候
4. 今天天气如何 - 天气查询
5. 摸头 - 摸头互动
6. 抽卡 - 抽卡模拟
7. [n.1]多少好感 - 好感度查询

🤝 致谢

特别感谢：

• Van词库原作者 ZiYi - 为词库移植至AstrBot提供支持
• AstrBot开发团队 - 提供优秀的机器人框架
• 所有贡献者和用户 - 反馈和建议让插件更完善
  -开源协议： MIT License

项目地址： "https://github.com/TY-China/astrbot_plugin_van"