# 入口与注册

## activate(api)

入口文件导出的函数。Cowork 每次启动 Extension 的进程时调用它一次。

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

### 参数

| 名称 | 类型 | 说明 |
|---|---|---|
| `api` | `DozinAPI` | 下面的注册函数 |

### 返回值

不返回，或返回一个清理函数（可以是 async），或返回 resolve 为二者之一的 promise。清理函数在进程停止时运行，调用多次也必须安全。

### 限制

- `activate` 限时 5 秒。定时器和连接要在 Connector 的 `start` 或任务的 `run` 里开启，不要放在这里。
- 如果它抛出异常或超时，Extension 在 **设置 › 扩展** 里显示为失败。

## api.registerConnector(definition)

注册一个 Connector：在外部渠道和 Cowork 的 Gateway 之间收发消息的那一端。

### 参数

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `definition` | `ConnectorDefinition` | 是 | 见 [Connector](https://docs.micromeet.ai/zh/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/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/extension-sdk/connector.md): 传给 `registerConnector` 的定义
- [后台任务](https://docs.micromeet.ai/zh/extension-sdk/service.md): 传给 `registerService` 的定义