mirror of
https://github.com/snowy-yang/qqbotsdk.git
synced 2026-10-21 08:04:49 +00:00
docs: 基于 docsify 搭建文档站点
This commit is contained in:
snowy-yang committed
1 parent
097bc96d8b
commit
750ed81d96
6 files changed
+126
No files matched your search
@@ -10,6 +10,7 @@
|
||||
- Markdown 与内嵌按钮一等支持：`post_group_message`/`post_c2c_message` 新增 `markdown`/`keyboard` 参数（自动置 msg_type=2，与 content 互斥）；新增 `respond_interaction()` 回应按钮回调；`Interaction` payload 补齐 `chat_type`/`scene`/`group_openid` 等官方字段
|
||||
- `Event` 新增 `event_id` 属性（推送信封顶层的事件 id，与 op/t/d 平级）：非消息事件（GROUP_ADD_ROBOT 等）的被动回复不再需要手动 `event.raw["id"]`
|
||||
- 按钮快捷构造与点击处理：`button()`/`keyboard()` 生成内嵌按钮（免手写嵌套 dict）；`Interaction` 新增 `button_data` 属性（被点按钮的 action.data）；examples/group_bot 补 `/btn` 卡片与 `INTERACTION_CREATE` 回调示例
|
||||
- 文档站点：基于 docsify（侧边栏、全文搜索、代码复制、mermaid 图渲染、分页），`npx docsify-cli serve` 本地预览；新增 `examples/README.md` 示例索引
|
||||
|
||||
### 变更
|
||||
|
||||
|
||||
@@ -126,6 +126,12 @@ uv run pytest # 单元测试
|
||||
uv run ruff check src tests examples && uv run pyright
|
||||
```
|
||||
|
||||
文档站点基于 [docsify](https://docsify.js.org/)（无需构建，仓库根 `index.html` + Markdown），本地预览：
|
||||
|
||||
```bash
|
||||
npx docsify-cli serve # 打开 http://localhost:3000
|
||||
```
|
||||
|
||||
## 待完善
|
||||
|
||||
- 更多 OpenAPI 封装（按需在 `api.py` 的 `BotApi` 上加薄封装即可）
|
||||
@@ -0,0 +1,6 @@
|
||||
- [首页](/README.md)
|
||||
- [使用指南](/docs/GUIDE.md)
|
||||
- [API 参考](/docs/API.md)
|
||||
- [架构设计](/docs/ARCHITECTURE.md)
|
||||
- [示例](/examples/README.md)
|
||||
- [更新日志](/CHANGELOG.md)
|
||||
@@ -0,0 +1,25 @@
|
||||
# 示例
|
||||
|
||||
可运行的完整示例，均以仓库根目录为工作目录启动（`.env`、`intents.toml` 放在根目录）。
|
||||
|
||||
| 示例 | 接入方式 | 内容 |
|
||||
|---|---|---|
|
||||
| `group_bot/main.py` | WebSocket | @消息被动回复、`/img` 富媒体图片、`/btn` Markdown 按钮卡片与点击回调、入群欢迎、单聊回复 |
|
||||
| `webhook_bot/main.py` | Webhook | HTTP 回调收群 @消息并被动回复的最小接入 |
|
||||
|
||||
## 运行前提
|
||||
|
||||
1. 根目录 `.env` 配好 `APPID`/`APPSECRET`（`webhook_bot` 需另设 `CONNECTER=webhook`）；
|
||||
2. `intents.toml` 开启对应事件分组（`group_bot` 需 `GROUP_AND_C2C_EVENT` 与 `INTERACTION`，`webhook_bot` 需 `GROUP_AND_C2C_EVENT`）；
|
||||
3. `group_bot` 要求机器人已开通群聊能力并拉入测试群；`webhook_bot` 要求公网 HTTPS 部署（平台仅支持 80/443/8080/8443 端口，本地调试可用内网穿透）。
|
||||
|
||||
## 运行
|
||||
|
||||
```bash
|
||||
uv run python examples/group_bot/main.py
|
||||
uv run python examples/webhook_bot/main.py
|
||||
```
|
||||
|
||||
Webhook 示例启动后，把 `https://<你的域名>:<端口>/qqbot/webhook` 填到开放平台回调地址；保存时平台先发 op=13 验证请求，SDK 自动完成签名应答。
|
||||
|
||||
接入方式切换与 handler 写法详见 [使用指南](docs/GUIDE.md#接入方式选择)。
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>qqbotsdk 文档</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="description" content="QQ 官方机器人 Python SDK：使用指南、API 参考、架构设计与示例">
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/themes/vue.css">
|
||||
<style>
|
||||
/* mermaid 图居中并自适应宽度 */
|
||||
.markdown-section .mermaid {
|
||||
text-align: center;
|
||||
}
|
||||
.markdown-section .mermaid svg {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app">加载中…</div>
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
name: 'qqbotsdk',
|
||||
repo: 'https://gitea.4i.hk/hhhge/qqbotsdk',
|
||||
// 相对链接按当前页面所在目录解析（与 GitHub 行为一致），docs/*.md 的互链才能正确跳转
|
||||
relativePath: true,
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 3,
|
||||
auto2top: true,
|
||||
themeColor: '#0f8bff',
|
||||
search: {
|
||||
paths: 'auto',
|
||||
placeholder: '搜索文档',
|
||||
noData: '没有找到相关结果',
|
||||
depth: 3,
|
||||
},
|
||||
copyCode: {
|
||||
buttonText: '复制',
|
||||
errorText: '复制失败',
|
||||
successText: '已复制',
|
||||
},
|
||||
pagination: {
|
||||
previousText: '上一页',
|
||||
nextText: '下一页',
|
||||
},
|
||||
// README 里的 examples/ 链接指向示例索引页
|
||||
alias: {
|
||||
'/examples': '/examples/README.md',
|
||||
'/examples/': '/examples/README.md',
|
||||
},
|
||||
plugins: [
|
||||
// 把 ```mermaid 代码块替换为 div 后交给 mermaid 渲染（架构图/时序图）
|
||||
function (hook) {
|
||||
hook.doneEach(function () {
|
||||
var blocks = document.querySelectorAll('pre code.lang-mermaid, pre code.language-mermaid');
|
||||
if (!blocks.length || !window.mermaid) return;
|
||||
blocks.forEach(function (el) {
|
||||
var pre = el.closest('pre') || el;
|
||||
var div = document.createElement('div');
|
||||
div.className = 'mermaid';
|
||||
div.textContent = el.textContent;
|
||||
pre.replaceWith(div);
|
||||
});
|
||||
mermaid.run({ querySelector: 'div.mermaid:not([data-processed])', suppressErrors: true });
|
||||
});
|
||||
},
|
||||
],
|
||||
};
|
||||
</script>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
|
||||
<!-- prism 语言包需在 docsify 之后引入（docsify 会重建 window.Prism，先加载会被覆盖） -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-python.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-toml.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-ini.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@3/dist/docsify-copy-code.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
|
||||
<script>
|
||||
mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
Reference in new issue
Block a user