人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本文围绕 Kun 开源仓库中 packages/extension-api/README.md 展开深入讲解 Kun 扩展开发所依赖的公共 SDK 包kun/extension-api如何在仓库内或独立项目中安装与构建、如何用ExtensionContext与ExtensionHostClient编写扩展、配置/认证/密钥如何分界以及ExtensionManifestSchema如何成为 Manifest JSON Schema 的运行时真源。读完本文你将掌握基于 Kun 扩展 API v1 编写、校验、测试和打包扩展的完整技术路径并理解其底层的 Host Transport 协议与版本协商机制。kun/extension-api是 Kun 扩展体系中的框架中立framework-neutral、稳定公共契约stable public contracts与 Host 客户端Host client包。它的核心承诺是不依赖 React 或 Electron扩展作者只需要面向这一层契约编程同时ExtensionManifestSchema作为schema/kun-extension.schema.json的规范运行时源canonical runtime source保证类型、运行时校验与 JSON Schema 三者始终同源一致。本文所有内容均可在当前仓库中直接核对包入口见 packages/extension-api/src/index.tsSchema 生成物见 packages/extension-api/schema/kun-extension.schema.json。一、包定位与设计原则kun/extension-api的职责可以从 packages/extension-api/package.json 中读出全貌{ name: kun/extension-api, version: 1.5.0, description: Stable framework-neutral API for Kun extensions, type: module, sideEffects: false, main: ./dist/index.js, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.js }, ./manifest.schema.json: ./schema/kun-extension.schema.json }, files: [dist, schema, fixtures, README.md], engines: { node: 20 } }关键设计点单一公开入口唯一受支持的入口是kun/extension-api另有只读的kun/extension-api/manifest.schema.json子路径。不要导入src/*、dist/*或其它未声明 subpath即使文件存在于开发仓库中也没有 SemVer 保证详见 docs/extensions/api-reference.md。运行时 Schema 即真源以Schema结尾的导出如ExtensionManifestSchema、AgentRunSchema、ToolResultSchema是运行时校验值基于zod同名或相邻的 TypeScript 类型描述通过校验后的静态形状。唯一依赖运行时依赖仅zod这是包保持框架中立、可被 Node 与 Webview 两端共同引用的基础。ESM onlytype: module且exports只提供import条件。ExtensionManifestSchema与 JSON Schema 的“同源”关系由 packages/extension-api/scripts/generate-manifest-schema.mjs 维持构建后运行schema:generate从 Zod Schema 生成schema/kun-extension.schema.jsonschema:check用于发布门禁校验二者一致性见package.json中的prepack: npm run schema:check。这意味着你在kun-extension.json中能写的字段与parseExtensionManifest在运行时接受的字段永远来自同一份定义。二、安装模式仓库工作区与独立项目关联文档给出了两条安装路径分别对应“参与仓库开发”与“独立开发扩展”两种场景。2.1 仓库内安装npm workspace在 Kun 仓库根目录执行npm ci npm run build --workspace kun/extension-apinpm ci依据根目录 package-lock.json 安装全部 workspace 依赖npm run build --workspace kun/extension-api会执行tsc -p tsconfig.build.json见 packages/extension-api/package.json 的build脚本把src/编译到dist/。之后可在测试中直接引用该 workspace 包。2.2 独立项目安装public registry对仓库外的独立扩展项目需要先确认公共 registry 上确实存在该产物再按名安装npm view kun/extension-api1.5.0 version npm install kun/extension-api^1.5.0只有第一条命令返回版本号时才执行安装。如果返回E404说明当前配置的 registry 没有该制品此时应使用仓库内的扩展示例工作流不要在需要移植的扩展里添加仓库相对的file:依赖——那会破坏可移植性。这一点在 docs/extensions/quick-start.md 中同样强调只有当前模板所需的命令都返回版本时才继续。2.3 独立扩展开发环境确认开始前先确认环境就绪kun --version kun extension --help node --versionKun CLI 来自 Kun 安装本身npm 上无 scope 的同名kun包并不是 Kun Agent CLI。三、最小扩展activate 与 ExtensionContext关联文档中的最小示例注册了一条命令import type { ExtensionContext } from kun/extension-api export async function activate(context: ExtensionContext) { context.subscriptions.add( await context.commands.registerCommand(hello, async () ({ ok: true })) ) }activate是 Node 入口Manifest 的main字段导出的约定函数。真正打开 View、调用命令或工具时Kun 才触发对应激活事件并调用activate把 Host 创建好的ExtensionContext传入。3.1 ExtensionContext 的完整服务面ExtensionContext的完整定义在 packages/extension-api/src/extension-context.ts它继承了ActivationContextData包含extension身份、apiVersion、capabilities、permissions、可选的workspaceContext、activationEvent与initialState并提供如下只读服务属性公开契约subscriptions,onDidError生命周期释放与结构化扩展错误commands声明过的命令注册、执行与 handler disposalstorage,configuration扩展/工作区隔离状态与声明式设置不保存秘密network受 permission/domain/account 约束的 Broker fetchsecrets需storage.secrets的 Node Host 受保护字符串存储View 不可直接访问uitheme、locale、View state、Host message、通知和主会话上下文挂载agent,threads需agent.capacity.read的全局容量扩展自有 Agent run、事件、steer/cancel 与 thread projectionrooms需rooms.read的房间、消息、任务与事件只读投影toolsManifest 声明工具的注册、progress、cancellation 与 bounded resultmodelProviders自定义 Provider adapter 的 probe/listModels/stream/cancel/countTokensauthenticationredacted account、受保护认证 session、authenticated fetch 与显式 secret revealmedia受保护选择、不透明 handle、bounded metadata/probe、View resource lease 与 brokered FFmpeg job 创建jobs扩展自有 durable job 的 get/list/subscribe/cancelworkspace,workspaceContext已授权 root 内的文件操作与当前 workspace/trust 投影这些服务接口的类型定义集中在 packages/extension-api/src/services.ts。createExtensionContext(transport, data)函数接收一个HostTransport与激活数据内部实例化ExtensionHostClient并把它订阅进DisposableStore见 packages/extension-api/src/extension-context.ts。3.2 生命周期与资源释放subscriptions是一个DisposableStore其实现位于 packages/extension-api/src/lifecycle.tsadd()接受Disposable或纯函数clear()/dispose()按逆序释放所有资源并把释放过程中的错误聚合成AggregateError抛出。因此所有registerCommand、registerTool、registerProvider返回的Disposable都应加入context.subscriptionsHost 在扩展停用时会统一释放。四、配置、认证与密钥的边界关联文档明确了两条安全边界这也是编写扩展时最容易出错的地方Declared non-secret settings are available fromcontext.configuration; Provider credentials must usecontext.authenticationand the Host-owned protected account flow. Node and Webview clients receive the same scoped configuration API.4.1 声明式配置context.configurationConfigurationApipackages/extension-api/src/services.ts提供getT(sectionId, key)读取声明式设置值update(sectionId, key, value)写入keys(sectionId)枚举onDidChange订阅ConfigurationChangeEvent携带sectionId、key、scope与value。Manifest 中通过contributes.settings声明设置 Sectionid、title、properties、scope: global | workspace默认workspace。Node 与 Webview 客户端拿到的是同一套 scoped configuration API——Webview 也通过context.configuration或 React 模板的useConfiguration读取设置但设置中不允许放秘密。4.2 认证与密钥context.authentication / context.secretsProvider 凭据一律走context.authentication与 Host 拥有的受保护账号流程protected account flowlistAccounts、createSession、getSession、cancelSession、deleteAccount、authenticatedFetch、revealSecret。context.secretsSecretStorageApi是 Host 保护的、扩展隔离的秘密字符串存储只对Node Extension Host可用需要storage.secrets权限Authenticated View 不能直接访问必须把依赖秘密的工作路由到声明的命令。这一点有测试直接佐证packages/extension-api/test/secrets.test.ts 用TestTransport验证secrets.get/set/delete走的是受保护的secrets.*方法并断言请求列表不含任何storage.*方法——即秘密永远不会投影进普通存储。4.3 权限模型Manifest 的permissions是精确字符串数组在 packages/extension-api/src/permissions.ts 中分为两类静态权限STATIC_PERMISSIONS如commands.register、ui.views、webview、agent.run、tools.register、providers.register、storage.secrets、workspace.read/write、media.*、jobs.manage等作用域权限accounts.use|manage|secrets.read:providerId与network:hostname/network:*.example.compermissionMatches支持*.前缀的子域通配匹配。原则是最小权限只声明扩展真正需要的权限新增权限的包版本不会继承旧同意用户必须在受保护窗口重新确认。五、ExtensionHostClient 与 HostTransport 协议Node 入口通常直接拿到 Host 创建的ExtensionContextWebview 则使用 Host 提供的窄HostTransport自己创建客户端import { ExtensionHostClient, type HostTransport } from kun/extension-api export function createViewClient(transport: HostTransport): ExtensionHostClient { return new ExtensionHostClient(transport) }5.1 HostTransport 抽象HostTransportpackages/extension-api/src/services.ts是扩展与 Host 之间的 wire 抽象request(method, params?, options?)请求-响应调用支持AbortSignal与timeoutMsnotify(method, params?)单向通知sendStream?(requestId, payload, terminal?)可选的应答确认流onNotification(listener)订阅 Host 推送registerHandler(method, handler)注册扩展侧 handler供 Host 反向调用。5.2 ExtensionHostClient 的内部机制ExtensionHostClientpackages/extension-api/src/client.ts在构造时把全部 API 面组装到 transport 之上commands、storage、secrets、configuration、network、ui、agent、rooms、threads、tools、modelProviders、authentication、media、jobs、workspace。几个值得注意的实现细节通知分发#handleNotification根据 method 分发ui.themeChanged、ui.localeChanged、ui.message、configuration.changed、modelProviders.statusChanged、agent.event、jobs.event等非法通知会触发ExtensionApiErrorcodePROTOCOL_ERROR。订阅缓冲agent.subscribe与jobs.subscribe在客户端维护订阅状态与orphan event 缓冲——事件先于监听器注册到达时先缓冲首个监听器挂载后按sequence顺序回放防止丢事件同时用MAX_ORPHAN_AGENT_SUBSCRIPTIONS/MAX_ORPHAN_JOB_SUBSCRIPTIONS限制无主缓冲规模。工具注册tools.registerTool(declaration, handler)先向 Host 注册再通过transport.registerHandler(tools.invoke:registrationId)接收调用handler 的返回值统一经ToolResultSchema规范化。Provider 注册modelProviders.registerProvider(declaration, adapter)委托给 packages/extension-api/src/client-provider-registration.ts 中的registerProvider。5.3 工具契约要点扩展工具ExtensionToolDeclarationSchema见 packages/extension-api/src/tools.ts声明id、description、inputSchema可选outputSchema、sideEffectsnone|read|write|external|destructive默认none、idempotent默认 false与maxOutputBytes1 KiB–1 MiB。outputSchema描述并验证ToolResult.content而不是整个ToolResultenvelope省略它只表示不启用额外输出结构校验并不会关闭输出上限。handler 上下文提供cancellationCancellationToken与reportProgress()。六、Manifest Schema运行时真源6.1 顶层结构与两种入口形态ExtensionManifestSchemapackages/extension-api/src/manifest.ts是 union 结构Node 形态必含main可选browserBrowser-only 形态必含browsermain被禁用且contributes不能声明commands、agentProfiles、tools、modelProviders、authentication这些都需要 Node handler。顶层公共字段包括manifestVersionv1 固定为1、apiVersion、name、publisher、version、可选displayName/description/icon/localizations/license/homepage、必填engines: { kun: semver range }、activationEvents、contributes、permissions、stateSchemaVersion、可选signatureed25519。完整字段约束见 docs/extensions/manifest.md 的“顶层字段”表。parseExtensionManifest(value)就是ExtensionManifestSchema.parse的封装是运行时校验入口。6.2 激活事件双向校验v1 支持的激活事件onStartup、onView:id、onCommand:id、onTool:id、onProvider:id、onAuthentication:id、onAgentProfile:id。SuperRefine 会做双向检查packages/extension-api/src/manifest.ts每个 View/command/tool/Provider/authentication/Agent profile 贡献必须声明对应事件或扩展明确使用onStartup每个非 startup 事件也必须指向真实存在的贡献——拼错的事件不会被降级处理。6.3 贡献点与隐含权限contributes支持的键packages/extension-api/src/manifest.tscommands、views.containers、views.leftSidebar/rightSidebar/auxiliaryPanel/editorTab/fullPage、actions.topBar/composer/message、message.resultPreviews、settings、contextMenus、notifications、agentProfiles、tools、modelProviders、authentication、hostContentScripts。MANIFEST_CONTRIBUTION_PERMISSION_REQUIREMENTSpackages/extension-api/src/manifest.ts定义了贡献点与最小权限的映射例如commands → commands.register、任意views.*→ui.views webview、tools → tools.register、modelProviders → providers.register、hostContentScripts → hostDom。requiredManifestPermissions()据此计算Schema 在解析时强制执行——缺失必要权限的 Manifest 直接校验失败测试见 packages/extension-api/test/manifest.test.ts 的requires permissions implied by entrypoints and contributions。另外两个有意思的强校验webview.external必须同时拥有至少一个network:hostnamegrant带externalBrowser的 View其每个 site 的 hostname 必须匹配显式network:grantsite URL 还必须是 credential-free 的 HTTPS 默认端口 URLmodelProviders[].authenticationProviderId必须指向本 Manifest 声明的 authentication 贡献。6.4 本地化覆盖localizations把最多 32 个 BCP 47 语言标签映射为纯文本显示覆盖packages/extension-api/src/manifest-localization.ts。resolveExtensionManifestLocale()先按大小写不敏感完整标签匹配再逐级回退语言标签zh-Hans-CN→zh-Hans→zh最后回退基础 Manifest且只覆盖显示文案——身份、激活事件、权限、路径、Schema 与指令始终以基础 Manifest 为准本地化引用未声明贡献会被拒绝测试见 packages/extension-api/test/manifest.test.ts 的 locale 用例。七、API 版本协商与兼容性7.1 协商算法packages/extension-api/src/compatibility.ts 实现negotiateApiVersion()Host 声明supportedApiVersions与capabilitiesByVersion扩展声明declaredApiVersion与requiredCapabilities。协商结果有三种失败码与一种成功态API_MAJOR_UNSUPPORTED声明 major 不在支持窗口API_MINOR_UNSUPPORTED声明 minor 高于 Host 支持的 minorCAPABILITY_REQUIRED要求的 capability 在该协商版本中不可用成功返回negotiatedApiVersion、capabilities与adaptercurrent/previous用于判断走哪个 major 的 adapter。Kun 支持当前 API major 与前一个 major当前为 v1因此只支持 1。同一安装中不同 major 的扩展可以同时激活各自使用协商契约能力缺失时 SDK 暴露 unavailable 或结构化错误required capability 缺失会在代码执行前 fail closed。7.2 协商 fixturespackages/extension-api/fixtures/api-major-negotiation.json 与 packages/extension-api/fixtures/api-minor-negotiation.json 是协商场景的固定输入配合测试验证 major/minor 边界行为。7.3 六个版本维度Manifest 中的version、manifestVersion、apiVersion、engines.kun、stateSchemaVersion与私有的rpcVersion是相互独立的版本维度详见 docs/extensions/versioning-and-migrations.md改变一个维度不隐式改变其它维度rpcVersion不属于第三方 APIManifest 不声明、扩展不导入。stateSchemaVersion只在持久化状态结构需要迁移时提高并通过main导出的migrateState(state, context)事务化迁移。八、测试与验证包内测试packages/extension-api/test/覆盖多个契约面manifest.test.tsManifest 解析、安全默认值、localization 覆盖、权限推导、外部 Webview 授权、激活事件引用secrets.test.ts秘密存储不投影进普通存储agent-run-options.test.ts、capacity-rooms.test.ts、composer-context.test.ts、media-jobs.test.ts、chart.test.ts。运行测试npm run test --workspace kun/extension-api发布前的 Schema 一致性门禁npm run schema:generate --workspace kun/extension-api # 重新生成 JSON Schema npm run schema:check --workspace kun/extension-api # 校验生成物与运行时 Schema 一致prepack脚本自动执行schema:check保证发布的.tgz中 JSON Schema 与ExtensionManifestSchema永远同步。九、从 SDK 到完整扩展推荐路径kun/extension-api只是公共契约层一个完整扩展通常还配合另外两个 SDK 与宿主 CLI包用途kun/extension-apiManifest、生命周期、Host client、Agent、工具、Provider、账号、存储、网络、UI、media、job 与 artifact 契约kun/extension-react基于ExtensionHostClient的 React Provider、hooks 与状态组件ExtensionViewProvider、useTheme、useConfiguration等kun/extension-testFake Host/transport/service 与ExtensionTestHarness提供确定性的媒体与 job fake完整的开发闭环脚手架 → 构建 → 测试 → 验证 → 安装 → 日志参见 docs/extensions/quick-start.mdnpx create-kun-extension hello-sidebar --template react --publisher acme --name hello-sidebar npm install npm run build npm test npm run validate kun extension install --development . kun extension reload acme.hello-sidebar npm run pack kun extension install ./dist/acme.hello-sidebar-0.1.0.kunx kun extension logs acme.hello-sidebar仓库内的扩展示例如hello-sidebar、tool-provider、streaming-model-provider、agent-assistant等是可直接对照的完整实现docs/extensions/api-reference.md 是中文 API 参考与生成导出清单docs/extensions/manifest.md 是 Manifest 字段级参考docs/extensions/security-and-resources.md 讲解权限与资源边界。结语kun/extension-api的定位可以概括为三句话框架中立不依赖 React/ElectronNode 与 Webview 共用同一契约、Schema 同源ExtensionManifestSchema与kun-extension.schema.json由同一份 Zod 定义生成、稳定可迁移单一公开入口 SemVer API major 协商窗口。无论你是要在仓库内为 Kun 贡献扩展还是为独立项目编写可移植的.kunx从本文的安装命令、activate骨架与 Manifest 校验规则出发都能快速进入正轨。赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐Kun 扩展 Webview 的 React 绑定kun/extension-react 使用指南Kun 扩展 Webview 的 React 绑定kun/extension react 使用指南 本文基于 packages/extension reac人工智能AI Agent自主智能体桌面应用MCP ClientsKun 扩展开发者生态框架无关 Extension API、React Webview Kit 与全流程 CLI 实战指南Kun 扩展开发者生态框架无关 Extension API、React Webview Kit 与全流程 CLI 实战指南 Kun 是一个本地优先Local人工智能AI Agent自主智能体桌面应用MCP ClientsKun 扩展开发实战Agent Runs 与工具Extension API v1 权威指南Kun 扩展开发实战Agent Runs 与工具Extension API v1 权威指南 本文面向在 Kun 桌面/TUI 一体 runtime 上开发人工智能AI Agent自主智能体桌面应用MCP Clients上一篇Vue-codemodVue2到Vue3迁移的完整解决方案下一篇如何为YTPro贡献代码新手开发者的完整贡献指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考