@zhin.js/adapter-qq 1.0.83 → 1.1.0

package/src/platform-permit.ts

@@ -0,0 +1,56 @@
+/**
+ * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
+ */
+import type { PermissionSubject } from '@zhin.js/permission';
+
+const ADAPTER = 'qq';
+
+export function platformPermit(perm: string): string {
+  return `platform(${ADAPTER},${perm})`;
+}
+
+/** 官方频道工厂工具：映射到 guild 语义，不用 group_* */
+const FACTORY_PERM_MAP: Record<string, string> = {
+  scene_admin: 'guild_admin',
+  scene_owner: 'guild_owner',
+};
+
+export function qqGuildPermitResolver(logicalPerm: string): string {
+  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+
+export function normalizeQqGuildSenderForPermit(input: {
+  roles?: string[];
+  isOwner?: boolean;
+  isAdmin?: boolean;
+}): { role?: string; permissions?: string[] } {
+  const permissions = [...(input.roles ?? [])];
+  if (input.isOwner) {
+    permissions.push('guild_owner', 'guild_admin');
+    return { role: 'owner', permissions };
+  }
+  if (input.isAdmin) {
+    permissions.push('guild_admin');
+    return { role: 'admin', permissions };
+  }
+  return { role: 'member', permissions };
+}
+
+export function checkQqPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
+  const has = (t: string) => permissions.includes(t);
+
+  switch (perm) {
+    case 'guild_owner':
+      return role === 'owner' || has('guild_owner');
+    case 'guild_admin':
+      return role === 'owner' || role === 'admin' || has('guild_admin') || has('guild_owner');
+    case 'manage_roles':
+      return role === 'owner' || has('guild_owner') || has('manage_roles');
+    case 'manage_channels':
+      return role === 'owner' || role === 'admin' || has('guild_owner') || has('guild_admin') || has('manage_channels');
+    default:
+      return false;
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,273 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { pickCredential } from 'zhin.js/adapter';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { resolveQqIntents } from './qq-intents.js';
+
+const logger = getLogger('qq');
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+  readonly id?: string;
+  readonly appid?: string;
+  readonly secret?: string;
+  /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+  readonly mode?: 'websocket' | 'webhook' | 'middleware';
+  readonly sandbox?: boolean;
+  /** Explicit intents; when omitted, derived from `botKind` (default public). */
+  readonly intents?: readonly string[];
+  /** public | private — drives default intents when `intents` omitted. */
+  readonly botKind?: string;
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+  readonly webhookPath?: string;
+  readonly port?: number;
+  readonly path?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly id?: string;
+    readonly appid?: string;
+    readonly secret?: string;
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    readonly intents?: readonly string[];
+    readonly botKind?: string;
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+    readonly port?: number;
+    readonly path?: string;
+  }>;
+}
+
+export interface ResolvedQqWebsocketConfig {
+  readonly context: 'qq';
+  readonly mode: 'websocket';
+  readonly id: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly sandbox: boolean;
+  readonly intents?: readonly string[];
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+}
+
+export interface ResolvedQqHttpConfig {
+  readonly context: 'qq';
+  readonly mode: 'webhook' | 'middleware';
+  readonly id: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly webhookPath: string;
+  readonly sandbox: boolean;
+}
+
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+
+export interface QqInboundMessage {
+  readonly id: string;
+  readonly content: string;
+  readonly channelKind: QqChannelKind;
+  readonly channelId: string;
+  readonly authorId: string;
+  readonly authorName: string;
+  readonly authorRoles?: string[];
+  readonly timestamp: number;
+  readonly guildId?: string;
+  readonly rawMessage?: string;
+  /** canonical 入站段（text/mention/face/image/audio/video/file/reply），与 content 同源 */
+  readonly segments?: readonly import('@zhin.js/core').Segment[];
+  /**
+   * 入站是否 @ 当前机器人：统一按 mentions 判定。群场景只认 is_you（@ 另一个
+   * 机器人时 bot:true 但无 is_you，不误判）；bot 回退仅限频道 AT 事件。
+   * 群 GROUP_MESSAGE_CREATE 的非 @ 消息不置位。新 Runtime 纯文本 content 需经
+   * metadata 传递。
+   */
+  readonly mentioned?: boolean;
+}
+
+export interface QqWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export function resolveQqConfig(config: QqAdapterConfig = {}): ResolvedQqConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+  const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+  const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+  if (!appid || !secret) {
+    throw new TypeError(
+      'QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)',
+    );
+  }
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
+    || process.env.QQ_BOT_NAME
+    || 'qq-bot';
+  const mode = config.mode ?? entry?.mode ?? 'websocket';
+
+  if (mode === 'webhook' || mode === 'middleware') {
+    const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+    const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+    return {
+      context: 'qq',
+      mode,
+      id,
+      appid,
+      secret,
+      webhookPath,
+      sandbox: config.sandbox === true || entry?.sandbox === true,
+    };
+  }
+
+  return {
+    context: 'qq',
+    mode: 'websocket',
+    id,
+    appid,
+    secret,
+    sandbox: config.sandbox === true || entry?.sandbox === true,
+    intents: resolveQqIntents({
+      intents: config.intents ?? entry?.intents,
+      botKind: config.botKind ?? entry?.botKind,
+    }),
+    accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+    gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+  };
+}
+
+/**
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
+ */
+export function qqInboundConversation(endpointKey: string, msg: QqInboundMessage): ConversationRef {
+  const kind: ConversationKind = msg.channelKind === 'direct' ? 'private' : msg.channelKind;
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind,
+    id: msg.channelId,
+    ...(msg.guildId && (msg.channelKind === 'channel' || msg.channelKind === 'direct')
+      ? { parent: { kind: 'channel' as const, id: msg.guildId } }
+      : {}),
+  };
+}
+
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export function qqOutboundKind(conversation: ConversationRef): QqChannelKind {
+  if (conversation.kind === 'private' && conversation.parent?.kind === 'channel') return 'direct';
+  return conversation.kind;
+}
+
+export function senderDisplayName(msg: QqInboundMessage): string {
+  return msg.authorName || msg.authorId;
+}
+
+export function formatInboundContent(msg: QqInboundMessage): string {
+  const text = (msg.content || msg.rawMessage || '').trim();
+  return text || '(Empty message)';
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload: unknown): string {
+  if (typeof payload === 'string') return payload;
+
+  const segments: Array<string | QqWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | QqWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as QqWireSegment]
+      : [];
+
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  return segments
+    .map((item) => {
+      if (typeof item === 'string') return item;
+      const data = item.data ?? {};
+      switch (item.type) {
+        case 'text':
+          return String(data.text ?? data.content ?? '');
+        case 'at': {
+          const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+          return id ? `<@!${id}>` : '';
+        }
+        case 'image': {
+          const src = String(data.url || data.file || '');
+          // base64/本地路径由 formatOutbound 走媒体上传，文本视图静默省略；
+          // 仅当彻底缺少来源时留痕，避免出站静默降级排障无头绪。
+          if (!src) {
+            logger.warn(formatCompact({
+              op: 'qq_outbound_image_dropped',
+              reason: 'missing_source',
+            }));
+            return '';
+          }
+          return /^https?:\/\//.test(src) ? src : '';
+        }
+        case 'reply':
+          return '';
+        default:
+          return data.text != null ? String(data.text) : '';
+      }
+    })
+    .filter(Boolean)
+    .join('');
+}
+
+/**
+ * Parse a compound messageId produced by `send()`: `kind-channelId:qqMsgId`.
+ */
+export function parseCompoundMessageId(messageId: string): {
+  kind: QqChannelKind;
+  channelId: string;
+  qqMsgId: string;
+} {
+  const hyphen = messageId.indexOf('-');
+  if (hyphen <= 0) throw new Error(`invalid QQ messageId format: ${messageId}`);
+  const kind = messageId.slice(0, hyphen);
+  if (kind !== 'private' && kind !== 'group' && kind !== 'channel' && kind !== 'direct') {
+    throw new Error(`invalid QQ messageId kind: ${kind}`);
+  }
+  const rest = messageId.slice(hyphen + 1);
+  const colon = rest.indexOf(':');
+  if (colon <= 0) throw new Error(`invalid QQ messageId format: ${messageId}`);
+  return { kind, channelId: rest.slice(0, colon), qqMsgId: rest.slice(colon + 1) };
+}
+
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result: unknown): string {
+  if (!result || typeof result !== 'object') {
+    throw new Error('QQ 发送消息失败：响应为空');
+  }
+  const row = result as Record<string, unknown>;
+  const nested = row.data && typeof row.data === 'object'
+    ? row.data as Record<string, unknown>
+    : undefined;
+  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
+  const id = row.id ?? row.message_id ?? audit?.audit_id;
+  if (id == null || id === '') {
+    const code = row.code;
+    const msg = row.message;
+    throw new Error(
+      code != null
+        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+        : 'QQ 发送消息失败：响应缺少消息 ID',
+    );
+  }
+  return String(id);
+}

package/src/qq-bind-api.ts

@@ -0,0 +1,145 @@
+/**
+ * QQ Bot 扫码绑定协议（内联）
+ * Protocol aligned with @tencent-connect/qqbot-connector@1.1.0 qqbot-session — inlined to avoid runtime dependency.
+ */
+import { createDecipheriv, randomBytes } from 'node:crypto';
+
+export type QQBotEnv = 'production' | 'test';
+
+const HOSTS: Record<QQBotEnv, string> = {
+  production: 'q.qq.com',
+  test: 'test.q.qq.com',
+};
+
+export enum BindStatus {
+  NONE = 0,
+  PENDING = 1,
+  COMPLETED = 2,
+  EXPIRED = 3,
+}
+
+export function getQQBotHost(env: QQBotEnv = 'production'): string {
+  return HOSTS[env];
+}
+
+export function generateBindKey(): string {
+  return randomBytes(32).toString('base64');
+}
+
+export function buildConnectUrl(taskId: string, source = 'zhin'): string {
+  return `https://${getQQBotHost('production')}/qqbot/openclaw/connect.html?task_id=${encodeURIComponent(taskId)}&source=${encodeURIComponent(source)}&_wv=2`;
+}
+
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export function decryptSecret(encryptedBase64: string, keyBase64: string): string {
+  const key = Buffer.from(keyBase64, 'base64');
+  const payload = Buffer.from(encryptedBase64, 'base64');
+  const iv = payload.subarray(0, 12);
+  const authTag = payload.subarray(payload.length - 16);
+  const ciphertext = payload.subarray(12, payload.length - 16);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+
+interface LiteApiResponse<T> {
+  retcode: number;
+  msg?: string;
+  data?: T;
+}
+
+async function postJson<T>(
+  url: string,
+  body: Record<string, unknown>,
+  timeoutMs: number,
+): Promise<LiteApiResponse<T>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} from ${url}`);
+    }
+    return (await res.json()) as LiteApiResponse<T>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface BindTaskResult {
+  taskId: string;
+  key: string;
+}
+
+export async function createBindTask(
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<BindTaskResult> {
+  const url = `https://${getQQBotHost(env)}/lite/create_bind_task`;
+  const key = generateBindKey();
+  const res = await postJson<{ task_id?: string }>(url, { key }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'create_bind_task failed');
+  }
+  if (!res.data?.task_id) {
+    throw new Error('create_bind_task: missing task_id');
+  }
+  return { taskId: res.data.task_id, key };
+}
+
+export interface PollBindResultOk {
+  status: BindStatus;
+  botAppId: string;
+  botEncryptSecret: string;
+  /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+  userOpenId: string;
+}
+
+export function parsePollBindResultData(data: {
+  status?: number;
+  bot_appid?: string | number;
+  bot_encrypt_secret?: string;
+  user_openid?: string;
+  userOpenid?: string;
+  openid?: string;
+} | undefined): PollBindResultOk {
+  return {
+    status: (data?.status ?? BindStatus.NONE) as BindStatus,
+    botAppId: String(data?.bot_appid ?? ''),
+    botEncryptSecret: data?.bot_encrypt_secret ?? '',
+    userOpenId: String(
+      data?.user_openid ?? data?.userOpenid ?? data?.openid ?? '',
+    ),
+  };
+}
+
+export async function pollBindResult(
+  taskId: string,
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<PollBindResultOk> {
+  const url = `https://${getQQBotHost(env)}/lite/poll_bind_result`;
+  const res = await postJson<{
+    status?: number;
+    bot_appid?: string | number;
+    bot_encrypt_secret?: string;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
+  }>(url, { task_id: taskId }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'poll_bind_result failed');
+  }
+  return parsePollBindResultData(res.data);
+}

package/src/qq-bind-flow.ts

@@ -0,0 +1,127 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import {
+  BindStatus,
+  buildConnectUrl,
+  createBindTask,
+  decryptSecret,
+  pollBindResult,
+} from './qq-bind-api.js';
+
+const POLL_INTERVAL_MS = 2000;
+
+export interface QqBindCredentials {
+  appId: string;
+  appSecret: string;
+  userOpenId?: string;
+}
+
+export interface QqBindCallbacks {
+  onSuccess: (credentials: QqBindCredentials[]) => void;
+  onFailure: (error: Error) => void;
+  onQrDisplayed?: (url: string) => void | Promise<void>;
+  onQrExpired?: () => void | Promise<void>;
+}
+
+export interface QqBindFlowOptions {
+  signal?: AbortSignal;
+  source?: string;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException('Aborted', 'AbortError'));
+      },
+      { once: true },
+    );
+  });
+}
+
+async function pollUntilResult(
+  taskId: string,
+  key: string,
+  signal?: AbortSignal,
+): Promise<{ outcome: 'scanned'; appId: string; appSecret: string; userOpenId: string } | { outcome: 'expired' }> {
+  while (!signal?.aborted) {
+    let result;
+    try {
+      result = await pollBindResult(taskId);
+    } catch {
+      await sleep(POLL_INTERVAL_MS, signal);
+      continue;
+    }
+    if (result.status === BindStatus.COMPLETED) {
+      const appSecret = decryptSecret(result.botEncryptSecret, key);
+      return {
+        outcome: 'scanned',
+        appId: result.botAppId,
+        appSecret,
+        userOpenId: result.userOpenId,
+      };
+    }
+    if (result.status === BindStatus.EXPIRED) {
+      return { outcome: 'expired' };
+    }
+    await sleep(POLL_INTERVAL_MS, signal);
+  }
+  throw new DOMException('Aborted', 'AbortError');
+}
+
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export function startQqBindFlow(
+  callbacks: QqBindCallbacks,
+  options: QqBindFlowOptions = {},
+): () => void {
+  const controller = new AbortController();
+  const signal = options.signal
+    ? AbortSignal.any([controller.signal, options.signal])
+    : controller.signal;
+
+  void (async () => {
+    for (;;) {
+      if (signal.aborted) {
+        throw new DOMException('Aborted', 'AbortError');
+      }
+      let task;
+      try {
+        task = await createBindTask();
+      } catch (err) {
+        throw new Error(
+          `获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`,
+          { cause: err },
+        );
+      }
+      const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
+      await callbacks.onQrDisplayed?.(connectUrl);
+      const pollResult = await pollUntilResult(task.taskId, task.key, signal);
+      if (pollResult.outcome === 'scanned') {
+        callbacks.onSuccess([{
+          appId: pollResult.appId,
+          appSecret: pollResult.appSecret,
+          userOpenId: pollResult.userOpenId || undefined,
+        }]);
+        return;
+      }
+      await callbacks.onQrExpired?.();
+    }
+  })().catch((err) => {
+    if (err instanceof DOMException && err.name === 'AbortError') {
+      return;
+    }
+    callbacks.onFailure(err instanceof Error ? err : new Error(String(err)));
+  });
+
+  return () => controller.abort();
+}

package/src/qq-bind-persist.ts

@@ -0,0 +1,44 @@
+import {
+  buildEndpointEnvKey,
+  persistEndpointEnvValues,
+  resolveProjectRoot,
+} from 'zhin.js/adapter';
+
+export { resolveProjectRoot };
+
+export interface QqCredentialEnvKeys {
+  appidKey: string;
+  secretKey: string;
+  appidRef: string;
+  secretRef: string;
+}
+
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
+export function buildQqCredentialEnvKeys(endpointId: string): QqCredentialEnvKeys {
+  const appidKey = buildEndpointEnvKey('qq', endpointId, 'appid');
+  const secretKey = buildEndpointEnvKey('qq', endpointId, 'secret');
+  return {
+    appidKey,
+    secretKey,
+    appidRef: `\${${appidKey}}`,
+    secretRef: `\${${secretKey}}`,
+  };
+}
+
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(
+  endpointId: string,
+  appId: string,
+  appSecret: string,
+  projectRoot?: string,
+): QqCredentialEnvKeys {
+  const keys = buildQqCredentialEnvKeys(endpointId);
+  persistEndpointEnvValues(
+    {
+      [keys.appidKey]: appId,
+      [keys.secretKey]: appSecret,
+    },
+    projectRoot,
+  );
+  return keys;
+}

package/src/qq-bot-kind-prompt.ts

@@ -0,0 +1,47 @@
+import { parseQqBotKind, type QqBotKind } from './qq-intents.js';
+
+/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+export function qqCommandSessionKey(input: unknown): string | undefined {
+  const message = input as {
+    conversation?: {
+      endpoint?: { id?: unknown; adapter?: unknown };
+      kind?: unknown;
+      id?: unknown;
+    };
+    sender?: unknown;
+  } | null | undefined;
+  const conversation = message?.conversation;
+  const adapter = conversation?.endpoint?.adapter;
+  const endpointKey = conversation?.endpoint?.id;
+  const kind = conversation?.kind;
+  const id = conversation?.id;
+  const sender = message?.sender;
+  if (
+    adapter == null
+    || endpointKey == null
+    || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
+    || typeof id !== 'string'
+    || !id
+    || sender == null
+    || String(sender).trim() === ''
+  ) {
+    return undefined;
+  }
+  return `${String(adapter)}\0${String(endpointKey)}\0${kind}\0${id}\0${String(sender).trim()}`;
+}
+
+/**
+ * 解析用户对公域/私域的回复。
+ * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
+ */
+export function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined {
+  const text = String(raw ?? '').trim().toLowerCase();
+  if (!text) return undefined;
+  if (text === '公域' || text === '公开' || text === '1') return 'public';
+  if (text === '私域' || text === '2') return 'private';
+  return parseQqBotKind(text);
+}
+
+export const QQ_BOT_KIND_PROMPT =
+  '请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。\n'
+  + '也可发 qq.endpoint cancel 取消。';