包结构与清单

目录结构

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 都是显式授权，不写就没有。只在运行时真的需要时声明。

载荷规则

宿主不安装依赖、不执行构建。包里应当是能直接运行的成品，第三方运行时依赖要打包或拷进载荷目录。优先使用 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

载荷规则