扩展运行机制

当你在扩展中调用 Clipboard.readText() 时，你的沙箱中不会发生任何操作——该调用被转发到主机，在主机经过权限检查后执行，然后返回结果。本页将解释其机制。

kkrpc：类型化双向 RPC

Kunkun 使用 kkrpc，一个类型安全的 RPC 层，用于主机↔扩展通信。它用编译时检查的方法名、参数和返回类型替换了字符串类型的通道，并且可以在任何传输层（Electron IPC、WebSocket、stdio、Worker postMessage）上工作。

每个 SDK 方法都是一个异步代理调用：

如果权限检查失败，Promise 会以类型化错误拒绝而不是返回值——你永远不会静默地获得部分访问权限。

HostAPI 代理：getHostAPI()

SDK 通过一个全局单例解析主机连接：

import { getHostAPI } from "@kunkunsh/sdk/runtime";
const host = getHostAPI(); // 类型化的 KunkunHostAPI 代理；如果尚未连接则抛出异常

两个设计要点使其健壮：

• 跨包的唯一实例。 连接存储在 globalThis.__kunkun_host_api__ 上，因此即使多个 @kunkunsh/sdk 副本被一起打包（主机 + 插件），它们共享一个主机连接。
• 错误在传输中存活。 像 DbError 这样的类型化错误在穿越 kkrpc 后在插件端被重新实例化，因此 error instanceof DbError 和 error.code 仍然有效。

你很少直接调用 getHostAPI()——友好的包装器（Clipboard、fs、db、showToast……）会替你调用。

启动信息：window.__kunkun__

在你的代码运行之前，主机会注入运行时元数据：

interface KunkunPluginBoot {
  pluginId: string
  installationId: string
  extensionIdentifier: string
  commandName: string
  runtimeKind: "custom-view" | "worker-view" | "node-view"
  apiVersion: string
  mode: "development" | "production"
  permissionScope: PermissionScope
  // ...
}

Custom-View：通过自定义协议的静态 SPA

Custom-view 扩展通过 kunkun-ext:// 协议加载到隔离的 BrowserWindow 中：

• 源隔离。 每个扩展获得唯一的源（kunkun-ext://{pluginId}），因此 Chromium 自动强制执行同源分离。
• 路径安全。 协议处理器拒绝符号链接逃逸和路径遍历，并对 SPA 路由回退到 index.html。
• 预加载通道白名单。 插件窗口使用仅允许为该窗口注入的确切 kkrpc 通道的预加载脚本——受信任应用的主通道被阻止。即使该过滤器被绕过，kkrpc 的发送者检查也会丢弃跨窗口消息。

Worker-View：React 在 Web Worker 中，主机渲染 UI

Worker-view（和 node-view）扩展不接触 DOM。你编写 React；一个自定义协调器（Uniview）将你的组件树序列化为 JSON；主机将每个节点映射到原生 Svelte 组件并渲染它。事件处理程序变成 ID，被回调回 Worker 中。

这就是为什么 worker-view 组件从 @kunkunsh/sdk/ui 导入原语（Button、List、Form……）而不是使用原始 HTML：这些原语是主机知道如何渲染的内容。这也是为什么你的构建必须打包成单个文件并使用 dedupeReact()——两个 React 副本会破坏协调器。

Node-view 使用完全相同的 UI 模型，但工作进程是 Node.js/Deno 进程而不是 Web Worker，因此你还可以获得 fs、shell、原生模块和完整的网络访问（需经权限检查）。

各模式的运行位置

参见扩展类型进行选择，以及权限了解各运行时的沙箱机制。