用途
Media Library 技能用于在用户的照片库中查找照片,包括 Jarvis 上传的媒体库以及通过设备连接的相册。它适合处理照片请求,或在回答问题时需要用照片作为依据或个性化内容。
media-library CLI 只覆盖已上传的照片;设备相册需要通过设备命令另行搜索。
主要能力
设备照片
当用户明确要求查看相册,或已上传/附加的图片不足以满足个人照片请求时,可以搜索已连接的相册。流程包括:
- 发现设备:调用 device.list,再调用 device.describe。选择可访问且命令中声明支持 photos.search 的设备,优先用户指定的设备,其次 is_request_origin,再次其他手机。存在歧义时需澄清。
- 搜索:调用 photos.search,使用其声明的过滤器缩小范围;相册即文件夹。尊重权限拒绝,在所需设置成功后重试。遵循分页,覆盖不完整时报告不完整,而不是声称没有匹配。
- 上传:搜索返回元数据。如需查看或比较,使用声明的命令上传候选照片。等待完成并考虑部分失败;接受请求不等于完成。
- 定位:完成后运行
/opt/hatch/bin/media-library recent --limit 20获取路径/ID。将拍摄日期、文件名和 GPS 与设备结果匹配;使用 get 获取详情,用日期/GPS 搜索查找更旧或已上传的照片。仅凭文件名或时间新近不能证明身份。自信匹配后读取图像;不确定时报告不确定,而不是猜测路径。
已上传照片工具
通过 exec 运行 /opt/hatch/bin/media-library <subcommand> [options]。子命令包括:
stats:库概览(总数、日期范围、描述状态)。search [--query "<terms>"] [--after YYYY-MM-DD] [--before YYYY-MM-DD] [--lat <f64>] [--long <f64>] [--radius <km>] [--has-gps] [--path <prefix>] [--limit N]:有 --query 时使用 FTS 按 BM25 排序;否则按拍摄日期结构化过滤排序。recent [--limit N]:按上传时间返回最新上传(默认 20,最大 50)。scan [--ids <id1,id2,...>] [--query "<terms>"] [--after YYYY-MM-DD] [--before YYYY-MM-DD] [--limit N]:返回更丰富的摘要和完整描述;至少需要一个缩小范围的选项(上述任一标志,包括单独 --limit)。get <media_id>:获取单张照片的完整详情(JSON)。
输出约定:
stats:纯文本,包含 Total photos、Date range 和描述状态计数(ready、pending、failed、rejected)。search:每行格式为<media_id> | <path> | <date> | [<location> |] <summary_short>,下方可选 match 片段。recent:与 search 相同的紧凑格式,不含 match 片段。scan:每项文本块包含 media_id、path、date、location、summary、detail。get:JSON,包含 media_id、rel_path、mime_type、size_bytes、taken_at_local、taken_at_local_date、gps_latitude、gps_longitude、location_text、location_json、exif_json、description_status、description(嵌套 summary_short、summary_full、people_text、activity_text、objects_text、ocr_text、location_hint_text)。
结果中的 path 字段相对于主目录。
使用方式
建议工作流:首次使用先 stats → search 或 recent → 对候选使用 scan 获取更丰富详情 → get 获取完整信息 → 仅当用户想查看或描述不足时读取图像。大多数查询可仅凭描述回答。
stats 解读:总数为 0 表示上传库为空或尚未设置,简要说明并检查可用设备相册;总数较低(约 20 以下)提示库较小;大量 pending 意味着文本搜索会遗漏未描述项,优先使用 recent 或日期过滤搜索。
使用强度:当媒体库可能有助于回答问题时,快速探测(stats 加 search 或 recent),无有用结果则继续;当用户明确要求查找、展示、识别、确定日期或定位照片时,将媒体库作为主要来源,用多次搜索、scan 和 get 反复尝试。已上传库搜索是本地 PostgreSQL 查询,通常毫秒级,可放心运行多种查询。
FTS 语义:裸词以隐式 OR 连接,按 BM25 排序(匹配词越多排名越高)。支持 AND/OR/NOT。词在去除标点后做前缀匹配。增加 OR 词会扩大而非缩小结果;要缩小请用 AND、日期过滤或 GPS 过滤。
先使用用户的原话,直接查询不足或结果不相关时,再用同义词、记忆或对话上下文、相关词扩展。
位置:搜索索引包含地理编码的城市/县、州和国家名称,search --query "Tokyo" 可用。GPS 邻近搜索可先调用 map.geocode 获取坐标,再用 search --lat <lat> --long <lon> --radius <km>,半径尺度:0.1 为地点,5 为街区,50 为都市区。
人物:使用物理描述(如“穿红裙的女士”),而非姓名。
记忆:用户提到事件或旅行时,交叉参考记忆中的日期和位置。
找到特定照片时,展示结果并确认是否正确。
适用场景
- 用户要求查找、展示、识别、确定日期或定位某张照片。
- 回答问题时需要用个人照片作为依据或个性化内容。
- 在已上传媒体库或连接设备相册中按关键词、日期、位置筛选照片。
限制
- media-library CLI 仅处理已上传照片;设备相册需通过设备命令搜索。
- 设备搜索依赖设备可访问并声明支持 photos.search。
- 需遵守权限拒绝,并在设置成功后重试。
- 分页覆盖不完整时应报告不完整,不能声称无匹配。
- 文件名或时间新近不能单独证明照片身份;不确定时应报告不确定。
- 大量描述 pending 时文本搜索可能遗漏。
- 仅凭描述可能不足以回答,需要时读取图像。
- 收费、价格、平台支持等细节暂未提供。