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

# 用 Agent 构建 Mini App

> 在 MiniMax Code 桌面端用 /miniapp-creator，从一句需求走到可用的页面。

你不需要从零写起。对 Agent 说一句"帮我做一个 XX 看板"，它会初始化包、写页面和后端、发布、打开，并自己截图验收。你看结果，再让它改。

## 一句话开始

```text theme={null}
/miniapp-creator 帮我做一个 Notion 任务看板：按状态分栏，可以在页面里改状态，改完同步回 Notion
```

不输入命令也可以。直接说"帮我做一个番茄钟""把我在 Jira 里的需求做成能增删改的列表"，Agent 同样会走这个流程。只有"做一个 Notion board"这种可能是指 Notion 自带看板视图的说法，它才会先问你要哪一种。

## Agent 会做什么

**1. 理解需求**

先看你已有的连接和工具，提出两三个具体方向，只问会明显改变产品的问题。名称、图标、布局这类可以随时改的细节直接用默认值。

**2. 验证数据通路**

对每个数据源做一次只读查询，确认授权、字段和真实返回。验证不过就停下来说明原因，不会用样例数据拼一个空壳。

**3. 初始化包**

调用 `miniapp` 工具的 `init`，在工作区的 `miniapps/<pluginId>/` 下生成脚手架。这是这次唯一可编辑的包。

**4. 写页面和后端**

页面写在 `miniapp/client/`，Node 入口写在 `miniapp/node/`；按需声明托管 MCP、Connector 和 Agent 权限。

**5. 发布并打开**

依次调用 `publish`、`inspect`、`open`，页面出现在当前会话的侧栏里。

**6. 截图验收**

用内置浏览器检查页面结构、文字和交互，汇报哪些通过、哪些没能验证。

## miniapp 工具

Agent 通过宿主提供的 `miniapp` 工具管理 Mini App 的生命周期。你一般不用直接调用它，但知道这些动作，就能看懂 Agent 在做什么。

| 动作 | 作用 |
| - | - |
| `init` | 在当前工作区创建或认领 `miniapps/<pluginId>/`，返回唯一可编辑的包路径。`mode: "update"` 表示找到了已有的包 |
| `publish` | 校验并发布包，启动或替换运行中的服务。`sourcePath` 用于发布现成的成品目录 |
| `inspect` | 读取已安装 Mini App 的来源（`official` / `local`）、运行状态和最近一次运行的诊断，不会启动服务 |
| `open` | 在当前会话打开页面；`path` 打开插件内的指定地址 |
| `restart` | 用已安装的版本重新启动服务，不读工作区 |
| `stop` | 停止服务，保留插件以及同包的 Skill、MCP |
| `list` | 列出已安装的 Mini App 和运行状态 |

```json theme={null}
{ "action": "open", "pluginId": "sales-board", "path": "/items/42?tab=details" }
```

## 继续修改

直接告诉 Agent 要改什么，它会在同一个包里修改，再重新发布。改动只发生在 `init` 返回的那个目录里，它不会去读别的草稿、已安装的插件或宿主源码。

> [!WARNING]
>
> 从插件市场安装的官方 Mini App 不能在本地修改或重新发布。想定制时，让 Agent 用新的 `pluginId` 另做一份。

## 已有现成的包

拿到别人做好的 Mini App 目录或 ZIP，直接交给 Agent："帮我安装这个 Mini App"。Agent 会先检查包内容，不执行包里的说明、不装依赖、不构建，再用 `publish` 的 `sourcePath` 发布。ZIP 会先解压到一个新目录。

```json theme={null}
{
  "action": "publish",
  "pluginId": "sales-board",
  "sourcePath": "./received/extracted/sales-board"
}
```

这个路径只用于这一次发布，之后的更新和重启不会再读它。