# 打包與簽章 <Badge type="warning" text="尚未發布" />

要讓人登入的 Mini App（請見[登入](https://docs.micromeet.ai/zh-tw/miniapp-sdk/auth.md)）以**已簽章的封裝**交付：檔案打進一個 `app.asar`，加上一個 `manifest.json`，再加上 Micromeet 對兩者的簽章。Cowork 開啟 Mini App 時驗證簽章，頁面讀取每個檔案時再依簽章逐一比對；檔案被改過就關閉這個 Mini App。沒有簽章或簽章驗證不過的封裝，Cowork 不會開啟，並告訴使用者這個 Mini App 未經認證。

## 封裝的結構

```text
manifest.json         { appId, name, version, version_code, entry, asar, domains, asarHeaderSha256, signature }
app.asar              建置出的頁面、腳本和樣式，每個檔案的 SHA-256 摘要記在它的檔頭裡
app.asar.unpacked/    大型媒體檔（影片、音訊），放在 app.asar 外面；摘要仍在它的檔頭裡
INSTALL.md            選用：給安裝它的 Agent 的步驟
```

| 欄位 | 說明 |
|---|---|
| `appId` | 小寫反向網域，例如 `ai.example.app`；Micromeet 登記這個 Mini App 時給出 |
| `name` | 字串，或 `{ zh, en }`；1–60 個字元 |
| `version` | 字母、數字、`.`、`+`、`-`；最多 32 個 |
| `version_code` | 12 位數字，建置時間 `YYMMDDHHmmss` |
| `entry` | `app.asar` 裡的進入頁面；預設 `index.html` |
| `domains` | 頁面要請求的伺服器網域；由外掛的 `domains` 選項寫入（請見下面的「伺服器網域」） |
| `asarHeaderSha256` · `signature` | 由下面的工具寫入；不要手動修改 |

Cowork 從 `miniapp://<appId>/` 提供頁面，內容政策是 `script-src 'self'`：腳本都要放在檔案裡（不能有內嵌 `<script>`），`/assets/app.js` 這樣的絕對路徑可以用。已簽章的 Mini App 在每個 Cowork 帳號下各有一份儲存空間，一個人看不到另一個人存的東西。

## 建置

`@micromeet-ai/miniapp-sdk`（在 Micromeet 的 GitLab 套件庫；存取權限請洽 Micromeet）提供一個 Vite 外掛，每次建置後寫出封裝：

```js
// vite.config.js
import { defineConfig } from 'vite';
import { miniapp } from '@micromeet-ai/miniapp-sdk/vite';

export default defineConfig({
  plugins: [miniapp({ appId: 'ai.example.app', name: { en: 'Example', zh: '示例' }, unpackDir: 'media' })]
});
```

`vite build` 之後會寫出 `miniapp-package/`，版本取自 `package.json`。名為 `.DS_Store`、`__MACOSX`、`.git`、`node_modules` 的檔案不會打包進去。不用 Vite 時，`micromeet-miniapp pack --src dist --out miniapp-package --app-id … --name … --version …` 做同樣的事。

## 伺服器網域

Mini App 要和它自己的後端一起完成登入：頁面把一次性 code 送到後端（請見[登入](https://docs.micromeet.ai/zh-tw/miniapp-sdk/auth.md)）。後端的位址就是 Mini App 的**伺服器網域**；沒有驗證過的伺服器網域的版本，無法讓任何人登入。只有要用 Micromeet 登入的 Mini App 才需要伺服器網域；頁面請求別的介面不受它們限制。

1. 把後端的位址告訴 Micromeet，例如 `https://api.example.com`：HTTPS、主機名稱、不帶路徑；每個 Mini App 最多 20 個。
2. Micromeet 給你一個檔案：`https://api.example.com/micromeet-miniapp-<16 個字元>.txt`，內容是一串 token。把它放在這個位址，用 HTTPS 回傳 200，不能轉址。
3. Micromeet 取回這個檔案來驗證網域。檔案要一直留著：檔案不在了，這個網域就不再算數，登入也會停止。
4. 在封裝裡寫上這些網域：

```js
miniapp({ appId: 'ai.example.app', name: { en: 'Example' }, domains: ['https://api.example.com'] })
```

不用 Vite 時：`micromeet-miniapp pack … --domain https://api.example.com`。網域隨版本一起簽章，所以改了網域就是一個新版本。開發時，`http://localhost:<連接埠>` 或 `http://127.0.0.1:<連接埠>` 在 Micromeet 允許的環境裡不用放檔案。

## 交給 Micromeet 簽章

每個版本由 Micromeet 登記並簽章：Micromeet 自己的 Core 讀取 `app.asar`，逐一核對每個檔案的摘要，再對檔頭簽章；簽章會寫進 `manifest.json`。交出封裝之前，先依 Cowork 和 Micromeet 的規則自行檢查：

```bash
micromeet-miniapp verify miniapp-package            # 檢查封裝
micromeet-miniapp verify miniapp-package --signed   # 簽章之後：簽章能驗證通過
```

同一個版本不能登記兩次：每次交出新的建置都要改 `version`。

## 交付

```bash
micromeet-miniapp zip miniapp-package    # → ai.example.app-1.0.0.zip
```

使用者在 Cowork 裡請 Agent 安裝這個 zip（`miniapp_install`）。Cowork 把每個版本放在各自的資料夾，舊版本在它的分頁關閉後刪除。已簽章的 Mini App 也可以放進 Extension 和技能的套件裡一起安裝；每次開啟，Cowork 都同樣驗證簽章。

| 上限 | |
|---|---|
| `app.asar` | 512 MB；媒體放進 `app.asar.unpacked/`（`unpackDir` 或 `unpack`） |
| `app.asar.unpacked/` | 100,000 個檔案，8 GB |

## 相關

- [開發登入 Mini App](https://docs.micromeet.ai/zh-tw/miniapp-sdk/sign-in-guide.md): 從登記到登入跑通
- [封裝規範](https://docs.micromeet.ai/zh-tw/miniapp-sdk/package-spec.md): 封裝必須符合的全部規則，以及誰檢查
- [登入](https://docs.micromeet.ai/zh-tw/miniapp-sdk/auth.md): 在 Mini App 裡讓使用者登入
- [概覽](https://docs.micromeet.ai/zh-tw/miniapp-sdk/overview.md): Mini App SDK 的全部模組