跳转到内容
Kabegame

plugin-sdk 工具库

@kabegame/plugin-sdk 是一个打包进插件产物的 npm 工具库，提供 URL 解析、正则、md5、类型声明等纯工具。

SDK 主要服务 V8 后端（用 TypeScript 写在 src/，打包成单个 dist/main.js）。WebView 后端有真实浏览器环境，通常直接用原生 API，用到的 SDK 较少。

安装与使用

仓库内的插件已把 @kabegame/plugin-sdk 作为 workspace 依赖。在插件源码里直接 import，打包器会把用到的部分内联进产物：

import { type kbCrawlFn, resolveUrl, sleep } from "@kabegame/plugin-sdk";


export const crawl = (async (common, custom) => {
  await Kabegame.to("https://example.test/posts");
  await sleep(1000);
  await Kabegame.downloadImage(await resolveUrl("/image.jpg"));
}) satisfies kbCrawlFn;

URL

resolveUrl

两个重载：

resolveUrl(relative: string, base: string): string             // 同步，相对显式 base 解析
resolveUrl(relative: string): Promise<string>                  // 异步，相对 Kabegame.currentUrl() 解析
  • 给了 base → 同步返回 new URL(relative, base).toString()。
  • 不给 base → 异步，相对当前页面 URL解析（内部读 Kabegame.currentUrl()）；当前 URL 不可用时原样返回 relative。
const a = resolveUrl("/images/o.jpg", "https://example.test/post/1");  // 同步
const b = await resolveUrl(href);                                       // 相对当前页

时间与延时（misc）

unixTimeMs(): number                            // = Date.now()
randF64(min = 0, max = 1): number               // [min, max) 随机浮点
sleep(ms: number): Promise<void>                // 至少等待 ms（用 Web timer，无需 Node API）
await sleep(randF64(500, 1500));  // 随机退避

正则（regex）

不抛异常的正则工具，适合处理来自插件配置的模式串（非法模式返回安全默认值而非报错）：

reIsMatch(pattern: string | RegExp, text: string): boolean
reReplaceAll(pattern: string | RegExp, replacement: string, text: string): string
reFindAll(pattern: string | RegExp, text: string): KbRegexMatch[]

reFindAll 返回的每个 KbRegexMatch：

interface KbRegexMatch {
  match: string;                       // 完整匹配文本
  captures: string[];                  // 位置捕获组（缺失归一化为空串）
  groups: Record<string, string>;      // 命名捕获组
  index: number;                       // 匹配在文本中的 0 基下标
}

哈希（md5）

md5(value: string): string            // 十六进制 md5，用于构造去重 key、签名参数等

TypeScript 类型

SDK 还导出用于给 crawl 加类型的辅助（纯类型，无运行时开销）：

类型说明
kbCrawlFn<CustomCfg>crawl 入口的签名：(common: KbCommonCfg, custom: CustomCfg) => void | Promise<void>。
KbCommonCfgcommon 的形状：{ base_url: string | null }。
kbCustomCfg<Fields>由字段列表构建 custom 的类型。
kbCfgField<K, T>描述一个 custom 字段（键 + 值类型）。
kbCfgInt / kbCfgStr / kbCfgBool / kbCfgDate / kbCfgList<T> / kbCfgOption<T> / kbCfgCheckbox各 kbConfig 变量类型对应的值类型。
JsonValue / JsonObject / JsonPrimitive可跨宿主边界的 JSON 值。

给 custom 加类型：

import type { kbCfgField, kbCfgInt, kbCfgStr, kbCustomCfg, KbCommonCfg } from "@kabegame/plugin-sdk";


type Cfg = kbCustomCfg<[
  kbCfgField<"startPage", kbCfgInt>,
  kbCfgField<"tag", kbCfgStr>,
]>;


export async function crawl(common: KbCommonCfg, custom: Cfg) {
  const startPage = custom.startPage ?? 1;   // 默认每个字段还接受 null
  const tag = custom.tag ?? "";
}

延伸阅读