243 lines
9.8 KiB
Markdown
243 lines
9.8 KiB
Markdown
# 插件SDK工具文档
|
||
|
||
## 1. 工具概览
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
sdk/
|
||
├── dist/ # 打包输出目录
|
||
├── src/ # 插件源码目录
|
||
│ ├── packages/ # 依赖库目录（自动生成）
|
||
│ ├── process.py # 插件主逻辑文件
|
||
│ └── config.toml # 插件配置文件
|
||
├── packup.bat # Windows打包脚本
|
||
├── packup.sh # Linux/macOS打包脚本
|
||
├── dependence.py # 依赖安装工具
|
||
├── package.py # 打包工具
|
||
└── requirements.txt # 依赖声明文件
|
||
```
|
||
|
||
## 2. 快速开始
|
||
|
||
### 2.1 开发流程
|
||
|
||
1. 在 `src/process.py`中开发插件逻辑
|
||
2. 添加依赖到 `requirements.txt`
|
||
3. 运行打包脚本：
|
||
```bash
|
||
# Windows
|
||
./packup.bat
|
||
|
||
# Linux/macOS
|
||
chmod +x packup.sh
|
||
./packup.sh
|
||
```
|
||
|
||
### 2.2 示例插件结构
|
||
|
||
`process.py` 最小示例：
|
||
|
||
```python
|
||
from src.modules.plugin_modules import BasePlugin
|
||
|
||
class MyPlugin(BasePlugin):
|
||
def after_save(self):
|
||
self.ctx.user.send_message("Hello World")
|
||
return "ok"
|
||
```
|
||
|
||
## 3. SDK工具详解
|
||
|
||
### 3.1 dependence.py
|
||
|
||
**功能**：安装依赖到 `src/packages/`
|
||
|
||
### 3.2 package.py
|
||
|
||
**打包规则**：
|
||
|
||
1. 自动检测继承 `BasePlugin`的类
|
||
2. 打包生成 `dist/{插件类名小写}.zip`
|
||
3. 包含文件：
|
||
- `process.py`
|
||
- `config.toml`
|
||
- `packages/`（依赖目录）
|
||
|
||
**错误处理**：
|
||
|
||
| 错误码 | 说明 | 解决方案 |
|
||
| ------ | -------------------- | --------------- |
|
||
| 1 | process.py未找到 | 检查src目录结构 |
|
||
| 2 | 未找到BasePlugin子类 | 检查类继承关系 |
|
||
|
||
### 3.3 打包脚本
|
||
|
||
**packup.bat/packup.sh** 执行顺序：
|
||
|
||
1. 安装依赖（dependence.py）
|
||
2. 打包插件（package.py）
|
||
3. 输出到dist目录
|
||
|
||
## 4. 测试与调试
|
||
|
||
### 4.1 测试流程
|
||
|
||
使用 `test.py`进行本地测试：
|
||
|
||
```python
|
||
from sdk.src.process import MyPlugin
|
||
from src.modules.plugin_modules import MessageContext
|
||
|
||
# 模拟上下文
|
||
ctx = MessageContext(uid="test", gid=None, raw_message="hello", id="bot")
|
||
|
||
# 测试插件
|
||
plugin = MyPlugin(ctx)
|
||
print(plugin.after_save()) # 应该输出"ok"
|
||
```
|
||
|
||
### 4.2 调试技巧
|
||
|
||
```python
|
||
# 在process.py中添加调试代码
|
||
import pdb; pdb.set_trace() # 添加断点
|
||
|
||
# 查看可用属性
|
||
print(dir(self.ctx.user))
|
||
```
|
||
|
||
## 5. 最佳实践
|
||
|
||
### 5.1 依赖管理
|
||
|
||
✅ **推荐做法**：
|
||
|
||
```text
|
||
# requirements.txt 示例
|
||
requests==2.31.0 # 固定版本
|
||
numpy>=1.21.0 # 最低版本限制
|
||
```
|
||
|
||
❌ **应避免**：
|
||
|
||
```text
|
||
pytorch # 无版本声明
|
||
```
|
||
|
||
### 5.2 配置建议
|
||
|
||
`config.toml`标准结构：
|
||
|
||
```toml
|
||
[plugin]
|
||
name = "my_plugin"
|
||
version = "1.0.0"
|
||
|
||
[settings]
|
||
timeout = 30
|
||
```
|
||
|
||
## 6. 常见问题
|
||
|
||
### Q1: 打包后插件不生效
|
||
|
||
- ✅ 检查类名是否继承 `BasePlugin`
|
||
- ✅ 确认ZIP内文件在根目录（不在src子目录）
|
||
|
||
## **7. `self.ctx` 核心对象方法/属性总表**
|
||
|
||
#### **1. 基础信息**
|
||
|
||
| 属性/方法 | 类型 | 说明 | 示例 |
|
||
| --------------- | ----------------- | -------------------------------------- | ------------------------------ |
|
||
| `raw_message` | `str` | 用户原始消息文本 | `ctx.raw_message` → "hello" |
|
||
| `response` | `Optional[str]` | 可设置的响应内容（设置后拦截后续处理） | `ctx.response = "ok"` |
|
||
| `rebot_id` | `str` | 当前机器人ID | `print(ctx.rebot_id)` |
|
||
| `_processed` | `bool` | 标记消息是否已被处理（自动管理） | `if ctx._processed: ...` |
|
||
|
||
#### **2. 用户相关 (`ctx.user`)**
|
||
|
||
| 属性/方法 | 类型 | 说明 | 示例 |
|
||
| --------------------------- | ----------------- | --------------------------------------------- | ------------------------------------------------- |
|
||
| `user.user_id` | `str` | 用户唯一ID | `uid = ctx.user.user_id` |
|
||
| `user.nickname` | `Optional[str]` | 用户昵称（自动从API获取） | `greet = f"Hi {ctx.user.nickname}"` |
|
||
| `user.messages` | `List[dict]` | 用户历史消息记录（需 `after_load`后才有值） | `last_msg = ctx.user.messages[-1]` |
|
||
| `user.send_message()` | `method` | **发送私聊消息** | `ctx.user.send_message("Hello")` |
|
||
| `user.set_input_status()` | `method` | 设置用户输入状态（如"typing"） | `ctx.user.set_input_status(1)（为用户正在输入)` |
|
||
| `user.send_file()` | `method` | 上传文件 | `ctx.user.set.send_file("/path",filename)` |
|
||
|
||
#### **3. 群组相关 (`ctx.group`)**
|
||
|
||
> *仅当消息来自群聊时可用*
|
||
>
|
||
> | 属性/方法 | 类型 | 说明 | 示例 |
|
||
> | ------------------------ | ----------------- | ------------------------------------- | ------------------------------------------------------ |
|
||
> | `group.group_id` | `str` | 群组唯一ID | `gid = ctx.group.group_id` |
|
||
> | `group.nickname` | `Optional[str]` | 群名称（自动从API获取） | `print(ctx.group.nickname)` |
|
||
> | `group.users` | `List[dict]` | 群成员列表 | `members = ctx.group.users` |
|
||
> | `group.current_user` | `User` | 当前发言用户（即 `ctx.user`的引用） | `sender = ctx.group.current_user` |
|
||
> | `group.send_message()` | `method` | **发送群消息** | `ctx.group.send_message("@all 通知")` |
|
||
> | `group.messages` | `List[dict]` | 群聊历史消息 | `last_msg = ctx.group.messages[-1]` |
|
||
> | `group.upload_file` | `method` | 上传群文件 | `ctx.group.upload_file("/path",filename,group_path)` |
|
||
|
||
注：在群聊消息中current_user中的message存储了用户在群里的近十条消息。
|
||
|
||
#### **4. 数据存储 (`ctx.chat_manager`)**
|
||
|
||
| 方法 | 参数 | 说明 | 示例 |
|
||
| --------------------------- | --------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
|
||
| `save_private_message()` | `user: User, role: str, content: str` | 保存私聊消息到数据库 | `ctx.chat_manager.save_private_message(ctx.user, "user", "hi")` |
|
||
| `save_group_message()` | `group: Group, role: str, content: str, sender_id: str` | 保存群消息 | `ctx.chat_manager.save_group_message(ctx.group, "user", "hi", ctx.user.user_id)` |
|
||
| `load_private_messages()` | `user: User` → `List[dict]` | 加载用户私聊历史 | `ctx.user.messages = ctx.chat_manager.load_private_messages(ctx.user)` |
|
||
| `load_group_messages()` | `group: Group` → `List[dict]` | 加载群聊历史 | `ctx.group.messages = ctx.chat_manager.load_group_messages(ctx.group)` |
|
||
|
||
#### **5. 插件配置 (`self.config`)**
|
||
|
||
| 方法/属性 | 说明 | 示例 |
|
||
| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
|
||
| `self.config` | **自动加载**的配置字典（来自 `config.toml`） | `timeout = self.config.get("timeout", 30)` |
|
||
| `self.save_config()` | 保存修改后的配置 | `self.save_config({"key": "value"})` |
|
||
| `self._get_plugin_resource()` | 从插件ZIP包内读取文件 | `data = self._get_plugin_resource("data.json")` |
|
||
|
||
---
|
||
|
||
#### **6. 调试工具**
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
| ------------------- | -------- | ------------------------------------------------------------- |
|
||
| `ctx.phase` | `str` | 当前处理阶段（`before_load`/`after_load`/`after_save`） |
|
||
| `ctx.intercepted` | `bool` | 是否已被其他插件拦截 |
|
||
|
||
### **典型使用场景**
|
||
|
||
#### 场景1：消息预处理
|
||
|
||
```python
|
||
def before_load(self):
|
||
if "admin" in ctx.raw_message:
|
||
if not self.check_admin(ctx.user.user_id):
|
||
ctx.response = "权限不足" # 拦截请求
|
||
return
|
||
```
|
||
|
||
#### 场景2：响应生成
|
||
|
||
```python
|
||
def after_save(self):
|
||
if "天气" in ctx.raw_message:
|
||
city = extract_city(ctx.raw_message) # 自定义解析逻辑
|
||
ctx.response = get_weather(city) # 返回天气信息
|
||
```
|
||
|
||
### **注意事项**
|
||
|
||
1. **`ctx.group` 可能为 `None`**：私聊消息时需判空
|
||
```python
|
||
if ctx.group: # 群聊专属逻辑
|
||
```
|
||
2. **配置热更新**：修改 `self.config` 后需手动调用 `save_config()`
|
||
3. **大文件处理**：通过 `_get_plugin_resource()` 读取ZIP内资源，避免解压
|
||
|
||
示例插件 转发消息到mc服务器[chatrebot_mcrcon_plug](https://jianfgit.xyz/jianf/chatrebot_mcrcon_plug) ，自动ai回复[chatrebot_aireply_plug](https://jianfgit.xyz/jianf/chatrebot_aireply_plug)
|