> ## 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.

# 包结构与清单

> Mini App 是一个普通的 MiniMax Plugin，多了一份 miniapp.json 声明和页面、Node 两份运行载荷。

## 目录结构

```text theme={null}
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 不会重新解释或清空这些字段。

```json .minimax-plugin/plugin.json theme={null}
{
  "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

```json package.json theme={null}
{
  "mcode": {
    "schemaVersion": 2,
    "miniApp": "./miniapp/miniapp.json"
  }
}
```

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

## Mini App 声明 miniapp.json

```json miniapp/miniapp.json theme={null}
{
  "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 字段](/docs/miniapp/reference/manifest)。几个要点：

* `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` 外，载荷里的每个文件都会进入摘要。日志、缓存、临时文件这类不想发布的东西，发布前删掉。