nonebot-plugin-group-chat-memory 0.1.0__tar.gz

nonebot_plugin_group_chat_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TonyLiangP2010405
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonebot_plugin_group_chat_memory-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: nonebot-plugin-group-chat-memory
+Version: 0.1.0
+Summary: 为 NoneBot2 群聊提供共享长期记忆、点名对话和按群概率回复
+License-Expression: MIT
+License-File: LICENSE
+Keywords: nonebot,nonebot2,onebot,group,memory,embedding
+Author: TonyLiangP2010405
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiosqlite (>=0.19)
+Requires-Dist: httpx (>=0.27,<1.0)
+Requires-Dist: nonebot-adapter-onebot (>=2.4.0,<3.0.0)
+Requires-Dist: nonebot-plugin-localstore (>=0.7.0,<1.0.0)
+Requires-Dist: nonebot2 (>=2.2.0,<3.0.0)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: sqlite-vec (>=0.1.6,<0.2.0)
+Project-URL: Homepage, https://github.com/TonyLiangP2010405/nonebot-plugin-group-chat-memory
+Project-URL: Repository, https://github.com/TonyLiangP2010405/nonebot-plugin-group-chat-memory
+Description-Content-Type: text/markdown
+
+# nonebot-plugin-group-chat-memory
+
+为 NoneBot2 OneBot v11 群聊提供按群隔离的长期向量记忆、@/回复对话和按群概率随机回复。插件使用 SQLite + sqlite-vec 保存原文、分块、向量和群配置，聊天与 Embedding 均请求可配置的 OpenAI 兼容 HTTP API。
+
+## 环境与安装
+
+- Python 3.10+
+- NoneBot2 2.2+
+- OneBot v11 适配器与对应的 OneBot 协议端
+
+选择一种安装方式：
+
+```bash
+# nb-cli
+nb plugin install nonebot-plugin-group-chat-memory
+nb adapter install nonebot-adapter-onebot
+
+# pip
+pip install nonebot-plugin-group-chat-memory nonebot-adapter-onebot
+
+# Poetry
+poetry add nonebot-plugin-group-chat-memory nonebot-adapter-onebot
+```
+
+nb-cli 通常会写入插件配置。使用 pip 或 Poetry 手动安装后，确认项目的 `pyproject.toml` 已加载插件：
+
+```toml
+[tool.nonebot]
+plugins = ["nonebot_plugin_group_chat_memory"]
+```
+
+并在 NoneBot 启动代码中注册 OneBot v11 Adapter。仓库中的 `.env.example` 使用 `DRIVER=~fastapi`；该示例驱动不是本插件的运行时依赖，需要在你的 Bot 项目中另行安装：
+
+```bash
+pip install "nonebot2[fastapi]"
+# 或
+poetry add "nonebot2[fastapi]"
+```
+
+## 快速配置
+
+复制 `.env.example` 为 `.env` 并设置 SUPERUSER：
+
+```dotenv
+SUPERUSERS=["10001"]
+COMMAND_START=["/"]
+```
+
+启动 Bot 后，由 SUPERUSER 在**私聊**中依次设置四项运行时配置：
+
+```text
+/设置聊天地址 https://your-chat-provider.example/v1
+/设置聊天密钥 sk-your-chat-key
+/设置聊天模型 your-provider-model-id
+/设置向量密钥 sk-your-embedding-key
+```
+
+聊天地址填到 API 根路径（通常包含 `/v1`），插件分别请求其下的 `/chat/completions` 和 `/embeddings`。默认聊天模型标识是 `deepseek-v4.1-flash`，但**模型标识必须以实际服务商支持的值为准**。这四项保存到 SQLite，不再读取同名环境变量，更新后立即生效且重启后保留。使用 `/模型配置` 可查询脱敏状态。
+
+## 其余环境配置字段
+
+四个模型运行时字段不再通过 env 设置。其余以下字段可写在 NoneBot `.env` 中；集合类值使用 JSON 格式。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `GROUP_CHAT_MEMORY_CHAT_TIMEOUT` | `60` | 单次聊天 HTTP 请求超时秒数，必须大于 0。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_BASE_URL` | `https://api.siliconflow.cn/v1` | OpenAI 兼容 Embedding API 根地址。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_MODEL` | `BAAI/bge-m3` | Embedding 模型标识。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_DIMENSIONS` | `1024` | 向量维度，必须大于 0，必须与模型及既有数据库一致。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_TIMEOUT` | `10` | 后台分块 Embedding HTTP 请求超时秒数，必须大于 0。 |
+| `GROUP_CHAT_MEMORY_QUERY_TIMEOUT` | `3` | 回复前“查询向量 + 本地检索”的整体短超时秒数；超时后只用最近消息聊天。 |
+| `GROUP_CHAT_MEMORY_DB_PATH_OVERRIDE` | 空 | 数据库路径覆盖，支持 `~`；留空时使用 nonebot-plugin-localstore 的本插件数据目录下 `group_chat_memory.db`。 |
+| `GROUP_CHAT_MEMORY_RECENT_MESSAGES` | `20` | 每次回复最多读取的当前群最近消息数，至少为 1。 |
+| `GROUP_CHAT_MEMORY_CHUNK_SIZE` | `10` | 每个长期记忆片段包含的消息数，至少为 1。 |
+| `GROUP_CHAT_MEMORY_LONG_TERM_MEMORIES` | `5` | 每次回复最多检索的长期片段数；设为 0 可停用长期检索。 |
+| `GROUP_CHAT_MEMORY_CONTEXT_MAX_CHARS` | `6000` | 发送给聊天模型的上下文总字符预算，至少为 1；优先保留当前消息和最近消息。 |
+| `GROUP_CHAT_MEMORY_DEFAULT_PROBABILITY` | `0` | 新群随机回复概率，范围 0～100；已有群使用数据库中的概率。 |
+| `GROUP_CHAT_MEMORY_IGNORED_QQ` | `[]` | 完全忽略的 QQ 号 JSON 数组，例如 `[12345, 67890]`；这些账号的消息不记忆也不触发回复。 |
+| `GROUP_CHAT_MEMORY_SYSTEM_PROMPT` | `你是一个群聊助手。回答自然、简洁，像群友一样交流。只使用提供的聊天记录和长期记忆，不要假装记得没有出现过的内容。` | 自定义系统提示词；设为空时仅使用内置的发言者区分和当前消息约束。 |
+
+更改 `GROUP_CHAT_MEMORY_EMBEDDING_DIMENSIONS` 不会迁移既有向量。如果与数据库首次创建时记录的维度不同，插件会拒绝打开该数据库；请恢复原配置，或备份后另行重建数据库。
+
+## 使用与权限
+
+在群里 @Bot 或回复 Bot 的消息即可对话；这两种定向消息必定进入回复队列，不受随机概率影响。普通纯文本按当前群概率触发，默认 0% 表示关闭随机回复，100% 表示每条符合条件的普通文本都回复。
+
+| 命令 | 权限 | 行为 |
+|---|---|---|
+| `/设置聊天地址 <URL>` | 仅私聊 SUPERUSER | 设置全局 OpenAI 兼容聊天 API 根地址。 |
+| `/设置聊天密钥 <密钥>` | 仅私聊 SUPERUSER | 设置全局聊天 API 密钥。 |
+| `/设置聊天模型 <模型标识>` | 仅私聊 SUPERUSER | 设置全局聊天模型。 |
+| `/设置向量密钥 <密钥>` | 仅私聊 SUPERUSER | 设置全局 Embedding API 密钥。 |
+| `/模型配置` | SUPERUSER，私聊或群聊 | 查询全局配置状态，密钥只显示掩码。 |
+| `/回复概率` | 仅 SUPERUSER | 查询当前群概率，显示一位小数。 |
+| `/回复概率 <0～100>` | 仅 SUPERUSER | 设置当前群概率，最多一位小数，例如 `/回复概率 5.5`。 |
+| `/清空群记忆` | 仅 SUPERUSER | 删除当前群原始消息、分块和向量；保留当前群概率，不影响其他群。 |
+
+非 SUPERUSER 会收到简短权限提示。命令不进入记忆，也不触发随机回复。SUPERUSER 通过 NoneBot 的 `SUPERUSERS` 配置，而不是群管理员身份确定。
+
+同一群的模型请求串行执行：定向请求逐条排队；等待中的随机请求只保留最新一条，避免集中补发。不同群可以并行处理。
+
+## 记忆范围与隐私
+
+**这是全群文本记忆，不只是与 Bot 的对话。** 符合条件的群成员纯文本、定向文本以及 Bot 成功发送的模型回复都会保存；其他机器人账号也会保存，除非列入 `GROUP_CHAT_MEMORY_IGNORED_QQ`。命令、私聊、临时会话、匿名消息、Bot 自身消息、纯非文本及含不支持消息段的内容不会进入记忆。
+
+每积累 10 条消息（可由 `GROUP_CHAT_MEMORY_CHUNK_SIZE` 修改）形成的完整群聊片段会发送给配置的**第三方 Embedding 服务商**；每次回复前的当前查询文本也会发送给 Embedding 服务商。回复时，当前群最近消息、检索到的长期片段和当前输入会发送给聊天模型服务商。不同群的记忆和检索在数据库层面隔离，但同一群的成员内容可能进入该群后续模型上下文。
+
+原文、向量与命令设置的 API 密钥保存在本地 SQLite 文件中，数据库本身不加密。请保护好数据库与备份，并限制文件访问权限。虽然设置密钥只允许私聊 SUPERUSER，但命令内容仍可能保留在你和 OneBot 协议端的聊天记录或日志中；不要把密钥发到群里，泄露后请立即更换。请根据群成员授权、服务商数据政策和适用法律决定是否启用。
+
+## 缺失凭据与故障降级
+
+- 零配置导入插件和 `nonebot.load_plugin("nonebot_plugin_group_chat_memory")` 均可成功，不要求先填写 API 密钥。
+- 聊天地址、密钥或模型为空时，收到定向/随机触发后只发送通用错误提示；传入消息仍会保存，不会把密钥或内部响应发到群里。
+- Embedding 密钥缺失或后台向量化失败时，原始消息仍保留，未完成片段等待后续重试或重启恢复，但暂时不能用于长期检索。
+- 查询 Embedding 超时或失败时，回复会降级为最近消息上下文，不阻断聊天。
+- 数据库向量维度不匹配属于配置/数据错误，应先按备份说明处理，而不是直接删除生产数据。
+
+## 随机回复风险
+
+随机回复可能接错话题、打扰群友、放大敏感内容传播，并产生额外模型费用和限流压力；100% 会对每条符合条件的普通文本调用模型。“等待中只保留最新随机请求”只能减少积压，不能限制每条新消息继续触发。建议保持默认 0%，先在测试群验证，再从较低概率开始，并用忽略列表排除已知机器人。
+
+## 数据库备份
+
+默认数据库位于 nonebot-plugin-localstore 为本插件分配的数据目录，文件名为 `group_chat_memory.db`；配置 `GROUP_CHAT_MEMORY_DB_PATH_OVERRIDE` 时使用该路径。插件启用了 WAL，运行中可能出现同名 `-wal` 和 `-shm` 文件。
+
+运行中备份推荐使用 SQLite CLI 的在线备份命令，它会正确处理 WAL：
+
+```bash
+sqlite3 /path/to/group_chat_memory.db ".backup '/path/to/group_chat_memory.backup.db'"
+```
+
+也可以先正常停止 Bot，再复制数据库文件及存在的 `-wal`、`-shm` 文件。**不要在运行中只复制主 `.db` 文件**，否则可能得到不完整备份。恢复后必须使用与原数据库相同的 Embedding 维度配置。
+
+## 开发验证
+
+```bash
+poetry install
+poetry run pytest -v
+poetry run ruff check .
+poetry run python -m compileall nonebot_plugin_group_chat_memory
+poetry build
+```
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。
+

nonebot_plugin_group_chat_memory-0.1.0/README.md

@@ -0,0 +1,146 @@
+# nonebot-plugin-group-chat-memory
+
+为 NoneBot2 OneBot v11 群聊提供按群隔离的长期向量记忆、@/回复对话和按群概率随机回复。插件使用 SQLite + sqlite-vec 保存原文、分块、向量和群配置，聊天与 Embedding 均请求可配置的 OpenAI 兼容 HTTP API。
+
+## 环境与安装
+
+- Python 3.10+
+- NoneBot2 2.2+
+- OneBot v11 适配器与对应的 OneBot 协议端
+
+选择一种安装方式：
+
+```bash
+# nb-cli
+nb plugin install nonebot-plugin-group-chat-memory
+nb adapter install nonebot-adapter-onebot
+
+# pip
+pip install nonebot-plugin-group-chat-memory nonebot-adapter-onebot
+
+# Poetry
+poetry add nonebot-plugin-group-chat-memory nonebot-adapter-onebot
+```
+
+nb-cli 通常会写入插件配置。使用 pip 或 Poetry 手动安装后，确认项目的 `pyproject.toml` 已加载插件：
+
+```toml
+[tool.nonebot]
+plugins = ["nonebot_plugin_group_chat_memory"]
+```
+
+并在 NoneBot 启动代码中注册 OneBot v11 Adapter。仓库中的 `.env.example` 使用 `DRIVER=~fastapi`；该示例驱动不是本插件的运行时依赖，需要在你的 Bot 项目中另行安装：
+
+```bash
+pip install "nonebot2[fastapi]"
+# 或
+poetry add "nonebot2[fastapi]"
+```
+
+## 快速配置
+
+复制 `.env.example` 为 `.env` 并设置 SUPERUSER：
+
+```dotenv
+SUPERUSERS=["10001"]
+COMMAND_START=["/"]
+```
+
+启动 Bot 后，由 SUPERUSER 在**私聊**中依次设置四项运行时配置：
+
+```text
+/设置聊天地址 https://your-chat-provider.example/v1
+/设置聊天密钥 sk-your-chat-key
+/设置聊天模型 your-provider-model-id
+/设置向量密钥 sk-your-embedding-key
+```
+
+聊天地址填到 API 根路径（通常包含 `/v1`），插件分别请求其下的 `/chat/completions` 和 `/embeddings`。默认聊天模型标识是 `deepseek-v4.1-flash`，但**模型标识必须以实际服务商支持的值为准**。这四项保存到 SQLite，不再读取同名环境变量，更新后立即生效且重启后保留。使用 `/模型配置` 可查询脱敏状态。
+
+## 其余环境配置字段
+
+四个模型运行时字段不再通过 env 设置。其余以下字段可写在 NoneBot `.env` 中；集合类值使用 JSON 格式。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `GROUP_CHAT_MEMORY_CHAT_TIMEOUT` | `60` | 单次聊天 HTTP 请求超时秒数，必须大于 0。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_BASE_URL` | `https://api.siliconflow.cn/v1` | OpenAI 兼容 Embedding API 根地址。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_MODEL` | `BAAI/bge-m3` | Embedding 模型标识。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_DIMENSIONS` | `1024` | 向量维度，必须大于 0，必须与模型及既有数据库一致。 |
+| `GROUP_CHAT_MEMORY_EMBEDDING_TIMEOUT` | `10` | 后台分块 Embedding HTTP 请求超时秒数，必须大于 0。 |
+| `GROUP_CHAT_MEMORY_QUERY_TIMEOUT` | `3` | 回复前“查询向量 + 本地检索”的整体短超时秒数；超时后只用最近消息聊天。 |
+| `GROUP_CHAT_MEMORY_DB_PATH_OVERRIDE` | 空 | 数据库路径覆盖，支持 `~`；留空时使用 nonebot-plugin-localstore 的本插件数据目录下 `group_chat_memory.db`。 |
+| `GROUP_CHAT_MEMORY_RECENT_MESSAGES` | `20` | 每次回复最多读取的当前群最近消息数，至少为 1。 |
+| `GROUP_CHAT_MEMORY_CHUNK_SIZE` | `10` | 每个长期记忆片段包含的消息数，至少为 1。 |
+| `GROUP_CHAT_MEMORY_LONG_TERM_MEMORIES` | `5` | 每次回复最多检索的长期片段数；设为 0 可停用长期检索。 |
+| `GROUP_CHAT_MEMORY_CONTEXT_MAX_CHARS` | `6000` | 发送给聊天模型的上下文总字符预算，至少为 1；优先保留当前消息和最近消息。 |
+| `GROUP_CHAT_MEMORY_DEFAULT_PROBABILITY` | `0` | 新群随机回复概率，范围 0～100；已有群使用数据库中的概率。 |
+| `GROUP_CHAT_MEMORY_IGNORED_QQ` | `[]` | 完全忽略的 QQ 号 JSON 数组，例如 `[12345, 67890]`；这些账号的消息不记忆也不触发回复。 |
+| `GROUP_CHAT_MEMORY_SYSTEM_PROMPT` | `你是一个群聊助手。回答自然、简洁，像群友一样交流。只使用提供的聊天记录和长期记忆，不要假装记得没有出现过的内容。` | 自定义系统提示词；设为空时仅使用内置的发言者区分和当前消息约束。 |
+
+更改 `GROUP_CHAT_MEMORY_EMBEDDING_DIMENSIONS` 不会迁移既有向量。如果与数据库首次创建时记录的维度不同，插件会拒绝打开该数据库；请恢复原配置，或备份后另行重建数据库。
+
+## 使用与权限
+
+在群里 @Bot 或回复 Bot 的消息即可对话；这两种定向消息必定进入回复队列，不受随机概率影响。普通纯文本按当前群概率触发，默认 0% 表示关闭随机回复，100% 表示每条符合条件的普通文本都回复。
+
+| 命令 | 权限 | 行为 |
+|---|---|---|
+| `/设置聊天地址 <URL>` | 仅私聊 SUPERUSER | 设置全局 OpenAI 兼容聊天 API 根地址。 |
+| `/设置聊天密钥 <密钥>` | 仅私聊 SUPERUSER | 设置全局聊天 API 密钥。 |
+| `/设置聊天模型 <模型标识>` | 仅私聊 SUPERUSER | 设置全局聊天模型。 |
+| `/设置向量密钥 <密钥>` | 仅私聊 SUPERUSER | 设置全局 Embedding API 密钥。 |
+| `/模型配置` | SUPERUSER，私聊或群聊 | 查询全局配置状态，密钥只显示掩码。 |
+| `/回复概率` | 仅 SUPERUSER | 查询当前群概率，显示一位小数。 |
+| `/回复概率 <0～100>` | 仅 SUPERUSER | 设置当前群概率，最多一位小数，例如 `/回复概率 5.5`。 |
+| `/清空群记忆` | 仅 SUPERUSER | 删除当前群原始消息、分块和向量；保留当前群概率，不影响其他群。 |
+
+非 SUPERUSER 会收到简短权限提示。命令不进入记忆，也不触发随机回复。SUPERUSER 通过 NoneBot 的 `SUPERUSERS` 配置，而不是群管理员身份确定。
+
+同一群的模型请求串行执行：定向请求逐条排队；等待中的随机请求只保留最新一条，避免集中补发。不同群可以并行处理。
+
+## 记忆范围与隐私
+
+**这是全群文本记忆，不只是与 Bot 的对话。** 符合条件的群成员纯文本、定向文本以及 Bot 成功发送的模型回复都会保存；其他机器人账号也会保存，除非列入 `GROUP_CHAT_MEMORY_IGNORED_QQ`。命令、私聊、临时会话、匿名消息、Bot 自身消息、纯非文本及含不支持消息段的内容不会进入记忆。
+
+每积累 10 条消息（可由 `GROUP_CHAT_MEMORY_CHUNK_SIZE` 修改）形成的完整群聊片段会发送给配置的**第三方 Embedding 服务商**；每次回复前的当前查询文本也会发送给 Embedding 服务商。回复时，当前群最近消息、检索到的长期片段和当前输入会发送给聊天模型服务商。不同群的记忆和检索在数据库层面隔离，但同一群的成员内容可能进入该群后续模型上下文。
+
+原文、向量与命令设置的 API 密钥保存在本地 SQLite 文件中，数据库本身不加密。请保护好数据库与备份，并限制文件访问权限。虽然设置密钥只允许私聊 SUPERUSER，但命令内容仍可能保留在你和 OneBot 协议端的聊天记录或日志中；不要把密钥发到群里，泄露后请立即更换。请根据群成员授权、服务商数据政策和适用法律决定是否启用。
+
+## 缺失凭据与故障降级
+
+- 零配置导入插件和 `nonebot.load_plugin("nonebot_plugin_group_chat_memory")` 均可成功，不要求先填写 API 密钥。
+- 聊天地址、密钥或模型为空时，收到定向/随机触发后只发送通用错误提示；传入消息仍会保存，不会把密钥或内部响应发到群里。
+- Embedding 密钥缺失或后台向量化失败时，原始消息仍保留，未完成片段等待后续重试或重启恢复，但暂时不能用于长期检索。
+- 查询 Embedding 超时或失败时，回复会降级为最近消息上下文，不阻断聊天。
+- 数据库向量维度不匹配属于配置/数据错误，应先按备份说明处理，而不是直接删除生产数据。
+
+## 随机回复风险
+
+随机回复可能接错话题、打扰群友、放大敏感内容传播，并产生额外模型费用和限流压力；100% 会对每条符合条件的普通文本调用模型。“等待中只保留最新随机请求”只能减少积压，不能限制每条新消息继续触发。建议保持默认 0%，先在测试群验证，再从较低概率开始，并用忽略列表排除已知机器人。
+
+## 数据库备份
+
+默认数据库位于 nonebot-plugin-localstore 为本插件分配的数据目录，文件名为 `group_chat_memory.db`；配置 `GROUP_CHAT_MEMORY_DB_PATH_OVERRIDE` 时使用该路径。插件启用了 WAL，运行中可能出现同名 `-wal` 和 `-shm` 文件。
+
+运行中备份推荐使用 SQLite CLI 的在线备份命令，它会正确处理 WAL：
+
+```bash
+sqlite3 /path/to/group_chat_memory.db ".backup '/path/to/group_chat_memory.backup.db'"
+```
+
+也可以先正常停止 Bot，再复制数据库文件及存在的 `-wal`、`-shm` 文件。**不要在运行中只复制主 `.db` 文件**，否则可能得到不完整备份。恢复后必须使用与原数据库相同的 Embedding 维度配置。
+
+## 开发验证
+
+```bash
+poetry install
+poetry run pytest -v
+poetry run ruff check .
+poetry run python -m compileall nonebot_plugin_group_chat_memory
+poetry build
+```
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

nonebot_plugin_group_chat_memory-0.1.0/nonebot_plugin_group_chat_memory/__init__.py

@@ -0,0 +1,26 @@
+from nonebot import get_driver, require
+from nonebot.plugin import PluginMetadata
+
+from .config import Config
+
+__plugin_meta__ = PluginMetadata(
+    name="群聊记忆",
+    description="为群聊提供共享长期记忆、点名对话和按群概率回复",
+    usage=(
+        "在群聊中 @机器人 或回复机器人的消息即可对话。\n"
+        "SUPERUSER：/回复概率 [0~100] 查询或设置当前群随机回复概率；"
+        "/清空群记忆 清除当前群聊天记录与长期记忆。"
+    ),
+    type="application",
+    homepage="https://github.com/TonyLiangP2010405/nonebot-plugin-group-chat-memory",
+    config=Config,
+    supported_adapters={"~onebot.v11"},
+)
+
+try:
+    get_driver()
+except ValueError:
+    pass  # 允许在 NoneBot 初始化前单独导入模块
+else:
+    require("nonebot_plugin_localstore")
+    from . import handlers as handlers

nonebot_plugin_group_chat_memory-0.1.0/nonebot_plugin_group_chat_memory/api.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import asyncio
+import math
+from typing import Any
+
+import httpx
+
+from .config import Config
+from .context import build_chat_messages
+from .models import ChatContext
+
+CHAT_RETRY_DELAYS: tuple[float, ...] = (0.5, 1.0)
+
+
+class ModelAPIError(RuntimeError):
+    """模型 API 调用失败；异常消息只包含状态或原因，不含密钥与响应正文。"""
+
+
+class EmbeddingAPIError(ModelAPIError):
+    """Embedding 请求失败或响应不可用。"""
+
+
+class ChatAPIError(ModelAPIError):
+    """聊天请求失败或响应不可用。"""
+
+    def __init__(self, message: str, *, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+
+
+def _make_client(timeout: float) -> httpx.AsyncClient:
+    """为单次请求创建客户端，使聊天与 Embedding 各自使用独立超时。"""
+    return httpx.AsyncClient(timeout=timeout)
+
+
+def _endpoint(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/{path}"
+
+
+def _auth_headers(api_key: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {api_key.strip()}"}
+
+
+class EmbeddingClient:
+    """OpenAI 兼容 `/embeddings` 客户端，用于批量向量化。"""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        """批量向量化 texts，返回与输入顺序一致的向量；失败时抛出 EmbeddingAPIError。"""
+        if not texts:
+            return []
+        self._config.require_embedding_config()
+        payload = {"model": self._config.group_chat_memory_embedding_model, "input": list(texts)}
+        response = await self._post(payload)
+        return self._parse(response, len(texts))
+
+    async def _post(self, payload: dict[str, Any]) -> httpx.Response:
+        url = _endpoint(self._config.group_chat_memory_embedding_base_url, "embeddings")
+        headers = _auth_headers(self._config.group_chat_memory_embedding_api_key.get_secret_value())
+        timeout = self._config.group_chat_memory_embedding_timeout
+        try:
+            async with _make_client(timeout) as client:
+                response = await client.post(url, json=payload, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise EmbeddingAPIError("Embedding 请求超时。") from exc
+        except httpx.HTTPError as exc:
+            raise EmbeddingAPIError("Embedding 请求失败，无法连接服务。") from exc
+        if not 200 <= response.status_code < 300:
+            raise EmbeddingAPIError(f"Embedding 服务返回 HTTP {response.status_code}。")
+        return response
+
+    def _parse(self, response: httpx.Response, expected: int) -> list[list[float]]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise EmbeddingAPIError("Embedding 响应不是合法 JSON。") from exc
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if not isinstance(data, list) or not data:
+            raise EmbeddingAPIError("Embedding 响应缺少向量数据。")
+        if len(data) != expected:
+            raise EmbeddingAPIError(
+                f"Embedding 响应返回 {len(data)} 条向量，与请求的 {expected} 条不一致。"
+            )
+
+        ordered = sorted(
+            enumerate(data),
+            key=lambda item: _index_of(item[1], item[0]),
+        )
+        dimensions = self._config.group_chat_memory_embedding_dimensions
+        return [_parse_vector(item, dimensions) for _, item in ordered]
+
+
+class ChatClient:
+    """OpenAI 兼容 `/chat/completions` 客户端，带有限重试。"""
+
+    def __init__(
+        self,
+        config: Config,
+        *,
+        retry_delays: tuple[float, ...] = CHAT_RETRY_DELAYS,
+    ) -> None:
+        self._config = config
+        self._retry_delays = tuple(retry_delays)
+
+    async def complete(self, context: ChatContext, current_text: str) -> str:
+        """按上下文请求一条回复；瞬时失败按配置次数重试，最终失败抛出 ChatAPIError。"""
+        self._config.require_chat_config()
+        if not current_text.strip():
+            raise ChatAPIError("当前消息为空，无法请求聊天模型。")
+        payload = {
+            "model": self._config.group_chat_memory_chat_model,
+            "messages": build_chat_messages(self._config, context, current_text),
+        }
+
+        attempts = len(self._retry_delays) + 1
+        for attempt in range(attempts):
+            try:
+                response = await self._post(payload)
+            except ChatAPIError as exc:
+                if not exc.retryable or attempt + 1 >= attempts:
+                    raise
+                await asyncio.sleep(self._retry_delays[attempt])
+                continue
+            return self._parse(response)
+        raise ChatAPIError("聊天请求重试次数已用尽。")
+
+    async def _post(self, payload: dict[str, Any]) -> httpx.Response:
+        url = _endpoint(self._config.group_chat_memory_chat_base_url, "chat/completions")
+        headers = _auth_headers(self._config.group_chat_memory_chat_api_key.get_secret_value())
+        timeout = self._config.group_chat_memory_chat_timeout
+        try:
+            async with _make_client(timeout) as client:
+                response = await client.post(url, json=payload, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise ChatAPIError("聊天请求超时。", retryable=True) from exc
+        except httpx.HTTPError as exc:
+            raise ChatAPIError("聊天请求失败，无法连接服务。", retryable=True) from exc
+        if not 200 <= response.status_code < 300:
+            raise ChatAPIError(
+                f"聊天服务返回 HTTP {response.status_code}。",
+                retryable=response.status_code == 429 or response.status_code >= 500,
+            )
+        return response
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> str:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ChatAPIError("聊天响应不是合法 JSON。") from exc
+        choices = payload.get("choices") if isinstance(payload, dict) else None
+        if not isinstance(choices, list) or not choices:
+            raise ChatAPIError("聊天响应缺少 choices。")
+        message = choices[0].get("message") if isinstance(choices[0], dict) else None
+        content = message.get("content") if isinstance(message, dict) else None
+        if not isinstance(content, str) or not content.strip():
+            raise ChatAPIError("聊天响应缺少回复内容。")
+        return content.strip()
+
+
+def _index_of(item: Any, fallback: int) -> int:
+    index = item.get("index") if isinstance(item, dict) else None
+    if isinstance(index, int) and not isinstance(index, bool):
+        return index
+    return fallback
+
+
+def _parse_vector(item: Any, dimensions: int) -> list[float]:
+    vector = item.get("embedding") if isinstance(item, dict) else None
+    if not isinstance(vector, list):
+        raise EmbeddingAPIError("Embedding 响应缺少向量。")
+    if len(vector) != dimensions:
+        raise EmbeddingAPIError(f"Embedding 向量维度为 {len(vector)}，配置要求 {dimensions}。")
+    values: list[float] = []
+    for value in vector:
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            raise EmbeddingAPIError("Embedding 向量包含非数值。")
+        number = float(value)
+        if not math.isfinite(number):
+            raise EmbeddingAPIError("Embedding 向量包含非有限数值。")
+        values.append(number)
+    return values

nonebot_plugin_group_chat_memory-0.1.0/nonebot_plugin_group_chat_memory/config.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from nonebot import get_plugin_config
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+DEFAULT_DB_FILENAME = "group_chat_memory.db"
+
+DEFAULT_SYSTEM_PROMPT = (
+    "你是一个群聊助手。回答自然、简洁，像群友一样交流。"
+    "只使用提供的聊天记录和长期记忆，不要假装记得没有出现过的内容。"
+)
+
+RUNTIME_CONFIG_DEFAULTS = {
+    "chat_base_url": "",
+    "chat_api_key": "",
+    "chat_model": "deepseek-v4.1-flash",
+    "embedding_api_key": "",
+}
+
+
+class ConfigError(RuntimeError):
+    """功能所需的配置缺失时抛出。"""
+
+
+def _localstore_data_dir() -> Path:
+    from nonebot_plugin_localstore import get_plugin_data_dir
+
+    return get_plugin_data_dir()
+
+
+class Config(BaseModel):
+    """群聊记忆插件配置；四个模型运行时字段由私聊命令和数据库覆盖。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    group_chat_memory_chat_base_url: str = ""
+    group_chat_memory_chat_api_key: SecretStr = SecretStr("")
+    group_chat_memory_chat_model: str = "deepseek-v4.1-flash"
+    group_chat_memory_chat_timeout: float = Field(default=60.0, gt=0)
+
+    group_chat_memory_embedding_base_url: str = "https://api.siliconflow.cn/v1"
+    group_chat_memory_embedding_api_key: SecretStr = SecretStr("")
+    group_chat_memory_embedding_model: str = "BAAI/bge-m3"
+    group_chat_memory_embedding_dimensions: int = Field(default=1024, gt=0)
+    group_chat_memory_embedding_timeout: float = Field(default=10.0, gt=0)
+    group_chat_memory_query_timeout: float = Field(default=3.0, gt=0)
+
+    group_chat_memory_db_path_override: str | None = None
+
+    group_chat_memory_recent_messages: int = Field(default=20, ge=1)
+    group_chat_memory_chunk_size: int = Field(default=10, ge=1)
+    group_chat_memory_long_term_memories: int = Field(default=5, ge=0)
+    group_chat_memory_context_max_chars: int = Field(default=6000, ge=1)
+    group_chat_memory_default_probability: float = Field(default=0.0, ge=0.0, le=100.0)
+    group_chat_memory_ignored_qq: set[int] = Field(default_factory=set)
+    group_chat_memory_system_prompt: str = DEFAULT_SYSTEM_PROMPT
+
+    @property
+    def database_path(self) -> Path:
+        """数据库文件路径；未配置时使用 localstore 的插件数据目录。"""
+        configured = (self.group_chat_memory_db_path_override or "").strip()
+        if configured:
+            return Path(configured).expanduser()
+        return _localstore_data_dir() / DEFAULT_DB_FILENAME
+
+    def apply_runtime_config(self, values: dict[str, str]) -> None:
+        """应用数据库中的四项全局配置，未保存的字段恢复内置默认值。"""
+        for key, default in RUNTIME_CONFIG_DEFAULTS.items():
+            value = values.get(key, default)
+            if key == "chat_base_url":
+                self.group_chat_memory_chat_base_url = value
+            elif key == "chat_api_key":
+                self.group_chat_memory_chat_api_key = SecretStr(value)
+            elif key == "chat_model":
+                self.group_chat_memory_chat_model = value
+            elif key == "embedding_api_key":
+                self.group_chat_memory_embedding_api_key = SecretStr(value)
+
+    def require_chat_config(self) -> None:
+        """检查聊天模型配置，仅在真正调用聊天功能时使用。"""
+        missing = self._missing(
+            ("GROUP_CHAT_MEMORY_CHAT_BASE_URL", self.group_chat_memory_chat_base_url),
+            (
+                "GROUP_CHAT_MEMORY_CHAT_API_KEY",
+                self.group_chat_memory_chat_api_key.get_secret_value(),
+            ),
+            ("GROUP_CHAT_MEMORY_CHAT_MODEL", self.group_chat_memory_chat_model),
+        )
+        if missing:
+            raise ConfigError(f"聊天模型未配置，请设置：{'、'.join(missing)}")
+
+    def require_embedding_config(self) -> None:
+        """检查 Embedding 配置，仅在真正调用向量化功能时使用。"""
+        missing = self._missing(
+            (
+                "GROUP_CHAT_MEMORY_EMBEDDING_BASE_URL",
+                self.group_chat_memory_embedding_base_url,
+            ),
+            (
+                "GROUP_CHAT_MEMORY_EMBEDDING_API_KEY",
+                self.group_chat_memory_embedding_api_key.get_secret_value(),
+            ),
+            ("GROUP_CHAT_MEMORY_EMBEDDING_MODEL", self.group_chat_memory_embedding_model),
+        )
+        if missing:
+            raise ConfigError(f"Embedding 未配置，请设置：{'、'.join(missing)}")
+
+    @staticmethod
+    def _missing(*items: tuple[str, str]) -> list[str]:
+        return [name for name, value in items if not value.strip()]
+
+
+def get_settings() -> Config:
+    """从 NoneBot 全局配置读取本插件配置。"""
+    return get_plugin_config(Config)