妙言小智图片翻译

使用本 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。配置完成后，我会自动读取，不需要你每次翻译都输入。

处理用户请求的流程

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

支持语言

支持的源语言：

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

目标语言除了支持以上语言外，还支持 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 是“图片上无文字”的无需重试终态，必须跳过并缓存，不要重复提交。
• 如果某张图片超过大小限制或格式不支持，将该图片记录为失败，并继续处理剩余图片。
• 最终回复优先使用简洁摘要，不要默认向用户倾倒完整结构化对象，除非用户要求查看原始返回结果。