# 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 方法（已适配，无需你改）。