📚 XiaoQing 开发文档
BOT FRAMEWORK
Python asyncio + OneBot
XiaoQing
面向 QQ 机器人场景的轻量框架文档入口，聚焦启动、消息链路、插件体系和部署配置，适合从接入到二次开发的完整阅读。
查看 XiaoQing 仓库
项目主页与源码入口
结构
从项目概览到消息流、插件开发与 API 参考，文档路径清晰。
重点
围绕 OneBot 接入、asyncio 运行时和插件机制组织内容。
适合
首次部署、插件开发、框架维护和排障阅读。
中文 | English
本目录保存 XiaoQingBot 项目手册。 文档按“认识项目 → 启动服务 → 理解架构 → 开发插件 → 查询接口与配置 → 深入运行机制 → 使用插件”的顺序组织。
📚 主题索引
| 文档 | 主要职责 | 目标读者 |
|---|---|---|
| 00 - 项目概览 | 项目定位、能力边界、核心概念和目录结构 | 所有读者 |
| 01 - 快速开始 | 安装、配置、OneBot 接入、启动和首次验证 | 新用户、部署者 |
| 02 - 系统架构 | 运行时组件、服务边界、生命周期和数据流 | 框架维护者 |
| 03 - 插件开发 | Manifest、入口、上下文、会话、调度和测试 | 插件开发者 |
| 04 - Core 模块 | core/ 模块职责与协作关系 | 框架维护者 |
| 05 - API 参考 | PluginContext、消息段、会话和插件入口签名 | 插件开发者 |
| 06 - 配置详解 | 配置字段、secrets、AI 路由、网络安全和热重载 | 部署者、管理员 |
| 07 - 高级主题 | 权限模型、后台任务、调度、服务能力、性能和部署模式 | 高级开发者 |
| 08 - 消息流程 | OneBot 事件从接收到回复的完整路径 | 排障人员、框架维护者 |
| 09 - 插件使用手册 | 31 个内置插件的用途、命令、配置与数据，命令入口速查和定时任务总表 | 用户、管理员 |
| Pendo Scriptable 小组件 | iPhone 小组件鉴权、脚本和设置步骤 | Pendo 用户 |
| 更新记录 | 各版本的功能变化、影响范围和验证结果 | 用户、维护者 |
📌 推荐阅读路线
第一次运行
- 阅读 项目概览，了解 OneBot、Core、插件和数据目录。
- 按 快速开始 完成安装、配置、接入和启动。
- 通过 配置详解 完成生产参数与 secrets 设置。
- 在 插件目录 选择功能，并进入对应插件 README。
开发插件
排查消息链路
🧩 核心插件文档
| 插件 | 使用说明 | 架构说明 |
|---|---|---|
xiaoqing_chat | README | ARCHITECTURE |
xiaoqing_agent | README | README 内含模块结构、运行边界与数据说明 |
pendo | README | ARCHITECTURE |
其他插件均在各自目录提供 README.md。 插件目录 提供统一入口。
🏗️ 文档职责
docs/保存完整中文手册，docs/en/保存完整英文手册；两套手册使用对应的普通文件名，通过页首链接切换语言。- 中文文档是权威维护版本。修改手册中的功能、命令、参数、默认值、权限或部署步骤时，在同一变更中同步英文版本。
- 根目录 README 保留中英两版。插件说明、测试验收指南、维护约定和 Changelog 统一维护中文版本，英文手册中的相关链接标注为 Chinese。
- 根目录 README 提供项目入口和最短启动路径。
docs/00-09分别维护一个明确主题。- 插件 README 面向插件用户和部署者。
- 插件 ARCHITECTURE 面向插件维护者。
- 命令 Manifest 定义运行时帮助、权限、场景和样例。维护者在 Manifest 中声明权限。Core 统一检查权限。
- 所有 README 只描述当前能力、使用方法和运行契约；版本变化、一次性迁移与发布验证统一写入 Changelog。
- Changelog 记录版本变化与验证结果。
文档中的命令、字段、默认值和路径以代码、配置示例、Manifest 和测试契约为依据。