@zhin.js/adapter-qq 7.0.2 → 7.0.5

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 取消。';

package/src/qq-endpoint-commands.ts

@@ -11,15 +11,21 @@ import {
   extractEndpointCommandReply,
   formatEndpointList,
   isEndpointOperator,
-  removeEndpointByName,
+  removeEndpointById,
   type ConfiguredEndpointEntry,
   type EndpointCommandReply,
 } from '@zhin.js/adapter';
 import { defineCommand } from '@zhin.js/command';
+import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from './qq-bot-kind-prompt.js';
 import { startQqBindFlow } from './qq-bind-flow.js';
 import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
 import { addQqEndpointToConfig, listQqEndpointEntries } from './qq-endpoint-config.js';
-import { qqRuntimeStateToken, type QqRuntimeState } from './qq-runtime-state.js';
+import { defaultQqEndpointIntentFields, type QqBotKind } from './qq-intents.js';
+import {
+  qqRuntimeStateToken,
+  type QqPendingBotKind,
+  type QqRuntimeState,
+} from './qq-runtime-state.js';
 
 export type QqCommandReply = EndpointCommandReply;
 
@@ -41,12 +47,20 @@ export function extractQqCommandReply(input: unknown): QqCommandReply {
   return extractEndpointCommandReply(input);
 }
 
+function busyFooter(state: QqRuntimeState): string | undefined {
+  if (state.bindFlow) return '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消';
+  if (state.pendingBotKind) {
+    return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq.endpoint cancel`;
+  }
+  return undefined;
+}
+
 /** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
 export function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string {
   return formatEndpointList(qqEndpointListSpec, {
     running: state.endpoints.values(),
     configured: listQqEndpointEntries(projectRoot),
-    footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined,
+    footer: busyFooter(state),
   });
 }
 
@@ -56,21 +70,67 @@ const qqEndpointListSpec = {
   describeEntry: (entry: ConfiguredEndpointEntry) => `appid: ${String(entry.appid)}`,
 } as const;
 
+function writeEndpointWithBotKind(
+  pending: QqPendingBotKind,
+  botKind: QqBotKind,
+  projectRoot?: string,
+): string {
+  const envKeys = persistQqCredentialsToEnv(
+    pending.endpointId,
+    pending.appId,
+    pending.appSecret,
+    projectRoot,
+  );
+  const intentFields = defaultQqEndpointIntentFields(botKind);
+  const filePath = addQqEndpointToConfig(
+    {
+      id: pending.endpointId,
+      appid: envKeys.appidRef,
+      secret: envKeys.secretRef,
+      botKind: intentFields.botKind,
+      intents: [...intentFields.intents],
+    },
+    projectRoot,
+  );
+  return (
+    `✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
+    `intents: ${intentFields.intents.join(', ')}。\n` +
+    '⚠️ 需重启 zhin 后新 endpoint 才会生效。'
+  );
+}
+
 /**
- * `qq.endpoint add [name]`：启动扫码绑定流程。
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export function completeQqPendingBotKind(
+  pending: QqPendingBotKind,
+  botKind: QqBotKind,
+  projectRoot?: string,
+): string {
+  return writeEndpointWithBotKind(pending, botKind, projectRoot);
+}
+
+/**
+ * `qq.endpoint add [id]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
  */
 export function runQqEndpointAdd(
   state: QqRuntimeState,
-  name: string | undefined,
+  id: string | undefined,
   reply: QqCommandReply,
   projectRoot?: string,
+  input?: unknown,
 ): Promise<string> {
-  if (state.bindFlow) {
-    return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq.endpoint cancel 取消后再试');
+  if (state.bindFlow || state.pendingBotKind) {
+    return Promise.resolve(
+      '已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq.endpoint cancel 取消后再试',
+    );
   }
-  const endpointName = name?.trim() || undefined;
+  const endpointId = id?.trim() || undefined;
+  const sessionKey = qqCommandSessionKey(input);
   return new Promise<string>((resolve) => {
     let firstReplied = false;
     const settle = (text: string) => {
@@ -79,7 +139,10 @@ export function runQqEndpointAdd(
         resolve(text);
         return;
       }
-      void reply(text);
+      // Follow-ups outlive the inbound Message reply scope; durable reply
+      // (OutboundHost) is provided by createEndpointCommands.bindFlow. Never
+      // let a late notify crash the process.
+      void Promise.resolve(reply(text)).catch(() => undefined);
     };
     const stop = startQqBindFlow(
       {
@@ -90,21 +153,45 @@ export function runQqEndpointAdd(
           );
         },
         onQrExpired: async () => {
-          await reply('二维码已过期，正在刷新，请扫描新链接…');
+          try {
+            await reply('二维码已过期，正在刷新，请扫描新链接…');
+          } catch {
+            // same as settle follow-up: best-effort after command scope ends
+          }
         },
         onSuccess: async (credentials) => {
           state.bindFlow = null;
           try {
             const [{ appId, appSecret }] = credentials;
-            const finalName = endpointName ?? appId;
-            const envKeys = persistQqCredentialsToEnv(finalName, appId, appSecret, projectRoot);
-            const filePath = addQqEndpointToConfig(
-              { name: finalName, appid: envKeys.appidRef, secret: envKeys.secretRef },
-              projectRoot,
-            );
+            const finalName = endpointId ?? appId;
+
+            // 无会话上下文（Host 等）时无法追问，直接按公域一次性写入
+            if (!sessionKey) {
+              settle(
+                writeEndpointWithBotKind(
+                  {
+                    endpointId: finalName,
+                    appId,
+                    appSecret,
+                    sessionKey: '',
+                  },
+                  'public',
+                  projectRoot,
+                ) +
+                '\n（当前会话无法交互选择公/私域；私域请手动改配置。）',
+              );
+              return;
+            }
+
+            state.pendingBotKind = {
+              endpointId: finalName,
+              appId,
+              appSecret,
+              sessionKey,
+            };
             settle(
-              `✅ 绑定成功！endpoint「${finalName}」的凭据已写入 .env，并已追加到 ${filePath} 的 plugins.qq.endpoints。\n` +
-              '⚠️ 需重启 zhin 后新 endpoint 才会生效。',
+              `✅ 扫码成功！endpoint「${finalName}」。\n` +
+              QQ_BOT_KIND_PROMPT,
             );
           } catch (error) {
             settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
@@ -117,27 +204,32 @@ export function runQqEndpointAdd(
       },
       { source: 'zhin' },
     );
-    state.bindFlow = { name: endpointName, stop };
+    state.bindFlow = { id: endpointId, stop };
   });
 }
 
-/** `qq.endpoint cancel`：中止进行中的绑定流程 */
+/** `qq.endpoint cancel`：中止进行中的绑定或待选 botKind */
 export function runQqEndpointCancel(state: QqRuntimeState): string {
-  if (!state.bindFlow) {
-    return '当前没有进行中的 QQ 绑定流程';
+  if (state.bindFlow) {
+    state.bindFlow.stop();
+    state.bindFlow = null;
+    return '已取消进行中的 QQ 绑定流程';
+  }
+  if (state.pendingBotKind) {
+    const name = state.pendingBotKind.endpointId;
+    state.pendingBotKind = null;
+    return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
   }
-  state.bindFlow.stop();
-  state.bindFlow = null;
-  return '已取消进行中的 QQ 绑定流程';
+  return '当前没有进行中的 QQ 绑定流程';
 }
 
-/** `qq.endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+/** `qq.endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
 export function runQqEndpointRemove(
   _state: QqRuntimeState,
-  name: string,
+  id: string,
   projectRoot?: string,
 ): string {
-  return removeEndpointByName(qqEndpointListSpec, name, projectRoot);
+  return removeEndpointById(qqEndpointListSpec, id, projectRoot);
 }
 
 /**
@@ -151,10 +243,9 @@ export const qqEndpointCommands = createEndpointCommands({
     { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
   ],
   running: (use) => use(qqRuntimeStateToken).endpoints.values(),
-  listFooter: (use) => {
-    const state = use(qqRuntimeStateToken);
-    return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined;
-  },
-  addDescription: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
-  bindFlow: ({ name, reply, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), name, reply),
+  listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+  addDescription:
+    '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
+  bindFlow: ({ id, reply, input, use }) =>
+    runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, undefined, input),
 }, defineCommand);

package/src/qq-endpoint-config.ts

@@ -11,7 +11,7 @@ import {
 } from '@zhin.js/adapter';
 
 export interface QqEndpointConfigEntry {
-  name: string;
+  id: string;
   appid: string;
   secret: string;
   [key: string]: unknown;
@@ -27,7 +27,7 @@ export function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEnt
   return listConfiguredEndpoints('qq', projectRoot) as QqEndpointConfigEntry[];
 }
 
-/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+/** 追加 endpoint 到 plugins.qq.endpoints；id 已存在时报错 */
 export function addQqEndpointToConfig(
   entry: QqEndpointConfigEntry,
   projectRoot?: string,
@@ -35,10 +35,10 @@ export function addQqEndpointToConfig(
   return addEndpointToConfig('qq', entry, projectRoot);
 }
 
-/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+/** 按 id 移除 plugins.qq.endpoints 项；不存在返回 false */
 export function removeQqEndpointFromConfig(
-  name: string,
+  id: string,
   projectRoot?: string,
 ): { removed: boolean; filePath: string } {
-  return removeEndpointFromConfig('qq', name, projectRoot);
+  return removeEndpointFromConfig('qq', id, projectRoot);
 }

package/src/qq-intents.ts

@@ -0,0 +1,76 @@
+/**
+ * QQ 官方机器人 intents 与公域/私域映射。
+ *
+ * 群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`。
+ * 频道消息 intent 不同：
+ * - public（公域）：`PUBLIC_GUILD_MESSAGES`（仅 @ 机器人）
+ * - private（私域）：`GUILD_MESSAGES`（频道全量消息；公域订阅会 Identify 失败）
+ */
+
+export type QqBotKind = 'public' | 'private';
+
+export type QqIntent =
+  | 'GUILDS'
+  | 'GUILD_MEMBERS'
+  | 'GUILD_MESSAGES'
+  | 'GUILD_MESSAGE_REACTIONS'
+  | 'DIRECT_MESSAGE'
+  | 'GROUP_AND_C2C_EVENT'
+  | 'INTERACTION'
+  | 'MESSAGE_AUDIT'
+  | 'FORUMS_EVENT'
+  | 'AUDIO_ACTION'
+  | 'PUBLIC_GUILD_MESSAGES'
+  | 'GROUP_MEMBER';
+
+/** 扫码绑定 / 未声明 botKind 时的默认（公域更常见）。 */
+export const DEFAULT_QQ_BOT_KIND: QqBotKind = 'public';
+
+/** 公/私域共用：群@+私聊 C2C、频道基础事件、频道私信。 */
+const QQ_SHARED_INTENTS = Object.freeze([
+  'GROUP_AND_C2C_EVENT',
+  'GUILDS',
+  'GUILD_MEMBERS',
+  'DIRECT_MESSAGE',
+] as const satisfies readonly QqIntent[]);
+
+export const QQ_INTENTS_BY_KIND: Readonly<Record<QqBotKind, readonly QqIntent[]>> = Object.freeze({
+  public: Object.freeze([
+    ...QQ_SHARED_INTENTS,
+    'PUBLIC_GUILD_MESSAGES',
+  ] as const),
+  private: Object.freeze([
+    ...QQ_SHARED_INTENTS,
+    'GUILD_MESSAGES',
+  ] as const),
+});
+
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export function parseQqBotKind(value: unknown): QqBotKind | undefined {
+  if (value === 'public' || value === 'private') return value;
+  return undefined;
+}
+
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export function resolveQqIntents(input: {
+  readonly intents?: readonly string[] | undefined;
+  readonly botKind?: unknown;
+}): readonly QqIntent[] {
+  if (Array.isArray(input.intents) && input.intents.length > 0) {
+    return Object.freeze(input.intents.map(String)) as readonly QqIntent[];
+  }
+  const kind = parseQqBotKind(input.botKind) ?? DEFAULT_QQ_BOT_KIND;
+  return QQ_INTENTS_BY_KIND[kind];
+}
+
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export function defaultQqEndpointIntentFields(
+  botKind: QqBotKind = DEFAULT_QQ_BOT_KIND,
+): { readonly botKind: QqBotKind; readonly intents: readonly QqIntent[] } {
+  return Object.freeze({
+    botKind,
+    intents: QQ_INTENTS_BY_KIND[botKind],
+  });
+}

package/src/qq-runtime-state.ts

@@ -1,32 +1,47 @@
 /**
  * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
- * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
- * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ * 扫码绑定 / 待选 botKind 流程。由 plugin.ts setup() provide，
+ * adapter create 与 commands / middleware 通过 use(qqRuntimeStateToken) 共享。
  */
 import { createToken } from '@zhin.js/plugin-runtime';
 
 export interface QqRunningEndpoint {
-  name: string;
+  id: string;
   mode: string;
 }
 
 export interface QqBindFlowHandle {
-  /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
-  name?: string;
+  /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
+  id?: string;
   stop: () => void;
 }
 
+/**
+ * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
+ * （提前写 .env 会触发 HMR，冲掉 pending。）
+ */
+export interface QqPendingBotKind {
+  readonly endpointId: string;
+  readonly appId: string;
+  readonly appSecret: string;
+  /** 发起 add 的会话键；仅同会话回复可完成选择 */
+  readonly sessionKey: string;
+}
+
 export interface QqRuntimeState {
-  /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+  /** 当前 generation 已成功创建的 endpoint（id → 描述） */
   readonly endpoints: Map<string, QqRunningEndpoint>;
   /** 全局单例：同一时间只允许一个扫码绑定流程 */
   bindFlow: QqBindFlowHandle | null;
+  /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
+  pendingBotKind: QqPendingBotKind | null;
 }
 
 export function createQqRuntimeState(): QqRuntimeState {
   return {
     endpoints: new Map(),
     bindFlow: null,
+    pendingBotKind: null,
   };
 }
 

package/src/webhook.ts

@@ -86,6 +86,8 @@ export function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTra
     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 {

package/src/ws.ts

@@ -3,7 +3,6 @@
  */
 import path from 'node:path';
 import { Bot, ReceiverMode, type Sendable } from 'qq-official-bot';
-import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
 import type { MediaRef, Segment } from '@zhin.js/core';
 import type { QqOutboundMessage } from './outbound.js';
 import type { QqChannelKind, QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
@@ -250,7 +249,8 @@ export function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransp
     mode: ReceiverMode.WEBSOCKET,
     sandbox: config.sandbox,
     dataDir: path.join(process.cwd(), 'data', 'qq'),
-    logLevel: toLog4jsLevel(getLevel()),
+    // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
+    logLevel: 'off',
     ...(config.intents ? { intents: config.intents as never } : {}),
     ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
     ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),