# manifest.json

## 功能

`manifest.json` 是扩展包的身份和运行声明。它告诉 BT：这个包是不是 `.bts` 扩展、扩展叫什么、用什么后端运行、入口文件在哪里、最低 BT 版本是多少、需要哪些权限，以及单次调用允许传输多大的参数和返回值。

## 语法

纯 BT 扩展示例：

```json
{
    "format": "bts",
    "format_version": 1,
    "name": "calc",
    "version": "1.0.0",
    "description": "calc extension",
    "author": "",
    "kind": "bt",
    "abi": "bts-bt-1",
    "bt_min_version": "1.1.0",
    "api_version": 1,
    "entry": "src/lib.bt",
    "bindings": "bindings.json",
    "permissions": {
        "fs_read": false,
        "fs_write": false,
        "net": false,
        "http": false,
        "process": false,
        "env": false
    },
    "limits": {
        "max_args_bytes": 16777216,
        "max_result_bytes": 16777216
    }
}
```

WASM 扩展只需要把后端相关字段改为：

```json
{
    "kind": "wasm",
    "abi": "bts-wasi-1",
    "entry": "module.wasm"
}
```

## 参数

| 字段 | 类型 | 说明 |
| ------ | ------ | ------ |
| `format` | String | 固定为 `bts`。 |
| `format_version` | Number | 包格式版本，使用 `1`。 |
| `name` | String | 扩展包名称，只能使用小写字母、数字和下划线，并以小写字母开头。 |
| `version` | String | 扩展自身版本，使用三段式 SemVer，例如 `1.0.0`。 |
| `description` | String | 可选说明文本。 |
| `author` | String | 可选作者文本。 |
| `kind` | String | 后端类型，只能是 `bt` 或 `wasm`。 |
| `abi` | String | 后端 ABI，必须和 `kind` 匹配。 |
| `bt_min_version` | String | 扩展要求的最低 BT 版本。 |
| `api_version` | Number | bindings 语义版本，使用 `1`。 |
| `entry` | String | 后端入口文件的包内相对路径。 |
| `bindings` | String | bindings 描述文件的包内相对路径。 |
| `permissions` | Object | 扩展声明的能力权限。 |
| `limits` | Object | 单次调用的参数和返回值编码大小上限。 |

## kind 与 abi

| kind | abi | 含义 |
| ------ | ------ | ------ |
| `bt` | `bts-bt-1` | 入口文件是 BT 源码，函数和对象方法由纯 BT Runner 执行。 |
| `wasm` | `bts-wasi-1` | 入口文件是 WASM 模块，调用通过 WASI P1 和 BtValueBinary 完成。 |

如果 `kind` 和 `abi` 不匹配，扩展会在加载阶段报错。

## 权限说明

| 权限 | 说明 |
| ------ | ------ |
| `fs_read` | 允许声明读取文件路径参数。 |
| `fs_write` | 允许声明写入文件路径参数。 |
| `net` | 预留给网络通信能力声明。 |
| `http` | 预留给 HTTP 客户端能力声明。 |
| `process` | 预留给进程能力声明。 |
| `env` | 预留给环境变量能力声明。 |

权限必须和运行进程的权限配置同时允许。扩展声明了某项权限，但运行进程禁止该能力时，扩展会加载失败。

## 返回值

`manifest.json` 不是脚本函数，没有运行时返回值。校验成功时，BT 会继续读取 bindings 和入口文件；校验失败时，加载过程返回中文错误并停止加载该扩展。

## 代码示例

纯 BT 扩展入口和 manifest 的对应关系：

```bt
fn calc(value) {
    value
}
```

`manifest.entry` 指向包含这段源码的 `src/lib.bt`，`manifest.kind` 写 `bt`，`manifest.abi` 写 `bts-bt-1`。

## 注意事项

- `entry` 和 `bindings` 必须是包内安全相对路径，不能使用绝对路径、反斜杠、空路径、`.`、`..` 或带盘符的路径。
- `entry` 不能和 `bindings` 指向同一个文件。
- `limits.max_args_bytes` 和 `limits.max_result_bytes` 不能为 `0`，也不能超过宿主硬上限。
- 扩展名、入口名、参数名和方法名都应遵守 BT 的 snake_case 命名风格。