# d2-qq-bot

**Repository Path**: chenxiu/d2-qq-bot

## Basic Information

- **Project Name**: d2-qq-bot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 暗黑破坏神2 MOD 群聊 AI 助手（QQ 版）

基于 `qq_bot`（传奇版本）架构移植的 **D2 MOD 版本**：群友 `@机器人` 提问 MOD 相关玩法/数值/掉落，
自动检索 **92 张游戏数值表 + D2MOO 源码** → AI 自主调工具查证 → 回群。偏玩家向。

## 项目结构
```
d2_qq_bot/
├── bot.py          主程序（OneBot 连接、@识别、限流、agent循环、插嘴、安全过滤）
├── retriever.py    MOD 知识库检索（TXTeditor 语义解析 + 92表 + D2MOO源码 + 实体关联 + function calling 工具）
├── ai.py           AI 调用封装（OpenAI 兼容接口，支持 function calling）
├── config.json     配置（必填）
├── schema/curated.json  TXTeditor 语义 schema（机器人自带副本）
├── requirements.txt
├── test_retriever.py  离线验证检索器（不连 QQ）
└── sim_test.py        离线链路干跑（mock AI，验证 @解析→工具→回群）
```

## 一、填配置（config.json）
```json
{
  "qq": "机器人QQ号（纯数字）",
  "napcat_ws": "ws://127.0.0.1:3001",
  "napcat_token": "",
  "allow_all_groups": false,          // 安全默认：false 时必须填写 group_whitelist
  "group_whitelist": [群号],           // 只响应这些群；确需全开放时再将 allow_all_groups 改为 true
  "join": { "auto_approve": true, "welcome_enabled": true, "welcome_delay_sec": 3 },
  "d2txt_root": "…/D2TXT/Data/Global/Excel",   // 92 张 TXT 表目录
  "d2moo_root": "…/D2MOO/source",             // D2MOO 源码目录（不存在则仅索引 TXT）
  "ai": { "base_url": "…/v1", "api_key": "你的key", "model": "模型名", "timeout": 90 },
  "limits": { "min_interval_sec": 3, "max_reply_len": 1500, "max_concurrent_ai": 4, "max_hits": 6, "per_user_cool_sec": 10 },
  "chatty": { "enabled": false, "probability": 0.05, "cooldown_sec": 600, "max_reply_len": 60, "min_msg_len": 2, "ignore_words": ["http","www","//","微信","qq群"] }
}
```

记忆库按群隔离；“记忆列表”、编号删除、关键词删除和玩家投喂每日上限都会限定在正确的权限范围内。默认不主动插嘴、不抬杠，也不会响应未加入白名单的群。

TXT 解析优先读取机器人目录内的 `schema/curated.json`，因此运行机器人不再依赖外部 `editor` 目录；如果本地副本不存在，才会回退到同级或上级 `editor/server/schema/curated.json`，最后使用基础解析。

入群申请也复用 `group_whitelist`：白名单群会自动通过 `add/invite` 申请；收到新人实际入群通知后，延迟几秒 @ 新人发送欢迎语、群文件提示和在线说明地址。

## 二、装 NapCat（QQ 协议网关）
同 qq_bot：下载 NapCat → 登录 QQ 小号 → 开启 **OneBot 11 正向 WebSocket（端口 3001）** → 把机器人拉进群。
> ⚠️ 非官方协议有封号风险，请用专用小号、降低回复频率。

## 三、安装依赖
```bash
C:\Users\lion\.workbuddy\binaries\python\envs\d2_qq_bot\Scripts\python.exe -m pip install -r requirements.txt
```

## 四、运行
```bash
C:\Users\lion\.workbuddy\binaries\python\envs\d2_qq_bot\Scripts\python.exe bot.py
# 可选：用其它 MOD 数据/源码覆盖
python bot.py --mod D:/别的MOD/Excel --moo D:/别的MOD/D2MOO/source
```
看到 `已连接 NapCat` 即就绪。群内 `@机器人 安达利尔掉什么` 即可获得回答。

## 五、离线自检（不连 QQ）
```bash
python test_retriever.py     # 验证 92表+源码索引与各工具返回
python sim_test.py           # 验证 @解析→agent循环→工具→回群 整条链路
```

## 六、AI 可调用的工具
| 工具 | 用途 |
|---|---|
| `query_monster_drops` | 某怪物掉什么（含 1/N 掉率） |
| `query_item_sources` | 某物品/装备由哪些怪物、哪个宝箱类(TC)掉落 |
| `query_skill` | 技能机制：职业/描述/导弹/状态/calc公式/需求 |
| `query_item` | 装备属性：类型/需求/升级链 |
| `query_property` | 属性码（如 dmg-min、res-all）含义 |
| `query_table` | 按表/字段/主键查询真实 TXT 行，并返回字段类型、外键和编辑器说明 |
| `search_tables` | 92 张数值表关键词全文搜索 |
| `search_source` / `read_source` | D2MOO 源码搜索/读取 |

## 七、注意
- 玩家问题中的怪物/物品/技能名若是中文，由 AI 从训练知识映射到英文内部名（如 安达利尔→Andariel）再查；若 MOD 自定义了名称，可在 `retriever.py` 顶部加中文别名映射。
- 安全过滤仅拦截作弊/复制/利用漏洞类问题，正常数值与玩法问题均开放。
- 改 MOD 数据（TXT 表）属于开发行为，本助手偏玩家向，主要通过查表回答"数值在哪、是多少"。
- TXT 解析优先使用机器人自带的 `schema/curated.json`，并补齐所有表的类型、主键和保守外键推断；本地 schema 不存在时才回退到 `editor/server/schema/curated.json`，找不到编辑器目录时仍可运行基础解析。
- 怪物掉落按普通/噩梦/地狱分别读取对应的 `Level`、生命、经验、防御和 TC；属性码会继续解析到 `Properties.txt`、`ItemStatCost.txt` 和字符串表。