EOS清单、权限与兼容性参考
清单使用 UTF-8 TOML，结构版本为 schemaVersion = 1。大小上限 1 MiB；未知字段、重复键、类型错误会拒绝。不要使用旧后台的 plugin.json 或历史 Agent [tools] 清单。完整起步样例见快速开始。
顶层字段
| 字段 | 必填 | 当前含义 |
|---|---|---|
schemaVersion | 是 | 固定为整数 1 |
[plugin] | 是 | 身份、名称、版本、说明、许可证及资源 |
[compatibility] | 是 | 平台 API 版本范围、portable/targeted、应用限制 |
[[modules]] | 是 | 1–64 个模块 |
[[permissions]] | 否 | 模块按 ID 引用的宿主能力权限 |
[configuration] | 否 | 包内自包含 JSON Schema；不存秘密 |
[data] | 否 | 插件私有数据版本与纯 WASM 迁移 |
[[dependencies]] | 否 | 同市场插件版本依赖 |
[[exports]] | 否 | 合同扩展点；当前 Agent 没有跨插件导出调用适配器 |
plugin.id 格式为 publisher.slug，只允许小写 ASCII 字母、数字与段内连字符，总长最多 128；例如 acme.text-tools。publisher 必须与 ID 第一段相同。名称最多 128 字符，description 最多 8192。版本是完整 SemVer，不允许 +build 区分发布；0.1.0-dev.1 是预发布版本，不能假定普通版本范围自动接受它。正式版本最好用于第一次入门测试，避免混淆预发布筛选与打包错误。
必填元信息为 id/publisher/name/version/description/license。可选 homepage/repository 仅作说明，icon 与 i18n 指向包内文件。声明文件必须存在。
portable 禁止顶层 applications；targeted 要求非空列表，例如：
[compatibility]
platformApi = "^1.0.0"
scope = "targeted"
applications = [{ id = "eos-agent", version = ">=1.0.0" }]
插件 scope 与安装 scope 不同：前者表示适用产品范围，后者表示用户/工作区/组织安装隔离。当前 Agent 只提供用户安装 scope；包、授权和配置不会跨应用、账号或设备自动共享。
modules 字段
| 字段 | 必填/默认 | 规则 |
|---|---|---|
id | 必填 | 插件内唯一，小写字母数字与连字符 |
type | 必填 | skills/v1、mcp-stdio/v1、mcp-http/v1、wasm-component/v1、webview/v1 |
required | 必填 bool | true 的模块必须兼容；false 的模块由用户选择 |
activation | 必填 | 结构接受 on-demand/on-command/on-event/on-startup；当前并未实现一套可订阅的事件调度 API，见下文 |
requires | 必填数组 | {capability, version}；不用能力时写 [] |
permissions | 必填数组 | 引用顶层 permission.id，不是 capability ID；不用权限时写 [] |
entry | 除 HTTP MCP 外必填 | 包内相对文件路径；Skills 是目录 |
endpoint | HTTP MCP 必填 | 固定 HTTPS URL；HTTP MCP 禁止 entry |
profile | stdio MCP 必填 | 当前只运行 trusted-process；sandboxed-process 会不兼容 |
world | WASM 必填 | 固定 eos:plugin/[email protected] |
args/env | 默认 []/{} | stdio MCP 的固定参数、非秘密环境变量；当前不做配置模板插值 |
applications | 默认 [] | 模块自己的可选应用范围；不赋予应用能力 |
contributions | 默认 [] | 页面使用 {kind,id,title}；kind 为 panel/page/settings，id 不含点/斜线 |
limits | 可选 | memoryBytes/fuel/timeoutMs/concurrency；并非每个执行器都实施每个字段 |
optional 模块即使在包中也不会自动选中；用户勾选后才激活。当前 Agent 安装提交时注册所选 Skills、探测 MCP、加载 WASM 工具，页面在点击打开时显示。activation 没有提供定时器或任意事件订阅；on-event/on-startup 会被策略标记为需要授权，不能据此宣称存在后台任务调度能力。
WASM 实施的限制：内存默认/上限 64 MiB，fuel 默认 1,000,000、上限 10,000,000；单次调用默认/上限 30 秒，加载 describe 和迁移 5 秒。输入/输出各最多 1 MiB。每次调用新建实例，不能把全局内存当持久存储。concurrency 当前不是可依赖的每模块并发配额实现。其他模块不要把 limits 当成操作系统沙箱承诺。
能力要求与权限的区别
requires 决定“这个宿主能否提供功能”；permissions 决定“模块请求调用哪些功能”。声明 requires 不会生成授权，权限确认也不会实现不存在的能力。
当前可声明的 Agent 能力为：
| 能力 | 版本 | 用法 |
|---|---|---|
eos.ai.skills | 1.0.0 | Skills 注册；页面/WASM 的 invoke 仅可指向当前插件命名空间 |
eos.ai.skills.tool-policy | 1.0.0 | 显式调用技能时执行 allowed-tools 限制 |
eos.ui.panel | 1.0.0 | 仅实际启用原生页面隔离的宿主声明 |
例如页面请求激活自己的技能：
[[permissions]]
id = "invoke-summary"
capability = "eos.ai.skills"
actions = ["invoke"]
resources = { skills = ["tutorial.hello-skills/writing/summarize"] }
reason = "在当前插件内启用摘要技能"
相应页面模块需 permissions = ["invoke-summary"] 且声明 requires。资源名是完整技能名；资源对象 {} 表示允许本插件命名空间内技能，非空对象仅支持一个 skills 数组，按完整名称精确匹配。不支持通配符、其他键或跨插件调用。
SDK 调用参数与返回值见模块手册。这里的 invoke 是选择/激活技能，不等同于一次模型完成请求，不返回 AI 生成文本。
普通配置
[configuration]
schema = "schemas/config.json"
{
"type": "object",
"properties": { "title": { "type": "string", "maxLength": 80 } },
"required": ["title"],
"additionalProperties": false
}
Schema 必须是包内 JSON 对象，至多 1 MiB，$ref 只能引用 # 开头的本地定义。安装对话框填写 JSON；Schema 的 default 不会自动填充值。页面用 configuration.get，WASM 用 host.call("eos.plugin.configuration", "get", "{}") 读取。当前不会自动把普通配置灌进 Skills 文本、MCP args/env 或 endpoint。
声明 credentials 会要求 eos.credentials.<kind> 能力；当前 Agent 不提供。不要把 API key 放入普通配置、env、包、页面或日志。
私有数据与迁移
页面的 storage 是安装级私有 JSON 键值对象，所选页面模块共享；不是每个 module 单独隔离。键最多 256 字节，总序列化数据至多 1 MiB。卸载默认保留数据，停用不清数据。不要读写插件管理器的磁盘文件来调试数据。
[data]
version = 1
migrations = [{ fromVersion = 0, toVersion = 1, module = "migrate-data" }]
当前 Schema 只接受 version 和 migrations，没有 recovery 字段；运行时依靠事务快照恢复。迁移模块必须是清单中的 WASM 模块，每段前进且不超过目标数据版本，迁移调用为 invoke("migrate", {fromVersion,toVersion,data} 的 JSON 字符串)，返回升级后的数据对象 JSON；未保存过数据时 input.data 可能为 null。每条迁移记录需使用不同 module ID（解析器拒绝重复的迁移 module）。迁移时授权清空，不允许外部业务副作用；缺迁移路径、非法返回、崩溃或降级都会失败。先在测试安装中保存 v0 数据，再升级核对保留字段，不能只验证全新安装。
包和制品目标
.eos-plugin 是 tar.gz，根目录需 plugin.toml、README.md、LICENSE 及全部声明入口。不能包含符号/硬链接、设备文件、绝对路径、..、反斜线、盘符、保留设备文件名、大小写/Unicode 归一化碰撞或特殊权限位。默认上限：压缩 200 MiB、解压 500 MiB、单文件 200 MiB、10,000 个归档条目、16 层路径。
上传目标不是清单字段，由上传请求另行声明：
{"os":"any","arch":"any","abis":["skills/[email protected]"]}
原生包按机器声明，如 linux/aarch64、windows/x86_64。当前 Core 在 macOS 报告 os: "macos"，因此上传使用 macos；架构使用 aarch64/x86_64，不是 arm64/amd64。精确目标优先于 any/any；同优先级多匹配拒绝。abis 是执行器 type@abi，不是 WIT world；列出的每项都必须存在于宿主，因而不要把可选页面的 ABI 塞进本应支持无页面宿主的通用制品。
同一发布的所有目标需要完全相同的 plugin.toml 原始字节、相同市场多语言投影；修改换行也会改变清单摘要。一个目标元组只有一个制品。当前依赖由服务端解析并固定到安装计划；dependency-lock.json 在目标规范中要求，但当前包读取器未强制它、也不据它解析依赖。不要把它当成已生效的锁定机制；作者先使用无依赖模板，依赖版本以确认计划为准。
市场多语言
[plugin.i18n]
zh = "i18n/zh.json"
en = "i18n/en.json"
{"$eos.marketplace":{"schemaVersion":1,"name":"三点摘要","description":"将输入整理为三条要点"}}
语言键使用规范小写，例如 zh、en、pt-br。最多 32 种投影；每个展示资源至多 16 KiB；name 至多 256 UTF-8 字节、description 至多 8192 字节，不允许空白、控制字符、重复/未知保留字段。普通 UI JSON 键可共存，不会自动翻译。当前 CLI validate 检查资源存在，不检查 marketplace 投影内容；服务端上传时才严格检查。更新市场名称/简介需要新版本上传审核签名，不能修改历史包。