> ## 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。写 Mini App 不需要读完这页，遇到边界情况时再来查。

## 定义和运行分开

* 启用并校验通过的包进入 Mini App 目录，可以被发现，但不会因此启动。
* 只有显式激活（`@` 选中、`open`、`publish`、`restart`）才启动对应的服务，并且只影响这一个 Mini App。
* 同包的 App、Skill 和普通 MCP 按普通插件的规则自动发布，不等 Mini App 启动。

## 启动

**1. 复制运行副本**

宿主把已安装的包复制到自己管理的运行目录，重新核对身份、内容摘要和入口位置，通过才运行。进程不读工作区，也不读安装目录，所以 Agent 正在修改的文件不会影响当前实例，要等下一次发布。

**2. 分配端口**

端口在 49152–65535 之间。宿主按插件 ID 的哈希选起点，冲突就换一个；选定后记下来，下次启动优先复用。

**3. 装好请求守卫**

子进程先运行宿主的启动代码，通过 IPC 接收初始化消息并逐项校验，再给进程里的 HTTP 服务装上请求守卫，最后才加载插件代码，见[端口与凭据](/docs/miniapp/host/security#guard)。

**4. 等待就绪**

插件的 `start(context)` 返回后，宿主做两次探测：不带凭据必须被拒绝（`401`），带上凭据必须成功（`204`）。启动时限内（目前 10 秒）没通过，就判定启动失败。

## 就绪判定

入口的 `start(context)` 已经完成、子进程回报了和本次运行匹配的 started 消息、宿主对分配端口的鉴权探测通过（不带凭据返回 `401`，带凭据返回 `204`），三者都满足才算就绪。

这能识别绕过守卫、端口被其他进程占用之类的异常，但不能证明插件本身是安全的。端口冲突时会在有限范围内换端口重试；其他启动错误直接失败，并清理进程、端口和运行目录。

## 更新运行中的 Mini App

直接停掉旧进程、启动新进程，很容易打断正在进行的工作：Agent 可能在等 MCP 工具返回，Mini App 也可能正在调用 Connector。而同一个 Mini App 同时只能有一个进程，所以宿主把"停止旧进程"当作分界线：

![更新运行中的 Mini App](https://mintcdn.com/agent-cn/cVBevhAJXWhxEBzo/images/miniapp/update-zh.svg?fit=max\&auto=format\&n=cVBevhAJXWhxEBzo\&q=85\&s=14581ec45211cc0dd47c6286f7f5e7b4)

* **停止之前，随时可以放弃。**宿主先校验新包，再让旧进程停止接收新的 Connector 调用，并在期限内等已经发出的调用结束。任何一步不成，就放弃这次更新，旧进程继续服务，操作返回失败（例如 `BUSY`），稍后再试。
* **停止之后，不再回头。**宿主停止旧进程并确认它已经退出，复制新的运行副本、启动新进程，通过完整的就绪检查后才让它接管，托管 MCP 重新连接，提交新的能力快照。
* **新进程起不来时，**Mini App 进入失败状态，宿主不会自动复活旧进程；同包的 App、Skill 和普通 MCP 保持可用，等下一次 `open`、`publish` 或 `restart`。

发布、重启和停止都走插件系统的同一条操作队列。能力快照只在没有进行中的对话回合时切换，进行中的回合继续使用它开始时的快照。

## 哪些改动会替换进程

发布时宿主分别计算三个内容摘要：整个包、页面载荷和 Node 载荷。只改插件里的 Skill 或普通 MCP 声明，不会替换运行中的进程；页面或 Node 载荷变了，才走上面的更新流程。`agentAccess` 等授权跟着进程生效，声明变了也会重启进程。

## 停止与退出

* 停止时，宿主先断开 Host Connector，再通知插件 `dispose`。
* 进程退出需要确认：先给 2 秒宽限，再发 `SIGTERM`，仍未退出就强制结束，并等待实际退出。
* 如果仍然确认不了退出，宿主把这个插件标为不可用，不再向它的端口调度请求，也不提前释放运行名额。

## 容量与共享

* 同一个 Mini App 任何时候只有一个 Node 进程。替换时必须先确认旧进程退出，再启动新进程。
* 同时最多 3 个不同的 Mini App 服务。准备中的服务也占名额，确认退出后才释放。
* 不同 Mini App 的冷启动各自进行，互不等待。
* `@` 选中一个 Mini App 而名额已满时，不启动、不打开页面，只提示"插件服务超出上限"，引用保留。

## 停止、关闭与账号切换

* `stop` 停止进程，保留已安装的包、启用状态以及同包的 App、Skill 和普通 MCP。之后的普通发布不会隐式启动它。
* 退出登录或切换账号时，旧账号下运行的官方 Mini App 会先退役，新账号才能激活。同一个登录刷新凭据时，运行中的 Mini App 不受影响。