权限与 manifest

在 manifest.json 申请插件确实需要的能力，写明用途，交由服主确认。安装、保存配置和保存授权都不等于启动；权限必须与目标 Host 的能力和来源同时匹配。

一个完整的聊天插件声明

此声明允许订阅聊天、解析玩家身份和发送命令通知。它可搭配事件页的聊天命令示例；如果不需要发通知，删除命令操作及对应用途。

json

{
  "manifest_version": 1,
  "id": "example.chat-help",
  "version": "1.0.0",
  "host_api": {"major": 1, "min_minor": 1},
  "worker_protocol": {"major": 1, "min_minor": 0},
  "runtime": "python",
  "entrypoint": "main.py",
  "mode": "service",
  "session_required": true,
  "state_version": 1,
  "subscriptions": [
    {"name": "chat", "kind": "chat.received", "delivery": "durable"}
  ],
  "permissions": {
    "operations": ["framework.command.execute"],
    "services": [],
    "players": ["list"],
    "purposes": {
      "operation:framework.command.execute": "向请求帮助的玩家发送提示",
      "event:chat.received": "识别玩家输入的帮助命令",
      "players:list": "核对聊天玩家的身份"
    }
  },
  "dependencies": [],
  "exports": []
}

id 是插件 ID，安装名是管理员给某次安装的名称，两者不同。version 是插件制品版本，state_version 是业务状态版本；它们也不等于配置 revision 或权限 revision。入口文件必须随包提供。用工具包的 lint、pack 和 check 验证完整制品。

申请放在哪里

行为	声明位置	例子
执行动作	`permissions.operations`	`framework.command.execute`、`framework.scoreboard.add`
订阅持久事件	`subscriptions`	`chat.received`、`actor.observed`、`environment.observed`
读取或观察玩家	`permissions.players`	`list`、`observe`
调用插件服务	`permissions.services`	按被调用服务的公开标识申请。
发送指定协议包	操作权限及 `permissions.packet_send_ids`	两者都需申请和授权，包号不能为 0；预览及观察的字段见协议包。

不能用 * 或缩写替代完整操作名。用途写在 permissions.purposes：键使用 operation:<id>、service:<id>、event:<kind>、players:list、players:observe 或 packet_send:<id>，且必须引用真实申请的权限。用途非空，最多 512 UTF-8 字节，不含控制字符。

普通安装的持久状态读写不需要在 permissions.operations 虚构 storage.* 权限。ctx.storage 由当前安装身份约束；配置和业务状态也不是公开的跨插件数据库。

1.1.0 的资源会话按 scope.acquire、scope.renew、scope.close、scope.read、scope.lookup、scope.evidence 等精确成员申请，参见Scope 最小授权。远程 EP 另外需要三个会话成员权限，见连接与权限。资源占用不替代业务动作授权。

API 版本

使用的 manifest 字段	最低 `host_api.min_minor`
基础 operations、services 和 subscriptions	`0`
`players`、`packet_send_ids`、`purposes`	`1`
`packet_preview_ids`、`raw_packet_directions`	`3`
`packet_observe_ids`	`5`
`bus`	`6`
`bus.exports` 中的 `event` 成员	`7`
`runtime: "lua"`	`8`
`runtime: "go"` 与其 `target_os` / `target_arch`	`9`
`transport: "unix"` 或 `"tcp-loopback"`	`9`

以上新增字段即使是空数组或空对象，也要声明相应最低版本；不要写 null。当前 Host API 为 1.10，Worker 协议仍为 1.0。这个表是字段解析门槛，具体动作还必须由目标实例实现和授权。使用 1.1.0 的 Scope、远程会话或投影能力时，将插件的 host_api.min_minor 设为 10，并核对对应 SDK 与成员是否可用。

保存授权与启动

托管用户在实际管理入口审阅插件申请。拥有自部署管理权限的用户可以在工具包目录执行：

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" permissions hello
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" doctor hello
python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" start hello

TARGET_URL 和 TARGET_TOKEN_FILE 由目标实例管理员提供；不要猜测端口。权限向导输入“同意”保存后，后续启动提问可回车保持停止，再单独 start。空权限申请也需要确认。运行中的插件修改权限前先停止。

doctor 显示的来源缺口不能靠扩大权限解决。chat.received 需要存活且无故障的聊天或游戏事件来源；player.list_added、player.list_removed、actor.observed 和 environment.observed 需要原生游戏事件来源。只读模式仍会阻止世界写入。

AI 自动化与升级

使用 --json permissions-plan hello 获取 artifact_sha256、revision、requested、granted、missing 和用途。已获得用户明确授权的自动化，才能提交审核过的授权集合：

python3 runtime-admin.py --url "$TARGET_URL" --token-file "$TARGET_TOKEN_FILE" --json permissions-apply hello \
  --sha256 "$ARTIFACT_SHA256" --expected-revision "$PERMISSION_REVISION" \
  --grants "$APPROVED_GRANTS_JSON" --confirm

APPROVED_GRANTS_JSON 是 plan 中权限标识的 JSON 数组，只能包含该 manifest 请求的项。保存子集可以成功，但有缺口时无法启动。apply 不启动插件。

升级只继承新 manifest 仍申请的已授权限；新权限需要重新确认。若制品 SHA 或权限 revision 冲突，重新读取并审阅差异，不能只换 revision 重交旧确认。

能力与权限对照入口

按实际调用查找完整操作名和参数：命令与计分板、世界、物品与库存、协议包。通知复用命令权限；存储与业务事务按当前安装隔离；在线服务同时需要服务导出、调用方授权及可用的提供方。后台任务和配置读取本身不会增加游戏权限。

握手返回的 ctx.installation.capabilities 是元数据快照，激活后的 ctx.capabilities 描述当时能力；它们都不能取代每次调用时 Host 的授权、来源、会话及只读状态检查。

Bus 授权

Bus read/service/op/View 使用精确 permissions.services 成员及管理授权 service:<member>。旧 permissions.operations grant 不能替代它；例如 framework.command.execute 与 command.execute 分属两种入口。在线事件还需对应事件声明和授权。完整边界见Bus和完整示例。

权限与 manifest ​

一个完整的聊天插件声明 ​

申请放在哪里 ​

API 版本 ​

保存授权与启动 ​

AI 自动化与升级 ​

能力与权限对照入口 ​

Bus 授权 ​