架构概览

范围

包格式：一个普通的 MiniMax Plugin 包，加上一份 miniapp.json 声明，见包结构与清单。
宿主运行时：MiniMax Code 桌面端里负责发布、启动、鉴权和回收 Mini App 的部分，见运行与更新。
宿主接口：Node 侧的 start(context)、context.agent、context.hostConnector、context.tool，页面侧的 window.mcode.miniapp；capabilities.has(name) 用于探测宿主接口支持。
创建 Skill：/miniapp-creator，指导 Agent 验证数据、编写、发布和验收，见用 Agent 构建。

Mini App 只规定运行环境和宿主接口。页面的技术栈和业务数据的存储方式由插件决定；宿主不为插件提供操作系统级隔离，见安全模型。

核心概念

参与方

宿主：MiniMax Code 桌面端。它校验并发布插件包，启动 Node 进程、分配端口、签发凭据，在会话侧栏显示页面，并按清单声明开放 Agent 和 Connector 能力。
Mini App 页面：运行在宿主内置浏览器里的网页，显示在会话侧栏的标签里，也可以弹出成独立窗口。业务数据通过自己的 Node 服务访问；宿主能力通过注入的页面 API 调用。
Mini App Node 服务：插件的后端。每个插件只有一个进程，监听宿主分配的本机端口，负责业务逻辑、数据和托管 MCP 工具。即使只有一页 HTML，也由它来提供。
Agent：会话里的 Agent 通过宿主的 MCP 客户端调用 Mini App 的工具；Mini App 也可以通过 Agent API 发起自己的 Agent 会话。

Mini App 架构 — 页面、Agent 和宿主服务通过本机端口或 IPC 与 Mini App 的 Node 进程通信，凭据由宿主管理。

举个例子：你在会话里 @ 股市 Mini App，宿主为它启动一个 Node 进程，并在侧栏打开它的页面。之后在另一个会话中打开它时，两个页面仍连接同一个服务、读写同一份数据，宿主不会再启动一个进程，见 Mini App 与会话。

分层

展示层（页面）：HTML、CSS、JavaScript，负责筛选、表格、图表和交互。页面不持有任何凭证。
应用层（Node 服务）：数据聚合、业务规则和持久化。页面接口和 Agent 工具复用同一套业务服务，所以人和 Agent 改的是同一份数据。
能力层：宿主提供的 Agent API、Host Connector、统一工具入口和托管 MCP 接入，以及插件自己访问的命令行、HTTP API 和本地文件。

这三层都由宿主管理：它决定进程何时运行、谁能访问端口、哪些能力可用，业务逻辑则由插件负责。

通信方式

谁 → 谁	通道	身份怎么确认
页面 → Node 服务	本机 HTTP，用相对地址或同源 URL	宿主主进程核对页面的真实来源，再补上本次运行的凭据
会话 Agent → Node 服务	托管 MCP（Streamable HTTP）	宿主的 MCP 客户端把凭据放在请求头里，不写进配置
Node 服务 → 宿主	IPC：`context.agent`、`context.hostConnector`、`context.tool`	宿主按进程身份、清单声明和当前权限判断
页面 → 宿主	preload 注入的 `window.mcode.miniapp`	按 Electron 报告的真实页面核对，不采信页面自报的信息
Node 服务 → 外部	插件自己发起：命令行、HTTP API、文件	由插件自己处理，宿主不额外设关卡

生命周期

Mini App 按需启动：启用插件不会启动它，@ 选中、打开页面、发布或重启时才启动。每个插件同一时刻只有一个进程，同时最多运行 3 个不同的 Mini App 服务。市场更新可先保留运行版本；确认切换时先停旧进程、再起新进程。安装失败可回滚，旧进程停止后的启动失败不会自动恢复旧进程，见运行与更新。

示例：一次完整的调用

以一个「本周风险」看板为例：用户点击页面按钮，Node 服务请 Agent 整理风险。Agent 调用这个 Mini App 自己的工具读取数据，结果再返回页面。

声明能力

看板需要两项宿主能力：供 Agent 使用的托管 MCP 服务器，以及发起 Agent 会话的权限。两者都要在 miniapp.json 里声明：

miniapp/miniapp.json

{
  "runtime": { "kind": "process", "entry": "./miniapp/node/server.mjs" },
  "surface": { "path": "/risks" },
  "mcpEndpoints": [{ "server": "risk-board", "path": "/mcp/risk-board" }],
  "agentAccess": ["session.run"]
}

宿主据此在发布时接入 MCP 端点，并只为这个插件开放 context.agent。没有声明的能力，运行时拿不到。

启动并就绪

Node 入口在宿主分配的端口上启动 HTTP 服务，同时提供页面、业务接口和 /mcp/risk-board。start 返回之后，宿主再做一次鉴权探测，通过后才将服务标为就绪。

miniapp/node/server.mjs（节选）

export async function start(context) {
  const server = createServer((req, res) => route(context, req, res));
  await listen(server, context.listen.host, context.listen.port);
  return { dispose: () => close(server) };
}

页面发起请求

用户点击「整理本周风险」。页面只通过相对地址请求自己的 Node 服务；宿主在请求离开页面时补上凭据，页面代码看不到它。

miniapp/client/app.js

summarizeButton.onclick = async () => {
  const res = await fetch('/api/weekly-risks', { method: 'POST' });
  if (!res.ok) showError(await res.text());
};

Node 服务把任务交给 Agent

请求处理函数调用 context.agent.run。宿主为这个 Mini App 创建一个 Agent 会话：它不出现在会话列表中，只有这个 Mini App 能继续使用。

miniapp/node/server.mjs（节选）

async function handleWeeklyRisks(context, res) {
  const result = await context.agent.run({
    text: '调用 list_risks 读取本周风险，按影响从高到低总结，并列出需要我确认的事项。',
  });
  if (result.status !== 'finished') return sendJson(res, 502, { error: result.status });
  await saveSummary(context.dataDir, result.text);
  broadcast({ type: 'summary.updated' }); // 推给所有打开的页面
  sendJson(res, 200, { sessionId: result.sessionId });
}

这里没有传 onEvent：回合中若有工具调用需要审批、却无人能够处理，宿主会直接拒绝并向模型说明原因，避免任务一直等待，见审批和问卷。

Agent 调用 Mini App 的工具

会话里的 Agent 拥有完整能力，也包括这个 Mini App 自己的 MCP 工具。它调用 list_risks 时，宿主把请求转回同一个 Node 服务，附上本次运行的凭据：

POST /mcp/risk-board

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_risks",
    "arguments": { "week": "2026-W42" }
  }
}

Node 服务从 dataDir 读出风险列表，作为工具结果返回。页面接口和这个工具调用的是同一段业务逻辑。

结果回到页面

回合结束后 run() 返回总结文字。Node 先把结果写进 dataDir，再通过 SSE 通知页面；推送失败时，页面重连后可重新读取。如果用户想看 Agent 的过程，页面可以调用 window.mcode.miniapp.agent.open(sessionId)，把这个会话显示到聊天侧栏。

入门

了解 Mini App

开发

参考

范围

核心概念

参与方

分层

通信方式

生命周期

示例：一次完整的调用

​范围

​核心概念

​参与方

​分层

​通信方式

​生命周期

​示例：一次完整的调用

范围

核心概念

参与方

分层

通信方式

生命周期

示例：一次完整的调用