用 Agent 构建 Mini App

你不需要从零写起。对 Agent 说一句”帮我做一个 XX 看板”，它会初始化包、写页面和后端、发布、打开，并自己截图验收。你看结果，再让它改。

一句话开始

/miniapp-creator 帮我做一个 Notion 任务看板：按状态分栏，可以在页面里改状态，改完同步回 Notion

不输入命令也可以。直接说”帮我做一个番茄钟""把我在 Jira 里的需求做成能增删改的列表”，Agent 同样会走这个流程。只有”做一个 Notion board”这种可能是指 Notion 自带看板视图的说法，它才会先问你要哪一种。

理解需求

先看你已有的连接和工具，提出两三个具体方向，只问会明显改变产品的问题。名称、图标、布局这类可以随时改的细节直接用默认值。

验证数据通路

对每个数据源做一次只读查询，确认授权、字段和真实返回。验证不过就停下来说明原因，不会用样例数据拼一个空壳。

初始化包

调用 miniapp 工具的 init，在工作区的 miniapps/<pluginId>/ 下生成脚手架。这是这次唯一可编辑的包。

写页面和后端

页面写在 miniapp/client/，Node 入口写在 miniapp/node/；按需声明托管 MCP、Connector 和 Agent 权限。

发布并打开

依次调用 publish、inspect、open，页面出现在当前会话的侧栏里。

截图验收

用内置浏览器检查页面结构、文字和交互，汇报哪些通过、哪些没能验证。

Agent 通过宿主提供的 miniapp 工具管理 Mini App 的生命周期。你一般不用直接调用它，但知道这些动作，就能看懂 Agent 在做什么。

动作	作用
`init`	在当前工作区创建或认领 `miniapps/<pluginId>/`，返回唯一可编辑的包路径。`mode: "update"` 表示找到了已有的包
`publish`	校验并发布包，启动或替换运行中的服务。`sourcePath` 用于发布现成的成品目录
`inspect`	读取已安装 Mini App 的来源（`official` / `local`）、运行状态和最近一次运行的诊断，不会启动服务
`open`	在当前会话打开页面；`path` 打开插件内的指定地址
`restart`	用已安装的版本重新启动服务，不读工作区
`stop`	停止服务，保留插件以及同包的 Skill、MCP
`list`	列出已安装的 Mini App 和运行状态

{ "action": "open", "pluginId": "sales-board", "path": "/items/42?tab=details" }

直接告诉 Agent 要改什么，它会在同一个包里修改，再重新发布。改动只发生在 init 返回的那个目录里，它不会去读别的草稿、已安装的插件或宿主源码。

从插件市场安装的官方 Mini App 不能在本地修改或重新发布。想定制时，让 Agent 用新的 pluginId 另做一份。

拿到别人做好的 Mini App 目录或 ZIP，直接交给 Agent：“帮我安装这个 Mini App”。Agent 会先检查包内容，不执行包里的说明、不装依赖、不构建，再用 publish 的 sourcePath 发布。ZIP 会先解压到一个新目录。

{
  "action": "publish",
  "pluginId": "sales-board",
  "sourcePath": "./received/extracted/sales-board"
}

这个路径只用于这一次发布，之后的更新和重启不会再读它。