# 发布扩展

## 功能

官方扩展的元数据、编辑器接口契约和文档只维护 `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`。

## 语法

```powershell
node tools/extensions/publish-extension.js image 1.0.0
```

生成的版本目录如下：

```text
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](/zh-hans/docs/extensions/manifest)。官方发布还要求以下由源码维护的目录字段：

| 字段 | 类型 | 必填 | 默认值 | 有效值 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `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` 时不会查询官网；注册表是分发目录，不是运行时白名单。