跳转到主要内容
适配器是 plugin/adapters/ 下的独立进程。你负责平台协议、账号解析、登录、事件标准化和发送;autClaw 负责进程管理、配置、账号路由、事件分发、媒体准备和发送回执。

Go 适配器

用 Go SDK 管理连接、握手、重连和并发调用。

Node.js 适配器

直接实现 control WebSocket,复用平台 npm SDK。

选择接入形态

声明 open_ingress 后,该 IM 的 receive 路由交给 adapter_open_ingress,不再调用账号解析和入站标准化动作。

声明 manifest

推荐文件名为 adapter_{im_type}_{transport} 加语言扩展名。在文件顶部声明:
Go 文件需要构建约束,详见 Go 适配器。通用头注见 manifest 声明头。

连接与握手

读取 AUTCLAW_ADAPTER_CONNECT_URL 连接 control WebSocket。保留完整 URL,包括 query 参数。未提供时,使用 ws://127.0.0.1:${AUTCLAW_PORT}/api/adapters/{im_type}/connect,端口默认 8200。
  1. 收到 adapter_init,缓存 global_config_values、account_configs、common 和 host_capabilities。
  2. 按 account_configs[].account_id 建立索引,保存每个账号的 instance_id;后续事件回填这个值。
  3. 发出有效的 adapter_worker_ready,再启动平台连接或轮询。
ready 的 aut_params:
contract 必须为 v6。features 和 outbound_actions 必须显式为数组,无能力时传 [];缺失、null 或类型错误会关闭连接。能力按当前连接声明,未声明的能力不可调用。协议支持与账号实际权限分别判断。 features 支持 message.streaming、message.typing、message.proactive、message.reaction、group.info、platform.action 和 action.generic。主动发送单独声明 message.proactive。

control 消息信封

成功和失败响应:
响应原样返回 aut_echo,不带 aut_action;aut_params 是对象。主动调用注册 pending、设置超时并按 aut_echo 匹配响应。断线时立即终止该连接的 pending 和平台循环;重连后重新初始化、声明能力。

上报标准事件

所有入站路径都使用同一结构:
kind、event_type、im_type、instance_id 必填。im_type 与来源适配器一致,instance_id 对应已知账号绑定。occurred_at 为 Unix 毫秒。session.type 可为 private、group、channel;群和频道必须提供 chat_id,私聊消息必须提供 actor.id。频道向插件投影为群会话。

规范事件名与载荷

event_type 是插件订阅值,必须精确填写下表名称: 群成员、群申请、好友申请和撤回事件还必须提供非空 event_id、dedupe_key 和正数 occurred_at。群成员与群申请事件必须使用 group 会话。没有平台事件 ID 时,用规范字段构造可重复生成的稳定 ID。 消息内容只写入 message.chain.items。历史上下文使用 message.history.message_ids 和 message.history.messages。raw 可保存消息原始摘要;专用通知和请求使用表中的规范载荷,插件读取投影后的字段。

消息段

chain.options.text_mode 可用 auto、plain、markdown。命令匹配文本只拼接 text 段,提及、引用和媒体不会混入命令文本。

媒体与宿主解析

入站和出站都使用 MediaRef:
source.kind 为 http、data_uri、base64、local_path 时,用 source.value 保存来源,不带 platform。platform 来源必须带 platform.im_type、reference_type、value,不填写 source.value。 display_name 仅供 file 段使用,必须是安全文件名。hints 是来源提示,不代表已检测的格式。宿主返回的 storage_name 按真实字节生成;平台上传文件名由 worker 明确选择。 adapter_init.host_capabilities.media_resolve: true 时,你可在当前发送的 build 或 execute 阶段调用:
representation 可选 reference、file_path、temporary_url;target.format 可选 original、opus、amr、mp4。返回相应的 reference、file_path 或 url,以及检测格式、名称、大小等信息。 能主动上传文件的平台请求 file_path,宿主下载、解码和校验后交给同机 worker 上传。需要平台下载地址时请求 temporary_url。可直接使用的 URL 或平台引用可直接转换为平台参数。 必须复用当前调用的 execution_id。发送完成或 control 断线后,解析资源释放;未知、已完成或跨连接的执行返回 media_execution_invalid。worker 无需调用清理动作,不向远端发送本地文件路径。

构造出站与能力映射

adapter_codec_build_outbound 接收 execution_id、request_id、im_type、account_id、action、目标字段和 payload。私聊目标用 session_type: "private" 与 user_id,群目标用 session_type: "group" 与 chat_id。 下面列出 worker 收到的动作与 ready 声明,避免把能力名称当成平台协议方法: 插件的 sendQRCode 由宿主生成二维码图片后转换为 sendImage;worker 按图片发送处理。 媒体 payload 示例:
build 返回 transport: "ws"、raw_payload、await_receipt。由 worker 发送时,额外返回 executor: "worker",autClaw 会调用 adapter_execute_outbound,参数包含 execution_id、im_type、account_id、raw_payload。 共享发送连接需要回执时,把 request_id 写进平台 echo 或 nonce。adapter_codec_decode_receipt 返回 matched、request_id、ok、error、data;非回执返回 {"matched":false}。worker 自执行返回 ok、error、data。信封外层 ok 表示调用执行结果,参数内层 ok 表示平台操作结果。

可撤回发送回执

支持撤回的发送在 data.sent_messages 返回每条实际发出的消息:
拆分发送时返回所有成功消息;部分失败时仍保留成功项。recall_context 只放撤回所需的字符串路由值,不放凭据或消息内容。autClaw 原样传给 recallMessage。不支持撤回或没有可靠消息 ID 时省略 sent_messages。

主动上报与游标

调用 adapter_emit_inbound_events,参数为 {"im_type":"demo","events":[...]}。返回结果示例:
queued、waiter_consumed、filtered、duplicate 均可推进游标;rejected 不可跳过。只推进到第一个拒绝项之前,重试缺口及后续事件。超时或断线表示整批未确认,重试整批并保持相同 dedupe_key。 结构校验失败、来源账号不符或连接 generation 过期会整批拒绝。队列满、入站媒体准备失败可产生逐事件拒绝。去重按 im_type 与 instance_id 隔离;自发消息可被过滤。不要只根据信封 ok 或 accepted 总数推进游标。

raw ingress

adapter_open_ingress 接收 instance_id、request_id、method、path、raw_query、多值 headers 与 body_base64。每个账号的专属回调地址为 /api/{im_type}/receive/{ingress_id}。 worker 返回:
verified: false 返回 403,不接收入站事件。response_mode 可为 immediate 或 passive;被动回复由 worker 在平台时限内等待插件回复并编码响应。请求与响应 body 上限 1 MiB。

账号、扫码与私有状态

  • adapter_request_outbound:声明 request_outbound 后,用 action、目标字段与标准 payload 请求统一发送链路。可带 execution_id 绑定当前父执行。
  • adapter_update_account_state:ready 后上报 account_id、status、sendable,可带 alias、message、last_error、RFC3339 时间字段与字符串 meta。无需独立能力位。
  • 扫码登录:manifest 和 ready 同时声明 supports_qr_login,并提供四项核心能力。adapter_login_qr_start 返回 session_key、qr_code_url、message、issued_at;adapter_login_qr_wait 接收 session_key、timeout_ms,成功返回 connected: true、account_id、account_config,由 autClaw 保存账号。
  • adapter_storage_get、adapter_storage_set、adapter_storage_delete:按 key 读写当前适配器的私有持久化字符串值;get 返回 found、value。用于保存游标或平台状态。

发布前检查

  • ready 包含 contract: "v6" 和两个能力数组,声明与实际实现一致。
  • 事件名称、专用载荷、账号实例和消息段均通过校验。
  • 每个调用有超时,断线清理 pending、平台循环和临时状态。
  • 覆盖部分拒绝、重复事件、部分发送失败、媒体准备和撤回。
  • 日志、raw、meta 和回执不泄露 token、密码或完整签名。

Go 适配器开发

使用 v6 Go SDK 管理 worker 生命周期、上报规范事件、解析媒体和返回发送回执。

Node.js 适配器开发

直接实现 v6 control WebSocket,管理握手、双向调用、标准事件、媒体解析和断线重连。
最后修改于 2026年10月12日