plugin.json 位于 .astraviapkg 插件包的 ZIP 容器根目录（或归档内唯一的顶层文件夹里）。宿主在加载代码前用它校验身份、兼容性和权限，因此清单必须与构建产物一致。
清单结构的唯一实现是 @astravia-org/plugin-sdk/manifest 导出的 TypeBox Schema：PluginManifestSchema 可直接序列化为 JSON Schema，parsePluginManifest() 负责校验、默认值、去重、相对路径归一化和跨字段约束。Schema 有意允许未知字段，这样更高版本清单不会被旧宿主直接拒绝。
{
"id": "my-plugin",
"name": "My Plugin",
"version": "0.1.0",
"pluginApiVersion": "^2.0.0",
"entry": "dist/mf-manifest.json",
"moduleFederation": {
"remoteName": "my_plugin",
"expose": "./plugin"
},
"styles": ["dist/style.css"],
"permissions": ["ui.slot.activity-tab", "agent.command.run", "network.fetch"],
"commands": ["git"],
"network": { "allowedHosts": ["api.example.com", "*.cdn.example.com"] },
"defaultLocale": "zh"
}字段
Prop
Type
路径与主机名会被归一化
所有清单路径都会过越界校验：拒绝绝对路径与盘符前缀，展开 . 与 ..，向上越过插件根直接报错。安装时还会再查一遍，声明的资源必须真实存在、类型正确且位于包根之内。
network.allowedHosts 与 browser.allowedHosts 的每一项也会归一化：* 表示全通配，*.example.com 是前缀通配，带端口、用户名或密码的写法一律拒绝。通配项不匹配裸域名本身，*.example.com 不覆盖 example.com。
安装目录与版本
用户插件按版本存放在 ~/.astravia/plugins/<id>/versions/<version>/。安装一个更新版本只被记录为 pending，应用继续加载当前活动版本，直到触发 reload 才切换。调试时改了代码要提升 version 并 reload 才稳妥生效。
系统插件不进这个目录，随应用发布、每次启动从只读目录重新发现，声明的权限自动全量授予且用户不可撤销。
声明、授权与校验
在清单中声明
在 plugin.json 的 permissions 数组列出权限。没声明的权限永远拿不到。
安装时授权
用户在插件页逐项勾选授权。Agent 通过本地路径安装时，用户确认后可按声明一次性授予。
运行时校验
宿主在调用对应 API 时再次校验，声明与授权必须同时成立。运行时也可以用 ctx.permissions.has() 自查、require() 主动抛错。
更新插件时，宿主保留用户已授予且新版本仍声明的权限，不自动授予新增权限，也不恢复用户主动撤销的权限——从一份空的授权记录无法反推用户原来的选择。
权限清单
清单里的 agent.agents、agent.teams、guidingWords，以及 ctx.ui.notify 和 ctx.i18n 都不需要权限。
commands 是命令执行的第二道闸
ctx.command.run 要跑一个二进制，需要 agent.command.run 权限并且该可执行文件名在清单 commands 里。未列入的二进制被硬拒绝；已声明的可以由用户在插件设置里逐条开关，关闭后调用被拦截。
宿主不经用户可控的 shell 启动进程，node、npm、npx 会被重定向到宿主托管的运行时。
最小权限原则
只声明插件实际使用的权限，声明越小用户授权越省心、审核越快。开发时先从最小清单开始，调用宿主 API 报权限错误时确认该行为确实必要，再增加对应权限并重新走安装授权。不要为了省事复制其他插件的完整权限数组。