发布扩展
发布扩展
功能
官方扩展的元数据、编辑器接口契约和文档只维护 bt-lang/extension/<name>/ 中的一套源文件：manifest.json、bindings.json、README.md 和 README.zh-CN.md。发布时以完全相同的文件内容和文件名复制到官网不可变版本目录。
官网自有的 db/ext/index.json 只保存不适合写入源码 manifest 的注册表状态：最新发布版本、包文件名、下载 URL、SHA-256、字节大小、发布时间、撤回状态和下载计数。不再存在 info.json 或 readme-source.json。
语法
node tools/extensions/publish-extension.js image 1.0.0
生成的版本目录如下：
db/ext/image/1.0.0/ ├── manifest.json ├── bindings.json ├── README.md ├── README.zh-CN.md └── image-1.0.0.bts
命令要求四个源文件均已提交到 github/main，校验 manifest 与 bindings 一致性和 Markdown 格式，复制精确文件，核对扩展包摘要与大小，然后更新 db/ext/index.json。生成快照不得手工编辑。
Manifest 目录字段
扩展运行时字段见 manifest.json。官方发布还要求以下由源码维护的目录字段：
| 字段 | 类型 | 必填 | 默认值 | 有效值 | 含义 |
|---|---|---|---|---|---|
summary | String | 是 | 无 | 非空文本 | 英文目录短摘要。 |
description | String | 是 | 无 | 非空文本 | 英文完整说明。 |
author | String | 是 | 无 | 文本 | 源码作者。 |
developer | Object | 是 | 无 | 见下表 | 公开开发者或发布者身份。 |
repository | String | 是 | 无 | GitHub 或 Gitee 公开 HTTPS URL | 可审查源码目录。 |
license | String | 是 | 无 | SPDX 表达式 | 扩展包许可证。 |
locales | Object | 是 | {} | 规范 BCP 47 键 | 只包含本地化展示元数据。 |
developer 字段
| 字段 | 类型 | 必填 | 默认值 | 有效值 | 含义 |
|---|---|---|---|---|---|
id | String | 是 | 无 | 小写标识符 | 稳定机器身份。 |
name | String | 是 | 无 | 非空文本 | 默认英文显示名称。 |
homepage | String | 否 | 无 | 公开 URL | 开发者主页。 |
locales.<tag> 字段
| 字段 | 类型 | 必填 | 默认值 | 有效值 | 含义 |
|---|---|---|---|---|---|
summary | String | 否 | 顶层 summary | 非空文本 | 本地化短摘要。 |
description | String | 否 | 顶层 description | 非空文本 | 本地化完整说明。 |
developer_name | String | 否 | developer.name | 非空文本 | 本地化开发者显示名称。 |
语言键使用规范 BCP 47 大小写。简体中文始终使用 zh-CN，与 README.zh-CN.md 完全一致；manifest 中不得再存储 zh-cn、zh-hans 或 zh-Hans 等别名。官网中文 URL 仍是 /zh-hans/，仅在路由内部映射到 zh-CN。
公开元数据 API
| URL | 响应 | 缓存策略 |
|---|---|---|
/api/ext/<name> | 最新 manifest 与注册表发布记录 | 重新验证 |
/api/ext/<name>/<version> | 指定版本 manifest 与注册表发布记录 | 重新验证 |
/api/ext/<name>/<version>/manifest.json | 精确发布的 manifest.json | 不可变 |
/api/ext/<name>/<version>/bindings.json | 供编辑器补全与诊断使用的精确 bindings.json | 不可变 |
/api/ext/<name>/<version>/README.md | 精确英文 README | 不可变 |
/api/ext/<name>/<version>/README.zh-CN.md | 精确简体中文 README | 不可变 |
/api/ext/<name>/readme/<version> | 英文 README.md | 重新验证 |
/api/ext/<name>/download/<version> | 精确 .bts 扩展包 | 不可变 |
全部精确版本文件响应都允许跨域 GET。工具应先通过 /api/ext/<name> 确定版本，再缓存不可变的版本化 manifest.json 和 bindings.json URL。
返回值与回退
英文使用 manifest 顶层展示字段和 README.md。/zh-hans/ext/<name> 页面读取 manifest.locales['zh-CN'] 和 README.zh-CN.md，缺少翻译时回退英文。机器标识、API 名称、版本、哈希、ABI 名称、文件名和下载 URL 永不本地化。
注意事项
-
bt-lang/main的变化不会修改官网，只有明确发布更高扩展版本时才更新。 - 注册表审查和包完整性只适用于精确发布版本及其 SHA-256。
-
bindings.json是运行时校验、VS Code 自动补全、参数提示、对象方法、返回类型和生命周期元数据的规范机器接口。 - 加载本地
.bts时不会查询官网；注册表是分发目录，不是运行时白名单。