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

人工智能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 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.tsCLI 命令。一、.kunx是什么不可变、可校验的 ZIP 包Kun 的发布包.kunx是一个不可变、可校验的 ZIP 归档。它支持三种来源形态本地.kunx文件——用户显式侧载的发布包本地开发目录——通过--development注册的可变源码目录显式配置的 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.tsEXTENSION_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、LICENSEManifest 中直接引用的每个文件包括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 与完整性自处理遵循生成的 SchemaIndex 下载字节摘要与包内文件摘要分别独立校验。可选的签名元数据仅是来源证据provenance不是安装前提也不构成代码审计。签名状态为valid、unsigned、invalid或unknown-key。v1 不内置发行方密钥信任目录因此侧载的签名若无法关联到受信公钥将明确显示为unknown-key仅有签名文本绝不等于valid失败的签名也不能被呈现为已验证。当前宿主把签名报告为present-unverifiedManifest 文档 manifest.en.md 同样声明。四、确定性打包实操4.1 推荐流程脚本五步npm run build npm test npm run validate npm run pack4.2 直接使用 CLIkun extension validate . kun extension pack . --output ./dist4.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/assertNoSourceLinkParentsarchive-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 选择规则诊断码速查稳定代码含义修复建议EXTENSION_PACKAGE_RULE_INVALIDinclude/ignore 不是规范相对路径使用无 glob、无..的包相对路径EXTENSION_PACKAGE_INCLUDE_MISSING显式 include 或递归根不存在先构建再核对相对源码根的路径EXTENSION_PACKAGE_FORBIDDEN_PATH选中路径命中机密/VCS/依赖/嵌套包策略移出发布树或对选中树下非必需文件精确 ignoreEXTENSION_PACKAGE_LINK_FORBIDDEN源码、父级或选中成员是符号链接复制为真实发布资产绝不让打包器跟随链接EXTENSION_PACKAGE_FILE_MISSING必需文档或 Manifest 引用被省略/忽略恢复文件或修正 Manifest/ignore 规则五、包校验限额与安装前拦截5.1 v1 安全默认值项目默认上限压缩后的.kunx100 MiB总解压字节250 MiB单个文件25 MiB文件数量5,000这些默认值定义在 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.rollbackpreviousSelectedVersion见 package-manager.ts。七、产品内置默认包Product-bundled default packagesKun 桌面端默认只随产品内置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 先前播种指纹完全相同的权限集新增权限走常规用户审查流程字节不同但版本相同、降级、无效目录、哈希不匹配都会失败关闭同时保留上一个有效注册表状态可用。八、侧载本地 .kunxkun 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 Directorykun 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后重新加载/替换 Hostreload 校验失败后报告可操作的错误且不运行无效条目。开发目录不是发布工件。发布前请在干净档案中打包并测试.kunx。十、自定义 HTTPS Index v1Index 是不受信任、不可执行的 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 都必须是 HTTPSassertHttps强制https:协议且禁止 URL 内嵌用户名/密码index-client.tsIndex 内容仅为数据不执行任何脚本/模板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对每个跳转重新断言 HTTPSindex-client.ts。Index 所有者不得替换既有 URL/版本的字节。不可变版本 SHA-256 可防止静默替换。语义校验还包括publisher必须匹配 ID 前缀、扩展 ID 与版本不得重复、权限必须唯一validateIndexSemanticsindex-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 Updatesv1 明确禁止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与isEnabledpackage-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 串行化serializeExtensionIndex 客户端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【免费下载链接】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点击查看免费下载相关推荐10分钟跑通GetQzonehistory如何离线导出QQ空间全部历史说说10分钟跑通GetQzonehistory如何离线导出QQ空间全部历史说说你在QQ空间往前翻时间线翻到某年就不动了几年前的找不出来部分图片链接已经打不人工智能AI Agent自主智能体桌面应用MCP Clients专业Chrome扩展打包发布全流程指南从源码到分发专业Chrome扩展打包发布全流程指南从源码到分发作为一名Chrome扩展开发者你是否曾经在发布扩展时遇到这样的困扰手动打包时遗漏关键文件导致安装失败音视频Kun 扩展包管理深入解析.kunx 包格式、防御性校验、原子安装与 HTTPS 索引Kun 扩展包管理深入解析.kunx 包格式、防御性校验、原子安装与 HTTPS 索引本文基于 Kun 扩展平台的设计规范 extension packag人工智能AI Agent自主智能体桌面应用MCP Clients上一篇React CodeMirror 终极使用指南快速构建现代化代码编辑器下一篇远程终端管理工具解锁高效运维的智能钥匙创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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

相关推荐

Meteor 微博 OAuth 登录包弃用迁移指南：从 `weibo` 切换到 `weibo-oauth` 并理解其 OAuth 2.0 流程实现

Zeek DNS 日志增强：如何将 Authoritative 与 Additional 响应纳入 dns.log（auth-addl 脚本深度解析）

Graffle 官方指南导读：为什么选择 Graffle、生成式客户端六大优势与文档体系速览

更多资讯

从Day1到Day105：面试经典150题刷题复盘与高效计划

高并发电商支付中台实战：从架构拆分到稳定性治理

网络基础大汇总：从IP、子网、VLAN到DNS排障的实战主线

uni-app x 强力工具库 unix-utils 正式发布

人脸识别项目落地实战：架构、部署、调优与避坑全解析

基于 Agones 的多集群游戏服务器统一分配端点（Allocation Endpoint）代理实战指南

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？