企业官网建设流程全解析

• 人工智能
• AI Agent
• 自主智能体
• 桌面应用
• MCP Clients

Kun 的扩展系统以kun-extension.json（Manifest）为唯一入口契约：Kun 在读取任何扩展代码或远程内容之前，先对 Manifest 的版本、入口、贡献、权限与资源引用做完整验证，未知字段、无效引用和不兼容版本都会直接判定失败，绝不靠“忽略未知字段”来猜测兼容。本文以 Kun Extension API v1 的 Manifest 参考为核心，逐字段拆解顶层结构、本地化、五维版本、激活事件、全部贡献点、权限模型与验证命令，并结合仓库源码（Manifest Schema 实现）、机器可读的 kun-extension.schema.json 以及 hello-sidebar、tool-provider、streaming-model-provider、direct-dom 等真实示例，帮助你写出一次通过校验、可打包发布、安全合规的扩展 Manifest。

Manifest 的定位与强制校验原则

每个扩展包（.kunx）或开发目录的根目录都必须存在kun-extension.json。Kun 在加载任何扩展代码或远程内容之前，会先验证 Manifest 的以下六个维度：

1. Manifest 结构版本（manifestVersion）：当前 v1 固定为整数1；
2. API 版本（apiVersion）：用于 Extension API 能力协商；
3. 入口（main/browser）：必须存在且通过路径与完整性校验；
4. 贡献（contributes）：所有静态声明必须合法且引用完整；
5. 权限（permissions）：必须显式声明并满足贡献隐含的最小权限；
6. 资源引用（icon、entry、localResourceRoots 等）：必须使用包内相对路径。

核心原则是严格同版本校验，拒绝猜测：未知字段、未知贡献类型、无效引用和不兼容版本都按同一版本的 Schema 处理，而不是靠忽略字段来“猜测兼容”。这也是为什么 Manifest 的权威真源是随@kun/extension-api发布的kun-extension.schema.json（仓库内即 packages/extension-api/schema/kun-extension.schema.json）——它是从 zod 定义自动生成的机器可读 Schema，字段级完整参考，文档中的省略示例不能用于绕过 validator。

在源码层面，Manifest 的解析与校验全部集中在 packages/extension-api/src/manifest.ts：ExtensionManifestSchema基于 zod 的strictObject（即额外字段直接报错）构建，并通过superRefine施加跨字段约束（隐含权限、激活事件双向引用、ID 唯一性、本地化引用合法性等）。当前常量定义也在这里：

• CURRENT_MANIFEST_VERSION = 1
• CURRENT_EXTENSION_API_VERSION = '1.5.0'
• 支持 API 版本列表：1.5.0、1.4.0、1.3.0、1.2.0、1.1.0、1.0.0

完整骨架：一个可直接照抄的 v1 Manifest

以下骨架覆盖了绝大多数扩展所需的字段，空数组可以省略，实际 Manifest 应只声明扩展真正需要的贡献和权限：

{ "$schema": "https://kun.dev/schemas/extensions/manifest/v1.json", "manifestVersion": 1, "apiVersion": "1.0.0", "publisher": "acme", "name": "issue-assistant", "version": "1.2.0", "displayName": "Issue Assistant", "description": "Manage issues with a sidebar and Kun Agent tools.", "icon": "assets/issue-assistant.svg", "engines": { "kun": ">=0.1.0" }, "main": "dist/extension.js", "browser": "dist/webview/index.html", "activationEvents": [ "onView:issues", "onCommand:refresh", "onTool:create-issue" ], "contributes": { "commands": [], "views.rightSidebar": [], "actions.topBar": [], "settings": [], "tools": [], "agentProfiles": [] }, "permissions": [ "commands.register", "ui.views", "ui.actions", "webview", "agent.run", "agent.threads.readOwn", "tools.register", "network:api.example.com", "storage.workspace" ], "stateSchemaVersion": 1 }

仓库中真实的、可通过校验的最小示例是 examples/extensions/hello-sidebar/kun-extension.json，它只声明了一个右侧栏 View、两条激活事件和两个权限，是学习最小合法 Manifest 的绝佳范本。

顶层字段逐项说明

结合 kun-extension.schema.json 中的正则细节，以下几点容易踩坑：

• publisher：小写 ASCII 字母/数字/连字符，以字母或数字开头，最长 64；正则形如^[a-z0-9][a-z0-9-]*$。
• name与所有 local contribution ID：小写字母开头，之后只允许小写字母/数字/连字符，最长 64；正则形如^[a-z][a-z0-9-]*$。以同版本 Schema 的正则和保留字校验为准。
• displayName最长 128 字符，description最长 4096 字符（schema 中分别由minLength: 1/maxLength: 128与maxLength: 4096约束）。
• engines.kun是必填的 SemVer range 字符串（最长 128，允许^、~、>=、*等常见运算符）。
• icon、main、browser、entry等路径字段必须符合相对路径正则：不能以/开头、不能包含盘符（[A-Za-z]:）、不能出现..段逃逸，长度上限 512。

main 与 browser：两类入口的取舍

main与browser至少存在一个：

• main：Node Host 入口，模块公开activate(context)，可选公开deactivate()；详见生命周期。任何要求 headless 的工具、Agent profile、模型 Provider、认证处理器、计划任务或后台命令都必须存在main，Kun 不会用browser代替 Node 入口。
• browser：沙箱 View 资源入口，不是 Node 模块，也不会获得自定义 preload。

Browser-only Manifest（只有browser）不能声明commands、agentProfiles、tools、modelProviders或authentication——这些都需要 Node handler。所有browser入口都必须声明webview权限。这一约束在源码中体现为BrowserOnlyContributionsSchema（packages/extension-api/src/manifest.ts）：它把上述五类贡献的最大数量压成 0，且main为never类型。

完整 ID 为publisher.name，一旦公开不得更改。改名等同于一个新扩展，旧状态、权限、账号和 thread 不会自动转移。

未声明顶层icon时，Host 可以兼容使用第一个声明了图标的 View 容器或主 View；都没有时显示默认占位图标。Logo 文件与其他 Manifest 资源一样，必须通过包内相对路径、完整性和受控资源协议校验。

Host 渲染文案的本地化

localizations把最多 32 个有界 BCP 47 语言标签映射为纯文本显示覆盖。基础 Manifest 始终是必需的 fallback，也是身份、激活事件、权限、路径、可执行 Schema 和 Agent instructions 的稳定真源。覆盖只能修改已知显示字段，且必须引用已声明的贡献、设置属性、通知操作或 Provider model。

{ "displayName": "Issue Assistant", "contributes": { "views.rightSidebar": [{ "id": "issues", "title": "Issues", "entry": "dist/index.html" }] }, "localizations": { "zh-CN": { "displayName": "问题助手", "contributes": { "views.rightSidebar": { "issues": { "title": "问题" } } } } } }

匹配顺序：Kun 先按大小写不敏感的完整标签匹配，再逐级匹配更宽的语言标签（zh-Hans-CN→zh-Hans→zh），最后使用基础 Manifest。Webview 内容仍通过ui.getLocale和ui.localeChanged自行本地化；Manifest 覆盖用于侧栏 tooltip、面板/结果预览标题、扩展中心卡片和声明式设置等 Host chrome。

源码中的实现依据：

• findManifestLocalization（packages/extension-api/src/manifest.ts）将请求语言标签逐级缩短（去掉最后一个-段）匹配本地化表，与文档描述的逐级匹配完全一致；
• resolveExtensionManifestLocale（同文件 L488-L548）只克隆并覆盖displayName、description及各贡献点的显示字段，身份、激活、权限、路径、Schema 与 instructions 始终保持基础 Manifest 数据；
• validateManifestLocalizationReferences（同文件 L581-L647）会校验每个本地化条目引用的贡献、设置属性、通知 action 和 Provider model 是否真的在基础 Manifest 中声明，未声明即报错。

版本字段：五个彼此独立的维度

manifestVersion是 Manifest Schema major，apiVersion是公开 Extension API SemVer，version是扩展包版本，stateSchemaVersion是扩展持久化状态的整数版本，engines.kun是允许运行的 Kun SemVer range——这五个维度彼此独立，不能混用。Kun/Host 的私有rpcVersion不写入 Manifest，也不要通过提高包版本来暗示 API 或状态兼容。详细规则见版本与迁移。

可选signaturev1 使用以下结构：

{ "algorithm": "ed25519", "keyId": "...", "value": "..." }

它只携带发布者提供的来源元数据；当前 Host 不做密码学验签，并将其报告为present-unverified。包字节、Index SHA-256 和文件 integrity 仍分别验证。Schema 中signature的约束为：algorithm枚举仅ed25519，keyId最长 256，value最长 16384。

入口：路径与执行环境约束

入口必须满足：

• 使用规范化包内相对路径；
• 位于完整性清单和允许资源根内；
• 不能包含绝对路径、..逃逸或符号链接；
• 在 validate、pack 和安装时存在；
• 与所声明贡献的执行环境一致。

main模块公开activate(context)，可选公开deactivate()；详见生命周期。browser是沙箱 View 资源入口，不是 Node 模块，也不会获得自定义 preload。测试中也明确验证了路径越界会被拒绝——packages/extension-api/test/manifest.test.ts 断言{ ...manifest, icon: '../icon.svg' }校验失败。

激活事件

v1 支持的事件及触发时机如下：

<id>是 Manifest 内本地贡献 ID。Validator 会双向检查引用：每个 View/command/tool/Provider/authentication/Agent profile 必须声明对应事件（或扩展明确使用onStartup），每个非 startup 事件也必须指向真实贡献；不会把拼错的事件降级为第一个任意事件。仅展示图标、标题或设置元数据不会激活代码。不要把onStartup当作默认值。

源码中的双向校验逻辑清晰可见：ActivationEventSchema的正则只允许onStartup或on(?:View|Command|Tool|Provider|Authentication|AgentProfile):[a-z][a-z0-9-]*（packages/extension-api/src/manifest.ts）；superRefine中先遍历每个贡献要求其事件存在（L341-L370），再遍历每个非 startup 事件要求其指向真实贡献（L372-L388）。也就是说，声明了onTool:create-issue却忘了在contributes.tools里声明create-issue，会直接校验失败。

贡献点总览

contributes只接受下列 v1 键。所有本地 ID 在同类贡献中必须唯一；所有可打开的 View（包括 result preview）还共享同一个 ID namespace。modelProviders[].authenticationProviderId必须指向本 Manifest 的 authentication contribution。宿主将本地 ID 解析为extension:<publisher.name>/<local-id>或等价的命名空间身份。

views.rightSidebar是新扩展的规范可发现 UI：默认情况下，View 的包内 icon 和本地化标题会出现在 Code 模式右侧竖向图标栏，并在主会话旁打开独立标签。设置showInRightRail: false可保留可由扩展管理页或命令打开的 View，但不在图标栏常驻。其它views.*位置继续保留 Extension API v1 解析和命令路由兼容，但宿主不会为它们生成额外的聚合扩展选择器。

Schema 层面的硬性约束（来自 kun-extension.schema.json）值得注意：

• 各贡献点数量上限：commands与tools最多 512，各views.*与actions.*最多 128，views.containers与settings最多 64，contextMenus最多 256，hostContentScripts最多 32；
• views.*View 的order是-10000 ~ 10000的整数，默认 0；multiple默认 false，showInRightRail默认 true；
• notifications的severity枚举info | warning | error（默认 info），actions最多 4 个；
• tools的sideEffects枚举none | read | write | external | destructive（默认 none），idempotent默认 false，maxOutputBytes范围 1024–1048576（即 1 KiB–1 MiB）；
• settings的scope枚举global | workspace（默认 workspace）。

固定远程网站：externalBrowser

需要固定远程网站时，View 可声明externalBrowser: { presentation, sites }。presentation为desktop或mobile；每个 site 只接受id、title、可选 badge/accent 和 credential-free HTTPSurl。这要求webview.external，且每个 site hostname 必须匹配显式network:grant。远程页由 Main-owned browser surface 承载，不加载扩展entry或 bridge。

Schema 与源码给出的细节约束：

• sites最多 12 个；ExternalBrowserSiteSchema（packages/extension-api/src/manifest.ts）强制 HTTPS、默认端口 443、无用户名/密码；
• 校验器为每个 site 从 URL 提取 hostname，要求webview.external权限且存在匹配的network:<hostname>授权（manifest.ts L298-L339）；
• 同一 View 的 site id 不得重复。

Contribution 隐含权限

Validator 从入口/贡献自动推导并强制以下最小权限；缺少时 Manifest 无效：

这些只是注册/呈现所需权限；实际 handler 仍要声明其使用的 workspace、network、account、storage 等权限。authentication的账号读取/管理/use/secret 权限按具体调用检查。

源码层面，隐含权限表就是MANIFEST_CONTRIBUTION_PERMISSION_REQUIREMENTS（packages/extension-api/src/manifest.ts），requiredManifestPermissions（同文件 L468-L478）汇总所有要求后在superRefine中与manifest.permissions逐一比对并报出具体缺失项。同时，Schema JSON 的allOf部分也以 JSON Schema 的if/then形式复刻了这套强制逻辑，保证非 TypeScript 工具链同样能校验。

三个可直接运行的最小贡献

最小命令：

{ "commands": [ { "id": "refresh", "title": "Refresh issues" } ] }

最小 View：

{ "views.rightSidebar": [ { "id": "issues", "title": "Issues", "entry": "dist/webview/index.html", "icon": "assets/issues.svg", "when": "workspaceOpen", "order": 100, "localResourceRoots": ["dist/webview", "assets"] } ] }

最小工具：

{ "tools": [ { "id": "create-issue", "description": "Create an issue in the configured project", "inputSchema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 } }, "required": ["title"], "additionalProperties": false }, "outputSchema": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "text" }, "text": { "type": "string" } }, "required": ["type", "text"], "additionalProperties": false } }, "sideEffects": "external", "idempotent": false, "maxOutputBytes": 32768 } ] }

真实仓库示例中，tool-provider 给出了一个 headless 工具的标准写法：main入口 +onTool:workspace-summary激活事件 +tools.register与workspace.read权限 +sideEffects: "read"、idempotent: true、maxOutputBytes: 65536；streaming-model-provider 则展示了完整的authentication（api-key 与 oauth2-pkce 两种类型）与modelProviders组合，包括模型能力元数据（输入/输出模态、reasoning、tools、streaming、上下文窗口）以及authenticationProviderId指向本 Manifest 认证贡献的引用方式。Contribution 的详细行为见工作台、Agent 与工具和Provider 与账号。

when条件

when使用宿主定义的封闭、无副作用表达式语言和公开 context keys。它不能执行 JavaScript、读取 renderer global、DOM 或私有 store，也不能创造调用者没有的权限。未知 key/capability 解析为 unavailable。

只使用同一 API 版本文档列出的 context key 和运算符。把业务决策放进命令 handler；when只负责可见/可用状态。状态变化后，宿主可能隐藏贡献并按该 contribution contract 关闭 View Session。Schema 中when是长度 1–2048 的字符串（WhenExpressionSchema）。

权限：精确字符串数组

v1 权限是精确字符串数组，每个权限对应一类明确的 Broker 能力：

Schema 中权限数组最多 256 项，且除了固定枚举（含media.read、media.process、media.export、jobs.manage等），还支持两类带参数的模式：accounts.(use|manage|secrets.read):<providerId>与network:(*.hostname|hostname)。

**只声明最小权限。**新增权限的包版本不会继承旧同意：用户必须在受保护窗口重新确认。webview.external还要求显式的network:<hostname>授权；该网络授权在这里限制远程子 Webview 的顶层导航，子页面绝不会获得 Kun preload、Node 或 Electron。权限不会让普通 browser 或 content script 获得 Node/秘密，也不能绕过 Kun ApprovalGate。详见安全与资源。

Direct DOM 声明

hostContentScripts必须静态列出id、matches、scripts，可选styles，以及runAt: "documentStart" | "documentEnd"；运行时不能请求注入未声明文件或 surface。matches使用宿主 surface token，不是 URL glob：可选值为workbench:*、workbench:code、workbench:design、workbench:write、workbench:connect。Settings/初始设置包含凭据和执行权限控制，始终是 protected surface；没有workbench:settingsmatcher，workbench:*也不会匹配它或其它凭据/consent 窗口。安装器会把hostDom显示为最高风险能力。

这些脚本在插件专属 isolated world 中运行，可以访问可见 DOM，但不能访问页面 JavaScript 对象、React internals、Electron、Node、window.kunGui或受保护 consent/credential surface。宿主 DOM、选择器和 CSS 不属于稳定 API，详见Webview 与 Direct DOM。

Schema 细节：matches最多 64 个，scripts1–32 个，styles0–32 个，runAt默认documentEnd。仓库示例 direct-dom 是最小的 Direct DOM 声明——onStartup激活、workbench:*surface、hostDom权限。

资源与完整性

发布包根还必须包含：

• README.md；
• LICENSE；
• kun-extension.integrity.json；
• 所有入口和 Manifest 引用的本地资源。

完整性清单记录包文件的 SHA-256。安装验证拒绝未声明/缺失文件、摘要不一致、路径穿越、绝对路径、link、重复/大小写碰撞路径、越界资源和超过公布限制的包。不要把秘密、令牌、私钥、开发.env或用户数据打进.kunx。完整性清单的生成与校验实现位于 kun/src/extensions/archive-support.ts、archive-core.ts 与 registry-validation.ts 等文件，配合kun extension pack生成确定性归档。

验证：validate、pack 与 CLI 生态

Kun CLI 提供完整的扩展生命周期命令。用kun extension --help可查看全部命令（定义见 kun/src/cli/extension-cli-commands.ts），核心流程是：

# 校验一个源码目录 kun extension validate . # 校验一个已打包的 .kunx 归档 kun extension validate ./dist/acme.issue-assistant-1.2.0.kunx

常用的相关命令还包括：kun extension create <directory>（脚手架）、kun extension pack <directory>（生成确定性.kunx）、kun extension install <path>（安装归档/开发目录/Index 版本）、kun extension list、kun extension enable/disable、kun extension doctor（校验包完整性与 Host 健康）、kun extension logs <extension-id>与kun extension reload <extension-id>。打包与校验还支持--output、--overwrite、--include、--ignore等选项（见 extension-cli-commands.ts）。

验证错误应包含稳定诊断代码、JSON path、说明和文档链接。兼容性失败会指出具体维度（Manifest、API、Kun engine、state 或 Host negotiation），而不是只报“版本错误”。

常见校验失败对照与排查要点

把上文散落的约束汇总成一张自查清单，可以大幅减少验证返工：

1. 身份命名：publisher可用数字开头，name与所有本地贡献 ID 必须小写字母开头，全小写字母/数字/连字符，最长 64；
2. 入口配对：main/browser至少一个；Browser-only 时不能声明commands、agentProfiles、tools、modelProviders、authentication，且必须声明webview；
3. 路径安全：所有资源路径必须是包内相对路径，禁止绝对路径、..、盘符、符号链接；
4. 激活事件双向引用：每个 View/command/tool/Provider/authentication/Agent profile 都要有对应事件（或用onStartup），每个非 startup 事件都必须指向真实贡献；
5. 隐含权限：按“Contribution 隐含权限”表补齐最小权限，externalBrowser还要追加webview.external与逐 site 的network:<hostname>；
6. ID 唯一性：同类贡献内 ID 唯一，所有可打开 View（含 result preview）共享 ID namespace；
7. 认证引用：modelProviders[].authenticationProviderId必须指向本 Manifest 的 authentication contribution；
8. 本地化引用：本地化覆盖只能引用已声明的贡献/设置属性/通知 action/Provider model；
9. 版本一致性：manifestVersion: 1、apiVersion取受支持列表（1.0.0至1.5.0）、stateSchemaVersion为非负整数；
10. 打包完整性：README.md、LICENSE、kun-extension.integrity.json与全部引用资源必须在包内，且不含秘密与用户数据。

把kun-extension.json当作扩展的“安全边界声明”来写：身份与入口决定它如何被加载，贡献点决定它提供什么能力，权限决定它能触碰哪些 Broker 资源，而 Validator 则在代码运行前把这些声明全部钉死——这也是 Kun 扩展体系能够在加载任何远程内容前保持可审计、可回滚、可信任的根本原因。

• 人工智能
• AI Agent
• 自主智能体
• 桌面应用
• MCP Clients