ChannelMediaMetadata
public final class ChannelMediaMetadataio/agentscope/extensions/channel/common/ChannelMediaMetadata.java:37–153渠道 Media 元数据，把智能体接入外部消息渠道与企业平台。位于 io.agentscope.extensions.channel.common 包。核心成员包括 markerText、putIfPresent、KIND_IMAGE、KIND_AUDIO、KIND_VIDEO、KIND_FILE。
Metadata key contract for inbound media (image / audio / video / file) messages surfaced by channel inbound mappers.
Channel adapters deliberately do not decode provider media into content blocks: material
identifiers (media_id / image_key / file_key / downloadCode)
are not URLs and can only be exchanged for bytes through a token-authenticated download whose
artifacts are short-lived. Deciding whether and when to fetch, where to buffer, and how to
degrade is application policy. Mappers therefore surface a media event as a user Msg
whose text content is a neutral marker (#markerText(String, String)) and whose metadata
carries the keys defined here, so the application can observe the event, download the material
through its own path, or reply with guidance.
All values are strings. Keys absent on a given platform are omitted; readers must treat the metadata as a sparse map and never assume a key's presence.
字段摘要Field Summary
| 字段Field | 类型Type | 说明Description |
|---|---|---|
KIND_IMAGEstaticfinal | String | 种类图像字段。 Normalized media kind: image (photo / picture). |
KIND_AUDIOstaticfinal | String | 种类音频字段。 Normalized media kind: audio (voice message). |
KIND_VIDEOstaticfinal | String | 种类视频字段。 Normalized media kind: video, including video-bearing composite messages. |
KIND_FILEstaticfinal | String | 种类文件字段。 Normalized media kind: generic file attachment. |
KINDstaticfinal | String | 种类字段。 Normalized media kind — one of `image`, `audio`, `video`, `file`. |
PROVIDER_TYPEstaticfinal | String | 提供者类型字段。 Original provider type token, verbatim (WeCom `MsgType`, Feishu `
message_type`, DingTalk `msgtype`) — e.g. |
IDstaticfinal | String | 标识字段。 Primary provider material identifier (`MediaId` / `image_key` / `
file_key` / `downloadCode`), verbatim. |
SECONDARY_IDstaticfinal | String | SECONDARY 标识字段。 Secondary material identifier when the platform provides one (thumbnail / cover image /
picture-specific download code). |
URLstaticfinal | String | URL字段。 Directly fetchable URL when the platform provides one alongside the material id (WeCom
image `PicUrl`). |
FILE_NAMEstaticfinal | String | 文件名称字段。 File name, when the platform reports one. |
FORMATstaticfinal | String | 格式字段。 Container / format token (WeCom voice `Format`, DingTalk video `videoType`). |
DURATION_MSstaticfinal | String | 时长 MS字段。 Playback duration in milliseconds, as reported by the platform (Feishu and DingTalk
both document the field in milliseconds for audio and video messages). |
RECOGNITIONstaticfinal | String | RECOGNITION字段。 Platform speech-to-text result for audio messages, when the platform provides one. |
方法摘要Method Summary
| 方法Method | 说明Description |
|---|---|
public static String markerText(String kind, String fileName)static | 执行 `markerText` 方法。 Returns the neutral marker text used as the `Msg` text content of a mapped media
message: `"[image]"`, `"[audio]"`, `"[video]"`, or `
"[file: report.pdf]"` when a file name is available. |
public static void putIfPresent(Map<String, Object> metadata, String key, String value)static | 执行 `putIfPresent` 方法。 Puts `value` under `key` only when `value` is neither `null` nor
blank; a null/blank value is silently skipped. |
字段详情Field Detail
KIND_IMAGE
public static final String KIND_IMAGE种类图像字段。声明为 public static final String KIND_IMAGE。
Normalized media kind: image (photo / picture).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:44KIND_AUDIO
public static final String KIND_AUDIO种类音频字段。声明为 public static final String KIND_AUDIO。
Normalized media kind: audio (voice message).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:47KIND_VIDEO
public static final String KIND_VIDEO种类视频字段。声明为 public static final String KIND_VIDEO。
Normalized media kind: video, including video-bearing composite messages.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:50KIND_FILE
public static final String KIND_FILE种类文件字段。声明为 public static final String KIND_FILE。
Normalized media kind: generic file attachment.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:53KIND
public static final String KIND种类字段。声明为 public static final String KIND。
Normalized media kind — one of image, audio, video, file.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:56PROVIDER_TYPE
public static final String PROVIDER_TYPE提供者类型字段。声明为 public static final String PROVIDER_TYPE。
Original provider type token, verbatim (WeCom MsgType, Feishu message_type, DingTalk msgtype) — e.g.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:61ID
public static final String ID标识字段。声明为 public static final String ID。
Primary provider material identifier (MediaId / image_key / file_key / downloadCode), verbatim.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:65SECONDARY_ID
public static final String SECONDARY_IDSECONDARY 标识字段。声明为 public static final String SECONDARY_ID。
Secondary material identifier when the platform provides one (thumbnail / cover image / picture-specific download code).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:69URL
public static final String URLURL字段。声明为 public static final String URL。
Directly fetchable URL when the platform provides one alongside the material id (WeCom image PicUrl).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:73FILE_NAME
public static final String FILE_NAME文件名称字段。声明为 public static final String FILE_NAME。
File name, when the platform reports one.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:76FORMAT
public static final String FORMAT格式字段。声明为 public static final String FORMAT。
Container / format token (WeCom voice Format, DingTalk video videoType).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:79DURATION_MS
public static final String DURATION_MS时长 MS字段。声明为 public static final String DURATION_MS。
Playback duration in milliseconds, as reported by the platform (Feishu and DingTalk both document the field in milliseconds for audio and video messages).
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:83RECOGNITION
public static final String RECOGNITIONRECOGNITION字段。声明为 public static final String RECOGNITION。
Platform speech-to-text result for audio messages, when the platform provides one.
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:86方法详情Method Detail
markerText
public static String markerText(String kind, String fileName)执行 markerText 方法。
Returns the neutral marker text used as the Msg text content of a mapped media message: "[image]", "[audio]", "[video]", or "[file: report.pdf]" when a file name is available.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
kind | String | 种类（类型 `String`）。normalized media kind, as in `#KIND` |
fileName | String | 文件名称（类型 `String`）。optional file name; a sanitized copy is embedded when non-blank |
StringNullPointerException可能抛出 `NullPointerException`。if `kind` is `null`
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:105–115putIfPresent
public static void putIfPresent(Map<String, Object> metadata, String key, String value)执行 putIfPresent 方法。
Puts value under key only when value is neither null nor blank; a null/blank value is silently skipped.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
metadata | Map<String, Object> | 元数据（类型 `Map`）。The metadata. |
key | String | 键（类型 `String`）。The key. |
value | String | 值（类型 `String`）。The value. |
NullPointerException当if`metadata`或`key`是`null`时抛出 `NullPointerException`。if `metadata` or `key` is `null`
io/agentscope/extensions/channel/common/ChannelMediaMetadata.java:146–152