Business Plugin Manifest V1

状态：Accepted Contract

业务插件清单由独立控制面读取和校验，Core 当前不会读取它。清单只声明插件身份、版本、能力、服务、UI、兼容性、发布者和 Core API 权限，不授予数据库、路由或 secret 权限。

1. 最小清单

{
  "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. 签名和哈希

{
  "algorithm": "ed25519",
  "key_id": "PUBLISHER_KEY_ID",
  "signature": "BASE64_SIGNATURE"
}

签名覆盖 manifest.json 原始字节。包内每个服务文件和 UI 文件的 SHA-256 由清单声明。验证器必须拒绝尾随 JSON、重复字段、未知字段、无效 Base64、大小写错误的哈希和不匹配的 key ID。

4. 兼容性门禁

清单 schema 版本不匹配：incompatible。
Core 不在 requires 范围：incompatible。
Core 在范围内但未列入 tested_core_versions：安装后保持 disabled，要求管理员确认。
业务能力、服务协议或 UI 版本不支持：禁止启用。
升级只产生新 revision；旧 active revision 在新版本健康和契约测试通过前保持可用。

2.9 KiB Raw Permalink Blame History

Business Plugin Manifest V1

1. 最小清单

2. 字段规则

3. 签名和哈希

4. 兼容性门禁

2.9 KiB

Raw Permalink Blame History