MeowID 接入中大猫谱

本教程适用于已经提供“识猫服务”入口的中大猫谱及其衍生校园猫谱，直接从 MeowID 平台配置和小程序操作开始。

开始前，请准备：

• 一个可登录的 MeowID 控制台账号，可以创建项目和 API Key。
• 中大猫谱的 Level-99 管理员账号，用于保存服务配置及同步数据。
• 已有的猫咪档案及审核通过的照片，用于登记和验证识别。

完成后，使用者可以在原小程序中拍照查找相似猫咪，并进入原有猫咪档案。首次操作建议先选择少量猫咪和清晰单猫照片，核对结果后再同步更多历史照片。

1. 打开 MeowID 控制台并登录，创建一个用于校园猫谱的项目。
2. 进入项目详情，复制项目 ID，后面填写到小程序的“项目编号”。
3. 在控制台确认可用余额与当前计费规则，按需充值；登记照片和识别可能产生用量。

一个猫谱应持续使用同一个 MeowID 项目。后续同步会为本地猫咪建立对应的远端个体，不需要先手工逐只创建猫咪。

进入控制台的 API Keys，选择刚创建的同一个项目，创建接入使用的 Key。权限选“完整访问”，或使用自定义权限并勾选下面四项。

仅识别权限不足以完成本教程的同步流程。保存完整 Key，创建后通常只显示一次。将 Key 填入下一步的“服务配置”，不要公开分享或放进截图。

1. 以 Level-99 管理员登录，进入关于 → 小程序配置 → 识猫服务。低等级管理员不会显示此入口。
2. “识猫模式”选择 MeowID，点击“保存识猫模式”。
3. 在“服务配置”中填入项目编号、API Key 和接口根地址；默认根地址为 https://platform.meowid.net，不要填写官网文档地址 https://meowid.net/developers。
4. 识别候选数量可先保留 5，点击“保存配置”，再点击“检查连接”。

项目编号和 API Key 必须来自同一个 MeowID 项目。已保存的 Key 不会回显，输入框留空表示保留原值；不要因为输入框为空就认为密钥没有保存。

截图使用实际校园猫谱界面，示例名称与数量不要求与你的项目一致。候选数量控制识别结果返回多少只相似猫咪，和下一步的“每猫图片上限”是两项独立设置。

在“数据同步”中选择同步方式。两种方式都会同步猫咪档案，并跳过已有受理凭证的照片；都只上传审核通过的照片，不要求精选。

第一次接入可先用“按上限同步”控制历史图片用量。某只猫只有 3 张审核照片时，实际上传 3 张，不会为凑满 5 张而重复提交；没有审核照片时只同步档案。降低上限也不会删除已上传图片。

同步期间保持页面打开；离开页面后不会继续发起新批次，已经提交的云端批次可能仍在执行。再次选择同一种方式可以继续。无需清空原同步记录，也不要根据平台总图片数与本地数量的差值强行重传。

“猫咪：已同步 / 剩余”统计本地档案的远端关联；“图片：已上传 / 剩余”统计审核照片中已有平台受理记录的数量。每组已同步（或已上传）加剩余等于总数。

已上传不等于注册完成。照片提交后还需要裁剪、特征提取等处理。打开 MeowID 项目的“任务队列”核对：

• queued / running：已受理，仍在排队或处理中。
• completed：本次登记任务处理完成；建议以此时的可用登记图片验证识别。
• waiting_user：需要在 MeowID 控制台确认目标猫咪。
• failed：查看具体错误；已有回执的失败任务不会被当作新照片反复上传。

“剩余图片”也可能包含上限暂缓、明确失败、上传结果待核对的记录，不全都适合直接重传。小程序的本地猫咪关联数与平台手工创建的猫咪总数也可能不同。

1. 选一只已在本地关联且拥有可用登记图片的猫咪，准备一张清晰的单猫照片；验证时尽量使用另一张照片。
2. 回到小程序“猫谱”页，点击搜索框右侧的识别，拍照或从相册选图。
3. 查看相似猫咪列表，点击候选进入本地猫咪档案，确认姓名、照片和档案链接正确。

MeowID 返回相似猫咪后，小程序会展示已关联的本地档案。核对候选是否正确时，请结合猫咪姓名、照片与外观特征判断。

相似度用于候选排序，不代表识别正确率。没有检测到猫、检测到但身份未确认、服务请求失败是不同情况。多猫照片可切换候选；切换会重新请求识别并可能产生用量。第一次验证先用单猫照片更容易核对。

启用 MeowID 后，新增照片在管理员审核通过后直接尝试上传，不受手动批次的每猫上限限制。项目正有同步批次或上传未完成时，审核记录仍可保存；之后在识猫服务页继续补传。

• 同步期间保留已有同步记录，直接点击相应按钮继续，不需要重新创建猫咪档案。
• 上传结果待核对时，先到 MeowID 任务队列确认处理结果，不要直接再传一次。
• 避免把同一张照片重复添加为多条照片记录；记录不同的重复照片仍可能被分别提交。
• 更换项目或 Key 前，先核对项目归属；同一猫谱尽量持续使用同一个 MeowID 项目。

继续阅读 API 文档、MeowID 控制台图文教程。反馈问题时可提供提示截图、任务编号和发生时间，不要公开 API Key。