# 入口與註冊

## activate(api)

你的入口檔案匯出的函式。Cowork 每次啟動 Extension 的程序時呼叫它一次。

```js
export function activate(api) {
  api.registerService({ id: 'sync', start: 'auto', async run(ctx) { /* ... */ } });
  return () => { /* optional cleanup */ };
}
```

### 參數

| 名稱 | 類型 | 說明 |
|---|---|---|
| `api` | `DozinAPI` | 下面的註冊函式 |

### 回傳值

不回傳、回傳一個清理函式（可以是 async），或回傳兩者之一的 promise。清理函式在程序停止時執行，多次呼叫必須安全。

### 限制

- `activate` 有 5 秒時間。定時器和連線放在 Connector 的 `start` 或任務的 `run` 裡啟動，不要放在這裡。
- 如果它拋出錯誤或逾時，Extension 會在 **設定 › 擴充功能** 裡顯示為失敗。

## api.registerConnector(definition)

註冊一個 Connector：在外部渠道和 Cowork 的 Gateway 之間傳遞訊息的那一部分。

### 參數

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `definition` | `ConnectorDefinition` | 是 | 見 [Connector](https://docs.micromeet.ai/zh-tw/extension-sdk/connector.md) |

### 回傳值

不回傳任何值。

### 拋出

| 錯誤 | 時機 |
|---|---|
| `TypeError` | 缺少 `start`、`stop` 或 `send`；`id` 不是小寫字母、數字和連字元；`systemPrompt` 超過 4000 個字元；`chat` 無效 |
| `CapabilityDeniedError` | 在 `activate` 回傳後才呼叫；`dozin.connectors` 列出了 id，而這個 `id` 不在其中；同一個 `id` 註冊兩次；未提供 `dozin.connectors` 時註冊超過 16 個 Connector |

在 0.1.41 中，id 必須列在 `dozin.connectors` 裡（清單為空時所有 Connector 都會被拒絕），而且還沒有 `systemPrompt` 和 `chat`。

### 示例

```js
api.registerConnector({ id: 'demo', start(ctx) {}, stop() {}, async send() { return { ok: true }; } });
```

## api.registerService(definition) <Badge type="warning" text="尚未發布" />

註冊一個背景任務。它顯示在 **設定 › 擴充功能** 裡該 Extension 的下方，使用者（或有 `local_service` 的 AI）可以在那裡啟動和停止它。

### 參數

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `definition` | `ServiceDefinition` | 是 | 見 [背景任務](https://docs.micromeet.ai/zh-tw/extension-sdk/service.md) |

### 回傳值

不回傳任何值。

### 拋出

| 錯誤 | 時機 |
|---|---|
| `TypeError` | 沒有 `run` 函式，或定義裡的某個欄位無效（錯誤訊息會指出是哪個） |
| `CapabilityDeniedError` | 在 `activate` 回傳後才呼叫；`service` 不在 `dozin.capabilities` 裡；同一個 `id` 註冊兩次；超過 8 個任務 |

### 示例

```js
api.registerService({ id: 'sync', name: 'Sync', start: 'auto', async run(ctx) { /* ... */ } });
```

## api.log(text)

在 Extension 的日誌寫一行；使用者可以從 **設定 › 擴充功能** 開啟這份日誌。

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `text` | `string` | 是 | 這一行內容 |

不回傳任何值。

```js
api.log('activated');
```

## 相關

- [Connector](https://docs.micromeet.ai/zh-tw/extension-sdk/connector.md): 傳給 `registerConnector` 的定義
- [背景任務](https://docs.micromeet.ai/zh-tw/extension-sdk/service.md): 傳給 `registerService` 的定義