# Mini App SDK

Mini App 是 Cowork 在自己的分頁裡開啟的網頁。Cowork 會在頁面裡加入一個全域物件 `window.MAESTROSDK`，頁面透過它和 Cowork 溝通。本章列出這個物件裡 Cowork 支援的模組及其中的每個函式，格式與方法參考相同。

> **發布狀態**
> 標有 <Badge type="warning" text="尚未發布" /> 的函式已在 Cowork 的原始碼裡，但還沒有進入已發布的版本。呼叫前先檢查函式是否存在（見 [檢查可用的功能](#檢查可用的功能)）。

## 模組

| 模組 | 函式 | 用途 |
|---|---|---|
| [生命週期](https://docs.micromeet.ai/zh-tw/miniapp-sdk/lifecycle.md) | `beforeRefresh(handler)` | 有人重新整理分頁時保住尚未儲存的工作 |
| [互動](https://docs.micromeet.ai/zh-tw/miniapp-sdk/interaction.md) | `confirm(request)` | 用原生對話框問使用者一個是 / 否的問題 |
| [模型](https://docs.micromeet.ai/zh-tw/miniapp-sdk/llm.md) | `llm.providers()` · `llm.complete(request)` | 使用 Cowork 已設定好的某個 AI 模型 |
| [套件](https://docs.micromeet.ai/zh-tw/miniapp-sdk/package.md) | `package.get()` | 讀取這個 Mini App 所屬的套件，以及它帶有哪些 Extension |
| [登入](https://docs.micromeet.ai/zh-tw/miniapp-sdk/auth.md) | `auth.login(params?)` · `auth.status()` | 用這個人的 Micromeet 帳號登入（僅限已簽章的封裝） |

要做一個用 Micromeet 帳號登入的 Mini App，請從[開發登入 Mini App](https://docs.micromeet.ai/zh-tw/miniapp-sdk/sign-in-guide.md)開始。打包 Mini App 並交給 Micromeet 簽章，請見[打包與簽章](https://docs.micromeet.ai/zh-tw/miniapp-sdk/build.md)；封裝必須符合的全部規則請見[封裝規範](https://docs.micromeet.ai/zh-tw/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；你無法安裝自己的 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-tw/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：其中一個資料夾，放著它唯一的 Extension。套件裡的 Mini App 不填 |

- 頁面以相對路徑載入，並使用 hash 路由（`#/page`）。
- 每個 Mini App 有自己的儲存空間（cookies、`localStorage`），與網頁分頁和其他 Mini App 分開。解除安裝時會清除。
- 以套件的一部分安裝，與它的 Extension 和技能一起：見 [擴充能力總覽](https://docs.micromeet.ai/zh-tw/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-tw/extension-sdk/overview.md): 同一個套件裡的 Extension 可以呼叫什麼
- [Mini App](https://docs.micromeet.ai/zh-tw/extend/mini-apps.md): Cowork 內建的 Mini App
- [擴充能力總覽](https://docs.micromeet.ai/zh-tw/extend/overview.md): 該做哪一種擴充