五分钟快速开始

July 15, 2026 · View on GitHub

Extension API：v1 English: Five-minute quick start 参考：Manifest · 生命周期 · CLI

本指南创建一个 React Webview 右侧栏扩展。你不需要 Kun 源码，也不需要使用 Electron 或 Kun 的内部 IPC。

1. 准备环境

需要：

  • 一个支持 Extension API v1 的 Kun 安装；
  • Kun CLI 可执行文件 kun；
  • 当前受支持的 Node.js LTS 和 npm；
  • 一个用于 Manifest 身份的 publisher，例如 acme。

先确认工具：

kun --version
kun extension --help
node --version

2. 创建项目

下面是独立项目的公网 registry 路径。先检查脚手架和模板依赖是否真的已发布：

npm view create-kun-extension version
npm view @kun/extension-api version
npm view @kun/extension-react version
npm view @kun/extension-test version

只有当前模板所需的命令都返回版本时才继续。E404 表示配置的 registry 还没有独立开发所需的产物，此时请使用仓库内的 扩展示例，不要把仓库相对 file: 路径写进 需要移植的项目。kun CLI 来自 Kun 安装；npm 上无 scope 的同名 kun 包不是 Kun Agent CLI。

npx create-kun-extension hello-sidebar \
  --template react \
  --publisher acme \
  --name hello-sidebar
cd hello-sidebar
npm install

可选模板为 node、webview 和 react。脚手架会生成最小权限 Manifest、独立 Node/Webview 入口（模板需要时）、build/test/validate/pack 脚本和对应版本的文档链接。

生成项目的核心布局类似：

hello-sidebar/
  kun-extension.json
  README.md
  LICENSE
  src/host/extension.ts
  src/webview/index.html
  src/webview/main.tsx
  package.json
  tsconfig.host.json
  tsconfig.webview.json
  vite.config.ts

构建产物目录和完整性文件由打包脚本生成，不要手工编辑最终 .kunx。

3. 理解最小 Manifest

React 模板会声明 Node 入口和 Webview 文档。下面是关键字段的缩略示例；以脚手架生成文件和同版本 JSON Schema 为准：

{
  "$schema": "https://kun.dev/schemas/extensions/manifest/v1.json",
  "manifestVersion": 1,
  "apiVersion": "1.0.0",
  "publisher": "acme",
  "name": "hello-sidebar",
  "version": "0.1.0",
  "displayName": "Hello Sidebar",
  "engines": { "kun": ">=0.1.0" },
  "main": "dist/extension.js",
  "browser": "dist/webview/index.html",
  "activationEvents": [
    "onView:hello"
  ],
  "contributes": {
    "commands": [
      { "id": "refresh", "title": "Refresh greeting" }
    ],
    "views.rightSidebar": [
      {
        "id": "hello",
        "title": "Hello",
        "entry": "dist/webview/index.html",
        "localResourceRoots": ["dist/webview"]
      }
    ]
  },
  "permissions": [
    "commands.register",
    "ui.views",
    "webview"
  ],
  "stateSchemaVersion": 1
}

扩展完整 ID 是不可变的 publisher.name，这里为 acme.hello-sidebar。贡献在宿主中解析为 extension:acme.hello-sidebar/hello；命令和其它注册项同样由宿主绑定到扩展命名空间，不要在 payload 中自报另一个扩展 ID。

4. 实现并释放资源

脚手架的 src/host/extension.ts 导出 activate(context)，并把注册返回的 Disposable 加入 context.subscriptions：

import type { ExtensionContext } from '@kun/extension-api'

export async function activate(context: ExtensionContext): Promise<void> {
  context.subscriptions.add(
    await context.commands.registerCommand('refresh', async () => {
      await context.ui.postMessage({
        channel: 'hello',
        payload: {
          type: 'greeting',
          text: 'Hello from the Kun Extension Host'
        }
      })
      return { accepted: true }
    })
  )
}

export async function deactivate(): Promise<void> {
  // context.subscriptions is disposed by the Host.
}

不要导入 Kun 源码、Electron、window.kunGui 或私有 HTTP/RPC。View 使用框架中立 bridge；React 模板通过 ExtensionViewProvider 和公开 Hooks 接收主题、locale、状态及消息。

5. 构建和测试

npm run build
npm test
npm run validate

validate 必须检查同一份生成 Schema、入口文件、贡献引用、权限、引擎/API 兼容和本地资源。修复所有 error；warning（例如已弃用 API 或 Direct DOM 风险）也应在发布前处理或明确接受。

开发测试不需要打包：

kun extension install --development .
kun extension reload acme.hello-sidebar
kun extension doctor acme.hello-sidebar

开发目录保持原位，不会复制到安装目录，也不会被 Kun 自动 reload。每次重新构建后显式执行 reload。如果本机 CLI 的参数形式有变化，以 kun extension <command> --help 显示的同版本语法为准。

6. 打包并侧载

npm run pack
kun extension install ./dist/acme.hello-sidebar-0.1.0.kunx
kun extension list
kun extension doctor acme.hello-sidebar

安装前，Kun 会在受保护窗口显示来源、ID、版本、SHA-256、签名状态、贡献和权限。Node 或 Direct DOM 权限会显示额外高风险说明。确认后才会原子安装并选择该版本。

打开 Kun，在 Code 模式右侧竖向图标栏中直接选择 Hello，Kun 会把它作为独立的右侧工作区标签打开。只渲染图标和标题不会激活 Node 入口；真正打开 View 时 onView:hello 才触发激活并建立一个身份绑定的 View Session。

7. 查看日志与清理

kun extension logs acme.hello-sidebar
kun extension disable acme.hello-sidebar
kun extension uninstall acme.hello-sidebar

卸载默认只删除包注册和代码，保留扩展状态、日志和账号引用。删除这些数据是另一个需要明确确认的操作。

下一步