English | 中文
AstrBot 自主学习插件
让 AstrBot 在群聊中持续采集、学习、审查并注入上下文，使 Bot 逐步具备表达风格、群组黑话、社交关系、长期记忆和人格演化能力。
功能 · 架构 · 安装 · WebUI · 文档 · 社区
版权与许可 / Copyright and License
作者: NickMo / Mo Zhiping (莫志平) — [email protected] / [email protected]；EterUltimate
维护者: EterUltimate
版权所有: Copyright © 2025-2026 NickMo (Mo Zhiping). All rights reserved (for personal components).
许可协议: 本项目采用 AGPL-3.0 开源协议，包含并衍生自 AstrBot（同为 AGPL-3.0）。基于本仓库的修改或衍生作品必须以相同协议分发。
Author: NickMo / Mo Zhiping — [email protected] / [email protected]; EterUltimate
Maintainer: EterUltimate
Copyright: Copyright © 2025-2026 NickMo (Mo Zhiping). All rights reserved (for personal components).
License: Licensed under AGPL-3.0. This project incorporates and is a derivative work of AstrBot (also AGPL-3.0). Any modifications or derivative works must be distributed under the same license.
使用前请先在 AstrBot 原生人格管理中手动备份当前人格。学习、审查和回滚机制不能替代外部备份。
免责声明与用户协议
使用本项目即表示您已阅读、理解并同意以下条款：
- 本项目仅供学习、研究和合法用途使用，严禁用于任何违反当地法律法规、平台服务条款或侵犯隐私的场景。
- 使用者需在采集和处理用户消息前取得必要授权，并遵守相关数据保护要求。
- 本项目按“原样”提供，开发者不对数据丢失、人格错误、系统崩溃或任何直接、间接损失承担责任。
- 因用户违规使用导致的法律纠纷，由用户自行承担全部责任。
- 本协议可能随项目更新而调整，继续使用即表示接受更新后的条款。
核心功能
| 功能 |
说明 |
| 对话风格学习 |
从群友之间的上下文对话提取表达模式，经审查后注入已批准样本 |
| 群组黑话学习 |
统计预筛高频词，结合上下文推断含义，并在 LLM 请求前注入解释 |
| 人格演化审查 |
学习结果先进入审查链路，支持批准、拒绝、删除、回滚和自动应用策略 |
| 社交关系分析 |
记录互动关系、好感度、心理状态和群组社交上下文 |
| 记忆与知识图谱 |
构建记忆图、知识图谱和可视化查询入口 |
| LLM 请求注入 |
在 on_llm_request 阶段注入社交、黑话、记忆、few-shot 和临时人格增量 |
| WebUI Dashboard |
提供全量设置、审查、黑话、图谱、学习内容、日志等级和指标监控 |
| 多数据库支持 |
支持 SQLite、MySQL、PostgreSQL，包含自动建表和轻量迁移 |
插件不会直接替换 AstrBot 的回复逻辑。它在消息进入、Bot 回复发送后、下一次 LLM 请求前这三个位置增强 AstrBot。
架构总览
flowchart TB
subgraph AstrBot["AstrBot 框架"]
Event["消息事件 on_message"]
Sent["发送后事件 after_message_sent"]
Req["LLM 请求 on_llm_request"]
end
subgraph Plugin["SelfLearningPlugin"]
Lifecycle["PluginLifecycle"]
Factory["FactoryManager / ServiceFactory"]
Commands["管理命令"]
Hook["LLMHookHandler"]
end
subgraph Learning["学习服务层"]
Pipeline["MessagePipeline"]
Realtime["RealtimeProcessor"]
Progressive["ProgressiveLearningService"]
Quality["LearningQualityMonitor"]
Jargon["JargonMiner / JargonQuery"]
Persona["Persona / Style Review"]
Social["Affection / Social / State"]
end
subgraph Data["数据层"]
Manager["SQLAlchemyDatabaseManager"]
Engine["DatabaseEngine"]
Facades["Domain Facades"]
ORM["models/orm"]
end
subgraph WebUI["WebUI"]
Quart["Quart API"]
Dashboard["Dashboard 静态页面"]
Graphs["图谱与审查界面"]
end
Event --> Pipeline
Sent --> Manager
Req --> Hook
Lifecycle --> Factory
Factory --> Learning
Pipeline --> Realtime
Pipeline --> Progressive
Pipeline --> Jargon
Progressive --> Quality
Progressive --> Persona
Hook --> Social
Hook --> Jargon
Hook --> Manager
Learning --> Manager
Manager --> Facades
Facades --> Engine
Engine --> ORM
Quart --> Manager
Dashboard --> Quart
Graphs --> Quart
Commands --> Learning
学习链路示意
sequenceDiagram
participant U as 用户消息
participant P as on_message
participant M as MessagePipeline
participant DB as 数据库
participant R as 实时学习
participant G as 群组批量学习
participant Review as 审查队列
participant H as LLMHookHandler
participant LLM as AstrBot LLM 请求
U->>P: AstrMessageEvent
P->>M: 后台处理消息
M->>DB: 保存 RawMessage
M->>R: 表达模式 / 实时学习
M->>G: 达到阈值后启动批量学习
G->>DB: 筛选消息并创建学习会话
G->>Review: 写入人格审查 / 风格审查
LLM->>H: 下一次请求前触发
H->>DB: 读取已批准 few-shot / 黑话 / 记忆 / 社交关系
H->>LLM: 临时 extra_user_content_parts 注入，旧版 fallback
flowchart LR
Raw["原始消息 RawMessage"] --> Filtered["筛选消息 FilteredMessage"]
Raw --> Expression["表达模式 ExpressionPattern"]
Raw --> Jargon["黑话 Jargon"]
Raw --> Pair["群友 A -> 群友 B 上下文对话"]
Pair --> StyleReview["风格审查 StyleLearningReview"]
Filtered --> PersonaReview["人格审查 PersonaLearningReview"]
StyleReview --> Approved["作用域匹配的批准样本"]
Jargon --> Context["LLM 注入上下文"]
Approved --> Context
PersonaReview --> Context
快速开始
安装
进入 AstrBot 插件目录：
cd C:\path\to\AstrBot\data\plugins
git clone https://github.com/EterUltimate/self_learning_EterU.git astrbot_plugin_self_learning
重启 AstrBot 或在插件管理页重新加载插件。
依赖安装
当前代码不会在插件安装或启动阶段自动安装 pip 依赖。安装完成后，请进入 self-learning WebUI Dashboard 的全量设置页，手动点击“基础能力依赖”或“全能力依赖”。
依赖安装接口只接受 WebUI 明确确认后的请求：
{"manual_confirmed": true, "source": "webui_settings"}
如果部署环境禁止 WebUI 安装依赖：
$env:ASTRBOT_ENABLE_WEB_DEP_INSTALL="false"
访问 WebUI
默认地址：
http://127.0.0.1:7833
当前 WebUI 默认免密访问。若 web_interface_host=0.0.0.0，局域网内可使用服务器 IP 访问。
远程服务器 / Docker 容器部署的端口映射、防火墙放行、密码与隧道访问，见 远程部署与连接指南。
内嵌面板可在 AstrBot 管理面板（默认 http://127.0.0.1:6185）的插件管理中直接打开，功能与独立 WebUI 对齐（黑话、表达、人格、影子模式、审查、内容、图谱、功能融合、监控、设置），无需额外端口。独立 WebUI 保留为后续改动的 alpha 试验区。
基础配置顺序
- 备份当前人格。
- 设置学习目标：
Target_Settings.target_qq_list 和 target_blacklist。
- 设置 Provider：
filter_provider_id、refine_provider_id、reinforce_provider_id。
- 配置数据库：默认 PostgreSQL，会自动创建缺失数据库、schema 和表；可显式切换 SQLite 或 MySQL。
- 按需开启表达学习、黑话学习、自动学习、记忆图和知识图谱。
Provider 未配置时插件仍可加载，但 LLM 相关功能会降级并写入日志。
WebUI Dashboard
插件提供两套视觉与功能一致的管理界面（endfield 设计语言：纸白/炭墨底、信号黄动作标记、方角工程面板，支持亮/暗主题与 reduced-motion）：
- 独立 WebUI：
http://127.0.0.1:7833（可在配置中改端口/监听地址/登录密码）
- 内嵌插件页：AstrBot 插件管理页直接打开，经官方
page/* 桥接通信，无需额外端口。自 2026-11 起与独立版逐路由对齐——同文案、同功能、同交互；差异仅限平台固有限制（内嵌无图标字体、图表用简化条形图、WebUI 密码与自定义 CSS 仅独立版有意义）
模块入口首页（①顶栏刷新/主题/设置 ②十四模块导航 ③指挥台与快捷入口 ④学习模块卡 ⑤系统入口卡实时读数）：
审查队列（①页题 ②逐条通过/驳回/删除含变更差异 ③全部/所选批量操作 ④最近学习批次：重跑与删除）：
情绪中枢（内嵌版；①情绪读数 ②Bot 心情 ③好感度排行 ④走向分析 ⑤情绪加权闸门 ⑥三阶段遗忘治理）：
全部 14 个路由：
| 路由 |
内容 |
| 模块入口 |
指挥台总貌：4 读数、学习模块卡、8 个系统入口实时状态 |
| 总览 |
消息/学习趋势与当前状态快照 |
| AI 巡检 |
按快照生成可执行关注事项（积压、过滤、健康、降级、委托） |
| 运行监控 |
健康检查、函数热点、模型调用与综合评分 |
| 审查队列 |
人格 / 风格 / 黑话三栏审查 + 最近学习批次（重跑/删除） |
| 黑话学习 |
词库检索、原地编辑、批量操作、全局/本地范围、导入 |
| 表达学习 |
风格统计、表达样本库（对话/分析/特征/历史）、学习模式 |
| 人格学习 |
当前人格、人格列表、备份恢复、最近已审查（撤回）、待审更新 |
| 影子模式 |
选择群友学习其表达习惯，档案启停 |
| 情绪中枢 |
心情、好感度、走向、加权闸门、三阶段遗忘治理 |
| 学习内容 |
按类型浏览/检索/清理表达学习数据 |
| 图谱 |
记忆 / 知识 / 社交关系图谱 |
| 功能融合 |
伴随插件状态、世界书 / QQ / MaiBot 导入 |
| 设置 |
全量配置、依赖安装、数据管理、Bug 反馈 |
更多截图：总览 · 黑话学习 · 表达学习 · 人格学习 · 影子模式 · 学习内容 · 图谱 · 社交关系 · 功能融合 · 设置
修改数据库类型、数据目录、WebUI host/port 后需要重启插件。日志等级和多数学习阈值可立即生效。
数据库
| 类型 |
Driver |
适用场景 |
| PostgreSQL |
postgresql+asyncpg |
默认后端，长期运行、schema 隔离、多实例部署 |
| SQLite |
sqlite+aiosqlite |
显式配置的单机回退 |
| MySQL |
mysql+aiomysql |
显式配置的兼容后端 |
数据库层使用 SQLAlchemy async ORM。SQLAlchemyDatabaseManager 对外保持旧接口兼容，内部通过 Domain Facade 路由到消息、学习、黑话、人格、社交、表达、心理状态、强化学习、指标和管理等领域。
默认 PostgreSQL 启动时会先连接维护库 postgres，如果目标库不存在则创建 astrbot_self_learning，再创建缺失 schema 和 ORM 表。默认数据库用户需要具备创建数据库、schema 和表的权限。没有 PostgreSQL 服务时，可显式设置 Database_Settings.db_type=sqlite 回退到本地文件数据库。
自动建表会执行：
Base.metadata.create_all- 检查缺失表和缺失列
- 自动创建 ORM 中存在但数据库缺失的表
- 对已有表补齐新增列
自动迁移只做列级新增，不做字段删除、重命名或类型变更。
管理命令
所有命令需要 AstrBot 管理员权限。
| 命令 |
说明 |
/learning_status |
查看学习状态和统计 |
/start_learning |
手动启动学习 |
/stop_learning |
停止学习 |
/force_learning |
强制执行一次学习 |
/remember <引用或上下文> => <表达示例> |
手动记住对话上下文，并链入表达方式和对话示例 |
/affection_status |
查看好感度状态 |
/set_mood <类型> |
设置 Bot 情绪 |
常见排查
插件加载失败：缺少依赖
确认已经通过 WebUI Dashboard 手动安装依赖。安装阶段不会自动执行 pip install。
WebUI 打不开
检查：
enable_web_interface=True- 端口
7833 是否被占用
- AstrBot 日志中是否有 Web 服务器启动成功信息
- 修改 host/port 后是否已重启插件
学不到内容
按顺序检查：
enable_message_capture=True- 当前用户或群组未被黑名单排除
RawMessage 是否增长- 消息长度是否满足阈值
enable_expression_patterns=True- Bot 出站文本是否进入
BotMessage
- 群组消息是否达到
min_messages_for_learning
- 是否存在 pending 审查记录但未批准
- Provider 是否可用
数据库建表失败
检查：
- 数据库驱动是否已安装
- 数据库用户是否有创建数据库、schema 和表的权限
- PostgreSQL schema 名称是否有效
- SQLite 数据目录是否可写
开发和文档
详细文档位于 docs/：
关键源码入口：
main.pycore/plugin_lifecycle.pycore/factory.pyservices/learning/message_pipeline.pyservices/core_learning/progressive_learning.pyservices/hooks/llm_hook_handler.pyservices/database/sqlalchemy_database_manager.pycore/database/engine.pywebui/manager.py, webui/server.py, webui/app.py
社区交流
推荐搭配
LivingMemory 长期记忆插件
群聊增强插件 Group Chat Plus
本插件负责学习、审查、黑话、表达方式和上下文注入；LivingMemory 负责长期记忆、召回和反思；Group Chat Plus 负责回复决策、读空气和回复生成。三者组合时，本插件会在检测到目标插件已加载后自动跳过本地重叠能力，避免重复记忆或重复回复。
开源协议
本项目采用 AGPL-3.0 License 开源协议。
特别鸣谢
如果觉得有帮助，欢迎 Star、投喂支持。
回到顶部
好感度只读查询工具
query_affection 查询数据库中的本人分数或当前群排行，不请求模型、不修改分数。普通成员只能查询本人；排行和他人查询需全局管理员，跨群查询仅限管理员私聊明确指定机器人已加入的群号。查询沿用现有 affection_scope，不迁移或合并历史记录。
该工具独立于通用 enable_llm_hooks，不会为查询开启社交分析或人格学习。数据库未就绪、查询失败和缺少记录分别返回状态；同分用户并列，未记录成员不按零分排名。
评论