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`)

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):
        """清理临时资源"""

插件开发指南

基本插件结构

# 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/

依赖声明

插件可通过两种方式声明依赖：

requirements.txt 标准格式
dependencies.json 自定义格式

// dependencies.json 示例
{
    "requirements": [
        "requests==2.28.2",
        "numpy>=1.25.0"
    ]
}

快速启动

为启动脚本授权（Linux）：
```
chmod +x run.sh
```
修改配置文件，list_port 为接收消息推送端口，send_url 为消息发送地址
运行启动脚本

Linux：
```
./run.sh
```
Windows：
```
.\run.bat
```

完整部署指南

架构概览

整个系统分三层：

QQ客户端                   服务器
   │                         │
   │  QQ 协议                │
   ▼                         │
NapCat / go-cqhttp           │
   │  OneBot HTTP            │
   ├─── POST 消息 →  qqrebot （本仓库）
   │                        │
   │  HTTP API               │
   ◄─── 主动操作 ── qqrebot  │
   │                        ├─── 转发消息 → OpenClaw Gateway
   │                        │               └─── agent 处理
   │                        ◄─── 回复 ←────┘

第1步：部署 NapCat / go-cqhttp

这是 QQ 协议实现，负责登录 QQ 账号并与腾讯服务器通信。

NapCat：https://napcat.napneko.com/
go-cqhttp：https://docs.go-cqhttp.org/

配置 NapCat 的 HTTP 上报地址指向 qqrebot（默认 http://127.0.0.1:25580）。

第2步：部署 qqrebot（本仓库）

从 chatrebot1.0 release 下载并解压：

# 下载 release 源码
wget https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/archive/chatrebot1.0.tar.gz
tar xzf chatrebot1.0.tar.gz
cd chat_rebot-connect-with-onebot-standard-

# 如需安装 OpenClaw Bridge 插件，从 main 分支复制
wget https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/raw/branch/main/src/process.py
wget https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/raw/branch/main/config/openclawbridge/config.toml
mkdir -p plugins config/openclawbridge
mv process.py plugins/
mv config.toml config/openclawbridge/

配置 NapCat 地址（config/config.toml）：

[app]
list_port = 25580                  # 接收 NapCat 消息推送的端口
send_url = "http://127.0.0.1:25570"  # NapCat HTTP API 地址

[rebot]
id = ""

[plugins]
dir = ["plugins"]

启动（Linux）：

chmod +x run.sh
./run.sh

配置 systemd 服务（推荐）：

[Unit]
Description=QQ Robot
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/chat_rebot-connect-with-onebot-standard-
ExecStart=/path/to/chat_rebot-connect-with-onebot-standard-/run.sh
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

第3步：配置 OpenClaw Agent

让 agent 能够主动操作 QQ（发消息、管理群、查信息等）。

3a. 部署脚本到 agent 工作区

cp -r scripts/ /path/to/qq-agent/workspace/

3b. 部署 Skills 到 agent skills 目录

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/

3c. 替换占位符

编辑各脚本开头的配置变量，将占位符替换为实际值：

# 需替换的占位符：
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

3d. 验证

在 agent 工作区尝试执行单个脚本确认连通性：

cd /path/to/qq-agent/workspace/scripts
python3 qq_get_groups.py

常见问题 / 踩坑指南

1. systemd 下只有 stdin/stdout，没有持久化日志

本仓库设计为通过 systemd 托管，run.sh 中的 gunicorn 输出全部走 stdout/stderr。systemd 会自动捕获到 journald。

查看日志：

journalctl -u qqrebot --since "5 minutes ago" -f

如果发现日志回滚太短，在 service 中设置 StandardOutput=journal+console。

2. `app.py` 端口硬编码

app.py 的 __main__ 直接将端口写死在 port=25580，不走 config.toml。这意味着：

python3 app.py 直接运行 → 无视配置，始终占 25580
run.sh（gunicorn）→ 自动读取配置，正常

如果直接 python3 app.py 启动报 Address already in use，检查是否跟 gunicorn 实例抢端口。

3. ConfigManager 内部字典不自动刷新

当插件首次部署，config/插件名/config.toml 尚不存在时，ConfigManager.__init__ 会通过 build_config_dict() 扫描目录。此时文件不存在，内部 self.config 为空。

BasePlugin.config 属性的异常处理会触发 _ensure_config_exists() 创建文件，但 ConfigManager 的 self.config 不会被刷新，第二次 load_config("config") 仍然 KeyError。解决方法：_ensure_config_exists 创建文件后调用 self._config_manager.build_config_dict() 手动刷新。

4. python3-venv 缺失

纯净 Debian/Ubuntu 没有 python3-venv：

apt install python3.13-venv   # 替换 .13 为实际版本

否则 run.sh 创建虚拟环境会直接失败。

5. gunicorn / waitress 不在 requirements.txt 中

# requirements.txt 未包含，由启动脚本单独安装
# run.sh:  pip install gunicorn
# run.bat: pip install waitress

设计优势

解耦设计：插件与核心系统完全解耦
安全隔离：使用临时目录加载插件
版本兼容：内建依赖版本验证机制
灵活扩展：支持多个消息处理点
新旧兼容：支持传统钩子和现代OOP插件的共存

仓库地址：chat_rebot-connect-with-onebot-standard-

README.md Unescape Escape

OneBot Chatbot Framework

项目特点

内置插件

OpenClaw Bridge

QQ 操作脚本

Agent Skills

核心组件

消息处理流程 (process_message)

插件管理器 (PluginManager)