79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# Business Plugin Manifest V1
|
|
|
|
状态：Accepted Contract
|
|
|
|
业务插件清单由独立控制面读取和校验，Core 当前不会读取它。清单只声明插件身份、版本、能力、服务、UI、兼容性、发布者和 Core API 权限，不授予数据库、路由或 secret 权限。
|
|
|
|
## 1. 最小清单
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"plugin_id": "DOMAIN_PLUGIN_ID",
|
|
"name": "DOMAIN_PLUGIN_NAME",
|
|
"version": "1.0.0",
|
|
"core_api_baseline": "sub2api-0.1.183",
|
|
"tested_core_versions": ["0.1.183"],
|
|
"capabilities": ["DOMAIN_CAPABILITY_V1"],
|
|
"backend": {
|
|
"listen_env": "PLUGIN_PORT",
|
|
"health_path": "/healthz",
|
|
"readiness_path": "/readyz"
|
|
},
|
|
"ui": {
|
|
"entrypoint": "/admin/",
|
|
"menu": {
|
|
"id": "DOMAIN_PLUGIN_ID",
|
|
"label": "DOMAIN_PLUGIN_LABEL",
|
|
"visibility": "admin",
|
|
"sort_order": 200
|
|
}
|
|
},
|
|
"publisher": {
|
|
"key_id": "PUBLISHER_KEY_ID"
|
|
},
|
|
"core_api_allowlist": [
|
|
"POST /api/v1/auth/login",
|
|
"POST /api/v1/auth/login/2fa",
|
|
"POST /api/v1/auth/refresh",
|
|
"POST /api/v1/auth/logout",
|
|
"GET /api/v1/auth/me",
|
|
"GET /api/v1/settings/public",
|
|
"GET /api/v1/admin/DOMAIN_READ_ENDPOINT"
|
|
]
|
|
}
|
|
```
|
|
|
|
## 2. 字段规则
|
|
|
|
- `plugin_id`：小写、稳定、全局唯一；不得包含 `/`、空格或路径跳转。
|
|
- `version`：插件自身 SemVer，与 Core 版本和发行标签分离。
|
|
- `core_api_baseline`：插件编译和契约测试所针对的 Core 版本。
|
|
- `tested_core_versions`：只填写真实执行过契约测试的版本。
|
|
- `capabilities`：一个或多个业务能力 ID；控制面不为未实现的能力自动创建路由。
|
|
- `backend.health_path`、`readiness_path`：只能是插件服务根下的绝对 HTTP 路径（例如 `/healthz`、`/readyz`），不得包含主机、查询、片段或路径跳转。
|
|
- `ui.entrypoint`：只能指向包内 UI 资源。
|
|
- `ui.menu`：管理员菜单声明；控制面必须校验 ID 与插件 ID 绑定，`visibility` 只能是 `admin`。
|
|
- `publisher.key_id`：必须匹配受信任发布者配置。
|
|
- `core_api_allowlist`：方法和路径必须逐项列出，不允许通配符、任意 URL 或未声明查询参数。
|
|
|
|
## 3. 签名和哈希
|
|
|
|
```json
|
|
{
|
|
"algorithm": "ed25519",
|
|
"key_id": "PUBLISHER_KEY_ID",
|
|
"signature": "BASE64_SIGNATURE"
|
|
}
|
|
```
|
|
|
|
签名覆盖 `manifest.json` 原始字节。包内每个服务文件和 UI 文件的 SHA-256 由清单声明。验证器必须拒绝尾随 JSON、重复字段、未知字段、无效 Base64、大小写错误的哈希和不匹配的 key ID。
|
|
|
|
## 4. 兼容性门禁
|
|
|
|
1. 清单 schema 版本不匹配：`incompatible`。
|
|
2. Core 不在 `requires` 范围：`incompatible`。
|
|
3. Core 在范围内但未列入 `tested_core_versions`：安装后保持 disabled，要求管理员确认。
|
|
4. 业务能力、服务协议或 UI 版本不支持：禁止启用。
|
|
5. 升级只产生新 revision；旧 active revision 在新版本健康和契约测试通过前保持可用。
|