@zhin.js/adapter-qq 7.0.3 → 7.0.5

package/lib/protocol.js

@@ -4,6 +4,7 @@
  */
 import { pickCredential } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { resolveQqIntents } from './qq-intents.js';
 const logger = getLogger('qq');
 export function resolveQqConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
@@ -12,8 +13,8 @@ export function resolveQqConfig(config = {}) {
     if (!appid || !secret) {
         throw new TypeError('QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    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';
@@ -23,7 +24,7 @@ export function resolveQqConfig(config = {}) {
         return {
             context: 'qq',
             mode,
-            name,
+            id,
             appid,
             secret,
             webhookPath,
@@ -33,11 +34,14 @@ export function resolveQqConfig(config = {}) {
     return {
         context: 'qq',
         mode: 'websocket',
-        name,
+        id,
         appid,
         secret,
         sandbox: config.sandbox === true || entry?.sandbox === true,
-        intents: config.intents ?? entry?.intents,
+        intents: resolveQqIntents({
+            intents: config.intents ?? entry?.intents,
+            botKind: config.botKind ?? entry?.botKind,
+        }),
         accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
         gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
     };
@@ -46,10 +50,10 @@ export function resolveQqConfig(config = {}) {
  * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
  * private 会话；频道消息的所属 guild 进 `parent`。
  */
-export function qqInboundConversation(endpointId, msg) {
+export function qqInboundConversation(endpointKey, msg) {
     const kind = msg.channelKind === 'direct' ? 'private' : msg.channelKind;
     return {
-        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
         kind,
         id: msg.channelId,
         ...(msg.guildId && (msg.channelKind === 'channel' || msg.channelKind === 'direct')

package/lib/qq-agent-deps.d.ts

@@ -13,9 +13,9 @@ export interface QqAgentEndpoint {
     removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
 }
 export interface QqAgentDeps {
-    getEndpoint: (endpointId: string) => QqAgentEndpoint;
+    getEndpoint: (endpointKey: string) => QqAgentEndpoint;
 }
-export declare function registerQqAgentEndpoint(endpointId: string, endpoint: QqAgentEndpoint): () => void;
+export declare function registerQqAgentEndpoint(endpointKey: string, endpoint: QqAgentEndpoint): () => void;
 /** Optional override used by tests / transitional callers. Pass `null` to clear. */
 export declare function setQqAgentDeps(deps: QqAgentDeps | null): void;
 export declare function getQqAgentDeps(): QqAgentDeps;

package/lib/qq-agent-deps.js

@@ -4,11 +4,11 @@
  */
 const endpoints = new Map();
 let override = null;
-export function registerQqAgentEndpoint(endpointId, endpoint) {
-    endpoints.set(endpointId, endpoint);
+export function registerQqAgentEndpoint(endpointKey, endpoint) {
+    endpoints.set(endpointKey, endpoint);
     return () => {
-        if (endpoints.get(endpointId) === endpoint) {
-            endpoints.delete(endpointId);
+        if (endpoints.get(endpointKey) === endpoint) {
+            endpoints.delete(endpointKey);
         }
     };
 }
@@ -20,10 +20,10 @@ export function getQqAgentDeps() {
     if (override)
         return override;
     return {
-        getEndpoint(endpointId) {
-            const registered = endpoints.get(endpointId);
+        getEndpoint(endpointKey) {
+            const registered = endpoints.get(endpointKey);
             if (!registered)
-                throw new Error(`Endpoint ${endpointId} 不存在`);
+                throw new Error(`Endpoint ${endpointKey} 不存在`);
             return registered;
         },
     };

package/lib/qq-bind-persist.d.ts

@@ -7,6 +7,6 @@ export interface QqCredentialEnvKeys {
     secretRef: string;
 }
 /** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
-export declare function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys;
+export declare function buildQqCredentialEnvKeys(endpointId: string): QqCredentialEnvKeys;
 /** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
-export declare function persistQqCredentialsToEnv(endpointName: string, appId: string, appSecret: string, projectRoot?: string): QqCredentialEnvKeys;
+export declare function persistQqCredentialsToEnv(endpointId: string, appId: string, appSecret: string, projectRoot?: string): QqCredentialEnvKeys;

package/lib/qq-bind-persist.js

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

package/lib/qq-bot-kind-prompt.d.ts

@@ -0,0 +1,9 @@
+import { type QqBotKind } from './qq-intents.js';
+/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+export declare function qqCommandSessionKey(input: unknown): string | undefined;
+/**
+ * 解析用户对公域/私域的回复。
+ * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
+ */
+export declare function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined;
+export declare const QQ_BOT_KIND_PROMPT: string;

package/lib/qq-bot-kind-prompt.js

@@ -0,0 +1,37 @@
+import { parseQqBotKind } from './qq-intents.js';
+/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+export function qqCommandSessionKey(input) {
+    const message = input;
+    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) {
+    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/lib/qq-endpoint-commands.d.ts

@@ -6,7 +6,8 @@
  * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
  */
 import { type EndpointCommandReply } from '@zhin.js/adapter';
-import { type QqRuntimeState } from './qq-runtime-state.js';
+import { type QqBotKind } from './qq-intents.js';
+import { type QqPendingBotKind, type QqRuntimeState } from './qq-runtime-state.js';
 export type QqCommandReply = EndpointCommandReply;
 /**
  * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
@@ -22,15 +23,21 @@ export declare function extractQqCommandReply(input: unknown): QqCommandReply;
 /** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
 export declare function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string;
 /**
- * `qq.endpoint add [name]`：启动扫码绑定流程。
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export declare function completeQqPendingBotKind(pending: QqPendingBotKind, botKind: QqBotKind, projectRoot?: string): string;
+/**
+ * `qq.endpoint add [id]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
  */
-export declare function runQqEndpointAdd(state: QqRuntimeState, name: string | undefined, reply: QqCommandReply, projectRoot?: string): Promise<string>;
-/** `qq.endpoint cancel`：中止进行中的绑定流程 */
+export declare function runQqEndpointAdd(state: QqRuntimeState, id: string | undefined, reply: QqCommandReply, projectRoot?: string, input?: unknown): Promise<string>;
+/** `qq.endpoint cancel`：中止进行中的绑定或待选 botKind */
 export declare function runQqEndpointCancel(state: QqRuntimeState): string;
-/** `qq.endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
-export declare function runQqEndpointRemove(_state: QqRuntimeState, name: string, projectRoot?: string): string;
+/** `qq.endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export declare function runQqEndpointRemove(_state: QqRuntimeState, id: string, projectRoot?: string): string;
 /**
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。

package/lib/qq-endpoint-commands.js

@@ -5,12 +5,14 @@
  * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
  * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
  */
-import { createEndpointCommands, endpointCommandForbidden, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointByName, } from '@zhin.js/adapter';
+import { createEndpointCommands, endpointCommandForbidden, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } 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 } from './qq-runtime-state.js';
+import { defaultQqEndpointIntentFields } from './qq-intents.js';
+import { qqRuntimeStateToken, } from './qq-runtime-state.js';
 /**
  * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
  * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
@@ -26,12 +28,20 @@ export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 export function extractQqCommandReply(input) {
     return extractEndpointCommandReply(input);
 }
+function busyFooter(state) {
+    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, projectRoot) {
     return formatEndpointList(qqEndpointListSpec, {
         running: state.endpoints.values(),
         configured: listQqEndpointEntries(projectRoot),
-        footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined,
+        footer: busyFooter(state),
     });
 }
 const qqEndpointListSpec = {
@@ -39,16 +49,39 @@ const qqEndpointListSpec = {
     adapterDisplayName: 'QQ',
     describeEntry: (entry) => `appid: ${String(entry.appid)}`,
 };
+function writeEndpointWithBotKind(pending, botKind, projectRoot) {
+    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 才会生效。');
+}
+/**
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export function completeQqPendingBotKind(pending, botKind, projectRoot) {
+    return writeEndpointWithBotKind(pending, botKind, projectRoot);
+}
 /**
- * `qq.endpoint add [name]`：启动扫码绑定流程。
+ * `qq.endpoint add [id]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
  */
-export function runQqEndpointAdd(state, name, reply, projectRoot) {
-    if (state.bindFlow) {
-        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq.endpoint cancel 取消后再试');
+export function runQqEndpointAdd(state, id, reply, projectRoot, input) {
+    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((resolve) => {
         let firstReplied = false;
         const settle = (text) => {
@@ -57,7 +90,10 @@ export function runQqEndpointAdd(state, name, reply, projectRoot) {
                 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({
             onQrDisplayed: (url) => {
@@ -65,17 +101,37 @@ export function runQqEndpointAdd(state, name, reply, projectRoot) {
                 settle(`请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`);
             },
             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);
-                    settle(`✅ 绑定成功！endpoint「${finalName}」的凭据已写入 .env，并已追加到 ${filePath} 的 plugins.qq.endpoints。\n` +
-                        '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+                    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}」。\n` +
+                        QQ_BOT_KIND_PROMPT);
                 }
                 catch (error) {
                     settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
@@ -86,21 +142,26 @@ export function runQqEndpointAdd(state, name, reply, projectRoot) {
                 settle(`❌ QQ 绑定失败：${error.message}`);
             },
         }, { source: 'zhin' });
-        state.bindFlow = { name: endpointName, stop };
+        state.bindFlow = { id: endpointId, stop };
     });
 }
-/** `qq.endpoint cancel`：中止进行中的绑定流程 */
+/** `qq.endpoint cancel`：中止进行中的绑定或待选 botKind */
 export function runQqEndpointCancel(state) {
-    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 项 */
-export function runQqEndpointRemove(_state, name, projectRoot) {
-    return removeEndpointByName(qqEndpointListSpec, name, projectRoot);
+/** `qq.endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export function runQqEndpointRemove(_state, id, projectRoot) {
+    return removeEndpointById(qqEndpointListSpec, id, projectRoot);
 }
 /**
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
@@ -113,10 +174,7 @@ 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/lib/qq-endpoint-config.d.ts

@@ -1,5 +1,5 @@
 export interface QqEndpointConfigEntry {
-    name: string;
+    id: string;
     appid: string;
     secret: string;
     [key: string]: unknown;
@@ -8,10 +8,10 @@ export interface QqEndpointConfigEntry {
 export declare function findQqConfigFile(projectRoot?: string): string;
 /** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
 export declare function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[];
-/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+/** 追加 endpoint 到 plugins.qq.endpoints；id 已存在时报错 */
 export declare function addQqEndpointToConfig(entry: QqEndpointConfigEntry, projectRoot?: string): string;
-/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
-export declare function removeQqEndpointFromConfig(name: string, projectRoot?: string): {
+/** 按 id 移除 plugins.qq.endpoints 项；不存在返回 false */
+export declare function removeQqEndpointFromConfig(id: string, projectRoot?: string): {
     removed: boolean;
     filePath: string;
 };

package/lib/qq-endpoint-config.js

@@ -12,11 +12,11 @@ export function findQqConfigFile(projectRoot) {
 export function listQqEndpointEntries(projectRoot) {
     return listConfiguredEndpoints('qq', projectRoot);
 }
-/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+/** 追加 endpoint 到 plugins.qq.endpoints；id 已存在时报错 */
 export function addQqEndpointToConfig(entry, projectRoot) {
     return addEndpointToConfig('qq', entry, projectRoot);
 }
-/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
-export function removeQqEndpointFromConfig(name, projectRoot) {
-    return removeEndpointFromConfig('qq', name, projectRoot);
+/** 按 id 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(id, projectRoot) {
+    return removeEndpointFromConfig('qq', id, projectRoot);
 }

package/lib/qq-intents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare const DEFAULT_QQ_BOT_KIND: QqBotKind;
+export declare const QQ_INTENTS_BY_KIND: Readonly<Record<QqBotKind, readonly QqIntent[]>>;
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export declare function parseQqBotKind(value: unknown): QqBotKind | undefined;
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export declare function resolveQqIntents(input: {
+    readonly intents?: readonly string[] | undefined;
+    readonly botKind?: unknown;
+}): readonly QqIntent[];
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export declare function defaultQqEndpointIntentFields(botKind?: QqBotKind): {
+    readonly botKind: QqBotKind;
+    readonly intents: readonly QqIntent[];
+};

package/lib/qq-intents.js

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

package/lib/qq-runtime-state.d.ts

@@ -1,17 +1,30 @@
 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 declare function createQqRuntimeState(): QqRuntimeState;
 export declare const qqRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

@@ -1,13 +1,14 @@
 /**
  * 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 function createQqRuntimeState() {
     return {
         endpoints: new Map(),
         bindFlow: null,
+        pendingBotKind: null,
     };
 }
 export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');

package/lib/webhook.js

@@ -60,6 +60,8 @@ export function defaultCreateHttpBot(config) {
         platform: 'koa',
         sandbox: config.sandbox,
         dataDir: path.join(process.cwd(), 'data', 'qq'),
+        // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
+        logLevel: 'off',
     });
     return {
         start: () => bot.start().then(() => undefined),

package/lib/ws.js

@@ -3,7 +3,6 @@
  */
 import path from 'node:path';
 import { Bot, ReceiverMode } from 'qq-official-bot';
-import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
 /**
  * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
  * Session.stop() does not update it, so a normal shutdown is treated as an
@@ -190,7 +189,8 @@ export function defaultCreateBot(config) {
         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 } : {}),
         ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
         ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),