> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# miniapp.json 字段

> Mini App 声明的全部字段。未知字段一律拒绝。

## 顶层字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `schemaVersion` | `1` | 固定为 1 |
| `artifacts.client` | `string[]` | 必填。页面载荷根目录，非空、不重复，位于 `miniapp/` 下 |
| `artifacts.node` | `string[]` | 必填。Node 载荷根目录，可以和 `client` 重叠 |
| `runtime.kind` | `"process"` | 固定为 `process` |
| `runtime.entry` | `string` | Node 入口，`.js` / `.mjs` / `.cjs`，必须在 Node 载荷内 |
| `runtime.lifecycle` | `"on-demand"` | 可省略。只支持按需启动；旧的 `background` 按 `on-demand` 处理 |
| `surface.path` | `string` | 页面入口路由，以 `/` 开头，不带 origin、query、fragment 和反斜杠 |
| `surface.window` | `object` | 可选。弹出成独立窗口时的属性，见[下表](https://agent.minimaxi.com/docs/miniapp/reference/manifest.md#window) |
| `mcpEndpoints` | `{ server, path }[]` | 托管 MCP。`server` 必须是 `plugin.json` 已声明的 MCP 服务器；没有就写空数组 |
| `hostConnectorAccess.providers` | `string[]` | 允许使用的 Connector provider，小写字母、数字、`_`、`-`，不重复 |
| `agentAccess` | `string[]` | 可选。`session.run` 允许运行 Mini App 自己的 Agent 会话；`session.read` 允许列出、读取和观察用户会话。两项独立，缺失或为空即禁止 |
| `agentConcurrency` | `integer` | 可选，1–32，默认 4。同时运行的 Agent 回合数；没有 `session.run` 时不生效 |
| `toolAccess` | `["call"]` | 可选。向 Node 服务提供 `context.tool`，调用宿主已挂载的 MCP 工具和 Connector；每次调用仍按用户的工具权限规则判定 |
| `deviceAccess` | `string[]` | 可选。页面可申请的设备权限，见[设备权限](https://agent.minimaxi.com/docs/miniapp/reference/manifest.md#devices) |
| `engines.mcode` | `string` | 可选。所需的最低 MiniMax Code 版本，仅接受 `>=MAJOR.MINOR.PATCH`，见[版本要求](https://agent.minimaxi.com/docs/miniapp/reference/manifest.md#compat) |

## 能力声明与开关

只声明实际需要的能力。下面只展示 `miniapp/miniapp.json` 的部分声明：

```json theme={null}
{
  "agentAccess": ["session.run", "session.read"],
  "toolAccess": ["call"],
  "deviceAccess": ["microphone"]
}
```

用户可以在插件详情的权限面板逐项关闭 Connector provider、Agent 会话、读取会话、工具调用，以及麦克风、摄像头和系统通知权限。声明限定可申请的能力，开关决定调用是否获准；关闭权限无需重启 Mini App，代码仍需处理调用被拒绝的情况。具体限制见[安全模型](https://agent.minimaxi.com/docs/miniapp/host/security.md#permissions)。

## 设备权限

v3.1.6 支持 `microphone`；`camera` 和 `notifications` 从 v3.1.9 起正式提供。

| `deviceAccess` 项 | 允许的页面操作 |
| - | - |
| `microphone` | `getUserMedia({ audio: true })` 录音，以及宿主的 `speech.transcribe` 转写 |
| `camera` | `getUserMedia({ video: true })` 获取摄像头画面 |
| `notifications` | `new Notification(...)` 发送系统通知 |

声明后还需开启对应的权限开关；同时请求音视频需要声明并开启 `microphone` 和 `camera` 两项。定位、剪贴板读取、屏幕捕获等未开放的页面系统权限仍被拒绝。用法见[页面设备 API](https://agent.minimaxi.com/docs/miniapp/authors/client-api.md#devices)。

使用摄像头或系统通知时，在 `miniapp/miniapp.json` 中声明最低宿主版本：

```json theme={null}
{
  "engines": { "mcode": ">=3.1.9" },
  "deviceAccess": ["camera", "notifications"]
}
```

旧宿主可能拒绝这些设备项，不能靠 `capabilities.has()` 绕过清单校验。摄像头和通知没有独立的 capability 名称；接口探测也不能代替权限声明和用户开关。版本下限的处理规则见[版本要求](#compat)。

## 版本要求

`engines` 写在 `miniapp/miniapp.json` 中，与 `agentAccess` 同级，不是写在 `plugin.json` 中：

```json theme={null}
{
  "engines": { "mcode": ">=3.1.5" }
}
```

只支持 `>=` 加三段数字，不支持 `^`、`~` 或多个范围。设置下限前先确认目标版本，避免排除原本仍可使用的宿主。

能识别 `engines` 且低于下限的宿主会拒绝工作区发布；对已安装的包，不加载它的 Mini App 和托管 MCP，同包的 Skill 和普通 MCP 仍可使用。更早的宿主可能不认识 `engines` 或其他新字段，会直接拒绝 manifest，不能依靠版本下限让未知字段自动降级。

页面用 `window.mcode?.miniapp?.capabilities?.has(name)`，Node 用 `context.capabilities?.has(name)` 探测宿主是否实现某项接口，例如 `agent.observe` 或 `tool`。旧宿主可能没有 `capabilities`，需先检测对象是否存在；返回 `true` 也不表示当前插件已声明或获准使用该能力。支持的名称和端侧适用范围见[能力探测参考](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#capabilities)。

## surface.window

这些属性在弹出窗口时应用，仅支持白名单中的 Electron 窗口参数。所有字段都可选。

| 字段 | 默认值 | 说明 |
| - | - | - |
| `width` / `height` | 弹出前在文件面板里的尺寸 | 整数，200–10000 |
| `minWidth` / `minHeight` | 480 / 360 | 同时给出时，不能大于对应的 `width` / `height` |
| `resizable` | `true` | 为 `false` 时，运行时也不能改尺寸 |
| `frame` | `true` | 为 `false` 时要自己提供拖动区域 |
| `transparent` | `false` | 为 `true` 时必须同时声明 `frame: false` |
| `alwaysOnTop` | `false` | 运行时开启置顶的上限 |
| `skipTaskbar` | `false` | 不在任务栏显示 |
| `clickThrough` | `false` | 鼠标事件穿透到下层窗口，页面仍能收到移动事件；也是运行时开启的上限 |

以下属性不能声明：与主窗口的关系（始终是独立的顶层窗口，主窗口隐藏、最小化或关到托盘都不影响它的显隐）、标题（始终为 `displayName`）、屏幕位置，以及打开和关闭行为。页面可通过文件面板的弹出操作，或在用户手势中调用 [`window.update({ mode: 'window' })`](https://agent.minimaxi.com/docs/miniapp/reference/client-api#window-update) 进入独立窗口；关闭窗口后回到文件面板。