跳转到内容
Kabegame

插件开发指南

Kabegame 的抓取能力全部由插件提供。一个插件是一个自包含的文件夹，描述「去哪里取图」以及「怎么把图取回来」。本页帮你在 10 分钟内跑通一个插件的开发循环：从用 kabegame-cli 生成模板，到在运行中的 Kabegame 看到自己的改动。全程不需要克隆 Kabegame 的源码仓库。

插件用 JavaScript / TypeScript 编写，打包成 .kgpg 文件分发。脚本后端有两个：V8（默认，嵌入式 JS 引擎）与 WebView（真实浏览器窗口）。

什么是插件

一个插件告诉 Kabegame：

  • 在哪里取图：kbBaseUrl 入口，以及可选的登录 / 筛选参数。
  • 怎么取图：一段脚本（V8 或 WebView），负责遍历列表页、解析详情页、把图片 URL 交给下载器。
  • 怎么展示自己：图标、多语言名称与描述、标签，以及「采集」对话框里的表单项。

后端怎么选见 爬虫后端选择。简单说：能用 HTTP 请求 + 解析拿到数据就用 V8（也是唯一能在安卓上运行的后端）；只有目标站必须靠真实浏览器渲染、反爬或登录态时才用 WebView（仅桌面）。

插件目录骨架

每个插件是一个独立目录，放在哪里都可以。package.json 的 name 就是插件 ID：它决定插件的数据目录、图片记录上的 plugin_id、日志里的插件名，以及安装后的文件名 <ID>.kgpg。.kgpg 文件和目录叫什么都不影响 ID，但习惯上让三者一致。用户看到的插件名来自 name.zh、name.en 等多语言键，name 只在缺少对应语言时作为回退显示。ID 的规则见 打包与发布 · 插件 ID。

my-plugin/
├── package.json           # 必需：v3 自描述清单（元数据 + 配置 + 后端声明）
├── src/index.ts           # 源码（用 TS + plugin-sdk 编写）
├── dist/main.js           # 必需：package.json.main 指向的打包产物
├── icon.png               # 推荐：图标，打包进 KGPG 头部（HTTP Range 可读）
├── configs/               # 可选：推荐预设，出现在「预设」里
│   └── <preset>.json
├── providers/             # 可选：PathQL provider DSL（*.json5）
├── metadata_migrations/   # 可选：图片 metadata 迁移脚本
│   └── migrate.js
├── doc_root/              # 可选：用户文档，应用内渲染
│   ├── doc.md             #       默认语言
│   └── doc.<lang>.md      #       各语言覆盖（zh / en / ja / ko / zhtw）
├── templates/             # 可选：EJS 模板
│   └── description.ejs    #       在源管理详情面板渲染 metadata
└── README.md              # 可选：开发者自用说明，不会被应用读取

package.json（必需）

这是 KGPG v3 的自描述清单——元数据、后端、表单、标签全部内联在一个文件里（不再有独立的 manifest.json 或 config.json）。最小可用字段：

{
  "name": "my-plugin",              // 插件 ID，[a-zA-Z0-9_-]，≤64 字节；也是显示名回退
  "version": "1.0.0",              // 每段 ≤255
  "description": "插件描述",
  "author": "you",
  "kbPackageVersion": 3,           // 必须 ≥3
  "engines": { "kabegame": ">=4.3.0" },  // 最低 Kabegame 版本
  "main": "dist/main.js",          // 入口脚本相对路径
  "kbBackend": "v8",              // "v8" 或 "webview"
  "kbBaseUrl": "https://example.com",
  "kbConfig": []                   // 采集对话框表单变量
}
  • kbPackageVersion 必须为 3；低于 3 的旧格式已不再支持。
  • engines.kabegame 声明插件需要的最低应用版本（只支持 >=X.Y.Z 写法）。用到某个版本才有的接口时，把它抬高到那个版本——比如用了 kbLabels 或 Kabegame.requireCookie() 就要写 >=4.4.0。各能力的首次可用版本见 更新日志 的速查表。
  • name / description 支持以点号展平的多语言键，例如 "name.zh": "我的插件"、"description.ja": "..."。

完整字段（kbLabels、kbConfig、kbIcon、kbDoc 等）见 插件清单字段。

kbConfig（可选）

定义采集对话框里的表单项。用户填的值在 V8 脚本里通过 crawl(common, custom) 的 custom 参数读取（详见 V8 脚本），在 WebView 脚本里通过 Kabegame.vars 读取（详见 WebView 脚本）。

{
  "kbConfig": [
    {
      "key": "start",
      "type": "int",
      "name": "起始页面",
      "descripts": "要拉取的起始页面",
      "default": 1,
      "min": 1,
      "max": 5
    },
    {
      "key": "keyword",
      "type": "string",
      "name": "搜索关键词"
    }
  ]
}

支持的变量类型（int / float / string / date / boolean / options / list / checkbox / 路径类）、options / checkbox 的结构、when 条件显示等完整语义见 插件清单字段 · kbConfig。

一个最小 V8 脚本

V8 插件导出 async function crawl(common, custom)，宿主能力通过全局 Kabegame.* 提供：

export async function crawl(common, custom) {
  const baseUrl = common.base_url ?? "https://example.com";
  await Kabegame.to(`${baseUrl}/gallery`);


  const doc = await Kabegame.currentDocument();
  for (const img of doc?.querySelectorAll("img") ?? []) {
    const src = img.getAttribute("src");
    if (src) {
      await Kabegame.downloadImage(new URL(src, await Kabegame.currentUrl()).href);
    }
  }
}

Kabegame.* 的完整接口见 V8 脚本 与 Kabegame API 字典；URL 等 Web 平台全局与打包工具库分别见 V8 脚本 · 运行时全局 和 plugin-sdk 工具库。

开发循环

整个循环只依赖 kabegame-cli 和已安装的 Kabegame 应用。CLI 不随应用安装，先按 打包与发布 · 准备 kabegame-cli 从 GitHub Releases 下载与应用同版本的 CLI。

1. 生成模板

Terminal window
kabegame-cli plugin new my-plugin                    # V8 后端（默认）
kabegame-cli plugin new my-plugin --backend webview  # WebView 后端

V8 模板是 TypeScript 项目。在 Kabegame 源码仓库外开发时，要先把模板 package.json 里的 devDependencies 改成从 GitHub 安装类型声明，写法见 打包与发布 · 准备插件目录。

2. 构建并打包

Terminal window
cd my-plugin
npm install          # 首次
npm run build        # 产出 dist/main.js
kabegame-cli plugin pack --plugin-dir . --output ../my-plugin.kgpg

plugin pack 不会替你构建，改完源码要先 npm run build 再打包。

3. 试跑

Terminal window
kabegame-cli plugin run ../my-plugin.kgpg --id my-plugin-test --var key=value

路径模式只是这一次临时加载插件，不会安装。--id 换一个测试 ID，试跑数据就不会和正式安装的插件混在一起。CLI 在日志上方渲染一个常驻进度条。

Kabegame 应用正在运行时，CLI 会把任务交给应用执行，任务也会出现在应用的任务抽屉里，这时 WebView 插件也能跑；应用没有运行时，任务在 CLI 进程内执行，只支持 V8 后端。详见 命令行工具 · plugin run。

改完源码后重复第 2、3 步即可。

4. 装进应用

Terminal window
kabegame-cli plugin import ../my-plugin.kgpg

发布版 CLI 和应用共用同一个系统用户数据目录，装好后应用里就能看到这个插件。也可以直接把 .kgpg 拖进应用，见下文 在应用中导入插件。

打包与发布

交付插件就是把 plugin pack 打出的 .kgpg 交给用户：

  • 想进官方商店，把插件源码目录以 PR 提交到 官方插件仓库，由维护者统一打包发布；
  • 也可以自己托管 .kgpg 和一份 index.json，让用户在「源管理」里添加你的源。

打包规则、index.json 格式、版本号与用户何时看到更新，见 打包与发布。

从哪个插件开始读

官方插件仓库 里的插件都可以当参考实现。推荐阅读顺序：

  1. konachan：V8 后端、无需登录，覆盖 kbConfig 的 options / list / when、多语言文档、configs/、providers/、templates/description.ejs，与本页骨架几乎一一对应。
  2. pixiv：功能多也更复杂，需要登录 cookie（Kabegame.requireCookie()）、R18 判定和 kbLabels，熟悉基本流程后再看。
  3. xhs-webview：WebView 后端的参考实现，演示真实浏览器页面抓取、Kabegame.vars 读配置、跨页 updateState。

注意 konachan、pixiv 这类 TypeScript 插件的 devDependencies 指向 Kabegame 源码仓库里的相对路径，还用到了尚未发布到 npm 的 @kabegame/plugin-sdk，适合对照阅读；直接复制出来构建会失败。

在应用中导入插件

打包好的 .kgpg 可以：

  1. 双击 .kgpg 文件（仅桌面）。
  2. 把 .kgpg 拖到主窗口中（仅桌面）。
  3. 在「源管理」页点击「导入源」按钮（全平台）。

详情见 插件导入方法。

延伸阅读