# Extension SDK

Extension 是在自己的后台进程里运行的代码。Cowork 加载它的入口文件，并调用一次 `activate(api)`。Extension 能做的一切都通过这个 `api` 对象，以及 Cowork 交给它所注册内容的 `ctx` 对象完成。本章列出每个模块和函数。

> **发布状态**
> 标有 <Badge type="warning" text="尚未发布" /> 的函数已在 Cowork 源码里，但还没有进入已发布的版本。

## 模块

| 模块 | 函数 | 需要 |
|---|---|---|
| [入口与注册](https://docs.micromeet.ai/zh/extension-sdk/entry.md) | `activate(api)` · `api.registerConnector` · `api.registerService` · `api.log` | — |
| [Connector](https://docs.micromeet.ai/zh/extension-sdk/connector.md) | `start(ctx)` · `stop()` · `send(reply)` · `ctx.emit` · `ctx.log` | —（0.1.41 中：列在 `connectors` 里） |
| [后台任务](https://docs.micromeet.ai/zh/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/extension-sdk/site.md) | `ctx.site.request` · `ctx.site.session` | `service` + `sites` |
| [服务对话](https://docs.micromeet.ai/zh/extension-sdk/agent.md) | `ctx.agent.handoff` | `service` + `agent` |
| [浏览器](https://docs.micromeet.ai/zh/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 不能读取 cookie、token 或其他扩展的数据。

## 相关

- [Extension](https://docs.micromeet.ai/zh/extend/extensions.md): Extension 是什么，怎么上线
- [Mini App SDK](https://docs.micromeet.ai/zh/miniapp-sdk/overview.md): 同一个包里的 Mini App 可以调用什么
- [扩展](https://docs.micromeet.ai/zh/connections/extensions.md): 安装、批准和打开开关