# .mengplugin 包格式规范 v1.0

## 包结构

`.mengplugin` 文件本质是一个 ZIP 压缩包，包含以下目录结构：

```
plugin.mengplugin (zip)
├── manifest.json          # 必须 — 插件元数据
├── plugin.bin             # 必须 — 编译后的二进制（或 frontend/ 目录）
├── migrations/            # 可选 — 数据库迁移脚本
│   ├── 000001_init.up.sql
│   └── 000001_init.down.sql
├── frontend/              # 可选 — 前端资源（Type=frontend/theme 时必须）
│   ├── index.js
│   └── style.css
├── config.yaml            # 可选 — 插件默认配置
├── icon.png               # 可选 — 插件图标（256x256 PNG）
├── README.md              # 可选 — 插件说明
└── signature.sig          # 可选 — 数字签名（P1 完整实现）
```

## manifest.json 字段说明

| 字段 | 类型 | 必须 | 说明 |
|------|------|------|------|
| id | string | ✅ | 唯一标识符（如 `com.example.cms`） |
| name | string | ✅ | 显示名称 |
| version | string | ✅ | SemVer 版本号 |
| description | string | ✅ | 一句话描述 |
| author.name | string | ✅ | 作者名称 |
| author.email | string | - | 作者邮箱 |
| author.url | string | - | 作者主页 |
| type | string | ✅ | 插件类型：backend/frontend/theme/hook/mcp_tool |
| min_host_version | string | ✅ | 最低兼容宿主版本 |
| max_host_version | string | - | 最高兼容版本（空=无上限） |
| permissions | object | ✅ | 权限声明（见下文） |
| dependencies | array | - | 依赖的其他插件 |
| entry.binary | string | ✅ | 可执行文件名 |
| entry.config | string | - | 配置文件名 |
| entry.migrate | string | - | 迁移目录名 |
| icon | string | - | 图标文件名 |
| homepage | string | - | 插件主页 URL |
| license | string | - | 许可证（如 MIT） |

## 权限声明（permissions）

```json
{
  "permissions": {
    "database": ["articles", "categories", "media"],
    "storage": true,
    "network": ["api.external.com"],
    "events": ["article.published", "article.deleted"],
    "routes": ["/api/v1/articles", "/api/v1/media"],
    "admin_panel": true
  }
}
```

| 权限 | 类型 | 说明 |
|------|------|------|
| database | string[] | 允许访问的数据库表 |
| storage | bool | 是否需要文件存储 |
| network | string[] | 允许访问的外部域名（空=禁止外网） |
| events | string[] | 允许订阅/发布的事件名 |
| routes | string[] | 允许注册的 HTTP 路由前缀 |
| admin_panel | bool | 是否需要后台管理面板 |

**未声明的权限，运行时直接拒绝。**

## 插件类型

| 类型 | 说明 | 必须包含 |
|------|------|----------|
| backend | 后端业务插件 | plugin.bin + manifest.json |
| frontend | 前端注入插件 | frontend/ + manifest.json |
| theme | 主题插件 | frontend/ + manifest.json |
| hook | 事件钩子插件 | plugin.bin + manifest.json |
| mcp_tool | MCP 工具集成 | plugin.bin + manifest.json |

## 打包命令（规划中）

```bash
smrm plugin pack ./my-plugin    # 打包为 .mengplugin
smrm plugin verify ./my.mengplugin  # 验证包完整性
smrm plugin manifest ./my-plugin    # 生成 manifest.json 模板
```

## 安全约束

1. manifest.json 必须存在且格式合法
2. plugin.bin 不得引用宿主内部路径
3. 网络访问必须在 permissions.network 白名单内
4. 数据库访问必须在 permissions.database 白名单内
5. 签名校验（P1 实现）：Ed25519 非对称签名