Local Quotes System (LQS) - 语录系统使用手册
1. 系统简介
LQS 是一个基于 Nonebot2 (OneBot V11) 的本地化语录管理插件。
该系统旨在提供一个轻量级、高互动性的群内语录存储库。采用本地 JSON 数据库，支持多人协作录入、热度追踪以及基于表情回应（Emoji Reaction）的互动评分机制。
核心特性：
- 本地存储：数据完全私有化，无外部 API 依赖。
- 互动热度：监听群友对语录消息的表情回应，自动增加热度。
- 智能 ID：支持 ID 回收与自增管理。
- CLI 风格：指令设计遵循 Linux 命令行参数风格，简洁高效。
2. 用户指令指南 (User Guide)
所有指令统一前缀为 /t。
基础操作
| 指令格式 | 功能描述 | 示例 |
|---|---|---|
| /t | 随机抽取：只显示文本内容，无干扰信息。 | /t |
| /t -s [内容] | 录入语录：将内容写入数据库，自动分配 ID。可简写为/t s | /t -s 这里的空气真香甜 |
| /t -i | 详细随机：抽取一条语录，并显示 ID、上传者、时间、热度。 | /t -i |
| /t -r | 排行榜：显示热度 (Heat) 最高的 Top 5。 | /t -r |
检索与查询
| 指令格式 | 功能描述 | 示例 |
|---|---|---|
| /t -f [ID] | 精确查找：根据 ID 获取某条语录的内容。 | /t -f 10 |
| /t -f [ID] -i | 详细溯源：在查找的基础上，额外显示最近 5 条表情互动记录（谁、什么时间、发了什么表情）。 | /t -f 10 -i |
| /t -t | 全库统计：显示当前数据库收录的总条数。 | /t -t |
| /t -t -c | 个人档案：查询自己贡献了哪些语录（显示最近 10 条）。 | /t -t -c |
| /t -t -c [QQ] | (管理员) 查询指定 QQ 号贡献的语录。 | /t -t -c 123456 |
互动机制 (Interaction)
当机器人发送语录消息后（无论是随机抽取还是精确查找），系统会开启一个 300秒（5分钟） 的监听窗口。
- 在此期间，任何群成员对该消息贴表情（Emoji Reaction），语录的 热度 (Heat) 将自动 +1。
- 支持反复刷分（贴表情 -> 取消 -> 再贴）。
- 系统会记录最近 5 次互动的用户与表情类型。
3. 管理与调试 (Admin & Debug)
该模式仅允许 白名单管理员 (ADMIN_LIST) 或 内容发布者（仅限修改/删除自己的内容）使用。 指令前缀：/t -d [ID] [操作码] [参数]
| 操作码 | 功能 | 权限 | 是否需二次确认 | 示例 |
|---|---|---|---|---|
| -c | 删除数据 | 管理员 / 作者 | 是 (confirm) | /t -d 5 -c /t -d 5 -c confirm |
| -s | 修改内容 | 管理员 / 作者 | 否 | /t -d 5 -s 新的内容 |
| -r | 重置热度 | 仅管理员 | 是 (confirm) | /t -d 5 -r /t -d 5 -r confirm |
| -a | 调整热度 | 仅管理员 | 否 | /t -d 5 -a 10 (增加10) /t -d 5 -a -5 (减少5) |
注意：删除操作 (-c) 触发 ID 回收逻辑。如果删除的是最新的 ID，系统指针 (next_id) 会回退；如果删除的是中间的 ID，该 ID 将永久空缺。
4. 开发者文档 (Developer Reference)
4.1 文件结构
- quotes_local.py: 插件核心逻辑。
- quotes_data.json: 数据存储文件（自动生成）。
4.2 JSON 数据库结构
quotes_data.json 采用扁平化设计，结构清晰，易于迁移或手动编辑。
JSON
{
"next_id": 105, // [Pointer] 下一条新语录将使用的 ID
"quotes": [ // [Array] 数据主体
{
"id": 104, // [Int] 唯一索引 ID
"content": "人类的本质是...", // [String] 内容
"heat": 23, // [Int] 热度值
"uploader": 123456789, // [Int] 上传者 QQ
"time": 1705481000, // [Int] Unix 时间戳 (录入时间)
"reactions": [ // [Array] 互动日志 (Max 5)
{
"user": 987654321, // [Int] 互动者 QQ
"emoji": "212", // [String] 表情代码 (QQ Face ID 或 Unicode)
"time": 1705481050 // [Int] 互动时间
}
]
}
]
}4.3 关键逻辑说明
内存映射 (Memory Mapping)
为了实现“对消息贴表情增加热度”，系统在内存中维护了一个映射表 active_messages。
- Key: message_id (Bot 发出的消息 ID)
- Value:
- 生命周期:
- Bot 发消息 -> 写入映射。
- 收到表情通知 -> 查表 -> 校验时间 (now - time < 300s) -> 更新 JSON。
- 限制: Bot 重启后内存清空，重启前的消息将失去互动能力（符合预期，避免内存泄漏）。
表情解析 (Emoji Parsing)
NapCat/OneBot 上报的 emoji_id 有两种情况：
- QQ 自带表情 (Face): 通常为较小的数字 ID (如 212, 66)。系统使用 MessageSegment.face(id) 渲染为图片。
- Unicode Emoji: 通常为较大的十进制 Unicode 码点 (如 128514 对应 😂)。系统通过 chr(code) 还原为字符。
ID 回收策略 (ID Recycling)
- 场景 1 (删除最新): 当前 next_id 为 10，最大 ID 为 9。删除 ID 9 后，系统检测到最大 ID 变为 8，则将 next_id 回退为 9。
- 场景 2 (删除中间): 当前 next_id 为 10，删除 ID 5。系统检测到最大 ID 仍为 9，next_id 保持 10 不变。ID 5 成为空洞 (Void)。
4.4 配置参数 (Configuration)
在 quotes_local.py 头部可调整：
- WHITE_LIST: 允许响应指令的群号列表。
- ADMIN_LIST: 拥有调试/数值修改权限的 QQ 号列表。
- REACTION_WINDOW: 互动有效时间窗口（秒），默认 300。