用途:该技能通过文本查询在网络上查找公开图片,返回图片 URL 和来源页面,供 Feed、Artifact 及视觉参考使用。它是文本到图片的搜索,不是反向图片识别,不能用于根据用户提供的照片识别未知人物。
主要能力:使用捆绑的 CLI 按文本查询检索图片,可指定结果数量与结果语言。示例: /opt/hatch/bin/image-search "Golden Gate Bridge at sunset" --max-results 5 /opt/hatch/bin/image-search "Paris architecture" --max-results 5 --language fr CLI 返回结构化结果,并省略不可用字段。
结果字段:media_url 是公开源图片定位符,存在时为首选完整图片 URL;thumbnail_cdn_url 是可渲染的 CDN 预览,在缺少 media_url 时作为回退,应视为缓存 URL 而非唯一持久副本;media_handle 和 candidate_ref 是内部不可渲染字段,不应抓取、显示或当作图片 URL 传递;page_url 是来源页面,应保留用于溯源或署名。服务只返回含 media_url 或 thumbnail_cdn_url 的结果,两者都缺失的结果应忽略,并应选择最匹配请求的结果而非盲目取第一个。
使用方式与限制:该技能只返回定位符,不下载、上传,也不把图片转为 Muse 媒体引用。Feed 可使用合适的远程图片 URL;Artifact 若需持久本地副本,应通过其支持的媒体摄取路径传入所选定位符和来源页,不能把 CDN 缩略图当作永久存储。为 Artifact 选择下载安全的定位符时,应优先选择无 URL 凭据、查询字符串或片段的 HTTPS media_url,并保持结果顺序。抓取前应像浏览器一样预检,使用跨源 referer,并逐个候选抓取,设置连接与总超时。仅接受最终 2xx 且内容类型与文件魔数为图片的响应,然后复制字节到 Artifact 自有存储。优先 PNG 或 JPEG;WEBP 在 Word 文档中不可用,AVIF 在网页分享时会被拒绝且无法通过重试修复;HEIC 应转为 JPEG。应拒绝防盗链、过期、重定向、403/404、非图片、带水印或不稳定的 URL。若简单 media_url 均失败,可考虑带查询的 media_url 或 thumbnail_cdn_url,并逐字节使用返回的定位符,不得为简化而删除或改写查询字符串。搜索结果的预批准会记录返回定位符的精确路径与查询,因此逐字节使用它的普通 GET/HEAD 通常无需再次提示。抓取失败时不要反复重试或用无关本地图片替代。
适用场景:为 Feed、Artifact 和视觉参考查找公开图片及其来源页面。限制:不识别图片或人物,不负责下载与持久化,需自行处理媒体摄取与存储。