妙言小智图片翻译

使用本 skill 通过妙言小智图片翻译服务翻译图片中的文字。

妙言小智官方网站：https://www.pictech.cc
妙言小智API 服务域名：https://stableai.com.cn VK(APP KEY) 获取地址：https://www.pictech.cc/newpictech/skills/openclaw-image-translation-skill

VK 凭证规则

VK 是必需的 API 凭证。

必须优先从 skill/plugin 的持久配置中读取 VK，即 config.vk。
不要要求用户在每次图片翻译任务中都输入 VK。
不要把 VK 写入普通用户提示、聊天消息、日志、报告、文件名或返回摘要。
如果缺少 VK，告诉用户需要先在 skill/plugin 配置中填写一次 VK，然后重新执行任务。
只有在受控内部测试时才允许使用直接传入的 vk 字段；正式使用时优先使用 config.vk。

缺少 VK 时可以这样回复用户：

需要先在图片翻译 skill 的配置中填写一次 VK。配置完成后，我会自动读取，不需要你每次翻译都输入。

处理用户请求的流程

识别图片输入来源：
- 单个本地图片路径
- 包含图片的本地文件夹
- 一个或多个图片 URL
- 逗号分隔的多个路径或 URL
判断翻译语言方向：
- 默认源语言：中文
- 默认目标语言：英文
- 如果用户明确说明语言方向，使用用户指定的语言。
- 如果用户没有说明语言方向，使用默认值。
判断是否启用主图/主体保护：
- 默认值：false
- 当用户要求保护主商品、主体、主图、产品本体、Logo 区域或关键视觉元素不被翻译/修改时，设置 mainImageProtection: true。
判断保存目录：
- 如果用户指定了保存目录，使用用户指定的目录。
- 如果用户没有指定保存目录，让 index.js 使用默认结果目录。
使用结构化参数调用 skill 执行器。
根据返回的结构化结果向用户总结任务结果。

支持语言

支持的源语言：

中文
繁体中文
英文
泰语
俄语
印尼语
马来语
葡萄牙语
西班牙语
法语
德语

目标语言除了支持以上语言外，还支持 index.js 中映射到 API 的其他语言，例如：

韩语
意大利语
波兰语
荷兰语
土耳其语
越南语
菲律宾语

如果用户指定了不支持的源语言，需要说明当前支持的源语言列表，并请用户选择其中一种。

调用方式

从 index.js 导入默认导出的执行函数，并传入结构化参数。

单张图片示例：

await run({
    input: "C:/path/to/image.png",
    sourceLanguage: "中文",
    targetLanguage: "英文",
    mainImageProtection: false,
    saveDir: "C:/path/to/output",
    config: {
        vk: "<从 skill/plugin 持久配置中读取>"
    }
});

多张图片示例：

await run({
    input: [
        "C:/path/to/one.jpg",
        "C:/path/to/two.png",
        "https://example.com/three.webp"
    ],
    sourceLanguage: "中文",
    targetLanguage: "英文",
    mainImageProtection: true,
    config: {
        vk: "<从 skill/plugin 持久配置中读取>"
    }
});

文件夹示例：

await run({
    input: "C:/path/to/image-folder",
    sourceLanguage: "中文",
    targetLanguage: "英语",
    config: {
        vk: "<从 skill/plugin 持久配置中读取>"
    }
});

参数说明

input：必填。可以是本地图片路径、文件夹路径、图片 URL、路径/URL 数组，或逗号分隔的字符串。

config.vk：必填。必须来自 skill/plugin 的持久配置。

sourceLanguage：可选。默认值为 中文。

targetLanguage：可选。默认值为 英文。

mainImageProtection：可选。默认值为 false。

saveDir：可选。未提供时，执行器会保存到默认输出目录。

返回结果结构

执行器会返回适合大模型解析的结构化对象：

{
    success: true,
    status: "completed",
    message: "图片翻译完成，成功 1 个，无文字 0 个，失败 0 个，总计 1 个。",
    batchId: "batch_...",
    sourceLanguage: "中文",
    targetLanguage: "英文",
    sourceLanguageCode: "Chinese",
    targetLanguageCode: "English",
    mainImageProtection: false,
    saveDir: "C:/path/to/result/batch",
    counts: {
        total: 1,
        success: 1,
        noText: 0,
        failed: 0
    },
    results: [
        {
            taskId: "...",
            input: "C:/path/to/image.png",
            fileName: "image.png",
            resultUrl: "https://...",
            editorUrl: "https://...",
            localPath: "C:/path/to/result.png",
            fromCache: false
        }
    ],
    errors: [],
    skipped: []
}

无文字图片处理

后端 querytask 返回 data.status === 300 时，表示该图片上没有可翻译文字：

{
  "code": 200,
  "data": {
    "status": 300,
    "errorMessage": "图片上无文字 翻译失败，无需重试"
  }
}

Agent 必须把 300 当作终态处理：

不要继续轮询该任务
不要把该图片重新提交给 submittask
不要把它当作需要重试的普通失败
应记录为 no_text / skipped，并在本地缓存中标记，后续同图同语言方向直接跳过提交
最终统计中写入 counts.noText，并在 skipped 中说明原因
如果一批图片里只有无文字图片且没有真实失败，整体 status 可以是 completed

可能的 status 值：

completed：全部图片翻译成功
partial_success：部分图片成功或无文字跳过，部分图片失败
failed：所有已尝试图片均失败
no_tasks：没有找到可处理的有效图片任务
invalid_params：缺少必填参数
invalid_source_language：源语言不受支持
invalid_target_language：目标语言不受支持
missing_api_key：没有配置 VK

给用户的回复规范

任务成功时，向用户说明：

成功、无文字跳过和失败的图片数量
本地文件保存位置
可用的翻译结果预览链接
可用的在线编辑链接

不要暴露内部缓存 key、请求头、原始 VK、堆栈信息或完整 API 请求数据。

当 status 是 partial_success 时，先展示成功结果，再简要列出失败文件和失败原因。

当返回结果包含 skipped 或 counts.noText > 0 时，说明这些图片是“图片上无文字，无需重试”，不要建议用户再次提交这些图片。

当 status 是 missing_api_key 时，不要反复要求用户在对话里输入 VK。应提示用户到 skill/plugin 配置中填写一次 VK。

典型用户请求

把这张图片从中文翻译成英文
翻译这个文件夹里的所有商品图，中文到西班牙语
把这些图片 URL 翻译成英文，主图产品不要动
中文图片翻译成英语，结果保存到指定目录

可靠性要求

不要修改原始输入图片。
保留返回结果中的本地路径，方便用户找到文件。
将 URL 作为远程图片输入处理，将本地路径作为文件系统输入处理。
后端 status=300 是“图片上无文字”的无需重试终态，必须跳过并缓存，不要重复提交。
如果某张图片超过大小限制或格式不支持，将该图片记录为失败，并继续处理剩余图片。
最终回复优先使用简洁摘要，不要默认向用户倾倒完整结构化对象，除非用户要求查看原始返回结果。