SuggarChat Logo

SuggarChat

基于 AmritaCore 的轻量完整聊天智能体插件

PyPI Version Python Version NoneBot Version License QQ Group

✨ 特性一览

本插件定位为轻量完整的聊天智能体，面向日常聊天场景； 如需体验完整的 Agent 编排能力（复杂工具链、任务编排等），请迁移至 AmritaBot。

🚀 核心功能

  • ✅ 开箱即用的多种模型协议支持（OpenAI / DeepSeek / Gemini 等）
  • ✅ 可独立运行的聊天机器人
  • ✅ 支持群聊与私聊双模式
  • ✅ AT 触发与智能上下文管理
  • ✅ 戳一戳消息交互支持
  • ✅ 多模型热切换
  • ✅ 多角色（预设）热切换
  • ✅ 会话生命周期管理（超时自动清理 / 手动续聊）
  • ✅ Function Calling 支持
    • ✅ 内置聊天不良内容检测（可配置熔断）
    • ✅ 基于 Cookie 检测的提示词防泄露
  • ✅ 可选 MCP 支持

🧩 扩展体系

  • 🔌 模块化模型预设架构（config/models/）
  • 🧠 自定义提示词模板体系（config/prompts/）
  • 📦 基于 nonebot-plugin-orm 的持久化存储
  • 🧰 插件 API 全开放，易于开发拓展

🛠️ 高级功能

  • 🤖 自动回复模式（概率性随机触发）
  • ♻️ 消息撤回缓解机制
  • 🚨 异常日志自动推送管理群
  • ⏱️ 会话生命周期控制
  • 📊 每日用量统计与频率限制（群 / 用户 / 全局）
  • 🦺 提示词防泄露

📦 安装

提供两种安装方式：

  • 方法一（推荐）：

    nb plugin install nonebot-plugin-suggarchat

  • 方法二（手动安装）：

    pip install nonebot_plugin_suggarchat[openai]

    若使用方法二，还需在 pyproject.toml 中手动添加插件名：

    plugins = ["nonebot_plugin_suggarchat"]

🚀 快速部署

完整配置说明请查阅 📘 使用文档。

环境要求

  • Python 3.10+
  • NoneBot2 ≥ 2.4.0
  • 一个 OneBot V11 协议端（如 NapCat / Lagrange / go-cqhttp 等）

安装

nb plugin install nonebot-plugin-suggarchat

或在 pyproject.toml 中手动添加并安装依赖：

[tool.nonebot]
plugins = ["nonebot_plugin_suggarchat"]
adapters = [
    { name = "OneBot V11", module_name = "nonebot.adapters.onebot.v11" },
]

pip install nonebot_plugin_suggarchat

首次启动

nb run

首次启动会自动创建插件数据目录，目录位置由 nonebot-plugin-localstore 管理。 以 Linux 为例，默认位于：

~/.local/share/nonebot2/nonebot_plugin_suggarchat/
├── config.toml            # 插件主配置
├── models/                # 模型预设（*.json）
├── group_prompts/         # 群聊提示词模板（*.txt）
└── private_prompts/       # 私聊提示词模板（*.txt）

配置模型

  1. 在 models/ 目录下新建 my_model.json（可参考仓库内 config/models/deepseek-v3.json）：

    {
  "model": "deepseek-chat",
  "name": "DS-V3",
  "base_url": "https://api.deepseek.com",
  "api_key": "sk-你的密钥",
  "config": {
    "top_k": 50,
    "top_p": 0.8,
    "temperature": 0.6,
    "stream": false,
    "multimodal": false
  }
}

  2. 编辑 config.toml，启用聊天并指定默认模型：

    enable = true
preset = "my_model"

[core.llm]
max_tokens = 1000
llm_timeout = 60

  3. 保存后配置会自动热重载（无需重启）；也可以使用 /presets、/set_preset 在线切换模型。

提示：enable = false 时机器人不响应任何聊天消息；如需完整 Agent 编排能力，请迁移至 AmritaBot。

🧭 快速参考

常用命令

直接发送消息即可与机器人聊天；发送 /menu 或 /菜单 可随时查看功能菜单。

/menu              — 查看聊天功能菜单
/prompt            — 自定义提示词
/choose_prompt     — 切换提示词模板
/presets           — 查看模型列表
/set_preset <名>   — 切换模型
/sessions          — 会话管理
/del_memory        — 清除记忆
/show-abstract     — 查看摘要
/insights          — 今日用量
/chatobj           — 会话状态
/mcp               — MCP 管理
/debug on|off|status — 调试开关
/chat on|off       — 启用/禁用聊天
/chat auto on|off  — 自动回复开关
/chat status       — 查看聊天状态

权限说明

等级 说明 命令示例
超级用户 全局 SUPERUSERS /presets /set_preset /choose_prompt /sessions /debug /mcp
群管理 群主 / 管理员 / 超级用户 /prompt /chatobj /chat
普通用户 所有人 /menu /del_memory /show-abstract /insights

核心配置速览

配置项 说明 默认值
enable 是否启用聊天能力 false
preset 默认使用的模型预设名称 "default"
function.enable_group_chat 是否启用群聊功能 true
function.enable_private_chat 是否启用私聊功能 true
function.poke_reply 是否响应戳一戳事件 true
session.session_control 是否启用会话超时自动清理 false
autoreply.enable 是否启用自动回复系统 false
core.llm.max_tokens 单次回复最大 Token 数 1000
core.llm.llm_timeout LLM 请求超时（秒） 60
core.llm.memory_length_limit 记忆保留条数 50
usage_limit.enable_usage_limit 是否启用使用频率限制 false

💬 社区支持

如需帮助或参与讨论，欢迎加入我们的官方 QQ 群：1006893368

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for JohnRichard4096 from gravatar.com JohnRichard4096

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: LiteSuggarDEV

License

GPL-3.0-or-later

Requires

Python <3.14, >=3.10

Tags

chat suggar nonebot

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nonebot_plugin_suggarchat-4.0.0.tar.gz (85.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nonebot_plugin_suggarchat-4.0.0-py3-none-any.whl (109.2 kB view details)

Uploaded Python 3

File details

Details for the file nonebot_plugin_suggarchat-4.0.0.tar.gz.

File metadata

  • Download URL: nonebot_plugin_suggarchat-4.0.0.tar.gz
  • Upload date:
  • Size: 85.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for nonebot_plugin_suggarchat-4.0.0.tar.gz
Algorithm Hash digest
SHA256 061112ff6297d34a34c313fb3f5de0d5203d0ddd1087ca0a0dedacecdf949e5a
MD5 82628d774e05bcb8ceb2716567c07d18
BLAKE2b-256 87a4e81ac4f8f0c7d313ab4f1ada2dc0d4bb26507fcb2073bedb35ac5adf390e

See more details on using hashes here.

File details

Details for the file nonebot_plugin_suggarchat-4.0.0-py3-none-any.whl.

File metadata

  • Download URL: nonebot_plugin_suggarchat-4.0.0-py3-none-any.whl
  • Upload date:
  • Size: 109.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for nonebot_plugin_suggarchat-4.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a8a2f4db95aec423c97e4c7f57446611cbc98e9745da866cf769c5aca19b4f1a
MD5 748040691dcfb298b436dc4413c29299
BLAKE2b-256 5f8dde6fec643b3dc764347b46277c06bafd546c7b5ebcc7d19f258c9421bb32

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

4.0.0 This release

2 files

3.7.0

2 files

3.6.0

2 files

3.5.0

2 files

3.4.6.2

2 files

3.4.6.1

2 files

3.4.6

2 files

3.4.5.3

2 files

3.4.5.2

2 files

3.4.5.1

2 files

3.4.5

2 files

3.4.4.3

2 files

3.4.4.2

2 files

3.4.4.1

2 files

3.4.4

2 files

3.4.3.1

2 files

3.4.3

2 files

3.4.2

2 files

3.4.0

2 files

Pre-release

3.4.0.dev1

2 files

3.3.1.1

2 files

3.3.1

2 files

3.3.0

2 files

Pre-release

3.3.0.dev1

2 files

3.2.2

2 files

3.2.1.2

2 files

3.2.1.1

2 files

3.2.1

2 files

3.2.0.post1

2 files

3.2.0

2 files

Pre-release

3.2.0.dev7

2 files

Pre-release

3.2.0.dev6

2 files

Pre-release

3.2.0.dev5

2 files

Pre-release

3.2.0.dev4

2 files

Pre-release

3.2.0.dev3

2 files

Pre-release

3.2.0.dev2

2 files

Pre-release

3.2.0.dev1

2 files

3.1.2.post2

2 files

3.1.2.post1

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.1

2 files

3.0.0

2 files

Pre-release

3.0.0.dev2

2 files

Pre-release

3.0.0.dev1

2 files

2.4.7

2 files

2.4.6.post1

2 files

2.4.6

2 files

2.4.5.post2

2 files

2.4.4.post2

2 files

2.4.4.post1

2 files

2.4.4

2 files

2.4.3.post4

2 files

2.4.3.post3

2 files

2.4.3.post2

2 files

2.4.3.post1

2 files

2.4.3

2 files

2.4.2.post5

2 files

2.4.2.post4

2 files

2.4.2.post3

2 files

2.4.2.post2

2 files

2.4.2.post1

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0.post3

2 files

2.4.0.post2

2 files

2.4.0.post1

2 files

2.4.0

2 files

Pre-release

2.4.0.dev3

2 files

Pre-release

2.4.0.dev2

2 files

Pre-release

2.4.0.dev1

2 files

2.3.0.post1

2 files

2.3.0

2 files

Pre-release

2.3.0.dev3

2 files

Pre-release

2.3.0.dev2

2 files

Pre-release

2.3.0.dev1

2 files

2.2.0.post2

2 files

2.2.0.post1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.4.post8

2 files

2.0.4.post7

2 files

2.0.4.post6

2 files

2.0.4.post5

2 files

2.0.4.post4

2 files

2.0.4.post3

2 files

2.0.4.post2

2 files

2.0.4

2 files

2.0.3.1.post3

2 files

2.0.3.1.post2

2 files

2.0.3.1

2 files

2.0.3

2 files

2.0.2.post4

2 files

2.0.2.post3

2 files

2.0.2.post2

2 files

2.0.2.post1

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.15.7

2 files

1.15.6.1

2 files

1.15.6

2 files

1.15.5

2 files

1.15.4

2 files

1.15.3.1

2 files

1.15.3

2 files

1.15.2.1

2 files

1.15.2

2 files

1.15.1

2 files

1.15

2 files

1.14.2.1

2 files

1.14.2

2 files

1.14.1

2 files

1.14

2 files

1.13.3

2 files

1.13.2

2 files

1.13.1

2 files

1.13

2 files

1.12.5

2 files

1.12.1

2 files

1.12

2 files

1.11.1

2 files

1.11

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10

2 files

1.9.3

2 files

1.9.1

2 files

1.9.0

2 files

1.8.4

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

0.1.7.3

2 files

0.1.7.0

2 files

0.1.6.5

2 files

0.1.6.3

2 files

0.1.6.2

2 files

0.1.6

2 files

0.1.5.7.1

2 files

0.1.5.7

2 files

0.1.5.2

2 files

0.1.5.1

2 files

0.1.5

2 files

0.1.4.3

2 files

0.1.4.2.1

2 files

0.1.4.2

2 files

0.1.4.1

2 files

0.1.4

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page