表达风格学习插件

让 AI 机器人学会群友的说话方式，回复时更有"人味"。

---

快速开始

1. 安装 — AstrBot 插件市场搜索"表达风格学习"，或手动放到 data/plugins/ 下
2. 重启插件
3. 什么都不用配 — 默认学习模式，进群开始观察，攒够消息自动触发学习
4. 效果 — 机器人回复中会自动加入群友常用的表达方式和黑话

刚装好是宽松的"学习模式"（不守卫、不防抖），最快感受效果。想控制 LLM 输出时，管理页一键切到"完整模式"。

💡 为确保效果最佳，建议在 AstrBot WebUI → 配置 → LTM（长期记忆）中开启：

• 主动图片理解（provider_ltm_settings.image_caption）— 让插件能理解群友发的图片内容，注入更准确的上下文（需同时配置图片转述模型 image_caption_provider_id）
• 主动回复（provider_ltm_settings.active_reply.enable）— 让机器人能像群友一样自然参与对话，学习到更多互动模式

---

工作流程

群友聊天 ──→ 插件默默观察、记录
                │
                ▼ 攒够 30 条消息
          LLM 总结表达方式（按情绪分类）
                │
                ▼ 后续 LLM 回复时
          自动注入风格提示 + 黑话解释

插件不修改原消息，只在每次 LLM 回复前追加一段上下文提示。

---

功能

功能	一句话
自动学习	观察群聊，记住常用表达方式和梗，按 16 种情绪分类
黑话词典	自动识别 yyds / xswl 这类缩写，推断含义并注入上下文
内容守卫	开启后 LLM 仅能通过工具发送消息，原生文本输出会被拦截
消息分段	长回复自动按标点拆成多条发送，保护颜文字和引号不被切开
图片感知	多模态模型直接看图；非多模态由 AstrBot 自动生成文字描述，插件缓存
WebUI 管理	管理页支持查看/审核/删除学到的表达和黑话

---

预设

管理页提供两套一键切换：

预设	适合场景	守卫	防抖	平滑
学习模式（默认）	先看效果，宽松运行	❌	❌	❌
完整模式	生产环境，控制输出	✅	✅	✅

---

管理页面

WebUI → 侧边栏 → 插件 → 找到本插件 → 点击"页面"

四标签页：

• 表达 — 按情绪/状态/群聊筛选，审核/编辑/删除
• 黑话 — 搜索，编辑含义，拒绝/删除
• 统计 — 概览、情绪分布、预设切换、手动触发学习、待学习队列
• 模板 — 自定义 Prompt 模板（留空使用默认值）

---

指令

在群聊中发送：

指令	作用
/style list	查看已学到的表达方式
/style list 开心	只看"开心"类的表达
/style stats	学习统计

---

配置

按组分类，不调可跳过：

学习

项	默认	说明
启用表达学习	开	总开关
启用黑话挖掘	开	总开关
最少学习消息数	30	攒够后触发一次学习
学习间隔	60 分钟	两次学习之间最少间隔

注入

项	默认	说明
注入模式	append	append=追加到上下文，both=额外注册 LLM 工具
选择模式	classic	classic=LLM 分析语境，random=随机抽取省 token
最大历史轮次	1	保留最近 N 轮对话，0=全部清除
最近消息数	0	注入 N 条最近群聊消息到上下文，0=关闭

守卫

项	默认	说明
内容守卫	关	拦截 LLM 非工具输出的文本
防抖	0 秒	连发时跳过中间消息，0=关闭
平滑	0 秒	连续 LLM 调用最小间隔，0=关闭
私聊自动优化	关	私聊时自动关闭守卫/防抖/平滑

数据范围

项	默认	说明
全局黑话	开	跨群共享黑话
全局表达	开	跨群共享表达方式
仅已审核	关	只使用管理员确认过的表达
自动审核	开	定期 LLM 审核新学到的表达

模型

项	默认	说明
模型覆盖	空	可分别指定 learn/selection/check/infer 用不同模型
Bot 名称	空	留空用平台默认名

其他

项	默认	说明
分段最大段数	3	长消息最多拆成几段发送
调试模式	关	开启后异常透传到日志栈

---

调试

设置日志级别为 DEBUG，所有插件日志以 [SL] 为前缀：

rg "\[SL\]"                           # 一键过滤插件日志

---

开发

架构

Dependencies.build()
  ├─ Repository(session)        ← 数据层（SQLAlchemy async）
  ├─ ExpressionSelector          ← 选择匹配的表达注入
  ├─ ExpressionLearner           ← LLM 学习表达
  ├─ JargonMiner / Explainer    ← 黑话挖掘与解释
  ├─ ExpressionReflector        ← 管理员审核提问
  ├─ ExpressionAutoCheckTask    ← 自动审核定时任务
  └─ MessageRecorder            ← 消息记录与学习触发

依赖注入设计，所有服务通过 container.py 的 Dependencies.build() 构建，测试可注入 mock。

测试

pytest tests/ -v                 # 105 个测试，全部通过

文件	数量	覆盖
test_utils.py	26	情绪检测/相似度/文本过滤/响应解析/上下文构建
test_selector.py	19	匹配打分/群组归属/表达选择/hint 构建
test_splitter.py	10	分词/分段/引号保护/颜文字保护
test_pipeline.py	35	6 个事件处理器的编排和配置组合

关键接口

• RepositoryProtocol (interfaces.py) — 40+ 异步方法，AsyncMock(spec=...) 保证 mock 不漏方法
• Dependencies (container.py) — DI 容器，_built 守卫防止未构建使用

---

关于图片

插件会缓存 AstrBot 生成的图片描述并注入到上下文中。需要在 AstrBot WebUI 配置图片转述提供商（default_image_caption_provider_id）才能生效。

• 非多模态模型：AstrBot 自动生成文字描述，插件缓存并注入
• 多模态模型：模型直接看图，历史图片由 AstrBot 的对话上下文携带