linkfox-multimodal-recognize-image

图像识别

本技能将指导你如何使用多模态图像识别 API 分析 URL 中的图像，并根据用户意图提取有意义的信息。

核心概念

图像识别工具接收图像 URL，以及可选的自然语言要求，用于描述用户想了解图像中的哪些信息。后端使用多模态 AI 模型解读视觉内容，并返回文本描述或分析结果。

支持的格式：JPG、JPEG、PNG、GIF、WebP、BMP。

工作原理：你提供一个可公开访问的图像 URL 和一项要求（你想从图像中了解的信息）。服务会下载图像、运行多模态分析，并返回基于文本的结果。

参数指南

参数	必填	说明
imageUrl	是	指向图像的可公开访问 URL。格式必须为 JPG、JPEG、PNG、GIF、WebP 或 BMP。最多 1000 个字符。
requirement	否	用自然语言描述要在图像中识别或分析的内容。省略时默认为 "Describe the content of this image"。最多 1000 个字符。

编写 requirement 参数的提示

1. 描述具体：不要只说“分析这张图像”，而要说“列出货架上可见的所有商品，并估算其类别。”
2. 说明目标：如果需要提取文本，请说“提取图像中的所有可见文本。”如果需要识别物体，请说“识别主要物体及其颜色。”
3. 适当提供上下文：对于商品图像，可以说明“这是一张电商商品列表图像”，以便模型据此调整分析方式。

上传本地图像

此工具需要可公开访问的图像 URL。如果用户提供的是本地图像文件路径（例如，C:\Users\...\photo.png、/home/.../image.jpg），你必须先上传该文件以获取公开 URL。

运行上传脚本：

python scripts/upload_image.py /path/to/local/image.png

脚本将返回一个公开 URL（有效期为 24 小时），可用作图像 URL 参数。

使用示例

1. 通用图像描述

• 用户说：“这张图片里有什么？”
• 将 imageUrl 设置为提供的 URL，并将 requirement 留空以使用默认值。

2. 商品图像分析

• 用户说：“分析这张 Amazon 商品图像，并列出图中展示的主要卖点。”
• 将 requirement 设置为：“这是一张 Amazon 商品列表图像。识别图中可见的商品、主要特征和卖点。”

3. 从图像中提取文本

• 用户说：“读出这张截图里的文字。”
• 将 requirement 设置为：“提取图像中的所有可见文本，并尽可能保留布局。”

4. A+ 页面图像审阅

• 用户说：“描述这张 A+ 内容图像传达了什么信息。”
• 将 requirement 设置为：“这是一张 Amazon A+ 商品描述图像。描述其视觉内容、主要信息和品牌元素。”

5. 比较／细节检查

• 用户说：“你能看出商品和包装之间有哪些不同吗？”
• 将 requirement 设置为：“识别并描述图像中商品与其包装之间的任何差异。”

调用方式

• API 端点：POST /multimodal/recognizeImage（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/multimodal_recognize_image.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-multimodal-recognize-image-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置 API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应 401 或 402 状态码
• 响应提示算力或余额不足：消息含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”，或类似含义的内容。

展示规则

1. 清晰展示分析结果：以易读的格式呈现返回的文本分析结果。根据内容酌情使用项目符号或段落。
2. 不得捏造内容：仅转述 API 实际返回的信息。不要添加响应中没有的视觉细节。
3. 格式支持：如果图片 URL 无效或格式不受支持，请说明限制并列出支持的格式（JPG、JPEG、PNG、GIF、WebP、BMP）。
4. 错误处理：当 API 返回错误状态时，根据响应说明问题并建议纠正措施（例如，检查 URL 是否可公开访问、确认图片格式）。
5. Token 用量：如果用户询问费用，可以提及响应中的 costToken 值。

用户表达与场景速查

适用——图片分析任务：

用户说法	场景
“这张图片/照片里有什么？”	一般图片描述
“分析这张产品图片”	产品视觉分析
“读取图片中的文字”	OCR / 文本提取
“描述 A+ 页面图片”	电商内容审核
“这个截图展示了什么？”	截图解读
“识别这张照片中的物体”	物体检测 / 列举

不适用——超出图像识别范围的需求： ``

• 生成或编辑图片
• 视频分析
• 分析本地文件路径中的图片（仅支持 URL）
• 图片搜索或反向图片搜索

算力消耗规则

按动态规则计费：消耗算力 = 输入消耗的算力 + 输出结果消耗的算力。

重要：本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。

反馈：

在以下任一情况下，通过 Feedback API 自动检测并提交反馈：

1. 本技能描述的功能或用途与实际行为不符
2. 本技能的结果与用户意图不符
3. 用户对本技能表示不满或称赞
4. 你认为有任何可以改进的地方

按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

---

如需更多高质量、专业的跨境电商技能，请设置 LinkFox Skills。