kernel-typescript-sdk

Kernel TypeScript SDK

何时使用此技能

使用此技能从 TypeScript 创建和自动化 Kernel 浏览器会话、通过配置文件持久保存浏览器状态、通过代理路由会话，或将自动化打包为 Kernel 操作。

对于一次性的 kernel ... 命令，请改用 kernel-cli 技能。

安装和初始化

npm install @onkernel/sdk
# Only CDP-based automation also needs a local Playwright client:
npm install playwright-core

import { Kernel } from "@onkernel/sdk";

const kernel = new Kernel(); // Reads KERNEL_API_KEY from the environment.

请求和响应字段使用 snake_case（timeout_seconds、session_id、cdp_ws_url）。SDK 方法使用 JavaScript 大小写形式（deleteByID、captureScreenshot）。

选择自动化方式

对于大多数自动化任务，优先使用服务端 Playwright，通过 kernel.browsers.playwright.execute() 执行。代码在浏览器旁运行，延迟低，且无需在本地安装 Playwright。

当本地库必须直接控制 Playwright，或需要交互式调试时，请使用 CDP 连接。使用 browser.cdp_ws_url 进行连接，并复用浏览器现有的上下文。

服务端 Playwright 生命周期

始终在 finally 中删除已创建的会话。空闲超时是安全措施，并非常规清理方式。

import { Kernel } from "@onkernel/sdk";

const kernel = new Kernel();
const session = await kernel.browsers.create({
  stealth: true,
  timeout_seconds: 300,
});

try {
  const response = await kernel.browsers.playwright.execute(session.session_id, {
    code: `
      await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
      return { title: await page.title(), url: page.url() };
    `,
    timeout_sec: 60,
  });

  if (!response.success) {
    throw new Error(response.error ?? response.stderr ?? "Playwright execution failed");
  }

  console.log(response.result);
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

在 code 中使用 return 填充 response.result。每次调用都会使用全新的执行上下文，因此请将有依赖关系的步骤放在同一次调用中，或返回后续调用所需的状态。

CDP 生命周期

关闭本地 CDP 客户端，然后删除 Kernel 会话，即使连接或自动化失败也不例外。

import { Kernel } from "@onkernel/sdk";
import { chromium } from "playwright-core";

const kernel = new Kernel();
const session = await kernel.browsers.create({ stealth: true, timeout_seconds: 300 });

try {
  const browser = await chromium.connectOverCDP(session.cdp_ws_url);
  try {
    const context = browser.contexts()[0];
    if (!context) throw new Error("Kernel browser has no default context");

    const page = context.pages()[0] ?? (await context.newPage());
    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

不要将 browser.close() 视为清理 Kernel 资源；务必调用 deleteByID()。

配置文件

先创建配置文件，再将其附加到会话。仅当此会话中的更改应在会话结束后保留时，才设置 save_changes: true。

const profile = await kernel.profiles.create({ name: "example-login" });
const session = await kernel.browsers.create({
  profile: { id: profile.id, save_changes: true },
  stealth: true,
});

try {
  // Authenticate or automate with playwright.execute or CDP.
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

对于长期运行的工作，优先使用配置文件 ID。浏览器按名称引用配置文件时，不要重命名该配置文件；否则可能导致会话更改无法保存。仅当配置文件是为临时测试数据创建时，才删除它，并且必须先删除其浏览器会话：

await kernel.profiles.delete(profile.id);

代理和直接连接

在创建会话时，通过 ID 附加现有代理：

const session = await kernel.browsers.create({
  stealth: true,
  proxy_id: process.env.KERNEL_PROXY_ID!,
});

当目标的可访问性很重要时，使用前请通过公开的 HTTP(S) 目标检查已配置的代理：

const checked = await kernel.proxies.check(process.env.KERNEL_PROXY_ID!, {
  url: "https://example.com",
});
if (checked.status === "unavailable") throw new Error("Proxy is unavailable");

对于正在运行的隐身会话，请清除显式代理并禁用 Kernel 的默认隐身代理，以直接连接：

await kernel.browsers.update(session.session_id, {
  proxy_id: "",
  disable_default_proxy: true,
});

设置 disable_default_proxy: false 可重新启用默认隐身代理。kernel.proxies.update(id, { name }) 仅会重命名代理；若要更改其类型或配置，请重新创建代理。只有在使用临时代理的所有会话都已删除后，才能删除这些代理。

二进制数据

不要从 playwright.execute 返回屏幕截图或文件字节。请使用专用的响应端点：

const screenshot = await kernel.browsers.computer.captureScreenshot(session.session_id);
const screenshotBuffer = Buffer.from(await screenshot.arrayBuffer());

const file = await kernel.browsers.fs.readFile(session.session_id, {
  path: "/tmp/output.pdf",
});
const fileBuffer = Buffer.from(await file.arrayBuffer());

清理规则

1. 每次创建浏览器会话后，立即使用 try/finally 包装。
2. 无论成功还是失败，都使用 kernel.browsers.deleteByID(session_id) 删除会话。
3. 对于 CDP，请先关闭本地客户端，再删除会话。
4. 只有在相关会话全部结束后，才能删除临时配置文件和代理。
5. 将凭据和代理密码保存在环境变量中；切勿将其写入源代码或日志。

参考资料

• Kernel 文档：https://www.kernel.sh/docs
• 快速入门指南：https://www.kernel.sh/docs/quickstart
• TypeScript 类型：使用 @onkernel/sdk 附带的声明和悬停文档
• 其他集成示例：示例