清单与权限

plugin.manifest.json 会告诉平台你是谁、体验托管在哪里，以及它需要哪些能力。我们会批准一个确切的版本、入口和权限组合。任一项变更后，新版本都需要重新审核。

示例

plugin.manifest.json

{
  "schema": "zenclub.plugin/v1",
  "id": "my-garden",
  "name": "My garden",
  "description": "Tend a small garden at your own pace.",
  "coverLabel": "A small garden",
  "version": "1.0.0",
  "sdkProtocol": "zenclub.rpc/1",
  "hostApi": {"major": 1, "minMinor": 2},
  "entry": "https://my-garden.example/v1.0.0/",
  "permissions": ["lifecycle.report", "storage.read", "storage.write", "session.report"],
  "optionalPermissions": ["moments.create", "header.setActions"],
  "modes": ["watch", "manual"],
  "tags": ["garden", "slow"]
}

字段

字段	规则
`schema`	始终为 `zenclub.plugin/v1`。
`id`	1 至 80 个字母、数字、点、下划线或连字符，且必须以字母或数字开头。创建后不可更改。
`name, description, coverLabel`	每项最多 2048 个字符的纯文本。`coverLabel` 是封面上的简短说明。
`version`	语义化版本，例如 `1.4.0` 或 `1.5.0-beta.1`。必须与传给 `connect()` 的 `version` 一致。
`sdkProtocol`	始终为 `zenclub.rpc/1`。
`hostApi`	所需的最低宿主 API 版本，格式为 `{major, minMinor}`。请申请可用的最低次版本。
`entry`	页面的绝对 HTTPS URL，不得包含用户名、密码或片段。仅 localhost 接受普通 HTTP。不得与平台共用源站。
`permissions`	体验运行所必需的能力。不得重复。
`optionalPermissions`	最多 32 项在获批后会使用的能力。不得重复列出必需能力。
`milestones`	可选：声明一个固定键、规则版本和最高等级；运营方会连同报告能力单独审核。
`modes`	从 `watch`、`manual` 和 `listen` 中选择一项或多项。只能报告已声明的模式。
`tags`	最多 10 个标签，每个不超过 32 个字符。

能力

每个 SDK 方法都对应一项能力。调用未获授的能力时，会在离开你的框架前以 FORBIDDEN 失败。请先用 sdk.supports(name) 检查可选能力。

能力	宿主 API	用途
`lifecycle.report`	1.0	报告加载、就绪或失败状态。
`storage.read`	1.0	读取一个存档槽。
`storage.write`	1.0	通过修订号检查写入存档槽。
`session.report`	1.0	报告运行、暂停或结束状态，以便计时。
`runs.finish`	1.0	记录已完成或重新开始的一局，最多附带 20 项数值指标。
`moments.create`	1.0	向访客提供一张可保存的图片。平台可能会先征求同意。
`achievements.request`	1.0	请求平台核验并授予徽章。
`counters.add`	1.2	为你增加运营者定义的共享计数。
`events.report`	1.2	报告简短的命名事件，例如章节完成。
`shares.request`	1.2	打开平台分享面板，分享徽章或你的体验。
`navigation.exit`	1.2	静静返回体验详情页。
`display.immersive`	1.3	请求平台隐藏体验周围的框架。
`header.setActions`	1.4	将操作放在平台页头。
`milestones.report`	1.6	玩家开启记录后，依据已确认的存档报告一项获准的私人城市装饰。

申请前先验证

命令行工具会运行与平台相同的检查，并确认你申请的宿主 API 可用。验证不会授予任何权限，只有审核通过才会授予。

shell

npx zenclub-plugin validate plugin.manifest.json --host=https://zenclub.app

宿主 API 版本

当前宿主接口版本为 1.6，接受申请 1.0 至 1.6 的插件。请申请满足需求的最低小版本，并用 sdk.supports() 检查可选方法。若要接收声音偏好，请在清单和 connect() 中都要求 1.5 或更高版本。未声明里程碑的旧插件仍会获得与以往相同的授权和上下文。

可选的城市里程碑

将 milestones.report 声明为可选项，并且只添加一个 milestones 条目。首个版本包含八个固定键：homestead、pond、clouds、bamboo、tea、stream、bell 和 lotus。每项规则版本均为对应的键后接 .1，并设为 maxTier: 2。审核会绑定这一组确切的组合、版本、条目和能力。自行编写声明不会授予访问权限。

plugin.manifest.json

{
  "hostApi": {"major": 1, "minMinor": 6},
  "optionalPermissions": ["milestones.report"],
  "milestones": [{"key": "tea", "ruleVersion": "tea.1", "maxTier": 2}]
}

报告为可选时，使用开发套件 0.9 构建的插件可以继续采用较低的最低版本。在 1.0–1.5 宿主上、未经批准或仅使用设备存储时，请保持正常游玩，并跳过报告。旧宿主的批准项必须省略新增授权。必需的里程碑报告需使用 1.6；记录不能成为游玩或登录的前提。