# 扩展快速开始

## 功能

本页从一个 `calc` 计算扩展示例开始，演示如何创建扩展开发目录、构建 `.bts` 包、安装到项目并在 `main.bt` 中调用。零基础用户建议先按本页跑通流程，再阅读 [运行机制](/docs/extensions/mechanism)。

## 语法

快速开始会用到这些命令：

```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 main.bt
```

## 参数

| 参数 | 说明 |
| ------ | ------ |
| `calc` | 扩展开发目录名，也会作为默认扩展名。 |
| `calc.bts` | 构建输出的扩展包文件。 |
| `project` | 要安装扩展的目标 BT 项目目录。 |
| `main.bt` | 项目入口脚本。 |

## 准备项目

先准备一个普通 BT 项目目录：

```text
project/
└── main.bt
```

`main.bt` 用来调用扩展：

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

// 输出：3
print result
```

此时还没有安装 `calc` 扩展，直接运行会找不到 `calc`。下一步先创建扩展。

## 创建扩展

执行：

```text
bt ext new calc
```

这会生成一个纯 BT 扩展开发目录：

```text
calc/
├── manifest.json
├── bindings.json
└── src/
    └── lib.bt
```

默认脚手架已经包含一个链式计算对象：`calc(1).add(2).value()`。

## 构建扩展包

在 `calc` 目录外执行：

```text
bt ext build calc -o calc.bts
```

构建时会读取 `manifest.json` 和 `bindings.json`，检查入口源码，并把开发目录打包成 `calc.bts`。

构建后可以先检查包信息：

```text
bt ext check calc.bts
bt ext info calc.bts
```

## 安装到项目

把扩展安装到项目目录：

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

安装后的结构是：

```text
project/
├── main.bt
└── extensions/
    └── calc.bts
```

然后在 `project` 目录运行项目：

```text
bt main.bt
```

输出应为：

```text
3
```

## 返回值

`bt ext` 命令成功时会在终端输出创建、构建、检查或安装结果；失败时输出中文错误。示例脚本中 `calc(1).add(2).value()` 返回整数 `3`。

## 代码示例

扩展对象可以继续链式调用：

```bt
num = calc(10)
value = num.add(5).add(2).value()
closed = num.close()

// 输出：[17,true]
print [value, closed]
```

## 注意事项

- `bt ext new calc` 会根据目录名生成扩展名，目录名必须使用小写字母、数字和下划线，并且以小写字母开头。
- `bt ext install calc.bts project` 会把包复制到 `project/extensions/calc.bts`；同名扩展会被覆盖。
- 项目启动时才会加载 `extensions/` 下的 `.bts` 包，开发目录 `calc/` 不会被项目自动加载。
- 如果运行用的 BT 构建没有启用 `extensions` feature，存在 `extensions/` 目录的项目会报错提示扩展能力不可用。