Losita/mai-bot
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: import private baseline from gitea state

Browse Source
This commit is contained in:
Losita
2026-05-11 19:24:06 +08:00
parent 161fc42c52
commit 1ba863d135
111 changed files with 10873 additions and 7347 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
plugin-templates/MaiBot-Napcat-Adapter/docs/README.md Normal file
View File

@@ -0,0 +1,90 @@
# MaiBot NapCat Adapter API 文档
当前统计：
- 公开 API 总数：`164`
- 强类型封装 API：`24`
- 透传 NapCat action API：`140`
- 对照到 NapCat 官方文档的底层 action：`162 / 162`
## 文档索引
- [强类型封装 API](./typed-api.md)
- [System 透传 API](./system-api.md)
- [Account 透传 API](./account-api.md)
- [Group 透传 API](./group-api.md)
- [Message 透传 API](./message-api.md)
- [File 透传 API](./file-api.md)
- [核验与兼容性说明](./verification.md)
## 先看调用方式
### 强类型封装 API
这类 API 直接展开参数，不要再套一层 `params`。
```python
response = await self.ctx.api.call(
"adapter.napcat.group.get_group_member_info",
group_id=123456789,
user_id=987654321,
no_cache=True,
)
```
### 透传 NapCat action API
这类 API 统一只收 `params` 对象。
```python
response = await self.ctx.api.call(
"adapter.napcat.group.set_group_admin",
params={
"group_id": 123456789,
"user_id": 987654321,
"enable": True,
},
)
```
### 宿主统一返回结构
`self.ctx.api.call(...)` 返回的是宿主包装结构：
```python
{
"success": True,
"result": ...,
}
```
失败时通常为：
```python
{
"success": False,
"error": "...",
}
```
## 这次文档采用的对齐口径
- 透传 API 的“官方请求字段”优先看 NapCat 官方页面的“请求参数”结构。
- 如果官方页面左侧 Schema 没展开字段，改用同页 `curl --data-raw` 示例补齐。
- 如果官方页面 Schema 和 `curl` 示例同时给出、但字段不一致，文档会把冲突显式写出来，不会替官方文档做静默裁剪。
- 强类型封装 API 额外写清“适配器直接参数”和“实际下发给 NapCat 的 body”。
详细例外见 [核验与兼容性说明](./verification.md)。
- NapCat 官方文档地址：[https://napcat.apifox.cn/](https://napcat.apifox.cn/)
## 命名空间数量
| 命名空间 | 数量 | 说明 |
| --- | ---: | --- |
| `adapter.napcat.action` | 2 | 适配器提供的通用动作入口。 |
| `adapter.napcat.system` | 23 | 登录、状态、凭证、系统控制。 |
| `adapter.napcat.account` | 27 | 资料、好友、收藏、OCR、账号能力。 |
| `adapter.napcat.group` | 41 | 群、频道、公告、群管理。 |
| `adapter.napcat.message` | 28 | 消息、互动、转发、AI 语音。 |
| `adapter.napcat.file` | 43 | 文件、群文件、在线文件、相册、流式传输。 |

59
plugin-templates/MaiBot-Napcat-Adapter/docs/account-api.md Normal file
View File

@@ -0,0 +1,59 @@
# Account 透传 API
这一页覆盖 `adapter.napcat.account.*` 下除强类型封装 API 外的透传 API。
统一调用方式：
```python
response = await self.ctx.api.call(
"adapter.napcat.account.send_like",
params={
"user_id": 123456789,
"times": 10,
},
)
```
字段来源说明：
- `无参`：官方页面当前无请求字段。
- `Schema`：直接来自官方“请求参数”结构。
- `示例`：官方页面 Schema 没展开出具体字段，参数来自同页 `curl --data-raw` 示例。
## API 列表
| API | 底层 action | 官方请求字段 | 来源 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.account.create_collection` | `create_collection` | `rawData`、`brief` | `Schema` | [官方](https://napcat.apifox.cn/226659178e0) | 创建收藏。 |
| `adapter.napcat.account.delete_friend` | `delete_friend` | `friend_id`、`user_id`、`temp_block`、`temp_both_del` | `Schema` | [官方](https://napcat.apifox.cn/227237873e0) | 删除好友。 |
| `adapter.napcat.account.fetch_custom_face` | `fetch_custom_face` | `count` | `Schema` | [官方](https://napcat.apifox.cn/226659210e0) | 获取自定义表情。 |
| `adapter.napcat.account.get_ai_characters` | `get_ai_characters` | `group_id`、`chat_type` | `Schema` | [官方](https://napcat.apifox.cn/229485683e0) | 获取 AI 角色列表。 |
| `adapter.napcat.account.get_clientkey` | `get_clientkey` | 无 | `无参` | [官方](https://napcat.apifox.cn/250286915e0) | 获取 ClientKey。 |
| `adapter.napcat.account.get_collection_list` | `get_collection_list` | `category`、`count` | `Schema` | [官方](https://napcat.apifox.cn/226659182e0) | 获取收藏列表。 |
| `adapter.napcat.account.get_cookies` | `get_cookies` | `domain` | `Schema` | [官方](https://napcat.apifox.cn/226657041e0) | 获取 Cookies。 |
| `adapter.napcat.account.get_friends_with_category` | `get_friends_with_category` | 无 | `无参` | [官方](https://napcat.apifox.cn/226658978e0) | 获取带分组的好友列表。 |
| `adapter.napcat.account.get_mini_app_ark` | `get_mini_app_ark` | `type`、`title`、`desc`、`picUrl`、`jumpUrl` | `示例` | [官方](https://napcat.apifox.cn/227738594e0) | 官方页当前为 `Any Of` 结构，但左侧 Schema 未展开具体顶层字段，这里按同页示例请求体记录。 |
| `adapter.napcat.account.get_profile_like` | `get_profile_like` | `user_id`、`start`、`count` | `Schema` | [官方](https://napcat.apifox.cn/226659197e0) | 获取资料点赞。 |
| `adapter.napcat.account.get_recent_contact` | `get_recent_contact` | `count` | `Schema` | [官方](https://napcat.apifox.cn/226659190e0) | 获取最近会话。 |
| `adapter.napcat.account.get_rkey` | `get_rkey` | 无 | `无参` | [官方](https://napcat.apifox.cn/283136230e0) | 获取扩展 RKey。 |
| `adapter.napcat.account.get_rkey_server` | `get_rkey_server` | 无 | `无参` | [官方](https://napcat.apifox.cn/283136236e0) | 获取 RKey 服务器。 |
| `adapter.napcat.account.get_unidirectional_friend_list` | `get_unidirectional_friend_list` | 无 | `无参` | [官方](https://napcat.apifox.cn/266151878e0) | 获取单向好友列表。 |
| `adapter.napcat.account.internal_ocr_image` | `.ocr_image` | `image` | `Schema` | [官方](https://napcat.apifox.cn/226658234e0) | 内部 OCR 动作。 |
| `adapter.napcat.account.nc_get_rkey` | `nc_get_rkey` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659297e0) | 获取 RKey。 |
| `adapter.napcat.account.ocr_image` | `ocr_image` | `image` | `Schema` | [官方](https://napcat.apifox.cn/226658231e0) | 图片 OCR 识别。 |
| `adapter.napcat.account.send_like` | `send_like` | `user_id`、`times` | `Schema` | [官方](https://napcat.apifox.cn/226656717e0) | 点赞。 |
| `adapter.napcat.account.set_diy_online_status` | `set_diy_online_status` | `face_id`、`face_type`、`wording` | `Schema` | [官方](https://napcat.apifox.cn/266151905e0) | 设置自定义在线状态。 |
| `adapter.napcat.account.set_friend_add_request` | `set_friend_add_request` | `flag`、`approve`、`remark` | `Schema` | [官方](https://napcat.apifox.cn/226656932e0) | 处理加好友请求。 |
| `adapter.napcat.account.set_friend_remark` | `set_friend_remark` | `user_id`、`remark` | `Schema` | [官方](https://napcat.apifox.cn/298305173e0) | 设置好友备注。 |
| `adapter.napcat.account.set_qq_avatar` | `set_qq_avatar` | `file` | `Schema` | [官方](https://napcat.apifox.cn/226658980e0) | 设置 QQ 头像。 |
| `adapter.napcat.account.set_self_longnick` | `set_self_longnick` | `longNick` | `Schema` | [官方](https://napcat.apifox.cn/226659186e0) | 设置个性签名。 |
| `adapter.napcat.account.translate_en2zh` | `translate_en2zh` | `words` | `Schema` | [官方](https://napcat.apifox.cn/226659102e0) | 英文单词翻译。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.account.ocr_image",
params={"image": "https://example.com/demo.png"},
)
```

83
plugin-templates/MaiBot-Napcat-Adapter/docs/file-api.md Normal file
View File

@@ -0,0 +1,83 @@
# File 透传 API
这一页覆盖 `adapter.napcat.file.*` 下除 `get_record` 外的透传 API。
统一调用方式：
```python
response = await self.ctx.api.call(
"adapter.napcat.file.upload_group_file",
params={
"group_id": 123456789,
"file": "/tmp/demo.txt",
"name": "demo.txt",
},
)
```
字段来源说明：
- `无参`：官方页面当前无请求字段。
- `Schema`：直接来自官方“请求参数”结构。
- `Schema + 示例`：官方页左侧 Schema 和同页 `curl --data-raw` 示例合并后得到。
- `冲突`：官方页同页 Schema / 示例字段互相冲突，文档显式列出。
## API 列表
| API | 底层 action | 官方请求字段 | 来源 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.file.cancel_online_file` | `cancel_online_file` | `user_id`、`msg_id` | `Schema` | [官方](https://napcat.apifox.cn/410334677e0) | 取消在线文件。 |
| `adapter.napcat.file.clean_stream_temp_file` | `clean_stream_temp_file` | 无 | `无参` | [官方](https://napcat.apifox.cn/395354124e0) | 清理流式传输临时文件。 |
| `adapter.napcat.file.create_flash_task` | `create_flash_task` | `files`、`name`、`thumb_path` | `Schema` | [官方](https://napcat.apifox.cn/410334666e0) | 创建闪传任务。 |
| `adapter.napcat.file.create_group_file_folder` | `create_group_file_folder` | `group_id`、`folder_name`、`name` | `Schema` | [官方](https://napcat.apifox.cn/226658773e0) | 创建群文件目录。 |
| `adapter.napcat.file.del_group_album_media` | `del_group_album_media` | `group_id`、`album_id`、`lloc` | `Schema` | [官方](https://napcat.apifox.cn/395455119e0) | 删除群相册媒体。 |
| `adapter.napcat.file.delete_group_file` | `delete_group_file` | `group_id`、`file_id` | `Schema` | [官方](https://napcat.apifox.cn/226658755e0) | 删除群文件。 |
| `adapter.napcat.file.delete_group_folder` | `delete_group_folder` | `group_id`、`folder_id`、`folder` | `Schema` | [官方](https://napcat.apifox.cn/226658779e0) | 删除群文件目录。 |
| `adapter.napcat.file.do_group_album_comment` | `do_group_album_comment` | `group_id`、`album_id`、`lloc`、`content` | `Schema` | [官方](https://napcat.apifox.cn/395458911e0) | 发表群相册评论。 |
| `adapter.napcat.file.download_file` | `download_file` | `url`、`base64`、`name`、`headers` | `Schema` | [官方](https://napcat.apifox.cn/226658887e0) | 下载文件。 |
| `adapter.napcat.file.download_file_image_stream` | `download_file_image_stream` | `file`、`file_id`、`chunk_size` | `Schema` | [官方](https://napcat.apifox.cn/395419462e0) | 下载图片文件流。 |
| `adapter.napcat.file.download_file_record_stream` | `download_file_record_stream` | `file`、`file_id`、`chunk_size`、`out_format` | `Schema` | [官方](https://napcat.apifox.cn/395417040e0) | 下载语音文件流。 |
| `adapter.napcat.file.download_file_stream` | `download_file_stream` | `file`、`file_id`、`chunk_size` | `Schema` | [官方](https://napcat.apifox.cn/395413859e0) | 下载文件流。 |
| `adapter.napcat.file.download_fileset` | `download_fileset` | `fileset_id` | `Schema` | [官方](https://napcat.apifox.cn/410334678e0) | 下载文件集。 |
| `adapter.napcat.file.get_file` | `get_file` | `file`、`file_id` | `Schema` | [官方](https://napcat.apifox.cn/226658985e0) | 获取文件。 |
| `adapter.napcat.file.get_fileset_id` | `get_fileset_id` | `share_code` | `Schema` | [官方](https://napcat.apifox.cn/410334679e0) | 获取文件集 ID。 |
| `adapter.napcat.file.get_fileset_info` | `get_fileset_info` | `fileset_id` | `Schema` | [官方](https://napcat.apifox.cn/410334671e0) | 获取文件集信息。 |
| `adapter.napcat.file.get_flash_file_list` | `get_flash_file_list` | `fileset_id` | `Schema` | [官方](https://napcat.apifox.cn/410334667e0) | 获取闪传文件列表。 |
| `adapter.napcat.file.get_flash_file_url` | `get_flash_file_url` | `fileset_id`、`file_name`、`file_index` | `Schema` | [官方](https://napcat.apifox.cn/410334668e0) | 获取闪传文件链接。 |
| `adapter.napcat.file.get_group_album_media_list` | `get_group_album_media_list` | `group_id`、`album_id`、`attach_info` | `Schema` | [官方](https://napcat.apifox.cn/395459066e0) | 获取群相册媒体列表。 |
| `adapter.napcat.file.get_group_file_system_info` | `get_group_file_system_info` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658789e0) | 获取群文件系统信息。 |
| `adapter.napcat.file.get_group_file_url` | `get_group_file_url` | `group_id`、`file_id`、`busid` | `Schema + 示例` | [官方](https://napcat.apifox.cn/226658867e0) | 官方页左侧 Schema 当前只列 `group_id` / `file_id`，同页示例请求体额外给出 `busid`。 |
| `adapter.napcat.file.get_group_files_by_folder` | `get_group_files_by_folder` | `group_id`、`folder_id`、`folder`、`file_count` | `Schema` | [官方](https://napcat.apifox.cn/226658865e0) | 获取群文件夹文件列表。 |
| `adapter.napcat.file.get_group_root_files` | `get_group_root_files` | `group_id`、`file_count` | `Schema` | [官方](https://napcat.apifox.cn/226658823e0) | 获取群根目录文件列表。 |
| `adapter.napcat.file.get_image` | `get_image` | `file`、`file_id` | `Schema` | [官方](https://napcat.apifox.cn/226657066e0) | 获取图片。 |
| `adapter.napcat.file.get_online_file_msg` | `get_online_file_msg` | `user_id` | `Schema` | [官方](https://napcat.apifox.cn/410334672e0) | 获取在线文件消息。 |
| `adapter.napcat.file.get_private_file_url` | `get_private_file_url` | `user_id`、`file_id` | `Schema + 示例` | [官方](https://napcat.apifox.cn/266151849e0) | 官方页左侧 Schema 当前只列 `file_id`，同页示例请求体额外给出 `user_id`。 |
| `adapter.napcat.file.get_qun_album_list` | `get_qun_album_list` | `group_id`、`attach_info` | `Schema` | [官方](https://napcat.apifox.cn/395460287e0) | 获取群相册列表。 |
| `adapter.napcat.file.get_share_link` | `get_share_link` | `fileset_id` | `Schema` | [官方](https://napcat.apifox.cn/410334670e0) | 获取文件分享链接。 |
| `adapter.napcat.file.move_group_file` | `move_group_file` | `group_id`、`file_id`、`current_parent_directory`、`target_parent_directory` | `Schema` | [官方](https://napcat.apifox.cn/283136359e0) | 移动群文件。 |
| `adapter.napcat.file.receive_online_file` | `receive_online_file` | `user_id`、`msg_id`、`element_id` | `Schema` | [官方](https://napcat.apifox.cn/410334675e0) | 接收在线文件。 |
| `adapter.napcat.file.refuse_online_file` | `refuse_online_file` | `user_id`、`msg_id`、`element_id` | `Schema` | [官方](https://napcat.apifox.cn/410334676e0) | 拒绝在线文件。 |
| `adapter.napcat.file.rename_group_file` | `rename_group_file` | `group_id`、`file_id`、`current_parent_directory`、`new_name` | `Schema` | [官方](https://napcat.apifox.cn/283136375e0) | 重命名群文件。 |
| `adapter.napcat.file.send_flash_msg` | `send_flash_msg` | `fileset_id`、`user_id`、`group_id` | `Schema` | [官方](https://napcat.apifox.cn/410334669e0) | 发送闪传消息。 |
| `adapter.napcat.file.send_online_file` | `send_online_file` | `user_id`、`file_path`、`file_name` | `Schema` | [官方](https://napcat.apifox.cn/410334673e0) | 发送在线文件。 |
| `adapter.napcat.file.send_online_folder` | `send_online_folder` | `user_id`、`folder_path`、`folder_name` | `Schema` | [官方](https://napcat.apifox.cn/410334674e0) | 发送在线文件夹。 |
| `adapter.napcat.file.set_group_album_media_like` | `set_group_album_media_like` | `group_id`、`album_id`、`lloc`、`id`、`set` | `Schema` | [官方](https://napcat.apifox.cn/395457331e0) | 点赞群相册媒体。 |
| `adapter.napcat.file.trans_group_file` | `trans_group_file` | `group_id`、`file_id` | `Schema` | [官方](https://napcat.apifox.cn/283136366e0) | 传输群文件。 |
| `adapter.napcat.file.upload_file_stream` | `upload_file_stream` | `stream_id`、`chunk_data`、`chunk_index`、`total_chunks`、`file_size`、`expected_sha256`、`is_complete`、`filename`、`reset`、`verify_only`、`file_retention` | `Schema` | [官方](https://napcat.apifox.cn/395363988e0) | 上传文件流。 |
| `adapter.napcat.file.upload_group_file` | `upload_group_file` | `group_id`、`file`、`name`、`folder`、`folder_id`、`upload_file` | `Schema` | [官方](https://napcat.apifox.cn/226658753e0) | 上传群文件。 |
| `adapter.napcat.file.upload_image_to_qun_album` | `upload_image_to_qun_album` | `group_id`、`album_id`、`album_name`、`file` | `Schema` | [官方](https://napcat.apifox.cn/395459739e0) | 上传图片到群相册。 |
| `adapter.napcat.file.upload_private_file` | `upload_private_file` | `user_id`、`file`、`name`、`upload_file` | `Schema` | [官方](https://napcat.apifox.cn/226658883e0) | 上传私聊文件。 |
| `adapter.napcat.file.test_download_stream` | `test_download_stream` | `error`、`url` | `冲突` | [官方](https://napcat.apifox.cn/395355338e0) | 官方页左侧 Schema 当前字段为 `error`，同页示例请求体却使用 `url`，两者互相冲突。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.file.upload_group_file",
params={
"group_id": 123456789,
"file": "/tmp/demo.txt",
"name": "demo.txt",
},
)
```

70
plugin-templates/MaiBot-Napcat-Adapter/docs/group-api.md Normal file
View File

@@ -0,0 +1,70 @@
# Group 透传 API
这一页覆盖 `adapter.napcat.group.*` 下除强类型封装 API 外的透传 API。
统一调用方式：
```python
response = await self.ctx.api.call(
"adapter.napcat.group.set_group_admin",
params={
"group_id": 123456789,
"user_id": 987654321,
"enable": True,
},
)
```
字段来源说明：
- `无参`：官方页面当前无请求字段。
- `Schema`：直接来自官方“请求参数”结构。
- `示例`：官方页面 Schema 未展开字段，参数来自同页 `curl --data-raw` 示例。
## API 列表
| API | 底层 action | 官方请求字段 | 来源 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.group.delete_essence_msg` | `delete_essence_msg` | `message_id`、`msg_seq`、`msg_random`、`group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658678e0) | 官方页当前除了 `message_id` 还列出兼容字段；适配器这里完全透传。 |
| `adapter.napcat.group.delete_group_notice` | `_del_group_notice` | `group_id`、`notice_id` | `Schema` | [官方](https://napcat.apifox.cn/226659240e0) | 删除群公告。 |
| `adapter.napcat.group.get_essence_msg_list` | `get_essence_msg_list` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658664e0) | 获取群精华消息。 |
| `adapter.napcat.group.get_group_honor_info` | `get_group_honor_info` | `group_id`、`type` | `Schema` | [官方](https://napcat.apifox.cn/226657036e0) | 获取群荣誉信息。 |
| `adapter.napcat.group.get_group_ignore_add_request` | `get_group_ignore_add_request` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659234e0) | 获取群被忽略的加群请求。 |
| `adapter.napcat.group.get_group_ignored_notifies` | `get_group_ignored_notifies` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659323e0) | 获取群忽略通知。 |
| `adapter.napcat.group.get_group_info_ex` | `get_group_info_ex` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226659229e0) | 获取群详细信息（扩展）。 |
| `adapter.napcat.group.get_group_notice` | `_get_group_notice` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658742e0) | 获取群公告。 |
| `adapter.napcat.group.get_group_shut_list` | `get_group_shut_list` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226659300e0) | 获取群禁言列表。 |
| `adapter.napcat.group.get_group_system_msg` | `get_group_system_msg` | `count` | `Schema` | [官方](https://napcat.apifox.cn/226658660e0) | 获取群系统消息。 |
| `adapter.napcat.group.get_guild_list` | `get_guild_list` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659311e0) | 获取频道列表。 |
| `adapter.napcat.group.get_guild_service_profile` | `get_guild_service_profile` | `guild_id` | `示例` | [官方](https://napcat.apifox.cn/226659317e0) | 官方页左侧 Schema 当前只显示 `object`，同页示例请求体给出 `guild_id`。 |
| `adapter.napcat.group.group_poke` | `group_poke` | `group_id`、`user_id`、`target_id` | `Schema` | [官方](https://napcat.apifox.cn/226659265e0) | 发送群聊戳一戳。 |
| `adapter.napcat.group.handle_quick_operation_internal` | `.handle_quick_operation` | `context`、`operation` | `Schema` | [官方](https://napcat.apifox.cn/226658889e0) | 处理快速操作。 |
| `adapter.napcat.group.send_group_msg` | `send_group_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226656598e0) | 官方页当前顶层请求字段就是这一组；真正的消息段细节放在 `message` 内。 |
| `adapter.napcat.group.send_group_notice` | `_send_group_notice` | `group_id`、`content`、`image`、`pinned`、`type`、`confirm_required`、`is_show_edit_card`、`tip_window_type` | `Schema` | [官方](https://napcat.apifox.cn/226658740e0) | 发送群公告。 |
| `adapter.napcat.group.send_group_sign` | `send_group_sign` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/230897177e0) | NapCat 另外提供的“群打卡”动作。 |
| `adapter.napcat.group.set_essence_msg` | `set_essence_msg` | `message_id` | `Schema` | [官方](https://napcat.apifox.cn/226658674e0) | 设置精华消息。 |
| `adapter.napcat.group.set_group_add_option` | `set_group_add_option` | `group_id`、`add_type`、`group_question`、`group_answer` | `Schema` | [官方](https://napcat.apifox.cn/301542178e0) | 设置群加群选项。 |
| `adapter.napcat.group.set_group_add_request` | `set_group_add_request` | `flag`、`approve`、`reason`、`count` | `Schema` | [官方](https://napcat.apifox.cn/226656947e0) | 官方页当前字段与旧版常见的 `sub_type` 方案不同；文档按当前官方页记录。 |
| `adapter.napcat.group.set_group_admin` | `set_group_admin` | `group_id`、`user_id`、`enable` | `Schema` | [官方](https://napcat.apifox.cn/226656815e0) | 设置群管理员。 |
| `adapter.napcat.group.set_group_card` | `set_group_card` | `group_id`、`user_id`、`card` | `Schema` | [官方](https://napcat.apifox.cn/226656913e0) | 设置群名片。 |
| `adapter.napcat.group.set_group_leave` | `set_group_leave` | `group_id`、`is_dismiss` | `Schema` | [官方](https://napcat.apifox.cn/226656926e0) | 退出群组。 |
| `adapter.napcat.group.set_group_portrait` | `set_group_portrait` | `file`、`group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658669e0) | 设置群头像。 |
| `adapter.napcat.group.set_group_remark` | `set_group_remark` | `group_id`、`remark` | `Schema` | [官方](https://napcat.apifox.cn/283136268e0) | 设置群备注。 |
| `adapter.napcat.group.set_group_robot_add_option` | `set_group_robot_add_option` | `group_id`、`robot_member_switch`、`robot_member_examine` | `Schema` | [官方](https://napcat.apifox.cn/301542198e0) | 设置群机器人加群选项。 |
| `adapter.napcat.group.set_group_search` | `set_group_search` | `group_id`、`no_code_finger_open`、`no_finger_open` | `Schema` | [官方](https://napcat.apifox.cn/301542170e0) | 设置群搜索选项。 |
| `adapter.napcat.group.set_group_sign` | `set_group_sign` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226659329e0) | 群打卡。 |
| `adapter.napcat.group.set_group_special_title` | `set_group_special_title` | `group_id`、`user_id`、`special_title` | `Schema` | [官方](https://napcat.apifox.cn/226656931e0) | 设置专属头衔。 |
| `adapter.napcat.group.set_group_todo` | `set_group_todo` | `group_id`、`message_id`、`message_seq` | `Schema` | [官方](https://napcat.apifox.cn/395460568e0) | 设置群待办。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.group.send_group_msg",
params={
"message_type": "group",
"group_id": 123456789,
"message": [{"type": "text", "data": {"text": "你好"}}],
},
)
```

61
plugin-templates/MaiBot-Napcat-Adapter/docs/message-api.md Normal file
View File

@@ -0,0 +1,61 @@
# Message 透传 API
这一页覆盖 `adapter.napcat.message.*` 下除强类型封装 API 外的透传 API。
统一调用方式：
```python
response = await self.ctx.api.call(
"adapter.napcat.message.friend_poke",
params={
"group_id": 123456789,
"user_id": 987654321,
"target_id": 987654321,
},
)
```
字段来源说明：
- `无参`：官方页面当前无请求字段。
- `Schema`：直接来自官方“请求参数”结构。
## API 列表
| API | 底层 action | 官方请求字段 | 来源 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.message.ark_share_group` | `ArkShareGroup` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/226658971e0) | 分享群（Ark）。 |
| `adapter.napcat.message.ark_share_peer` | `ArkSharePeer` | `user_id`、`group_id`、`phone_number` | `Schema` | [官方](https://napcat.apifox.cn/226658965e0) | 分享用户（Ark）。 |
| `adapter.napcat.message.click_inline_keyboard_button` | `click_inline_keyboard_button` | `group_id`、`bot_appid`、`button_id`、`callback_data`、`msg_seq` | `Schema` | [官方](https://napcat.apifox.cn/266151864e0) | 点击内联键盘按钮。 |
| `adapter.napcat.message.fetch_emoji_like` | `fetch_emoji_like` | `message_id`、`emojiId`、`emojiType`、`count`、`cookie` | `Schema` | [官方](https://napcat.apifox.cn/226659219e0) | 获取表情点赞详情。 |
| `adapter.napcat.message.forward_friend_single_msg` | `forward_friend_single_msg` | `message_id`、`group_id`、`user_id` | `Schema` | [官方](https://napcat.apifox.cn/226659051e0) | 转发单条消息。 |
| `adapter.napcat.message.forward_group_single_msg` | `forward_group_single_msg` | `message_id`、`group_id`、`user_id` | `Schema` | [官方](https://napcat.apifox.cn/226659074e0) | 转发单条消息。 |
| `adapter.napcat.message.friend_poke` | `friend_poke` | `group_id`、`user_id`、`target_id` | `Schema` | [官方](https://napcat.apifox.cn/226659255e0) | 发送私聊戳一戳。 |
| `adapter.napcat.message.get_ai_record` | `get_ai_record` | `character`、`group_id`、`text` | `Schema` | [官方](https://napcat.apifox.cn/229486818e0) | 获取 AI 语音。 |
| `adapter.napcat.message.get_emoji_likes` | `get_emoji_likes` | `group_id`、`message_id`、`emoji_id`、`emoji_type`、`count` | `Schema` | [官方](https://napcat.apifox.cn/410334663e0) | 获取消息表情点赞列表。 |
| `adapter.napcat.message.get_friend_msg_history` | `get_friend_msg_history` | `user_id`、`message_seq`、`count`、`reverse_order`、`disable_get_url`、`parse_mult_msg`、`quick_reply`、`reverseOrder` | `Schema` | [官方](https://napcat.apifox.cn/226659174e0) | 官方页当前同时列出 `reverse_order` 和 `reverseOrder` 两种写法。 |
| `adapter.napcat.message.get_group_msg_history` | `get_group_msg_history` | `group_id`、`message_seq`、`count`、`reverse_order`、`disable_get_url`、`parse_mult_msg`、`quick_reply`、`reverseOrder` | `Schema` | [官方](https://napcat.apifox.cn/226657401e0) | 官方页当前同时列出 `reverse_order` 和 `reverseOrder` 两种写法。 |
| `adapter.napcat.message.mark_all_as_read` | `_mark_all_as_read` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659194e0) | 标记所有消息已读。 |
| `adapter.napcat.message.mark_group_msg_as_read` | `mark_group_msg_as_read` | `user_id`、`group_id`、`message_id` | `Schema` | [官方](https://napcat.apifox.cn/226659167e0) | 标记群聊已读。 |
| `adapter.napcat.message.mark_msg_as_read` | `mark_msg_as_read` | `user_id`、`group_id`、`message_id` | `Schema` | [官方](https://napcat.apifox.cn/226657389e0) | 标记消息已读（Go-CQHTTP 兼容）。 |
| `adapter.napcat.message.mark_private_msg_as_read` | `mark_private_msg_as_read` | `user_id`、`group_id`、`message_id` | `Schema` | [官方](https://napcat.apifox.cn/226659165e0) | 标记私聊已读。 |
| `adapter.napcat.message.send_ark_share` | `send_ark_share` | `user_id`、`group_id`、`phone_number` | `Schema` | [官方](https://napcat.apifox.cn/410334665e0) | 分享用户（Ark）。 |
| `adapter.napcat.message.send_forward_msg` | `send_forward_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226659136e0) | 官方页当前顶层请求字段就是这一组；真正的转发节点细节放在 `message` 内。 |
| `adapter.napcat.message.send_group_ark_share` | `send_group_ark_share` | `group_id` | `Schema` | [官方](https://napcat.apifox.cn/410334664e0) | 分享群（Ark）。 |
| `adapter.napcat.message.send_group_forward_msg` | `send_group_forward_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226657396e0) | 发送群合并转发消息。 |
| `adapter.napcat.message.send_msg` | `send_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226656652e0) | 通用发送消息。 |
| `adapter.napcat.message.send_private_forward_msg` | `send_private_forward_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226657399e0) | 发送私聊合并转发消息。 |
| `adapter.napcat.message.send_private_msg` | `send_private_msg` | `message_type`、`user_id`、`group_id`、`message`、`auto_escape`、`source`、`news`、`summary`、`prompt`、`timeout` | `Schema` | [官方](https://napcat.apifox.cn/226656553e0) | 发送私聊消息。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.message.send_msg",
params={
"message_type": "group",
"group_id": 123456789,
"message": [{"type": "text", "data": {"text": "你好，MaiBot"}}],
},
)
```

54
plugin-templates/MaiBot-Napcat-Adapter/docs/system-api.md Normal file
View File

@@ -0,0 +1,54 @@
# System 透传 API
这一页覆盖 `adapter.napcat.system.*` 下除 `get_login_info` 外的透传 API。
统一调用方式：
```python
response = await self.ctx.api.call(
"adapter.napcat.system.check_url_safely",
params={"url": "https://example.com"},
)
```
字段来源说明：
- `无参`：官方页面当前无请求字段。
- `Schema`：直接来自官方“请求参数”结构。
- `示例`：官方页面 Schema 只显示泛型 `object`，字段来自同页 `curl --data-raw` 示例。
## API 列表
| API | 底层 action | 官方请求字段 | 来源 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.system.bot_exit` | `bot_exit` | 无 | `无参` | [官方](https://napcat.apifox.cn/283136399e0) | 退出登录。 |
| `adapter.napcat.system.can_send_image` | `can_send_image` | 无 | `无参` | [官方](https://napcat.apifox.cn/226657071e0) | 是否可以发送图片。 |
| `adapter.napcat.system.can_send_record` | `can_send_record` | 无 | `无参` | [官方](https://napcat.apifox.cn/226657080e0) | 是否可以发送语音。 |
| `adapter.napcat.system.check_url_safely` | `check_url_safely` | `url` | `Schema` | [官方](https://napcat.apifox.cn/228534361e0) | 检查 URL 安全性。 |
| `adapter.napcat.system.clean_cache` | `clean_cache` | 无 | `无参` | [官方](https://napcat.apifox.cn/298305106e0) | 清理缓存。 |
| `adapter.napcat.system.get_credentials` | `get_credentials` | `domain` | `Schema` | [官方](https://napcat.apifox.cn/226657054e0) | 获取登录凭证。 |
| `adapter.napcat.system.get_csrf_token` | `get_csrf_token` | 无 | `无参` | [官方](https://napcat.apifox.cn/226657044e0) | 获取 CSRF Token。 |
| `adapter.napcat.system.get_doubt_friends_add_request` | `get_doubt_friends_add_request` | `count` | `Schema` | [官方](https://napcat.apifox.cn/289565516e0) | 获取可疑好友申请。 |
| `adapter.napcat.system.get_model_show` | `_get_model_show` | `model` | `Schema` | [官方](https://napcat.apifox.cn/227233981e0) | 获取机型显示。 |
| `adapter.napcat.system.get_online_clients` | `get_online_clients` | `no_cache` | `示例` | [官方](https://napcat.apifox.cn/226657379e0) | 官方页左侧 Schema 当前只显示 `object`，同页示例请求体给出 `no_cache`。 |
| `adapter.napcat.system.get_robot_uin_range` | `get_robot_uin_range` | 无 | `无参` | [官方](https://napcat.apifox.cn/226658975e0) | 获取机器人 UIN 范围。 |
| `adapter.napcat.system.get_status` | `get_status` | 无 | `无参` | [官方](https://napcat.apifox.cn/226657083e0) | 获取运行状态。 |
| `adapter.napcat.system.get_version_info` | `get_version_info` | 无 | `无参` | [官方](https://napcat.apifox.cn/226657087e0) | 获取版本信息。 |
| `adapter.napcat.system.nc_get_packet_status` | `nc_get_packet_status` | 无 | `无参` | [官方](https://napcat.apifox.cn/226659280e0) | 获取 Packet 状态。 |
| `adapter.napcat.system.nc_get_user_status` | `nc_get_user_status` | `user_id` | `Schema` | [官方](https://napcat.apifox.cn/226659292e0) | 获取用户在线状态。 |
| `adapter.napcat.system.send_packet` | `send_packet` | `cmd`、`data`、`rsp` | `Schema` | [官方](https://napcat.apifox.cn/250286903e0) | 发送原始数据包。 |
| `adapter.napcat.system.set_doubt_friends_add_request` | `set_doubt_friends_add_request` | `flag`、`approve` | `Schema` | [官方](https://napcat.apifox.cn/289565525e0) | 处理可疑好友申请。 |
| `adapter.napcat.system.set_input_status` | `set_input_status` | `user_id`、`event_type` | `Schema` | [官方](https://napcat.apifox.cn/226659225e0) | 设置输入状态。 |
| `adapter.napcat.system.set_model_show` | `_set_model_show` | `model`、`model_show` | `示例` | [官方](https://napcat.apifox.cn/227233993e0) | 官方页左侧 Schema 当前只显示 `object`，同页示例请求体给出 `model` / `model_show`。 |
| `adapter.napcat.system.set_online_status` | `set_online_status` | `status`、`ext_status`、`battery_status` | `Schema` | [官方](https://napcat.apifox.cn/226658977e0) | 设置在线状态。 |
| `adapter.napcat.system.set_restart` | `set_restart` | 无 | `无参` | [官方](https://napcat.apifox.cn/410334662e0) | 重启服务。 |
| `adapter.napcat.system.unknown_action` | `unknown` | 无 | `无参` | [官方](https://napcat.apifox.cn/411631224e0) | 透传调用名为 `unknown` 的底层动作。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.system.get_online_clients",
params={"no_cache": False},
)
```

83
plugin-templates/MaiBot-Napcat-Adapter/docs/typed-api.md Normal file
View File

@@ -0,0 +1,83 @@
# 强类型封装 API
这一页只写“强类型封装 API”。
调用规则：
- 直接使用 `self.ctx.api.call("完整 API 名", **kwargs)`。
- 不要把参数再包进 `params`。
- 如果 `response["success"]` 为真，真正的业务结果在 `response["result"]`。
## 通用入口
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.action.call` | `action_name`、`params=None` | 任意 action | 由 `action_name` 决定 | 无 | 适配器通用入口；`result` 为 NapCat 原始响应字典。 |
| `adapter.napcat.action.call_data` | `action_name`、`params=None` | 任意 action | 由 `action_name` 决定 | 无 | 适配器通用入口；`result` 直接返回 NapCat 响应里的 `data`。 |
## System
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.system.get_login_info` | 无 | `get_login_info` | 无 | [官方](https://napcat.apifox.cn/226656952e0) | `result` 为 `dict \| None`；失败返回 `None`。 |
## Account
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.account.set_qq_profile` | `nickname`、`personal_note=""`、`sex=""` | `set_qq_profile` | `nickname`、`personal_note`、`sex` | [官方](https://napcat.apifox.cn/226657374e0) | `nickname` 必填；`sex` 仅允许 `male` / `female` / `unknown`；空 `personal_note` 和空 `sex` 不会下发。 |
| `adapter.napcat.account.get_stranger_info` | `user_id`、`no_cache=False` | `get_stranger_info` | `user_id`、`no_cache` | [官方](https://napcat.apifox.cn/226656970e0) | 适配器已对齐官方隐藏 schema；官方默认示例只展示 `user_id`，但页面内嵌 schema 还定义了 `no_cache`；`result` 为 `dict \| None`。 |
| `adapter.napcat.account.get_friend_list` | `no_cache=False` | `get_friend_list` | `no_cache` | [官方](https://napcat.apifox.cn/226656976e0) | `result` 为归一化后的好友列表；NapCat 不同版本下若把列表包在 `friend_list` / `data` 里，适配器会自动展开。 |
## Group
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.group.set_group_ban` | `group_id`、`user_id`、`duration` | `set_group_ban` | `group_id`、`user_id`、`duration` | [官方](https://napcat.apifox.cn/226656791e0) | `duration` 必须是 `0` 到 `2592000` 之间的非负整数。 |
| `adapter.napcat.group.set_group_whole_ban` | `group_id`、`enable` | `set_group_whole_ban` | `group_id`、`enable` | [官方](https://napcat.apifox.cn/226656802e0) | `enable` 会被规范成布尔值。 |
| `adapter.napcat.group.set_group_kick` | `group_id`、`user_id`、`reject_add_request=False` | `set_group_kick` | `group_id`、`user_id`、`reject_add_request` | [官方](https://napcat.apifox.cn/226656748e0) | 单个踢人封装。 |
| `adapter.napcat.group.set_group_kick_members` | `group_id`、`user_id`、`reject_add_request=False` | `set_group_kick_members` | `group_id`、`user_id`、`reject_add_request` | [官方](https://napcat.apifox.cn/301542209e0) | 适配器要求 `user_id` 传数组，并实际下发 `user_id: [ ... ]`。 |
| `adapter.napcat.group.set_group_name` | `group_id`、`group_name` | `set_group_name` | `group_id`、`group_name` | [官方](https://napcat.apifox.cn/226656919e0) | `group_name` 会被规范成非空字符串。 |
| `adapter.napcat.group.get_group_info` | `group_id` | `get_group_info` | `group_id` | [官方](https://napcat.apifox.cn/226656979e0) | `result` 为 `dict \| None`。 |
| `adapter.napcat.group.get_group_detail_info` | `group_id` | `get_group_detail_info` | `group_id` | [官方](https://napcat.apifox.cn/307180859e0) | `result` 为 `dict \| None`。 |
| `adapter.napcat.group.get_group_list` | `no_cache=False` | `get_group_list` | `no_cache` | [官方](https://napcat.apifox.cn/226656992e0) | `result` 为归一化后的群列表。 |
| `adapter.napcat.group.get_group_at_all_remain` | `group_id` | `get_group_at_all_remain` | `group_id` | [官方](https://napcat.apifox.cn/227245941e0) | `result` 为 `dict \| None`；不同 NapCat 版本下返回字段名可能不同。 |
| `adapter.napcat.group.get_group_member_info` | `group_id`、`user_id`、`no_cache=True` | `get_group_member_info` | `group_id`、`user_id`、`no_cache` | [官方](https://napcat.apifox.cn/226657019e0) | `group_id` / `user_id` 会先规范化为正整数，再转字符串下发。 |
| `adapter.napcat.group.get_group_member_list` | `group_id`、`no_cache=False` | `get_group_member_list` | `group_id`、`no_cache` | [官方](https://napcat.apifox.cn/226657034e0) | `result` 为归一化后的成员列表。 |
## Message
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.message.send_poke` | `user_id=None`、`group_id=None`、`target_id=None`、`qq_id=None` | `send_poke` | `group_id`、`user_id`、`target_id` | [官方](https://napcat.apifox.cn/250286923e0) | 优先使用官方字段 `user_id` / `group_id` / `target_id`；`qq_id` 仅作为旧版兼容别名，会映射成 `user_id`。 |
| `adapter.napcat.message.delete_msg` | `message_id` | `delete_msg` | `message_id` | [官方](https://napcat.apifox.cn/226919954e0) | `message_id` 必须是正整数。 |
| `adapter.napcat.message.send_group_ai_record` | `group_id`、`character`、`text` | `send_group_ai_record` | `character`、`group_id`、`text` | [官方](https://napcat.apifox.cn/229486774e0) | `character` 和 `text` 都会被规范成非空字符串。 |
| `adapter.napcat.message.set_msg_emoji_like` | `message_id`、`emoji_id`、`set=True` | `set_msg_emoji_like` | `message_id`、`emoji_id`、`set` | [官方](https://napcat.apifox.cn/226659104e0) | 适配器把 `set` 下发为官方字段 `set`。 |
| `adapter.napcat.message.get_msg` | `message_id` | `get_msg` | `message_id` | [官方](https://napcat.apifox.cn/226656707e0) | `result` 为 `dict \| None`。 |
| `adapter.napcat.message.get_forward_msg` | `message_id=""`、`id=""` | `get_forward_msg` | `message_id`、`id` | [官方](https://napcat.apifox.cn/226656712e0) | 适配器已对齐官方隐藏 schema；至少提供一个字段；若两个字段同时传入则要求值一致；`result` 会统一整理成 `{\"messages\": [...]}`。 |
## File
| API | 适配器直接参数 | 官方 action | 官方请求字段 | 官方文档 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `adapter.napcat.file.get_record` | `file=""`、`file_id=""`、`out_format="wav"` | `get_record` | `file`、`file_id`、`out_format` | [官方](https://napcat.apifox.cn/226657058e0) | 适配器已对齐官方隐藏 schema；`file` / `file_id` 至少提供一个；`out_format` 默认仍为 `wav`，以兼容旧行为。 |
## 典型示例
```python
response = await self.ctx.api.call(
"adapter.napcat.message.send_poke",
user_id=987654321,
group_id=123456789,
target_id=123456789,
)
```
```python
response = await self.ctx.api.call(
"adapter.napcat.group.get_group_member_info",
group_id=123456789,
user_id=987654321,
no_cache=True,
)
```

55
plugin-templates/MaiBot-Napcat-Adapter/docs/verification.md Normal file
View File

@@ -0,0 +1,55 @@
# 核验与兼容性说明
## 1. 这次核验做了什么
- 扫描 `plugins/MaiBot-Napcat-Adapter/apis/*.py` 中全部 `@API(..., public=True)` 公开接口。
- 对每个透传 API 反查其底层 NapCat action。
- 用 NapCat 官方文档 [https://napcat.apifox.cn/](https://napcat.apifox.cn/) 逐项确认底层 action 页面是否存在。
- 用浏览器逐页读取官方页面的“请求参数”结构；遇到官方页左侧只显示泛型 `object` 时，再补读同页 `curl --data-raw` 示例。
- 对请求示例少于隐藏 schema 的页面，额外抓取官方页原始 HTML，核对 Apifox 内嵌的 request body schema。
- 对强类型封装 API，额外对照 `plugins/MaiBot-Napcat-Adapter/services/query_service.py` 确认适配器实际下发的 body。
## 2. 覆盖范围
- 适配器公开 API 总数：`164`
- 其中适配器自带通用入口：`2`
- `adapter.napcat.action.call`
- `adapter.napcat.action.call_data`
- 其中可映射到底层 NapCat action 的 API：`162`
- 这 `162` 个底层 action 的官方文档页面：`162 / 162` 都已找到并写入 docs
## 3. 参数对齐口径
- 普通透传 API：文档写“官方请求字段”，适配器自己不裁剪，只要求调用方传 `params={...}`。
- 强类型封装 API：文档写“适配器直接参数”和“官方请求字段”两列，明确哪里是适配器收敛过的用法。
- 如果官方页 `Schema` 和同页 `curl` 示例不一致，文档不会替官方做静默判断，而是显式标成 `Schema + 示例` 或 `冲突`。
## 4. 已确认的官方页例外
| action / API | 官方文档 | 现象 | 文档处理方式 |
| --- | --- | --- | --- |
| `get_online_clients` | [官方](https://napcat.apifox.cn/226657379e0) | 左侧 Schema 只显示 `object`，同页示例请求体给出 `no_cache` | 在文档中按 `示例` 记录 `no_cache` |
| `_set_model_show` | [官方](https://napcat.apifox.cn/227233993e0) | 左侧 Schema 只显示 `object`，同页示例请求体给出 `model`、`model_show` | 在文档中按 `示例` 记录 |
| `get_mini_app_ark` | [官方](https://napcat.apifox.cn/227738594e0) | 官方页为 `Any Of` 结构，但左侧 Schema 未展开可直接抄用的顶层字段 | 在文档中按同页示例请求体记录当前可见字段 |
| `get_guild_service_profile` | [官方](https://napcat.apifox.cn/226659317e0) | 左侧 Schema 只显示 `object`，同页示例请求体给出 `guild_id` | 在文档中按 `示例` 记录 `guild_id` |
| `get_group_file_url` | [官方](https://napcat.apifox.cn/226658867e0) | 左侧 Schema 只列 `group_id`、`file_id`，同页示例请求体额外给出 `busid` | 在文档中按 `Schema + 示例` 合并记录 |
| `get_private_file_url` | [官方](https://napcat.apifox.cn/266151849e0) | 左侧 Schema 只列 `file_id`，同页示例请求体额外给出 `user_id` | 在文档中按 `Schema + 示例` 合并记录 |
| `test_download_stream` | [官方](https://napcat.apifox.cn/395355338e0) | 左侧 Schema 当前字段为 `error`，同页示例请求体却使用 `url` | 在文档中标记为 `冲突`，两组字段都写出 |
| `get_stranger_info` | [官方](https://napcat.apifox.cn/226656970e0) | 页面默认示例只写 `user_id`，但原始 HTML 的隐藏 schema 还定义了 `no_cache` | 在文档和实现中按隐藏 schema 记录 `user_id`、`no_cache` |
| `get_forward_msg` | [官方](https://napcat.apifox.cn/226656712e0) | 页面默认示例只写 `message_id`，但原始 HTML 的隐藏 schema 还定义了 `id` | 在文档和实现中按隐藏 schema 同时支持 `message_id`、`id` |
| `get_record` | [官方](https://napcat.apifox.cn/226657058e0) | 页面默认示例只写 `file`、`out_format`，但原始 HTML 的隐藏 schema 还定义了 `file_id` | 在文档和实现中按隐藏 schema 记录 `file`、`file_id`、`out_format` |
| `send_poke` | [官方](https://napcat.apifox.cn/250286923e0) | 页面默认示例只写 `user_id`，但原始 HTML 的隐藏 schema 还定义了 `group_id`、`target_id` | 在文档和实现中按隐藏 schema 记录 `user_id`、`group_id`、`target_id` |
| `send_group_sign` | [官方](https://napcat.apifox.cn/230897177e0) | 官方页面存在，但侧边序列化索引缺少常规标题字段 | 文档直接写死官方链接，不依赖侧边索引标题 |
| `send_poke` / `friend_poke` / `forward_group_single_msg` / `send_ark_share` / `send_group_ark_share` / `clean_stream_temp_file` | 对应各自官方页 | 官方侧边序列化索引缺少常规标题字段，但页面本身存在 | 文档直接写死官方链接，不依赖侧边索引标题 |
## 5. 适配器实现侧的对齐与兼容策略
| API | 实际下发 | 与官方字段的关系 |
| --- | --- | --- |
| `adapter.napcat.message.send_poke` | `{"user_id": ..., "group_id"?: ..., "target_id"?: ...}` | 已对齐官方隐藏 schema；公开 API 额外保留 `qq_id` 作为旧版兼容别名 |
| `adapter.napcat.message.get_forward_msg` | 调 `get_forward_msg({"message_id"?: ..., "id"?: ...})` | 已对齐官方隐藏 schema；至少提供一个字段，双字段同时传入时要求一致 |
| `adapter.napcat.file.get_record` | 调 `get_record({"file"?: ..., "file_id"?: ..., "out_format"?: ...})` | 已对齐官方隐藏 schema；默认 `out_format="wav"` 仅用于兼容旧行为 |
| `adapter.napcat.account.get_stranger_info` | `{"user_id": ..., "no_cache": ...}` | 已对齐官方隐藏 schema；`no_cache` 默认值为 `False` |
- 当前强类型封装 API 已无“缺少官方字段”的已知冲突项。
- 当前仍保留的兼容策略只有两类：`send_poke` 的 `qq_id` 旧版别名，以及 `get_record` 的 `out_format="wav"` 默认值。