# qq-resolver Skill

QQ 信息查询能力 — 群列表、好友列表、ID 转名称、历史消息回溯、文件接收。通过 NapCat (OneBot) HTTP API 直接查询。

> **什么时候用历史消息工具：** 当用户提到某个话题、人物或事件，而你在当前 session 里找不到相关信息时，说明这个信息来自其他聊天（其他群/私聊），或者 session 重启过导致记忆丢失。这时应该调用 `qq_get_history.py` 查看相关群/私聊的历史消息来补全上下文。

## 脚本清单

所有脚本都在 `YOUR_WORKSPACE_PATH/scripts/` 目录下。

| 脚本 | 调用方式 | 说明 |
|---|---|---|
| `qq_get_groups.py` | `--json` `[--keyword 关键词]` | 返回所有群聊列表 |
| `qq_get_friends.py` | `--json` `[--keyword 关键词]` | 返回好友列表 |
| `qq_resolve_name.py` | `--uid <QQ号>` 或 `--gid <群号>` | QQ号/群号 ↔ 可读名称 |
| `qq_get_history.py` | `--gid <群号>` 或 `--uid <QQ号>` `--num <条数>` `--json` | 历史消息（时间倒序） |
| `qq_get_file.py` | `--file <file_id>` | 下载文件到 `files/` 目录 |

## 用法

所有脚本用 `subprocess.run(cmd, capture_output=True, text=True, timeout=10-15)` 即可，输出直接读 `result.stdout`。

### 查群列表
```
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_groups.py --json
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_groups.py --json --keyword "我的世界"
```

### 查好友列表
```
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_friends.py --json
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_friends.py --json --keyword "张三"
```

### 解析 QQ 号 / 群号
```
python3 YOUR_WORKSPACE_PATH/scripts/qq_resolve_name.py --uid YOUR_ADMIN_QQ
python3 YOUR_WORKSPACE_PATH/scripts/qq_resolve_name.py --gid 812704915
python3 YOUR_WORKSPACE_PATH/scripts/qq_resolve_name.py --uid YOUR_ADMIN_QQ --uid 12345678 --gid YOUR_GROUP_ID
```

### 获取历史消息 ⭐ 回顾
```
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_history.py --gid 812704915 --num 10 --json
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_history.py --uid YOUR_ADMIN_QQ --num 20 --json
```
返回 `[{ "time": "...", "sender_name": "...", "sender_card": "...", "message": "...", "message_type": "..." }]`

**什么时候该用：**
- 用户说"上次我们聊到的那个事" → 查历史看看上次聊了什么
- 用户问"你还记得XX吗" → 你不记得，查历史
- 提到一个不熟悉的人/群 → 先查群列表/好友列表确定身份，再查对应聊天历史
- session 刚启动时对之前对话没印象 → 主动查最近历史恢复认知

### 接收文件/图片 ⭐ 从QQ获取文件
```
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_file.py --file <file_id>
python3 YOUR_WORKSPACE_PATH/scripts/qq_get_file.py --file <file_id> --info --json
```
执行后自动下载到 `files/` 目录，输出：保存路径、文件名、大小、类型（图片/文件）。

**注意：** file_id 来自消息中的 `[image:xxx.jpg]` 或 `[file:xxx.zip]` 标记，冒号后面就是 file_id。

## 工作流程

遇到不认识的内容 → 查群列表/好友列表确定身份 → 查历史消息看上下文 → 回复用户

需要看文件内容（如图片识别、文档处理）→ 用 `qq_get_file.py` 下载到 `files/` 目录后读取