Kun 扩展打包、侧载与自定义 Index 权威指南：从 .kunx 包到安全分发全流程

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

适用版本：Kun Extension API v1 · 本文对应仓库文档 packaging-and-index.en.md

导读

本文系统讲解 Kun 扩展的发布与安装体系：如何把开发目录变成不可变、可校验的.kunx发布包，如何通过侧载（side-load）安装本地包或注册开发目录，以及如何构建和维护一个自定义 HTTPS Index来向用户分发扩展。读完本文，你将掌握从kun extension pack到 Index 发布、再到用户侧安装、启停、回滚与卸载的完整闭环，并理解 Kun 在打包选择规则、完整性校验、敏感路径策略、安装原子性与"无自动更新"等关键安全设计上的底层实现。

Kun 的扩展分发遵循一个明确的安全哲学：第三方安装与版本选择始终由用户发起；v1 运行时不做任何后台 Index 检查或下载；包内容不可变、逐文件 SHA-256 校验、敏感文件强制排除；安装失败永远保留旧版本可用状态。核心实现位于 kun/src/extensions（打包/校验/安装管理器）与 kun/src/cli/extension-cli-commands.ts（CLI 命令）。

一、.kunx是什么：不可变、可校验的 ZIP 包

Kun 的发布包.kunx是一个不可变、可校验的 ZIP 归档。它支持三种来源形态：

1. 本地.kunx文件——用户显式侧载的发布包；
2. 本地开发目录——通过--development注册的可变源码目录；
3. 显式配置的 HTTPS Index——用户主动浏览并选择精确版本后下载安装。

三种形态中只有前两者在 v1 中真正参与"安装"；Index 只是元数据源，真正的包下载在用户选定精确版本后才发生。产品发行版可以在下述约束下，通过正式目录预置（seed）一个显式列出的第一方默认包，但绝不能绕过校验。

1.1 包根目录的强制内容

一个发布包根目录必须包含：

kun-extension.json kun-extension.integrity.json README.md LICENSE <main/browser 入口点> <Manifest 引用的资源>

其中扩展 ID 恒为publisher.name，包版本取 Manifestversion字段的 SemVer。每一个条目和每一个本地资源都必须出现在完整性文件中（源码常量见 archive-core.ts：EXTENSION_MANIFEST_FILE、EXTENSION_INTEGRITY_FILE、EXTENSION_README_FILE、EXTENSION_LICENSE_FILE以及REQUIRED_PACKAGE_FILES数组）。

一个包不能依赖仓库相对机器路径、未发布的 workspace 别名或外部node_modules。

1.2 严禁包含的内容

打包前必须人工审计以下内容，官方打包器也会通过敏感路径策略拦截一部分：

• .env、API 密钥、令牌、私钥或测试账号；
• 用户状态、缓存或日志；
• source map 中的密钥或私有绝对路径；
• 未声明的文件、符号链接或硬链接；
• 构建缓存与无关依赖。

二、默认打包选择规则：白名单而非递归收集

官方打包器默认采用白名单选择，不会递归收集整个项目目录。默认选中的仅有（archive-support.ts 的collectPackFiles实现即为底层依据）：

• 根目录的kun-extension.json、README.md、LICENSE；
• Manifest 中直接引用的每个文件，包括main、browser、View/预览条目、图标、内容脚本与样式；
• 每个 ManifestlocalResourceRoots条目下的文件树。

因此，根目录下的src、node_modules、.git、测试输出及其他未声明文件，不会仅仅因为位于源码目录下就被打进包。如果 Node 入口需要打包器未合并的本地 chunk，必须用下面的--include显式声明；永远不要依赖机器外部（machine-external）的node_modules。

三、完整性清单：kun-extension.integrity.json

官方打包工具会确定性生成kun-extension.integrity.json，对发布文件逐项记录 SHA-256。不要手工维护它。校验器要求的结构（archive-core.ts 的IntegritySchema严格匹配{ algorithm: 'sha256', files: { path: 64位十六进制 } }）：

{ "algorithm": "sha256", "files": { "kun-extension.json": "0000000000000000000000000000000000000000000000000000000000000000", "dist/extension.js": "0000000000000000000000000000000000000000000000000000000000000000" } }

校验契约要点：

• 完整性文件本身不会被递归列在files中；打包与校验按约定单独处理它；
• 每个允许文件恰好一条规范路径记录；
• 每个记录文件必须存在且摘要与声明一致；
• Manifest、README、LICENSE 与完整性自处理遵循生成的 Schema；
• Index 下载字节摘要与包内文件摘要分别独立校验。

可选的签名元数据仅是"来源证据（provenance）"，不是安装前提，也不构成代码审计。签名状态为valid、unsigned、invalid或unknown-key。v1 不内置发行方密钥信任目录，因此侧载的签名若无法关联到受信公钥，将明确显示为unknown-key；仅有签名文本绝不等于valid，失败的签名也不能被呈现为已验证。当前宿主把签名报告为present-unverified（Manifest 文档 manifest.en.md 同样声明）。

四、确定性打包实操

4.1 推荐流程：脚本五步

npm run build npm test npm run validate npm run pack

4.2 直接使用 CLI

kun extension validate . kun extension pack . --output ./dist

4.3 用 include/ignore 精确控制发布集

Manifest 无法直接引用的发布文件，用可重复的包相对路径规则补充：

kun extension pack . \ --include dist/chunks \ --include NOTICE.txt \ --ignore dist/chunks/debug.map \ --output ./dist

规则约束（CLI 定义见 extension-cli-commands.ts）：

• --include接受已存在的普通文件或真实目录；目录会被递归选中；
• --ignore在 Manifest/include 选择之后排除该路径及其整棵子树；
• 两者只接受规范的可移植相对路径；绝对路径、..、反斜杠、glob 与!重新包含都会被拒绝；
• 源码目录validate接受同样的--include/--ignore选项；最终pack时务必使用相同的取值；
• 忽略 README、LICENSE、Manifest 条目或其他必需引用仍会以"缺失"失败校验。

4.4 不可覆盖的敏感路径策略

打包器会对选中集合施加不可覆盖的敏感路径策略，绝不打包：.git/.hg/.svn、node_modules、.ssh/.gnupg/.aws、.env*、.npmrc、.netrc、常见凭据/密钥配置、私钥/证书容器，以及嵌套的.kunx（敏感目录/文件/扩展名清单见 archive-support.ts 的FORBIDDEN_PACKAGE_DIRECTORY_NAMES、FORBIDDEN_PACKAGE_FILE_NAMES、FORBIDDEN_PACKAGE_FILE_EXTENSIONS）。

如果选中树中出现上述路径，打包会报错并指出路径；请将其移出发布树，或用精确的--ignore排除。注意：文件名检查无法发现任意内容中的机密，发布者仍必须人工审计 bundle、source map 与生成资产。

4.5 符号链接全面拒绝

源码根、include 目标与每个被选中的目录树都拒绝符号链接。路径在读取前被限制在源码根内，无法通过链接父级或路径规则逃逸；打包器从不跟随链接。源码侧实现由assertNoSourceLinkParents/assertNoSourceLinkParents（archive-support.ts）与packKunx的lstat检查（archive-core.ts）保证。

4.6 可复现性承诺

相同输入与相同工具版本应产生相同的文件集合、路径顺序与摘要（ZIP 容器可复现性遵循同版本打包契约）。实现上，打包器把 ZIP 内所有文件时间戳固定为1980-01-01T00:00:00.000Z、权限固定为0o100644（见 archive-core.ts），这正是确定性输出的关键。打包输出至少报告：扩展 ID、版本、输出路径、SHA-256、请求的权限与兼容性结果。

4.7 选择规则诊断码速查

五、包校验限额与安装前拦截

5.1 v1 安全默认值

这些默认值定义在 archive-core.ts 的DEFAULT_EXTENSION_ARCHIVE_LIMITS（另有maxManifestBytes: 1 MiB）。平台策略可能进一步收紧，不要依赖逼近默认值。用validate --json检查实际生效限额（CLI 提供--json机器可读输出，extension-cli-commands.ts）。

5.2 扩展代码运行前的 staging 校验拒绝项

• 绝对路径、路径穿越、编码转义；
• 符号/硬链接或链接穿越；
• 重复、规范化或大小写折叠碰撞；
• 未声明、缺失或哈希不匹配的文件；
• 资源根逃逸；
• 非法 ID/SemVer/Manifest/条目；
• 不兼容的engines.kun、Manifest/API 主版本；
• 压缩/解压/单文件/文件数限额超限。

任何失败都会清理或隔离 staging，绝不留下部分激活的安装。安装管理器在 package-manager.ts 的installArchive中按extractKunxArchive → 权限授予校验 → 期望包校验 → 原子切换执行，任何失败都会删除 staging 目录。

六、安装布局与原子性

6.1 默认包根目录

~/.kun/extensions/ registry.json .staging/ .downloads/ acme.issue-assistant/ 1.1.0/ 1.2.0/

宿主可以显式覆盖根目录，扩展代码绝不能硬编码它。路径类 paths.ts 显示默认packageRoot为~/.kun/extensions、dataRoot为~/.kun/extension-data，并包含registryFile、stagingRoot（.staging）、downloadsRoot（.downloads）。

已校验的版本目录不可变（安装后通过makePackageTreeReadOnly置为只读，见 package-manager.ts）。注册表（registry.json）存储：

• 身份、已安装版本、选中版本；
• 来源类型/定位符；
• 包 SHA-256 与签名状态；
• 已接受的权限快照；
• 全局与按工作区的启用状态。

6.2 安装事务流水线

新版本安装流经：inspect → staging 校验 → 受保护来源/权限审查 → 必需状态迁移 → 原子版本目录移动 → 原子选中版本切换。任何失败都保留旧的选中版本、状态、授权与启用状态。

Kun 会至少保留紧邻的上一选中版本直到显式移除，以支持手动回滚（registry.rollback+previousSelectedVersion，见 package-manager.ts）。

七、产品内置默认包（Product-bundled default packages）

Kun 桌面端默认只随产品内置kun-examples.social-media-sidebar。kun-examples.presentation-studio与kun-examples.kun-video-editor仍是源码示例：它们被排除在默认目录、产品构建、Release 打包与首次启动播种之外；目录将这两个 ID 标记为retired（退役），因此产品播种的安装会被移除，而用户自行管理的安装保持不动（实现见 bundled-extension-seeder.ts，含retired-removed/retired-user-managed等状态）。

产品构建流程：运行常规 validate/pack CLI，把生成的确定性.kunx放在bundled-extensions/catalog.json旁；目录固定 ID、版本、归档名、SHA-256、引擎范围、API 版本与精确权限。在新档案（fresh profile）上，kun serve校验该目录并调用与本地侧载相同的ExtensionPackageManager.installArchive事务（bundled-extension-seeder.ts）。它不会把解压树复制进注册表，也不会绕过兼容性、完整性、迁移、权限或激活检查。

默认播种授予产品随附包的权限快照并全局启用，但不授予工作区信任、媒体路径或受保护选择器决策——这些仍由用户控制。独立的种子账本（seed ledger）维护所有权：

• 播种前已存在的扩展保持用户管理；
• 用户禁用的默认扩展在升级后仍保持禁用；
• 卸载会记录移除，后续启动或产品更新绝不会重建；
• 用户选中的开发源或手动选中/回滚的版本绝不被覆盖；
• 自动内置更新要求：更新的 SemVer + 先前播种指纹 +完全相同的权限集；新增权限走常规用户审查流程；
• 字节不同但版本相同、降级、无效目录、哈希不匹配都会失败关闭，同时保留上一个有效注册表状态可用。

八、侧载本地 .kunx

kun extension install ./dist/acme.issue-assistant-1.2.0.kunx kun extension list kun extension doctor acme.issue-assistant

受保护审查（protected review）展示：本地来源路径、ID、版本、摘要、签名、贡献（contributions）、权限，以及 Node/Direct DOM/密钥/Provider 数据风险。拒绝任何权限就不执行任何代码，注册表选择与授权保持不变。

未签名的本地包可以侧载，但会保持unsigned标记。永远不要建议用户关闭完整性或权限校验。

九、开发目录（Development Directory）

kun extension install --development /absolute/path/to/extension kun extension reload acme.issue-assistant

开发源（package-manager.ts 的registerDevelopment/reloadDevelopment）：

• 仍校验 Manifest、引擎/API、条目与适用资源；
• 明确标记为可变（mutable）；
• 不被 Kun 复制、重写或打包；
• 不会在启动或文件变化时隐式重新加载；
• 注册目录内容变更后，新激活返回EXTENSION_DEVELOPMENT_RELOAD_REQUIRED，直到显式 reload 校验新一代（generation 递增）；
• 只在显式reload后重新加载/替换 Host；
• reload 校验失败后报告可操作的错误，且不运行无效条目。

开发目录不是发布工件。发布前请在干净档案中打包并测试.kunx。

十、自定义 HTTPS Index v1

Index 是不受信任、不可执行的 JSON。完整示例：

{ "schemaVersion": 1, "extensions": [ { "id": "acme.issue-assistant", "name": "Issue Assistant", "description": "Manage project issues from Kun.", "publisher": "acme", "versions": [ { "version": "1.2.0", "url": "https://extensions.acme.example/acme.issue-assistant-1.2.0.kunx", "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "engines": { "kun": ">=1.0.0 <2.0.0" }, "apiVersion": "1.0.0", "permissions": [ "commands.register", "ui.views", "webview" ], "signature": { "algorithm": "ed25519", "keyId": "acme-release-2026", "value": "<signature metadata>" } } ] } ] }

description与signature可选。Index 的signature必须与 Manifest 使用完全相同的algorithm、keyId、value形状，安装精确版本时每个字段都必须匹配。这个相等性检查不做密码学验签；当前宿主报告为present-unverified。字段级要求请以 Index v1 Schema 为准（客户端校验实现见 index-client.ts 的IndexVersionSchema与IndexSchema）。

10.1 Index 规则

• Index URL 与每个包 URL 都必须是 HTTPS（assertHttps强制https:协议且禁止 URL 内嵌用户名/密码，index-client.ts）；
• Index 内容仅为数据，不执行任何脚本/模板；
• Index JSON 默认上限 5 MiB；包下载保持在 100 MiB 默认上限内，并对照实际响应字节再次检查（maxIndexBytes: 5 MiB、maxPackageBytes: 100 MiB、最多 5 次重定向，见 index-client.ts）；
• 版本条目必须是精确 SemVer；可变的latestURL 不构成身份；
• Kun 在展示前校验字段、大小、重复身份/版本与 URL；
• 只有用户选定一个精确兼容版本后才会下载；
• 下载 SHA-256 必须匹配 Index；包身份/版本/引擎/API/权限必须匹配选中条目，随后校验内部完整性；
• 任何不一致都被拒绝，不注册、不执行；
• 重定向目标也必须满足 HTTPS/来源策略（fetchHttps对每个跳转重新断言 HTTPS，index-client.ts）。

Index 所有者不得替换既有 URL/版本的字节。不可变版本 + SHA-256 可防止静默替换。语义校验还包括：publisher必须匹配 ID 前缀、扩展 ID 与版本不得重复、权限必须唯一（validateIndexSemantics，index-client.ts）。

Index 安装的 CLI 形态（[extension-cli-commands.ts](https://link.gitcode.com/i/fe6194f962378ac7850d86e1f2de87ce#L93-L94, L396-L411)）：

kun extension install --index https://extensions.acme.example/index.json \ --id acme.issue-assistant --version 1.2.0

十一、无自动更新（No Automatic Updates）

v1 明确禁止：

• Kun/GUI 启动时联系 Index；
• 后台轮询本地目录或 Index；
• 自动版本比较；
• 未经请求的更新提示/徽标；
• 自动下载/安装/选中/回滚。

只有用户显式刷新/浏览才会抓取目录元数据，且不会下载任何包。随后用户选定精确版本并完成权限审查。

十二、启用、禁用、回滚与卸载

kun extension enable acme.issue-assistant --workspace /path/to/workspace kun extension disable acme.issue-assistant --workspace /path/to/workspace kun extension rollback acme.issue-assistant --version 1.1.0 kun extension uninstall acme.issue-assistant

• 工作区启用只改变激活资格，不复制包；
• 禁用会围栏（fence）新调用、取消/停用 Host，并保留代码与数据；
• 回滚仍检查引擎/API/状态兼容性；没有兼容快照时失败，绝不猜测逆向迁移；
• 卸载先安全停用，再移除注册表/代码；
• 状态、日志、账号引用与密钥默认保留；永久删除需另行确认并先展示影响。

工作区信任与启用是激活前置条件（resolveForActivationSerialized检查isWorkspaceTrusted与isEnabled，package-manager.ts）。

十三、发布包检查清单（Release Package Checks）

发布前逐项核对：

• ID/包/引擎/API/状态版本正确；
• README、LICENSE、完整性文件、条目与资源齐全；
• 最小权限；新增权限必须有清晰的发布说明；
• 无机密、私有路径、未声明文件或链接；
• 校验与测试通过；
• .kunx在干净档案中完成安装、激活、禁用、回滚、卸载全流程；
• 无头工具/Provider 不依赖 GUI/浏览器；
• Index 条目与包元数据/摘要精确匹配；
• 中英文文档与 Changelog 同步。

十四、从源码印证安全边界

本文的每一条规则都能在源码中找到对应实现，建议读者按需深入：

• 打包与解包：archive-core.ts——packKunx（确定性 ZIP、固定时间戳/权限、输出前自检inspectKunxArchive）、extractKunxArchive（限额、大小流式检查、完整性解析）、verifyExtractedExtension（已安装包文件集与摘要复核）；
• 选择与敏感策略：archive-support.ts——collectPackFiles白名单收集、FORBIDDEN_PACKAGE_*清单、路径规范校验；
• 安装事务与注册表：package-manager.ts 与 registry.ts——staging → 原子移动 → 只读化 → 版本切换 → 上一版本保留；同扩展操作按 lane 串行化（serializeExtension）；
• Index 客户端：index-client.ts——Schema 校验、HTTPS 强制、大小限制、重定向策略、下载摘要比对；
• 产品播种：bundled-extension-seeder.ts——目录固定指纹与权限、种子账本、退役 ID 处理；
• Manifest 配套：manifest.en.md 提供kun-extension.json的完整字段、条目、贡献点与权限表，是打包前必须对照的 Schema 级参考；CLI 全局形态见 cli-testing-debugging.en.md，版本维度见 versioning-and-migrations.en.md，权限语义见 security-and-resources.en.md。

一句话总结：Kun 用"确定性白名单打包 + 逐文件 SHA-256 完整性 + 敏感路径硬拒绝 + 原子安装事务 + 用户显式发起的 Index 选择"这套组合拳，让.kunx的发布、侧载、目录分发与产品预置在同一个安全边界内工作；在 v1 中，没有任何路径可以绕过校验让代码运行。

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