6.6 KiB
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 项目原来：
import "gitea.doicat.com/bot/napcat"
改成：
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 等占位/未实现动作）一律通过：
var out map[string]any
err := bot.Call(nil, "action_name", snowluma.H{"k": "v"}, &out)
// 或事件内：c.Call(nil, "action_name", snowluma.H{...}, &out)
五、替换结论
- 编译层：100% 兼容——改导入（加别名）即可，全部 103 个方法名都存在。
- 运行层：100/103 方法行为一致；2 个 Ark 方法已适配为 SnowLuma 标准名；1 个（
GetRobotUinRange）SnowLuma 未实现。 - 能力层：SnowLuma 比 NapCat 多出约 96 个动作（闪传/Ark/待办/相册/空间/系统表情/流式等）， 这些是 NapCat SDK 没有的增量能力，迁移后可按需使用。
因此：「直接替换包名」这个思路成立，且因为本包连公开 API 名都对齐了 napcat，
连「写一个中间适配层」都不需要，一行 import napcat "gitea.doicat.com/bot/snowluma" 即可。
唯一需要你留意的运行时差异就是 GetRobotUinRange（未实现）与两个 Ark 方法（已适配，无需你改）。