插件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. 运行打包脚本：

   # Windows
   ./packup.bat
   
   # Linux/macOS
   chmod +x packup.sh
   ./packup.sh
   

2.2 示例插件结构

process.py 最小示例：

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进行本地测试：

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 调试技巧

# 在process.py中添加调试代码
import pdb; pdb.set_trace()  # 添加断点

# 查看可用属性
print(dir(self.ctx.user))

5. 最佳实践

5.1 依赖管理

✅ 推荐做法：

# requirements.txt 示例
requests==2.31.0  # 固定版本
numpy>=1.21.0     # 最低版本限制

❌ 应避免：

pytorch          # 无版本声明

5.2 配置建议

config.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：消息预处理

def before_load(self):
    if "admin" in ctx.raw_message:
        if not self.check_admin(ctx.user.user_id):
            ctx.response = "权限不足"  # 拦截请求
            return

场景2：响应生成

def after_save(self):
    if "天气" in ctx.raw_message:
        city = extract_city(ctx.raw_message)  # 自定义解析逻辑
        ctx.response = get_weather(city)      # 返回天气信息

注意事项

1. ctx.group 可能为 None：私聊消息时需判空

   if ctx.group:  # 群聊专属逻辑
   

2. 配置热更新：修改 self.config 后需手动调用 save_config()
3. 大文件处理：通过 _get_plugin_resource() 读取ZIP内资源，避免解压

示例插件 转发消息到mc服务器chatrebot_mcrcon_plug ，自动ai回复chatrebot_aireply_plug