modified: README.md
new file: dependence.py new file: package.py new file: packup.bat new file: packup.sh new file: requirements.txt new file: scripts/__init__.py new file: scripts/file_store_api.py new file: src/__init__.py new file: src/config.toml new file: src/modules/__init__.py new file: src/modules/plugin_modules.py new file: src/modules/user_module.py new file: src/process.py new file: test.py
This commit is contained in:
JianFeeeee
256
README.md
256
README.md
@ -1,3 +1,255 @@
|
||||
# chat_rebot_plugen_support
|
||||
以下是针对您提供的SDK工具的开发者文档，包含使用说明、工作流程和最佳实践：
|
||||
|
||||
聊天机器人插件开发支持
|
||||
---
|
||||
|
||||
# 插件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/`
|
||||
|
||||
| 参数 | 说明 |
|
||||
| ---------------- | -------------------------------- |
|
||||
| `--no-deps` | 仅安装直接依赖（不含依赖的依赖） |
|
||||
| `--no-upgrade` | 禁用自动升级 |
|
||||
|
||||
**示例**：
|
||||
|
||||
```bash
|
||||
python dependence.py --no-deps
|
||||
```
|
||||
|
||||
### 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子目录）
|
||||
|
||||
### Q2:
|
||||
|
||||
## **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("typing")` |
|
||||
|
||||
#### **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]` |
|
||||
|
||||
注：在群聊消息中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内资源，避免解压
|
||||
|
||||
Reference in New Issue
Block a user