TTS文本过滤插件
一个智能的AstrBot TTS文本过滤插件，专门用于清理不适合语音朗读的内容，让TTS输出更加自然流畅。
仅适用于astrbot4.5.0之前的版本！
✨ 主要特性
- 🎭 颜文字过滤: 自动移除
(＾_＾),(>_<),o_o等颜文字 - 🎨 特殊符号清理: 过滤 ★♪♥💖→ 等装饰性符号和表情符号
- 🔄 智能替换:
233→哈哈哈,666→厉害,555→呜呜呜 - 🗑️ 直接过滤: 完全移除
orz,QAQ,TAT等不适合朗读的词汇 - 📝 重复字符压缩:
哈哈哈哈哈→哈哈(可配置保留数量) - 📏 字数限制: 超过指定字数自动跳过TTS朗读
- 🛡️ 超长文本保护: 可配置最大处理长度，防止处理超长文本
- ⚙️ 灵活配置: 支持正则表达式自定义过滤规则
- 🔧 实时调试: 可开启调试模式查看详细过滤过程
- 📊 状态监控: 提供测试命令和统计信息
- 🎯 只过滤TTS: 用户看到的文本保持原样，只影响语音朗读
🚀 快速开始
安装方法
- 将插件文件放入AstrBot的插件目录
- 重启AstrBot或使用插件管理功能加载
- 插件会自动启用，使用默认配置即可开始工作
基本使用
插件安装后会自动工作，无需额外配置。当机器人回复包含不适合TTS的内容时，会自动进行过滤：
用户看到的文本: 你好(＾_＾)这是测试233哈哈哈哈♪
TTS朗读内容: 你好 这是测试 哈哈哈 哈哈
💡 核心机制: 插件会临时修改文本供TTS使用，然后立即恢复原文本。用户在聊天界面看到的是完整的原始文本，只有TTS朗读的是过滤后的版本。
🎮 命令使用
测试命令
/tts_filter_test [测试文本]
测试过滤效果，查看处理前后的对比。
示例:
/tts_filter_test 你好(＾_＾)这是测试233哈哈哈哈♪
📝 原文 (15 字符):
你好(＾_＾)这是测试233哈哈哈哈♪
🔧 过滤后 (9 字符):
你好这是测试哈哈哈
⚙️ 当前配置:
• 直接过滤: orz, QAQ, TAT等
• 替换规则: 233→哈哈哈, 666→厉害等
📊 处理结果:
• 字符压缩率: 40.0%
• TTS状态: ✅ 可朗读
状态查看
/tts_filter_stats
查看插件运行状态和当前配置信息。
配置重载
/tts_filter_reload
重新加载配置文件，使配置修改立即生效。
⚙️ 配置说明
插件支持通过AstrBot配置面板进行设置，主要配置项包括：
基础设置
- 启用过滤 (
enabled): 总开关，控制是否启用过滤功能 - 最大朗读字数 (
max_length): 超过此字数将跳过TTS (0=无限制) - 最大处理长度 (
max_processing_length): 超过此长度将跳过过滤，防止处理超长文本 - 调试模式 (
debug_mode): 是否输出详细的处理日志
过滤规则
- 颜文字过滤规则 (
emoticon_patterns): 正则表达式列表，匹配需要过滤的颜文字 - 直接过滤词汇 (
filter_words): 完全不朗读的词汇列表 - 替换词汇配置 (
replacement_words): 替换规则，格式为"原词|替换词" - 特殊符号过滤 (
filter_special_chars): 是否过滤装饰性符号和表情 - 重复字符处理 (
filter_repeats): 是否压缩重复字符 - 最大重复数量 (
max_repeat_count): 保留的最大重复字符数量
默认配置
{
"enabled": true,
"max_length": 200,
"max_processing_length": 10000,
"emoticon_patterns": [
"[（(][^（()]*[）)]",
"[＞>][＿_][＜<]",
"[＾^][＿_][＾^]",
"[oO][＿_][oO]",
"[xX][＿_][xX]",
"[－-][＿_][－-]",
"[（(][；;][＿_][；;][）)]"
],
"filter_words": ["orz", "OTZ", "QAQ", "QWQ", "TAT", "TUT"],
"replacement_words": [
"233|哈哈哈",
"666|厉害",
"999|很棒",
"6|厉害",
"555|呜呜呜"
],
"filter_special_chars": true,
"special_char_patterns": [
"[★☆♪♫♬♩♡♥❤️💖💕💗💓💝💟💜💛💚💙🧡🤍🖤🤎💔❣️💋]",
"[→←↑↓↖↗↘↙↔↕↺↻]"
],
"filter_repeats": true,
"max_repeat_count": 2,
"debug_mode": false
}
🔧 工作原理
核心机制：临时修改 + 立即恢复
┌─────────────┐
│ LLM 回复 │
└──────┬──────┘
│
▼
┌─────────────────────────────┐
│ 本插件 (优先级 -1001) │
│ 1. 保存原始文本 │
│ 2. 应用过滤规则 │
│ 3. 临时修改为过滤后的文本 │
│ 4. 使用 call_soon 调度恢复 │
└──────┬──────────────────────┘
│
▼
┌─────────────────────────────┐
│ TTS 插件 (优先级 -1000) │
│ 读取过滤后的文本进行朗读 │
└──────┬──────────────────────┘
│
▼
┌─────────────────────────────┐
│ 事件循环下一次迭代 │
│ 执行 call_soon 恢复原文本 │
└──────┬──────────────────────┘
│
▼
┌─────────────────────────────┐
│ 消息发送给用户 │
│ 用户看到原始完整文本 │
└─────────────────────────────┘
过滤流程
在临时修改阶段应用以下过滤规则：
- 颜文字移除 - 使用正则表达式匹配并删除
- 直接过滤词汇移除 - 完全删除不适合朗读的词
- 词汇替换 - 将网络用语转换为可朗读的词汇
- 特殊符号移除 - 删除装饰性符号和表情
- 重复字符压缩 - 将多个重复字符压缩到指定数量
- 多余空格清理 - 清理多余的空白字符
技术要点
为什么使用 call_soon？
call_soon将恢复操作调度到事件循环的下一次迭代- 保证在当前钩子链执行完毕后才恢复文本
- TTS 插件在当前迭代中读取过滤后的文本
- 消息发送在下一次迭代时使用恢复后的原文本
- 这是在框架限制下的最佳实践
优先级设计
- 本插件优先级: -1001
- TTS 插件通常: -1000
- 确保过滤在 TTS 处理之前执行
🐛 故障排除
常见问题
Q: 过滤不生效怎么办？
A: 检查插件是否启用，使用 /tts_filter_stats 查看状态，确认配置正确。
Q: 用户看到的文本也被过滤了？
A: 检查是否使用了正确的 call_soon 机制。如果问题持续，开启调试模式查看日志。
Q: 配置修改后不生效？
A: 使用 /tts_filter_reload 重新加载配置，或重启AstrBot。
Q: 正则表达式报错？
A: 检查配置中的正则表达式语法，可以使用在线正则测试工具验证。
Q: TTS 朗读超长文本导致卡顿？
A: 调整 max_processing_length 配置，对超长文本跳过处理。
调试方法
- 开启调试模式: 在配置中设置
debug_mode: true - 使用测试命令:
/tts_filter_test验证过滤效果 - 检查统计信息:
/tts_filter_stats确认插件运行状态 - 查看日志: 开启调试模式后查看详细的处理过程
📈 性能优化
- 高效正则: 使用编译后的正则表达式提高匹配速度
- 智能跳过: 空文本或超长文本直接跳过处理
- 长度保护: 可配置最大处理长度，防止处理超长文本
- 性能监控: 处理时间超过 0.1 秒会记录警告日志
- 内存优化: 及时清理临时变量，避免内存泄漏
- 异步处理: 使用异步方法，不阻塞主线程
🔄 版本历史
v0.3 (当前版本)
- ✅ 新增配置项: 添加
max_processing_length配置，可自定义最大处理长度 - 🔧 代码优化: 统一导入语句到文件顶部，符合 PEP 8 规范
- 🛡️ 增强防护: 消除硬编码的魔术数字，提高代码可维护性
- 📝 文档完善: 更新文档，准确反映实际功能和工作原理
- ⚡ 性能稳定: 保持
call_soon机制，经过实际测试的稳定方案
- ✅ 新增配置项: 添加
v0.2
- 分离过滤和替换功能
- 优化配置界面和错误处理
- 移除数据持久化，简化架构
- 添加详细的调试和统计功能
- 改进正则表达式匹配性能
- 使用
call_soon实现可靠的文本恢复机制
v0.1
- 初始版本，基础过滤功能
📝 许可证
MIT License - 详见 LICENSE 文件
🤝 贡献
欢迎提交Issue和Pull Request来改进这个插件！
📞 支持
如有问题，请通过以下方式获取帮助：
- 提交GitHub Issue
- 查看AstrBot官方文档
- 使用插件内置的测试和统计命令