QQ 邮件登记机器人插件
一个基于 NoneBot2 + OneBot v11 的 QQ 机器人文件夹插件,用于管理“寄信 / 查件 / 签收 / 联系人表 / 邮件记录表”,并将数据同步到 Notion。
版本:见pyproject.toml.project.version
本版本相比0.7.6增加群白名单功能。相比0.7.7:使用现代化插件配置。 相比0.7.10:寄信/智能寄信增加取消和多次错误自动取消。
安装
nb plugin install nonebot-plugin-mail
或
pip install nonebot-plugin-mail
然后在项目里加载此插件
功能
/mail contacts:查看联系人表图片/mail records:查看最新邮件记录图片/mail @某人:查看联系人信息/mail 修改 字段 内容:修改自己的联系人信息,支持电话、电子邮箱、地址、邮编、QQ 等字段/mail 我的寄件:查看自己最近寄出的邮件记录/mail 删除 编号 确认删除:删除自己最近寄件列表中的记录- /
寄信/寄件/寄出:进入人工寄件登记流程 - /
查询/查件:查询最近 7 天内是否有人给自己寄信 - /
签收/收件:查询并签收未签收邮件 - /
识别信件/智能寄信/信件识别/识别邮件:群聊发送信封图片,使用视觉 AI 识别后人工确认写入 Notion
联系人信息修改与寄件记录删除
普通用户默认操作自己:
/mail 修改 地址1 新地址
/mail 修改 电话 13800000000
/mail 修改 邮编1 510000
/mail 我的寄件
/mail 删除 1 确认删除
superuser 可以指定他人:
/mail 修改 @某人 地址1 新地址
/mail 修改 页面ID 地址1 新地址
/mail 我的寄件 @某人
/mail 删除 @某人 1 确认删除
/mail 删除 Notion页面ID 确认删除
可修改字段:电话、电子邮箱、地址1、邮编1、地址2、邮编2、QQ。删除寄件记录时,普通用户只能删除自己寄出的记录;Notion API 中的删除会以归档页面实现。
智能识别流程
- 群内发送
/识别信件。 - 按提示发送一张或多张信封图片。
- 插件下载图片并尝试压缩到最长边 2200px、JPEG 质量 0.92。
- 视觉 AI 识别寄件人、收件人、寄出日期、邮件类型和参考备注。
- 后端规则校验联系人 ID、日期、邮件类型、澳门收件人规则,并做电话、QQ、姓名、别名、地址兜底匹配。
- 群内返回识别结果预览。
- 回复
确认后写入 Notion。
如需修改识别结果,可在确认前回复类似:
收件人 @某人
寄件人 @某人
日期2026-06-09
类型挂号信
编号XA123456789
配置
在 NoneBot 2 环境配置 .env 或 .env.dev 中设置:
示例
NOTION_TOKEN=
RAS_DATA_SOURCE_ID=31e70d82-c716-80ba-b4d2-000b1892f62c
CONTACT_DATA_SOURCE_ID=31e70d82-c716-8034-b23d-000ba20878af
AI_BASE_URL=https://api.exesim.com/v1
AI_API_KEY=
AI_MODEL=Qwen3.6-Plus
MAIL_IMAGE_MAX_COUNT=12
Notion 相关
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
NOTION_TOKEN |
否,但不建议 | 无 | Notion API 访问令牌,用于读取联系人表、写入邮件记录、签收邮件记录。 |
RAS_DATA_SOURCE_ID |
否,但不建议 | 31e70d82-c716-80ba-b4d2-000b1892f62c |
邮件记录表的数据源 ID,用于查询邮件记录。 |
CONTACT_DATA_SOURCE_ID |
否,但不建议 | 31e70d82-c716-8034-b23d-000ba20878af |
联系人表的数据源 ID,用于读取联系人信息。 |
AI 相关
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
AI_BASE_URL |
否 | https://api.openai.com/v1 |
兼容 OpenAI 接口的视觉模型地址。 |
AI_API_KEY |
否 | 无 | 视觉识别接口的访问密钥。 |
AI_MODEL |
否 | Qwen3.6-Plus |
识别信封图片时使用的模型名称。 |
MAIL_IMAGE_MAX_COUNT |
否 | 12 |
单次允许上传并识别的最大图片数量。 |
其他
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
mail_group_whitelist(list[int]) |
否 | [] | /mail命令的群白名单列表,空或不配置表示白名单不生效,有值表示只在这些群生效 |
说明
AI_BASE_URL可不填,不填时默认使用https://api.openai.com/v1MAIL_IMAGE_MAX_COUNT可不填,不填时默认12NOTION_TOKEN不填时,联系人表会尝试使用本地 fallback,但邮件查询、签收和提交 Notion 仍会受限,基本必须
notion侧配置
- 创建的表应当至少包括 联系人表、邮件记录表
- 联系人表应当至少包含如下列:姓名 / 昵称,电话,邮编 1, 地址 1, 邮编 2, 地址 2, QQ
- 其中QQ可以用英文逗号分隔多个
- 邮件记录表需要包括:消息来源,签收,收件人,寄出日期,邮件编号,寄件人,备注
参考:
目录
nonebot_plugin_mail/
__init__.py # 插件入口:PluginMetadata、注册所有 handlers
config.py # 配置:Notion、AI_BASE_URL、AI_API_KEY、AI_MODEL、数据库 ID
models.py # Contact、RecognizeResult、MailRecordDraft 等数据结构
constants.py # 邮件类型、字段名、默认值、正则、澳门规则常量
services/
notion.py # Notion 联系人读取、邮件记录写入/查询/签收
contacts.py # 联系人缓存、fallback 合并、QQ 映射、联系人公开字段
recognizer.py # 视觉 AI 调用、prompt 构造、AI JSON 解析
matcher.py # 联系人匹配:电话、QQ、姓名/别名、地址片段评分
rules.py # AI 结果归一化:日期、邮件类型、条码、澳门收件人、错误项
images.py # 群聊图片下载、压缩/转 base64、图片临时保存
render.py # 联系人表、邮件记录、识别结果预览转图片/文本
handlers/
mail.py # /mail contacts、/mail records、/mail @某人
send.py # “寄信/寄件/寄出”人工登记流程
query.py # “查询/查件”
receive.py # “签收/收件”
recognize.py # 识别信件/智能寄信/信件识别/识别邮件 发送信件图片触发智能识别、人工确认、提交 Notion
data/
fallback_contacts.py # notion不可用时的临时contacts
示例
/mail @某人
/寄件
/查件
/签收
/信件识别
Metadata
Release files for nonebot-plugin-mail 0.7.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nonebot_plugin_mail-0.7.15.tar.gz | 47.0 kB | Without provenance | Details for nonebot_plugin_mail-0.7.15.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nonebot_plugin_mail-0.7.15-py3-none-any.whl | Python 3 | none | any | Details for nonebot_plugin_mail-0.7.15-py3-none-any.whl |
Total release size: 100.7 kB
Release files / nonebot_plugin_mail-0.7.15.tar.gz
| Download URL | nonebot_plugin_mail-0.7.15.tar.gz |
|---|---|
| Size | 47.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e35504a8cd805f039b46a41ef4a9168ef23bc0249ca1f8e77aaaffc5bfcb70e
|
|
BLAKE2b-256 checksum How to use checksums |
9ff41788aaca4bc33a6aab2a981fb492da63c767fcc17b8b15c7fa44ada07415
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Release files / nonebot_plugin_mail-0.7.15-py3-none-any.whl
| Download URL | nonebot_plugin_mail-0.7.15-py3-none-any.whl |
|---|---|
| Size | 53.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e77ba4e5d544970764b31d60d1e53420c7942e054a406989f8c43b5b2d781d8
|
|
BLAKE2b-256 checksum How to use checksums |
273c1c1b6655186ee118d6318f5630aa22d7c15007d1901f7d99d85cd3705f09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Security for nonebot-plugin-mail 0.7.15
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.