> ## 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 不会直接在安装目录里运行。发布时，宿主依次完成：

**1. 暂存**

把包复制到宿主管理的暂存区。依赖目录不随包发布。复制后重新读取清单和文件摘要，和复制前不一致就发布失败。

**2. 安装**

旧版本先移入隔离区，暂存副本原子替换进安装目录，再核对一次摘要。

**3. 启动**

从安装目录再复制一份运行副本，验证身份后启动独立进程。旧进程先停止，新进程就绪后才接管。

安装阶段任何一步失败，旧版本从隔离区移回，安装目录恢复原样。如果旧进程已经停了、新进程又没起来，宿主不会自动拉起旧进程，需要再 `open`、`publish` 或 `restart` 一次；同包的 Skill 和普通 MCP 不受影响。详见[更新运行中的 Mini App](/docs/miniapp/host/lifecycle#transaction)。

## 查看运行状态

`inspect` 是只读操作，不会启动或重启服务。主要返回：

* `source`：`official` 或 `local`，由宿主根据安装记录给出。
* `diagnostics.run`：当前或最近一次运行，包括准备、就绪时间和确认过的退出信息。
* `diagnostics.failure`：宿主当前报告的失败。
* `diagnostics.logs`：宿主记录的启动、就绪、失败和退出记录，有数量上限。

诊断只保存在宿主内存里，宿主重启后清空。缺失的时间、退出码和失败原因按"未知"处理，不要猜。

## 调试页面

先 `open` 打开页面，再用内置浏览器的 inspect、query 和点击、输入等操作，检查页面结构、文字、控件和状态。生命周期操作（发布、重启、停止）始终通过 `miniapp` 工具，不要用浏览器操作代替。

## 常见问题

| 现象 | 原因 | 处理 |
| - | - | - |
| `READINESS_TIMEOUT` | `start` 没有返回；或分配的端口不是用 `node:http` 监听的；或自己的路由遮住了 `/__mavis/` | 先监听、装好路由再返回；用 `node:http` 监听分配的端口 |
| `BUSY` · `capacity_busy` | 已经有 3 个 Mini App 服务在运行 | 停掉一个不用的，再重试一次 |
| `BUSY` · `operation_busy` | 同一个 Mini App 有操作正在进行 | 稍等后重试一次 |
| `PLUGIN_ALREADY_EXISTS` | 附带 `OFFICIAL_PLUGIN_READ_ONLY` 时，表示和已安装的官方插件同名 | 官方插件不能本地修改，换一个 `pluginId` |
| `PREPARATION_FAILED` | 发布准备阶段失败 | 按返回的 `diagnostic.recovery` 和 `hint` 处理 |
| `INTERNAL_ERROR` | 宿主内部错误，附带 `diagnosticId` | 不要原样重试；`lastGoodAvailable` 说明旧版本是否还能用 |
| 页面返回 `401` | 服务重启后，已打开的标签还拿着旧凭据 | 点刷新或重新打开 |
| Agent 用不了 Mini App 的工具 | 托管 MCP 处理器出错，或 `mcpEndpoints` 路径和实现不一致 | 修好后重新发布 |

完整列表见[错误码速查](/docs/miniapp/reference/errors)。