版权与许可 / Copyright and License

作者: NickMo / Mo Zhiping (莫志平) — nickmo318@outlook.com / max318515692@gmail.com

维护者: EterUltimate

版权所有: Copyright (c) 2025-2026 NickMo (Mo Zhiping). All rights reserved (for personal components).

许可协议: 本项目采用 GPLv3 开源协议，包含并衍生自 AstrBot（同为 GPLv3）。基于本仓库的修改或衍生作品必须以相同协议分发。

Author: NickMo / Mo Zhiping — nickmo318@outlook.com / max318515692@gmail.com

Maintainer: EterUltimate

Copyright: Copyright (c) 2025-2026 NickMo (Mo Zhiping). All rights reserved (for personal components).

License: Licensed under GPLv3. This project incorporates and is a derivative work of AstrBot (also GPLv3). Any modifications or derivative works must be distributed under the same license.

使用本项目即表示您已阅读、理解并同意以下条款：

1. 本项目仅供学习、研究和合法用途使用，严禁用于任何违反当地法律法规、平台服务条款或侵犯隐私的场景。
2. 使用者需在采集和处理用户消息前取得必要授权，并遵守相关数据保护要求。
3. 本项目按“原样”提供，开发者不对数据丢失、人格错误、系统崩溃或任何直接、间接损失承担责任。
4. 因用户违规使用导致的法律纠纷，由用户自行承担全部责任。
5. 本协议可能随项目更新而调整，继续使用即表示接受更新后的条款。

插件不会直接替换 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 或 system_prompt

flowchart LR
    Raw["原始消息 RawMessage"] --> Filtered["筛选消息 FilteredMessage"]
    Raw --> Expression["表达模式 ExpressionPattern"]
    Raw --> Jargon["黑话 Jargon"]
    Sent["Bot 出站消息 BotMessage"] --> Pair["user -> bot 对话对"]
    Pair --> StyleReview["风格审查 StyleLearningReview"]
    Filtered --> PersonaReview["人格审查 PersonaLearningReview"]
    StyleReview --> Approved["批准后的 few-shot"]
    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 系统设置，手动点击“安装依赖”。

依赖安装接口只接受设置页确认请求：

{"manual_confirmed": true, "source": "system_settings"}

如果部署环境禁止 WebUI 安装依赖：

$env:ASTRBOT_ENABLE_WEB_DEP_INSTALL="false"

默认地址：

http://127.0.0.1:7833

当前 WebUI 默认免密访问。若 web_interface_host=0.0.0.0，局域网内可使用服务器 IP 访问。

1. 备份当前人格。
2. 设置学习目标：Target_Settings.target_qq_list 和 target_blacklist。
3. 设置 Provider：filter_provider_id、refine_provider_id、reinforce_provider_id。
4. 选择数据库：默认 SQLite；可切换 MySQL 或 PostgreSQL。
5. 按需开启表达学习、黑话学习、自动学习、记忆图和知识图谱。

Provider 未配置时插件仍可加载，但 LLM 相关功能会降级并写入日志。

WebUI 提供以下入口：

• 总览：消息数、学习状态、待审数量、图谱数据和性能指标。
• 全量设置：读取 /api/config/schema，编辑所有公开配置项。
• 待审人格：批准、拒绝、删除、回滚人格学习结果。
• 风格审查：审查表达模式和 few-shot 对话。
• 黑话：查看候选词、含义、计数、群组和全局黑话同步。
• 学习内容：通过 /api/style_learning/content_text 查看原始消息、筛选消息、表达模式、学习批次和审查记录。
• 图谱：查看记忆图、知识图谱、社交关系图谱和分享链接。
• 日志等级：从 error 到 debug 动态调整 AstrBot 日志输出。
• 模型调用：监控筛选模型、提炼模型和强化模型调用情况，定位异常高频调用。

修改数据库类型、数据目录、WebUI host/port 后需要重启插件。日志等级和多数学习阈值可立即生效。

数据库层使用 SQLAlchemy async ORM。SQLAlchemyDatabaseManager 对外保持旧接口兼容，内部通过 Domain Facade 路由到消息、学习、黑话、人格、社交、表达、心理状态、强化学习、指标和管理等领域。

自动建表会执行：

1. Base.metadata.create_all
2. 检查缺失表和缺失列
3. 自动创建 ORM 中存在但数据库缺失的表
4. 对已有表补齐新增列

自动迁移只做列级新增，不做字段删除、重命名或类型变更。

所有命令需要 AstrBot 管理员权限。

确认已经通过设置页手动安装依赖。安装阶段不会自动执行 pip install。

检查：

• enable_web_interface=True
• 端口 7833 是否被占用
• AstrBot 日志中是否有 Web 服务器启动成功信息
• 修改 host/port 后是否已重启插件

按顺序检查：

1. enable_message_capture=True
2. 当前用户或群组未被黑名单排除
3. RawMessage 是否增长
4. 消息长度是否满足阈值
5. enable_expression_patterns=True
6. Bot 出站文本是否进入 BotMessage
7. 群组消息是否达到 min_messages_for_learning
8. 是否存在 pending 审查记录但未批准
9. Provider 是否可用

检查：

• 数据库驱动是否已安装
• 数据库用户是否有创建数据库、schema 和表的权限
• PostgreSQL schema 名称是否有效
• SQLite 数据目录是否可写

详细文档位于 docs/：

• 架构与实现
• 学习链路
• 数据库
• 配置
• WebUI API
• 使用指南
• 开发指南

关键源码入口：

• main.py
• core/plugin_lifecycle.py
• core/factory.py
• services/learning/message_pipeline.py
• services/core_learning/progressive_learning.py
• services/hooks/llm_hook_handler.py
• services/database/sqlalchemy_database_manager.py
• core/database/engine.py
• webui/manager.py, webui/server.py, webui/app.py

• QQ 群：1021544792（ChatPlus 插件用户 + 本插件用户）
• 提交 Bug
• 功能建议
• 贡献代码

群聊增强插件 Group Chat Plus

本插件负责学习、审查、记忆和人格优化；群聊增强插件负责回复决策和读空气。组合使用时，Bot 既能积累上下文，也能更稳地决定何时回复。

本项目采用 GPLv3 License 开源协议。

• MaiBot: 表达模式学习、知识图谱管理等核心设计思路
• AstrBot: 优秀的聊天机器人框架