Kun 扩展开发者文档

Extension API：v1（稳定） 适用 Kun：以 engines.kun 和兼容矩阵为准 English: Extension developer documentation

Kun 扩展（Extension）可以把工作台 UI、后台 Node 逻辑、Kun Agent 工作流、工具、账号认证和自定义模型 Provider 组合成一个可安装的 .kunx 应用。扩展通过公开 SDK 和能力 Broker 工作，不会获得 Kun 内部 AgentLoop、运行时令牌、Electron 私有 IPC 或完整的 window.kunGui。

Kun 始终只有一个 Agent runtime：kun serve。扩展调用 Agent，或 Kun 调用扩展工具/Provider，都经过同一个 runtime 的线程、审批、工具、事件和用量体系。Node 扩展可以在没有桌面 GUI 时由 kun serve 或受支持的 CLI 路径激活。

先选择正确的扩展机制

需求	应使用	是否执行代码	生命周期
工作台应用、后台服务、Agent 流程、完整模型 Provider	Kun Extension（本套文档）	可以，按入口和权限披露	Extension Host / Webview
只改变形象、图标或视觉资源	UI 外观包	否	现有 UI Plugin 流程
向 Agent 暴露外部工具服务	MCP Server	由 MCP 服务执行	现有 MCP 流程
提供提示、说明和可复用工作方法	Skill	通常不执行插件代码	现有 Skill 流程

这些系统彼此独立。安装 .kunx 不会迁移 UI 外观包、MCP 配置或 Skill；扩展也不应把它们复制进自己的私有格式。

推荐学习路径

1. 阅读架构与边界，理解 Node Host、Webview、Broker 和单 Kun runtime。
2. 按五分钟快速开始创建、测试、打包并侧载一个右侧栏扩展。
3. 用 Manifest 参考声明入口、贡献点、激活事件、权限和版本，并从 API 参考选择稳定 SDK 导出。
4. 用激活与生命周期正确注册和释放资源。
5. 根据用途选择工作台、Agent/工具、Provider/账号或资源 API 指南。
6. 发布前完成发布检查表。

指南索引

基础

• 架构与边界
• 五分钟快速开始
• Manifest 参考
• Extension API 参考
• 激活与生命周期

UI 与工作台

• 工作台贡献点、命令、设置与 UX
• Webview 与 Direct DOM

Kun 能力

• Agent Runs 与工具
• 模型 Provider、账号与认证
• 权限、信任、存储、网络、日志与配额

分发与维护

• 打包、侧载与自定义 Index
• CLI、测试与调试
• 版本、兼容与状态迁移
• 发布、故障排查与 API Changelog

稳定性边界

稳定范围仅包括：

• @kun/extension-api 的公开导出；
• @kun/extension-react 和 @kun/extension-test 的公开导出；
• 已发布的 Manifest/贡献点 JSON Schema；
• Host Context、Webview bridge、命令、上下文键、主题、locale 和状态 API；
• Agent、工具、Provider、账号、认证、存储和网络的公开契约；
• 文档明确列出的 CLI 命令、结构化输出和诊断代码。

不稳定且不受 SemVer 保护的范围包括：宿主 DOM、CSS 类、React 结构、renderer store、Electron IPC 名称、Kun 内部 HTTP/RPC、window.kunGui 和未导出的源码路径。尤其是 hostContentScripts 使用的选择器可能在 Kun 的补丁或次版本中变化；可行时应使用稳定贡献点和 Webview。

重要信任提示

• Node main 入口以当前操作系统用户权限运行。独立子进程提供故障和资源隔离，不是恶意代码安全沙箱。
• Webview 默认关闭 Node、启用 context isolation 和 Chromium sandbox，且禁止直接联网；网络应通过 Broker。
• Direct DOM 能读取和修改可见工作台内容，属于高风险、不稳定能力。
• 模型 Provider 会收到完整的模型可见请求，包括对话、指令、附件和工具 Schema。
• Webview 和 content script 永远不能取得原始账号秘密；Node 扩展只有在声明并获批专用 secret-read 权限后才能请求最小范围秘密。

只安装你信任来源的 Node 或 Direct DOM 扩展。签名是来源证据，不等于安全审计；未签名包可以侧载，但 Kun 会保留来源、摘要和权限确认记录。

文档与 Schema 的权威性

中文文件是行为规范主源，对应 .en.md 是英文版本。Manifest 和公开 wire payload 的字段、必填性与格式以同版本生成的 JSON Schema/TypeScript 类型为机器可执行真源；如果文档示例与 Schema 不一致，先使用 kun extension validate 确认，并把漂移报告为文档缺陷。

机器可读参考

• Manifest JSON Schema
• 生成的 Extension API 参考与导出快照
• @kun/extension-api 导出入口
• @kun/extension-react 导出入口
• @kun/extension-test 导出入口
• 六个可运行示例

发布构建生成的 .d.ts 是类型真源；本目录的独立 API 参考从公共 module symbols 和内存生成的声明快照派生。CI 会校验 Schema、双语 heading/代码块结构、JSON/TypeScript snippets、链接/anchors、SDK exports/type fingerprint 与 Changelog 未漂移，并对示例执行 typecheck、build、浏览器产物检查、Manifest 校验与 headless smoke test。