autClaw 适配器负责把外部 IM、机器人框架或官方 SDK 接入系统。你在 plugin/adapters/ 编写独立 worker，把平台事件转成 autClaw 标准事件，再把标准出站动作转成平台协议包。
先记住三条边界
- 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 |
新渠道优先做核心 codec：resolve_account、normalize_inbound、build_outbound、decode_receipt。只有当 worker 自己直接调用平台 HTTP API / SDK 完成发送时，才启用 execute_outbound；如果发送由 backend 持有的 Gateway / WebSocket 完成，就保持 transport: "ws"，不要启用 execute_outbound。
最小实现顺序
- 写 manifest：
author、im_type、transport、account_id_key。
- 使用 backend 下发的
AUTCLAW_ADAPTER_CONNECT_URL 连接 control websocket。
- 收到
adapter_init 后，缓存配置并发送 adapter_worker_ready。
- 实现四个核心动作：
adapter_codec_resolve_accountadapter_codec_normalize_inboundadapter_codec_build_outboundadapter_codec_decode_receipt
- 实测私聊、群聊、媒体、回执和掉线重连。
manifest 只保留关键字段
适配器放在 plugin/adapters/。推荐文件名使用 adapter_{im_type}_{transport}.js，例如 adapter_demo_http.js、adapter_demo_ws.js。autClaw 会根据文件名辅助推断路由，但你仍应在 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]
//[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 的字段。 |
receive_token_key | 外部平台请求中携带 token 的 query key。 |
param | 配置表单；账号级配置写 "scope":"account"。 |
dependency | 运行依赖，例如 ws、axios、官方 SDK。 |
media | 只有本地 SDK 必须读取文件路径时才声明。 |
插件 manifest 声明头。
生命周期很简单
control 连接建立后，backend 会先发 adapter_init。你先重建账号索引、恢复配置和临时状态，再发 adapter_worker_ready。
| 阶段 | 你做什么 |
|---|
adapter_init | 读取 account_configs、global_config_values、common、instance_id 等初始化数据。 |
adapter_worker_ready | 声明当前 worker 支持的能力。 |
| 业务 RPC | 处理账号解析、入站标准化、出站构造、回执解码和主动动作。 |
详细协议见参考页
如果你要实现完整适配器，请继续看 适配器参考：
- control 消息信封
- 账号解析
- 入站标准化
- 出站构造与回执
- 主动事件和账号状态
- 媒体发送契约
- 最小 Node.js 框架
发布前只检查这些
adapter_init 后再处理平台业务消息。- 所有带
aut_echo 的调用都能返回成功或失败。
EventData、meta 和日志不包含 token、密码、私钥、验证码或完整签名。- HTTP API 调用设置超时，批量事件分批处理。
- 媒体发送优先使用
source，只有本地 SDK 才读取 file_path。
