架构概览

范围

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

Mini App 只规定运行环境和宿主接口。页面用什么技术栈、业务数据怎么存，由插件决定；宿主也不替插件做操作系统级隔离，见安全模型。

核心概念

参与方

宿主：MiniMax Code 桌面端。它校验并发布插件包，启动 Node 进程、分配端口、签发凭据，在会话侧栏显示页面，并按清单声明开放 Agent 和 Connector 能力。
Mini App 页面：运行在宿主内置浏览器里的网页，显示在会话侧栏的标签里，也可以弹出成独立窗口。页面只和自己的 Node 服务通信。
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`	宿主按进程身份和清单里的授权判断
页面 → 宿主	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

开发

参考

范围

核心概念

参与方

分层

通信方式

生命周期

示例：一次完整的调用

​范围

​核心概念

​参与方

​分层

​通信方式

​生命周期

​示例：一次完整的调用

范围

核心概念

参与方

分层

通信方式

生命周期

示例：一次完整的调用