6ec3cd623d
- SKILL.md 前置条件 → 链接到本仓库 - README.md 底部链接 → chat_rebot-connect-with-onebot-standard- - SKILL.md 组件清单移除 browser/mc-query/nix-helper/file-process
214 lines
5.6 KiB
Markdown
Executable File
214 lines
5.6 KiB
Markdown
Executable File
# OneBot Chatbot Framework
|
||
|
||
该项目是一个基于OneBot标准的聊天机器人后端框架，采用高度可扩展的插件架构设计，支持消息的模块化处理和插件热加载。如果你有任何意见或建议，可以通过 jianfeee@outlook.com 联系我。
|
||
|
||
## 项目特点
|
||
|
||
- **模块化设计**：每个功能作为独立插件实现，易于扩展和维护
|
||
- **插件生命周期管理**：支持插件加载、注册、依赖处理和实例管理
|
||
- **消息处理管道**：分阶段处理消息，支持各阶段拦截机制
|
||
- **会话管理**：支持群组消息和私聊消息的独立管理
|
||
- **内嵌依赖处理**：自动管理插件内嵌的Python依赖包
|
||
- **兼容性设计**：支持新旧版本插件并存运行
|
||
|
||
## 内置插件
|
||
|
||
### OpenClaw Bridge
|
||
|
||
`src/process.py` — QQ 消息 ↔ OpenClaw Gateway 桥接插件。
|
||
将用户消息转发给 OpenClaw Gateway 上的 AI agent 处理并自动回复。
|
||
|
||
**配置**: `config/openclawbridge/config.toml`
|
||
|
||
### QQ 操作脚本
|
||
|
||
`scripts/qq_*.py` — 15 个独立脚本，agent 可通过 subprocess 直连 NapCat API 主动操作 QQ。
|
||
|
||
### Agent Skills
|
||
|
||
`skills/` — AgentSkills，指导 AI agent 如何使用上述脚本。
|
||
|
||
## 核心组件
|
||
|
||
### 消息处理流程 (`process_message`)
|
||
|
||
```python
|
||
def process_message(uid: str, gid: str | None, message: str) -> str:
|
||
# 1. 创建消息上下文
|
||
ctx = MessageContext(...)
|
||
|
||
# 2. 扫描并加载插件
|
||
plugin_manager.scan_plugins()
|
||
|
||
# 3. 消息处理阶段：
|
||
# - before_load: 加载数据前拦截点
|
||
# - after_load: 加载数据后处理点
|
||
# - after_save: 保存数据后处理点
|
||
|
||
# 4. 会话数据持久化
|
||
ctx.chat_manager.save_message(...)
|
||
|
||
return ctx.response or "ok"
|
||
```
|
||
|
||
### 插件管理器 (`PluginManager`)
|
||
|
||
```python
|
||
class PluginManager:
|
||
def __init__(self):
|
||
self._plugins = {} # 插件类注册表
|
||
self._active_instances = {} # 插件实例
|
||
self._hook_registry = {} # 兼容旧版钩子
|
||
self._temp_dirs = [] # 临时目录
|
||
self._dependency_manager = DependencyManager() # 依赖处理器
|
||
|
||
def scan_plugins(self):
|
||
"""扫描插件目录并加载ZIP格式插件"""
|
||
|
||
def load_plugin(self, zip_path: str) -> bool:
|
||
"""动态加载ZIP格式插件"""
|
||
|
||
def _load_embedded_dependencies(self, plugin_dir: str) -> bool:
|
||
"""加载插件内嵌的依赖包"""
|
||
|
||
def register_hook(self, hook_name: str):
|
||
"""注册兼容旧版钩子（装饰器模式）"""
|
||
|
||
def cleanup(self):
|
||
"""清理临时资源"""
|
||
```
|
||
|
||
## 插件开发指南
|
||
|
||
### 基本插件结构
|
||
|
||
```python
|
||
# process.py
|
||
from src.modules.plugin_modules import BasePlugin, MessageContext
|
||
|
||
class MyPlugin(BasePlugin):
|
||
def __init__(self, ctx: MessageContext):
|
||
super().__init__(ctx)
|
||
|
||
def process(self) -> str | None:
|
||
"""核心处理方法"""
|
||
if self.ctx.command == "help":
|
||
return self._show_help()
|
||
|
||
def before_load(self) -> str | None:
|
||
"""数据加载前拦截点"""
|
||
|
||
def after_load(self) -> str | None:
|
||
"""数据加载后处理点"""
|
||
|
||
def after_save(self) -> str | None:
|
||
"""数据保存后处理点"""
|
||
```
|
||
|
||
### 目录结构要求
|
||
|
||
插件应以ZIP格式打包，包含以下内容：
|
||
|
||
```
|
||
my_plugin.zip
|
||
├── process.py # 必需 - 插件入口文件
|
||
├── requirements.txt # 可选 - 依赖声明
|
||
└── packages/ # 可选 - 内嵌依赖包
|
||
├── package1/
|
||
└── package2/
|
||
```
|
||
|
||
### 依赖声明
|
||
|
||
插件可通过两种方式声明依赖：
|
||
|
||
1. `requirements.txt` 标准格式
|
||
2. `dependencies.json` 自定义格式
|
||
|
||
```json
|
||
// dependencies.json 示例
|
||
{
|
||
"requirements": [
|
||
"requests==2.28.2",
|
||
"numpy>=1.25.0"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
1. 为启动脚本授权（Linux）：
|
||
|
||
```bash
|
||
chmod +x run.sh
|
||
```
|
||
|
||
2. 修改配置文件，`list_port` 为接收消息推送端口，`send_url` 为消息发送地址
|
||
|
||
3. 运行启动脚本
|
||
|
||
Linux：
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
Windows：
|
||
|
||
```bat
|
||
.\run.bat
|
||
```
|
||
|
||
## AI Agent 部署（OpenClaw）
|
||
|
||
如需让 AI agent 主动操作 QQ（发消息、管理群、查信息等），需将脚本和 Skill 部署到 agent 的工作区。
|
||
|
||
### 1. 部署脚本
|
||
|
||
将 `scripts/` 目录复制到 qq-agent 工作区：
|
||
|
||
```bash
|
||
cp -r scripts/ /path/to/qq-agent/workspace/
|
||
```
|
||
|
||
### 2. 部署 Skills
|
||
|
||
将 QQ 相关的 Skill 复制到 agent 的 skills 目录：
|
||
|
||
```bash
|
||
cp -r skills/qq-messenger /path/to/agent/skills/
|
||
cp -r skills/qq-management /path/to/agent/skills/
|
||
cp -r skills/qq-resolver /path/to/agent/skills/
|
||
cp -r skills/qq-napcat-extras /path/to/agent/skills/
|
||
```
|
||
|
||
### 3. 替换占位符
|
||
|
||
编辑各脚本开头的配置变量，将占位符替换为实际值：
|
||
|
||
```python
|
||
# 需替换的占位符：
|
||
ADMIN_QQ = "YOUR_ADMIN_QQ" # 你的 QQ 号
|
||
CQHTTP_URL = "http://YOUR_NAPCAT_HOST:25570" # NapCat 地址
|
||
GATEWAY_URL = "http://127.0.0.1:18789" # OpenClaw Gateway
|
||
GATEWAY_TOKEN = "YOUR_GATEWAY_TOKEN" # Gateway 鉴权 Token
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
在 agent 工作区尝试执行单个脚本确认连通性：
|
||
|
||
```bash
|
||
cd /path/to/qq-agent/workspace/scripts
|
||
python3 qq_get_groups.py
|
||
```
|
||
## 设计优势
|
||
|
||
1. **解耦设计**：插件与核心系统完全解耦
|
||
2. **安全隔离**：使用临时目录加载插件
|
||
3. **版本兼容**：内建依赖版本验证机制
|
||
4. **灵活扩展**：支持多个消息处理点
|
||
5. **新旧兼容**：支持传统钩子和现代OOP插件的共存
|
||
|
||
仓库地址：[chat_rebot-connect-with-onebot-standard-](https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-)
|