SpCat 插件开发指南

1. 快速开始

一个插件就是一个 zip 包，里面至少包含两个文件：

• info.json — 插件的「身份证」，告诉 SpCat 这个插件叫什么、做什么
• main.js — 插件的代码，实际干活的地方

文件结构
myplugin/
├── info.json      ← 必填
├── main.js        ← 必填
└── icon.png       ← 可选图标（128×128 PNG，显示在设置页和添加服务页）

图标 icon

插件图标有两种设置方式：

方式一：直接放 icon.png（推荐）

在插件根目录放一个 icon.png（建议 128×128 像素），SpCat 会自动识别。

方式二：在 info.json 里指定

在 info.json 里添加 "icon" 字段：

icon 字段
{
  "identifier": "com.example.myplugin",
  "name": "MyPlugin",
  "icon": "icon.png",              ← 插件包内的相对路径
  ...
}

内置图标一览

在 info.json 的 "icon" 字段填入编号即可使用。点击图标可复制编号。

打包

在插件文件夹里全选所有文件 → 压缩成 zip → 扩展名改成 .spcatplugin。

安装

1. 打开 设置 → 翻译（翻译插件）或 设置 → 识别（识别插件）
2. 点击 添加服务 → 安装插件…，选择你打包好的文件
3. 安装完成，服务列表里就能看到了

调试

选中你的插件后，页面上有 调试插件 按钮，点击打开插件调试控制台 —— 这是开发插件最常用的工具：

2. 测试插件下载 真实可用

下面提供了 6 个完整可运行的测试插件，覆盖翻译和识别两大类。直接下载安装即可验证插件系统。点击文件名可查看源码。

3. info.json 与 UI

安装插件后，SpCat 会读取 info.json，在设置面板右侧自动渲染配置页面。你不需要写任何 UI 代码。

对应关系一览

下表是 info.json 的顶层字段。其中 identifier、category 虽然不直接渲染 UI，但决定插件能否被正确识别、归类到对应页面，务必写对。完整的 info.json 内容还会以 $info 注入脚本，插件运行时可读取任意顶层字段（如 $info.identifier、$info.version）。

category：识别插件还是翻译插件

category 决定插件的「身份」，SpCat 据此把插件归入对应页面，并在加载时校验 main.js 的导出：

options 每一项的 type → 控件映射

options 支持的字段

动态预览：左边改 JSON，右边实时看 UI

试试修改左侧的 options，右边会实时渲染出设置面板的效果：

4. 识别插件模板 直接复制用

识别插件只需要导出 1 个必须函数。info.json 的写法见第 3 节。

必须导出的函数

ocr() 的 query 参数

调用 ocr(query, completion) 时，query 里包含截图信息。你需要从中取出图片数据发给你的 OCR API。

query 结构
query = {
  "image": {                         // 图片数据
    "base64":    "iVBORw0KGgo...",  // JPEG base64（无 data:image 前缀）
    "toBase64":  function() {...}     // 同上，调用返回 base64 字符串
  },
  "pixelWidth":  1920,              // 图片原始宽度（像素）
  "pixelHeight": 1080,              // 图片原始高度（像素）
  "options": {                       // 用户配置（和 $option 一样）
    "apiKey": "sk-xxx",
    "apiUrl": "https://..."
  }
}

ocr() 的 completion 回调

处理完毕后必须调用 completion() 把结果交给宿主。有两种调用方式：

✅ 识别成功

成功格式
completion({
  "result": {
    "from": "zh",               // 可选：识别出的语言码（如 API 有返回的话）
    "texts": [
      {
        "text": "识别出的文字",     // 必填：这一块的文字内容
        "boundingBox": {             // 可选：文字在图片中的位置（归一化 0~1）
          "points": [
            { "x": 0.1, "y": 0.2 },   // 左上
            { "x": 0.9, "y": 0.2 },   // 右上
            { "x": 0.9, "y": 0.8 },   // 右下
            { "x": 0.1, "y": 0.8 }    // 左下
          ]
        }
      },
      {
        "text": "第二块文字"        // 多块文字按顺序返回
      }
    ]
  }
});

📝 大模型识别：输出 Markdown

如果用大模型做 OCR（如 GPT-4o、Claude），API 返回的可能是 Markdown 格式。直接把 Markdown 内容放在 text 字段即可，不需要特殊处理：

Markdown 输出示例
async function ocr(query, completion) {
  const resp = await $http.request({
    url: "https://api.openai.com/v1/chat/completions",
    method: "POST",
    header: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + $option.apiKey
    },
    body: {
      model: "gpt-4o",
      messages: [{
        role: "user",
        content: [
          { type: "text", text: "识别图片中的文字，输出 Markdown 格式" },
          { type: "image_url", image_url: {
            url: "data:image/jpeg;base64," + query.image.base64
          }}
        ]
      }]
    }
  });

  const mdText = resp.data.choices[0].message.content;

  // 直接把整个 Markdown 放进一个 text 字段
  completion({ result: {
    texts: [{ text: mdText }]
  }});
}

❌ 识别失败

失败格式
completion({
  "error": {
    "type":    "api",         // 错误类型（见下表）
    "message": "请求失败",     // 必填：用户可见的错误描述
    "addition": "详细信息"     // 可选：附加说明（显示在括号里）
  }
});

$option 读取配置

info.json 里 options 声明的每一项，通过 $option.键名 读取：

$option 对应关系
// info.json 里声明:
//   "identifier": "apiKey"  →  $option.apiKey
//   "identifier": "apiUrl"  →  $option.apiUrl
//   "identifier": "mode"    →  $option.mode

const apiKey = $option.apiKey || "";  // 字符串，需要数字用 Number() 转换
const mode   = $option.mode   || "fast";

完整示例

方式一：JSON API（图片以 base64 发送）

main.js复制
async function ocr(query, completion) {
  const apiKey = $option.apiKey || "";

  try {
    const resp = await $http.request({
      url:    "https://api.example.com/v1/ocr",
      method: "POST",
      header: { "Content-Type": "application/json" },
      body: { image: query.image.base64, apiKey: apiKey },
      timeout: 30
    });

    const data = resp.data;
    if (resp.response.statusCode !== 200 || !data || !data.text) {
      completion({ error: { type: "api", message: "HTTP " + resp.response.statusCode } });
      return;
    }

    // 成功：把 API 返回的文字放进 texts 数组
    completion({ result: { texts: [{ text: data.text }] } });
  } catch (e) {
    completion({ error: { type: "network", message: String(e) } });
  }
}

方式二：文件上传（multipart，适合图片类 API）

main.js复制
async function ocr(query, completion) {
  try {
    // query.image 直接作为字节对象传给 files.data
    const resp = await $http.request({
      url:    "https://api.example.com/v1/ocr?token=xxx",  // 参数拼URL
      method: "POST",
      files: [{
        name: "file",            // 表单字段名
        filename: "image.jpg",  // 文件名
        "content-type": "image/jpeg",  // MIME类型
        data: query.image       // 字节对象，直接传
      }],
      timeout: 30
    });

    const data = resp.data;
    completion({ result: { texts: [{ text: data.text }] } });
  } catch (e) {
    completion({ error: { type: "network", message: String(e) } });
  }
}

5. 翻译插件模板 直接复制用

翻译插件需要导出 2 个必须函数。info.json 的写法见第 3 节。

必须导出的函数

supportLanguages 函数详解

• 同步函数，直接 return 一个字符串数组
• 数组里的每个值是 BCP-47 语言码（如 "en"、"zh-Hans"）
• 完整语言码表见第 8 节
• 只填你 API 实际支持的语言即可

supportLanguages 示例
function supportLanguages() {
  return [
    "zh-Hans",   // 中文简体
    "zh-Hant",   // 中文繁体
    "en",        // 英语
    "ja",        // 日语
    "ko",        // 韩语
    "fr",        // 法语
    "de",        // 德语
    "es",        // 西班牙语
    "it",        // 意大利语
    "pt",        // 葡萄牙语
    "ru",        // 俄语
    "ar",        // 阿拉伯语
    "vi",        // 越南语
    "th",        // 泰语
    "hi",        // 印地语
    "ms",        // 马来语
    "id",        // 印尼语
    "tr",        // 土耳其语
    "pl",        // 波兰语
    "nl",        // 荷兰语
    "uk",        // 乌克兰语
    "cs",        // 捷克语
    "sv",        // 瑞典语
    "el",        // 希腊语
    "fi",        // 芬兰语
    "he",        // 希伯来语
    "hu",        // 匈牙利语
    "nb",        // 挪威语
    "sk",        // 斯洛伐克语
    "sl",        // 斯洛文尼亚语
    "da"         // 丹麦语
  ];
}

translate() 的 query 参数

调用 translate(query, completion) 时，query 里包含翻译请求。你需要从中取出原文和语言信息发给你的翻译 API。

query 结构
query = {
  "text":  "Hello, world!",   // 待翻译的原文
  "from":  "en",               // 源语言码（如 "en"、"auto"）
  "to":    "zh-Hans",          // 目标语言码（如 "zh-Hans"）
  "options": {                  // 用户配置（和 $option 一样）
    "apiKey": "sk-xxx",
    "mode":   "fast"
  }
}

translate() 的 completion 回调

翻译完毕后必须调用 completion() 把结果交给宿主。有三种调用方式：

✅ 段落翻译（最常用）

按行返回译文，数组第 i 项对应原文第 i 行：

段落翻译格式
completion({
  "result": {
    "toParagraphs": [
      "你好，世界！"              // 如果原文只有一行，数组就一个元素
    ]
  }
});

多行原文对应多行译文：

多行示例
// 原文: "Hello\nWorld"
completion({
  "result": {
    "toParagraphs": ["你好", "世界"]
  }
});

✅ 词典翻译

返回「原文 → 译文」的键值对，适合词典类 API：

词典格式
completion({
  "result": {
    "toDict": {
      "apple":  "苹果",
      "banana": "香蕉",
      "bank":   "银行；河岸"  // 值可以带多义
    }
  }
});

❌ 翻译失败

失败格式
completion({
  "error": {
    "type":    "auth",         // 错误类型（见下表）
    "message": "API Key 无效",  // 必填：用户可见的错误描述
    "addition": "401Unauthorized"// 可选：附加说明（显示在括号里）
  }
});

$option 读取配置

和识别插件一样，通过 $option.键名 读取用户在设置面板填的值：

$option 对应关系
// info.json 里声明:
//   "identifier": "apiKey"  →  $option.apiKey
//   "identifier": "apiUrl"  →  $option.apiUrl
//   "identifier": "mode"    →  $option.mode

const apiKey = $option.apiKey || "";  // 字符串，需要数字用 Number() 转换
const apiUrl = $option.apiUrl || "https://api.example.com";
const mode   = $option.mode   || "fast";

完整示例

main.js复制
// 【函数1】告诉 SpCat 支持哪些语言
function supportLanguages() {
  return ["zh-Hans", "zh-Hant", "en", "ja", "ko", "fr", "de", "es"];
}

// 【函数2】执行翻译
async function translate(query, completion) {
  const apiKey = $option.apiKey || "";
  if (!apiKey) {
    completion({ error: { type: "param", message: "请在设置中填写 API Key" } });
    return;
  }

  try {
    const resp = await $http.request({
      url:    "https://api.example.com/v1/translate",
      method: "POST",
      header: { "Content-Type": "application/json", "Authorization": "Bearer " + apiKey },
      body: { text: query.text, from: query.from, to: query.to },
      timeout: 20
    });

    const data = resp.data;
    if (resp.response.statusCode !== 200 || !data || !data.translation) {
      completion({ error: { type: "api", message: "HTTP " + resp.response.statusCode } });
      return;
    }

    // 成功:返回段落数组
    completion({ result: { toParagraphs: [data.translation] } });
  } catch (e) {
    completion({ error: { type: "network", message: String(e) } });
  }
}

6. $http 网络请求

6 种请求方法

请求配置字段

body 三种形态

body 示例复制
// ① JSON 对象 — header 含 "application/json" → 自动 JSON.stringify
$http.request({
  url: "https://api.example.com/v1/translate",
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { text: "Hello", from: "en", to: "zh-Hans" }
});

// ② form-urlencoded — 不设 json header → 自动编码为 form
$http.request({
  url: "https://translate.googleapis.com/translate_a/single",
  method: "POST",
  body: { q: "Hello", sl: "en", tl: "zh-Hans" }
});

// ③ 字节对象 — 原始字节发送
$http.request({
  url: "https://api.example.com/v1/ocr",
  method: "POST",
  header: { "Content-Type": "application/octet-stream" },
  body: query.image   // 字节对象 {__bobBytes}
});

files 文件上传（multipart）

当 config.files 非空时，自动组装 multipart/form-data，跳过 body 处理。

files 结构复制
files: [{
  name:        "file",           ← 表单字段名（默认 "file"）
  filename:    "image.jpg",     ← 文件名（可选）
  "content-type": "image/jpeg",  ← MIME（默认 application/octet-stream）
  data:        byteObj          ← 字节对象 / {base64} / 字符串
}]

流式请求（streamRequest）

用于 SSE 等流式接口。增量数据通过 streamHandler({text}) 逐块推送，完成时调用 handler(resp) 收尾。

流式请求示例复制
let fullText = "";

$http.streamRequest({
  url:    "https://api.example.com/v1/translate-stream",
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { text: query.text, from: query.from, to: query.to },

  // 每收到一块数据就调用一次
  streamHandler(resp) {
    fullText += resp.text;
  },

  // 流结束后调用，提交最终结果
  handler(resp) {
    completion({ result: { toParagraphs: [fullText] } });
  }
});

响应对象

resp 结构
{
  data:        // JSON 响应 → 自动解析为对象；否则 → 字符串
  statusCode:  // HTTP 状态码（number）
  response: {
    statusCode: // 同上（插件通常读这里）
    header:     // 响应头
  }
}

两种调用风格

7. 可用能力速查

$file 沙盒文件读写

每个插件有独立的沙盒目录（$sandbox），位于插件自己的目录下（<插件目录>/sandbox），$file 只能操作沙盒内的文件，防止目录逃逸。

$data 数据转换

在字符串和字节对象之间转换。字节对象格式：{__bobBytes: "base64编码"}。

$pdf 图片转 PDF

在宿主侧（Qt）把图片生成 PDF，插件不必自己拼 PDF 结构。支持 JPEG / PNG / WebP / BMP / TIFF / GIF，自动按 EXIF 方向转正；传数组即多页（每张一页）。

图片 → PDF → 上传复制
// 生成（默认返回全 ASCII 文本，可直接当 $http 字符串 body）
const pdf = $pdf.imageToPdf(query.image);

// 当文件上传：bytes 形态配 files[] 最省事
await $http.post({
  url: "https://your.api/upload",
  files: [{ name: "file", filename: "doc.pdf",
            "content-type": "application/pdf",
            data: $pdf.imageToPdf(query.image, { format: "bytes" }) }]
});

require 内置模块 — crypto-js

内置 crypto-js 的 MD5 子集，主要用于 Google 翻译等需要签名的接口。

crypto-js MD5复制
const CryptoJS = require("crypto-js");
const hash = CryptoJS.MD5("hello").toString();  // → "5d41402abc4b2a76b9719d911017c592"

$log 日志输出

$log 用法
$log.info("调试信息");
$log.error("错误信息");
$log.debug("调试详情");
$log.warning("警告");

$image 图片转内联 data URI

识别结果里的图片常常是远程链接 —— 编辑器里不一定显示，而且会过期、正文不再自包含。内联成 data: URI 即可解决，标签形如：

内联图片标签
<img src="data:image/jpeg;base64,..." alt="image" width="300" height="200" origin-size="300,200" />

返回 { dataUri, mimeType, width, height, size, bytes }。mimeType 按文件头嗅探；bytes 可直接喂给 $http 的 files[] 或 $pdf。

把正文里的远程图片批量内联复制
// 并发下载，单张失败保留原链接即可（不要因为一张图丢掉整篇结果）
const jobs = urls.map(u => $image.toDataUri(u).catch(() => null));
const got = (await Promise.all(jobs)).filter(Boolean);

setTimeout 定时器

QuickJS 标准库不含定时器，由宿主提供。配合 $http（同样是异步的）即可实现轮询、超时重试、限流等。

轮询任务状态复制
const waitMs = ms => new Promise(r => setTimeout(r, ms));

while (true) {
  const resp = await $http.post({ url: statusUrl, body: { id } });
  if (resp.data.status === 2) break;
  await waitMs(1500);   // 每次等待都让出主线程
}

异步执行与主线程

❌ 这些写法会卡死界面复制
// 这 1.5 秒里界面完全无响应，事件循环一次都不会跑
const t = Date.now();
while (Date.now() - t < 1500) { }

// 死等网络结果 —— 回调没有机会执行，必然死锁
while (!done) { }

completion 回调格式速查

详细的输入输出格式见第 4 节（识别）和第 5 节（翻译）。

8. 语言码映射

supportLanguages() 返回的语言码遵循 BCP-47 格式。宿主会自动转换界面上的中文语言名和插件码。

翻译模板里 supportLanguages() 的完整写法（按需增删）：

supportLanguages复制
function supportLanguages() {
  return [
    "zh-Hans",   // 中文简体
    "zh-Hant",   // 中文繁体
    "en",        // 英语
    "ja",        // 日语
    "ko",        // 韩语
    "fr",        // 法语
    "de",        // 德语
    "es",        // 西班牙语
    "it",        // 意大利语
    "pt",        // 葡萄牙语
    "ru",        // 俄语
    "ar",        // 阿拉伯语
    "vi",        // 越南语
    "th",        // 泰语
    "hi",        // 印地语
    "ms",        // 马来语
    "id",        // 印尼语
    "tr",        // 土耳其语
    "pl",        // 波兰语
    "nl",        // 荷兰语
    "uk",        // 乌克兰语
    "cs",        // 捷克语
    "sv",        // 瑞典语
    "el",        // 希腊语
    "fi",        // 芬兰语
    "he",        // 希伯来语
    "hu",        // 匈牙利语
    "nb",        // 挪威语
    "sk",        // 斯洛伐克语
    "sl",        // 斯洛文尼亚语
    "da"         // 丹麦语
  ];
}

完整语言码对照表

9. 常见问题