echo_bot/
echo_bot.rs

1//! 最小但覆盖面广的入门示例:bot 作者经 `nagisa::prelude::*` 接触到的公开 API。涵盖一个
2//! `command` + `mention_me` 命令、一个带插件元数据(`name` / `description`)的命令、一个普通的
3//! `GroupMessage` handler、一个 `State<T>` 共享状态 handler、带类型的 `#[derive(Args)]` 解析
4//! (文本位置参数 + 一个 `#[arg(at)]` 元素 + 一个 `-f` 标志),以及一个带可选 `#[arg(image)]`
5//! 元素的 `#[derive(ArgEnum)]` 选项。用
6//! `App::new().data(..).on(..).run_onebot(cfg, ctrl_c_shutdown())` 接起来。
7//!
8//! 运行(需要一个在线的 OneBot 端点):
9//!   cargo run --example echo_bot
10
11use nagisa::prelude::*;
12use std::sync::atomic::{AtomicU64, Ordering};
13
14// 1. 一个带 mention_me 的命令,把收到的文本回显回去。
15#[command("echo", mention_me)]
16async fn echo(reply: Reply, args: ArgText) -> HandlerResult {
17    reply.text(format!("echo: {}", args.0)).await?;
18    Ok(())
19}
20
21// 2. 一个携带插件元数据(name/description)的命令。
22#[command("ping", name = "ping", description = "health check")]
23async fn ping(reply: Reply) -> HandlerResult {
24    reply.text("pong").await?;
25    Ok(())
26}
27
28// 3. 只处理群消息的 handler(普通 `on`,靠提取器自我过滤)。
29async fn group_only(msg: GroupMessage, bot: Bot) -> HandlerResult {
30    let _ = (msg, bot);
31    Ok(())
32}
33
34// 4. 一个 State<T> 共享状态 handler。
35struct Counter {
36    hits: AtomicU64,
37}
38
39#[command("count")]
40async fn count(reply: Reply, state: State<Counter>) -> HandlerResult {
41    // `State<Counter>` deref 到 `Counter`,所以字段可直接访问。
42    let n = state.hits.fetch_add(1, Ordering::Relaxed) + 1;
43    reply.text(format!("count = {n}")).await?;
44    Ok(())
45}
46
47// 5. 在 segment 流上做带类型的 Args:有序位置参数 + 一个消息元素(@提及)+ 一个标志。
48//    `转账 @张三 100 -f` → target=张三, amount=100, force=true。必填的 `#[arg(at)]` 意味着
49//    只有出现 @ 时命令才触发。
50#[derive(Args)]
51struct Transfer {
52    #[arg(at)]
53    target: Uin, // 一个 @提及元素(必须是真的 @ 段;裸号/「@123」文本要用 #[arg(at_or_id)])
54    amount: u64, // 有序文本位置参数
55    #[arg(flag, short = 'f')]
56    force: bool, // -f / --force
57}
58
59#[command("转账", "transfer", mention_me)]
60async fn transfer(reply: Reply, args: Args<Transfer>) -> HandlerResult {
61    let Transfer { target, amount, force } = args.0;
62    reply.text(format!("transfer {amount} to {} (force={force})", target.0)).await?;
63    Ok(())
64}
65
66// 6. 一个经 `#[derive(ArgEnum)]` 的选项枚举,外加一个可选的图片元素。
67#[derive(ArgEnum, Debug)]
68enum Switch {
69    On,
70    Off,
71}
72
73#[derive(Args)]
74struct RepeatCfg {
75    mode: Switch, // on|off(大小写不敏感)
76    #[arg(image)]
77    sample: Option<Media>, // 可选图片;缺省则为 None
78}
79
80#[command("repeat", mention_me)]
81async fn repeat(reply: Reply, args: Args<RepeatCfg>) -> HandlerResult {
82    let RepeatCfg { mode, sample } = args.0;
83    reply.text(format!("repeat {mode:?}, has_image={}", sample.is_some())).await?;
84    Ok(())
85}
86
87#[tokio::main]
88async fn main() -> Result<()> {
89    let shutdown = ctrl_c_shutdown();
90    App::new()
91        .data(Counter { hits: AtomicU64::new(0) })
92        .on(group_only)
93        .run_onebot(OneBotConfig::new("ws://127.0.0.1:8080/onebot/v11/ws"), shutdown)
94        .await
95}
echo_bot/echo_bot.rs

echo_bot/
echo_bot.rs
