@zhin.js/adapter-qq 1.1.18 → 1.1.20

package/src/group-admin.ts

@@ -11,11 +11,13 @@ import type {
   GroupMemberInfo,
   GroupMemberRole,
 } from 'qq-official-bot';
-import type {
-  GroupMemberProfile,
-  GroupModerationAction,
-  GroupModerationMember,
-  GroupSceneFacts,
+import {
+  createEndpointOperation,
+  type EndpointGroupRequest, type EndpointMemberRequest, type EndpointMuteRequest,
+  type EndpointGroupInspectionRequest, type EndpointMemberInspectionRequest, type EndpointModerationRequest,
+  type GroupMemberProfile,
+  type GroupModerationMember,
+  type GroupSceneFacts,
 } from 'zhin.js/adapter';
 import type { QqOfficialApi } from './ws.js';
 
@@ -54,46 +56,46 @@ export function parseQqTime(value: unknown, { allowFuture = false } = {}): numbe
 }
 
 /** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
-export async function qqGroupBotState(api: Partial<QqOfficialApi> | undefined, groupId: string): Promise<GroupBotState> {
-  return qqGroupService(api).getBotState(requireId(groupId, 'group id'));
+export async function qqGroupBotState(api: Partial<QqOfficialApi> | undefined, { groupId, signal }: EndpointGroupRequest): Promise<GroupBotState> {
+  return createEndpointOperation({ signal }).run(() => qqGroupService(api).getBotState(requireId(groupId, 'group id')));
 }
 
-export async function qqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string): Promise<GroupMemberInfo> {
-  return qqGroupService(api).getMemberInfo(requireId(groupId, 'group id'), requireId(userId, 'member id'));
+export async function qqGroupMember(api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberRequest): Promise<GroupMemberInfo> {
+  return createEndpointOperation({ signal }).run(() => qqGroupService(api).getMemberInfo(requireId(groupId, 'group id'), requireId(userId, 'member id')));
 }
 
 /** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
 export async function muteQqGroupMember(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, durationSeconds: number,
+  api: Partial<QqOfficialApi> | undefined, { groupId, userId, durationSeconds, signal }: EndpointMuteRequest,
 ): Promise<void> {
   if (!Number.isSafeInteger(durationSeconds) || durationSeconds < 0 || durationSeconds > QQ_GROUP_MUTE_MAX_SECONDS) {
     throw new RangeError(`QQ group mute duration must be 0..${QQ_GROUP_MUTE_MAX_SECONDS} seconds`);
   }
   const member = requireId(userId, 'member id');
-  await qqGroupService(api).setMemberMute(requireId(groupId, 'group id'), [durationSeconds === 0
+  await createEndpointOperation({ signal }).run(() => qqGroupService(api).setMemberMute(requireId(groupId, 'group id'), [durationSeconds === 0
     ? { op: 'del', member_openid: member, mute_expire_at: '' }
-    : { op: 'add', member_openid: member, mute_expire_at: new Date(Date.now() + durationSeconds * 1000).toISOString() }]);
+    : { op: 'add', member_openid: member, mute_expire_at: new Date(Date.now() + durationSeconds * 1000).toISOString() }]));
 }
 
 /** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
 export async function kickQqGroupMember(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, addToBlacklist = false,
+  api: Partial<QqOfficialApi> | undefined, { groupId, userId, addToBlacklist = false, signal }: EndpointMemberRequest & { readonly addToBlacklist?: boolean },
 ): Promise<{ blacklistFailed: boolean }> {
   const member = requireId(userId, 'member id');
-  const result = await qqGroupService(api).removeMembers(requireId(groupId, 'group id'), {
+  const result = await createEndpointOperation({ signal }).run(() => qqGroupService(api).removeMembers(requireId(groupId, 'group id'), {
     member_openids: [member],
     ...(addToBlacklist ? { add_to_member_blacklist: true } : {}),
-  });
+  }));
   if (result?.remove_members_result !== 'success') throw new Error('QQ did not confirm the member removal');
   return { blacklistFailed: addToBlacklist && (result.add_to_member_blacklist_fail_openids ?? []).includes(member) };
 }
 
 /** 自动审核用：机器人与目标成员的实时角色；平台只允许管理员处置普通成员（且非机器人）。 */
 export async function inspectQqGroupMember(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal,
+  api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberInspectionRequest,
 ): Promise<GroupModerationMember> {
   signal.throwIfAborted();
-  const [self, member] = await Promise.all([qqGroupBotState(api, groupId), qqGroupMember(api, groupId, userId)]);
+  const [self, member] = await Promise.all([qqGroupBotState(api, { groupId, signal }), qqGroupMember(api, { groupId, userId, signal })]);
   signal.throwIfAborted();
   const role = member.member_openid === userId ? platformRole(member.member_role) : undefined;
   const joinedAt = parseQqTime(member.joined_at);
@@ -106,10 +108,10 @@ export async function inspectQqGroupMember(
 }
 
 export async function moderateQqGroupMember(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string,
-  action: GroupModerationAction, signal: AbortSignal, isActive: () => boolean,
+  { api, isActive }: { readonly api: Partial<QqOfficialApi> | undefined; readonly isActive: () => boolean },
+  { groupId, userId, action, signal }: EndpointModerationRequest,
 ): Promise<void> {
-  const member = await inspectQqGroupMember(api, groupId, userId, signal);
+  const member = await inspectQqGroupMember(api, { groupId: groupId, userId: userId, signal: signal });
   signal.throwIfAborted();
   if (!isActive() || !member.canModerate) throw new Error('Group moderation permission is unavailable');
   if (action.type === 'kick') {
@@ -118,21 +120,21 @@ export async function moderateQqGroupMember(
       || Date.now() - member.joinedAt > action.maxMembershipAgeMs) {
       throw new Error('Group membership no longer matches the approved newcomer window');
     }
-    await kickQqGroupMember(api, groupId, userId);
+    await kickQqGroupMember(api, { groupId, userId, signal });
     return;
   }
   if (!Number.isSafeInteger(action.durationSeconds) || action.durationSeconds <= 0) {
     throw new Error('Invalid group mute duration');
   }
-  await muteQqGroupMember(api, groupId, userId, Math.min(action.durationSeconds, QQ_GROUP_MUTE_MAX_SECONDS));
+  await muteQqGroupMember(api, { groupId: groupId, userId: userId, durationSeconds: Math.min(action.durationSeconds, QQ_GROUP_MUTE_MAX_SECONDS), signal });
 }
 
 /** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
 export async function inspectQqGroupScene(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, signal: AbortSignal,
+  api: Partial<QqOfficialApi> | undefined, { groupId, signal }: EndpointGroupInspectionRequest,
 ): Promise<GroupSceneFacts> {
   signal.throwIfAborted();
-  const info = await qqGroupService(api).getInfo(requireId(groupId, 'group id'));
+  const info = await createEndpointOperation({ signal }).run(() => qqGroupService(api).getInfo(requireId(groupId, 'group id')));
   signal.throwIfAborted();
   if (info?.group_openid && info.group_openid !== groupId) return {};
   const name = typeof info?.group_name === 'string' && info.group_name.trim() ? info.group_name.trim() : undefined;
@@ -142,10 +144,10 @@ export async function inspectQqGroupScene(
 
 /** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
 export async function inspectQqGroupMemberProfile(
-  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal,
+  api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberInspectionRequest,
 ): Promise<GroupMemberProfile> {
   signal.throwIfAborted();
-  const member = await qqGroupMember(api, groupId, userId);
+  const member = await qqGroupMember(api, { groupId, userId, signal });
   signal.throwIfAborted();
   if (member.member_openid !== userId) return {};
   const role = platformRole(member.member_role);

package/src/i18n.ts

@@ -3,8 +3,8 @@ import { createMessages } from 'zhin.js/i18n';
 export const messages = createMessages({
   bindTaskFailed: { 'zh-CN': '获取绑定任务失败: {error}', en: 'Could not create the binding task: {error}' },
   "kindPrompt": {
-    "zh-CN": "请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。",
-    "en": "Reply public or private to save .env and configuration together."
+    "zh-CN": "请回复 public（公域）或 private（私域），确认后保存账号；需手动启动。",
+    "en": "Reply public or private to save the account, then start it explicitly."
   },
   "cancelHint": {
     "zh-CN": "也可发 {command} 取消。",
@@ -19,8 +19,8 @@ export const messages = createMessages({
     "en": "⚠️ Endpoint “{id}” is waiting for public/private selection"
   },
   "endpointSaved": {
-    "zh-CN": "✅ 已按 botKind={kind} 将 endpoint「{id}」写入 .env 与 {file}。\nintents: {intents}。\n⚠️ 需重启 zhin 后新 endpoint 才会生效。",
-    "en": "✅ Saved endpoint “{id}” with botKind={kind} to .env and {file}.\nintents: {intents}.\n⚠️ Restart zhin to activate the new endpoint."
+    "zh-CN": "✅ 已按 botKind={kind} 保存账号「{id}」。\nintents: {intents}。\n尚未启动，请显式启动此账号。",
+    "en": "✅ Saved account “{id}” with botKind={kind}.\nintents: {intents}.\nThe account is inactive; start it explicitly."
   },
   "existingFlow": {
     "zh-CN": "已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先取消后再试",

package/src/image-size.ts

@@ -92,15 +92,19 @@ async function readHead(response: Awaited<ReturnType<ImageProbeFetch>>): Promise
 }
 
 /** 读取公网图片文件头得到尺寸；网络错误、超时或格式不识别时返回 undefined。 */
+export interface ImageProbeOptions {
+  readonly fetch?: ImageProbeFetch;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+}
 export async function probeImageSize(
   url: string,
-  fetchImpl: ImageProbeFetch = fetch as unknown as ImageProbeFetch,
-  timeoutMs = PROBE_TIMEOUT_MS,
+  { fetch: fetchImpl = fetch as unknown as ImageProbeFetch, timeoutMs = PROBE_TIMEOUT_MS, signal }: ImageProbeOptions = {},
 ): Promise<QqImageSize | undefined> {
   try {
     const response = await fetchImpl(url, {
       headers: { Range: `bytes=0-${PROBE_BYTES - 1}` },
-      signal: AbortSignal.timeout(timeoutMs),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok) return undefined;
     return imageSizeFromBytes(await readHead(response));

package/src/index.ts

@@ -38,8 +38,6 @@ export { imageSizeFromBytes, probeImageSize, type QqImageSize } from './image-si
 export {
   QqHttpEndpoint,
   QqWebsocketEndpoint,
-  type CreateQqBot,
-  type CreateQqHttpBot,
   type QqBotTransport,
   type QqOfficialApi,
   type QqEndpointOptions,
@@ -51,17 +49,17 @@ export {
   registerQqWebhookRoutes,
   handleQqWebhookRequest,
   readRequestBodyText,
-  defaultCreateHttpBot,
+  qqHttpBotOptions,
   type QqWebhookHandler,
 } from './webhook.js';
 
 export {
   bindQqBotInboundEvents,
-  defaultCreateBot,
+  qqWebsocketBotOptions,
   normalizeQqMessage,
 } from './ws.js';
 
-export { qqClient, type QqClientEventMap } from './client.js';
+export { type QqClientEventMap } from './client.js';
 
 export {
   checkQqPlatformPermit,
@@ -69,3 +67,5 @@ export {
   platformPermit,
   qqGuildPermitResolver,
 } from './platform-permit.js';
+
+export { QqAdapter } from './adapter.js';

package/src/interaction.ts

@@ -11,5 +11,5 @@ export function normalizeQqInteraction(raw: unknown): { message: QqInboundMessag
   const id = kind === 'private' ? actor : kind === 'group' ? event.group_id : event.channel_id;
   if (!kind || !id || !actor || (kind === 'channel' && !event.guild_id)) return null;
   const sourceMessageId = typeof resolved.message_id === 'string' && resolved.message_id ? resolved.message_id : undefined;
-  return { message: { id: event.notice_id, content: '', channelKind: kind, channelId: id, authorId: actor, authorName: '', timestamp: Date.now(), ...(event.guild_id ? { guildId: event.guild_id } : {}), segments: [{ type: 'action', data: { payload: resolved.button_data } }] }, ...(sourceMessageId ? { sourceMessageId } : {}), ack: () => event.reply!(0) };
+  return { message: { event: raw, id: event.notice_id, content: '', channelKind: kind, channelId: id, authorId: actor, authorName: '', timestamp: Date.now(), ...(event.guild_id ? { guildId: event.guild_id } : {}), segments: [{ type: 'action', data: { payload: resolved.button_data } }] }, ...(sourceMessageId ? { sourceMessageId } : {}), ack: () => event.reply!(0) };
 }

package/src/outbound.ts

@@ -374,7 +374,7 @@ export function formatOutboundMessages(payload: unknown, options: FormatOutbound
  */
 export async function collectOutboundImageSizes(
   payload: unknown,
-  probe: (url: string) => Promise<QqImageSize | undefined> = (url) => probeImageSize(url),
+  { probe, signal }: { readonly probe?: (url: string) => Promise<QqImageSize | undefined>; readonly signal?: AbortSignal } = {},
 ): Promise<Map<string, QqImageSize>> {
   const sizes = new Map<string, QqImageSize>();
   const segments = toSegmentList(payload).filter((item): item is QqWireSegment => typeof item !== 'string');
@@ -385,7 +385,8 @@ export async function collectOutboundImageSizes(
     if (isMediaRef(media) && media.kind === 'url' && /^https?:\/\//i.test(media.value)) urls.add(media.value);
   }
   await Promise.all([...urls].map(async (url) => {
-    const size = await probe(url);
+    signal?.throwIfAborted();
+    const size = await (probe ? probe(url) : probeImageSize(url, { signal }));
     if (size) sizes.set(url, size);
   }));
   return sizes;

package/src/protocol.ts

@@ -57,6 +57,8 @@ export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
 export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
 
 export interface QqInboundMessage {
+  readonly event?: unknown;
+  readonly platformSentAt?: number;
   readonly id: string;
   readonly content: string;
   readonly channelKind: QqChannelKind;

package/src/qq-console-spec.ts

@@ -9,7 +9,18 @@ import type { AdapterConsoleField } from 'zhin.js/adapter';
 export const qqConsoleSpec = {
   adapterKey: 'qq',
   adapterDisplayName: 'QQ',
-  fields: [] as readonly AdapterConsoleField[],
+  fields: [
+    { key: 'appid', required: true, description: 'QQ appid' },
+    { key: 'secret', required: true, env: true, description: 'QQ app secret' },
+    { key: 'mode', description: 'websocket, webhook or middleware' },
+    { key: 'sandbox', type: 'boolean', description: 'QQ sandbox environment' },
+    { key: 'botKind', description: 'public or private; existing explicit intents remain authoritative' },
+    { key: 'accessTokenUrl', description: 'Configured access-token API URL' },
+    { key: 'gatewayUrl', description: 'Configured Gateway discovery URL' },
+    { key: 'webhookPath', description: 'Local webhook route' },
+    { key: 'streamProxy.port', type: 'number', description: 'Configured Gateway loopback proxy port' },
+    { key: 'streamProxy.serverName', description: 'Expected Gateway TLS hostname' },
+  ] as readonly AdapterConsoleField[],
   canAdd: false,
   canRemove: true,
   docsUrl: 'https://zhin.js.org/adapters/qq',

package/src/qq-console.ts

@@ -3,15 +3,15 @@
  * 搬到 Console 页面。
  *
  * - `start` 返回扫码链接；后续状态写入 `state.consoleBind`，页面轮询 status。
- * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再一次性写 `.env` + 配置。
+ * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再通过捕获的所属 Adapter CAS 保存。
  * - 与聊天命令共享 `state.bindFlow` 单例，同一时间只允许一个绑定流程。
  */
 import { PluginConsoleRpcError } from 'zhin.js';
+import { AdapterManagementError } from 'zhin.js/adapter';
 import { startQqBindFlow } from './qq-bind-flow.js';
-import { writeQqEndpointWithBotKind, type QqEndpointWriteResult } from './qq-endpoint-write.js';
+import { writeQqEndpointWithBotKind, type QqEndpointWriteResult, type QqEndpointSavePort } from './qq-endpoint-write.js';
 import { parseQqBotKind } from './qq-intents.js';
 import type { QqRuntimeState } from './qq-runtime-state.js';
-import type { EndpointConfigurationStore } from 'zhin.js/adapter';
 
 /** 启动 Console 扫码；resolve 时二维码链接已就绪。 */
 export function startQqConsoleBind(
@@ -86,10 +86,10 @@ export function startQqConsoleBind(
   });
 }
 
-/** 扫码成功后选择公域 / 私域并写回配置。 */
+/** 扫码成功后选择公域 / 私域并保存未启动账号。 */
 export async function completeQqConsoleBind(
   state: QqRuntimeState,
-  store: EndpointConfigurationStore,
+  save: QqEndpointSavePort,
   kindValue: unknown,
 ): Promise<QqEndpointWriteResult> {
   const pending = state.consoleBind?.pending;
@@ -101,11 +101,16 @@ export async function completeQqConsoleBind(
     throw new PluginConsoleRpcError('invalid_input', '请选择公域（public）或私域（private）');
   }
   try {
-    const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, store);
+    const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, save);
     state.consoleBind = null;
+    state.consoleAdmission = null;
     return result;
-  } catch {
-    throw new PluginConsoleRpcError('unavailable', '写入配置失败，请检查配置文件和 .env 的权限');
+  } catch (error) {
+    if (error instanceof PluginConsoleRpcError) throw error;
+    const code = error instanceof AdapterManagementError ? error.code : 'unavailable';
+    if (code === 'commit_unknown') throw new PluginConsoleRpcError('commit_unknown', '提交结果未知，请刷新核实，勿重复提交');
+    if (code === 'conflict' || code === 'duplicate_entry' || code === 'closed') throw new PluginConsoleRpcError('conflict', '账号清单已变化，请刷新核实');
+    throw new PluginConsoleRpcError('unavailable', '账号配置未能保存，请刷新状态');
   }
 }
 
@@ -120,5 +125,6 @@ export function cancelQqConsoleBind(state: QqRuntimeState): boolean {
   state.bindFlow = null;
   state.pendingBotKind = null;
   state.consoleBind = null;
+  state.consoleAdmission = null;
   return active;
 }

package/src/qq-endpoint-write.ts

@@ -1,11 +1,7 @@
-/**
- * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
- * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
- *
- * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
- */
-import { buildEndpointEnvKey, type EndpointConfigurationStore } from 'zhin.js/adapter';
+/** A validated QR result is saved through its owning Adapter's single CAS admission. */
+import type { AdapterMutationResult } from 'zhin.js/adapter';
 import { defaultQqEndpointIntentFields, type QqBotKind } from './qq-intents.js';
+import type { QqEndpointConfig } from './protocol.js';
 
 export interface QqEndpointWriteInput {
   readonly endpointId: string;
@@ -13,40 +9,16 @@ export interface QqEndpointWriteInput {
   readonly appSecret: string;
   readonly botKind: QqBotKind;
 }
-
+export type QqEndpointSavePort = (configuration: QqEndpointConfig) => Promise<AdapterMutationResult>;
 export interface QqEndpointWriteResult {
-  readonly filePath: string;
   readonly endpointId: string;
   readonly botKind: QqBotKind;
   readonly intents: readonly string[];
+  readonly mutation: AdapterMutationResult;
 }
-
-/** 写回 `.env` + `zhin.config.yml`；失败时抛原错误，由调用方决定文案。 */
-export async function writeQqEndpointWithBotKind(
-  input: QqEndpointWriteInput,
-  store: EndpointConfigurationStore,
-): Promise<QqEndpointWriteResult> {
-  const appidKey = buildEndpointEnvKey('qq', input.endpointId, 'appid');
-  const secretKey = buildEndpointEnvKey('qq', input.endpointId, 'secret');
-  const intentFields = defaultQqEndpointIntentFields(input.botKind);
-  const { filePath } = await store.add({
-    adapterKey: 'qq',
-    entry: {
-      id: input.endpointId,
-      appid: `\${${appidKey}}`,
-      secret: `\${${secretKey}}`,
-      botKind: intentFields.botKind,
-      intents: [...intentFields.intents],
-    },
-    environment: {
-      [appidKey]: input.appId,
-      [secretKey]: input.appSecret,
-    },
-  });
-  return {
-    filePath,
-    endpointId: input.endpointId,
-    botKind: intentFields.botKind,
-    intents: intentFields.intents,
-  };
+export async function writeQqEndpointWithBotKind(input: QqEndpointWriteInput, save: QqEndpointSavePort): Promise<QqEndpointWriteResult> {
+  const fields = defaultQqEndpointIntentFields(input.botKind);
+  const mutation = await save({ id: input.endpointId, appid: input.appId, secret: input.appSecret,
+    botKind: fields.botKind, intents: [...fields.intents] });
+  return { endpointId: input.endpointId, botKind: fields.botKind, intents: fields.intents, mutation };
 }

package/src/qq-runtime-state.ts

@@ -1,14 +1,9 @@
 /**
- * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
- * 扫码绑定 / 待选 botKind 流程。由 plugin.ts setup() provide，
- * adapter create 与 commands / middleware 通过 use(qqRuntimeStateToken) 共享。
+ * QQ 插件实例的瞬态扫码绑定 / 待选 botKind 流程。
+ * 账号目录与 SDK 生命周期只由所属 Adapter 持有；此处不保存 Endpoint Map。
  */
 import { createToken } from 'zhin.js';
-
-export interface QqRunningEndpoint {
-  id: string;
-  mode: string;
-}
+import type { QqEndpointSavePort } from './qq-endpoint-write.js';
 
 export interface QqBindFlowHandle {
   /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
@@ -20,10 +15,10 @@ export interface QqBindFlowHandle {
 }
 
 /**
- * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
- * （提前写 .env 会触发 HMR，冲掉 pending。）
+ * 扫码成功后暂存在内存：确认公域/私域后调用发起时捕获的所属 Adapter CAS。
  */
 export interface QqPendingBotKind {
+  readonly save: QqEndpointSavePort;
   readonly endpointId: string;
   readonly appId: string;
   readonly appSecret: string;
@@ -53,19 +48,19 @@ export interface QqConsoleBindState {
 }
 
 export interface QqRuntimeState {
-  /** 当前 generation 已成功创建的 endpoint（id → 描述） */
-  readonly endpoints: Map<string, QqRunningEndpoint>;
-  /** 全局单例：同一时间只允许一个扫码绑定流程 */
+  /** Snapshot checked when the QR flow began, never a second account directory. */
+  consoleAdmission: Readonly<{ adapterId: string; generation: number; revision: number | null }> | null;
+  /** 同一插件 generation 内只允许一个扫码绑定流程 */
   bindFlow: QqBindFlowHandle | null;
   /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
   pendingBotKind: QqPendingBotKind | null;
-  /** Console 页面的扫码绑定进度（与 bindFlow 共享单例）。 */
+  /** Console 页面的扫码绑定进度（与 bindFlow 共享同一插件瞬态流程）。 */
   consoleBind: QqConsoleBindState | null;
 }
 
 export function createQqRuntimeState(): QqRuntimeState {
   return {
-    endpoints: new Map(),
+    consoleAdmission: null,
     bindFlow: null,
     pendingBotKind: null,
     consoleBind: null,
@@ -74,5 +69,5 @@ export function createQqRuntimeState(): QqRuntimeState {
 
 export const qqRuntimeStateToken = createToken<QqRuntimeState>(
   'zhin.qq.runtime-state',
-  'QQ adapter runtime state (running endpoints + bind flow singleton)',
+  'QQ transient QR binding state',
 );

package/src/qq-send.ts

@@ -10,8 +10,9 @@
  * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
  *    for a while and fail fast instead of calling the platform again.
  */
-import type { ConversationRef } from '@zhin.js/im-contract';
-import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { createEndpointOperation, type EndpointOperation } from 'zhin.js/adapter';
+import { EndpointDeliveryError, type ConversationRef } from '@zhin.js/im-contract';
+import type { Sendable } from 'qq-official-bot';
 import type { QqOutboundElem, QqOutboundMessage } from './outbound.js';
 import {
   QQ_ACTIVE_UNAVAILABLE_CODES,
@@ -34,6 +35,20 @@ export interface QqSendContext {
 }
 
 type Kind = ReturnType<typeof qqOutboundKind>;
+interface QqSendExecution extends QqSendContext { readonly operation: EndpointOperation; }
+interface QqMessageDispatch {
+  readonly kind: Kind;
+  readonly id: string;
+  readonly message: QqOutboundMessage;
+  readonly source?: QqReplySource;
+  readonly options?: QqSendOptions;
+}
+export interface QqMessagesRequest {
+  readonly conversation: ConversationRef;
+  readonly messages: readonly QqOutboundMessage[];
+  readonly signal?: AbortSignal;
+}
+
 
 function elements(message: QqOutboundMessage): Array<string | QqOutboundElem> {
   return Array.isArray(message) ? [...message] : [message as string | QqOutboundElem];
@@ -69,14 +84,14 @@ export function markdownAsText(message: QqOutboundMessage): QqOutboundMessage |
   return text ? [...kept, text] : undefined;
 }
 
-function dispatch(bot: QqBotTransport, kind: Kind, id: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown> {
+function dispatch(bot: QqBotTransport, { kind, id, message, source, options }: QqMessageDispatch): Promise<unknown> {
   switch (kind) {
-    case 'private': return bot.sendPrivateMessage(id, message, source, options);
-    case 'group': return bot.sendGroupMessage(id, message, source, options);
-    case 'channel': return bot.sendGuildMessage(id, message, source, options);
+    case 'private': return bot.sendPrivateMessage(id, message as Sendable, source, options);
+    case 'group': return bot.sendGroupMessage(id, message as Sendable, source, options);
+    case 'channel': return bot.sendGuildMessage(id, message as Sendable, source, options);
     case 'direct':
       if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
-      return bot.sendDirectMessage(id, message, source, options);
+      return bot.sendDirectMessage(id, message as Sendable, source, options);
   }
 }
 
@@ -85,15 +100,15 @@ function platformCode(error: unknown): number | undefined {
 }
 
 /** Sends one message, passive if possible; returns the platform result. */
-async function sendOne(context: QqSendContext, kind: Kind, id: string, message: QqOutboundMessage): Promise<unknown> {
+async function sendOne(context: QqSendExecution, { kind, id, message }: QqMessageDispatch): Promise<unknown> {
   const passive = (body: QqOutboundMessage, grant: PassiveReplyGrant) =>
-    dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+    context.operation.run(() => dispatch(context.bot, { kind, id, message: body, source: grant.source, options: { msgSeq: grant.msgSeq } }));
   const active = async (body: QqOutboundMessage): Promise<unknown> => {
     if (context.activeGate.blocked(kind, id)) {
       throw new EndpointDeliveryError('platform_rejected', 'QQ active messages are unavailable for this conversation', 'not_sent');
     }
     try {
-      return await dispatch(context.bot, kind, id, body);
+      return await context.operation.run(() => dispatch(context.bot, { kind, id, message: body }));
     } catch (error) {
       const code = platformCode(error);
       if (code !== undefined && QQ_ACTIVE_UNAVAILABLE_CODES.has(code) && context.activeGate.block(kind, id)) {
@@ -130,9 +145,10 @@ async function sendOne(context: QqSendContext, kind: Kind, id: string, message:
 }
 
 /** Sends every message of one delivery in order; returns the last platform result. */
-export async function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown> {
+export async function sendQqMessages(context: QqSendContext, { conversation, messages, signal }: QqMessagesRequest): Promise<unknown> {
   const kind = qqOutboundKind(conversation);
+  const execution = { ...context, operation: createEndpointOperation({ signal }) };
   let result: unknown;
-  for (const message of messages) result = await sendOne(context, kind, conversation.id, message);
+  for (const message of messages) result = await sendOne(execution, { kind, id: conversation.id, message });
   return result;
 }

package/src/webhook.ts

@@ -3,7 +3,7 @@
  */
 import path from 'node:path';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { Bot, ReceiverMode, type Sendable } from 'qq-official-bot';
+import { Bot, ReceiverMode } from 'qq-official-bot';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { ResolvedQqHttpConfig } from './protocol.js';
@@ -11,11 +11,7 @@ import type { QqBotTransport } from './ws.js';
 
 const logger = getLogger('qq');
 
-export type QqHttpBotTransport = QqBotTransport & {
-  middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
-};
-
-export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+export type QqHttpBotTransport = Bot<ReceiverMode.MIDDLEWARE, 'koa'>;
 
 export interface QqWebhookHandler {
   readonly config: ResolvedQqHttpConfig;
@@ -53,6 +49,7 @@ export async function handleQqWebhookRequest(
       req: request,
       res: response,
       request: { body: undefined },
+      response: {},
     }, async () => undefined);
   } catch (error) {
     logger.error('QQ webhook error:', error);
@@ -78,55 +75,8 @@ export async function readRequestBodyText(request: IncomingMessage): Promise<str
   return Buffer.concat(chunks).toString('utf8');
 }
 
-export function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport {
-  const bot = new Bot({
-    appid: config.appid,
-    secret: config.secret,
-    mode: ReceiverMode.MIDDLEWARE,
-    platform: 'koa',
-    sandbox: config.sandbox,
-    dataDir: path.join(process.cwd(), 'data', 'qq'),
-    // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
-    logLevel: 'off',
-  } as never) as Bot<ReceiverMode.MIDDLEWARE, 'koa'> & QqBotTransport;
-
-  return {
-    api: bot,
-    start: () => bot.start().then(() => undefined),
-    stop: () => bot.stop().then(() => undefined),
-    on: (event, listener) => {
-      bot.on(event as never, listener as never);
-    },
-    removeAllListeners: () => {
-      bot.removeAllListeners(undefined as never);
-    },
-    sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message as Sendable, source, options),
-    sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message as Sendable, source, options),
-    sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message as Sendable, source, options),
-    sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message as Sendable, source, options),
-    recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
-    recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
-    recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
-    recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
-    getGuilds: () => bot.guildService.getList(),
-    getChannels: (guildId) => bot.channelService.getList(guildId),
-    getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
-    getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
-    getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
-    createGuildRole: (guildId, name, color) =>
-      bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
-    addMemberRole: async (guildId, channelId, userId, roleId) => {
-      await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
-      return true;
-    },
-    removeMemberRole: async (guildId, channelId, userId, roleId) => {
-      await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
-      return true;
-    },
-    approveGroupJoinRequest: (groupId, userId, options) =>
-      (bot as { approveGroupJoinRequest?: QqBotTransport['approveGroupJoinRequest'] })
-        .approveGroupJoinRequest?.(groupId, userId, options)
-      ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
-    middleware: (ctx, next) => bot.middleware(ctx as never, next as never),
-  };
+export function qqHttpBotOptions(config: ResolvedQqHttpConfig): ConstructorParameters<typeof Bot<ReceiverMode.MIDDLEWARE, 'koa'>>[0] {
+  return { handleProcessErrors: false, appid: config.appid, secret: config.secret,
+    mode: ReceiverMode.MIDDLEWARE, platform: 'koa', sandbox: config.sandbox,
+    dataDir: path.join(process.cwd(), 'data', 'qq'), logLevel: 'off' };
 }