技能介绍

解决的问题

MT Photos 自建图床提供了约 400 个 REST 端点，覆盖用户、相册、文件管理以及人脸、分类、OCR、CLIP 搜索等能力。但直接调用这些接口需要自己处理 x-api-key 鉴权、24 小时有效的 auth_code 缓存、multipart 上传、分页与 JSON 解析，还要区分管理员与普通用户 Key 的权限边界。对想用脚本自动化照片管理的工程师来说，这些胶水代码成本高且容易出错。

工作方式

技能封装为 Python 客户端 scripts/mtphotos_client.py，仅依赖标准库，无需 pip install。它按 7 大能力组织：A 用户管理（管理员）、B 文件夹与文件（管理员）、C 相册管理、D 图片/视频识别、E 图片/视频读取、F 图片/视频分析、G 批量管理。每个能力下提供对应方法，例如 list_users()、timeline()、search_clip()、batch_add_tags()。客户端自动处理鉴权、auth_code 获取与缓存、上传和 JSON 解析，同时提供 CLI 和可编程接口两种调用方式。

使用时先配置 base_url 与 api_key（支持环境变量、config.json 或命令行参数），再按权限选择 Key 类型。管理员 Key 可调用用户管理、文件夹管理、重复文件检测和后台任务；普通用户 Key 可管理相册、读取与分析个人图库。所有删除操作（如 delete_user、delete_folder、delete_files）强制二次确认：编程调用需显式传入 confirm=True，CLI 需加 --yes，AI 调用前必须向用户说明删除对象并取得同意。

适用边界与注意点

并非所有接口权限一致：重复文件检测和后台任务标注为非管理员能力，但实际接口要求管理员 Key，调用前需确认。gids（图库 ID）多值用下划线或逗号分隔，部分接口必传。取图接口返回二进制流，客户端已自动处理 auth_code 的 URL 编码。后台任务为异步，提交后需通过 /fileTask/jobs/* 查询进度。完整端点与参数见 references/api_reference.md。