mai-bot/plugin-templates/MaiBot-Napcat-Adapter/docs/verification.md

核验与兼容性说明

1. 这次核验做了什么

• 扫描 plugins/MaiBot-Napcat-Adapter/apis/*.py 中全部 @API(..., public=True) 公开接口。
• 对每个透传 API 反查其底层 NapCat action。
• 用 NapCat 官方文档 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	官方	左侧 Schema 只显示 object，同页示例请求体给出 no_cache	在文档中按 示例 记录 no_cache
_set_model_show	官方	左侧 Schema 只显示 object，同页示例请求体给出 model、model_show	在文档中按 示例 记录
get_mini_app_ark	官方	官方页为 Any Of 结构，但左侧 Schema 未展开可直接抄用的顶层字段	在文档中按同页示例请求体记录当前可见字段
get_guild_service_profile	官方	左侧 Schema 只显示 object，同页示例请求体给出 guild_id	在文档中按 示例 记录 guild_id
get_group_file_url	官方	左侧 Schema 只列 group_id、file_id，同页示例请求体额外给出 busid	在文档中按 Schema + 示例 合并记录
get_private_file_url	官方	左侧 Schema 只列 file_id，同页示例请求体额外给出 user_id	在文档中按 Schema + 示例 合并记录
test_download_stream	官方	左侧 Schema 当前字段为 error，同页示例请求体却使用 url	在文档中标记为 冲突，两组字段都写出
get_stranger_info	官方	页面默认示例只写 user_id，但原始 HTML 的隐藏 schema 还定义了 no_cache	在文档和实现中按隐藏 schema 记录 user_id、no_cache
get_forward_msg	官方	页面默认示例只写 message_id，但原始 HTML 的隐藏 schema 还定义了 id	在文档和实现中按隐藏 schema 同时支持 message_id、id
get_record	官方	页面默认示例只写 file、out_format，但原始 HTML 的隐藏 schema 还定义了 file_id	在文档和实现中按隐藏 schema 记录 file、file_id、out_format
send_poke	官方	页面默认示例只写 user_id，但原始 HTML 的隐藏 schema 还定义了 group_id、target_id	在文档和实现中按隐藏 schema 记录 user_id、group_id、target_id
send_group_sign	官方	官方页面存在，但侧边序列化索引缺少常规标题字段	文档直接写死官方链接，不依赖侧边索引标题
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" 默认值。