# 扩展打包与安装

## 功能

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

## 命令

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

```text
bt ext new <dir> [--kind bt|wasm]
bt ext build [dir] [-o <file.bts>]
bt ext install <file.bts> [project_dir]
bt ext info <file.bts>
bt ext check [dir|file.bts]
bt install <name> [version] [--project <dir>]
```

## 参数

| 命令 | 说明 |
| ------ | ------ |
| `new <dir>` | 创建扩展开发目录，默认生成 `kind=bt` 脚手架。 |
| `new <dir> --kind wasm` | 创建 WASM 扩展开发目录，生成 Rust SDK 脚手架。 |
| `build [dir]` | 从扩展开发目录打包 `.bts`，默认输出 `<manifest.name>.bts`。 |
| `build [dir] -o <file>` | 指定输出包路径，必须使用 `.bts` 后缀。 |
| `install <file> [dir]` | 校验本地包后复制到目标项目 `extensions/<name>/<name>-<version>.bts`。 |
| `info <file>` | 查看 manifest、入口、对象、方法和运行时上限。 |
| `check [dir|file]` | 校验开发目录或 `.bts` 包能被当前 BT 构建加载。 |
| `bt install <name>` | 从官网扩展库安装最新兼容版本。 |
| `bt install <name> <version>` | 从官网扩展库安装指定三段式版本。 |
| `--project <dir>` | 指定远程安装目标项目目录，默认是当前目录。 |

## 返回值

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

## 打包规则

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

```text
target/
.git/
.hg/
.svn/
node_modules/
```

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

## 安装规则

安装命令：

```text
bt ext install calc.bts project
```

会把扩展复制到：

```text
project/extensions/calc/calc-1.0.0.bts
```

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

远程安装命令：

```text
bt install sqlite
bt install sqlite 1.0.0
bt install sqlite --project examples/app
```

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

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

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

```text
Installing sqlite 1.0.0...

[1/3] Downloading
[████████████████████████████████████████] 720.3KB / 720.3KB  100%  1.2MB/s

[2/3] Verifying checksum
✔ sha256 OK

[3/3] Installing
✔ completed

Done.
```

## 代码示例

完整纯 BT 扩展流程：

```text
bt ext new calc
bt ext build calc -o calc.bts
bt ext check calc.bts
bt ext info calc.bts
bt ext install calc.bts project
bt install sqlite 1.0.0 --project project
```

安装后项目脚本调用：

```bt
result = calc(1).add(2).value()

// 输出：3
print result
```

## 注意事项

- `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` 更新解释器。交互提示符也支持相同命令。

### 语法

```text
bt update sqlite
bt update sqlite --project examples/app
```

### 参数

| 参数 | 类型 | 是否必填 | 默认值 | 有效值与含义 |
|---|---|---|---|---|
| `name` | 字符串 | 更新扩展时必填 | 无 | 已安装的官方扩展名，只能包含小写字母、数字和下划线，并以小写字母开头。 |
| `--project <dir>` | 路径字符串 | 否 | 当前工作目录 | 已存在且包含 `extensions/<name>/` 的项目目录。 |

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

### 返回值与注意事项

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