Runnel Zhang
Back to Projects

doge-repo

QQ机器人豆子 Doge的源码库。包括v2（使用CQP），v3（使用mirai），v4（使用AstrBot，当前版本）。

View on GitHub
Python

豆子 Doge 仓库说明

GitHub repo size GitHub last commit GitHub stars Line of Codes

QQ 机器人「豆子 Doge」源码仓库导读与上手指南

本文件旨在帮助你大致了解豆子、快速读懂仓库结构、了解各版本差异、并尽可能成功部署机器人

对此项目有疑问？

可以直接在wiki提问！DeepWiki

0. 简介

豆子 Doge 诞生于 2019 年，到如今历经四个版本。

v1活跃时间为 2019 年，采用 CQA 。仅有关键词回复和图灵api聊天两个功能，完全基于酷Q自带面板进行配置，不存在源码一说。

v2活跃时间为 2020 年，采用 CQP 。仓库中文件与v2实际功能不完全对应，只包含可以找到的少部分源文件。

  • v2文档可参见: v2_docs.pdf （注意：此文档为早期版本，基本不包含此仓库中源文件所涉及的功能）

v3活跃时间为 2022 年，采用 Mirai。仓库基本实现全收录.

v4为现行版本，采用 AstrBot。仓库实时更新。

  • v4文档可参见：v4_docs.md，已整合入bot的知识库，可直接向bot提问来咨询详情

四个版本的豆子始终活跃于数学吧官群，在此对数吧群的各位表示感谢。豆子诞生的契机是认识了丽琪，复刻丽琪的功能也一度成为开发豆子的动力和目标。在开发过程中，丽琪的作者多次进行了倾力指导。没有丽琪，也就不会有如今的豆子。感谢伟大的丽琪之父fyr。特别鸣谢sym学长，在服务器方面不遗余力地进行了大量指导，让豆子得以成功摆脱本地部署的种种不便。

欢迎各位参与豆子的开发工作！

1. 我应该从哪个版本开始？

  • v4（doge-v4）— 当前版本：基于 AstrBot 框架（Python）。如果你是首次部署或想获得最新功能，请从 v4 开始。
  • v3（doge-v3）— 旧版本：基于 Mirai 框架（JVM）。仅用于回溯或研究旧实现，不建议部署。此版本分为四个子模块，其中主体为mirai-native和mirai-jvm。
  • v2（doge-v2）— 历史版本：基于 CQP 的早期实现，生态已停运；如需复刻，通常需用 go-cqhttp / mirai-native / MiraiCQ 等替代底层。不建议部署。

2. 功能块/指令概览

.
├── doge-v2/
├── doge-v3/
│   ├── lua-mirai/
│   │   ├── jeffjoke
│   │   └── qs
│   ├── mirai-api-http/
│   │   └── chatlearning
│   ├── mirai-jvm/
│   │   ├── chat
│   │   ├── genshin
│   │   ├── mirage
│   │   ├── nasa
│   │   ├── nc
│   │   ├── netool
│   │   ├── px
│   │   ├── wa
│   │   └── yan
│   └── mirai-native/
│       └── epk/
│           ├── amuse
│           ├── anime
│           ├── ask
│           ├── bing
│           ├── chem
│           ├── chart
│           ├── cotool
│           ├── docs
│           ├── dream
│           ├── echo
│           ├── frun
│           ├── fru
│           ├── gan
│           ├── game
│           ├── gen
│           ├── gpt
│           ├── insult
│           ├── jianh
│           ├── law
│           ├── math
│           ├── meme
│           ├── phil
│           ├── pic-url
│           ├── poem
│           ├── repo
│           ├── run
│           ├── se
│           ├── siku
│           ├── style
│           ├── test
│           ├── tex
│           ├── toonify
│           ├── url-pic
│           ├── ver
│           └── yg
└── doge-v4/
    ├── apis
    ├── complex
    ├── cube
    ├── doubao
    ├── emojimix
    ├── fourier
    ├── genshin
    ├── gol
    ├── gomoku
    ├── honkai
    ├── latex
    ├── liblibapi
    ├── lyrics
    ├── mc
    ├── meme
    ├── mermaid
    ├── mirage
    ├── music
    ├── pack
    ├── pjsk
    ├── pokemon
    ├── poker
    ├── rrpl
    ├── run
    ├── soup
    ├── st
    ├── tangut
    ├── trace
    ├── typst
    ├── utex
    ├── vv
    ├── wa
    ├── wordle
    ├── wiki
    └── wp

3. 快速上手（v4 / AstrBot）

3.1 先决条件

  • Python：建议 3.10+
  • 平台：QQ / QQ 频道 （仅在 aiocqhttp 端进行过部署，其他平台不保证成功）
  • 依赖与配置：运行pip install -r requirements.txt安装依赖的库(可能有冗余)。为了bot的流畅运行，建议预留1G左右内存。
  • 协议端：建议安装 NapCat 并进行登录，配置反向 Websocket 待用。其余实现请自行参考有关文档。

3.2 部署路径

本项目未在AstrBot进行发布，请手动部署。以下全部为linux端部署教程。

方式 A：Docker（推荐）

  1. 安装 Docker / Docker Compose。
  2. 使用以下指令直接部署：
sudo docker run -itd -p 6180-6200:6180-6200 -p 11451:11451 -v $PWD/data:/AstrBot/data -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone:ro --name astrbot m.daocloud.io/docker.io/soulter/astrbot:latest

该操作会将容器中的/AstrBot/data目录映射到~/astrbot/data。如需映射其他目录请自行修改以上指令。

  1. 将doge-v4/下的文件复制到~/astrbot/data/plugins/。

  2. 通过面板重启bot以加载插件。

（如果不会使用docker不建议使用此方案部署，容易滋生问题。）

方式 B：本地运行

  1. 克隆AstrBot仓库，切换路径至仓库目录。

  2. 运行以下指令：

uv sync
uv run main.py

  1. 将 doge-v4/ 下文件复制到/AstrBot/data/plugins/

  2. 通过面板重启bot以加载插件。

如果仍不会部署请参考AstrBot 官方文档。

提示：AstrBot 提供可视化管理面板与插件系统；很多配置可以在 WebUI 中完成。

3.3 开发插件（v4）

作为一个成长中的bot，豆子欢迎各位开发者进行pr。

  • 在 plugins/ 下新建独立目录，内含最小化入口与 pyproject.toml/requirements.txt（如需要）。至少应包含main.py和metadata.yaml。
  • 插件代码应避免阻塞，尽量使用异步 I/O；
  • 将密钥放入环境变量或独立配置文件，不要写死在仓库中。

4. 旧版本导读

4.1 v3（Mirai）

  • 适合复现旧功能或迁移思路；
  • 鉴于 Mirai 官方已跑路，不建议再对此版本进行部署；
  • MCL 登录目前需要自行签名，或者通过 overflow 对接 NapCat，具体操作不多赘述，请自行搜索；
  • mirai-jvm 目录下插件依赖于 mirai-console ，本仓库仅提供src/main下主要源码，请自行分辨将各文件放在Mirai插件模板的合适位置，自行打包后投放至 plugins 目录；
  • lua-mirai 直接基于 mirai-core，具体可见 lua-mirai 官方文档；
  • mirai-api-http 基于 OneBot 标准，其插件理论上可通过 http/ws 连接其他支持 OneBot 的框架（如 NapCat）；
  • 鉴于 mirai-native 的特殊性，和 mirai-console 部分插件可能发生冲突，上述方案不一定适用。目前经个人测试确定可行的一个方案是通过 MiraiCQ 连 NapCat 的正向 Websocket，合理放置插件的dll和json位置。v3_epk_config.json无法直接导入，请打开插件面板后对照json逐条配置。

4.2 v2（CQP）

  • 酷Q已停运；如需复刻或回溯，请以其他底层作为事件/协议桥接；
  • 可参考上方针对mirai-native的部署方案进行部署，合理放置插件的dll和json位置，在插件面板导入doge-v2.epk；
  • 该目录只包含可以找到的部分源文件，并不能复刻v2豆子全部功能，也缺少相关的本地数据。v2_epk_config.json为doge-v2.epk解码整理所得，便于查看，无法直接导入。
  • 由于生态陈旧，不建议用户使用 v2。

5. 运行与调试建议

  • 最小可运行：先仅接入一个平台（例如 QQ），验证收发消息，再逐步开启其他平台与功能。

  • 日志与排障：

    • 启动失败：优先检查 Python 版本、依赖安装、端口占用、环境变量；
    • 登录异常：检查平台凭据、风控/设备锁、频率限制；
    • 收发异常：核对适配器开关、路由/权限、消息上报/推送配置。
    • 回复错误：检查文件目录是否对应、部分功能的 API KEY 是否配置

6. 常见问答（FAQ）

Q: 一次性支持多平台吗？

A: 可以。建议先接一个平台，稳定后再逐步扩展。

Q: 插件该放哪里？怎么热更新？

A: 放在 plugins/。支持热加载；生产环境建议重启以保证一致性。

Q: 需要前置驱动或手机协议文件吗？

A: 取决于所选平台与适配器。请按对应文档准备设备信息、协议选择与风控处理策略。

7. 参考与延伸阅读

若你在使用本导读时发现与仓库实际不符，请提交 Issue 说明具体目录与文件，我们会同步更新本文件。

8. 许可证

本仓库使用 GPL-3.0 许可证。提交贡献即默认接受相同开源协议。