miniapp.json 字段

顶层字段

字段	类型	说明
`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`	可选。弹出成独立窗口时的属性，见下表
`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[]`	可选。页面可申请的设备权限，见设备权限
`engines.mcode`	`string`	可选。所需的最低 MiniMax Code 版本，仅接受 `>=MAJOR.MINOR.PATCH`，见版本要求

能力声明与开关

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

{
  "agentAccess": ["session.run", "session.read"],
  "toolAccess": ["call"],
  "deviceAccess": ["microphone"]
}

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

设备权限

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。使用摄像头或系统通知时，在 miniapp/miniapp.json 中声明最低宿主版本：

{
  "engines": { "mcode": ">=3.1.9" },
  "deviceAccess": ["camera", "notifications"]
}

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

版本要求

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

{
  "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 也不表示当前插件已声明或获准使用该能力。支持的名称和端侧适用范围见能力探测参考。

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' }) 进入独立窗口；关闭窗口后回到文件面板。

入门

了解 Mini App

开发

参考

顶层字段

能力声明与开关

设备权限

版本要求

surface.window

​顶层字段

​能力声明与开关

​设备权限

​版本要求

​surface.window

顶层字段

能力声明与开关

设备权限

版本要求

surface.window