适配器插件开发规范

​

先记住三条边界

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

​

选择接入模式

​

最小实现顺序

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 只保留关键字段

//[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]

​

生命周期很简单

​

声明扫码登录能力

• 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 前会检查这一层。

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,
    },
  }))
}

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 会把账号配置写入适配器设置。

​

详细协议见参考页

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

​

发布前只检查这些

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