@zhin.js/adapter-qq 1.1.17 → 1.1.18

package/agents/qq/skills/qq-group-directory/tools/group_member_info/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '获取当前 QQ 群中指定成员的信息（昵称、角色、是否机器人、入群时间）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('目标成员的 member_openid（来自消息发送者或成员列表，不要猜测）'),
+  }),
+  async execute({ user_id }, context) {
+    const member = await context.$client.api.groupService.getMemberInfo(currentGroup(context), user_id);
+    return { success: true, member };
+  },
+});

package/agents/qq/skills/qq-group-directory/tools/group_members/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页列出当前 QQ 群成员（每页最多 30 人，含 member_openid、昵称、角色）；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.api.groupService.getMembersPage(currentGroup(context), cursor ? { cursor } : {});
+        return { success: true, members: page.members ?? [], count: page.members?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-directory/tools/group_members/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页列出当前 QQ 群成员（每页最多 30 人，含 member_openid、昵称、角色）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.api.groupService.getMembersPage(currentGroup(context), cursor ? { cursor } : {});
+    return { success: true, members: page.members ?? [], count: page.members?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: qq-group-state
+platforms:
+  - qq
+description: 当前 QQ 群的禁言状态、待处理入群申请与黑名单查询。
+keywords:
+  - 禁言列表
+  - 入群申请
+  - 黑名单
+tools:
+  - list_muted
+  - list_join_requests
+  - group_blacklist
+scopes:
+  - group
+---
+# qq-group-state
+
+Read-only views of the current group. `list_muted` returns the global mute rule and members whose mute has not expired. `list_join_requests` and `group_blacklist` are paged invite-only APIs; error 11253 means the bot has no access.
+
+Act on a join request with `qq-group-admin` → `handle_join_request`, after confirming the applicant. Group files are not exposed by the official API.

package/agents/qq/skills/qq-group-state/tools/group_blacklist/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页查询当前 QQ 群的成员黑名单；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.api.groupService.getMemberBlacklist(currentGroup(context), cursor ? { cursor } : {});
+        return { users: page.users ?? [], count: page.users?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/group_blacklist/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页查询当前 QQ 群的成员黑名单；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.api.groupService.getMemberBlacklist(currentGroup(context), cursor ? { cursor } : {});
+    return { users: page.users ?? [], count: page.users?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/tools/list_join_requests/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页列出当前 QQ 群待处理的入群申请（含验证信息、风险提示）；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.api.groupService.getJoinRequests(currentGroup(context), cursor ? { cursor } : {});
+        return { requests: page.list ?? [], count: page.list?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/list_join_requests/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页列出当前 QQ 群待处理的入群申请（含验证信息、风险提示）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.api.groupService.getJoinRequests(currentGroup(context), cursor ? { cursor } : {});
+    return { requests: page.list ?? [], count: page.list?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/tools/list_muted/index.js

@@ -0,0 +1,21 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '查询当前 QQ 群的禁言状态：全员禁言规则与被禁言成员列表',
+    adapter: 'qq',
+    scopes: ['group'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({}),
+    async execute(_input, context) {
+        const setting = await context.$client.api.groupService.getMuteSetting(currentGroup(context));
+        const now = Date.now();
+        const muted = (setting.members ?? []).filter((m) => {
+            const until = Date.parse(m.mute_expire_at);
+            return !Number.isFinite(until) || until > now;
+        });
+        return { global_rule: setting.global_rule, muted_members: muted, count: muted.length };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/list_muted/index.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '查询当前 QQ 群的禁言状态：全员禁言规则与被禁言成员列表',
+  adapter: 'qq',
+  scopes: ['group'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({}),
+  async execute(_input, context) {
+    const setting = await context.$client.api.groupService.getMuteSetting(currentGroup(context));
+    const now = Date.now();
+    const muted = (setting.members ?? []).filter((m) => {
+      const until = Date.parse(m.mute_expire_at);
+      return !Number.isFinite(until) || until > now;
+    });
+    return { global_rule: setting.global_rule, muted_members: muted, count: muted.length };
+  },
+});

package/agents/qq/skills/qq-messages/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: qq-messages
+platforms:
+  - qq
+description: QQ 官方机器人当前会话的引用回复，以及撤回机器人自己的发言。
+keywords:
+  - 引用
+  - 回复原消息
+  - 撤回
+  - 自己的消息
+tools:
+  - quote_reply
+  - recall_own_message
+scopes:
+  - private
+  - group
+  - channel
+---
+# qq-messages
+
+Only use real message IDs from the current conversation. Do not invent IDs or source authors. Both tools stay inside the current conversation; cross-conversation forwarding does not exist on the official API.
+
+`quote_reply` sends a text reply that references one original (passive reply `msg_id` / guild `message_reference`) through the unified outbound pipeline. Use `inspect_conversation_reference` to read an incoming quote when available; it does not send messages.
+
+`recall_own_message` accepts only the bot's own send receipt ID and needs no management role or approval. QQ only recalls messages younger than 2 minutes; never promise success before confirmation or retry an unconfirmed result. To recall another member's message, load `qq-group-admin`.
+
+Merged forward (`forward_messages`) is not available: the official API cannot send merged-forward records.

package/agents/qq/skills/qq-messages/tools/quote_reply/index.js

@@ -0,0 +1,21 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { resolveMessageTarget, sendToConversation } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '引用当前 QQ 会话中的真实消息并回复文字（引用即被动回复的 msg_id / message_reference）；发送走统一链路',
+    adapter: 'qq',
+    scopes: ['private', 'group', 'channel'],
+    requiresApproval: 'never',
+    inputSchema: z.object({
+        message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
+        text: z.string().min(1).describe('本次回复的文字'),
+    }),
+    async execute({ message_id, text }, context) {
+        const target = resolveMessageTarget(context, message_id);
+        return sendToConversation(context, [
+            { type: 'reply', data: { message_id: target.messageId } },
+            { type: 'text', data: { text } },
+        ]);
+    },
+});

package/agents/qq/skills/qq-messages/tools/quote_reply/index.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { resolveMessageTarget, sendToConversation } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '引用当前 QQ 会话中的真实消息并回复文字（引用即被动回复的 msg_id / message_reference）；发送走统一链路',
+  adapter: 'qq',
+  scopes: ['private', 'group', 'channel'],
+  requiresApproval: 'never',
+  inputSchema: z.object({
+    message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
+    text: z.string().min(1).describe('本次回复的文字'),
+  }),
+  async execute({ message_id, text }, context) {
+    const target = resolveMessageTarget(context, message_id);
+    return sendToConversation(context, [
+      { type: 'reply', data: { message_id: target.messageId } },
+      { type: 'text', data: { text } },
+    ]);
+  },
+});

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { recallTarget, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+    adapter: 'qq',
+    scopes: ['private', 'group', 'channel'],
+    requiresApproval: 'never',
+    inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的消息 ID（发送回执），或消息头里的 m<n> 别名') }),
+    async execute({ message_id }, context) {
+        const target = resolveMessageTarget(context, message_id);
+        if (!target.ownOutbound)
+            return { success: false, message: t(context.locale, 'ownMessageRequired') };
+        return recallTarget(context, target);
+    },
+});

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { recallTarget, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+  adapter: 'qq',
+  scopes: ['private', 'group', 'channel'],
+  requiresApproval: 'never',
+  inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的消息 ID（发送回执），或消息头里的 m<n> 别名') }),
+  async execute({ message_id }, context) {
+    const target = resolveMessageTarget(context, message_id);
+    if (!target.ownOutbound) return { success: false, message: t(context.locale, 'ownMessageRequired') };
+    return recallTarget(context, target);
+  },
+});

package/commands/qq/endpoint/definition.js

@@ -8,11 +8,12 @@ import { messages as t } from "../../../lib/i18n.js";
  * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
  * qqEndpointCommands 供 commands/qq/endpoint/ 下的命令文件默认导出。
  */
-import { buildEndpointEnvKey, createEndpointCommands, endpointCommandForbidden, endpointConfigurationStoreToken, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } from 'zhin.js/adapter';
+import { createEndpointCommands, endpointCommandForbidden, endpointConfigurationStoreToken, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
 import { qqBotKindPrompt, qqCommandSessionKey } from "../../../lib/qq-bot-kind-prompt.js";
 import { startQqBindFlow } from "../../../lib/qq-bind-flow.js";
-import { defaultQqEndpointIntentFields } from "../../../lib/qq-intents.js";
+import { writeQqEndpointWithBotKind } from "../../../lib/qq-endpoint-write.js";
+import { cancelQqConsoleBind } from "../../../lib/qq-console.js";
 import { qqRuntimeStateToken, } from "../../../lib/qq-runtime-state.js";
 export { qqRuntimeStateToken };
 /**
@@ -21,7 +22,17 @@ export { qqRuntimeStateToken };
  * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
  */
 export function isQqEndpointOperator(config, input) {
-    return isEndpointOperator(config, input);
+    if (isEndpointOperator(config, input))
+        return true;
+    // The outage-notify target is the operator's conversation on another adapter.
+    const cfg = (config ?? {});
+    const notifyIds = [
+        cfg.notify?.id,
+        ...(Array.isArray(cfg.endpoints) ? cfg.endpoints.map((endpoint) => endpoint.notify?.id) : []),
+    ];
+    const senderRaw = input?.sender;
+    const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+    return senderId !== '' && notifyIds.some((id) => id != null && String(id) === senderId);
 }
 export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 /**
@@ -36,6 +47,9 @@ function busyFooter(state, locale) {
     if (state.pendingBotKind) {
         return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
     }
+    if (state.consoleBind?.state === 'scanned') {
+        return t(locale, 'kindBusy', { id: state.consoleBind.pending?.endpointId ?? 'QQ' });
+    }
     return undefined;
 }
 /** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
@@ -52,25 +66,18 @@ const qqEndpointListSpec = {
     describeEntry: (entry) => `appid: ${String(entry.appid)}`,
 };
 async function writeEndpointWithBotKind(pending, botKind, store) {
-    const locale = pending.locale;
-    const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
-    const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
-    const intentFields = defaultQqEndpointIntentFields(botKind);
-    const { filePath } = await store.add({
-        adapterKey: 'qq',
-        entry: {
-            id: pending.endpointId,
-            appid: `\${${appidKey}}`,
-            secret: `\${${secretKey}}`,
-            botKind: intentFields.botKind,
-            intents: [...intentFields.intents],
-        },
-        environment: {
-            [appidKey]: pending.appId,
-            [secretKey]: pending.appSecret,
-        },
+    const result = await writeQqEndpointWithBotKind({
+        endpointId: pending.endpointId,
+        appId: pending.appId,
+        appSecret: pending.appSecret,
+        botKind,
+    }, store);
+    return t(pending.locale, 'endpointSaved', {
+        kind: result.botKind,
+        id: result.endpointId,
+        file: result.filePath,
+        intents: result.intents.join(', '),
     });
-    return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 /**
  * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
@@ -86,9 +93,10 @@ export async function completeQqPendingBotKind(pending, botKind, store) {
  * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
  */
 export function runQqEndpointAdd(state, id, reply, store, input, locale = 'zh-CN', cancelCommand, commandHeads) {
-    if (state.bindFlow || state.pendingBotKind) {
+    if (state.bindFlow || state.pendingBotKind || state.consoleBind?.pending || state.consoleBind?.state === 'waiting') {
         return Promise.resolve(t(locale, 'existingFlow'));
     }
+    state.consoleBind = null;
     const endpointId = id?.trim() || undefined;
     const sessionKey = qqCommandSessionKey(input);
     return new Promise((resolve) => {
@@ -159,6 +167,7 @@ export function runQqEndpointCancel(state, preference) {
     if (state.bindFlow) {
         state.bindFlow.stop();
         state.bindFlow = null;
+        cancelQqConsoleBind(state);
         return t(locale, 'cancelled');
     }
     if (state.pendingBotKind) {
@@ -166,6 +175,10 @@ export function runQqEndpointCancel(state, preference) {
         state.pendingBotKind = null;
         return t(locale, 'pendingCancelled', { name });
     }
+    if (state.consoleBind) {
+        cancelQqConsoleBind(state);
+        return t(locale, 'cancelled');
+    }
     return t(locale, 'noFlow');
 }
 /** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */

package/commands/qq/endpoint/definition.ts

@@ -8,7 +8,6 @@ import { messages as t } from '../../../src/i18n.js';
  * qqEndpointCommands 供 commands/qq/endpoint/ 下的命令文件默认导出。
  */
 import {
-  buildEndpointEnvKey,
   createEndpointCommands,
   endpointCommandForbidden,
   endpointConfigurationStoreToken,
@@ -23,7 +22,9 @@ import {
 import { defineCommand } from 'zhin.js/command';
 import { qqBotKindPrompt, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
 import { startQqBindFlow } from '../../../src/qq-bind-flow.js';
-import { defaultQqEndpointIntentFields, type QqBotKind } from '../../../src/qq-intents.js';
+import { writeQqEndpointWithBotKind } from '../../../src/qq-endpoint-write.js';
+import type { QqBotKind } from '../../../src/qq-intents.js';
+import { cancelQqConsoleBind } from '../../../src/qq-console.js';
 import {
   qqRuntimeStateToken,
   type QqPendingBotKind,
@@ -40,7 +41,19 @@ export type QqCommandReply = EndpointCommandReply;
  * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
  */
 export function isQqEndpointOperator(config: unknown, input: unknown): boolean {
-  return isEndpointOperator(config, input);
+  if (isEndpointOperator(config, input)) return true;
+  // The outage-notify target is the operator's conversation on another adapter.
+  const cfg = (config ?? {}) as {
+    notify?: { id?: unknown };
+    endpoints?: readonly { notify?: { id?: unknown } }[];
+  };
+  const notifyIds = [
+    cfg.notify?.id,
+    ...(Array.isArray(cfg.endpoints) ? cfg.endpoints.map((endpoint) => endpoint.notify?.id) : []),
+  ];
+  const senderRaw = (input as { sender?: { id?: unknown } } | null | undefined)?.sender;
+  const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+  return senderId !== '' && notifyIds.some((id) => id != null && String(id) === senderId);
 }
 
 export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
@@ -57,6 +70,9 @@ function busyFooter(state: QqRuntimeState, locale?: Locale): string | undefined
   if (state.pendingBotKind) {
     return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
   }
+  if (state.consoleBind?.state === 'scanned') {
+    return t(locale, 'kindBusy', { id: state.consoleBind.pending?.endpointId ?? 'QQ' });
+  }
   return undefined;
 }
 
@@ -84,25 +100,18 @@ async function writeEndpointWithBotKind(
   botKind: QqBotKind,
   store: EndpointConfigurationStore,
 ): Promise<string> {
-  const locale = pending.locale;
-  const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
-  const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
-  const intentFields = defaultQqEndpointIntentFields(botKind);
-  const { filePath } = await store.add({
-    adapterKey: 'qq',
-    entry: {
-      id: pending.endpointId,
-      appid: `\${${appidKey}}`,
-      secret: `\${${secretKey}}`,
-      botKind: intentFields.botKind,
-      intents: [...intentFields.intents],
-    },
-    environment: {
-      [appidKey]: pending.appId,
-      [secretKey]: pending.appSecret,
-    },
+  const result = await writeQqEndpointWithBotKind({
+    endpointId: pending.endpointId,
+    appId: pending.appId,
+    appSecret: pending.appSecret,
+    botKind,
+  }, store);
+  return t(pending.locale, 'endpointSaved', {
+    kind: result.botKind,
+    id: result.endpointId,
+    file: result.filePath,
+    intents: result.intents.join(', '),
   });
-  return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 
 /**
@@ -133,11 +142,12 @@ export function runQqEndpointAdd(
   cancelCommand?: string,
   commandHeads?: readonly string[],
 ): Promise<string> {
-  if (state.bindFlow || state.pendingBotKind) {
+  if (state.bindFlow || state.pendingBotKind || state.consoleBind?.pending || state.consoleBind?.state === 'waiting') {
     return Promise.resolve(
       t(locale, 'existingFlow'),
     );
   }
+  state.consoleBind = null;
   const endpointId = id?.trim() || undefined;
   const sessionKey = qqCommandSessionKey(input);
   return new Promise<string>((resolve) => {
@@ -222,6 +232,7 @@ export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale):
   if (state.bindFlow) {
     state.bindFlow.stop();
     state.bindFlow = null;
+    cancelQqConsoleBind(state);
     return t(locale, 'cancelled');
   }
   if (state.pendingBotKind) {
@@ -229,6 +240,10 @@ export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale):
     state.pendingBotKind = null;
     return t(locale, 'pendingCancelled', { name });
   }
+  if (state.consoleBind) {
+    cancelQqConsoleBind(state);
+    return t(locale, 'cancelled');
+  }
   return t(locale, 'noFlow');
 }
 

package/lib/console.d.ts

@@ -0,0 +1,8 @@
+/**
+ * QQ Console RPC：除通用 endpoint 管理外，把 `qq endpoint add` 的扫码绑定
+ * （以及公域 / 私域选择、取消）搬到 Console 页面。
+ */
+import { type AdapterConsoleResources } from 'zhin.js/adapter';
+import { type PluginConsoleRpc } from 'zhin.js';
+import type { QqRuntimeState } from './qq-runtime-state.js';
+export declare function createQqConsoleRpc(state: QqRuntimeState, resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,84 @@
+/**
+ * QQ Console RPC：除通用 endpoint 管理外，把 `qq endpoint add` 的扫码绑定
+ * （以及公域 / 私域选择、取消）搬到 Console 页面。
+ */
+import { endpointConfigurationStoreToken, createAdapterConsoleRpc, } from 'zhin.js/adapter';
+import { PluginConsoleRpcError } from 'zhin.js';
+import { qqConsoleSpec } from './qq-console-spec.js';
+import { cancelQqConsoleBind, completeQqConsoleBind, startQqConsoleBind, } from './qq-console.js';
+export function createQqConsoleRpc(state, resources, getConfig) {
+    const store = resources.has(endpointConfigurationStoreToken)
+        ? resources.use(endpointConfigurationStoreToken)
+        : undefined;
+    const spec = {
+        ...qqConsoleSpec,
+        running: () => state.endpoints.values(),
+        getConfig,
+        extraStatus: () => {
+            const bind = state.consoleBind;
+            if (!bind) {
+                return { bindState: state.bindFlow ? 'binding' : 'idle' };
+            }
+            return {
+                bindState: bind.state,
+                ...(bind.url ? { scanUrl: bind.url } : {}),
+                ...(bind.message ? { bindMessage: bind.message } : {}),
+                ...(bind.pending ? { bindEndpoint: bind.pending.endpointId } : {}),
+                ...(bind.error ? { bindError: bind.error } : {}),
+            };
+        },
+        availableActions: () => {
+            if (!store)
+                return [];
+            if (state.consoleBind?.pending)
+                return ['qq-bind-kind', 'qq-bind-cancel'];
+            if (state.bindFlow || state.consoleBind?.state === 'waiting')
+                return ['qq-bind-cancel'];
+            return ['qq-bind-start'];
+        },
+        actions: {
+            'qq-bind-start': {
+                label: '扫码绑定新机器人',
+                labelI18n: { en: 'Bind a bot with QR' },
+                description: '用手机 QQ 扫码，成功后选择公域 / 私域，再一次性写入 .env 与配置。',
+                descriptionI18n: { en: 'Scan with mobile QQ, choose public/private, then save credentials to .env and the config.' },
+                handler: async () => {
+                    if (!store)
+                        throw new PluginConsoleRpcError('unsupported', '当前运行环境不支持写入 endpoint 配置');
+                    const { url } = await startQqConsoleBind(state);
+                    return { message: '请用手机 QQ 扫码；扫码成功后选择公域或私域', url };
+                },
+            },
+            'qq-bind-kind': {
+                label: '选择公域 / 私域',
+                labelI18n: { en: 'Choose public/private' },
+                description: '公域订阅 PUBLIC_GUILD_MESSAGES；私域订阅 GUILD_MESSAGES。',
+                descriptionI18n: { en: 'Public subscribes PUBLIC_GUILD_MESSAGES; private subscribes GUILD_MESSAGES.' },
+                options: [
+                    { value: 'public', label: '公域', labelI18n: { en: 'Public' } },
+                    { value: 'private', label: '私域', labelI18n: { en: 'Private' } },
+                ],
+                handler: async (input) => {
+                    if (!store)
+                        throw new PluginConsoleRpcError('unsupported', '当前运行环境不支持写入 endpoint 配置');
+                    const result = await completeQqConsoleBind(state, store, input.value);
+                    return {
+                        message: `已写入 endpoint「${result.endpointId}」（${result.botKind}），重启或热重载后生效`,
+                        details: { endpoint: result.endpointId, botKind: result.botKind, intents: result.intents.join(', ') },
+                    };
+                },
+            },
+            'qq-bind-cancel': {
+                label: '取消扫码绑定',
+                labelI18n: { en: 'Cancel QR binding' },
+                description: '中止正在进行的扫码绑定；已写入的配置不会删除。',
+                descriptionI18n: { en: 'Stop the current QR binding flow; already-saved configuration is untouched.' },
+                handler: async () => {
+                    const cancelled = cancelQqConsoleBind(state);
+                    return { message: cancelled ? '已取消绑定' : '当前没有进行中的绑定流程' };
+                },
+            },
+        },
+    };
+    return createAdapterConsoleRpc(spec, resources);
+}