适配器开发
适配器把一个聊天平台接入 Zhin。只有当你要接入的平台还没有官方适配器时,才需要读这一页;已支持的平台见 平台适配器。
适配器只做三件事:
- 创建平台 SDK 的客户端(Client);
- 把平台事件转换成 Zhin 的统一消息;
- 把 Zhin 要发出的消息转换成平台 API 调用。
热重载、账号身份、版本切换和资源清理都由框架负责。
Adapter API 2 的版本边界
本批仍以 npm patch 发布,但包含明确的插件接口变更。首批目标版本为 zhin.js 1.1.19、@zhin.js/core 1.1.54、@zhin.js/adapter 1.1.26、 @zhin.js/feature-kit 1.1.10(发布前以正式发布清单为准)。旧接口支持到这些版本之前; 新插件需要同时满足这组 npm 依赖下限,并声明 Adapter Feature API:
{ "features": [{ "package": "@zhin.js/adapter", "api": "^2.0.0" }] }这里的 api 位于 package.json#zhin.features。它与 npm 包版本、zhin.engine 是不同的 契约。首次接口切换的 featureApi 为 2.0.0(自身资料能力在 2.1.0 新增):旧的显式 api: ^1.0.0 会被拒绝,新插件在 旧 API-1 Provider 上也会被拒绝。未声明 api 的历史包保持原有行为,不代表已经确认兼容。 自定义插件需要重新编译、更新 peer/dev 下限,并验证实际安装组合;完整说明见 版本兼容与迁移。
最小实现
在插件里创建 adapters/<平台名>/index.ts,默认导出 defineAdapter():
// adapters/terminal/index.ts
import { Adapter, defineAdapter } from 'zhin.js/adapter';
import { TerminalEndpoint } from './endpoint.js';
interface TerminalConfig {
readonly terminal?: { readonly interactive?: boolean; readonly prompt?: string };
}
class TerminalAdapter extends Adapter<TerminalEndpoint, TerminalConfig, { readonly line: string }> {
protected createEndpoint(config: TerminalConfig): TerminalEndpoint {
return new TerminalEndpoint({
input: process.stdin, output: process.stdout, error: process.stderr,
interactive: config.terminal?.interactive ?? true,
prompt: config.terminal?.prompt ?? 'zhin> ',
});
}
}
declare module '@zhin.js/feature-kit' {
interface AdapterRegistry { readonly terminal: TerminalAdapter; }
}
export default defineAdapter<TerminalConfig>({
capabilities: ['inbound', 'outbound'],
createAdapter: () => new TerminalAdapter(),
});适配器包需直接依赖 @zhin.js/feature-kit,类型增补只写在该模块;自定义发布包可用 peer 加开发依赖,官方适配器的精确内部 dependencies 同样有效。zhin.js/adapter 仍提供 Adapter API;业务 Command 加载一次适配器声明后,只需填写平台名。
TerminalEndpoint 继承真正拥有终端 IO 的 TerminalClient,并 implements Endpoint;完整定义见 终端示例。平台有 SDK 时继承真实 SDK Client;没有 SDK 时,Client 应真正拥有协议 IO、请求和取消,不能只是回调 Endpoint 的空壳。
| 部分 | 作用 |
|---|---|
capabilities | 声明收、发或两者;直播弹幕另加 liveDanmaku,需同时声明 inbound |
createAdapter(context) | 创建所属插件的 Adapter,接收配置和注入依赖 |
Adapter.createEndpoint(config, execution) | 只在账号启动时构造真实 Endpoint;execution 固定 canonical identity、instance 和取消信号 |
Endpoint | 只有结构 interface,框架不提供公开可继承基类 |
[endpointSpec] | 通过 createEndpointSpecification(this, hooks) 绑定框架钩子,不覆盖原生 SDK API |
events.message() | 上报规范化消息,框架补全账号身份;发送者只能来自真实用户身份 |
specification 的 send() | 转换并发送消息,返回确认的消息 id 或有序 { parts } 证据 |
常见需求
让 Bot 能收到这个平台的消息
把适配器所在的插件挂载到 Bot 上,并在 zhin.config.yml 里填写配置:
configVersion: 2
plugins:
terminal: '@example/adapter-terminal'
terminal:
terminal:
interactive: true启动后在 Console 的"账号与会话"里确认账号在线(账号「接入」页签可测试连接),在账号「聊天」页签确认消息能收到。完整的挂载方式见 第一个插件 · 挂载到你的 Bot。
一个适配器挂多个账号
不需要改代码。在配置里写 endpoints 数组,每一项会创建一个独立的账号连接,所属 Adapter 的 createEndpoint(config, execution) 拿到合并后的单账号配置。规则见 端点生命周期 · 一个适配器挂多个账号。
只允许当前版本持有的监听器
将需要独占的监听器订阅放在 specification 的 open 钩子,在 close 中解除,stop 最终释放 IO。不要另建全局 live Endpoint Map。已经接纳的完整回调由 events.run 跟踪,关闭边界见下文。
WebSocket / SSE 长连接、心跳与重连
不要自己写重连状态机,使用 createEndpointLifecycle。
平台特有的消息格式
share、音频、卡片等平台特有结构,在 specification 的 send() 边界里转换成平台格式。插件发消息仍然统一走 Message.$reply 或 Host 的 outboundHostToken,不要另开发送通道。
在聊天里管理账号
用 createEndpointCommands 为适配器生成 <适配器> endpoint list / add / remove 命令,见 命令 · 适配器的 endpoint 管理命令。
继承平台 Client 与账号所有权
平台统一定义 Adapter<E, Config, Events> 子类,由它创建与管理所有 Endpoint。Endpoint 继承实际 SDK Client,并通过 endpointSpec / createEndpointSpecification 注册框架钩子;不覆盖 SDK 的 on、off、emit。通过唯一增补入口 @zhin.js/feature-kit 的 AdapterRegistry 注册一次 Adapter 类型,Command 的字符串平台声明即可推导子类与 Endpoint。
新增账号只保存停用配置,不创建 SDK 对象;显式启动才连接。停止、更新、删除和替换都由所属 Adapter 控制。仅更新配置资料 nickname / profile 时保留连接;连接配置变化才重连对应账号,旧操作固定到原 incarnation。defineAdapter 只接受 createAdapter;不要另建全局账号 Controller、Client token 或可写 Endpoint 目录。
配置资料的原地更新
nickname / profile 是平台资料缺失时的配置兜底,不是修改真实平台资料的命令。适配器级资料默认值按字段继承,账号显式值优先;已观察到的平台资料仍优先于配置。更新默认值不写账号库、不覆盖显式资料、不调用 SDK 资料写入。账号库已有 desired 记录时,文件中的账号启动种子不能覆盖它。
如果插件的 setup 不依赖这些字段建立业务状态,可以显式把它们声明为 Feature 所有:
import { definePlugin } from 'zhin.js';
export default definePlugin({
name: 'example-adapter',
configUpdate: { featurePaths: [['nickname'], ['profile'], ['endpoints']] },
setup(context) {
// 仅初始化与资料配置无关的资源。
},
});这份声明不等于整个 endpoints 数组都能原地更新:Adapter 会再次检查实际差异,只接受资料字段变化;账号增删、身份和连接参数变化仍走原生命周期。同一插件的其他 Feature 通过新的 snapshot 配置视图重建投影,不能简单返回旧索引。未声明的第三方插件保持原有重载行为。
已接纳操作持有原资料兜底门面,新操作使用新配置视图;平台观察事实和连接仍属于原账号。不要在异步 activateNext 修改共享 defaults,不要把 setup 捕获的 context.config.get() 当成能随配置变化的全局 getter。命令、工具与处理器应从本次操作的配置视图读取所需值;若 setup 必须捕获资料字段,就不要添加上述声明。
SDK 的 emit/on/off 与原生方法保持原合同。通过 AdapterRegistry 的 Adapter<Endpoint, Config, Events> 泛型一次推断 Client 和 EventMap;公开导出重用同一个 registry,不另注册 Client descriptor 或 token。
对应的适配器类型声明须进入 TypeScript 编译项目。同项目的适配器目录会自然参与;跨包可在 tsconfig 的 compilerOptions.types 加载适配器包,或在项目入口导入一次包类型。之后每条 Command 只写 adapter: 'icqq',无需导入具体 Adapter 类;运行时加载插件不会自动改变编辑器的类型项目。
完整接纳一次 SDK 回调
在 SDK listener 入口用 events.run(async () => { ... }) 包住整个异步回调,包括解析、原生事件转发和规范化消息提交,并等待或处理它返回的 Promise。只给最后一次 events.message() 加包装,不能覆盖此前仍在进行的解析或读取。
close 先关闭新的框架接纳,再调用平台关闭钩子,并等待已经接纳的回调及其规范化延续结束;stop 先退休该 incarnation 并取消信号,再排空操作租约、释放资源。平台请求也要响应这个信号。不要从本账号自己的入站回调同步等待其 close/stop,这会自等并被框架拒绝。
原生事件指 SDK 公开事件与它实际给出的对象:保留同一事件 payload,不删字段、不从规范化消息反推。它不等于原始 wire packet;SDK 没有公开的加密帧、HTTP bytes 或内部对象,不能宣称已经保真暴露。XML webhook、ParsedMail 等由平台自行解析的输入也应在原始事件路径保留实际原对象。
events.message() 负责规范化消息;events.platform(name, event) 保留平台原生事件。需要等实际准入和派发完成后再确认游标或 ACK 时,使用 events.emitAccepted(),失败不得推进游标。长连接重连与心跳仍用 createEndpointLifecycle,详见 生命周期钩子。
能力画像(profile)
核心只认能力,不认平台名:适配器用 defineAdapter({ profile }) 声明平台能做什么,zhin 在每个回合按当前会话把它合并、收窄成 TurnCapabilities,agent 和插件读它,不写平台名分支(ADR 0044)。
画像分 default、private、group、channel、thread 几个会话类型段(另有 kinds 声明自定义类型),未写的字段继承 default;类型段里写 false 可关掉继承来的能力。每段有七组:
| 组 | 内容 |
|---|---|
messaging | segments(即原 AdapterDefinition.segments,二者是同一份声明,写一处即可)、maxLength、mention、quote、reaction、recall、edit、forward、maxMessagesPerTurn |
scene | groupInfo、memberProfile、roles(平台角色词到 owner / admin / member)、platformStanding(入站 sender.platform 上报 standing / roles / permissions 中的哪些,ADR 0056 §1)、selfStanding(机器人自身在会话中的身份,由 management.inspectSelfStanding 查询、框架按会话缓存,供 bot:* permit;声明了就必须实现该方法)、mute、maxMembers、card、title |
actions | Bot 能主动做的事:reaction、poke、mute、unmute、muteAll、kick、setCard、setTitle、recall、essence、announce、invite、quoteReply、forward;每项 { scopes, requiresRole?, params? },未列出即不支持 |
events | emit(会发出的标准事件名)、liveDanmaku(即原 capabilities: ['liveDanmaku']) |
feedback | 「正在输入」方式:typing / reaction / status-message / none |
delivery | send、proactive、passiveWindow、rateLimitPerMinute、mediaMaxBytes、spool、requiresMessageSeq |
prompt | auto(自动生成平台说明)、text(适配器自定义文本) |
下面是一个 icqq 风格的例子:
import { defineAdapter } from 'zhin.js/adapter';
export default defineAdapter({
capabilities: ['inbound', 'outbound'],
profile: {
default: {
messaging: { maxLength: 4500, quote: true, segments: { supported: ['text', 'image', 'mention', 'face'] } },
scene: { roles: { owner: 'owner', admin: 'admin', member: 'member' } },
actions: {
reaction: { scopes: ['group'], params: { emojis: ['76', '66', '63'] } },
poke: { scopes: ['private', 'group'], params: { minIntervalSeconds: 5 } },
recall: { scopes: ['private', 'group'], params: { timeLimitSeconds: 120 } },
},
feedback: { mode: 'reaction', emoji: '424' },
delivery: { send: true, proactive: true, spool: true },
},
group: {
scene: { groupInfo: true, memberProfile: true, card: true, title: true, mute: { all: true } },
actions: {
mute: { scopes: ['group'], requiresRole: 'admin', params: { durationSeconds: { min: 60, max: 2592000 } } },
kick: { scopes: ['group'], requiresRole: 'admin' },
essence: { scopes: ['group'], requiresRole: 'admin' },
announce: { scopes: ['group'], requiresRole: 'admin', params: { maxLength: 1000 } },
setTitle: { scopes: ['group'], requiresRole: 'owner' },
},
prompt: { text: '群里提到你时再回应;不要主动刷屏。' },
},
private: {
actions: { poke: { scopes: ['private'] } },
scene: { groupInfo: false },
},
},
// 可选:按可信事实收窄。只能关掉能力、缩小范围,放宽的字段会被丢弃并记警告。
resolveCapabilities({ facts }) {
return facts.conversation?.muteAll ? { actions: { poke: false } } : undefined;
},
create: () => myEndpoint(),
});规则:
- 没声明 = 不支持。画像在
defineAdapter时校验,未知字段、类型错误直接抛错。 - 声明了动作就要实现端口。每个动作对应一个现有端口方法(
reaction→control.addReaction,recall→control.recall,mute→management.muteGroupMember,kick→management.kickGroupMember,announce→management.sendGroupNotice,poke→management.pokeUser,unmute→management.unmuteGroupMember,muteAll→management.muteAllGroupMembers,setCard→management.setGroupCard,setTitle→management.setGroupTitle,essence→management.setGroupEssence,invite→management.inviteGroupMember,quoteReply/forward→send())。缺端口时装配期报错并指出缺的方法。声明了画像的适配器,recall / edit / reaction / typing等operations由画像推出,不必再写一遍。 - 只收窄,不放宽。回合内先合并
default和当前会话类型段,再做通用收窄(Bot 的平台角色不满足requiresRole时动作关闭,角色未知也关闭;Bot 被禁言时发送与发消息类动作关闭;被动回复窗口用尽时关闭发送),最后应用resolveCapabilities的补丁。 segments按会话类型整段生效。messaging.segments是一整份声明:会话类型段(如channel)写了segments,就整段替换继承来的那份,不逐字段合并;出站投影(Markdown / HTML / 媒体 / 按钮的降级、supported白名单)和模型可用的段都按当前会话类型的那份判断,没写的类型沿用default(ADR 0064 F1)。- 不写画像也能用。没有
profile的适配器按capabilities、operations、segments得到一个保守画像(能发送、已声明的撤回/编辑/回应/输入中、已有的段策略),其余一律不支持。 - 回合内读取:
turn.input.platformCapabilities?.has('actions.mute')、.get('actions.mute.durationSeconds')(动作的params在路径里可省略)。能力描述平台允许什么;谁能让 Bot 这么做,仍由角色、硬闸和审批决定。
登录辅助(扫码、验证码、滑块)
需要人帮忙登录的适配器用 LoginAssist 的登录流程(ADR 0058)。分三步:
- 声明:
defineAdapter({ login: { mode: 'interactive', challenges: ['qrcode', 'slider'], relogin: true, refreshQr: true } })。mode取interactive/credential/external;不写login就是不支持,Console 不会显示登录操作。 - 实现钩子(声明了
relogin/refreshQr才需要):createEndpointSpecification(this, { …, login: { relogin: ({ signal }) => …, refreshChallenge: ({ signal }) => … } })。两者启动工作后就返回,结果走登录流程。 - 驱动流程:
// const assist = context.use(loginAssistToken) — import { loginAssistToken } from '@zhin.js/core/runtime'
const flow = assist.beginFlow({ adapter: 'demo', endpointKey, owner, signal, endpointIdentity });
flow.step('connect', t(locale, 'connecting'));
const answer = await flow.challenge({
kind: 'sms',
title: t(locale, 'smsTitle'),
help: { short: t(locale, 'smsHelp'), steps: [t(locale, 'smsStep1'), t(locale, 'smsStep2')] },
input: { kind: 'code', label: t(locale, 'code'), pattern: '^\\d{6}$', patternHint: t(locale, 'sixDigits'), secret: true },
actions: [
{ id: 'submit', label: t(locale, 'submit'), variant: 'primary', requiresInput: true },
{ id: 'resend', label: t(locale, 'resend'), variant: 'secondary', cooldownMs: 60_000 },
],
});
// 提交后 core 自动插入「验证中」;适配器报告真实结果:
const result = await sdk.submitSmsCode(answer.values.input);
if (result.ok) flow.online();
else flow.outcome({ result: 'rejected', code: 'code_invalid', message: t(locale, 'codeWrong'), next: 'retry_input' });要点:
- 文案和多语言由适配器负责;
kind只决定图标和排序。 - 平台错误映射到固定错误码:验证码错
code_invalid、太频繁rate_limited、过期challenge_expired、风控risk_blocked、密码或令牌错credential_invalid、网络network,其余unknown。flow.fail(code, message?)结束流程。 - 新挑战会替换旧挑战(旧的 Promise 以
LoginChallengeReplacedError结束)。 - 有人正在答挑战时不要自动重连:先看
assist.hasActiveChallenge(endpointKey, adapter)。 - 需要给用户材料时用
blocks:copy(设备信息等标sensitive: true)、link(只允许 http/https,showQr方便手机扫)、note。脚本块必须是静态文本,不要拼入用户或设备数据。 - 滑块 ticket 输入设
extract: 'ticket-json-or-url',core 的parseLoginTicket()会识别 ticket、ticket,randstr、JSON 和链接。 - 旧的
waitForInput()仍可用,会自动生成隐式流程;新代码请用beginFlow()。 - 参考实现:
plugins/adapters/icqq/src/icqq-login-assist.ts(扫码状态跟踪、滑块辅助页、设备锁 / 短信、身份验证引导)与错误码映射表icqq-login-errors.ts。
官方适配器能力矩阵
「✓」表示画像已声明且端口已实现;空白表示未声明,即不支持。管理类动作仅 icqq 有完整实现,napcat 只有群公告。
| 适配器 | 撤回 | 引用回复 | 编辑 | 回应 | 戳一戳 / 禁言 / 踢人 / 名片 / 头衔 / 精华 / 邀请 | 群公告 | 输入反馈 | 其他 |
|---|---|---|---|---|---|---|---|---|
| icqq | ✓(2 分钟) | ✓ | ✓(群) | ✓(管理类需 Bot 为管理员/群主,头衔需群主) | ✓ | 群:回应;私聊:状态消息 | 转发、事件、场景信息 | |
| qq(官方) | ✓ | ✓ | 被动回复窗口:群 5 分钟 × 5、C2C 60 分钟 × 4、频道 5 分钟 × 5 | |||||
| napcat | ✓ | ✓ | ✓(管理员) | |||||
| onebot11 / onebot12 / milky | ✓ | ✓ | ||||||
| kook / telegram / lark / discord | ✓ | ✓ | discord 的回应仍由 operations 声明(interactions 传输不能回应);telegram 撤回 48 小时 | |||||
| slack | ✓ | ✓ | ✓(可取消) | |||||
| satori / wecom | ✓ | |||||||
| weixin-ilink | 输入中 | |||||||
| wechat-mp | 客服消息窗口 48 小时 | |||||||
| bilibili / bilibili-live | 评论 1000 字 / 弹幕 20 字;bilibili-live 声明 liveDanmaku | |||||||
| dingtalk / line / email / github / sandbox | 仅发送 |
参考实现
examples/minimal-bot/adapters/terminal/index.ts:把终端当作一个聊天平台,适合对照学习。plugins/adapters/napcat:WebSocket / HTTP 多种连接方式,使用createEndpointLifecycle。
下一步
AI 能力与场景说明
适配器拥有平台能力声明,Agent 不应维护另一份平台操作清单:
- Tool 的
description、inputSchema、platforms / scopes / permissions描述一个操作。 agents/<platform>/skills/<name>/SKILL.md按用途和场景组织操作,正文仅在加载后披露。prompt-sections/<name>/index.ts承载必要的共同约定,使用platforms和scopes限定,不重复罗列 Skill/Tool 清单。segments.supported声明出站段,segments.model[type]提供模型扩展字段、平台hint和可选scopes。场景不匹配时,模型既看不到该段 Schema,也看不到其提示;这不授予发送权限,也不改变手写消息的发送策略。
以下声明表示模型只在群聊获得 share 卡片能力;其他场景仍保留通用文本和已有降级能力。不要根据名称推测平台支持,声明需与实际发送实现一致。
segments: {
supported: ['text', 'share'],
model: {
share: {
scopes: ['group'],
hint: 'Use a real URL and title from the user or tool results.',
},
},
}text 始终保留为通用回退;若为它声明场景,只限制扩展字段和提示。
渐进式回答
可在真实 Client 的 createEndpointSpecification(this, hooks) 中提供可选的 hooks.streaming。配置关闭或会话不适用时不提供该能力,普通 send 继续工作。 当前接入为 QQ 官方 C2C、Telegram 私聊草稿、Slack 线程、飞书应用卡片和 Sandbox; Discord 保留完整发送。各平台的适用范围和配置以适配器 README 为准。
EndpointStreaming.supports({ conversation, source }) 是同步、本地的预检,不能执行网络 查询;它用可信入站来源排除已知不支持的场景。open(request) 再校验正文格式、引用与 可见前缀,返回一个物理消息容器。undefined 表示确定不支持,查询失败不能冒充不支持。 这些端口随同原账号实例的租约保留,不得通过账号名重新查找一个替代 Client。
同一容器的 write(text) 和 finish(text) 由 Core 串行调用,接收累计原文,适配器再 转换成平台增量或完整更新。一个容器只承载一种文字格式;媒体、格式切换与平台容量 边界由 Core 保序。cancel() 仅停止本地更新,不暗中正式发送草稿、撤回消息或重试。
| 回执字段 | 含义 |
|---|---|
status: buffered | 本次没有新的外部变化,不能确认新增原文 |
status: preview | 仅临时可见,不能写成已发送历史 |
status: sent 与 messageId | 已确认的正式消息身份 |
acceptedText | 精确原文前缀,不是编码后的 HTML、Markdown 包装或 wire 长度 |
exhausted | 已证实达到物理容器限制,Core 先结束当前容器再续条 |
confirmedContent | 能独立验证的该条物理消息正文;包括可见前缀 |
contentUnavailable | 身份及原文游标已知,但独立富文本正文无法准确重建 |
EndpointMessageStream.lastAcknowledgement 可提供只读的最近确认事实。例如正文更新成功而 关闭流失败时,Core 会验证并记录其中的新 sent 正文,同时保留原关闭错误;它不能返回 推测的送达结果。续容器的 continuation.replyTo 仅保留原已渲染引用的路由,不重复发送可见前缀。
Core 继续复用渲染、权限、资源授权和出站中间件,不把模型原始 JSON、工具阶段文字或 推理内容直接交给适配器。已发送前缀不能改写;其后失败不得重发整条。语义快照上限是 每条回复 1 MiB(不含媒体原始字节),触限停止新增、保留已确认部分并说明原因。
完整类型见 endpoint-stream.ts,生命周期 回归见 捕获发送测试。
账号自身资料
此能力要求 Adapter Feature API ^2.1.0;在 Tool 中使用当前账号资料上下文还需要 Tool Feature API ^1.1.0。这些是可选能力的新增版本下限,不要求旧插件改成新的主版本。
账号昵称与性别、年龄、生日、签名、头像、兴趣和简介通过 createEndpointSpecification 的可选 profile 钩子提供。不要把 Endpoint 的实例名 name 当成平台昵称,也不要把群名片当成 账号昵称。原生 Client 的 API、属性和类型推断保持原样。
profile: {
writableFields: ['nickname'],
get current() { return { nickname: client.nickname }; }, // 已观察资料,不发请求
async read({ signal }) {
return readOwnPlatformProfile(client, signal);
},
async write({ change, signal }) {
if (change.field !== 'nickname') return { status: 'rejected' };
// 原生调用层区分 updated / rejected / unknown,不把超时当作拒绝。
const result = await changeOwnNickname(client, change.value, signal);
if (result.status === 'updated') return { ...result, profile: { nickname: change.value } };
return result; // 保留明确拒绝或结果未知。
},
}上面的读写函数代表适配器自己的原生调用,不是框架新增的函数。只声明实际安全实现的 writableFields;无法确认执行结果时返回 unknown,不得自动重试或冒充成功。一次请求 只改一个字段。头像资料只返回 URL;已解析的图片字节仅在执行时传入 SDK。
框架将端口绑定到原始 Client 和调用生命周期,停止或替换账号后不能通过旧端口修改新账号。 普通回合复用当前实例成功读取的资料,get_self_profile 主动刷新;不是实时轮询。 set_self_profile 只操作当前账号,沿用身份类审批;年龄不会被换算为一个虚构生日。 配置兜底见配置参考。