包结构与清单

目录结构

sales-board/
├── .minimax-plugin/
│   └── plugin.json          # 插件清单
├── package.json             # 只需要 mcode 扩展
├── icon.png
├── servers.mcp.json         # 可选
├── skills/                  # 可选
└── miniapp/
    ├── miniapp.json         # MiniApp 声明
    ├── client/              # 页面载荷
    │   ├── index.html
    │   └── client-api.ts    # 可选：仅用于类型检查
    └── node/                # Node 载荷
        ├── server.mjs
        └── miniapp-api.ts   # 可选：仅用于类型检查

Agent 用 init 创建的新包采用这个结构。宿主仍兼容早期的 liveboard/ 格式，更新旧包时不必迁移。

插件清单 plugin.json

.minimax-plugin/plugin.json 是插件身份、元数据、图标以及 Skill、MCP、App 的唯一来源。Mini App 不会重新解释或清空这些字段。

.minimax-plugin/plugin.json

{
  "schemaVersion": 1,
  "name": "sales-board",
  "displayName": "销售看板",
  "version": "1.0.0",
  "description": "展示已验证的销售管线数据。",
  "author": "Your Name",
  "icon": "icon.png",
  "category": "Business",
  "exampleQueries": ["打开我的销售管线看板"],
  "apps": [],
  "mcpServers": [],
  "skills": []
}

name 是小写机器名，最长 80 个字符，以字母开头，可以用数字和 . _ - 分隔。它就是 Mini App 的 pluginId。
version 使用 SemVer。description、author 和每条 exampleQueries 都不能为空。
icon 指向包内的 PNG、JPEG 或 WebP。init 会提供默认图标。
apps、mcpServers、skills 保持普通插件的含义；没有的能力写空数组。

声明入口 package.json

package.json

{
  "mcode": {
    "schemaVersion": 2,
    "miniApp": "./miniapp/miniapp.json"
  }
}

根目录的 package.json 只需这一段扩展。宿主不读取或执行 packageManager、lockfile、build 脚本、依赖等工程元数据。

Mini App 声明 miniapp.json

miniapp/miniapp.json

{
  "schemaVersion": 1,
  "artifacts": {
    "client": ["./miniapp/client"],
    "node": ["./miniapp/node"]
  },
  "runtime": {
    "kind": "process",
    "entry": "./miniapp/node/server.mjs",
    "lifecycle": "on-demand"
  },
  "surface": {
    "path": "/dashboard",
    "window": { "width": 960, "height": 700, "resizable": true }
  },
  "mcpEndpoints": [],
  "hostConnectorAccess": { "providers": ["notion"] },
  "agentAccess": ["session.run"],
  "agentConcurrency": 4
}

每个字段的完整说明见 miniapp.json 字段。需要注意：

artifacts.client 和 artifacts.node 都必须有。它们决定宿主计算摘要、接纳和发布的范围，可以是源码目录，不要求是编译产物，两者也可以重叠。
runtime.entry 是 Node 入口，后缀为 .js、.mjs 或 .cjs，必须落在 Node 载荷里。lifecycle 只有 on-demand：启用和扫描插件都不会启动服务。
surface.path 是 Node 服务提供的页面地址。
hostConnectorAccess 和 agentAccess 都是显式授权，不写就没有。仅声明运行时需要的权限。

上面的示例只申请 Connector 和 Agent 运行权限。读取用户会话另需 agentAccess: ["session.read"]，调用宿主工具需 toolAccess: ["call"]，使用麦克风需 deviceAccess: ["microphone"]；按实际需要组合声明，用户可在插件详情逐项关闭这些权限。摄像头和系统通知从 v3.1.9 起正式支持，分别通过 deviceAccess: ["camera"]、deviceAccess: ["notifications"] 声明。使用这两项能力时，将 engines.mcode 设为 >=3.1.9 或更高版本，完整说明见设备权限。使用较新的接口时，在这份 miniapp/miniapp.json 中声明最低宿主版本，例如 "engines": { "mcode": ">=3.1.5" }。版本门禁和 capabilities.has(name) 的兼容边界见版本与能力探测。

载荷规则

宿主不安装依赖、不执行构建。包内应提供能直接运行的文件，第三方运行时依赖需打包或复制到载荷目录。优先使用 Node 内置模块和浏览器 API。
node_modules 是构建状态，不会随包发布，也不能放在声明的载荷里。
使用可移植的相对路径：不能用绝对路径、..、反斜杠或符号链接，也不能指向包外。
除 node_modules 外，载荷里的每个文件都会进入摘要。日志、缓存、临时文件等无需发布的内容，应在发布前删除。

入门

了解 Mini App

开发

参考

目录结构

插件清单 plugin.json

声明入口 package.json

Mini App 声明 miniapp.json

载荷规则

​目录结构

​插件清单 plugin.json

​声明入口 package.json

​Mini App 声明 miniapp.json

​载荷规则

目录结构

插件清单 plugin.json

声明入口 package.json

Mini App 声明 miniapp.json

载荷规则