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

​
快速开始

//[author: your-name]
//[runtime: [email protected]]
//[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 和下载返回体。

Sender 消息能力

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

等待输入和支付

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

事件、媒体和文件

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

存储和路由

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

主动推送

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

工具、Cron 和群管理

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

TypeScript 声明

机器可读签名保存在 cn/plugin-sdk/types/middleware-js.d.ts，适合 IDE 和 AI 检索。

​
常用导入

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，并把可执行的错误提示回复给用户。

​
推荐模板

//[author: your-name]
//[runtime: [email protected]]
//[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)。

JavaScript 插件上下文和类型

理解 autClaw JavaScript 插件的 Sender 运行上下文、senderID、返回包装、SendReceipt 和媒体类型。

JavaScript Sender 消息能力

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

JavaScript 等待输入和支付

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

JavaScript 事件、媒体和文件

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

JavaScript 插件存储和路由

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

JavaScript 插件主动推送

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

JavaScript 工具、Cron 和群管理

在 JavaScript 插件中使用 importModule、importJs、系统工具函数、Cron 定时任务和群管理方法。
Last modified on June 3, 2026