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

​
快速开始

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 检索。

​
常用导入

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

​
推荐模板

​
与 JavaScript 中间件的实际差异

下表按当前 plugin/scripts/middleware.py 和 plugin/scripts/middleware.js 复核：
目录里的所有 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 方法。
最后修改于 2026年6月3日