插件清单

每个沙盒插件在其 package.json 旁边都有一个 emdash-plugin.jsonc。它是手动编辑的，包含插件的身份标识、信任契约（capabilities、hosts、storage）以及注册表显示的配置字段。emdash-plugin init 会创建一个；CLI 会自动读取 ./emdash-plugin.jsonc 用于 build、dev、validate、bundle 和 publish。

该文件是 JSONC：允许注释和尾随逗号。

以下示例显示了一个图片画廊插件的完整清单：

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "gallery",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "[email protected]" },

	// Optional profile
	"name": "Gallery",
	"description": "Image gallery block for EmDash.",
	"keywords": ["gallery", "images"],
	"repo": "https://github.com/example/plugin-gallery",

	// Trust contract
	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {}
}

身份标识

slug 和 publisher 共同构成包的身份。EmDash 会自动从中派生包的完整标识符。

version 位于 package.json 中

构建会将清单的 version 与 package.json#version 进行协调：

• 两者都设置且相等 → 正常。
• 两者都设置但不同 → 硬错误。
• 只设置一个 → 该值生效。
• 两者都未设置 → 硬错误。

npm 分发插件的推荐模式是从清单中省略 version，让 package.json 成为唯一的真实来源（你的发布工具已经在那里提升了版本）。没有 package.json 的纯注册表插件必须在清单中设置 version — 没有其他地方可以放置它。

配置文件

这些为注册表列表提供信息。license、作者（author 或 authors）和安全联系人（security 或 securityContacts）是必需的；其余是可选的。

除非你真的有多个作者，否则使用单数形式 author / security — 这是常见情况，脚手架会生成它。

信任契约

信任契约包括 capabilities、allowedHosts 和 storage。这三者默认都为空，因此不需要额外权限的插件可以完全省略它们。

{
	"capabilities": ["network:request", "content:read"],
	"allowedHosts": ["api.example.com", "*.cdn.example.com"],
	"storage": {
		"events": { "indexes": ["timestamp"] },
		"submissions": { "indexes": ["email"], "uniqueIndexes": ["token"] }
	}
}

Capabilities

已识别的名称：

CLI 强制执行的两条跨字段规则（编辑器的 JSON-Schema 检查不执行 — 运行 emdash-plugin validate）：

• network:request 需要非空的 allowedHosts。如果插件确实必须访问任何主机，请改用 network:request:unrestricted。
• network:request:unrestricted 需要 allowedHosts 为空 — 不受限制的 capability 已经授予所有主机，因此列表会与之矛盾。

主机模式是纯主机名（无方案、路径或空格）。前导 *. 允许子域：*.cdn.example.com。

Storage

集合名称 → 索引配置的映射。集合名称遵循相同的 /^[a-z][a-z0-9_]*$/ 规则（运行时使用名称作为 SQL 表后缀）。索引是字段名称或复合数组；uniqueIndexes 也可查询 — 不要在 indexes 中也列出它们。

"storage": {
	"events": { "indexes": ["timestamp", ["collection", "timestamp"]] }
}

管理界面

可选。沙盒插件通过 Block Kit 渲染管理页面和仪表板小部件；清单仅声明它们出现的位置。如果插件没有管理 UI，请完全省略 admin 键。

"admin": {
	"pages": [{ "path": "/gallery", "label": "Gallery", "icon": "image" }],
	"widgets": [{ "id": "recent-uploads", "title": "Recent uploads", "size": "half" }]
}

声明 admin.pages 或 admin.widgets 的插件还必须在 src/plugin.ts 中提供渲染 Block Kit 内容的 admin 路由 — schema 无法强制执行这一点（路由名称是从源代码而非清单中探测的），但运行时会检查它。

发布者固定

publisher 固定发布身份，这样你就不会意外地在错误的账户下发布插件。

在你的首次成功发布时，如果清单的 publisher 与活动会话匹配，它会保持原样。如果你使用 emdash-plugin init 创建脚手架并将其留空，CLI 会将活动会话的 DID 写回清单。

以下示例显示了 CLI 写入的行，为了可读性添加了已解析的句柄作为注释：

"publisher": "did:plc:abc123def456", // jane.example.com

在每次后续发布时，CLI 会将活动会话和固定的 publisher 解析为 DID 并进行比较。不匹配会立即以 MANIFEST_PUBLISHER_MISMATCH 失败 — 没有覆盖标志。有意解决它：

• 会话错误：emdash-plugin switch <did>，然后再次发布。
• 真正将插件转移到新发布者：编辑清单中的 publisher。

不发布的情况下验证

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # 特定目录

使用 tsc 风格的 file:line:column 诊断进行离线 schema 检查，包括跨字段规则。适用于预提交钩子或 CI 步骤。重复键和未知键是错误（严格模式捕获 "licens" 拼写错误）。

CLI 标志仍然优先

显式标志（--license、--author-name、…）在两者都设置时会覆盖清单值 — 对 CI 覆盖有用。--no-manifest 完全跳过清单（如果在默认路径存在清单则发出警告，这样发布者固定安全故事保持可见）。

下一步

• emdash-plugin CLI
• 打包和发布
• Capabilities 和安全性