> ## 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 JavaScript 插件参考
> 查看 autClaw JavaScript 插件 middleware.js 的入口、Sender 用法、消息回复、存储、路由和定时任务。
`plugin/scripts/middleware.js` 是 JavaScript 普通插件的 SDK。你用它创建 `Sender`，再读取当前运行上下文、回复消息、保存数据、等待输入、处理支付、下载用户上传文件、处理 HTTP 路由、主动推送和管理运行时定时任务。
新插件优先使用 `const { Sender, getSenderID } = require('./middleware.js')`。不要硬编码运行时凭据、端口或 autClaw 内部服务地址。
## 快速开始
```js theme={null}
//[author: your-name]
//[runtime: node@22.22.1]
//[title: Echo]
//[rule: echo (.+)]
const { Sender, getSenderID } = require('./middleware.js')
async function main() {
const sender = new Sender(getSenderID())
const text = await sender.param(1)
await sender.reply(text || '请输入内容')
}
main().catch((error) => {
console.error(error && error.stack ? error.stack : error)
})
```
## 按任务查阅
导入方式、`senderID`、返回包装、`SendReceipt`、`MediaItem` 和下载返回体。
读取用户和会话、匹配参数、回复文本/媒体、撤回、`replyMixed(...)`。
`listen(...)`、`input(...)`、`waitPay(exitcode, timeout, amount?)` 和金额匹配细节。
`getMediaItems()`、`fileDownload(...)`、`downloadAdapterFile(...)`、`getGroupMemberList(...)`。
默认存储、命名 bucket、HTTP router 请求和响应。
`push(...)` / `pushImage(...)` / `pushMixed(...)` 的目标、账号选择和返回值。
`importModule(...)`、`importJs(...)`、系统工具、`Cron`、群邀请/禁言/公告。
机器可读签名保存在 `cn/plugin-sdk/types/middleware-js.d.ts`，适合 IDE 和 AI 检索。
## 常用导入
```js theme={null}
const {
Sender,
Cron,
getSenderID,
bucketGet,
bucketSet,
fileDownload,
downloadAdapterFile,
getGroupMemberList,
importModule,
push,
pushImage,
pushMixed,
} = require('./middleware.js')
const sender = new Sender(getSenderID())
```
`middleware.js` 中的方法大多是异步方法，失败时会抛出 `Error`。在会发送网络请求、媒体或文件的流程里使用 `try/catch`，并把可执行的错误提示回复给用户。
## 推荐模板
```js theme={null}
//[author: your-name]
//[runtime: node@22.22.1]
//[title: Safe template]
//[rule: demo (.+)]
const { Sender, getSenderID } = require('./middleware.js')
async function main() {
const sender = new Sender(getSenderID())
const value = await sender.param(1)
if (!value) {
await sender.reply('请输入内容，例如：demo hello')
return
}
await sender.reply(`收到：${value}`)
}
main().catch((error) => {
console.error(error && error.stack ? error.stack : error)
})
```
## 开发技巧
* `sender.param(1)` 从 `1` 开始，不是 `0`。
* 主动推送多账号目标时，优先显式传 `account_id`，避免默认账号变更导致发错账号。
* 消息触发且目标 IM 与当前会话 IM 一致时，`push(...)` 默认使用当前会话账号；cron / fake 和跨 IM 推送默认使用目标 IM 默认账号。
* 下载用户上传文件时，使用 `sender.getMediaItems()` + `downloadAdapterFile(...)`，不要手动解析平台原始字段。
* `set(...)` / `bucketSet(...)` 保存字符串；对象请手动 `JSON.stringify(...)`。
* `listen(...)` / `input(...)` 超时返回空字符串，记得处理空值。
* `waitPay(..., amount)` 会记录并返回金额匹配结果；发货前检查 `amount_matched`。
* 路由插件返回对象用 `sender.response(data)`，返回纯文本可用 `sender.reply(text)`。