> ## Documentation Index
> Fetch the complete documentation index at: https://autclaw.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# 适配器插件开发规范

> 了解 autClaw 适配器的边界、最小能力和接入模式。详细协议、字段和示例见参考页。

autClaw 适配器负责把外部 IM、机器人框架或官方 SDK 接入系统。你在 `plugin/adapters/` 编写独立 worker，把平台事件转成 autClaw 标准事件，再把标准出站动作转成平台协议包。

<Note>
  本页只讲架构和最小落地路径。字段、消息信封、回执和完整示例见 [`适配器参考`](/cn/plugin-sdk/adapter-reference)。先从 [`适配器总览`](/cn/plugin-sdk/adapter) 开始更快。普通业务插件请先看 [`插件 SDK 概览`](/cn/plugin-sdk/overview)。
</Note>

## 先记住三条边界

* **worker** 负责协议适配：账号解析、入站标准化、出站构造、回执解码、登录和平台 workflow。
* **backend** 负责运行编排：启动进程、下发配置、维护 control websocket、分发消息和记录回执。
* **协议专属逻辑** 只放在适配器 worker 内，不要写进 autClaw 核心层。

## 选择接入模式

| 模式         | 适合场景                                    | 你要实现                                                                                                                  |
| ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Gateway 连接 | 平台通过反向 WebSocket / Gateway 收发，例如 OneBot | `resolve_account`、`normalize_inbound`、`build_outbound`、`decode_receipt`                                               |
| Worker 自发送 | 平台发送必须调用 HTTP API 或官方 SDK               | 上述 core codec + `execute_outbound`                                                                                    |
| 主动事件       | worker 自己维护长连接或 SDK 事件流                 | 上述 core codec + `emit_inbound_events`、`adapter_update_account_state`                                                  |
| 扫码登录       | 平台账号需要扫码授权或绑定                           | manifest 头注 `supports_qr_login` + worker ready `supports_qr_login` + `adapter_login_qr_start`、`adapter_login_qr_wait` |

<Tip>
  新渠道优先做核心 codec：`resolve_account`、`normalize_inbound`、`build_outbound`、`decode_receipt`。只有当 worker 自己直接调用平台 HTTP API / SDK 完成发送时，才启用 `execute_outbound`；如果发送由 backend 持有的 Gateway / WebSocket 完成，就保持 `transport: "ws"`，不要启用 `execute_outbound`。
</Tip>

## 最小实现顺序

1. 写 manifest：`author`、`im_type`、`transport`、`account_id_key`。
2. 使用 backend 下发的 `AUTCLAW_ADAPTER_CONNECT_URL` 连接 control websocket。
3. 收到 `adapter_init` 后，缓存配置并发送 `adapter_worker_ready`。
4. 实现四个核心动作：
   * `adapter_codec_resolve_account`
   * `adapter_codec_normalize_inbound`
   * `adapter_codec_build_outbound`
   * `adapter_codec_decode_receipt`
5. 如果适配器支持扫码登录，在 manifest 里声明 `//[supports_qr_login: true]`，并在 `adapter_worker_ready` 里上报 `supports_qr_login: true`，再实现 `adapter_login_qr_start`、`adapter_login_qr_wait`。
6. 实测私聊、群聊、媒体、回执和掉线重连；如果支持扫码登录，再实测扫码流程。

## manifest 只保留关键字段

适配器放在 `plugin/adapters/`。推荐文件名使用 `adapter_{im_type}_{transport}.js`，例如 `adapter_demo_http.js`、`adapter_demo_ws.js`。autClaw 会根据文件名辅助推断路由，但你仍应在 manifest 中显式声明关键字段。

```js theme={null}
//[title:adapter_demo_http]
//[version:1.0.0]
//[author: your-name]
//[class:适配器]
//[language: nodejs]
//[description: Demo IM HTTP adapter]
//[im_type: demo]
//[im_type_name: Demo IM]
//[protocol: im]
//[transport: http]
//[account_id_key: bot_id]
//[supports_qr_login: true]
//[receive_token_key: token]
//[dependency: {"name":"ws"}]
//[param: {"scope":"account","required":true,"key":"bot_id","name":"Bot ID","desc":"平台机器人账号 ID，同时作为 autClaw account_id"}]
//[param: {"scope":"account","required":false,"key":"token","type":"secret","secret":true,"bind":"ingress_token","name":"上报 Token","desc":"平台回调或连接携带的验证 token"}]
//[public: true]
//[price: 0]
```

| 字段                  | 说明                                                         |
| ------------------- | ---------------------------------------------------------- |
| `author`            | 用于生成稳定 `script_id`。                                        |
| `im_type`           | 渠道稳定标识，例如 `qq`、`fs`、`qx`。                                  |
| `transport`         | 外部入站方式，常用 `http` 或 `ws`。                                   |
| `account_id_key`    | 账号配置里用于生成 `account_id` 的字段。                                |
| `supports_qr_login` | 适配器声明自己提供扫码登录入口。这个头注只影响设置页入口展示，不代表当前 worker 已在线或一定能执行扫码动作。 |
| `receive_token_key` | 外部平台请求中携带 token 的 query key。                               |
| `param`             | 配置表单；账号级配置写 `"scope":"account"`。                           |
| `dependency`        | 运行依赖，例如 `ws`、`axios`、官方 SDK。                               |
| `media`             | 只有本地 SDK 必须读取文件路径时才声明。                                     |

<Info>
  `supports_qr_login` 分成两层：manifest 头注 `//[supports_qr_login: true]` 只声明“这个适配器有扫码登录入口”；`adapter_worker_ready.aut_params.supports_qr_login` 才声明“这个在线 worker 现在能处理扫码动作”。
</Info>

更多通用 manifest 字段见 [`插件 manifest 声明头`](/cn/plugin-sdk/manifest)。

## 生命周期很简单

control 连接建立后，backend 会先发 `adapter_init`。你先重建账号索引、恢复配置和临时状态，再发 `adapter_worker_ready`。

| 阶段                     | 你做什么                                                                       |
| ---------------------- | -------------------------------------------------------------------------- |
| `adapter_init`         | 读取 `account_configs`、`global_config_values`、`common`、`instance_id` 等初始化数据。 |
| `adapter_worker_ready` | 声明当前 worker 支持的能力，例如核心 codec、worker 自发送、主动事件和可选的 `supports_qr_login`。      |
| 业务 RPC                 | 处理账号解析、入站标准化、出站构造、回执解码和主动动作。                                               |

## 声明扫码登录能力

扫码登录在 autClaw 里分成“入口能力”和“运行能力”两层：

* manifest 头注 `//[supports_qr_login: true]`：让设置页在适配器未启用或 worker 未连上时也能显示“扫码登录”入口。
* `adapter_worker_ready.aut_params.supports_qr_login: true`：声明当前在线 worker 真的能处理扫码流程。backend 发起 `adapter_login_qr_start` / `adapter_login_qr_wait` 前会检查这一层。

```js theme={null}
function emitWorkerReady(ws) {
  ws.send(JSON.stringify({
    aut_action: 'adapter_worker_ready',
    aut_params: {
      resolve_account: true,
      normalize_inbound: true,
      build_outbound: true,
      decode_receipt: true,
      execute_outbound: true,

      // 只有支持扫码登录的适配器才写这一项
      supports_qr_login: true,
    },
  }))
}
```

然后处理两个 backend 下发的 action：

```js theme={null}
switch (message.aut_action) {
  case 'adapter_login_qr_start':
    replyWithEcho(ws, message, await handleLoginQRStart(message))
    return

  case 'adapter_login_qr_wait':
    replyWithEcho(ws, message, await handleLoginQRWait(message))
    return
}
```

要求：

* 不支持扫码登录的适配器不要声明 `//[supports_qr_login: true]`，也不要上报 `supports_qr_login: true`。
* 只声明 manifest 头注会显示入口，但不会让 backend 拉起扫码流程。
* 已上报 `supports_qr_login: true` 的适配器必须能响应 `adapter_login_qr_start` 和 `adapter_login_qr_wait`。
* 扫码成功后，`adapter_login_qr_wait` 可以返回 `account_config`，backend 会把账号配置写入适配器设置。

## 详细协议见参考页

如果你要实现完整适配器，请继续看 [`适配器参考`](/cn/plugin-sdk/adapter-reference)：

* control 消息信封
* 账号解析
* 入站标准化
* 出站构造与回执
* 扫码登录
* 主动事件和账号状态
* 媒体发送契约
* 最小 Node.js 框架

## 发布前只检查这些

* `adapter_init` 后再处理平台业务消息。
* 所有带 `aut_echo` 的调用都能返回成功或失败。
* `EventData`、`meta` 和日志不包含 token、密码、私钥、验证码或完整签名。
* HTTP API 调用设置超时，批量事件分批处理。
* 媒体发送优先使用 `source`，只有本地 SDK 才读取 `file_path`。