# 包规范 <Badge type="warning" text="尚未发布" />

Mini App 签名包要被 Micromeet 签名、被 Cowork 打开，必须满足的规则：每条规则是什么、谁检查、不满足会怎样。怎么做出这个包见[打包与签名](https://docs.micromeet.ai/zh/miniapp-sdk/build.md)；`micromeet-miniapp verify` 会先在你的电脑上把这些检查跑一遍。本页说的是签名的 Mini App 包，不是[包](https://docs.micromeet.ai/zh/miniapp-sdk/package.md)模块里的 Cowork 包。

| 检查方 | 什么时候 |
|---|---|
| **工具** | 你电脑上的 `micromeet-miniapp`（`pack`、`verify`、`zip`）和 Vite 插件 |
| **Micromeet** | Micromeet 登记并签名一个版本时 |
| **安装** | Cowork 安装这个包时 |
| **打开** | Cowork 每次打开这个 Mini App 时，以及页面每次读文件时 |

## 文件

```text
ai.example.app-1.0.0.zip
  manifest.json
  app.asar
  app.asar.unpacked/    可选：大的媒体文件
  INSTALL.md            可选：给安装它的 Agent 的步骤
```

| 规则 | 检查方 | 不满足时 |
|---|---|---|
| 这四项放在 zip（或文件夹）的根上；Cowork 只保留这些 | 安装 | 其他文件不会装上 |
| zip：最多 100,000 个条目、解开后最多 8 GB；不能加密，不能有绝对路径、`..`、反斜杠或符号链接 | 工具、安装 | 不安装 |
| 不能有名为 `.DS_Store`、`__MACOSX`、`.git`、`node_modules` 的文件或文件夹 | 工具 | `pack` 会去掉它们；`app.asar.unpacked/` 里有的话 `verify` 不通过 |

## manifest.json

| 字段 | 规则 | 检查方 | 不满足时 |
|---|---|---|---|
| `appId` | Micromeet 登记的 AppID：小写反向域名，如 `ai.example.app`，最多 128 个字符 | 工具、Micromeet、安装 | 拒收 |
| `name` | 字符串，或 `{ zh, en }`（至少一个）；1–60 个字符。不进签名：登录确认卡显示的是 Micromeet 登记的名字 | 工具、安装 | 拒收 |
| `version` | 以字母或数字开头；字母、数字、`.`、`+`、`-`；最多 32 个 | 工具、Micromeet | 拒收 |
| `version_code` | 12 位数字的字符串，构建时间 `YYMMDDHHmmss` | 工具、安装 | 拒收 |
| `entry` | 打在 `app.asar` 里面（不能放在 unpacked）的文件；相对路径，最多 256 个字符，不能有 `..`、反斜杠或控制字符。默认 `index.html` | 工具、Micromeet、安装 | 拒收 |
| `asar` | 归档的文件名：字母、数字、`.`、`_`、`-`，以 `.asar` 结尾。默认 `app.asar` | 工具、安装 | 拒收 |
| `domains` | 可选；只有要用 Micromeet 登录的 Mini App 才需要（[服务器域名](https://docs.micromeet.ai/zh/miniapp-sdk/build.md#服务器域名)）。`https://主机[:端口]`，小写、不带路径、不能是 IP；或 `http(s)://localhost[:端口]` / `127.0.0.1[:端口]`。不能重复，最多 20 个 | 工具、Micromeet、安装 | 拒收。每个域名都已为这个 AppID 验证过，Micromeet 才登记这个版本 |
| `asarHeaderSha256` | `app.asar` 前 8 + 文件头长度个字节的 SHA-256；由工具写入 | 工具、Micromeet、打开 | 算作未签名：Cowork 不打开 |
| `signature` | `{ kid, alg: "Ed25519", value }`，按 Micromeet 的回复写入 | 工具、打开 | 算作未签名：Cowork 不打开 |
| `extension` | 签名包里不能有 | 工具、安装 | 拒收 |

## app.asar

| 规则 | 检查方 | 不满足时 |
|---|---|---|
| 用 `@electron/asar` 3.x 打包；文件头与它写出的一字不差，最大 64 MB | 工具、Micromeet、安装 | 拒收 |
| 每个文件（含 unpacked）都有 `integrity`：SHA-256，按 4 MB 分块 | 工具、Micromeet、打开 | 拒收；Cowork 算作未签名 |
| 不能有符号链接，`app.asar` 里和 `app.asar.unpacked/` 里都不行 | 工具、Micromeet、安装 | 拒收 |
| 文件名和文件夹名不能为空、`.` 或 `..`，不能含 `/`、反斜杠或 NUL | 工具、Micromeet | 拒收 |
| `app.asar` 最大 512 MB；视频、音频放进 `app.asar.unpacked/` | 工具、Micromeet | 拒收 |
| `app.asar.unpacked/` 最多 100,000 个文件、8 GB；每个文件的大小与文件头记录的一致 | 工具、安装 | 拒收 |
| 每个文件的字节与它的摘要一致 | 工具、Micromeet、打开 | Micromeet 不签名；Cowork 关闭这个 Mini App，提示文件被改动 |
| HTML 里不能有内联 `<script>`：页面的内容策略是 `script-src 'self'` | 工具（`pack`） | `pack` 拒收；在页面里这段脚本也不会运行 |

Cowork 从 `miniapp://<appId>/` 提供文件，所以 `/assets/app.js` 这样的绝对路径可以用。请求其他服务不受限制。

## 签名

Micromeet 用 Ed25519 对下面这些字节签名。`domains` 排序后用一个空格连接，没有域名时最后一行为空。`name` 和图标不进签名。

```text
miniapp-sig-v2
<appId>
<version>
<entry>
<asarHeaderSha256>
<domains>
```

2026-11-10 之前登记的版本用的是 `miniapp-sig-v1`（前五行，没有域名），清单里没有 `domains` 时仍然有效。

| Cowork | 认作已签名 |
|---|---|
| 正式版 Cowork | `cowork-prod-1`：Micromeet 正式环境签的版本 |
| Cowork Preview | `cowork-preview-1` |
| 开发运行（未打包） | 自己渠道的密钥、`cowork-preview-1` 和 `cowork-test-1` |

## 版本与交付

| 规则 | 检查方 | 不满足时 |
|---|---|---|
| 一个版本只能登记一次：每次交出新的构建都要改 `version` | Micromeet | 拒收 |
| 改了任何文件、`entry` 或 `domains`，都要新版本、重新签名 | 打开 | 算作未签名：Cowork 不打开 |
| 用 zip 或文件夹单独安装（`miniapp_install`）：每个 `version_code` 放在自己的文件夹，旧版本在它的标签页关掉后删除 | 安装 | — |
| 也可以放进 Cowork 包里，复制安装或 link 安装；复制安装的包最多 2,000 个文件、50 MB（含 `app.asar`） | 安装 | 整个包拒收 |

## Cowork 打开时

- 没有签名、签名的密钥这个 Cowork 不认，或读不出来：Cowork 不打开，告诉用户这个 Mini App 未经认证。
- 页面读文件时，某个文件与摘要对不上：Cowork 关闭这个 Mini App，提示文件被改动。
- 每个 Cowork 账号各有一份这个 Mini App 的存储，一个人看不到另一个人存的东西。
- 页面只在 `miniapp://<appId>/` 里跳转；`http(s)` 链接用系统浏览器打开。
- 要登录用户，还需要 AppID 和版本在 Micromeet 处于启用状态，并且 `domains` 里至少有一个验证过的服务器域名（见[登录](https://docs.micromeet.ai/zh/miniapp-sdk/auth.md)）。

## 相关

- [打包与签名](https://docs.micromeet.ai/zh/miniapp-sdk/build.md): 做出这个包并交给 Micromeet 签名
- [登录](https://docs.micromeet.ai/zh/miniapp-sdk/auth.md): 在 Mini App 里登录用户
- [概览](https://docs.micromeet.ai/zh/miniapp-sdk/overview.md): Mini App SDK 的全部模块