Crate nagisa

Expand description

Nagisa —— 统一在 OneBot v11 与 Milky 之上的 Rust 聊天机器人框架(门面 crate)。

这是面向使用者的唯一入口。bot 作者只依赖 nagisa(按需开 onebot / milky feature),写 use nagisa::prelude::*;,从不直接点名底层的 engine / types / macros / adapter 这些 crate:

use nagisa::prelude::*;

#[command("ping", mention_me)]
async fn ping(reply: Reply) -> HandlerResult {
    reply.text("pong").await?;
    Ok(())
}

#[tokio::main]
async fn main() -> Result<()> {
    // ctrl_c_shutdown() 起一个后台任务,收到 SIGINT/Ctrl-C 时取消 shutdown
    // token,让 bot 停机。
    let shutdown = ctrl_c_shutdown();
    App::new()
        .run_onebot(OneBotConfig::new("ws://127.0.0.1:8080/onebot/v11/ws"), shutdown)
        .await
}

§门面做了什么

把 engine(nagisa_core)、统一领域模型(nagisa_types)、宏 (nagisa_macros)在 crate 根重新导出,业务代码只点 nagisa::…。
精选一个 prelude —— use nagisa::prelude::*; 这一行 glob 导入,带进宏、 App 构建器、Bot 句柄、常用 FromContext 提取器、统一的 Segment / Message / Peer / Uin / Result / Error,以及门控/规则组合子。
协议适配器(OneBotConfig / MilkyConfig)挂在 onebot / milky feature 后面,日志工具箱(nagisa::log)挂在 log feature 后面,排版引擎 (nagisa::render —— 文档排版成图片)挂在 render feature 后面。
提供 App 构建器(app),把适配器、分发循环、自动登记的 handler 和一个 ShutdownToken 接到一起。

适配器作者用的管线(新协议适配器要实现的出站动作 trait)在 adapter; engine 内部的对象安全机制在 engine。业务代码两者都不点名。

Re-exports§

pub use app::App;
pub use nagisa_core::inventory;
pub use nagisa_types;
pub use nagisa_onebot;
pub use nagisa_milky;

Modules§

adapter: 适配器作者用的管线:新协议适配器要实现的出站动作 trait —— ActionInvoker (两协议通用的根)、OneBotActions(OneBot v11 加上揉进来的 NapCat / LLOneBot / Lagrange 厂商扩展)、MilkyActions,由 Actions marker 合在一起。业务代码从不点名这些 —— 它调 Bot 的固有方法,厂商专属动作走 bot.actions().<m>() —— 所以放在这个子模块而非精选的 crate 根。转自 nagisa_core::adapter。
app: App 构建器 —— 面向使用者地组装一个 router 并把它跑在某个协议适配器之上。
engine: Engine 内部管线:分发引擎据以搭建的对象安全 handler/rule/waiter 机制 (ErasedHandler、Check、Selector、WaiterBuilder、StateMap)。handler 作者从不直接点名这些;不进精选的 crate 根。转自 nagisa_core::engine。
prelude: bot 作者唯一需要的一行 glob 导入:use nagisa::prelude::*;。

Macros§

bail: bail!("...") / bail!(kind, "..."):从 handler 里提前返回一个 nagisa Error,对标 anyhow::bail!。见 Error::action。在 handler（或任何返回 nagisa Result 的函数）里提前失败：bail!("...") 即 return Err(Error::action(format!("...")))。
matcher: matcher! { lit(".."), <field>: <ty> = re("..")|union("a","b")|tail, sep="..", usage=".." }:对同一套 #[derive(Slots)] codegen 的函数式糖(同样的区块序列),用于写一个内联头部 matcher;求值为 Matcher。派生宏才是规范形式(它还顺带产出 Slots<T> 提取器类型)。 #[derive(Slots)] 的内联函数式糖:就地求值出一个 Matcher,免去显式声明结构体。
plugin: plugin!{ .. } 宏:把当前模块声明为一个插件。同模块(及更下层)的触发器按 module_path!() 关联到它,其分层开关继承插件的 default_enable/can_disable。见插件模型。声明「当前模块即一个插件」,登记一个 PluginSpec。

Structs§

AdminChange: 群管理员被设置/取消（Notice::AdminChange）。is_set = 升为管理员。（user == self_id 时即 bot 自身权限变更，可据此监听 bot 被设/免管理员。）
AiCharacter: AI 语音音色（get_ai_characters）。 ENDPOINT: LagrangeDev/Lagrange.Core Lagrange.OneBot/Core/Operation/Generic/GetAiCharacters.cs (https://github.com/LagrangeDev/Lagrange.Core); 亦见 NapCat/LLOneBot get_ai_characters。 Wire 元素：{character_id, character_name, preview_url?}。
AiCharacterGroup: 一组 AI 音色（按类型分组；get_ai_characters 的顶层数组元素）。 Wire 元素：{type, characters:[AiCharacter]}。
Announcement: 群公告。 OFFICIAL: https://github.com/SaltifyDev/milky/blob/main/protocol/src/ir/api/group.ts (get_group_announcements) ENDPOINT(OneBot): go-cqhttp _get_group_notice
ArgSpec: 一个命令参数的元数据(由 #[derive(Args)] 生成),供 help 自动生成用法说明。
ArgText: 命令剩余段的纯文本。无 ParsedCommand 时 Skip。
Args: 类型化参数提取器:async fn h(args: Args<MyArgs>)。仅在命令匹配后(ParsedCommand 存在)可用;解析失败 → Skip(=本 handler 不触发)。
At: 匹配链中首个 @ 提及，投影为被 @ 的 Uin。链中无 mention（或非消息事件）→ Skip。
Bot: 廉价可克隆的 bot 句柄（内部 Arc<dyn Actions>）。
BotOffline: 机器人账号掉线（Meta::BotOffline）。注意与传输层 Disconnect 区分。
BotOnline: 机器人账号上线（Meta::BotOnline）。reason 为上线原因文案（Lagrange 提供，OneBot 为 None）。
Business: VIP / 业务徽章条目（Lagrange get_stranger_info.Business[]）。 kind 为业务类型（wire type），level 等级，icon 徽章图标 URL， is_pro/is_year 为大会员/年费标识。缺字段 → None（绝不 panic）。 OFFICIAL: Lagrange.OneBot get_stranger_info（stranger.Business[] → Business）。
Captures: 正则捕获组（非正则匹配器时为空）。无 ParsedCommand 时 Skip。
Cd: 命令式 DI 冷却句柄：在 handler 体内对数据派生键做条件冷却。
Command: 命中的命令字面量（或正则整段匹配）。无 ParsedCommand 时 Skip。
CommandArg: 命令之后剩余的消息段（保留非文本段，如图片）。无 ParsedCommand 时 Skip。
Connect: 协议端（传输层）连接成功（Meta::Connect，框架事件源每次（重）连发出）。
Cooldown: 声明式冷却门控的构建体。new(secs) 默认 UserGlobal / max_exec=1 / 静默；以 .per_peer()/.per_trigger()/.max_exec(n)/.bypass(rule) 链式定制。
CooldownStore: 冷却存储：key → Window 的进程级共享表。App::new 注入共享态（与 WaiterStore 同机制），声明式 Cooldown 的 Check 与命令式 Cd 句柄共用它。
Ctx: 每事件上下文。廉价构造（Arc 克隆 + 一个空 memo map）。
DevMode: dev/诊断模式标记，由 App::debug() 插入 StateMap。
Disconnect: 协议端（传输层）断开（Meta::Disconnect）。reason 为底层错误文案（如有）。
EnabledOverrides: 所有覆盖的可序列化快照。per_peer 用扁平列表（绕开「map 键非字符串」的序列化难题）。
EnabledSet: 命令启用状态表。廉价共享（内部锁），运行期可改。
EssenceMessage: 精华消息。 OFFICIAL: https://github.com/SaltifyDev/milky/blob/main/protocol/src/ir/api/group.ts (get_group_essence_messages) ENDPOINT(OneBot): go-cqhttp get_essence_msg_list
EventPeer: 消息事件的对端寻址（仅消息事件，否则 Skip）。
FileFetch: get_file 取回的富媒体文件（NapCat / LLOneBot 共有）。 ENDPOINT: NapNeko/NapCatQQ packages/napcat-onebot/action/file/GetFile.ts (get_file)；亦见 LLOneBot/LLOneBot src/onebot11/action/types.ts get_file。 Wire 响应：{file?(本地路径), url?, file_size?(字符串), file_name?, base64?}。
FileMeta
FlightGuard: 一个 RAII 的 single-flight 令牌。存活期间把其作用域标记为在飞，故同作用域上第二次 Session::single_flight 返回 None。其 Drop 释放作用域，故被守护 handler 的每条退出路径——? 提前返回、正常路径、panic——都无需手写清理即可释放该槽。沿用 Waiter 的 drop-摘除纪律。
ForwardNode: 合并转发的单个节点（发送者 + 内容）。
FriendAdd: 新加了一个好友（Notice::FriendAdd）。
FriendCategory
FriendCategoryList: 带分类的好友列表（get_friends_with_category，NapCat/LLOneBot 共有）。 ENDPOINT: NapCat packages/napcat-onebot/action/user/GetFriendsWithCategory.ts (get_friends_with_category) (https://github.com/NapNeko/NapCatQQ). Wire: [{categoryId, categoryName, buddyList:[FriendInfo]}]。
FriendGroup: 好友分组（Lagrange get_friend_list 元素的 group 子对象）。与 FriendCategory 区别：category 来自 NapCat/LLOneBot 的 categoryId/categroyName 扁平字段或 Milky 的嵌套 entity；group 是 Lagrange 私有的 {group_id, group_name}。 OFFICIAL: Lagrange.OneBot get_friend_list（friend.group → FriendGroup）。
FriendInfo
FriendRef: 好友句柄。
FriendRequest: 好友请求（Request::Friend）。
FriendStatus: 用户在线/VIP 状态（Lagrange get_stranger_info.status）。 status/ext_status 为协议原始枚举值（不解释，原样透出）； battery_status 为电量百分比。缺字段 → None（绝不 panic）。 OFFICIAL: Lagrange.OneBot get_stranger_info（stranger.status → FriendStatus）。
GateReply: 否决时记录的回复：门控 Rule 本身是纯布尔，无法回话；某些门控（如休眠门控的「Zzz」、required-slot 用法提示）需要否决并且回话。故引入一个增量、可选的 Ctx-ext 通道：replying 包装的门控在否决时把要发的消息 stash 进 GateReply， router 在门控否决点（router.rs 的 gate-veto）取出并发送一次。纯布尔门控从不触碰它。
GroupCardChange: 某成员的群名片（昵称）变更（Notice::GroupCardChange）。（可在此对新名片做文本审核等处理。）
GroupFileList: 群文件列表(某文件夹下的文件 + 子文件夹)。
GroupFolder: 群文件夹。 OFFICIAL: https://github.com/SaltifyDev/milky/blob/main/protocol/src/ir/api/file.ts (get_group_files)
GroupInfo
GroupJoinRequest: 入群请求（Request::GroupJoin）。
GroupMessage: 群消息提取器：仅当事件是 Scene::Group 的消息时命中，否则 Skip。
GroupRef: 群句柄。
Heartbeat: 心跳（Meta::Heartbeat）。interval 为心跳间隔（ms），online/good 取自 status。
Honor: 群荣誉变更（龙王/群聊之火/快乐源泉）（Notice::Honor）。
HonorList: 群荣誉信息（get_group_honor_info）。 OFFICIAL: https://github.com/botuniverse/onebot-11/blob/master/api/public.md (get_group_honor_info)
HonorMember: 群荣誉成员条目（current_talkative / *_list 元素）。 OFFICIAL: https://github.com/botuniverse/onebot-11/blob/master/api/public.md (get_group_honor_info)
Image: 匹配链中首个图片段，投影为 Media（含 recv.url）。链中无图片（或非消息事件）→ Skip。
ImplInfo: ImplInfo:get_impl_info() 的返回 —— 已连接实现的身份(app 名/版本、QQ 协议信息)。定义在 engine crate。厂商判定走 bot.vendor()(OneBot 专用轴),不在此类型上。底层 bot 实现的名称与版本（协议端信息）。
ImplStatus: 协议端运行状态(OneBot get_status)。 OFFICIAL: https://github.com/botuniverse/onebot-11/blob/master/api/public.md (get_status)
KillSwitch: 进程级全局总闸（kill-switch）：置位后 switch 一律否决。App 写入共享态， switch() 叶子读取。与 EnabledSet 的按命令/按会话开关正交——这是「一键全关」的紧急闸。
LuckyKing: 群红包运气王结果（Notice::LuckyKing）。user = 发红包者，target = 运气王。
Matcher: 命令触发匹配器:一组正则(任一命中即整体命中)+ MentionMe / to_me 开关。
Media: 媒体段载体：发送时持 source，接收时持 recv。
MemberInfo
MemberJoin: 有成员入群（Notice::MemberIncrease）。
MemberLeave: 成员退群或被踢（Notice::MemberDecrease）。
MemberRef: 群成员句柄。
MessageEvent
MessageId: 不透明消息标识：打包两协议各自的定位信息。业务把它当不透明句柄，不对其做算术/比较。
MilkyAdapter: Milky 1.2 协议适配器。
MilkyConfig: Milky adapter 配置。
Msg: 流式构建一条消息：Msg::new().reply(id).at(u).text(" hi").build()。链式 setter 追加段， build()（或 Into<Message>）收尾成 Message。
Mute: 群里有成员被禁言（Notice::Mute）。
Next: 指向「链条剩余部分」的续延：其余中间件 + 末端 handler 循环。
Nudge: 戳一戳事件——统一 Notice::FriendNudge 与 Notice::GroupNudge，归一为 { peer, sender, receiver }。自过滤：sender == self_id 时跳过（防止 bot 对自己的戳一戳反应）。
OneBotAdapter: OneBot v11 适配器。同时实现 EventSource 与 ActionInvoker。
OneBotConfig: 适配器配置。端点 / 绑定完全落在 mode 里(如默认正向 WS 模式的 OneBotTransport::Forward { url })。
ParsedCommand: 解析后的命令:命令字面量 + 剩余段 + 剩余纯文本 + 正则捕获组。
Peer: 会话寻址：场景 + 对端 id（好友 QQ 号或群号）。
PluginMeta: 插件级元数据 + 总开关策略。全 &'static，运行期零开销。
PrivateMessage: 私聊消息提取器：仅当事件是 Scene::Friend/Scene::Temp 的消息时命中，否则 Skip。
ProfileLiker: 对我点赞的用户（get_profile_like，NapCat/LLOneBot 共有）。 ENDPOINT: NapCat packages/napcat-onebot/action/user/GetProfileLike.ts (get_profile_like) (https://github.com/NapNeko/NapCatQQ). Also: LLOneBot src/onebot11/action/types.ts.
RateLimit: 可当 Middleware 用的令牌桶限流器。
RawEvent
Ready: 框架就绪：已解析出可用账号（Meta::Ready，每次 run_* 仅一次）。self_id 为机器人账号， nickname 为其昵称（来自 get_login_info，未知时为空串）。
Recall: 一条消息被撤回（Notice::Recall）。同时携带原始 sender（作者）与撤回它的 operator，使 handler 能套自己的策略（如防撤回类插件可在 author != bot OR operator == bot 时触发）。刻意不做自过滤——在这里写死一套自策略会挡掉防撤回功能需要的「bot 自己的消息被管理员撤回」这一情形。
Rendezvous: 带 TTL 的 rendezvous 存储。廉价共享（内部 RwLock）；运行期可改。
RendezvousSnapshot: 可序列化快照。每条带其剩余寿命（毫秒，而非不可移植的绝对 Instant）； restore 把截止时刻重锚到 now + remaining。
Reply: 便捷回复句柄：携带消息事件的 Peer + 触发消息的 MessageId + Bot，向同一会话回话。仅消息事件可提取（否则 Skip）。
ReplyMsg: Reply::msg 返回的链式构建体：累积 Msg 段，终结于 send （向来源会话发送）或 quote（引用触发消息再发送）。字段方法照搬 Msg，故 reply.msg().at(u).text("hi") 与 Msg 同手感。
RequestToken: 不透明请求令牌——同意/拒绝时 round-trip；内部按协议打包不同字段。业务侧视为不透明（只在事件里收到、回传给 Bot::handle_request）；内部 RequestTokenInner 标 #[doc(hidden)]，仅供各 adapter crate 构造/解构。
ResourceRef: 接收侧资源引用：真实 URL 可能需懒加载（Milky 文件需另调 get_*_file_download_url）。
Rkey: 富媒体下载鉴权密钥（Lagrange/NapCat/LLOneBot get_rkey）。 ENDPOINT: LagrangeDev/Lagrange.Core Lagrange.OneBot/Core/Operation/Generic/GetRkey.cs Wire response: {"rkeys":[{"type":"private"|"group","rkey":"...","created_at":u32,"ttl":u64}]}
Router: handler 注册表 + app 共享状态 + 洋葱中间件。dispatch 先穿过中间件，末端按优先级（小者先）依次执行 handler。 handlers 始终保持按优先级稳定排序（注册时排序，分发时直接遍历）。
Rule: 可组合门控。Arc 包裹，克隆廉价；用 &/|/! 组合。
Scope: 仅消息的便捷预设（事件型作用域手写 .on(Kind).filter(..)）。
Sender: 发送者 QQ 号（仅消息事件，否则 Skip）。
ServiceBus: 服务间共享句柄袋：按类型（TypeId）存取 Arc<T>。廉价克隆（内部 Arc）。
Session: 一个会话句柄（FromContext 提取器）。捕获 bot、共享态、WaiterStore（取自共享态）、当前会话 peer（如有），以及当前嵌套深度（取自 Ctx 上的 WaiterDepth ext，默认 0）。
ShutdownToken: A token which can be used to signal a cancellation request to one or more tasks.
SleepState: 机器人的「休眠」标志：置位时机器人装睡。App/管理命令写入共享态， awake 叶子读取。
SlotSpec: 一个有序 slot 规格。Matcher::slots 把一组 SlotSpec 编成一条锚定正则, 命名槽成编号组,并保留名→组下标的映射。
Slots: 类型化命名 slot 提取器:async fn h(m: Slots<ViewBoard>)。 Args<T> 的字面孪生——同样仅在命令匹配后(ParsedCommand 存在)可用,解析失败经共享 on_parse_miss(prod usage 回贴 / dev WARN / 静默)后 Skip。
State: app 共享状态注入。从 Router::data 注册的状态表里取 Arc<T>；缺失 → Reject::Error。
Superusers: 配置的超级用户集合。App::superusers 写入，superuser() 规则读取。
Supervisor: 服务生命周期 Supervisor:注册一批服务,按依赖 DAG 编排 prepare→run→cleanup。
Tail: 贪婪尾槽的载荷类型。#[slot(tail)] q: Option<String> 直接用 String (无需 Tail 包装);Tail<Vec<Segment>> 把未解析的多模态尾原样交还(此实现下尾是纯文本, 故包成单个 Segment::Text——from_slots 仅见文本捕获)。
ToMe: 消息是否「to me」：私聊/Temp 场景，或群聊里首段是 @self mention。
TriggerId: 一个触发器的稳定标识（plugin_key + trigger_key）。用于 User/per-trigger 作用域的键。
TriggerMeta: 触发器级元数据（命令或事件）。key == "<plugin_key>.<id>"。
TriggerSpec: 一条 inventory 收集到的触发器：元数据 + 一个挂载 handler 的函数。
Uin: QQ 号。用 newtype 包住 i64，防止与普通整数混淆。serde 透明序列化为内层 i64。
UserInfo: 任意用户档案（含陌生人）。OneBot get_stranger_info / Milky get_user_profile 字段并集，缺的为 Option。
Waiter: 一个活跃 waiter。RAII：其 Drop 摘除 store 条目。经 mpsc 收投递事件（多轮、无需重注册）。
WaiterDepth: 嵌套深度标记，打在重建的 Ctx 上，使从中提取的 Session 比产出它的 waiter 深一层注册。
WaiterStore: 活跃 waiter 的共享注册表。用 Vec（而非单槽），故多个并发/嵌套作用域可共存。注入 app 共享态；router 在 run_handlers 的 waiter 检查层查询它。

Enums§

ActionErrorKind: 动作错误的粗分类（启发式，绝不按精确 retcode 值匹配——三实现 retcode 不一致）。
ArgError: 参数解析错误(由生成代码产出,提取器据此 Skip)。
ArgKind: 参数角色,决定 help 里的写法(旗标 [-a] / 选项 [-r 值] / 位置 <名> 等)。
ArgToken: 参数 token:文本词或一个非文本消息段。
Capability: 可探测的能力。适配器据实现/版本回答 Bot::supports。 #[non_exhaustive]：新增能力不破坏下游 match。
Category: 插件分类。
CdKey: 冷却存储的实际键：把各作用域投影到一个可哈希的判别式。
CooldownScope: 冷却键的作用域。UserGlobal 是默认（key 仅 sender.id，跨全部触发器）。
Error: Nagisa 统一错误。
Event
EventKind: 给 #[event(Kind)] 用的友好选择器。覆盖 nagisa 的事件面；若干 Notice/Meta 变体被合并（如两种 nudge 变体都 → Nudge）。
Flank: 一个 slot 相对字面量头的位置。Pre+字面量+Post 程序编成 (?:..)?lit(?:..)?,使字面量头两侧的可选修饰可表达。
Flow: 中间件的传播控制。Stop = 吞掉本事件、不再下传。
Forward: 合并转发：接收为引用 + 预览元信息；发送为内联节点。
HandlerOutcome: dispatch 视角的单次 handler 执行结果。
HonorKind: 群荣誉类型。 OFFICIAL: https://github.com/botuniverse/onebot-11/blob/master/event/notice.md (§群成员荣誉变更)
ImageSubType
Meta
MilkyMode: Milky 出站事件信道模式：Ws / Sse 二选一（nagisa 主动连协议端的 /event）。默认 Ws（向后兼容）。
Notice
Protocol: 后端协议。
RateLimitScope: RateLimit 以什么为桶的键。
ReactionKind
Reject: 提取失败的两种语义。
Replied: recv_parse / recv_text 一次追问的结局:拿到值、用户主动取消、或超时没等到。取代裸 Option——把「取消」与「超时」分开返回,调用侧据此分别回话 (取消该道别、超时该说没等到),二者不再都塌成 None(那曾让发「取消」错报成超时)。
Request
ResourceSource: 发送侧资源来源。适配器各自序列化为 base64:// / file:// / http(s)://。
Role
Scene: 会话场景。
Segment: 统一消息段。#[non_exhaustive]：加段不破坏下游。
Sex
SwitchKey: 开关键的类型化句柄，EnabledSet::set/reset 接受它。
TransportError: 传输层错误。适配器把 tungstenite/reqwest 等错误映射成这里的字符串变体；本 crate 不依赖它们。
TriggerKind: 触发器是靠命令匹配触发还是靠事件触发。
Vendor: OneBot 协议端的实现厂商，由 app_name 子串判定。
WaitFlow: recv_with / recv_with_sync 的闭包对每条投递事件返回的类型化裁决：闭包逐事件决定继续等、用某值收束、还是放弃。

Traits§

ArgsMeta: 由 #[derive(Args)] 生成,暴露各字段的 ArgSpec,供 help 自动生成用法。无字段或手写 ParseArgs 的类型可不实现(此时 help 退回命令级 usage 文本)。
Context: 给 Result<T, E: Display> 与 Option<T> 附上下文并归一到 nagisa Result。
EventSource: 入站事件源。OneBot = WS 读半边；Milky = /event（WS/SSE/webhook）。
FromArg: 把单个文本 token 解析成一个字段值。#[derive(Args)] 的文本字段类型需实现它。
FromContext: 从每事件上下文按类型提取一个值。Skip 即类型层过滤。
FromSlots: 由 #[derive(Slots)] 生成:产出命令头匹配器 + 从命名捕获投影出 Self。
FromTailText: 从尾捕获文本构造一个尾载荷。derive 对 #[slot(tail)] 字段调用它。
Handler: 类型化 handler。由宏为多元 async fn 生成 blanket impl；用户一般不手写。
MessageExt: Message 的便捷扩展，实现在 [Segment] 上（查询 + 变换）。
Middleware: 一个洋葱层。handle 内 next.run(ctx) 把控制权交给内层（其余中间件 + handler 循环）。
ParseArgs: 由 #[derive(Args)] 生成。把 token 流(+ 原始文本,供 #[arg(rest, raw)] 保真)解析为 Self。
Service: 受 Supervisor 管理的服务。三段式生命周期 + 依赖声明。
SlotValue: 在框架边界把单个捕获组文本解析成一个字段值。FromArg 的兄弟,复用 ArgError。

Functions§

add_outgoing_logger: 追加一个出站消息日志器。多次调用按顺序累积(多订阅:nagisa-log、业务落库可并存)。
awake: 仅当机器人清醒时放行；睡着时否决并经 reply-on-veto 通道回贴一次「Zzz」。静默变体见 awake_silent。
awake_silent: awake 的静默变体：睡着时纯静默否决（不记 GateReply、不回话）。
collect_into: 把每条收集到的 TriggerSpec 折叠到 router 上（顺序不稳定；先后由各触发器自身的 priority 决定，而非折叠顺序）。见上文 DCE 注意事项。
ctrl_c_shutdown: 起一个后台任务,收到 SIGINT(Ctrl-C)时取消返回的 ShutdownToken。
from_user: 限定发送者。
group_admin: 发送者是群主或管理员。
group_only: 仅群消息。
group_owner: 发送者是群主。
in_group: 限定群。
keyword: 文本中包含任一关键词。
private: 仅私聊（好友/临时）消息。
registered_plugins: 全部已声明的插件（inventory 的克隆）。顺序不稳定。
registered_triggers: plugin_key/key 已解析好的触发器（宏产出时它们为空）。
replying: 把一条门控 Rule 包成「否决即回话」：rule 求值为 false 时，若尚无 GateReply 落下（首写者胜），则 ctx.insert_ext_if_absent(GateReply(on_veto()))；随后照常返回 false（语义仍是否决/Skip，只是额外记下一条回复）。rule 通过则原样放行、不触碰通道。
run_dispatch: 长生命周期分发任务：select!（关停 / 收事件 / reap 完成任务）。 shutdown 触发或事件流关闭即退出接收循环，之后等待所有 in-flight handler 完成。
superuser: 发送者是配置的超级用户。
switch: 一个额外具名的跨插件开关（Function.require("name")）：读取 EnabledSet 的按会话覆盖（per-peer override，优先于全局），并叠加全局总闸 KillSwitch。
to_me: 消息是否「针对机器人」：私聊，或群里 @ 了机器人自身。

Type Aliases§

Extracted: 提取结果：成功得 Self，失败为 Reject（注意区别于 nagisa_types::Result）。
HandlerResult: handler 业务返回：Ok(()) 处理成功，Err(e) 处理出错。
Message: 业务统一消息体：一串 Segment。不内嵌 CQ 字符串（CQ 编解码只在 OneBot 适配器内部）。
NamedCaptures: 命名正则槽的别名:名 → Some(text)(命中) | None(缺省的可选槽)。即 ParsedCommand.named_captures 的类型,FromSlots::from_slots 据此投影。
Result: 库内统一 Result。

Attribute Macros§

async_trait
command: #[command(...)] 属性宏:声明式登记一个 matcher 门控的 handler,在 App::new 时经 inventory 自动收集。把一个 async fn 注册成消息命令触发器。
event: #[event(Kind, id="..")] 属性宏:声明式登记一个事件触发的 handler(与 #[command] 对等),在给定 EventKind 的事件上触发,受同一套分层插件开关门控。把一个 async fn 注册成事件触发器(与 #[command] 对等,但按 EventKind 派发)。

Derive Macros§

ArgEnum: #[derive(ArgEnum)]:为无字段枚举派生 FromArg(变体名转小写;支持 #[arg(rename="..")]/#[arg(alias="..")]),使其可作受限的 Args<T> 字段类型 (如 on|off)。为无字段变体的枚举生成 FromArg,按变体名小写匹配,用于命令里的 on|off、 原曲|哼唱 这类受限选项。
Args: #[derive(Args)]:为结构体派生 ParseArgs,使其可经 Args<T> 从命令参数里提取。派生宏与 Args<T> 提取器刻意共用 Args 这个名字(跨宏/类型命名空间), 同 serde 的 Serialize。为带具名字段的结构体生成 ParseArgs,配合 Args<T> 提取器在消息段流上解析命令参数。
Slots: #[derive(Slots)]:命令头 = 有序区块序列——结构体级 #[slots(lit("查看"), board, lit("榜"), scope)](lit("..") 固定块、裸标识符引用同名字段、sep=/usage= 键),字段各自 #[slot(re=..)] /#[slot(union=[..])]/#[slot(tail)] 定来源/类型(Option<T> 表可选块)。派生 FromSlots,可经 Slots<T> 提取。HEAD 侧,与持有 TAIL 的 #[derive(Args)] 对称;还自动生成 COMMAND_WORDS(字面 × 各必填 union 块的笛卡尔积)供 help 像字面命令一样枚举。为「命令头 + 命名类型化正则槽」结构体生成 FromSlots(matcher() 产出头匹配器, from_slots() 从命名捕获投影出字段)。是 #[derive(Args)] 的兄弟,复用其 option_inner 助手判断可选性。

Crate nagisa

Crate nagisa Copy item path

§门面做了什么

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate nagisa