扩展打包与安装

扩展打包与安装

功能

bt ext 是 BT 扩展工具链，用于创建扩展项目、构建 .bts 包、安装到项目、查看包信息和执行加载检查。官方扩展库使用顶层命令 bt install 远程安装。

命令

解释器安装是独立操作：在包含待下一版本发布功能的构建中，不带扩展名的 bt install为当前用户安装解释器。bt install <name> 保留本页描述的扩展安装行为。详见环境搭建。

参数

返回值

bt ext 是命令行工具，不向 BT 脚本返回值。命令成功时输出执行进度和结果；命令失败时输出中文错误并返回失败状态。

打包规则

bt ext build 会收集开发目录中的普通文件，并跳过：

打包时会限制 .bts 包条目数量、单文件大小、总解压大小和包内路径。写出 zip 后，工具会回读 .bts 并初始化对应 Runner，确保包能被运行时加载。

安装规则

安装命令：

会把扩展复制到：

目标目录和文件名来自包内 manifest.name 与 manifest.version，不是命令行传入的文件名。安装同名新版本前会删除 extensions/<name>/ 下旧的 <name>-*.bts，避免同一项目同时加载两个同名扩展版本。运行时仍兼容旧的 extensions/*.bts 顶层包。

远程安装命令：

可先打开 /zh-hans/ext 查看官网当前分发的已审查开源扩展、版本、包哈希和源码仓库。

远程安装会先读取官网元数据，再下载 .bts 临时文件，校验 SHA-256、文件大小、包内 manifest.name、manifest.version、kind 和 abi 后写入项目扩展目录。下载失败、校验失败或包后端加载失败时，不会留下可被运行时加载的半截 .bts 文件。

远程安装输出分为下载、校验和安装三步：

代码示例

完整纯 BT 扩展流程：

安装后项目脚本调用：

注意事项

• bt ext new 不会覆盖非空目录。
• bt ext build 的输出路径如果位于开发目录内，工具会避免把输出包再次打进包里。
• bt ext install 和 bt install 都会让同名扩展在项目中只保留一个版本。
• 本地安装不会连接或依赖官网扩展库。安装扩展即表示信任其代码；BT 支持私有和闭源包，但它们不属于官网审核范围。
• bt install 第一阶段只支持 major.minor.patch 三段式版本，不支持范围版本和传递依赖。
• 扩展 CLI 命令成功时会向终端输出构建、安装或检查结果；失败时输出中文错误，不会生成可部分加载的 .bts 包。
• 默认构建已启用 extensions feature，可以直接使用 bt ext；只有使用 --no-default-features 构建轻量版时，bt ext 和项目扩展加载才不可用。

更新已安装的扩展

可用性：待下一版本发布。bt update <name> [--project <dir>] 把已有官方扩展更新到注册表中的最新版本。不带扩展名的 bt update 更新解释器。交互提示符也支持相同命令。

语法

参数

不接受版本参数。需要显式安装指定版本时，使用 bt install <name> <version>。

返回值与注意事项

命令输出更新进度或已是最新版本的提示，不返回 BT 语言值。命令行失败返回非零退出码，交互提示符在失败后保持打开。扩展必须已安装且恰好包含一个有效包；当前版本从包内 manifest 读取，同版或更高版本保留不变。最新官方版本必须未撤回，并兼容当前运行的 BT 版本；不兼容时报告错误，请先更新 BT 再重试。替换前校验下载大小、SHA-256、manifest 身份和后端兼容性；发布新包或校验项目扩展失败时恢复旧包。其他扩展保持不变。已经加载此扩展的脚本或应用需要重新启动，才能使用新版本。