snowluma: SnowLuma (OneBot 11) Go SDK, drop-in compatible with napcat
This commit is contained in:
111
COMPARISON.md
Normal file
111
COMPARISON.md
Normal file
@ -0,0 +1,111 @@
|
||||
# napcat ↔ snowluma 接口差异对比
|
||||
|
||||
> 结论先行：**可以直接替换**。现有 napcat 机器人项目只需改一行导入（加别名），
|
||||
> 103 个 API 方法里 100 个零改动可用、2 个已在本包内做动作名适配、1 个 SnowLuma 未实现。
|
||||
|
||||
## 一、协议层：完全一致
|
||||
|
||||
| 维度 | napcat（NapCatQQ） | snowluma（SnowLuma） |
|
||||
| --- | --- | --- |
|
||||
| 协议 | OneBot v11 + NapCat 兼容 | OneBot v11 + NapCat 兼容 |
|
||||
| HTTP API | `POST /{action}`，`Authorization: Bearer` | 同 |
|
||||
| WebSocket | 正向/反向，echo 配对 | 同 |
|
||||
| HTTP 上报 | X-Signature (HMAC-SHA1) 快速操作 | 同 |
|
||||
| 应答信封 | `{status,retcode,data,echo,message,wording}` | 同 |
|
||||
| 事件 | message/message_sent/notice/request/meta_event | 同 |
|
||||
|
||||
因此两包的 Client/Context/Session/消息段/CQ 码/事件结构完全可互换——本包 `snowluma`
|
||||
就是按 napcat 的公开 API 逐一对齐移植的，方法名、签名、返回类型、`On*` 注册、消息段构造函数全部同名。
|
||||
|
||||
## 二、迁移方式
|
||||
|
||||
napcat 项目原来：
|
||||
|
||||
```go
|
||||
import "gitea.doicat.com/bot/napcat"
|
||||
```
|
||||
|
||||
改成：
|
||||
|
||||
```go
|
||||
import napcat "gitea.doicat.com/bot/snowluma"
|
||||
```
|
||||
|
||||
导入别名 `napcat` 覆盖包声明名 `snowluma`，因此代码里所有 `napcat.XXX` 引用保持不变，
|
||||
`napcat.New()`、`napcat.Text(...)`、`*napcat.Context`、`napcat.ErrNotConnected` 等照常编译。
|
||||
这正是你设想的「方法名写一样 + import rename」。
|
||||
|
||||
## 三、napcat 103 个方法 → SnowLuma 的映射
|
||||
|
||||
### 3.1 直接可用（100 个）
|
||||
|
||||
以下方法对应的 wire 动作名在 SnowLuma 中完全相同，零改动即可用（示例，非全量）：
|
||||
|
||||
消息收发 `SendPrivateMsg/SendGroupMsg/SendMsg/SendPrivateMsgCQ/SendGroupMsgCQ/DeleteMsg/GetMessage/GetForwardMsg/SendLike/Mark*AsRead/SetMsgEmojiLike`；
|
||||
合并转发 `SendGroupForwardMsg/SendPrivateForwardMsg/SendForwardMsg/Forward*SingleMsg`；
|
||||
历史 `GetFriendMsgHistory/GetGroupMsgHistory`；
|
||||
信息 `GetLoginInfo/GetStrangerInfo/GetFriendList/GetFriendsWithCategory/DeleteFriend/GetGroupInfo/GetGroupInfoEx/GetGroupList/GetGroupMemberInfo/GetGroupMemberList/GetGroupHonorInfo`；
|
||||
群管理 `SetGroupKick/SetGroupBan/SetGroupWholeBan/SetGroupAdmin/SetGroupCard/SetGroupName/SetGroupLeave/SetGroupSpecialTitle/SetGroupPortrait/SetGroupSign/SendGroupSign/GetGroupAtAllRemain/GetGroupShutList`；
|
||||
戳一戳/状态 `SendPoke/FriendPoke/GroupPoke/SetInputStatus/SetOnlineStatus/SetSelfLongNick/GetUserStatus/GetPacketStatus/GetProfileLike`；
|
||||
请求 `SetFriendAddRequest/SetGroupAddRequest`；
|
||||
文件 `UploadGroupFile/UploadPrivateFile/DeleteGroupFile/DeleteGroupFolder/CreateGroupFileFolder/GetGroupFileSystemInfo/GetGroupRootFiles/GetGroupFilesByFolder/GetGroupFileURL/DownloadFile/GetFile/CheckURLSafely/OCRImage`；
|
||||
媒体 `GetImage/GetRecord/CanSendImage/CanSendRecord/FetchCustomFace/FetchEmojiLike/GetAICharacters/SendGroupAIRecord/GetMiniAppArk/TranslateEn2Zh/GetRKey`；
|
||||
系统 `GetStatus/GetVersionInfo/CleanCache/SetRestart/GetCookies/GetCSRFToken/GetCredentials/GetOnlineClients/SetQQProfile/SetQQAvatar/GetModelShow/SetModelShow/GetRecentContact`；
|
||||
精华/公告/系统消息 `GetEssenceMsgList/SetEssenceMsg/DeleteEssenceMsg/SendGroupNotice/GetGroupNotice/DelGroupNotice/GetGroupSystemMsg`。
|
||||
|
||||
### 3.2 已做动作名适配（2 个）
|
||||
|
||||
napcat 里这两个动作用了 **NapCat 私有的大小写混合名**，SnowLuma 改用 NapCat 标准名。
|
||||
本包保持方法名不变，内部改发 SnowLuma 的标准动作名，因此调用方无感知：
|
||||
|
||||
| napcat 方法 | napcat 动作名 | SnowLuma 动作名（本包已适配） |
|
||||
| --- | --- | --- |
|
||||
| `ArkShareGroup(groupID)` | `ArkShareGroup` | `send_group_ark_share` |
|
||||
| `ArkSharePeer(userID)` | `ArkSharePeer` | `send_ark_share` |
|
||||
|
||||
### 3.3 SnowLuma 未实现（1 个）
|
||||
|
||||
| napcat 方法 | 动作名 | SnowLuma 状态 |
|
||||
| --- | --- | --- |
|
||||
| `GetRobotUinRange()` | `get_robot_uin_range` | 未实现（调用返回 retcode 错误） |
|
||||
|
||||
该方法是 NapCat 特有扩展（获取官方机器人号段），SnowLuma 动作注册表中不存在。
|
||||
方法签名仍保留（保证代码能编译），运行时才会报错——若你的机器人在用这个接口，需要去掉或改为等价方案。
|
||||
|
||||
## 四、SnowLuma 独有（napcat 没有）的能力
|
||||
|
||||
SnowLuma 动作注册表共 **200 个动作**，比 napcat 覆盖的 103 个多出约 96 个。
|
||||
本包在 `api_ext.go` 中为其中主要动作提供了类型化方法，其余可用 `Call` 裸调：
|
||||
|
||||
| 类别 | 动作数（约） | 本包封装示例 |
|
||||
| --- | --- | --- |
|
||||
| 闪传（flash） | 11 | `CreateFlashTask/GetFilesetInfo/ListFilesets/SendFlashMsg/GetFlashFileURL/...` |
|
||||
| Ark 卡片 | 6 | `SendGroupArkShare/SendArkShare/SharePeer/ShareGroupEx/SendTuwenArk/ClickInlineKeyboardButton` |
|
||||
| 群待办 | 4 | `GetGroupTodoList/SetGroupTodo/CompleteGroupTodo/CancelGroupTodo` |
|
||||
| 群分类标签 | 4 | `GetGroupTags/AddGroupTag/DeleteGroupTag/GetGroupAdminSettings` |
|
||||
| 群相册 | 9 | `GetGroupAlbumList/UploadImageToQunAlbum/DoGroupAlbumComment/...` |
|
||||
| QQ 空间 | 10 | `GetQzoneMsgList/SendQzoneMsg/LikeQzone/CommentQzone/SetQzoneBan/...` |
|
||||
| 系统表情 | 4 | `FetchSysFaces/FetchFaceEntity/SearchSysFaces/FetchSuperFaceID` |
|
||||
| 流式接口 | 6 | `UploadFileStream/DownloadFileStream/DownloadFileImageStream/...` |
|
||||
| 群管理扩展 | 10+ | `SetGroupKickMembers/SetGroupAddOption/SetGroupSearch/SetGroupMemberPermissions/...` |
|
||||
| 其他扩展 | 30+ | `SetFriendRemark/SetGroupRemark/SetGroupReaction/FetchPttText/GetGroupDetailInfo/TransGroupFile/BotExit/GetAIRecord/SendPacket/GetCollectionList/...` |
|
||||
|
||||
未收录到类型化方法的动作（如 `get_group_ignored_notifies`、`send_packet` 的细节参数、
|
||||
`create_collection` 等占位/未实现动作）一律通过：
|
||||
|
||||
```go
|
||||
var out map[string]any
|
||||
err := bot.Call(nil, "action_name", snowluma.H{"k": "v"}, &out)
|
||||
// 或事件内：c.Call(nil, "action_name", snowluma.H{...}, &out)
|
||||
```
|
||||
|
||||
## 五、替换结论
|
||||
|
||||
1. **编译层**：100% 兼容——改导入（加别名）即可，全部 103 个方法名都存在。
|
||||
2. **运行层**：100/103 方法行为一致；2 个 Ark 方法已适配为 SnowLuma 标准名；1 个（`GetRobotUinRange`）SnowLuma 未实现。
|
||||
3. **能力层**：SnowLuma 比 NapCat 多出约 96 个动作（闪传/Ark/待办/相册/空间/系统表情/流式等），
|
||||
这些是 NapCat SDK 没有的增量能力，迁移后可按需使用。
|
||||
|
||||
因此：**「直接替换包名」这个思路成立**，且因为本包连公开 API 名都对齐了 napcat，
|
||||
连「写一个中间适配层」都不需要，一行 `import napcat "gitea.doicat.com/bot/snowluma"` 即可。
|
||||
唯一需要你留意的运行时差异就是 `GetRobotUinRange`（未实现）与两个 Ark 方法（已适配，无需你改）。
|
||||
Reference in New Issue
Block a user