mirror of
https://github.com/snowy-yang/qqbotsdk.git
synced 2026-10-21 13:37:19 +00:00
docs: 文档模块化重构（guide/api 多页），文档站迁移 GitHub Pages Actions 部署
GUIDE/API 拆为 docs/guide/ 五页与 docs/api/ 七页，侧边栏分组折叠， 旧链接 alias 映射；安装改为 pip install qqbotsdk-py，README 加徽章； 删除 docs 分支同步工作流，pages.yml 直部署（自定义域名 CNAME 随产物带上）。
This commit is contained in:
snowy-yang committed
1 parent
652a142e86
commit
bcd69099b6
18 files changed
+829
-71
No files matched your search
@@ -1,10 +1,60 @@
|
||||
# qqbotsdk
|
||||
|
||||
[](https://github.com/snowy-yang/qqbotsdk/actions/workflows/ci.yml)
|
||||
[](https://pypi.org/project/qqbotsdk-py/)
|
||||
[](https://pypi.org/project/qqbotsdk-py/)
|
||||
[](https://pypistats.org/packages/qqbotsdk-py)
|
||||
[](LICENSE)
|
||||
|
||||
QQ 官方机器人 Python SDK（Python 3.12+ / asyncio / aiohttp），支持 WebSocket 与 Webhook 两种接入方式。
|
||||
|
||||
**📖 在线文档：<https://qqbotsdk.4i.hk/>**
|
||||
|
||||
[使用指南](docs/GUIDE.md) · [API 参考](docs/API.md) · [架构](docs/ARCHITECTURE.md) · [示例](examples/) · [更新日志](CHANGELOG.md)
|
||||
[快速开始](docs/guide/start.md) · [使用指南](docs/guide/handlers.md) · [API 参考](docs/api/core.md) · [架构](docs/ARCHITECTURE.md) · [示例](examples/) · [更新日志](CHANGELOG.md)
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
pip install qqbotsdk-py # 或 uv add qqbotsdk-py
|
||||
```
|
||||
|
||||
## 五分钟上手
|
||||
|
||||
`.env` 配好 `APPID`/`APPSECRET`，`intents.toml` 开启 `GROUP_AND_C2C_EVENT = true`：
|
||||
|
||||
```python
|
||||
from qqbotsdk import Bot
|
||||
from qqbotsdk.api import BotApi
|
||||
from qqbotsdk.payloads import GroupAtMessage
|
||||
|
||||
bot = Bot()
|
||||
|
||||
|
||||
# handler 形参按标注注入 payload 与 BotApi 等组件
|
||||
@bot.on("GROUP_AT_MESSAGE_CREATE")
|
||||
async def on_group_message(msg: GroupAtMessage, api: BotApi):
|
||||
# 被动回复带 msg_id（5 分钟内有效，多次回复递增 msg_seq）；失败抛 ApiError
|
||||
await api.post_group_message(
|
||||
msg.group_openid,
|
||||
content=f"你说：{msg.content}",
|
||||
msg_id=msg.id,
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
bot.run()
|
||||
```
|
||||
|
||||
Webhook 接入：`.env` 中 `CONNECTER` 改为 `webhook`，再把回调地址配置到 QQ 开放平台（仅支持 80/443/8080/8443 端口，需公网 HTTPS），handler 写法完全一致。
|
||||
|
||||
## 特性
|
||||
|
||||
- `Bot` 门面：`bot.run()` 一行启动，`bot.call_api` 通用 REST，`bot.api` 类型化 API 面
|
||||
- 断线自动重连（指数退避 + 心跳看门狗），重连时自动 RESUME 续传
|
||||
- Webhook 接入自带 Ed25519 验签、op=13 验证应答与事件去重
|
||||
- 事件订阅由项目根目录的 `intents.toml` 按大类开关
|
||||
- Markdown 与内嵌按钮一等支持，`respond_interaction()` 回应按钮回调
|
||||
- 组件按类型注入 handler（自定义组件同样可注入），全 SDK 共享一个 HTTP 连接池
|
||||
|
||||
## 架构
|
||||
|
||||
@@ -24,7 +74,7 @@ flowchart TB
|
||||
end
|
||||
subgraph 业务层
|
||||
API["BotApi（REST + ApiError）"]
|
||||
USER["用户 handler @ee.on(...)"]
|
||||
USER["用户 handler @bot.on(...)"]
|
||||
end
|
||||
QQ["QQ 开放平台"]
|
||||
|
||||
@@ -39,65 +89,7 @@ flowchart TB
|
||||
WS --> QQ
|
||||
```
|
||||
|
||||
组件在 `run_loop` 中显式装配，依赖关系与设计决策详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
|
||||
|
||||
## 特性
|
||||
|
||||
- 断线自动重连（指数退避 + 心跳看门狗），重连时自动 RESUME 续传
|
||||
- Webhook 接入自带 Ed25519 验签、op=13 验证应答与事件去重
|
||||
- 事件订阅由项目根目录的 `intents.toml` 按大类开关
|
||||
- Markdown 与内嵌按钮一等支持，`respond_interaction()` 回应按钮回调
|
||||
- 组件显式装配（无全局单例），全 SDK 共享一个 HTTP 连接池
|
||||
|
||||
## 配置
|
||||
|
||||
`.env`（`APPID`/`APPSECRET` 必填，缺失启动即报错）：
|
||||
|
||||
```ini
|
||||
APPID=你的AppID
|
||||
APPSECRET=你的AppSecret
|
||||
BASE_URL=https://api.bot.qq.com # 可选
|
||||
TIMEOUT=5000 # 可选，毫秒
|
||||
CONNECTER=websocket # websocket 或 webhook
|
||||
|
||||
# 仅 webhook 接入时
|
||||
WEBHOOK_HOST=0.0.0.0
|
||||
WEBHOOK_PORT=8080
|
||||
WEBHOOK_PATH=/qqbot/webhook
|
||||
```
|
||||
|
||||
## 使用
|
||||
|
||||
```python
|
||||
from qqbotsdk import EventEmitter, main
|
||||
from qqbotsdk.payloads import GroupAtMessage
|
||||
from qqbotsdk.api import BotApi
|
||||
|
||||
ee = EventEmitter()
|
||||
|
||||
# handler 形参按标注注入 payload 与 BotApi 等组件
|
||||
@ee.on("GROUP_AT_MESSAGE_CREATE")
|
||||
async def on_group_message(msg: GroupAtMessage, api: BotApi):
|
||||
# 被动回复带 msg_id；多次回复递增 msg_seq；失败抛 ApiError
|
||||
await api.post_group_message(
|
||||
msg.group_openid,
|
||||
content=f"你说：{msg.content}",
|
||||
msg_id=msg.id,
|
||||
)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main(ee)
|
||||
```
|
||||
|
||||
运行：
|
||||
|
||||
```bash
|
||||
uv run python main.py
|
||||
```
|
||||
|
||||
Webhook 接入：`.env` 中 `CONNECTER` 改为 `webhook`，再把回调地址配置到 QQ 开放平台（仅支持 80/443/8080/8443 端口，需公网 HTTPS）。
|
||||
|
||||
完整示例见 [examples/](examples/)，更多写法见[使用指南](docs/GUIDE.md)。
|
||||
组件在 `Bot.start()` 中装配，依赖关系与设计决策详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
|
||||
|
||||
## 开发
|
||||
|
||||
@@ -106,14 +98,10 @@ uv run pytest # 单元测试
|
||||
uv run ruff check src tests examples && uv run pyright
|
||||
```
|
||||
|
||||
推送与 Pull Request 由 GitHub Actions 自动执行同样的检查（[.github/workflows/ci.yml](.github/workflows/ci.yml)）。
|
||||
推送与 Pull Request 由 GitHub Actions 自动执行同样的检查（[.github/workflows/ci.yml](.github/workflows/ci.yml)）；打 `v*` 标签经 [publish.yml](.github/workflows/publish.yml) 以 Trusted Publishing 发布到 PyPI。
|
||||
|
||||
文档站点基于 [docsify](https://docsify.js.org/)，文档变更时自动发布（[.github/workflows/deploy-docs.yml](.github/workflows/deploy-docs.yml)）；本地预览：
|
||||
文档站点基于 [docsify](https://docsify.js.org/)，文档变更时自动部署到 GitHub Pages（[.github/workflows/pages.yml](.github/workflows/pages.yml)，自定义域名 qqbotsdk.4i.hk）；本地预览：
|
||||
|
||||
```bash
|
||||
npx docsify-cli serve
|
||||
```
|
||||
|
||||
## 待完善
|
||||
|
||||
- 更多 OpenAPI 封装（按需在 `api.py` 的 `BotApi` 上加薄封装即可）
|
||||
Reference in new issue
Block a user