插件使用

插件（UI 中也叫「源」）是 Kabegame 从各个图站收集图片的能力单元。每个插件定义一套抓取逻辑、配置字段与文档。你在「源管理」页浏览商店、安装 / 更新 / 卸载，在「设置」页为插件保存默认参数，在「画廊」按「开始收集」时再按需覆写——三处职责清晰分工。

什么是插件？

插件文件格式

插件以 .kgpg 文件格式提供，本质上是一个 ZIP 压缩包，包含以下文件：

文件	必需	说明
package.json	是	插件元数据（名称、版本、描述、后端、配置变量、标签等）
入口脚本	是	爬取逻辑脚本（V8 或 WebView 后端的 JS/TS）
icon.png	否	插件图标
README.md	否	插件使用说明

插件更新后，如果新版本随包提供图片元数据迁移脚本，Kabegame 会自动迁移历史图片的插件元数据。

插件的类型

• 网络爬取插件：从在线网站爬取图片（如 Konachan、Anihonet 等）
• 本地导入插件：从本地文件系统导入图片（内置）
• 第三方插件：由其他作者发布、经第三方商店源分发的插件

如何获取插件？

• 从商店安装：在「源管理」页浏览官方或第三方商店源，选中后直接安装
• 手动导入：如果你有 .kgpg 文件，可通过拖入主窗口、双击文件、或源管理页的「导入源」按钮安装
• 自己编写：如果你想为自己写一个插件，请参考 开发者文档

---

源管理页导览

在侧边栏进入「源管理」，这里集中了所有与插件相关的浏览、安装与分发操作。页面顶部是 tab 栏，从左到右为：

• 「已安装源」：当前机器上已安装插件的清单，按卡片展示图标 / 名称 / 描述 / 版本 / 卸载按钮。
• 商店源 tab（按 source_id 动态生成）：每个商店源一个 tab。默认自带「官方 GitHub Releases 源」，你添加的第三方源也会各自占一个 tab。
• 「添加源」伪 tab：点击后弹出新增商店源对话框。

右上角 header 有若干操作入口：刷新（强制重拉商店列表）、导入源（选择本地 .kgpg）、管理源（Android / 折叠模式下用来管理商店源的对话框入口）。

注意

在 --mode web 的 Web 构建中，源管理页的安装 / 卸载 / 源编辑会被禁用，商店源管理对话框也会隐藏。这是预期行为。

已安装源 tab

每张卡片右下角是「卸载」按钮。点击后会弹出二次确认，确认后从磁盘清除插件包。若没有任何已安装插件，会显示一个「打开 GitHub 官方插件商店」按钮，点击直接跳到官方源 tab。

商店源 tab

进入商店 tab 时应用会优先读取本地缓存；缓存超过 24 小时会在后台静默重拉 index.json，若列表内容有变会弹「商店列表已自动更新」。若你想立刻看到最新版本，点 header 的刷新按钮强制重拉。

每张插件卡片根据本地状态显示不同的主按钮：

状态	按钮
未安装	「安装」
本地版本低于商店版本	「更新」，并在卡片上显示红色可更新标签
本地与商店版本相同	禁用的「已安装」
版本串异常 / 降级场景	「重新安装」

点击按钮会弹出确认对话框（带包大小提示），确认后按钮变为进度条「安装中 {percent}%」；完成后提示「安装成功」或「更新成功」，卡片状态自动同步。

添加 / 管理第三方商店源

点击「添加源」tab 或 header 的「管理源」，打开商店源管理对话框。新增源需要填：

• ID：留空会由后端生成 src_{timestamp}。
• 名称：显示在 tab 标签上。
• index.json URL：推荐指向 GitHub Releases 中的资产直链。

确认时应用会先远程校验 index.json 能否获取与解析；校验失败会提示「源验证失败」，你可以选择「仍然添加」或「返回修改」。保存后 tab 栏立即多出对应 tab。

要删除商店源，点 tab 标签右侧的叉号，或在管理对话框里点删除。

警告

删除第三方商店源会同时清掉该源下缓存的 .kgpg 下载文件；下次进入对应 tab 会重新从网络拉取。官方 GitHub Releases 源不可删除（UI 会直接隐藏删除按钮）。

---

导入本地 .kgpg

方法一：双击插件文件导入（仅桌面）

在资源管理器中直接双击 .kgpg 文件，会自动打开导入窗口。

注意

首次双击时，Windows 可能会询问「选择打开方式」，选择 Kabegame 即可。之后双击会自动关联。

方法二：拖入主窗口（仅桌面）

把 .kgpg 文件直接拖到主窗口中，应用会自动识别并导入。可以同时拖入多个插件文件。

方法三：从源管理页面导入

桌面：点 header 的「导入源」按钮 → 在文件选择对话框里选 .kgpg → 预览对话框显示版本信息 → 确认即成功。

Android：header 的「导入源」按钮会直接触发系统文件选择器（无中间对话框），选完自动导入。

导入时的版本处理

• 如果本地已存在相同 ID 且版本相同的插件，会提示「插件已存在（v{version}），无需重复导入」，不做任何更改。
• 如果版本不同（升级或降级），会提示「从 v? 变更为 v? 是否继续」，由你确认。
• 如果文件格式不正确（非 .kgpg），会提示「不支持的文件格式，请选择 .kgpg 文件」。

---

插件详情页

在任意插件卡片上点击会跳转到「源详情」页，它可以从两个入口进入：已安装源的卡片、商店源的卡片（后者会带上 sourceId 与版本号）。

页面顶部展示图标 / 名称 / 版本 / 最低应用版本 / baseUrl / 「复制插件ID」按钮与主操作按钮（安装或已安装）。下方是插件作者随包提供的文档渲染区——若该插件未提供文档，会显示「该插件未提供文档」。

警告

若插件声明的最低应用版本高于你当前安装的 Kabegame，详情页会展示阻止性提示「该插件需要 Kabegame {required} 或更高版本，当前为 {current}。请升级后再运行。」同时「开始收集」对话框也会拒绝使用该插件。

---

图片详情里的插件描述区

在画廊双击图片打开预览后，右侧详情面板（桌面）或底部详情区（Android）有时会出现一个由插件提供的描述区，展示作者信息、标签、原始画作链接等内容。这部分内容由插件作者随插件包附带，不是 Kabegame 自身提供的说明，不同插件展示的字段也各有不同。

点击描述区中的外部链接，会用系统浏览器打开，不会在 Kabegame 内部跳转。若某个插件没有提供此模板，描述区不会出现。

注意

描述区内容与「源详情」页（插件文档）是两处不同的展示：源详情页是安装前查看的插件使用说明，而图片详情里的描述区是该图片对应的原始元数据（如 Pixiv 作品信息）。

---

为插件配置默认参数

大多数用户真正使用插件的场景不在源管理页，而在「设置 → 爬虫插件默认配置」面板。这里你可以为每个已安装插件分别保存默认变量、HTTP 请求头与输出目录。之后在画廊的「开始收集」对话框或新建自动任务时选中该插件，表单会自动填入这些默认值；如遇字段不兼容仅回退对应项。

面板内容：

• 「选择插件」下拉：切换当前配置的对象。
• 输出目录（仅桌面）：留空则使用设置中的默认下载目录。Android 因无任意文件夹访问权限而隐藏此项。
• 插件变量区：按插件 package.json 的 kbConfig 定义的字段逐项渲染（文本 / 数字 / 下拉 / 开关 / 多选 / 路径等）。
• 高级设置 → HTTP 头：一张键值对编辑器，用于给爬虫请求与图片下载附带自定义 header（如 Authorization: Bearer xxx 或 Cookie: …）。注意这里的 header 只作用于 HTTP 请求，不会注入到插件脚本变量。
• 保存 / 重置：「保存默认配置」持久化；「重置为插件定义默认值」会弹二次确认后用 kbConfig 中的默认值覆盖当前保存。

另外本面板顶部还有「导入推荐配置时默认启用定时」开关：从插件包导入其自带的推荐运行配置时，是否默认启用定时；关闭后导入的配置需在任务列表中手动启用定时。

详见 设置。

---

登录态与 Cookie

Kabegame 没有插件级的登录入口——插件详情页没有「登录」按钮，设置里也没有「账号」概念。对需要登录的站点，走以下两种方式之一：

方式一：用「畅游」在内置浏览器里登录

在侧边栏进入「畅游」，输入站点 URL（如 https://www.pixiv.net）并点「开始畅游」，应用会打开一个内置 WebView，你在里面手动完成登录。Cookie 由 WebView 自动维护，结束会话后由后端写入畅游记录。适合把「登录后浏览 → 批量收集」放在畅游窗口里一次完成，详见 畅游。

注意

Linux 构建由于 WebKit 限制，畅游窗口仅能浏览，不能下载图片。

很多插件会自动用畅游 Cookie

自 4.4.0 起，V8 插件可以调用宿主接口 Kabegame.requireCookie() 自动把你在畅游里登录该站留下的 Cookie 注入到自己的请求中（Cookie 明文不会暴露给插件）。带有「需要 Cookie」标签的插件通常就是这么做的——你只需先在畅游里登录一次该站点，之后直接用插件收集即可，不必手动复制。下面的方式二是给不使用该机制的插件、或需要额外自定义头时的兜底做法。

方式二：把 Cookie 手动复制到插件的 HTTP 头

如果插件没有自动请求畅游 Cookie，或你需要附带别的鉴权头，可以手动复制。正确做法是：

1. 在「畅游」窗口登录目标站点 →「查看网站 Cookie」→ 复制 Cookie 字符串。
2. 回到「设置 → 爬虫插件默认配置」→ 选中对应插件 →「高级设置 → HTTP 头」→ 新增条目 Cookie: <粘贴>（或 Authorization: Bearer …）→ 保存。

之后该插件的请求就会带上这段 Cookie。

警告

Cookie 会随站点下发的过期时间失效。一旦插件开始返回 401 / 鉴权失败，回到畅游重新登录并把新的 Cookie 字符串粘回 HTTP 头即可——没有自动续期。

---

使用插件收集图片

打开收集对话框

在画廊页面，点击右上角的「开始收集」按钮（或空状态下的「开始导入」按钮），打开收集对话框。这是创建爬取任务的主要入口。

选择插件源

在收集对话框中，从「选择源」下拉菜单中挑选已安装的插件。

注意

如果下拉菜单为空，说明还没有安装任何插件。请先到插件商店安装插件。

配置插件变量

选择插件后，若该插件定义了配置变量，会在下方渲染出来。常见的配置类型包括：

类型	说明
文本输入	目标 URL、搜索关键词等
数字输入	页码、数量限制等（支持最小值/最大值限制）
下拉选择	从预设选项中选择
开关	布尔值配置
多选	列表或复选框类型
文件/文件夹路径	通过浏览按钮选择本地路径

若你在设置中为当前插件保存过默认配置，这些字段会预填。必填项会标注红色星号（*）。

设置输出目录和画册

• 输出目录：指定图片保存位置。留空则使用默认下载目录。
• 输出画册：选择将收集的图片添加到哪个画册，或选择「+ 新建画册」创建新画册。留空则仅添加到画廊。

保存运行配置（可选）

在运行配置下拉菜单中，可以保存当前的任务配置，方便下次复用。保存后下次创建任务可直接选中该配置，无需重新填写所有参数。

注意

如果插件版本更新导致历史运行配置不兼容，会显示「不兼容」标签，需要重新配置。

开始收集和查看进度

点击「开始收集」按钮创建任务。之后可在右下角任务抽屉中查看进度，任务状态包括：等待中、运行中、已完成、失败、已取消。详见 任务与下载。

---

平台差异

能力	Windows	macOS	Linux	Android
源管理页 / 安装 / 更新 / 卸载	支持	支持	支持	支持
双击或拖入 .kgpg 导入	支持	支持	支持	不适用
「导入源」按钮	打开文件对话框	打开文件对话框	打开文件对话框	打开系统选择器
插件默认配置：输出目录	支持	支持	支持	隐藏（系统限制）
插件默认配置：变量 / HTTP 头	支持	支持	支持	支持
畅游登录维护 Cookie	支持	支持	仅浏览，不能下载	支持

---

排障

现象：刚点了安装，但「已安装源」tab 里没出现。 原因：安装过程中出错或仍在下载。 操作：留意按钮上的进度条是否归零为「安装」——若是则点开重新安装；若弹出错误提示请查看提示内容（网络 / 校验失败等）。

现象：商店 tab 里看到的版本不是最新。 原因：商店列表有 24 小时缓存。 操作：点 header 的「刷新」按钮强制重拉 index.json。

现象：安装时提示「该插件需要 Kabegame X 或更高版本」。 原因：插件声明的最低应用版本高于当前版本。 操作：升级 Kabegame 后再安装，或换一个兼容的插件。

现象：在「收集」对话框选某插件时被拒，提示安卓不支持。 原因：WebView 后端插件需要真实浏览器窗口，安卓不支持（V8 后端插件在安卓可用）。 操作：在桌面端使用该 WebView 插件，或换一个同站点的 V8 插件。

现象：插件请求返回 401 / 403。 原因：缺少登录 Cookie 或 Cookie 已过期。 操作：在「畅游」重新登录目标站点并复制 Cookie，到「设置 → 爬虫插件默认配置」的 HTTP 头中更新。

---

延伸阅读

• 画廊：收集对话框的入口。
• 设置：插件默认配置面板。
• 畅游：内置 WebView 登录与 Cookie 查看。
• 任务与下载：收集任务的生命周期与进度查看。
• 开发者文档：想自己写一个插件？从这里开始。