qbot

使用 Golang 实现的 NapCat QQ 机器人框架，通过双向 HTTP 连接与 NapCat 通信。

example

NapCat 配置：

• NapCat HTTP 服务端，对应 qbot.HttpClient
• NapCat HTTP 客户端，对应 qbot.HttpServer

可指定任意端口，保证二者之间能通信即可。

下面是一个 echo 示例。

package main

import (
  "log"
  "strings"

  "github.com/awfufu/qbot"
)

func main() {
  receiver := qbot.HttpServer(":3002")
  sender := qbot.HttpClient("http://napcat:3000")

  for {
    select {
    case msg := <-receiver.OnMessage():
      if msg.ChatType != qbot.Group {
        continue // Not a group message
      }

      if len(msg.Array) > 0 && msg.Array[0].Type() == qbot.TextType {
        if after, ok := strings.CutPrefix(msg.Array[0].GetTextItem(), "/echo "); ok {
          sender.SendGroupMsg(msg.GroupID, after, msg.Array[1:])
        }
      }

    case err := <-receiver.Error():
      // Handle HTTP server error
      log.Printf("http server error: %v", err)
      receiver.Close()
      return
    }
  }
}

(you) > /echo helloworld
(bot) < helloworld

run

go mod init yourproject
# edit main.go
go get github.com/awfufu/qbot
go mod tidy
go run main.go

合并转发消息

SendGroupForward 和 SendPrivateForward 分别发送到群聊和私聊； SendForward(qbot.Group, groupID, block) 或 SendForward(qbot.Private, userID, block) 使用 NapCat 的统一 /send_forward_msg 接口。三个方法都返回 (messageID int32, forwardID string, err error)。

block := qbot.ForwardBlock{
    Title:   "聊天记录",
    News:    []qbot.News{{Text: "Alice: 你好"}, {Text: "Bob: [图片]"}},
    Summary: "查看聊天记录",
    Prompt:  "[聊天记录]",
    Timeout: 30 * time.Second,
    Content: []qbot.ForwardBlockItem{
        {
            Name:   "Alice",
            UserID: 123456,
            Content: []qbot.Segment{
                qbot.Text("你好"),
                qbot.Face(14),
                qbot.Image("https://example.com/image.png"),
            },
        },
        // 引用 NapCat 能找到的原消息，ID 是 message_id 的十进制字符串。
        {ID: "654321"},
    },
}

messageID, forwardID, err := sender.SendGroupForward(qbot.GroupID(123456789), block)
if err != nil {
    log.Printf("发送合并转发失败: %v", err)
    return
}
log.Printf("message_id=%d, forward_id=%s", messageID, forwardID)

示例需要导入 time。News 对应卡片中的多行预览；也可以继续使用原有的 Preview: "Alice: 你好\nBob: [图片]"，每个非空行会转换为一条预览。 同时设置时优先使用 News。不填标题、预览、摘要或提示时，使用 NapCat 的默认值。 Timeout 为零时沿用默认超时；指定后会以毫秒传给 NapCat，并为本次 HTTP 请求延长等待时间。

嵌套合并转发时，将内层 ForwardBlock 转为节点，保留它自己的标题和预览：

inner := qbot.ForwardBlock{
    Title: "内层聊天记录",
    Content: []qbot.ForwardBlockItem{
        {Name: "Alice", UserID: 123456, Content: []qbot.Segment{qbot.Text("内层消息")}},
    },
}
outer := qbot.ForwardBlock{
    Content: []qbot.ForwardBlockItem{
        {Name: "Bob", UserID: 654321, Content: []qbot.Segment{inner.Node("Bob", 654321)}},
    },
}
_, _, err = sender.SendGroupForward(qbot.GroupID(123456789), outer)

底层节点也可以用 qbot.Node("654321") 和 qbot.CustomNode("Alice", 123456, "你好", qbot.Face(14)) 构造。 同一层的节点内容可以是普通消息段，或全为嵌套节点；不要将两者混在一起。 ForwardBlockItem 还支持 Time、Source、News、Summary 和 Prompt 节点字段。 设置 ID 时，该节点只引用原消息，其余字段忽略。

要再次发送已有的合并转发，使用返回的资源 ID：

// forwardID 是 res_id/forward_id，不是普通消息的 message_id。
_, err = sender.SendGroupMsg(qbot.GroupID(123456789), qbot.Forward(forwardID))

响应只包含 res_id 时，它会作为 forwardID 返回；两个字段都缺失时返回空字符串。 HTTP 错误和 NapCat 的业务失败都会返回错误。业务错误可通过 errors.As(err, &apiErr) 提取为 *qbot.APIError，读取 Action、Status、 Retcode、Message 和 Wording。

接口文档：发送合并转发消息。