> ## Documentation Index
> Fetch the complete documentation index at: https://autclaw.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# autClaw Python 插件参考

> 查看 autClaw Python 插件 middleware.py 的导入、Sender、存储、路由、主动推送、Cron 和类型签名。

`plugin/scripts/middleware.py` 是 Python 普通插件的 SDK。你通过它创建 `Sender`，再读取当前上下文、回复消息、保存数据、等待输入、处理支付、下载用户上传文件、处理 HTTP 路由、主动推送和管理运行时定时任务。

<Note>
  新插件优先使用 `from middleware import Sender, getSenderID`。不要在插件里硬编码凭据、端口或 autClaw 内部服务地址。
</Note>

## 快速开始

```python theme={null}
#[author: your-name]
#[runtime: python@3.12]
#[title: Echo]
#[rule: echo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())
text = sender.param(1)
sender.reply(text or "请输入内容")
```

Python SDK 方法是同步调用。失败时会抛出 `Exception`，建议在发送网络请求、媒体或文件的流程里捕获异常，并回复可执行提示。

## 按任务查阅

<CardGroup cols={2}>
  <Card title="上下文和基础类型" icon="circle-dot" href="/cn/plugin-sdk/python/context">
    导入方式、`senderID`、返回包装、`SendReceipt`、`MediaItem` 和下载返回体。
  </Card>

  <Card title="Sender 消息能力" icon="message-circle" href="/cn/plugin-sdk/python/sender-messages">
    读取用户和会话、匹配参数、回复文本/媒体、撤回、`replyMixed(...)`。
  </Card>

  <Card title="等待输入和支付" icon="hourglass" href="/cn/plugin-sdk/python/wait-and-payment">
    `listen(...)`、`input(...)`、`waitPay(exitcode, timeout, amount=None)` 和金额匹配细节。
  </Card>

  <Card title="事件、媒体和文件" icon="file-down" href="/cn/plugin-sdk/python/media-files">
    `getMediaItems()`、`fileDownload(...)`、`downloadAdapterFile(...)`、`getGroupMemberList(...)`。
  </Card>

  <Card title="存储和路由" icon="database" href="/cn/plugin-sdk/python/storage-and-routes">
    默认存储、命名 bucket、HTTP router 请求和响应别名。
  </Card>

  <Card title="主动推送" icon="send" href="/cn/plugin-sdk/python/push">
    `push(...)` / `pushImage(...)` / `pushMixed(...)` 的目标、账号选择和返回值。
  </Card>

  <Card title="工具、Cron 和群管理" icon="wrench" href="/cn/plugin-sdk/python/tools-cron-group">
    `import_module(...)`、系统工具、`Cron`、群邀请/禁言/公告。
  </Card>

  <Card title="Python 签名速查" icon="file-code" href="/cn/plugin-sdk/python/signatures">
    导航内的 `.pyi` 风格签名，方便 IDE 和 AI 通过 MCP 检索。
  </Card>
</CardGroup>

## 常用导入

```python theme={null}
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(...)`。

## 推荐模板

```python theme={null}
#[author: your-name]
#[runtime: python@3.12]
#[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` 复核：

| 差异点               | JavaScript                                                   | Python                                                                               |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| 调用方式              | 大多返回 `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(...)`。                           |

<Tip>
  目录里的所有 Python 子页都已加入 `docs.json` 导航。Mintlify 默认只把导航页加入 MCP 搜索索引；这样 AI 检索会命中拆分后的准确页面。
</Tip>