manifest.json

AI 原文

manifest.json

功能

manifest.json 是扩展包的身份和运行声明。它告诉 BT 这个包是不是 .bts 扩展、扩展叫什么、使用什么后端和入口文件、最低 BT 版本、调用大小上限以及运行时模式。扩展是用户信任的本地程序依赖，不声明包级权限。

语法

纯 BT 扩展示例：

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

WASM shared runtime 配置示例：

参数

字段	类型	说明
`format`	String	固定为 `bts`。
`format_version`	Number	包格式版本，使用 `1`。
`name`	String	扩展包名称，只能使用小写字母、数字和下划线，并以小写字母开头。
`version`	String	扩展自身版本，使用三段式 SemVer，例如 `1.0.0`。
`summary`	String	可选英文目录短摘要。
`description`	String	可选说明文本。
`author`	String	可选作者文本。
`developer`	Object	可选稳定开发者身份，包含 `id`、`name` 和可选 `homepage`。
`repository`	String	可选公开源码仓库 URL。
`license`	String	可选 SPDX 许可证表达式。
`locales`	Object	可选本地化展示元数据，键使用 `zh-CN` 等规范 BCP 47 标识。
`kind`	String	后端类型，只能是 `bt` 或 `wasm`。
`abi`	String	后端 ABI，必须和 `kind` 匹配。
`bt_min_version`	String	扩展要求的最低 BT 版本。
`api_version`	Number	bindings 语义版本，使用 `1`。
`entry`	String	后端入口文件的包内相对路径。
`bindings`	String	bindings 描述文件的包内相对路径。
`limits`	Object	单次调用的参数和返回值编码大小上限。
`runtime`	Object	可选运行时模式配置；缺省等同 `mode: "thread_local"`。

每个 locales.<tag> 对象只接受 summary、description 和 developer_name。语言键必须使用规范 BCP 47 大小写；简体中文统一为 zh-CN，与 README.zh-CN.md 完全一致。本地化只改变展示文本，不改变扩展名称、API 标识、配置字段或事件名。

kind 与 abi

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

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

runtime 运行时配置

字段	类型	默认值	说明
`mode`	String	`thread_local`	运行时模式，只能是 `thread_local` 或 `shared`。
`workers`	Number	`1`	shared 模式 worker 数量，范围 `1..=64`。
`queue_limit`	Number	`1024`	shared 模式等待队列长度，范围 `1..=65536`。
`call_timeout_ms`	Number	`30000`	shared 模式单次调用超时，范围 `1..=300000`。
`idle_ttl_ms`	Number	`300000`	shared 模式空闲保留时间，范围 `1..=3600000`。
`max_objects`	Number	`65536`	shared 模式服务级对象数量上限，范围 `1..=65536`。
`max_worker_objects`	Number	`4096`	shared 模式单个 worker 内对象数量上限，范围 `1..=4096`，且不能大于 `max_objects`。
`max_inflight_calls`	Number	`64`	shared 模式执行中调用数量上限，范围 `1..=4096`。

runtime 缺失时，扩展继续使用当前线程本地 Runner 缓存，不改变现有扩展行为。mode=shared 第一版只允许 kind=wasm，纯 BT 扩展声明 shared 会在 manifest 校验阶段报错。

当前版本已经接入项目级 ExtensionService。声明 mode=shared 的 WASM 扩展会创建独立有界 worker 队列，入口函数可以通过 worker 返回原始值或扩展对象；返回扩展对象时宿主会分配 host_object_id，对象方法调用前再路由回创建该对象的 worker 本地对象 ID。队列满、服务关闭、执行中调用超过上限、服务级对象数或单 worker 对象数超过上限时会返回中文错误。

call_timeout_ms 不只是调用线程等待上限。shared worker 会启用 Wasmtime epoch interrupt，超时后宿主会标记目标 worker、触发 WASM trap，并在 worker 返回后重建 WASM Store/Instance，避免超时调用永久占用服务容量。服务统计会包含 workers、queued、running、completed、failed、timed_out、objects 和每个 worker 的对象数量。

返回值

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

代码示例

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

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

注意事项

entry 和 bindings 必须是包内安全相对路径，不能使用绝对路径、反斜杠、空路径、.、.. 或带盘符的路径。
entry 不能和 bindings 指向同一个文件。
permissions 字段已经删除。仍包含该字段的扩展包无法通过 manifest 校验，必须按新版 .bts 格式重新构建。
所有已安装扩展使用相同宿主 ABI；实际能力由 BT 进程级策略和操作系统账号决定，与包来源或是否被官网收录无关。
安装扩展即表示信任其代码。官网只审查自己分发的精确开源版本；本地、私有、修改版和闭源扩展不受限制，也不属于官网审核范围。
limits.max_args_bytes 和 limits.max_result_bytes 不能为 0，也不能超过宿主硬上限。
runtime 中不能出现未知字段，避免扩展作者误以为未实现的配置已经生效。
runtime.mode=shared 不改变 BT 请求变量生命周期，也不会让普通脚本全局变量跨请求共享。
runtime.mode=shared 已支持扩展对象宿主路由；close() 或 dispose() 标记为 lifecycle: "dispose" 且调用成功后，宿主对象句柄会失效。
runtime.mode=shared 的 call_timeout_ms 会触发目标 worker 的 WASM 中断和运行态重建，不能用于长期阻塞宿主 hostcall 的精确取消。
扩展名、入口名、参数名和方法名都应遵守 BT 的 snake_case 命名风格。