# Extension SDK

Extension 是在自己的背景程序裡執行的程式碼。Cowork 載入它的入口檔案，並呼叫一次 `activate(api)`。Extension 能做的一切都透過這個 `api` 物件，以及 Cowork 交給它所註冊內容的 `ctx` 物件。本章列出每個模組和函式。

> **發布狀態**
> 標有 <Badge type="warning" text="尚未發布" /> 的函式已在 Cowork 的原始碼裡，但還沒有進入已發布的版本。

## 模組

| 模組 | 函式 | 需要 |
|---|---|---|
| [入口與註冊](https://docs.micromeet.ai/zh-tw/extension-sdk/entry.md) | `activate(api)` · `api.registerConnector` · `api.registerService` · `api.log` | — |
| [Connector](https://docs.micromeet.ai/zh-tw/extension-sdk/connector.md) | `start(ctx)` · `stop()` · `send(reply)` · `ctx.emit` · `ctx.log` | —（在 0.1.41：列在 `connectors` 裡） |
| [背景任務](https://docs.micromeet.ai/zh-tw/extension-sdk/service.md) | `run(ctx)` · `ctx.status` · `ctx.log` · `ctx.readJson` · `ctx.writeJson` · `ctx.env` · `ctx.dataDir` · `ctx.signal` | 權限 `service` |
| [站點請求](https://docs.micromeet.ai/zh-tw/extension-sdk/site.md) | `ctx.site.request` · `ctx.site.session` | `service` + `sites` |
| [服務對話](https://docs.micromeet.ai/zh-tw/extension-sdk/agent.md) | `ctx.agent.handoff` | `service` + `agent` |
| [瀏覽器](https://docs.micromeet.ai/zh-tw/extension-sdk/browser.md) | `ctx.browser.adoptTab` · `releaseTab` · `evaluate` · `inject` · `uninject` · `captureAudio` · `stopAudio` · `onEvent` | 權限 `browser`（聲音需要 `audio`） |

## package.json

這個範例用了尚未發布的 `service` 和 `sites`，在 0.1.41 上會被拒絕安裝。

```json
{
  "name": "janeapp-operator",
  "version": "0.1.0",
  "pi": { "extensions": ["./index.mjs"] },
  "dozin": {
    "capabilities": ["service"],
    "sites": [{ "host": "welladjustedhk.janeapp.com", "methods": ["GET"], "pathPrefixes": ["/admin/api/v2/"], "minIntervalMs": 1000 }]
  }
}
```

| 欄位 | 說明 |
|---|---|
| `name` | 小寫字母、數字和連字元；與資料夾名稱相同 |
| `version` | **設定 › 擴充功能** 裡顯示的版本。在 0.1.41 為必填；從下一個版本起預設為 `0.0.0` |
| `pi.extensions` | 恰好一個入口檔案。在 0.1.41 為必填。<Badge type="warning" text="尚未發布" />：可以省略，此時用 `main`，再否則用 `index.mjs`、`index.js`、`index.ts` 中第一個存在的 |
| `dozin.connectors` | 它註冊的 Connector 的 ID。列出時，只有這些 id 可以註冊。在 0.1.41 中，只有列在這裡的 id 才能註冊 Connector |
| `dozin.capabilities` | `browser`、`audio`（需要 `browser`）、`platform-gate-v1`，以及 `service` <Badge type="warning" text="尚未發布" /> |
| `dozin.origins` | 有 `browser` 時：它可以使用的 1 到 20 個確切網站（`https://example.com`）。在 0.1.41 有 `browser` 時為必填；從下一個版本起可以省略，此時允許任何 http(s) 網站，但仍然只限使用者交出的分頁 |
| `dozin.platforms` | `darwin-arm64`、`darwin-x64`、`win32-x64`；需要 `capabilities` 裡恰好有一個 `platform-gate-v1` |
| `dozin.secrets` <Badge type="warning" text="尚未發布" /> | 有 `service` 時：最多 8 個由使用者填寫的值，`{ env, label }`；`env` 須符合 `^[A-Z][A-Z0-9_]{0,63}$` |
| `dozin.sites` <Badge type="warning" text="尚未發布" /> | 有 `service` 時：最多 8 個供 `ctx.site` 使用的站點，`{ host, methods, pathPrefixes, minIntervalMs }` |
| `dozin.agent` <Badge type="warning" text="尚未發布" /> | 有 `service` 時：服務對話用的 `{ brief, model?, tools?, secret? }` |

在 Cowork 和 Dozin 裡，類型名稱都是 `DozinAPI`，所以同一個 Extension 不用修改就能安裝到任一個。

## 適用於所有模組的規則

- 在使用者於 **設定 › 擴充功能** 裡核准那些確切的檔案之前，什麼都不會執行。改動一個檔案就要重新核准。
- 一個套件最多 200 個檔案、5 MB；不會安裝 `dependencies`。
- Extension 無法讀取 cookies、token 或其他 Extension 的資料。

## 相關

- [Extension](https://docs.micromeet.ai/zh-tw/extend/extensions.md): Extension 是什麼、怎麼上線
- [Mini App SDK](https://docs.micromeet.ai/zh-tw/miniapp-sdk/overview.md): 同一個套件裡的 Mini App 可以呼叫什麼
- [擴充功能設定](https://docs.micromeet.ai/zh-tw/connections/extensions.md): 安裝、核准、開啟