@zhin.js/adapter-qq 1.1.17 → 1.1.18

package/src/endpoint.ts

@@ -3,18 +3,27 @@ import { projectQqGuildSenderRoles } from './platform-permit.js';
 import { qqDeliveryFailure } from './delivery-error.js';
 import { normalizeQqInteraction } from './interaction.js';
 import { awaitQqStartup } from './start-deadline.js';
-import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, type MessageRef } from '@zhin.js/im-contract';
+import {
+  inspectQqGroupMember,
+  inspectQqGroupMemberProfile,
+  inspectQqGroupScene,
+  kickQqGroupMember,
+  moderateQqGroupMember,
+  muteQqGroupMember,
+  qqGroupService,
+} from './group-admin.js';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
 import {
   Endpoint, createEndpointLifecycle, type EndpointLifecycle,
-  createRecallEndpointControl,
   type EndpointControl,
   type EndpointChannel,
   type EndpointManagement,
   type EndpointSendRequest,
   type EndpointTransportState,
+  type AdapterOutageNotifier,
 } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
@@ -59,6 +68,8 @@ export interface QqEndpointOptions {
   readonly id: CapabilityId;
   readonly config: ResolvedQqWebsocketConfig;
   readonly createBot?: CreateQqBot;
+  /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+  readonly notifier?: AdapterOutageNotifier;
 }
 
 export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
@@ -68,14 +79,15 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   readonly #createBot: CreateQqBot;
   #bot: QqBotTransport | null = null;
   #open = false;
+  #offlineNoticeAt = 0;
   readonly #seenInteractions = new Map<string, number>();
   /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
   readonly #passiveReplies = new QqPassiveReplyLedger();
   readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
-  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
+  readonly control: EndpointControl = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
 
   constructor(options: QqEndpointOptions) {
     super();
@@ -121,7 +133,12 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
       this.#cleanup = cleanup;
       handle.onForceClose(() => { void cleanup(); });
       try {
-        bot.on('transport.close', () => { if (cancelled || this.#bot !== bot) return; void cleanup(); handle.notifyClosed(); });
+        bot.on('transport.close', () => {
+          if (cancelled || this.#bot !== bot) return;
+          this.#notifyOffline('transport_close');
+          void cleanup();
+          handle.notifyClosed();
+        });
         this.#bindBot(bot);
         await awaitQqStartup(bot.start().then(async () => {
           if (cancelled) await stopBot();
@@ -134,11 +151,13 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
           await stopping;
           return;
         }
+        this.#offlineNoticeAt = 0;
         this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
       } catch (error) {
         const wasCancelled = cancelled;
         await cleanup();
         if (wasCancelled) return;
+        this.#notifyOffline('start_failed');
         const raw = error instanceof Error ? error.message : String(error);
         throw new Error(
           `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
@@ -273,6 +292,24 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     return true;
   }
 
+  #notifyOffline(reason: string): void {
+    const notifier = this.#options.notifier;
+    if (!notifier?.configured) return;
+    const now = Date.now();
+    if (now - this.#offlineNoticeAt < 60_000) return;
+    this.#offlineNoticeAt = now;
+    const text = `[Zhin] QQ 机器人 ${this.#options.config.id} 掉线（${reason}）。正在自动重连。\n`
+      + '恢复：在 QQ 回复 `qq endpoint add` 重新扫码绑定，或打开 Console 的 QQ 页面。';
+    void notifier.send(text).then((sent) => {
+      if (sent) return;
+      this.#logger.warn(formatCompact({
+        op: 'qq_notify_failed',
+        endpoint: this.#options.config.id,
+        reason,
+      }));
+    });
+  }
+
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
       if (this.#bot !== bot) return;
@@ -316,6 +353,8 @@ export interface QqHttpEndpointOptions {
   readonly http: HttpHost;
   readonly config: ResolvedQqHttpConfig;
   readonly createBot?: CreateQqHttpBot;
+  /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+  readonly notifier?: AdapterOutageNotifier;
 }
 
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
@@ -326,14 +365,15 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   readonly #createBot: CreateQqHttpBot;
   #bot: QqHttpBotTransport | null = null;
   #open = false;
+  #offlineNoticeAt = 0;
   readonly #seenInteractions = new Map<string, number>();
   /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
   readonly #passiveReplies = new QqPassiveReplyLedger();
   readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
-  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot(), () => this.#open && this.#bot !== null);
+  readonly control: EndpointControl = createQqEndpointControl(() => this.#requireBot(), (id) => this.recallMessage(id));
 
   constructor(options: QqHttpEndpointOptions) {
     super();
@@ -396,11 +436,13 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
           await stopping;
           return;
         }
+        this.#offlineNoticeAt = 0;
         this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
       } catch (error) {
         const wasCancelled = cancelled;
         await cleanup();
         if (wasCancelled) return;
+        this.#notifyOffline('start_failed');
         throw error;
       }
     });
@@ -530,6 +572,24 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     return true;
   }
 
+  #notifyOffline(reason: string): void {
+    const notifier = this.#options.notifier;
+    if (!notifier?.configured) return;
+    const now = Date.now();
+    if (now - this.#offlineNoticeAt < 60_000) return;
+    this.#offlineNoticeAt = now;
+    const text = `[Zhin] QQ 机器人 ${this.#options.config.id} 掉线（${reason}）。正在自动重连。\n`
+      + '恢复：在 QQ 回复 `qq endpoint add` 重新扫码绑定，或打开 Console 的 QQ 页面。';
+    void notifier.send(text).then((sent) => {
+      if (sent) return;
+      this.#logger.warn(formatCompact({
+        op: 'qq_notify_failed',
+        endpoint: this.#options.config.id,
+        reason,
+      }));
+    });
+  }
+
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
       if (this.#bot !== bot) return;
@@ -569,9 +629,25 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
 }
 
 function createQqEndpointManagement(
-  requireClient: () => Pick<QqBotTransport, 'getGuilds' | 'getChannels'>,
+  requireClient: () => Pick<QqBotTransport, 'getGuilds' | 'getChannels' | 'api'>,
+  isActive: () => boolean,
 ): EndpointManagement {
+  const api = () => requireClient().api;
   return Object.freeze<EndpointManagement>({
+    // QQ 群（group_openid / member_openid）：官方 v2 群管理接口，部分为白名单能力（11253）。
+    inspectGroupMember: (group, user, signal) => inspectQqGroupMember(api(), group, user, signal),
+    inspectGroupScene: (group, signal) => inspectQqGroupScene(api(), group, signal),
+    inspectGroupMemberProfile: (group, user, signal) => inspectQqGroupMemberProfile(api(), group, user, signal),
+    moderateGroupMember: (group, user, action, signal) => moderateQqGroupMember(api(), group, user, action, signal, isActive),
+    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
+      return qqGroupService(api()).getMembers(groupId);
+    },
+    async kickGroupMember(groupId: string, userId: string): Promise<void> {
+      await kickQqGroupMember(api(), groupId, userId);
+    },
+    async muteGroupMember(groupId: string, userId: string, durationSeconds: number): Promise<void> {
+      await muteQqGroupMember(api(), groupId, userId, durationSeconds);
+    },
     async listChannels(): Promise<readonly EndpointChannel[]> {
       const channels: EndpointChannel[] = [];
       const client = requireClient();
@@ -604,6 +680,59 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
+/**
+ * Recall + 频道表情回应。recall 同时接受 send() 的复合 ID 与入站原生消息 ID（目标取自 MessageRef.conversation），
+ * 因此群管理员机器人可撤回普通成员 2 分钟内的消息（官方限制由平台执行）。
+ * 表情回应只有频道子频道消息支持（官方无群 / 单聊表情回应接口）。
+ */
+function createQqEndpointControl(
+  requireBot: () => QqBotTransport,
+  recallById: (messageId: string) => Promise<void>,
+): EndpointControl {
+  return Object.freeze<EndpointControl>({
+    recall: async (message: MessageRef) => {
+      if (isCompoundMessageId(message.id)) return recallById(message.id);
+      const kind = qqOutboundKind(message.conversation);
+      await recallQqMessage(requireBot(), kind, message.conversation.id, message.id);
+    },
+    addReaction: async (message: MessageRef, emoji: string) => {
+      const target = qqGuildReactionTarget(message, emoji);
+      if (!target) return null;
+      await requireBot().api.reactionService.addGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+      return `${target.type}:${target.id}`;
+    },
+    removeReaction: async (message: MessageRef, reactionId: string) => {
+      const target = qqGuildReactionTarget(message, reactionId);
+      if (!target) return;
+      await requireBot().api.reactionService.deleteGuildMessageReaction(target.channelId, target.messageId, target.type, target.id);
+    },
+  });
+}
+
+function isCompoundMessageId(id: string): boolean {
+  try { parseCompoundMessageId(id); return true; } catch { return false; }
+}
+
+/** `type:id`（1 系统表情 / 2 emoji）或单个 Unicode emoji（→ type 2 + 码点）。 */
+export function parseQqEmoji(value: string): { type: 1 | 2; id: `${number}` } | null {
+  const explicit = /^([12]):(\d+)$/.exec(value.trim());
+  if (explicit) return { type: Number(explicit[1]) as 1 | 2, id: explicit[2] as `${number}` };
+  const chars = [...value.trim().replace(/\uFE0F/g, '')];
+  if (chars.length !== 1) return null;
+  const code = chars[0]!.codePointAt(0)!;
+  return code > 0x7f ? { type: 2, id: String(code) as `${number}` } : null;
+}
+
+function qqGuildReactionTarget(message: MessageRef, emoji: string) {
+  let kind = qqOutboundKind(message.conversation);
+  let channelId = message.conversation.id;
+  let messageId = message.id;
+  if (isCompoundMessageId(message.id)) ({ kind, channelId, qqMsgId: messageId } = parseCompoundMessageId(message.id));
+  if (kind !== 'channel' || !channelId || !messageId) return null;
+  const parsed = parseQqEmoji(emoji);
+  return parsed ? { channelId, messageId, ...parsed } : null;
+}
+
 async function recallQqMessage(bot: QqBotTransport, kind: ReturnType<typeof qqOutboundKind>, channelId: string, messageId: string): Promise<void> {
   const recall = { private: bot.recallPrivateMessage, group: bot.recallGroupMessage,
     channel: bot.recallGuildMessage, direct: bot.recallDirectMessage }[kind];

package/src/group-admin.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 type {
+  GroupMemberProfile,
+  GroupModerationAction,
+  GroupModerationMember,
+  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: string): Promise<GroupBotState> {
+  return 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'));
+}
+
+/** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
+export async function muteQqGroupMember(
+  api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, durationSeconds: number,
+): 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
+    ? { 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: string, userId: string, addToBlacklist = false,
+): Promise<{ blacklistFailed: boolean }> {
+  const member = requireId(userId, 'member id');
+  const result = await 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,
+): Promise<GroupModerationMember> {
+  signal.throwIfAborted();
+  const [self, member] = await Promise.all([qqGroupBotState(api, groupId), qqGroupMember(api, groupId, userId)]);
+  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: Partial<QqOfficialApi> | undefined, groupId: string, userId: string,
+  action: GroupModerationAction, signal: AbortSignal, isActive: () => boolean,
+): Promise<void> {
+  const member = await inspectQqGroupMember(api, groupId, userId, 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);
+    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));
+}
+
+/** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
+export async function inspectQqGroupScene(
+  api: Partial<QqOfficialApi> | undefined, groupId: string, signal: AbortSignal,
+): Promise<GroupSceneFacts> {
+  signal.throwIfAborted();
+  const info = await 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: string, userId: string, signal: AbortSignal,
+): Promise<GroupMemberProfile> {
+  signal.throwIfAborted();
+  const member = await qqGroupMember(api, groupId, userId);
+  signal.throwIfAborted();
+  if (member.member_openid !== userId) return {};
+  const role = platformRole(member.member_role);
+  return role ? { platformRole: role } : {};
+}

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;
@@ -83,6 +88,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 +101,7 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
       secret,
       webhookPath,
       sandbox: config.sandbox === true,
+      ...(notify ? { notify } : {}),
     };
   }
 
@@ -114,6 +121,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,18 @@
+/**
+ * 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: [] 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,124 @@
+/**
+ * QQ Console 扫码绑定：把原本只能在聊天里执行的 `qq endpoint add` 流程
+ * 搬到 Console 页面。
+ *
+ * - `start` 返回扫码链接；后续状态写入 `state.consoleBind`，页面轮询 status。
+ * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再一次性写 `.env` + 配置。
+ * - 与聊天命令共享 `state.bindFlow` 单例，同一时间只允许一个绑定流程。
+ */
+import { PluginConsoleRpcError } from 'zhin.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { writeQqEndpointWithBotKind, type QqEndpointWriteResult } 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(
+  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,
+  store: EndpointConfigurationStore,
+  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 }, store);
+    state.consoleBind = null;
+    return result;
+  } catch {
+    throw new PluginConsoleRpcError('unavailable', '写入配置失败，请检查配置文件和 .env 的权限');
+  }
+}
+
+/** 取消 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;
+  return active;
+}

package/src/qq-endpoint-write.ts

@@ -0,0 +1,52 @@
+/**
+ * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
+ * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
+ *
+ * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
+ */
+import { buildEndpointEnvKey, type EndpointConfigurationStore } from 'zhin.js/adapter';
+import { defaultQqEndpointIntentFields, type QqBotKind } from './qq-intents.js';
+
+export interface QqEndpointWriteInput {
+  readonly endpointId: string;
+  readonly appId: string;
+  readonly appSecret: string;
+  readonly botKind: QqBotKind;
+}
+
+export interface QqEndpointWriteResult {
+  readonly filePath: string;
+  readonly endpointId: string;
+  readonly botKind: QqBotKind;
+  readonly intents: readonly string[];
+}
+
+/** 写回 `.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,
+  };
+}