Skip to main content

​
定义和运行分开

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

​
启动

1

复制运行副本

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

分配端口

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

装好请求守卫

子进程先运行宿主的启动代码，通过 IPC 接收初始化消息并逐项校验，再为进程中的 HTTP 服务安装请求守卫，最后才加载插件代码，见端口与凭据。
4

等待就绪

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

​
就绪判定

入口的 start(context) 已经完成、子进程回报了和本次运行匹配的 started 消息、宿主对分配端口的鉴权探测通过（不带凭据返回 401，带凭据返回 204），三者都满足才算就绪。这能识别绕过守卫、端口被其他进程占用之类的异常，但不能证明插件本身是安全的。端口冲突时会在有限范围内换端口重试；其他启动错误直接失败，并清理进程、端口和运行目录。

​
市场更新

插件市场的新版本仍提供兼容当前宿主的 Mini App 定义、且更新需要重启进程时，宿主会为运行中或启动中的 Mini App 保留当前整包版本，包括页面、Node 服务、托管 MCP 和 Skill；工具栏和插件详情提供「更新」入口，确认后执行下方的切换流程。服务停止或退出后，也会采用可用的新版定义，但不会因此自动启动服务。如果新版删除了 Mini App 定义，或宿主因其 engines.mcode 要求而屏蔽该定义，则不适用上述保留规则。旧服务会被退役，更新无需等待用户确认。只改 Skill、普通 MCP 或展示信息且无需重启的更新可以直接采用；本地目录和工作区的 publish 沿用原有发布流程。确认更新后，发起更新的会话重新打开页面，其他会话需要刷新或重新打开。

​
更新运行中的 Mini App

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

以停止旧进程为界：之前可以放弃，之后不再回头。

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

​
哪些改动会替换进程

发布时宿主分别计算三个内容摘要：整个包、页面载荷和 Node 载荷。只改插件里的 Skill 或普通 MCP 声明，不会替换运行中的进程；页面或 Node 载荷变了，才走上面的更新流程。agentAccess 等 manifest 授权声明跟着进程生效，声明变了也会重启进程。这与用户在权限面板里关闭权限不同：开关直接限制后续调用，不需要改包或重启进程。

​
停止与退出

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

​
容量与共享

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

​
停止、关闭与账号切换

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