@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/src/group-admin.ts

@@ -0,0 +1,155 @@
+/**
+ * QQ 群（group_openid / member_openid）管理：只走官方 v2 群管理接口。
+ *
+ * 官方限制（https://bot.q.qq.com/wiki/develop/api-v2/autogen/）：
+ * - 成员列表 / 成员信息 / 批量移除 / 黑名单 / 入群申请多为白名单能力，无权限返回 11253；
+ * - 禁言与入群审批要求机器人是群管理员；禁言最长 30 天，只能禁言普通成员；
+ * - 没有「机器人所在群列表」「好友列表」「退群」「设管理员」「群公告」等接口。
+ */
+import type {
+  GroupBotState,
+  GroupMemberInfo,
+  GroupMemberRole,
+} from 'qq-official-bot';
+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';
+
+/** 官方 restrict_chat_setting 上限：30 天。 */
+export const QQ_GROUP_MUTE_MAX_SECONDS = 30 * 24 * 60 * 60;
+
+export type QqGroupService = QqOfficialApi['groupService'];
+
+export function qqGroupService(api: Partial<QqOfficialApi> | undefined): QqGroupService {
+  const service = api?.groupService;
+  if (!service) throw new Error('QQ group management API is unavailable on this transport');
+  return service;
+}
+
+export function isQqGroupManagerRole(role: unknown): role is 'owner' | 'admin' {
+  return role === 'owner' || role === 'admin';
+}
+
+function platformRole(role: unknown): GroupMemberRole | undefined {
+  return role === 'owner' || role === 'admin' || role === 'member' ? role : undefined;
+}
+
+function requireId(value: string, what: string): string {
+  const id = typeof value === 'string' ? value.trim() : '';
+  if (!id || /[\s/?#]/.test(id)) throw new Error(`Invalid QQ ${what}`);
+  return id;
+}
+
+/** RFC3339 → epoch ms；非法或未来时间返回 undefined（从不猜测）。 */
+export function parseQqTime(value: unknown, { allowFuture = false } = {}): number | undefined {
+  if (typeof value !== 'string' || !value) return undefined;
+  const at = Date.parse(value);
+  if (!Number.isFinite(at) || at <= 0) return undefined;
+  if (!allowFuture && at > Date.now()) return undefined;
+  return at;
+}
+
+/** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
+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, 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, 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 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() }]));
+}
+
+/** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
+export async function kickQqGroupMember(
+  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 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, userId, signal }: EndpointMemberInspectionRequest,
+): Promise<GroupModerationMember> {
+  signal.throwIfAborted();
+  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);
+  return {
+    canModerate: isQqGroupManagerRole(self.member_role) && self.member_openid !== userId
+      && member.member_openid === userId && role === 'member' && member.bot !== true,
+    ...(role ? { platformRole: role } : {}),
+    ...(joinedAt ? { joinedAt } : {}),
+  };
+}
+
+export async function moderateQqGroupMember(
+  { api, isActive }: { readonly api: Partial<QqOfficialApi> | undefined; readonly isActive: () => boolean },
+  { groupId, userId, action, signal }: EndpointModerationRequest,
+): Promise<void> {
+  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') {
+    if (!Number.isSafeInteger(action.maxMembershipAgeMs) || action.maxMembershipAgeMs <= 0
+      || !member.joinedAt || member.joinedAt !== action.joinedAt
+      || Date.now() - member.joinedAt > action.maxMembershipAgeMs) {
+      throw new Error('Group membership no longer matches the approved newcomer window');
+    }
+    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: 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, signal }: EndpointGroupInspectionRequest,
+): Promise<GroupSceneFacts> {
+  signal.throwIfAborted();
+  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;
+  const memberCount = Number.isSafeInteger(info?.group_member_num) && info.group_member_num > 0 ? info.group_member_num : undefined;
+  return { ...(name ? { name } : {}), ...(memberCount ? { memberCount } : {}) };
+}
+
+/** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
+export async function inspectQqGroupMemberProfile(
+  api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberInspectionRequest,
+): Promise<GroupMemberProfile> {
+  signal.throwIfAborted();
+  const member = await qqGroupMember(api, { groupId, userId, signal });
+  signal.throwIfAborted();
+  if (member.member_openid !== userId) return {};
+  const role = platformRole(member.member_role);
+  return role ? { platformRole: 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

@@ -3,6 +3,7 @@
 import { EndpointDeliveryError, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { resolveQqIntents } from './qq-intents.js';
+import { resolveAdapterNotifyTarget, type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
 
 const logger = getLogger('qq');
 
@@ -22,6 +23,8 @@ export interface QqEndpointConfig {
   readonly gatewayUrl?: string;
   readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
   readonly webhookPath?: string;
+  /** Optional out-of-band outage notification target (usually an ICQQ instance). */
+  readonly notify?: AdapterNotifyTarget;
 }
 
 export interface ResolvedQqWebsocketConfig {
@@ -35,6 +38,7 @@ export interface ResolvedQqWebsocketConfig {
   readonly accessTokenUrl?: string;
   readonly gatewayUrl?: string;
   readonly streamProxy?: import('./stream-proxy.js').QqStreamProxy;
+  readonly notify?: ResolvedAdapterNotifyTarget;
 }
 
 export interface ResolvedQqHttpConfig {
@@ -45,6 +49,7 @@ export interface ResolvedQqHttpConfig {
   readonly secret: string;
   readonly webhookPath: string;
   readonly sandbox: boolean;
+  readonly notify?: ResolvedAdapterNotifyTarget;
 }
 
 export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
@@ -52,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;
@@ -83,6 +90,7 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
   const appid = requiredEndpointField(config.appid, 'appid');
   const secret = requiredEndpointField(config.secret, 'secret');
   const mode = config.mode ?? 'websocket';
+  const notify = resolveAdapterNotifyTarget(config.notify);
 
   if (mode === 'webhook' || mode === 'middleware') {
     const webhookPathRaw = config.webhookPath ?? '/qq/webhook';
@@ -95,6 +103,7 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
       secret,
       webhookPath,
       sandbox: config.sandbox === true,
+      ...(notify ? { notify } : {}),
     };
   }
 
@@ -114,6 +123,7 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
     accessTokenUrl: config.accessTokenUrl,
     gatewayUrl: config.gatewayUrl,
     ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
+    ...(notify ? { notify } : {}),
   };
 }
 

package/src/qq-console-spec.ts

@@ -0,0 +1,29 @@
+/**
+ * QQ Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ *
+ * QQ 的 endpoint 不走通用「字段表单」：`qq endpoint add` 是扫码绑定流程，
+ * 因此 `canAdd: false`，改由 `qq-console.ts` 的 `qq-bind-*` 动作完成。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const qqConsoleSpec = {
+  adapterKey: 'qq',
+  adapterDisplayName: 'QQ',
+  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',
+  readPermission: 'qq:read',
+  writePermission: 'qq:write',
+} as const;

package/src/qq-console.ts

@@ -0,0 +1,130 @@
+/**
+ * QQ Console 扫码绑定：把原本只能在聊天里执行的 `qq endpoint add` 流程
+ * 搬到 Console 页面。
+ *
+ * - `start` 返回扫码链接；后续状态写入 `state.consoleBind`，页面轮询 status。
+ * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再通过捕获的所属 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, type QqEndpointSavePort } from './qq-endpoint-write.js';
+import { parseQqBotKind } from './qq-intents.js';
+import type { QqRuntimeState } from './qq-runtime-state.js';
+
+/** 启动 Console 扫码；resolve 时二维码链接已就绪。 */
+export function startQqConsoleBind(
+  state: QqRuntimeState,
+  id?: string,
+): Promise<{ readonly url: string }> {
+  if (state.bindFlow || state.pendingBotKind) {
+    throw new PluginConsoleRpcError('conflict', '已有扫码绑定流程在进行，请先完成或取消');
+  }
+  if (state.consoleBind?.pending) {
+    throw new PluginConsoleRpcError('conflict', '已经扫码成功，请先选择公域或私域');
+  }
+  const endpointId = id?.trim() || undefined;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const stop = startQqBindFlow({
+      onQrDisplayed: (url) => {
+        state.consoleBind = {
+          state: 'waiting',
+          url,
+          message: '请用手机 QQ 扫码',
+          startedAt: state.consoleBind?.startedAt ?? Date.now(),
+        };
+        if (settled) return;
+        settled = true;
+        resolve({ url });
+      },
+      onQrExpired: () => {
+        state.consoleBind = {
+          state: 'waiting',
+          ...(state.consoleBind?.url ? { url: state.consoleBind.url } : {}),
+          message: '二维码已过期，正在刷新…',
+          startedAt: state.consoleBind?.startedAt ?? Date.now(),
+        };
+      },
+      onSuccess: (credentials) => {
+        state.bindFlow = null;
+        const [first] = credentials;
+        if (!first) {
+          state.consoleBind = {
+            state: 'failed',
+            error: '扫码结果为空，请重新扫码',
+            startedAt: state.consoleBind?.startedAt ?? Date.now(),
+          };
+          return;
+        }
+        state.consoleBind = {
+          state: 'scanned',
+          ...(state.consoleBind?.url ? { url: state.consoleBind.url } : {}),
+          message: '已扫码，请选择公域或私域',
+          startedAt: state.consoleBind?.startedAt ?? Date.now(),
+          pending: {
+            endpointId: endpointId ?? first.appId,
+            appId: first.appId,
+            appSecret: first.appSecret,
+          },
+        };
+      },
+      onFailure: (error) => {
+        state.bindFlow = null;
+        state.consoleBind = {
+          state: 'failed',
+          error: error.message,
+          startedAt: state.consoleBind?.startedAt ?? Date.now(),
+        };
+        if (settled) return;
+        settled = true;
+        reject(new PluginConsoleRpcError('unavailable', error.message));
+      },
+    }, { source: 'zhin' });
+    state.bindFlow = { id: endpointId, stop, locale: 'zh-CN' };
+  });
+}
+
+/** 扫码成功后选择公域 / 私域并保存未启动账号。 */
+export async function completeQqConsoleBind(
+  state: QqRuntimeState,
+  save: QqEndpointSavePort,
+  kindValue: unknown,
+): Promise<QqEndpointWriteResult> {
+  const pending = state.consoleBind?.pending;
+  if (!pending) {
+    throw new PluginConsoleRpcError('conflict', '还没有扫码成功，请先扫码绑定');
+  }
+  const botKind = parseQqBotKind(kindValue);
+  if (!botKind) {
+    throw new PluginConsoleRpcError('invalid_input', '请选择公域（public）或私域（private）');
+  }
+  try {
+    const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, save);
+    state.consoleBind = null;
+    state.consoleAdmission = null;
+    return result;
+  } 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', '账号配置未能保存，请刷新状态');
+  }
+}
+
+/** 取消 Console 绑定（也可用于收拾聊天命令发起的流程）。 */
+export function cancelQqConsoleBind(state: QqRuntimeState): boolean {
+  const active = Boolean(state.bindFlow || state.pendingBotKind || state.consoleBind);
+  try {
+    state.bindFlow?.stop();
+  } catch {
+    // best effort
+  }
+  state.bindFlow = null;
+  state.pendingBotKind = null;
+  state.consoleBind = null;
+  state.consoleAdmission = null;
+  return active;
+}

package/src/qq-endpoint-write.ts

@@ -0,0 +1,24 @@
+/** 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;
+  readonly appId: string;
+  readonly appSecret: string;
+  readonly botKind: QqBotKind;
+}
+export type QqEndpointSavePort = (configuration: QqEndpointConfig) => Promise<AdapterMutationResult>;
+export interface QqEndpointWriteResult {
+  readonly endpointId: string;
+  readonly botKind: QqBotKind;
+  readonly intents: readonly string[];
+  readonly mutation: AdapterMutationResult;
+}
+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;
@@ -34,24 +29,45 @@ export interface QqPendingBotKind {
   readonly commandHeads?: readonly string[];
 }
 
+/**
+ * Console 发起的扫码绑定进度。凭据（appSecret）只留在内存，
+ * status 只暴露状态、扫码链接与目标 endpoint id。
+ */
+export interface QqConsoleBindState {
+  readonly state: 'waiting' | 'scanned' | 'failed';
+  readonly url?: string;
+  readonly message?: string;
+  readonly error?: string;
+  readonly startedAt: number;
+  /** 扫码成功后暂存，确认公域/私域后写配置。 */
+  readonly pending?: {
+    readonly endpointId: string;
+    readonly appId: string;
+    readonly appSecret: string;
+  };
+}
+
 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 共享同一插件瞬态流程）。 */
+  consoleBind: QqConsoleBindState | null;
 }
 
 export function createQqRuntimeState(): QqRuntimeState {
   return {
-    endpoints: new Map(),
+    consoleAdmission: null,
     bindFlow: null,
     pendingBotKind: null,
+    consoleBind: null,
   };
 }
 
 export const qqRuntimeStateToken = createToken<QqRuntimeState>(
   'zhin.qq.runtime-state',
-  'QQ adapter runtime state (running endpoints + bind flow singleton)',
+  'QQ transient QR binding state',
 );