JavaScript 事件、媒体和文件

本页覆盖事件字段、sender.getMediaItems()、文件下载和群成员列表。处理用户上传文件时，优先用标准化 MediaItem，不要手动拼平台下载地址。

事件方法

方法	作用	参数	返回
`getPluginName()`	获取当前插件标题；无标题时返回插件名。	无	`Promise<string>`
`getPluginVersion()`	获取当前插件版本。	无	`Promise<string>`
`getEventType()`	获取当前事件类型。	无	`Promise<string>`
`setEventType(eventType)`	设置当前运行上下文的事件类型。	`eventType`：必填。	`Promise<boolean>`
`getEventData()`	获取当前事件数据。不存在时返回 `{}`。	无	`Promise<any>`
`setEventData(eventData)`	设置当前事件数据。	`eventData`：必填，任意 JSON-like 数据。	`Promise<boolean>`
`getMediaItems()`	获取当前事件或最近一次等待输入捕获到的媒体项。	无	`Promise<MediaItem[]>`

`getMediaItems()`

getMediaItems() 查找顺序：

last_input_media_items：最近一次 listen(...) / input(...) 捕获到的媒体。
media_items / mediaItems：当前运行上下文中的媒体数组。
event_data.media_items / event_data.mediaItems：当前事件数据中的媒体数组。
都不存在时返回 []。

返回数组中的每个对象会标准化为：

type

string

必填

媒体类型，例如 image、voice、video、file。只有同时具备 type 和 source 的媒体项会保留。

source

string

必填

媒体来源。可能是 URL、本地路径、平台文件 ID、临时资源 ID 或适配器文件标识。

name

string

文件名。运行时会从 name、filename、file_name 中选择。

mime_type

string

MIME 类型。运行时会从 mime_type 或 mimeType 中选择。

platform_payload

object

适配器原始文件信息。下载用户上传文件时，保留它能提高适配器解析成功率。

[
  {
    "type": "file",
    "source": "file_123",
    "name": "card_keys.csv",
    "mime_type": "text/csv",
    "platform_payload": {
      "file_id": "file_123",
      "group_id": "123456"
    }
  }
]

const items = await sender.getMediaItems()
const image = items.find((item) => item.type === 'image')
const file = items.find((item) => item.type === 'file')

if (image) {
  await sender.replyImage(image.source, { filename: image.name, mimeType: image.mime_type })
}

if (file) {
  const saved = await downloadAdapterFile(file, { path: 'uploads' })
  await sender.reply(`文件已保存到 ${saved.path}`)
}

不要丢弃 platform_payload 后再下载。某些适配器需要它来把平台文件 ID 解析成临时下载 URL。

`fileDownload(url, path?)`

把远程 URL、file://、base64://... 或 data:*;base64,... 保存到本地。

url

string

必填

文件来源。支持 http://、https://、file://、base64://... 和 data URI。

path

string

保存目录。不传时保存到运行下载根目录；相对路径会放到下载根目录下；绝对路径按原路径保存。相对路径不能跳出下载根目录。

const file = await fileDownload('https://example.com/report.csv', 'reports')
await sender.replyFile(file.path, { filename: file.file_name, mimeType: file.mime_type })

{
  "path": "/opt/autclaw/file/reports/report.csv",
  "file_path": "/opt/autclaw/file/reports/report.csv",
  "file_name": "report.csv",
  "mime_type": "text/csv",
  "file_size": 12345
}

`downloadAdapterFile(file, options?, timeout?)`

下载用户上传到 IM 平台的文件。优先把 sender.getMediaItems() 返回的整个 MediaItem 传进去。

file

MediaItem | object | string

必填

用户上传文件项。对象可包含 source、url、file_id、id、file、path 或 platform_payload。传字符串时会当作文件来源；只有普通 URL 时也可以直接使用 fileDownload(url)。

options.path

string

保存目录。规则同 fileDownload(..., path)。

options.fileName

string

指定保存文件名。也可写作 file_name、filename 或 name。

options.mimeType

string

指定 MIME 类型。也可写作 mime_type。

options.imType

string

可选 IM 类型。也可写作 imtype 或 im_type。不传时使用当前运行上下文。

options.account_id

string

可选账号 ID。也可写作 accountID 或 accountId。不传时使用当前运行上下文账号。

timeout

number

默认值:"30000"

请求超时时间，单位毫秒。也可以把第二个参数直接传成数字，例如 downloadAdapterFile(file, 60000)。

下载流程

如果 source 已经是 http://、https://、data:、base64:// 或 file://，运行时直接下载。
如果 source 是平台文件 ID 或其他不可直接下载标识，运行时调用适配器的 resolveFileURL。
下载成功后保存到运行文件目录，返回本地路径。

const items = await sender.getMediaItems()
const fileItem = items.find((item) => item.type === 'file')

if (fileItem) {
  const saved = await downloadAdapterFile(fileItem, {
    path: 'imports',
    fileName: fileItem.name || 'upload.bin',
    mimeType: fileItem.mime_type,
  })
  await sender.reply(`已保存：${saved.file_name}`)
}

{
  "ok": true,
  "action": "resolveFileURL",
  "url": "https://adapter.example/temp/file.csv",
  "path": "/opt/autclaw/file/imports/file.csv",
  "file_path": "/opt/autclaw/file/imports/file.csv",
  "file_name": "file.csv",
  "mime_type": "text/csv",
  "file_size": 2048
}

boolean

downloadAdapterFile(...) 成功时为 true。

action

string

如果先调用了适配器解析下载 URL，通常为 resolveFileURL；直接下载时可能为空。

url

string

实际下载地址或解析后的临时 URL。

path

string

保存后的本地路径。

file_path

string

与 path 相同。

file_name

string

保存后的文件名。

mime_type

string

MIME 类型。

file_size

number

文件大小，单位字节。

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

获取群成员列表。适配器必须支持 getGroupMemberList。

const result = await getGroupMemberList('123456', {
  imType: 'qq',
  account_id: 'bot_qq_ops',
  noCache: true,
})

for (const member of result.members) {
  console.log(member.user_id, member.display_name)
}

groupIDOrOptions

string | object

传字符串时表示群 ID。传对象时可包含 group_id、groupID、groupCode、group、chat_id、imType、account_id 等字段。不传群 ID 时会尝试使用当前群聊上下文。

options.imType

string

目标 IM 类型。也可写作 im_type。不传时使用当前上下文 IM；cron / fake 上下文必须传。

options.account_id

string

目标账号 ID。也可写作 accountID 或 accountId。不传时使用当前上下文账号或目标 IM 默认账号。

options.noCache

boolean

是否绕过适配器缓存。也可写作 no_cache。

options.raw

boolean

是否在每个成员对象里包含原始成员数据。也可写作 includeRaw 或 include_raw。

options.rawResult

boolean

是否在返回体的 raw / data 中包含适配器原始结果。也可写作 raw_result、includeRawResult。

timeout

number

默认值:"30000"

请求超时时间，单位毫秒。

{
  "ok": true,
  "im_type": "qq",
  "account_id": "bot_qq_ops",
  "group_id": "123456",
  "members": [
    {
      "group_id": "123456",
      "user_id": "10001",
      "nickname": "Alice",
      "card": "Alice A.",
      "display_name": "Alice A.",
      "role": "member",
      "join_time": 1710000000,
      "last_sent_time": 1710003600
    }
  ],
  "raw": {},
  "data": {}
}

boolean

获取成功时为 true。

im_type

string

实际请求的 IM 类型。

account_id

string

实际请求的账号 ID。未指定时可能为空。

group_id

string

实际请求的群 ID。

members

GroupMember[]

标准化成员数组。

raw

unknown

仅传 rawResult / raw_result / includeRawResult 时包含适配器原始结果。

JavaScript 事件、媒体和文件

事件方法

`getMediaItems()`

`fileDownload(url, path?)`

`downloadAdapterFile(file, options?, timeout?)`

下载流程

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

下一步

发送媒体

主动推送

​事件方法

​getMediaItems()

​fileDownload(url, path?)

​downloadAdapterFile(file, options?, timeout?)

​下载流程

​getGroupMemberList(groupIDOrOptions?, options?, timeout?)

​下一步

发送媒体

主动推送

事件方法

`getMediaItems()`

`fileDownload(url, path?)`

`downloadAdapterFile(file, options?, timeout?)`

下载流程

`getGroupMemberList(groupIDOrOptions?, options?, timeout?)`

下一步