> ## 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 Code 中，理解 Mini App 和会话（Session）的关系如下：

* **后端服务全局唯一：**每个 Mini App 只启动一个 Node 进程。不管你在哪个会话里调用，连的都是同一个后端、读写的都是同一份数据。
* **前端页面按会话隔离：**每个会话拥有自己独立的 Mini App 标签页（Tab）；但在同一个会话内，同一个 Mini App 只会打开一个标签页。
* **自建会话归 Mini App 私有：**Mini App 通过 Agent API 自己发起的会话，不会出现在左侧的聊天列表里，仅供该 Mini App 内部维护和续用。

![Mini App 与会话的关系](https://mintcdn.com/agent-cn/cVBevhAJXWhxEBzo/images/miniapp/sessions-zh.svg?fit=max\&auto=format\&n=cVBevhAJXWhxEBzo\&q=85\&s=9ce46b9eba621724d28a3011750ce497)

## 在会话里打开 Mini App

有三种方式：从右侧面板的「+」里选择，在输入框里 `@` 一个已安装的 Mini App，或者让 Agent 调用 `open`。页面总是打开在发起操作的那个会话里。

| 场景 | 会发生什么 |
| - | - |
| 已有会话的输入框里出现 Mini App 引用 | 立即启动或复用后台服务，页面打开成功后才展开侧栏；启动失败不会弹出空面板。`@` 选中、在插件市场点「使用」、恢复带引用的草稿都算 |
| 首页的新对话 | 只启动后台服务。第一次发送创建会话后，再为仍留在消息里、并且启动成功的 Mini App 打开页面 |
| 同一会话里再次打开或再次 `@` | 复用原来的标签，保留当前页面的路由和状态，不会跳回首页；只有显式指定 `path` 才会导航 |
| 纯文本 `@xxx`、历史消息 | 不会启动服务，也不会打开页面 |
| 云端、SSH、Remote Control 会话 | 不会启动或打开本机的 Mini App |

* 打开操作一旦发起，删除引用、取消消息或切换到别的会话都不会撤回。页面留在发起它的会话里，由你手动关闭。
* 左侧会话列表会标出当前打开了 Mini App 的会话，方便回到对应的工作台。

## 多个会话共用一个服务

* 会话 A 和会话 B 打开同一个 Mini App 时，两个页面连的是同一个 Node 服务，读写同一份 `dataDir`。
* 在会话 A 里改了数据，会话 B 的页面要刷新或订阅推送才能看到。作者应该让所有写入都经过 Node 业务服务，先落盘再通过 SSE 或 WebSocket 推送，见[状态与持久化](/docs/miniapp/authors/data#state)。
* 删除输入框里的 `@` 引用，不会停止共享服务。
* 关闭一个运行中 Mini App 的标签并在确认框里确认，会停止它的共享服务，并关闭所有会话里这个插件的页面。
* 同时最多运行 3 个不同的 Mini App 服务，已在运行的 Mini App 被再次引用不占新名额。`@` 一个需要新名额的 Mini App 而名额已满时，不会启动、也不会打开页面，只提示"插件服务超出上限"，引用保留；腾出名额后重新选择即可。
* 服务重启后，已经打开的标签点刷新或重新打开就能恢复。

## 会话里的 Agent 怎么用 Mini App

* **托管 MCP 工具：**Mini App 服务运行期间，它暴露的工具可以被 Agent 调用。工具跟着服务走，不跟某个会话的页面绑定。
* **发送前就绪：**消息里引用了某个 Mini App 时，宿主在请求模型之前先启动它的服务、连好 MCP、确认工具可用。必需的托管 MCP 不可用时，这次请求直接失败，不会让模型缺着工具继续。
* **不会隐式启动：**宿主不会根据历史消息、引用的消息或模型输出去启动 Mini App。
* **查看页面：**Agent 可以用内置浏览器检查当前会话里打开的 Mini App 页面。用 /miniapp-creator 构建时的截图验收就是这样做的。

## 把内容交给本会话的输入框

* `message.append` 的目标固定为页面所在的会话，不会写进别的会话或首页草稿，也不会新建会话。
* 只能追加到本地、可写的会话。会话被删除、变成只读，或切到云端、远程控制后，调用以 `target_unavailable` 拒绝，不会换一个目标继续写。
* 即使这个会话当前不在前台，也能追加到它的草稿里。
* 每次都要你确认，发送也由你自己按。

## Mini App 自己的 Agent 会话

声明了 `agentAccess` 的 Mini App 可以通过 [Agent API](/docs/miniapp/authors/agent#agent-api) 发起 Agent 会话。这些会话和你的聊天会话是两回事：

| | 页面发起 | Node 发起 |
| - | - | - |
| 关联的聊天 | 打开这个页面的会话 | 无 |
| agent | 该会话使用的 agent | 主 agent，或创建时指定 |
| 工作目录 | 该会话的项目目录；没有项目目录时，用 Mini App 自己的 Agent 目录 | Mini App 自己的 Agent 目录 |
| 模型 | 创建时取该会话的模型和思考强度 | 运行时默认模型 |

* 这些会话不出现在会话列表里。每个 Mini App 只能续用自己创建的会话。
* agent 在创建时确定，之后不变；要换 agent 就新建会话。
* 模型在创建时快照，之后和聊天脱钩：你在主聊天里切换模型，不影响 Mini App 的会话。`run` 和 `answer` 可以显式切换模型。
* 页面用 `create` 建的会话，可以把 `sessionId` 交给 Node，由 Node 用 `run({ sessionId })` 继续。

### 显示到聊天侧栏

页面调用 `open(sessionId)`，会把这个 Agent 会话显示在当前聊天的侧栏里，你可以在那里看过程、批准工具调用、回答问卷。

* 页面可以打开这个 Mini App 拥有的任何会话，包括 Node 创建的会话。
* 同一个会话可以同时显示在多个聊天的侧栏里，全部关闭后才算没人能回答。
* 工具审批只在有人能回答时等待：发起调用时传了 `onEvent`，或者会话正显示在某个聊天侧栏里。会话最初在哪个聊天里创建不算。没人能回答的审批会直接拒绝，并告诉模型不用这个工具继续。
* 宿主窗口刷新或关闭时，侧栏视为已关闭。聊天被删除或运行时重启后，需要页面重新 `open`。

## 弹出窗口与会话

* 弹出的独立窗口仍然属于原会话的那个标签。关闭窗口或按 Cmd/Ctrl+W，页面回到原来的文件面板。
* 独立窗口的显隐不跟随主窗口：主窗口隐藏、最小化或关到托盘，都不影响已经弹出的窗口。
* Mini App 停止、页面关闭或应用退出时，独立窗口随之关闭。

## 登录与账号

* 同一个登录刷新凭据时，运行中的 Mini App、托管 MCP 和工具都保留。
* 退出登录后，Host Connector 的工具清单和授权引用被撤销；同一账号重新登录，Mini App 重新获取工具就能继续调用，不用重新发布。
* 切换到其他账号时，旧账号下运行的官方 Mini App 先退役，新账号才能激活。本地 Mini App 不会被停止，但它在旧账号下的 Connector 访问会被永久撤销，重启服务后才能在新账号下使用 Connector。