@zhin.js/adapter-qq 1.1.18 → 1.1.19

package/lib/group-admin.d.ts

@@ -7,7 +7,7 @@
  * - 没有「机器人所在群列表」「好友列表」「退群」「设管理员」「群公告」等接口。
  */
 import type { GroupBotState, GroupMemberInfo } from 'qq-official-bot';
-import type { GroupMemberProfile, GroupModerationAction, GroupModerationMember, GroupSceneFacts } from 'zhin.js/adapter';
+import { type EndpointGroupRequest, type EndpointMemberRequest, type EndpointMuteRequest, type EndpointGroupInspectionRequest, type EndpointMemberInspectionRequest, type EndpointModerationRequest, type GroupMemberProfile, type GroupModerationMember, type GroupSceneFacts } from 'zhin.js/adapter';
 import type { QqOfficialApi } from './ws.js';
 /** 官方 restrict_chat_setting 上限：30 天。 */
 export declare const QQ_GROUP_MUTE_MAX_SECONDS: number;
@@ -19,18 +19,23 @@ export declare function parseQqTime(value: unknown, { allowFuture }?: {
     allowFuture?: boolean | undefined;
 }): number | undefined;
 /** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
-export declare function qqGroupBotState(api: Partial<QqOfficialApi> | undefined, groupId: string): Promise<GroupBotState>;
-export declare function qqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string): Promise<GroupMemberInfo>;
+export declare function qqGroupBotState(api: Partial<QqOfficialApi> | undefined, { groupId, signal }: EndpointGroupRequest): Promise<GroupBotState>;
+export declare function qqGroupMember(api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberRequest): Promise<GroupMemberInfo>;
 /** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
-export declare function muteQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, durationSeconds: number): Promise<void>;
+export declare function muteQqGroupMember(api: Partial<QqOfficialApi> | undefined, { groupId, userId, durationSeconds, signal }: EndpointMuteRequest): Promise<void>;
 /** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
-export declare function kickQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, addToBlacklist?: boolean): Promise<{
+export declare function kickQqGroupMember(api: Partial<QqOfficialApi> | undefined, { groupId, userId, addToBlacklist, signal }: EndpointMemberRequest & {
+    readonly addToBlacklist?: boolean;
+}): Promise<{
     blacklistFailed: boolean;
 }>;
 /** 自动审核用：机器人与目标成员的实时角色；平台只允许管理员处置普通成员（且非机器人）。 */
-export declare function inspectQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal): Promise<GroupModerationMember>;
-export declare function moderateQqGroupMember(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, action: GroupModerationAction, signal: AbortSignal, isActive: () => boolean): Promise<void>;
+export declare function inspectQqGroupMember(api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberInspectionRequest): Promise<GroupModerationMember>;
+export declare function moderateQqGroupMember({ api, isActive }: {
+    readonly api: Partial<QqOfficialApi> | undefined;
+    readonly isActive: () => boolean;
+}, { groupId, userId, action, signal }: EndpointModerationRequest): Promise<void>;
 /** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
-export declare function inspectQqGroupScene(api: Partial<QqOfficialApi> | undefined, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts>;
+export declare function inspectQqGroupScene(api: Partial<QqOfficialApi> | undefined, { groupId, signal }: EndpointGroupInspectionRequest): Promise<GroupSceneFacts>;
 /** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
-export declare function inspectQqGroupMemberProfile(api: Partial<QqOfficialApi> | undefined, groupId: string, userId: string, signal: AbortSignal): Promise<GroupMemberProfile>;
+export declare function inspectQqGroupMemberProfile(api: Partial<QqOfficialApi> | undefined, { groupId, userId, signal }: EndpointMemberInspectionRequest): Promise<GroupMemberProfile>;

package/lib/group-admin.js

@@ -1,3 +1,4 @@
+import { createEndpointOperation, } from 'zhin.js/adapter';
 /** 官方 restrict_chat_setting 上限：30 天。 */
 export const QQ_GROUP_MUTE_MAX_SECONDS = 30 * 24 * 60 * 60;
 export function qqGroupService(api) {
@@ -30,37 +31,37 @@ export function parseQqTime(value, { allowFuture = false } = {}) {
     return at;
 }
 /** 只读、实时：机器人在群里的状态（角色、是否允许主动消息、接收设置）。 */
-export async function qqGroupBotState(api, groupId) {
-    return qqGroupService(api).getBotState(requireId(groupId, 'group id'));
+export async function qqGroupBotState(api, { groupId, signal }) {
+    return createEndpointOperation({ signal }).run(() => qqGroupService(api).getBotState(requireId(groupId, 'group id')));
 }
-export async function qqGroupMember(api, groupId, userId) {
-    return qqGroupService(api).getMemberInfo(requireId(groupId, 'group id'), requireId(userId, 'member id'));
+export async function qqGroupMember(api, { groupId, userId, signal }) {
+    return createEndpointOperation({ signal }).run(() => qqGroupService(api).getMemberInfo(requireId(groupId, 'group id'), requireId(userId, 'member id')));
 }
 /** 禁言 / 解除禁言一个普通成员；0 = 解除。 */
-export async function muteQqGroupMember(api, groupId, userId, durationSeconds) {
+export async function muteQqGroupMember(api, { groupId, userId, durationSeconds, signal }) {
     if (!Number.isSafeInteger(durationSeconds) || durationSeconds < 0 || durationSeconds > QQ_GROUP_MUTE_MAX_SECONDS) {
         throw new RangeError(`QQ group mute duration must be 0..${QQ_GROUP_MUTE_MAX_SECONDS} seconds`);
     }
     const member = requireId(userId, 'member id');
-    await qqGroupService(api).setMemberMute(requireId(groupId, 'group id'), [durationSeconds === 0
+    await createEndpointOperation({ signal }).run(() => qqGroupService(api).setMemberMute(requireId(groupId, 'group id'), [durationSeconds === 0
             ? { op: 'del', member_openid: member, mute_expire_at: '' }
-            : { op: 'add', member_openid: member, mute_expire_at: new Date(Date.now() + durationSeconds * 1000).toISOString() }]);
+            : { op: 'add', member_openid: member, mute_expire_at: new Date(Date.now() + durationSeconds * 1000).toISOString() }]));
 }
 /** 移出一个成员；可选同时加入群黑名单。平台未确认 success 时抛错，不把未确认当成功。 */
-export async function kickQqGroupMember(api, groupId, userId, addToBlacklist = false) {
+export async function kickQqGroupMember(api, { groupId, userId, addToBlacklist = false, signal }) {
     const member = requireId(userId, 'member id');
-    const result = await qqGroupService(api).removeMembers(requireId(groupId, 'group id'), {
+    const result = await createEndpointOperation({ signal }).run(() => qqGroupService(api).removeMembers(requireId(groupId, 'group id'), {
         member_openids: [member],
         ...(addToBlacklist ? { add_to_member_blacklist: true } : {}),
-    });
+    }));
     if (result?.remove_members_result !== 'success')
         throw new Error('QQ did not confirm the member removal');
     return { blacklistFailed: addToBlacklist && (result.add_to_member_blacklist_fail_openids ?? []).includes(member) };
 }
 /** 自动审核用：机器人与目标成员的实时角色；平台只允许管理员处置普通成员（且非机器人）。 */
-export async function inspectQqGroupMember(api, groupId, userId, signal) {
+export async function inspectQqGroupMember(api, { groupId, userId, signal }) {
     signal.throwIfAborted();
-    const [self, member] = await Promise.all([qqGroupBotState(api, groupId), qqGroupMember(api, groupId, userId)]);
+    const [self, member] = await Promise.all([qqGroupBotState(api, { groupId, signal }), qqGroupMember(api, { groupId, userId, signal })]);
     signal.throwIfAborted();
     const role = member.member_openid === userId ? platformRole(member.member_role) : undefined;
     const joinedAt = parseQqTime(member.joined_at);
@@ -71,8 +72,8 @@ export async function inspectQqGroupMember(api, groupId, userId, signal) {
         ...(joinedAt ? { joinedAt } : {}),
     };
 }
-export async function moderateQqGroupMember(api, groupId, userId, action, signal, isActive) {
-    const member = await inspectQqGroupMember(api, groupId, userId, signal);
+export async function moderateQqGroupMember({ api, isActive }, { groupId, userId, action, signal }) {
+    const member = await inspectQqGroupMember(api, { groupId: groupId, userId: userId, signal: signal });
     signal.throwIfAborted();
     if (!isActive() || !member.canModerate)
         throw new Error('Group moderation permission is unavailable');
@@ -82,18 +83,18 @@ export async function moderateQqGroupMember(api, groupId, userId, action, signal
             || Date.now() - member.joinedAt > action.maxMembershipAgeMs) {
             throw new Error('Group membership no longer matches the approved newcomer window');
         }
-        await kickQqGroupMember(api, groupId, userId);
+        await kickQqGroupMember(api, { groupId, userId, signal });
         return;
     }
     if (!Number.isSafeInteger(action.durationSeconds) || action.durationSeconds <= 0) {
         throw new Error('Invalid group mute duration');
     }
-    await muteQqGroupMember(api, groupId, userId, Math.min(action.durationSeconds, QQ_GROUP_MUTE_MAX_SECONDS));
+    await muteQqGroupMember(api, { groupId: groupId, userId: userId, durationSeconds: Math.min(action.durationSeconds, QQ_GROUP_MUTE_MAX_SECONDS), signal });
 }
 /** ADR 0041 场景事实：一次群信息读取；官方群信息不含群主/管理员/全员禁言，留作 unknown。 */
-export async function inspectQqGroupScene(api, groupId, signal) {
+export async function inspectQqGroupScene(api, { groupId, signal }) {
     signal.throwIfAborted();
-    const info = await qqGroupService(api).getInfo(requireId(groupId, 'group id'));
+    const info = await createEndpointOperation({ signal }).run(() => qqGroupService(api).getInfo(requireId(groupId, 'group id')));
     signal.throwIfAborted();
     if (info?.group_openid && info.group_openid !== groupId)
         return {};
@@ -102,9 +103,9 @@ export async function inspectQqGroupScene(api, groupId, signal) {
     return { ...(name ? { name } : {}), ...(memberCount ? { memberCount } : {}) };
 }
 /** ADR 0041 成员事实：一次成员读取（群名片/头衔/禁言到期官方不提供）。 */
-export async function inspectQqGroupMemberProfile(api, groupId, userId, signal) {
+export async function inspectQqGroupMemberProfile(api, { groupId, userId, signal }) {
     signal.throwIfAborted();
-    const member = await qqGroupMember(api, groupId, userId);
+    const member = await qqGroupMember(api, { groupId, userId, signal });
     signal.throwIfAborted();
     if (member.member_openid !== userId)
         return {};

package/lib/i18n.js

@@ -2,8 +2,8 @@ import { createMessages } from 'zhin.js/i18n';
 export const messages = createMessages({
     bindTaskFailed: { 'zh-CN': '获取绑定任务失败: {error}', en: 'Could not create the binding task: {error}' },
     "kindPrompt": {
-        "zh-CN": "请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。",
-        "en": "Reply public or private to save .env and configuration together."
+        "zh-CN": "请回复 public（公域）或 private（私域），确认后保存账号；需手动启动。",
+        "en": "Reply public or private to save the account, then start it explicitly."
     },
     "cancelHint": {
         "zh-CN": "也可发 {command} 取消。",
@@ -18,8 +18,8 @@ export const messages = createMessages({
         "en": "⚠️ Endpoint “{id}” is waiting for public/private selection"
     },
     "endpointSaved": {
-        "zh-CN": "✅ 已按 botKind={kind} 将 endpoint「{id}」写入 .env 与 {file}。\nintents: {intents}。\n⚠️ 需重启 zhin 后新 endpoint 才会生效。",
-        "en": "✅ Saved endpoint “{id}” with botKind={kind} to .env and {file}.\nintents: {intents}.\n⚠️ Restart zhin to activate the new endpoint."
+        "zh-CN": "✅ 已按 botKind={kind} 保存账号「{id}」。\nintents: {intents}。\n尚未启动，请显式启动此账号。",
+        "en": "✅ Saved account “{id}” with botKind={kind}.\nintents: {intents}.\nThe account is inactive; start it explicitly."
     },
     "existingFlow": {
         "zh-CN": "已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先取消后再试",

package/lib/image-size.d.ts

@@ -17,4 +17,9 @@ export type ImageProbeFetch = (url: string, init: {
 /** 从图片文件头解析尺寸（PNG / GIF / JPEG / WebP）。 */
 export declare function imageSizeFromBytes(bytes: Uint8Array): QqImageSize | undefined;
 /** 读取公网图片文件头得到尺寸；网络错误、超时或格式不识别时返回 undefined。 */
-export declare function probeImageSize(url: string, fetchImpl?: ImageProbeFetch, timeoutMs?: number): Promise<QqImageSize | undefined>;
+export interface ImageProbeOptions {
+    readonly fetch?: ImageProbeFetch;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export declare function probeImageSize(url: string, { fetch: fetchImpl, timeoutMs, signal }?: ImageProbeOptions): Promise<QqImageSize | undefined>;

package/lib/image-size.js

@@ -82,12 +82,11 @@ async function readHead(response) {
     }
     return out;
 }
-/** 读取公网图片文件头得到尺寸；网络错误、超时或格式不识别时返回 undefined。 */
-export async function probeImageSize(url, fetchImpl = fetch, timeoutMs = PROBE_TIMEOUT_MS) {
+export async function probeImageSize(url, { fetch: fetchImpl = fetch, timeoutMs = PROBE_TIMEOUT_MS, signal } = {}) {
     try {
         const response = await fetchImpl(url, {
             headers: { Range: `bytes=0-${PROBE_BYTES - 1}` },
-            signal: AbortSignal.timeout(timeoutMs),
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
         });
         if (!response.ok)
             return undefined;

package/lib/index.d.ts

@@ -2,8 +2,9 @@ export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, res
 export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields, parseQqBotKind, resolveQqIntents, type QqBotKind, type QqIntent, } from './qq-intents.js';
 export { formatOutbound, formatOutboundMessages, collectOutboundImageSizes, type FormatOutboundMessagesOptions, resolveMediaFile, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
 export { imageSizeFromBytes, probeImageSize, type QqImageSize } from './image-size.js';
-export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqOfficialApi, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
-export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
-export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-export { qqClient, type QqClientEventMap } from './client.js';
+export { QqHttpEndpoint, QqWebsocketEndpoint, type QqBotTransport, type QqOfficialApi, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
+export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, qqHttpBotOptions, type QqWebhookHandler, } from './webhook.js';
+export { bindQqBotInboundEvents, qqWebsocketBotOptions, normalizeQqMessage, } from './ws.js';
+export { type QqClientEventMap } from './client.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';
+export { QqAdapter } from './adapter.js';

package/lib/index.js

@@ -3,7 +3,7 @@ export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields,
 export { formatOutbound, formatOutboundMessages, collectOutboundImageSizes, resolveMediaFile, } from './outbound.js';
 export { imageSizeFromBytes, probeImageSize } from './image-size.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
-export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
-export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-export { qqClient } from './client.js';
+export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, qqHttpBotOptions, } from './webhook.js';
+export { bindQqBotInboundEvents, qqWebsocketBotOptions, normalizeQqMessage, } from './ws.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';
+export { QqAdapter } from './adapter.js';

package/lib/interaction.js

@@ -12,5 +12,5 @@ export function normalizeQqInteraction(raw) {
     if (!kind || !id || !actor || (kind === 'channel' && !event.guild_id))
         return null;
     const sourceMessageId = typeof resolved.message_id === 'string' && resolved.message_id ? resolved.message_id : undefined;
-    return { message: { id: event.notice_id, content: '', channelKind: kind, channelId: id, authorId: actor, authorName: '', timestamp: Date.now(), ...(event.guild_id ? { guildId: event.guild_id } : {}), segments: [{ type: 'action', data: { payload: resolved.button_data } }] }, ...(sourceMessageId ? { sourceMessageId } : {}), ack: () => event.reply(0) };
+    return { message: { event: raw, id: event.notice_id, content: '', channelKind: kind, channelId: id, authorId: actor, authorName: '', timestamp: Date.now(), ...(event.guild_id ? { guildId: event.guild_id } : {}), segments: [{ type: 'action', data: { payload: resolved.button_data } }] }, ...(sourceMessageId ? { sourceMessageId } : {}), ack: () => event.reply(0) };
 }

package/lib/outbound.d.ts

@@ -37,4 +37,7 @@ export declare function formatOutboundMessages(payload: unknown, options?: Forma
  * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，
  * 对 http(s) URL 图片并发读取文件头；失败的图片不入表，formatOutboundMessages 会降级。
  */
-export declare function collectOutboundImageSizes(payload: unknown, probe?: (url: string) => Promise<QqImageSize | undefined>): Promise<Map<string, QqImageSize>>;
+export declare function collectOutboundImageSizes(payload: unknown, { probe, signal }?: {
+    readonly probe?: (url: string) => Promise<QqImageSize | undefined>;
+    readonly signal?: AbortSignal;
+}): Promise<Map<string, QqImageSize>>;

package/lib/outbound.js

@@ -348,7 +348,7 @@ export function formatOutboundMessages(payload, options = {}) {
  * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，
  * 对 http(s) URL 图片并发读取文件头；失败的图片不入表，formatOutboundMessages 会降级。
  */
-export async function collectOutboundImageSizes(payload, probe = (url) => probeImageSize(url)) {
+export async function collectOutboundImageSizes(payload, { probe, signal } = {}) {
     const sizes = new Map();
     const segments = toSegmentList(payload).filter((item) => typeof item !== 'string');
     if (!segments.some((item) => MARKDOWN_MESSAGE_TYPES.has(item.type)))
@@ -360,7 +360,8 @@ export async function collectOutboundImageSizes(payload, probe = (url) => probeI
             urls.add(media.value);
     }
     await Promise.all([...urls].map(async (url) => {
-        const size = await probe(url);
+        signal?.throwIfAborted();
+        const size = await (probe ? probe(url) : probeImageSize(url, { signal }));
         if (size)
             sizes.set(url, size);
     }));

package/lib/protocol.d.ts

@@ -46,6 +46,8 @@ export interface ResolvedQqHttpConfig {
 export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
 export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
 export interface QqInboundMessage {
+    readonly event?: unknown;
+    readonly platformSentAt?: number;
     readonly id: string;
     readonly content: string;
     readonly channelKind: QqChannelKind;

package/lib/qq-console-spec.js

@@ -1,7 +1,18 @@
 export const qqConsoleSpec = {
     adapterKey: 'qq',
     adapterDisplayName: 'QQ',
-    fields: [],
+    fields: [
+        { key: 'appid', required: true, description: 'QQ appid' },
+        { key: 'secret', required: true, env: true, description: 'QQ app secret' },
+        { key: 'mode', description: 'websocket, webhook or middleware' },
+        { key: 'sandbox', type: 'boolean', description: 'QQ sandbox environment' },
+        { key: 'botKind', description: 'public or private; existing explicit intents remain authoritative' },
+        { key: 'accessTokenUrl', description: 'Configured access-token API URL' },
+        { key: 'gatewayUrl', description: 'Configured Gateway discovery URL' },
+        { key: 'webhookPath', description: 'Local webhook route' },
+        { key: 'streamProxy.port', type: 'number', description: 'Configured Gateway loopback proxy port' },
+        { key: 'streamProxy.serverName', description: 'Expected Gateway TLS hostname' },
+    ],
     canAdd: false,
     canRemove: true,
     docsUrl: 'https://zhin.js.org/adapters/qq',

package/lib/qq-console.d.ts

@@ -1,11 +1,10 @@
-import { type QqEndpointWriteResult } from './qq-endpoint-write.js';
+import { type QqEndpointWriteResult, type QqEndpointSavePort } from './qq-endpoint-write.js';
 import type { QqRuntimeState } from './qq-runtime-state.js';
-import type { EndpointConfigurationStore } from 'zhin.js/adapter';
 /** 启动 Console 扫码；resolve 时二维码链接已就绪。 */
 export declare function startQqConsoleBind(state: QqRuntimeState, id?: string): Promise<{
     readonly url: string;
 }>;
-/** 扫码成功后选择公域 / 私域并写回配置。 */
-export declare function completeQqConsoleBind(state: QqRuntimeState, store: EndpointConfigurationStore, kindValue: unknown): Promise<QqEndpointWriteResult>;
+/** 扫码成功后选择公域 / 私域并保存未启动账号。 */
+export declare function completeQqConsoleBind(state: QqRuntimeState, save: QqEndpointSavePort, kindValue: unknown): Promise<QqEndpointWriteResult>;
 /** 取消 Console 绑定（也可用于收拾聊天命令发起的流程）。 */
 export declare function cancelQqConsoleBind(state: QqRuntimeState): boolean;

package/lib/qq-console.js

@@ -3,10 +3,11 @@
  * 搬到 Console 页面。
  *
  * - `start` 返回扫码链接；后续状态写入 `state.consoleBind`，页面轮询 status。
- * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再一次性写 `.env` + 配置。
+ * - 扫码成功后凭据只留在内存，等页面选择公域 / 私域再通过捕获的所属 Adapter CAS 保存。
  * - 与聊天命令共享 `state.bindFlow` 单例，同一时间只允许一个绑定流程。
  */
 import { PluginConsoleRpcError } from 'zhin.js';
+import { AdapterManagementError } from 'zhin.js/adapter';
 import { startQqBindFlow } from './qq-bind-flow.js';
 import { writeQqEndpointWithBotKind } from './qq-endpoint-write.js';
 import { parseQqBotKind } from './qq-intents.js';
@@ -81,8 +82,8 @@ export function startQqConsoleBind(state, id) {
         state.bindFlow = { id: endpointId, stop, locale: 'zh-CN' };
     });
 }
-/** 扫码成功后选择公域 / 私域并写回配置。 */
-export async function completeQqConsoleBind(state, store, kindValue) {
+/** 扫码成功后选择公域 / 私域并保存未启动账号。 */
+export async function completeQqConsoleBind(state, save, kindValue) {
     const pending = state.consoleBind?.pending;
     if (!pending) {
         throw new PluginConsoleRpcError('conflict', '还没有扫码成功，请先扫码绑定');
@@ -92,12 +93,20 @@ export async function completeQqConsoleBind(state, store, kindValue) {
         throw new PluginConsoleRpcError('invalid_input', '请选择公域（public）或私域（private）');
     }
     try {
-        const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, store);
+        const result = await writeQqEndpointWithBotKind({ ...pending, botKind }, save);
         state.consoleBind = null;
+        state.consoleAdmission = null;
         return result;
     }
-    catch {
-        throw new PluginConsoleRpcError('unavailable', '写入配置失败，请检查配置文件和 .env 的权限');
+    catch (error) {
+        if (error instanceof PluginConsoleRpcError)
+            throw error;
+        const code = error instanceof AdapterManagementError ? error.code : 'unavailable';
+        if (code === 'commit_unknown')
+            throw new PluginConsoleRpcError('commit_unknown', '提交结果未知，请刷新核实，勿重复提交');
+        if (code === 'conflict' || code === 'duplicate_entry' || code === 'closed')
+            throw new PluginConsoleRpcError('conflict', '账号清单已变化，请刷新核实');
+        throw new PluginConsoleRpcError('unavailable', '账号配置未能保存，请刷新状态');
     }
 }
 /** 取消 Console 绑定（也可用于收拾聊天命令发起的流程）。 */
@@ -112,5 +121,6 @@ export function cancelQqConsoleBind(state) {
     state.bindFlow = null;
     state.pendingBotKind = null;
     state.consoleBind = null;
+    state.consoleAdmission = null;
     return active;
 }

package/lib/qq-endpoint-write.d.ts

@@ -1,22 +1,18 @@
-/**
- * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
- * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
- *
- * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
- */
-import { type EndpointConfigurationStore } from 'zhin.js/adapter';
+/** A validated QR result is saved through its owning Adapter's single CAS admission. */
+import type { AdapterMutationResult } from 'zhin.js/adapter';
 import { type QqBotKind } from './qq-intents.js';
+import type { QqEndpointConfig } from './protocol.js';
 export interface QqEndpointWriteInput {
     readonly endpointId: string;
     readonly appId: string;
     readonly appSecret: string;
     readonly botKind: QqBotKind;
 }
+export type QqEndpointSavePort = (configuration: QqEndpointConfig) => Promise<AdapterMutationResult>;
 export interface QqEndpointWriteResult {
-    readonly filePath: string;
     readonly endpointId: string;
     readonly botKind: QqBotKind;
     readonly intents: readonly string[];
+    readonly mutation: AdapterMutationResult;
 }
-/** 写回 `.env` + `zhin.config.yml`；失败时抛原错误，由调用方决定文案。 */
-export declare function writeQqEndpointWithBotKind(input: QqEndpointWriteInput, store: EndpointConfigurationStore): Promise<QqEndpointWriteResult>;
+export declare function writeQqEndpointWithBotKind(input: QqEndpointWriteInput, save: QqEndpointSavePort): Promise<QqEndpointWriteResult>;

package/lib/qq-endpoint-write.js

@@ -1,34 +1,7 @@
-/**
- * QQ endpoint 配置写回：扫码成功后把 appId / appSecret 写进 `.env`，
- * 配置里只保留 `${ENV}` 引用，并按公域 / 私域展开 intents。
- *
- * 命令（`qq endpoint add`）与 Console 扫码绑定共用这一处实现。
- */
-import { buildEndpointEnvKey } from 'zhin.js/adapter';
 import { defaultQqEndpointIntentFields } from './qq-intents.js';
-/** 写回 `.env` + `zhin.config.yml`；失败时抛原错误，由调用方决定文案。 */
-export async function writeQqEndpointWithBotKind(input, store) {
-    const appidKey = buildEndpointEnvKey('qq', input.endpointId, 'appid');
-    const secretKey = buildEndpointEnvKey('qq', input.endpointId, 'secret');
-    const intentFields = defaultQqEndpointIntentFields(input.botKind);
-    const { filePath } = await store.add({
-        adapterKey: 'qq',
-        entry: {
-            id: input.endpointId,
-            appid: `\${${appidKey}}`,
-            secret: `\${${secretKey}}`,
-            botKind: intentFields.botKind,
-            intents: [...intentFields.intents],
-        },
-        environment: {
-            [appidKey]: input.appId,
-            [secretKey]: input.appSecret,
-        },
-    });
-    return {
-        filePath,
-        endpointId: input.endpointId,
-        botKind: intentFields.botKind,
-        intents: intentFields.intents,
-    };
+export async function writeQqEndpointWithBotKind(input, save) {
+    const fields = defaultQqEndpointIntentFields(input.botKind);
+    const mutation = await save({ id: input.endpointId, appid: input.appId, secret: input.appSecret,
+        botKind: fields.botKind, intents: [...fields.intents] });
+    return { endpointId: input.endpointId, botKind: fields.botKind, intents: fields.intents, mutation };
 }

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

@@ -1,7 +1,4 @@
-export interface QqRunningEndpoint {
-    id: string;
-    mode: string;
-}
+import type { QqEndpointSavePort } from './qq-endpoint-write.js';
 export interface QqBindFlowHandle {
     /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
     id?: string;
@@ -11,10 +8,10 @@ export interface QqBindFlowHandle {
     readonly commandHeads?: readonly string[];
 }
 /**
- * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
- * （提前写 .env 会触发 HMR，冲掉 pending。）
+ * 扫码成功后暂存在内存：确认公域/私域后调用发起时捕获的所属 Adapter CAS。
  */
 export interface QqPendingBotKind {
+    readonly save: QqEndpointSavePort;
     readonly endpointId: string;
     readonly appId: string;
     readonly appSecret: string;
@@ -42,13 +39,17 @@ export interface QqConsoleBindState {
     };
 }
 export interface QqRuntimeState {
-    /** 当前 generation 已成功创建的 endpoint（id → 描述） */
-    readonly endpoints: Map<string, QqRunningEndpoint>;
-    /** 全局单例：同一时间只允许一个扫码绑定流程 */
+    /** Snapshot checked when the QR flow began, never a second account directory. */
+    consoleAdmission: Readonly<{
+        adapterId: string;
+        generation: number;
+        revision: number | null;
+    }> | null;
+    /** 同一插件 generation 内只允许一个扫码绑定流程 */
     bindFlow: QqBindFlowHandle | null;
     /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
     pendingBotKind: QqPendingBotKind | null;
-    /** Console 页面的扫码绑定进度（与 bindFlow 共享单例）。 */
+    /** Console 页面的扫码绑定进度（与 bindFlow 共享同一插件瞬态流程）。 */
     consoleBind: QqConsoleBindState | null;
 }
 export declare function createQqRuntimeState(): QqRuntimeState;

package/lib/qq-runtime-state.js

@@ -1,15 +1,14 @@
 /**
- * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
- * 扫码绑定 / 待选 botKind 流程。由 plugin.ts setup() provide，
- * adapter create 与 commands / middleware 通过 use(qqRuntimeStateToken) 共享。
+ * QQ 插件实例的瞬态扫码绑定 / 待选 botKind 流程。
+ * 账号目录与 SDK 生命周期只由所属 Adapter 持有；此处不保存 Endpoint Map。
  */
 import { createToken } from 'zhin.js';
 export function createQqRuntimeState() {
     return {
-        endpoints: new Map(),
+        consoleAdmission: null,
         bindFlow: null,
         pendingBotKind: null,
         consoleBind: null,
     };
 }
-export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');
+export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ transient QR binding state');

package/lib/qq-send.d.ts

@@ -1,16 +1,4 @@
-/**
- * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
- * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
- *
- * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
- *    newest usable msg_id / event_id) with its own msg_seq.
- * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
- *    an active message. Never after a timeout: the first request may have been delivered.
- * 3. Markdown not allowed: resend the same message as plain text.
- * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
- *    for a while and fail fast instead of calling the platform again.
- */
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { type ConversationRef } from '@zhin.js/im-contract';
 import type { QqOutboundMessage } from './outbound.js';
 import { type QqActiveMessageGate, type QqPassiveReplyLedger, type QqReplySource } from './passive-reply.js';
 import type { QqBotTransport } from './ws.js';
@@ -20,9 +8,14 @@ export interface QqSendContext {
     readonly activeGate: QqActiveMessageGate;
     readonly log: (fields: Record<string, string | number | undefined>) => void;
 }
+export interface QqMessagesRequest {
+    readonly conversation: ConversationRef;
+    readonly messages: readonly QqOutboundMessage[];
+    readonly signal?: AbortSignal;
+}
 /** The reply segment the payload already names, as a passive source. */
 export declare function explicitReplySource(message: QqOutboundMessage): QqReplySource | undefined;
 /** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
 export declare function markdownAsText(message: QqOutboundMessage): QqOutboundMessage | undefined;
 /** Sends every message of one delivery in order; returns the last platform result. */
-export declare function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown>;
+export declare function sendQqMessages(context: QqSendContext, { conversation, messages, signal }: QqMessagesRequest): Promise<unknown>;

package/lib/qq-send.js

@@ -1,3 +1,16 @@
+/**
+ * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
+ * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
+ *
+ * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
+ *    newest usable msg_id / event_id) with its own msg_seq.
+ * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
+ *    an active message. Never after a timeout: the first request may have been delivered.
+ * 3. Markdown not allowed: resend the same message as plain text.
+ * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
+ *    for a while and fail fast instead of calling the platform again.
+ */
+import { createEndpointOperation } from 'zhin.js/adapter';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { QQ_ACTIVE_UNAVAILABLE_CODES, QQ_MARKDOWN_DENIED_CODES, QQ_PASSIVE_SOURCE_CODES, } from './passive-reply.js';
 import { qqDeliveryFailure } from './delivery-error.js';
@@ -39,7 +52,7 @@ export function markdownAsText(message) {
     const kept = parts.filter((part) => typeof part !== 'string' && (part.type === 'reply' || part.type === 'at'));
     return text ? [...kept, text] : undefined;
 }
-function dispatch(bot, kind, id, message, source, options) {
+function dispatch(bot, { kind, id, message, source, options }) {
     switch (kind) {
         case 'private': return bot.sendPrivateMessage(id, message, source, options);
         case 'group': return bot.sendGroupMessage(id, message, source, options);
@@ -54,14 +67,14 @@ function platformCode(error) {
     return qqDeliveryFailure(error).diagnostic.platformCode;
 }
 /** Sends one message, passive if possible; returns the platform result. */
-async function sendOne(context, kind, id, message) {
-    const passive = (body, grant) => dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+async function sendOne(context, { kind, id, message }) {
+    const passive = (body, grant) => context.operation.run(() => dispatch(context.bot, { kind, id, message: body, source: grant.source, options: { msgSeq: grant.msgSeq } }));
     const active = async (body) => {
         if (context.activeGate.blocked(kind, id)) {
             throw new EndpointDeliveryError('platform_rejected', 'QQ active messages are unavailable for this conversation', 'not_sent');
         }
         try {
-            return await dispatch(context.bot, kind, id, body);
+            return await context.operation.run(() => dispatch(context.bot, { kind, id, message: body }));
         }
         catch (error) {
             const code = platformCode(error);
@@ -100,10 +113,11 @@ async function sendOne(context, kind, id, message) {
     }
 }
 /** Sends every message of one delivery in order; returns the last platform result. */
-export async function sendQqMessages(context, conversation, messages) {
+export async function sendQqMessages(context, { conversation, messages, signal }) {
     const kind = qqOutboundKind(conversation);
+    const execution = { ...context, operation: createEndpointOperation({ signal }) };
     let result;
     for (const message of messages)
-        result = await sendOne(context, kind, conversation.id, message);
+        result = await sendOne(execution, { kind, id: conversation.id, message });
     return result;
 }

package/lib/webhook.d.ts

@@ -1,11 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Bot, ReceiverMode } from 'qq-official-bot';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import type { ResolvedQqHttpConfig } from './protocol.js';
-import type { QqBotTransport } from './ws.js';
-export type QqHttpBotTransport = QqBotTransport & {
-    middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
-};
-export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+export type QqHttpBotTransport = Bot<ReceiverMode.MIDDLEWARE, 'koa'>;
 export interface QqWebhookHandler {
     readonly config: ResolvedQqHttpConfig;
     getBot(): (QqHttpBotTransport & {
@@ -15,4 +12,4 @@ export interface QqWebhookHandler {
 export declare function registerQqWebhookRoutes(http: HttpHost, handler: QqWebhookHandler): HttpRouteRegistration[];
 export declare function handleQqWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: QqWebhookHandler): Promise<void>;
 export declare function readRequestBodyText(request: IncomingMessage): Promise<string>;
-export declare function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport;
+export declare function qqHttpBotOptions(config: ResolvedQqHttpConfig): ConstructorParameters<typeof Bot<ReceiverMode.MIDDLEWARE, 'koa'>>[0];