## 一个清单负责哪些事情

`manifest.json` 描述组件身份、类别、入口、资源顺序和宿主要求。它不是业务实现，也不会因为写了某个权限名称就自动创建接口。

下面以完整效率插件示例为准：


```json
{
  "id": "my-example-tool",
  "name": "文本整理示例",
  "version": "1.0.0",
  "apiVersion": 1,
  "minAppVersion": "2.7.5",
  "author": "Your Name",
  "description": "一个包含完整打开与清理流程的示例工具",
  "category": "tool",
  "type": "thirdparty",
  "main": "main.js",
  "scripts": [
    "modules/text.js",
    "modules/view.js"
  ],
  "styles": [
    "styles.css"
  ],
  "permissions": [],
  "slot": "workshop",
  "button": {
    "label": "文本整理",
    "order": 100
  }
}
```


## 必填字段与稳定身份

| 字段 | 含义 | 开发要求 |
| --- | --- | --- |
| `id` | 稳定的唯一组件 ID | 小写字母或数字开头；后续允许字母、数字、点、下划线、连字符；最长 64 字符 |
| `name` | 用户看到的名称 | 简短清楚，不用名称承担版本识别 |
| `version` | 当前组件版本 | 使用有效的三段语义版本，如 `1.0.1`；发行新内容时递增 |
| `main` | 最终注册入口 | 包内相对路径，文件必须存在 |
| `type` | 来源类型 | 第三方组件声明 `thirdparty`；最终还会受扫描来源约束 |
| `slot` | 宿主入口约定 | 示例工具使用 `workshop`，任务使用 `standalone`；以目标版本支持为准 |
| `category` | 扩展类别 | 工具为 `tool`，任务为 `task`；请显式声明 |
| `apiVersion` | 扩展接口版本 | 当前使用 `1` |

组件 ID 是更新身份。改 UI、改模板、补功能时继续使用原 ID；不要为了绕开同版本发布冲突新建一串 ID，否则用户得到的是另一个组件。

## 宿主版本与组件版本分开

`version` 是组件自己的发行版本；`minAppVersion` 和可选的 `maxAppVersion` 限定宿主范围。需要一个新 preload 方法时，不能只提升组件版本，还应提升最低宿主要求，并在旧版本确认不兼容提示。

源码中的注释编号不代表宿主版本。当前项目的真实宿主版本以 `package.json` 为准，示例最低要求也应结合目标版本核对。

## scripts、main 和 styles

```text
scripts[0]：底层逻辑
scripts[1]：状态或操作
scripts[2]：依赖前面模块的视图
main：最后注册组件
```

运行时读取资源后按声明顺序执行脚本。`main` 不需要重复列入 `scripts`。所有路径都在组件根目录以内，不能使用绝对磁盘路径或 `../` 跳出组件。

样式放进 `styles` 数组，并以组件自己的根类名限定作用范围。图片和字体放进包内资源目录，正式加密资源的寻址按目标宿主约定处理，不能假设始终存在普通磁盘文件。

## permissions 与 backend

| 声明 | 用途说明 |
| --- | --- |
| `fs` | 文件能力需求声明；不等于任意文件读写授权 |
| `ai` | 模型相关能力需求声明；不等于存在 `api.chat()` |
| `codemirror` | 编辑器相关需求 |
| `workspace`、`state` | 工作区、状态相关需求 |
| `ipc` | 对实际桥接能力的需求声明 |

> [!WARNING]
> 当前普通源码扫描只允许受支持的内置任务使用 `backend`。第三方插件不能填写任意后端文件来取得主进程执行权限。正式发行还有独立的格式、身份和授权校验。

## 类别必须贯穿发行流程

任务的 `category: task` 对应当前分类发行格式 `.mrite-task`；效率工具的 `category: tool` 对应 `.mrite-component`。旧 `.mrite-plugin` 可能仍由兼容流程处理，但不能通过改后缀改变类别。

安装会验证包内容及签名中的类别，文件扩展名不是唯一依据。不要拿任务清单配工具发行格式。

## 清单提交前检查

- JSON 无注释、无尾逗号，所有引用文件存在。
- ID 在清单、注册入口与后续发行记录中一致。
- 脚本依赖顺序正确，没有读取其他组件的私有资源。
- 不使用已有内置 ID，不靠来源类型扩权。
- 宿主最低版本覆盖实际用到的接口。
- 在真实开发版扫描、启用、打开并重新打开过一次。