Kunkun Docs

多壳/核心设计使 Kunkun 保持可移植性——以及这对你的扩展意味着什么。

Kunkun 的决定性设计是它不是一款 Electron 应用。Electron 是当前的桌面壳——而非产品本身。同一个后端/核心被设计为今天可通过 Electron 运行，未来可通过 CLI/TUI、无头服务器、浏览器 UI 或原生壳运行——只需在边缘层替换适配器即可。

对于作为扩展作者的你来说，这有一个实际影响：你的扩展与类型化的 HostAPI 通信，而非 Electron。 它运行所在的主机是一个实现细节。你为桌面应用编写的 worker-view 扩展可以在同一个核心被 CLI 或浏览器驱动时，无需修改即可运行。

一个核心，多个壳

每个壳驱动同一个核心；扩展只看到一个受限的 HostAPI。

分层模型

无论你运行哪个壳，请求都流经相同的层次：

只有顶部（接口）和底部（适配器）层会随壳而变化。中间层——API 视图、业务逻辑、权限执行、插件运行时、数据库——是共享的且与壳无关。

端口与适配器

Kunkun 遵循严格的端口-适配器分离：

后端/核心负责业务逻辑、权限执行、插件编排、数据库和进程生命周期策略。
壳适配器负责平台相关事项：窗口、菜单、协议注册、操作系统钥匙串、原生剪贴板、进程派生、原生文件系统/监视器。
传输层是一种选择，而非业务逻辑的一部分。同一个核心方法可以通过 Electron IPC、WebSocket、stdio、Worker postMessage 或进程内调用访问。

贡献者经验法则

可移植的逻辑（模式、迁移、查询、验证、服务契约、插件编排、权限组合）应放在包中，而不是 apps/desktop/electron 中。Electron 文件应只包含真正需要 BrowserWindow、系统托盘、协议注册、操作系统钥匙串、原生对话框或进程派生的内容。

代码存放位置

包	职责	导入 Electron？
`@kunkunsh/core`	后端 API 实现、服务编排、权限组合	否
`@kunkunsh/db`	Drizzle 模式、迁移、可移植查询、客户端工厂	否
`@kunkunsh/sdk`	插件 SDK、清单模式、HostAPI 契约、运行时引导	否
`@kunkunsh/plugin-runtime`	无 Electron 的插件运行时原语 + 权限门控	否
`@kunkunsh/agent`	可移植 AI Agent 循环 + 提供商系统	否（仅外部 API）
`apps/desktop`	Electron 壳、SvelteKit 渲染器、原生适配器、传输层连接	是——仅此一处
`apps/cli`	CLI/TUI 壳、Effect 组合根、Hono/WebSocket 主机	否

调用者身份，而非隐式信任

每个 RPC 连接或进程内调用者都携带一个会话，描述谁在调用：

interface BackendSession {
  sessionId: string
  callerKind: "trusted-shell" | "plugin-view" | "plugin-worker" | "url-view" | "cli" | "browser-ui"
  installationId?: string
  extensionIdentifier?: string
  commandName?: string
  permissionScope: PermissionScope
  transport: KunkunTransportDescriptor
}

由此得出两条规则，这两条规则对扩展作者都很重要：

权限检查在每个敏感调用上执行，使用此会话——不仅在连接建立时。
插件身份由主机创建，绝不信任插件代码。 主机将 kkrpc 监听器绑定到你的窗口/工作线程，并从受信任状态构造你的 HostAPI。你无法冒充另一个扩展的标识符来访问其存储或权限。

不是单一 API——而是受限视图

不同的调用者获得不同的、受限的表面，这些表面由相同的共享实现模块构建：

API 视图	调用者	表面	执行方式
`KunkunShellAPI`	受信任的壳（Electron/CLI/浏览器 UI）	广泛	能力检查
`KunkunHostAPI`	插件视图 / 工作线程 / 后端	由清单 + 动态授予限制	完整权限执行
`KunkunUrlViewAPI`	URL 支持的页面	非常狭窄，默认禁用	默认拒绝

例如，剪贴板操作在共享的 clipboard-ops 模块中只存在一次。壳 API 直接调用它；插件 HostAPI 在委托给同一模块之前，用 clipboard-read 权限检查包装它。

这对你的意义

你导入 @kunkunsh/sdk 并调用类型化方法。在底层，这些调用是通过 kkrpc 消息发送到主机的。
你在清单中声明权限；主机强制执行它们。
由于核心是可移植的，不硬依赖于特定壳的扩展（例如 worker-view UI、服务、无头命令）可以跨主机运行——而最雄心勃勃的扩展可以同时作为 CLI 和插件发布。

知识图谱

每个文档页面及页面之间的交叉引用，以交互式力导向图的形式可视化。拖拽节点、缩放，点击任意页面进行导航。

下一步：扩展运行机制——kkrpc + HostAPI 机制详解。

架构