用途
本技能面向使用 Kernel TypeScript SDK（@onkernel/sdk）构建浏览器自动化应用的场景。触发条件包括：编写或扩展 import @onkernel/sdk 或构造 new Kernel(...) 的 TypeScript 代码；通过 kernel.browsers.create、cdp_ws_url、kernel.browsers.playwright.execute、kernel.browsers.computer.、kernel.browsers.repl、kernel.browsers.webmcp.、kernel.browsers.process.* 驱动 Kernel 浏览器；用 kernel deploy 部署 Kernel App 并通过 kernel.invocations.create（同步或配合 invocations.follow 异步）调用；把 Playwright、Stagehand、Browser Use、Claude Agent SDK、Vibium、Notte、Magnitude、Laminar 或 Val Town 接入 Kernel 浏览器；使用 profiles、浏览器池（browserPools）、vaults/credentials 或 replays 与文件 I/O；通过 auth.connections.* 与 React 的 <KernelManagedAuth /> 组件实现 Managed Auth；用 projectID 客户端选项或 CLI 的 --project / KERNEL_PROJECT 为项目限定 KERNEL_API_KEY 或 CLI 请求作用域；以及调试 Kernel 特有的故障（如 browser.close() 未清理、同步调用 100 秒超时、默认上下文混淆、409 profile 冲突）。
不适用：用 agent-browser CLI 终端驱动（agent-browser -p kernel、@ref 快照、snapshot -i --json，见 run-agent-browser）；Python Kernel SDK 或 Browser Use 的 Python 框架；非 Kernel 专用的 LangChain.js / LangGraph 代理（见 build-langchain-ts-app）。
两种运行模式
模式 A（Embed）：由自有服务驱动 Kernel，代码在自有仓库，调用形式为 new Kernel() → browsers.create → CDP / playwright.execute / computer.* / repl / webmcp.* / process.*。
模式 B（Deploy）：长时间运行、与浏览器同址的动作，追求零 CDP 延迟或按调用隔离，代码为 Kernel App，通过 kernel deploy 部署，再以 kernel.invocations.create({ app_name, action_name, version, payload }) 调用。
两者可混用：常见生产做法是把长时浏览器任务部署为 Kernel App，由嵌入服务调用。
基本术语
App：已部署的具名代码库，包含一个或多个 action。Action：app 内注册的具名函数。Deployment：创建或更新 app 版本的构建/版本事件。Invocation：一次 action 执行，invocations.create 必须提供 app_name、action_name、version 三项。
硬性规则
KERNEL_API_KEY 从环境变量读取，禁止硬编码；仅在省略 apiKey 选项时环境变量生效。固定 SDK 版本：@onkernel/sdk 由 Stainless 自动生成、迭代频繁，应固定次要版本范围，并以安装后的类型声明为准（node_modules/@onkernel/sdk/client.d.ts 与 resources/**/.d.ts），npm 包不附带 api.md。不要用 browser.close() 作为清理手段：Playwright/Puppeteer 的 close() 只断开本地 CDP 连接，应调用 kernel.browsers.deleteByID(session_id) 或依赖 timeout_seconds。同步调用上限约 100 秒，更长任务须用 async: true 配 async_timeout_seconds（10–3600）并用 invocations.follow(id)，事后切换需重新部署。仅使用默认浏览器上下文与页面：用 browser.contexts()[0] 与 pages()[0]，不要调用 newContext()/newPage()。项目作用域：以组织级 API key 通过 new Kernel({ projectID: '…' }) 限定项目，SDK 会在每个请求带上 X-Kernel-Project-Id；CLI 侧用 --project 或 KERNEL_PROJECT。运行时要求：TypeScript ≥ 4.9，支持现代浏览器、Node 20 LTS+、Deno 1.28+、Bun 1.0+、Cloudflare Workers、Vercel Edge Runtime、Jest 28+、Nitro v2.6+，不支持 React Native。载荷上限文档存在冲突（App 开发与 CLI 文档为 64 KB，调用文档为 4.5 MB），大对象应走 browsers.fs. 或对象存储。
默认立场
对任何非简单站点默认 stealth: true；timeout_seconds 以 300 秒起步（默认 60 秒过于激进）。需要实时查看、录制回放或 GPU 时用 headful，脚本化快速抓取用 headless（更便宜更快但更易被检测）。热路径优先用 kernel.browsers.playwright.execute(id, { code })，原始 CDP 留给长时交互会话。跨会话登录状态用 profiles，凭据属于终端用户时用 Managed Auth。同一 profile 在 save_changes: true 时只应有一个并行浏览器写入。浏览器在连接 CDP/WebDriver/实时查看客户端或有 computer.* 请求在途时视为“活跃”，空闲 5 秒后进入 standby（零计算成本），此后 timeout_seconds 才开始倒计时；GPU 浏览器不支持 standby。
使用方式
新项目可用脚手架脚本（脚本在生成时从 npm 取版本固定）：bash scripts/scaffold-kernel-app.sh --mode embed --dir ./kernel-embed-demo；随后 cd、npm install、导出 KERNEL_API_KEY、npm run check、npm run start。已有仓库则显式安装并固定范围：npm install @onkernel/sdk@^$(npm view @onkernel/sdk version) playwright 以及 npm install -D tsx typescript @types/node。首次创建浏览器必须先打印 session_id，完成后在 finally 中调用 kernel.browsers.deleteByID(session_id)。
版本与文档核对：改造前运行 scripts/check-kernel-sdk-version.sh；新仓库用 npm view @onkernel/sdk version dist-tags --json；已安装 SDK 读取其 .d.ts 声明（如 grep -nE '^ [a-zA-Z]+(' node_modules/@onkernel/sdk/resources/browsers/browsers.d.ts）。生成版 api.md 仅在源码仓库（https://github.com/kernel/kernel-node-sdk/blob/main/api.md），跟随 main 而非你的固定版本且不含仅库内辅助方法，冲突时以本地 .d.ts 为准。计费、Managed Auth、profiles、浏览器池、部署调用、载荷大小等以 https://www.kernel.sh/docs/llms.txt 及其链接页面为准。
成本预检
运行前应列出所有可能创建付费或配额资源的操作：browsers.create（尤其 headful、GPU、高分辨率视口、长 timeout、代理、扩展、profile 会话）、浏览器池创建/获取/未释放实例、App 部署与 invocations.create、Managed Auth 连接与登录会话、代理及需活跃浏览器才能读取的文件/回放产物，并为每项确定清理路径。实际配额可调用 await kernel.organization.limits.retrieve() 查看 max_concurrent_sessions、concurrent_sessions_used、vaults_used、max_vaults 等，项目级覆盖在 kernel.projects.limits.retrieve(idOrName)。
工作流与常见陷阱
步骤：判断运行模式；构造客户端（KERNEL_API_KEY 必填，另有 KERNEL_LOG、KERNEL_BASE_URL、KERNEL_CUSTOM_HEADERS 等可选；本地开发可传 environment: 'development', baseURL: null）；选择浏览器控制面（原始 CDP / 虚拟机内 Playwright / computer 控制 / browser-curl / REPL / WebMCP / 进程执行）；按需接入 profiles、浏览器池或 Managed Auth/Vaults；配对 create 与 deleteByID 并用 try/finally；最后运行或部署调用。
要点提示：不要假设 browser.close() 会终止 Kernel 浏览器；不要新建上下文来“隔离”；热路径用 playwright.execute 而非逐次 CDP 往返；长任务用 async 调用并显式设置 async_timeout_seconds；payload 需 JSON 可序列化；错误用 Kernel.APIError 子类判断；固定 SDK 次要版本；browser-curl 用 kernel.browsers.curl(id, { url }) 保留 TLS 指纹；项目作用域用 projectID 而非手写 defaultHeaders。此外，Stagehand v4 改经 CDP 接入并使用 Stagehand.create()（browser 必填，modelName 需带命名空间）；browsers.create 上 proxy_id 已弃用，改用类型化 proxy 对象；Region 支持 us-east、us-west、eu-west、ap-southeast（部分需 Start-Up 或 Enterprise 计划）；持久化 VM（persistent: true）已停止支持，改用 timeout_seconds + Profiles。