# Mini App SDK

Mini App 是 Cowork 在自己的标签页里打开的网页。Cowork 会在其中加入一个全局对象 `window.MAESTROSDK`，页面通过它与 Cowork 通信。本章按方法参考的格式，列出这个对象中 Cowork 支持的模块，以及其中的每个函数。

> **发布状态**
> 标有 <Badge type="warning" text="尚未发布" /> 的函数已在 Cowork 源码里，但还没有进入已发布的版本。调用前先检查函数是否存在（见[检查可用性](#检查可用性)）。

## 模块

| 模块 | 函数 | 用途 |
|---|---|---|
| [生命周期](https://docs.micromeet.ai/zh/miniapp-sdk/lifecycle.md) | `beforeRefresh(handler)` | 有人刷新标签页时保住未保存的内容 |
| [交互](https://docs.micromeet.ai/zh/miniapp-sdk/interaction.md) | `confirm(request)` | 用原生对话框问用户一个是 / 否问题 |
| [模型](https://docs.micromeet.ai/zh/miniapp-sdk/llm.md) | `llm.providers()` · `llm.complete(request)` | 使用 Cowork 里已设置好的某个 AI 模型 |
| [包](https://docs.micromeet.ai/zh/miniapp-sdk/package.md) | `package.get()` | 读取这个 Mini App 所在的包，以及包里有哪些扩展 |
| [登录](https://docs.micromeet.ai/zh/miniapp-sdk/auth.md) | `auth.login(params?)` · `auth.status()` | 用这个人的 Micromeet 账号登录（只限签名包） |

要做一个用 Micromeet 账号登录的 Mini App，从[开发登录 Mini App](https://docs.micromeet.ai/zh/miniapp-sdk/sign-in-guide.md)开始。打包 Mini App 并交给 Micromeet 签名，见[打包与签名](https://docs.micromeet.ai/zh/miniapp-sdk/build.md)；包必须满足的全部规则见[包规范](https://docs.micromeet.ai/zh/miniapp-sdk/package-spec.md)。

除 `beforeRefresh` 外，每个函数都返回 `Promise`，而且遇到预期内的失败都不会抛出异常：各自返回 `false`、`null`、空列表或 `{ ok: false, error }`，具体见各自的小节。

这个对象还有一个 `connectors` 模块（`root`、`list`、`agentMdPath`、`readAgentMd`、`writeAgentMd`、`onAgentMdChange`）。Cowork 不支持它：其中的函数返回空结果、`{ ok: false, reason: 'unsupported' }`，或抛出 `unsupported`。不要在 Cowork 的 Mini App 里使用它。

## Mini App 文件夹 <Badge type="warning" text="尚未发布" />

在 0.1.41 里只有 Cowork 自带的 Mini App，你还不能安装自己的。从下一个版本起：

```text
miniapp/
  manifest.json    { appId, name, version, entry }
  index.html       the entry page
  app.js  app.css  anything else it loads, by relative path
```

从 Cowork 0.1.46 起文件名是 `manifest.json`；更早的版本读 `miniapp.json`，还有人在用旧版时请同时保留一份这个名字的副本。Mini App 也可以是签名包（`app.asar`）：见[打包与签名](https://docs.micromeet.ai/zh/miniapp-sdk/build.md)。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `appId` | `string` | 是 | 反向域名形式的 id，全小写，比如 `ai.micromeet.janeapp-operator`；最多 128 个字符。标签页为 `miniapp:<appId>` |
| `name` | `string` 或 `{ zh, en }` | 是 | 标签页和菜单里显示的名称；最多 60 个字符 |
| `version` | `string` | 是 | 最多 32 个字符 |
| `entry` | `string` | 否 | 入口页面，文件夹内的相对路径，最多 256 个字符。默认 `index.html` |
| `extension` | `string` | 否 | 仅用于单独安装的 Mini App：其中存放它唯一一个扩展的文件夹。包里的 Mini App 不写这一项 |

- 页面按相对路径加载，使用 hash 路由（`#/page`）。
- 每个 Mini App 有自己独立的存储（cookie、`localStorage`），与网页标签页和其他 Mini App 分开。卸载时会清除。
- 把它作为包的一部分，和它的扩展、技能一起安装：见[扩展能力总览](https://docs.micromeet.ai/zh/extend/overview.md)。

## 检查可用性

```js
const sdk = window.MAESTROSDK;
if (sdk && sdk.package && typeof sdk.package.get === 'function') {
  const info = await sdk.package.get();
}
```

在较旧的 Cowork 上，还没有的模块就是不存在；这时给用户显示一句简短说明，而不是直接出错。

## 相关

- [Extension SDK](https://docs.micromeet.ai/zh/extension-sdk/overview.md): 同一个包里的扩展可以调用什么
- [Mini App](https://docs.micromeet.ai/zh/extend/mini-apps.md): Cowork 自带的 Mini App
- [扩展能力总览](https://docs.micromeet.ai/zh/extend/overview.md): 该做哪种扩展