# 扩展打包与安装

## 功能

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

## 命令

```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
```

可先打开官网扩展库页面 `/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 install` 第一阶段只支持 `major.minor.patch` 三段式版本，不支持范围版本和传递依赖。
- 扩展 CLI 命令成功时会向终端输出构建、安装或检查结果；失败时输出中文错误，不会生成可部分加载的 `.bts` 包。
- 默认构建已启用 `extensions` feature，可以直接使用 `bt ext`；只有使用 `--no-default-features` 构建轻量版时，`bt ext` 和项目扩展加载才不可用。