跳转到主要内容
plugin/scripts/middleware.py 是 Python 普通插件的 SDK。你通过它创建 Sender，再读取当前上下文、回复消息、保存数据、等待输入、处理支付、下载用户上传文件、处理 HTTP 路由、主动推送和管理运行时定时任务。
新插件优先使用 from middleware import Sender, getSenderID。不要在插件里硬编码凭据、端口或 autClaw 内部服务地址。

​
快速开始

#[author: your-name]
#[runtime: [email protected]]
#[title: Echo]
#[rule: echo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())
text = sender.param(1)
sender.reply(text or "请输入内容")
Python SDK 方法是同步调用。失败时会抛出 Exception，建议在发送网络请求、媒体或文件的流程里捕获异常，并回复可执行提示。

​
按任务查阅

上下文和基础类型

导入方式、senderID、返回包装、SendReceipt、MediaItem 和下载返回体。

Sender 消息能力

读取用户和会话、匹配参数、回复文本/媒体、撤回、replyMixed(...)。

等待输入和支付

listen(...)、input(...)、waitPay(exitcode, timeout, amount=None) 和金额匹配细节。

事件、媒体和文件

getMediaItems()、fileDownload(...)、downloadAdapterFile(...)、getGroupMemberList(...)。

存储和路由

默认存储、命名 bucket、HTTP router 请求和响应别名。

主动推送

push(...) / pushImage(...) / pushMixed(...) 的目标、账号选择和返回值。

工具、Cron 和群管理

import_module(...)、系统工具、Cron、群邀请/禁言/公告。

Python 签名速查

导航内的 .pyi 风格签名，方便 IDE 和 AI 通过 MCP 检索。

​
常用导入

from middleware import (
    Sender,
    Cron,
    getSenderID,
    bucketGet,
    bucketSet,
    fileDownload,
    downloadAdapterFile,
    getGroupMemberList,
    import_module,
    push,
    pushImage,
    pushMixed,
)

sender = Sender(getSenderID())
常用规则：
  • 使用 Sender 处理当前消息、当前路由请求或当前事件。
  • 使用顶层函数做全局操作，例如 bucketGet(...)、pushImage(...)、fileDownload(...)。
  • listen(...)、input(...) 和 waitPay(...) 的业务超时参数使用毫秒。
  • 对象写入 set(...) / bucketSet(...) 前，先手动 json.dumps(...)。

​
推荐模板

#[author: your-name]
#[runtime: [email protected]]
#[title: Safe template]
#[rule: demo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())

try:
    value = sender.param(1)
    if not value:
        sender.reply("请输入内容，例如：demo hello")
    else:
        sender.reply(f"收到：{value}")
except Exception as error:
    print(error)
    sender.reply("处理失败，请稍后重试或联系管理员。")

​
与 JavaScript 中间件的实际差异

下表按当前 plugin/scripts/middleware.py 和 plugin/scripts/middleware.js 复核：
差异点JavaScriptPython
调用方式大多返回 Promise，需要 await。同步返回，失败抛出 Exception。
导入方式const { Sender } = require('./middleware.js')from middleware import Sender
默认存储删除del(key)delete(key)；也有 del_ 别名，避免使用 Python 关键字 del。
依赖确保importModule(module, versionOrOptions?, manager?)import_module(module, package="", version="", manager="")；当前也保留 importModule 别名。
路由别名sender.getRouter() / getMethod() / getRouterData() 可用。当前同样可用；推荐正文档使用 getRouterPath()、getRouterMethod()、getRouterBody()。
getRouterData()返回 JSON 字符串。返回 JSON 字符串；需要对象时用 getRouterBody()。
Cron 构造new Cron()Cron() 或兼容旧参数 Cron(cronID=None)。
Cron 方法getCron(...)、delCron(...)。额外支持 getCronByID(...)、deleteCron(...)。
Python 专属别名无。download_adapter_file(...)、get_group_member_list(...)。
目录里的所有 Python 子页都已加入 docs.json 导航。Mintlify 默认只把导航页加入 MCP 搜索索引；这样 AI 检索会命中拆分后的准确页面。

Python 插件上下文和基础类型

在 Python 插件中导入 middleware.py，创建 Sender，并理解常见返回值。

Python Sender 消息能力

使用 Python Sender 读取用户和会话信息，回复文本、Markdown、媒体和 mixed 消息，并撤回消息。

Python 等待输入和支付

在 Python 插件中使用 listen、input 和 waitPay 等待用户输入、捕获媒体和处理支付金额匹配。

Python 事件、媒体和文件

在 Python 插件中读取事件数据、获取媒体项、下载用户上传文件，并获取群成员列表。

Python 插件存储和路由

在 Python 插件中使用默认存储、命名 bucket，并读取和响应 HTTP router 请求。

Python 插件主动推送

使用 Python push、pushImage 和 pushMixed 主动发送文本、媒体和 mixed 消息，并指定发送账号。

Python 工具、Cron 和群管理

在 Python 插件中使用 import_module、系统工具函数、Cron 定时任务和群管理方法。

Python middleware.py 签名速查

用 .pyi 风格签名快速检索 middleware.py 的公开函数、Sender 方法和 Cron 方法。
Last modified on June 3, 2026