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。
- 收到
adapter_init,缓存global_config_values、account_configs、common和host_capabilities。 - 按
account_configs[].account_id建立索引,保存每个账号的instance_id;后续事件回填这个值。 - 发出有效的
adapter_worker_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 示例:
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、密码或完整签名。