Enum Segment 

#[non_exhaustive]
pub enum Segment {
    Text(String),
    Mention {
        user: Uin,
        name: Option<String>,
    },
    MentionAll,
    Face {
        id: String,
        large: bool,
        result_id: Option<String>,
        chain_count: Option<i32>,
        sub_type: Option<i32>,
    },
    Reply {
        id: MessageId,
        sender: Option<Uin>,
        time: Option<i64>,
        quoted: Vec<Segment>,
    },
    Image {
        res: Media,
        sub_type: ImageSubType,
        hints: MediaSendHints,
    },
    Record {
        res: Media,
        magic: Option<i32>,
        hints: MediaSendHints,
    },
    Video {
        res: Media,
        hints: MediaSendHints,
        thumb: Option<ResourceSource>,
    },
    File {
        id: String,
        name: String,
        size: u64,
        hash: Option<String>,
        url: Option<String>,
    },
    Forward(Forward),
    MarketFace {
        package_id: i32,
        emoji_id: String,
        key: String,
        summary: Option<String>,
        url: Option<String>,
    },
    LightApp {
        app_name: Option<String>,
        payload: String,
    },
    Xml {
        service_id: Option<i32>,
        payload: String,
    },
    Poke {
        kind: i32,
        id: i32,
        strength: Option<i32>,
        name: Option<String>,
    },
    Contact {
        kind: ContactKind,
        id: Uin,
    },
    Location {
        lat: f64,
        lon: f64,
        title: Option<String>,
        content: Option<String>,
    },
    Music(MusicShare),
    Share {
        url: String,
        title: String,
        content: Option<String>,
        image: Option<String>,
    },
    Rps {
        result: Option<i32>,
    },
    Dice {
        result: Option<i32>,
    },
    Shake,
    Anonymous {
        ignore: Option<bool>,
    },
    Keyboard {
        content: Value,
    },
    Markdown {
        content: String,
    },
    LongMsg {
        id: String,
    },
    FlashFile {
        title: Option<String>,
        file_set_id: String,
        scene_type: i32,
    },
    MiniApp {
        payload: String,
    },
    OnlineFile {
        msg_id: String,
        element_id: String,
        file_name: String,
        file_size: String,
        is_dir: bool,
    },
    FlashTransfer {
        file_set_id: String,
    },
    Raw {
        protocol: Protocol,
        kind: String,
        data: Map<String, Value>,
    },
}

统一消息段。#[non_exhaustive]：加段不破坏下游。

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Text(String)

Mention

Fields

user: Uin

name: Option<String>

MentionAll

Face

QQ 表情段。id/large 为 OneBot v11 标准字段。 result_id/chain_count 为 NapCat「超级表情」(super-face) 扩展（连发动画表情， 仅 NapCat 收发；其余厂商缺省 → None）。sub_type 为 LLOneBot 的 FaceType （表情子类型，如 0=普通 / 1=超级 / 2=原创，仅 LLOneBot 透传 → 其余 None）。 来源已核对（2026-06-04）：NapCat OB11MessageFace data resultId(string)/chainCount(number)； LLOneBot OB11MessageFace data sub_type(number, FaceType)。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageFaceSchema)

• LLOneBot/LLOneBot src/onebot11/types.ts (OB11MessageFace)。

Fields

id: String

large: bool

result_id: Option<String>

chain_count: Option<i32>

sub_type: Option<i32>

Reply

Fields

id: MessageId

sender: Option<Uin>

time: Option<i64>

quoted: Vec<Segment>

Image

Fields

res: Media

sub_type: ImageSubType

hints: MediaSendHints

Record

Fields

res: Media

magic: Option<i32>

hints: MediaSendHints

Video

视频段。thumb（封面缩略图）为跨协议非对称（固有限制）字段：标准 OneBot v11 的 video 段没有 thumb wire 字段，故纯 v11 端 encode 时必然丢弃 thumb；nagisa 仍会 在 encode 时写出 thumb 键（LLOneBot/go-cqhttp 扩展接受它，标准端忽略多发键，无害—— 见 nagisa-onebot/src/encode.rs），但标准 v11 解码侧 thumb 恒为 None。Milky 有 对称的 thumb_uri wire 字段，能完整收发。即：thumb 在标准 OneBot v11 下是只写不读 的有损字段，这是 v11 wire 的天然缺口，非编解码缺陷。

Fields

res: Media

hints: MediaSendHints

thumb: Option<ResourceSource>

File

Fields

id: String

name: String

size: u64

hash: Option<String>

url: Option<String>

Forward(Forward)

MarketFace

Fields

package_id: i32

emoji_id: String

key: String

summary: Option<String>

url: Option<String>

LightApp

Fields

app_name: Option<String>

payload: String

Xml

XML 卡片（OneBot xml / Milky 入站 xml）。与 LightApp 对称，避免 json 有 类型而 xml 退化成 Raw 的不对称。

Fields

service_id: Option<i32>

payload: String

Poke

戳一戳消息段（OneBot）。注意区别于 send_nudge 动作与 nudge 通知。

Fields

kind: i32

id: i32

strength: Option<i32>

name: Option<String>

Contact

推荐好友/群名片。

Fields

kind: ContactKind

id: Uin

Location

位置分享。

Fields

lat: f64

lon: f64

title: Option<String>

content: Option<String>

Music(MusicShare)

音乐分享（发送向；接收通常表现为 LightApp）。

Share

链接分享卡片（OneBot share）。url/title 必填，content/image 可选。 与已建模的 LightApp/Xml/Music 卡片并列；Milky 发送侧无对应段（降级跳过）。

Fields

url: String

title: String

content: Option<String>

image: Option<String>

Rps

猜拳魔法表情（OneBot rps，收发皆有）。标准 v11 为空 data；NapCat 额外带 result（1=布 / 2=剪刀 / 3=石头，随机数已定）→ result 保留（缺省 → None）。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageRPS data result)

Fields

result: Option<i32>

Dice

掷骰子魔法表情（OneBot dice，收发皆有）。标准 v11 为空 data；NapCat 额外带 result（1–6 点数）→ result 保留（缺省 → None）。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageDice data result)

Fields

result: Option<i32>

Shake

窗口抖动 / 戳一戳快捷（OneBot shake，空 data，仅发送）。

Anonymous

匿名发送（OneBot anonymous，仅发送）。ignore=Some(true) 表示无法匿名时 继续以普通身份发送；None = 不带该字段。

Fields

ignore: Option<bool>

Keyboard

QQ-Bot 内联键盘（Lagrange keyboard 段）。content 为 KeyboardData JSON 对象（按钮行/列）。Milky 无对应段（出站降级跳过）。 来源已核对（2026-06-04）：type="keyboard"、data 字段 content（KeyboardData JSON）。 ENDPOINT: LagrangeDev/Lagrange.Core Lagrange.OneBot/Message/Entity/KeyboardSegment.cs

Fields

content: Value

Markdown

Markdown 卡片（Lagrange markdown 段）。content 为 Markdown 文本字符串。 Milky 无对应段（出站降级跳过）。 来源已核对（2026-06-04）：type="markdown"、data 字段 content（string）。 ENDPOINT: LagrangeDev/Lagrange.Core Lagrange.OneBot/Message/Entity/MarkdownSegment.cs

Fields

content: String

LongMsg

长消息引用（Lagrange longmsg 段，主要入站）。id 为长消息 res_id。 Milky 无对应段（出站降级跳过）。 来源已核对（2026-06-04）：type="longmsg"、data 字段 id（string，非 res_id）。 ENDPOINT: LagrangeDev/Lagrange.Core Lagrange.OneBot/Message/Entity/LongMsgSegment.cs

Fields

id: String

FlashFile

QQ 闪传卡片（LLOneBot 私有 flash_file 段）。入站由 LLOneBot 解析「闪传」 markdown 卡片得到；出站可据此重建段。title 在 wire 上偶有缺省（标题属性可能 取不到），故为 Option（缺失 → None，保持 decode 无误）。 来源已核对（2026-06-04）：type="flash_file"、data 字段 title(string,可缺)/file_set_id(string)/scene_type(number)。 ENDPOINT: LLOneBot/LLOneBot src/onebot11/types.ts (OB11MessageFlashFile)

• src/onebot11/transform/message/incoming.ts。

Fields

title: Option<String>

file_set_id: String

scene_type: i32

MiniApp

小程序卡片（NapCat 私有 miniapp 段）。payload 为小程序的 JSON 字符串 （NapCat data 字段 data，原样透传，便于手工构建/转发）。与 LightApp/Xml 并列。 来源已核对（2026-06-04）：type="miniapp"、data 字段 data（string，小程序 JSON）。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageMiniAppSchema)

Fields

payload: String

OnlineFile

在线文件/文件夹卡片（NapCat 私有 onlinefile 段）。 来源已核对（2026-06-04）：type="onlinefile"、data 字段 msgId(string)/elementId(string)/fileName(string)/fileSize(string)/isDir(bool)。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageOnlineFileSchema)

Fields

msg_id: String

element_id: String

file_name: String

file_size: String

is_dir: bool

FlashTransfer

QQ 闪传卡片（NapCat 私有 flashtransfer 段）。file_set_id 为闪传文件集 id。 与 LLOneBot 的 FlashFile 同属闪传但 wire 名/字段不同，故各自建模。 来源已核对（2026-06-04）：type="flashtransfer"、data 字段 fileSetId（string）。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/types/message.ts (OB11MessageFlashTransferSchema)

Fields

file_set_id: String

Raw

逃生口：协议私有/未知段。adapter 的 decode 必须把未知段塞进来，绝不丢弃。

Fields

protocol: Protocol

kind: String

data: Map<String, Value>

Implementations

impl Segment

pub fn text(s: impl Into<String>) -> Segment

Examples found in repository

examples/event_plugin.rs (line 27)

async fn welcome(j: MemberJoin, bot: Bot) -> HandlerResult {
    bot.send(&Peer::group(j.group.0), &[Segment::at(j.user), Segment::text(" 欢迎入群！")]).await?;
    Ok(())
}

// 有人戳一戳 bot 时触发。`Nudge` 把好友/群的戳统一成 `{ peer, sender, receiver }`,并自我
// 过滤:bot 自己发的戳永远到不了这里,所以回复不会成环。
#[event(Nudge, id = "petpet")]
async fn petpet(n: Nudge, bot: Bot) -> HandlerResult {
    bot.send(&n.peer, &[Segment::text("戳回去！")]).await?;
    Ok(())
}

pub fn at(user: impl Into<Uin>) -> Segment

Examples found in repository

examples/event_plugin.rs (line 27)

async fn welcome(j: MemberJoin, bot: Bot) -> HandlerResult {
    bot.send(&Peer::group(j.group.0), &[Segment::at(j.user), Segment::text(" 欢迎入群！")]).await?;
    Ok(())
}

pub fn at_all() -> Segment

pub fn face(id: impl Into<String>) -> Segment

pub fn image_bytes(b: impl Into<Bytes>) -> Segment

pub fn image_url(u: impl Into<String>) -> Segment

pub fn image_path(p: impl Into<PathBuf>) -> Segment

本地文件图片（ResourceSource::Path，发送时由 adapter 读取/编码）。 与 image_bytes/image_url 三态对齐。

pub fn reply(id: MessageId) -> Segment

pub fn xml(payload: impl Into<String>) -> Segment

pub fn poke(kind: i32, id: i32) -> Segment

pub fn location(lat: f64, lon: f64) -> Segment

pub fn music(platform: impl Into<String>, id: impl Into<String>) -> Segment

pub fn share(url: impl Into<String>, title: impl Into<String>) -> Segment

pub fn anonymous(ignore: bool) -> Segment

pub fn image_url_with_summary( u: impl Into<String>, summary: impl Into<String>, ) -> Segment

带 summary(替代文本)的图片。Milky 出站 image.summary / OneBot image summary。

pub fn video_url(u: impl Into<String>) -> Segment

视频 URL 段（无缩略图）。

pub fn as_text(&self) -> Option<&str>

若是文本段返回其内容。

Examples found in repository

examples/word_guess.rs (line 28)

async fn start(reply: Reply, ep: EventPeer, session: Session) -> HandlerResult {
    let group = ep.0;
    let answer = "答案";
    let waiter = session.waiter().scope(Scope::peer(group)).build();
    reply.text("开始猜词,在群里直接发答案吧(发\"取消\"结束)").await?;
    loop {
        match waiter.recv::<GroupMessage>(Duration::from_secs(60)).await {
            Some(m) => {
                let text = m.0.content.first().and_then(|s| s.as_text()).unwrap_or("");
                if text == "取消" {
                    reply.text("已结束").await?;
                    break;
                } else if text == answer {
                    // 链式构建器对标 `Msg`:先 @ 赢家,再道贺。
                    reply.msg().at(m.0.sender).text(" 答对了!").send().await?;
                    break;
                } else {
                    reply.text("再猜猜").await?;
                }
            }
            None => {
                reply.text(format!("超时,答案是 {answer}")).await?;
                break;
            }
        }
    }
    Ok(())
}

pub fn forward(nodes: Vec<ForwardNode>) -> Segment

合并转发段的便捷入口：Segment::forward(nodes) ≡ Segment::Forward(Forward::nodes(nodes))。需要标题/卡片预览时用 Forward::nodes + 链式 setter，再自行 Segment::Forward(..)。

Trait Implementations

impl Clone for Segment

fn clone(&self) -> Segment

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Segment

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.