@zhin.js/adapter-qq 8.0.0 → 8.0.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @zhin.js/adapter-qq
 
+## 8.0.1
+
+### Patch Changes
+
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - @zhin.js/middleware@1.0.13
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
 ## 8.0.0
 
 ### Patch Changes

package/README.md

@@ -20,7 +20,7 @@ pnpm add @zhin.js/adapter-qq
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/qq.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
@@ -144,6 +144,15 @@ Markdown + 指令按钮组。按钮值与手动输入共用同一解析入口，
 不支持原生按钮的 Adapter 会在 Core 中把同一 keyboard 语义降级为编号列表，并保存数字到
 payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `MediaRef` 出站链投递。
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Gateway Identify 后断线 | 检查 `botKind` 与 intents；公域机器人不要订阅受限 intent |
+| 二维码绑定后仍离线 | 在 Console 登录待办确认结果，并检查 App ID、Secret 与 Token |
+| Webhook 无事件 | 检查 HTTP Host、公网路径、平台回调与签名参数 |
+| Markdown/按钮发送失败 | 检查平台模板与权限，并按 Endpoint 能力降级 |
+
 ## 许可证
 
 MIT License

package/adapters/qq.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/qq.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { QqHttpEndpoint, QqWebsocketEndpoint } from "../lib/endpoint.js";
 import { resolveQqConfig, } from "../lib/protocol.js";
@@ -22,8 +21,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveQqConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
         const state = context.use(qqRuntimeStateToken);
         state.endpoints.set(config.id, {
@@ -35,14 +32,10 @@ export default defineAdapter({
         const endpoint = config.mode === 'websocket'
             ? new QqWebsocketEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 config,
             })
             : new QqHttpEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });

package/adapters/qq.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/qq.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { QqHttpEndpoint, QqWebsocketEndpoint } from '../src/endpoint.js';
 import {
@@ -43,8 +42,6 @@ export default defineAdapter<QqAdapterConfig>({
   },
   create(context) {
     const config = resolveQqConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
     const state = context.use(qqRuntimeStateToken);
     state.endpoints.set(config.id, {
@@ -56,14 +53,10 @@ export default defineAdapter<QqAdapterConfig>({
     const endpoint = config.mode === 'websocket'
       ? new QqWebsocketEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         config,
       })
       : new QqHttpEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });

package/agent/tools/add_role.ts

@@ -1,23 +1,21 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; channel_id: string; user_id: string; role_id: string }>({
   description: '给成员添加 QQ 频道角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
     channel_id: z.string().describe('子频道 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, channel_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.addMemberRole(guild_id, channel_id, user_id, role_id);
+  async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
     return { success, message: success ? '已给成员添加角色' : '操作失败' };
   },
 });

package/agent/tools/channel_info.ts

@@ -1,19 +1,17 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; channel_id: string }>({
+export default defineAgentTool<{ channel_id: string }>({
   description: '获取 QQ 频道中指定子频道的详细信息',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     channel_id: z.string().describe('子频道 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('guild_admin')],
-  async execute({ endpoint_id, channel_id  }: { endpoint_id: string; channel_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    return endpoint.getChannelInfo(channel_id);
+  async execute({ channel_id  }: { channel_id: string }, context) {
+    const client = context.$client;
+    return client.getChannelInfo(channel_id);
   },
 });

package/agent/tools/create_role.ts

@@ -1,22 +1,20 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; name: string; color?: number }>({
+export default defineAgentTool<{ guild_id: string; name: string; color?: number }>({
   description: '创建 QQ 频道角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
     name: z.string().describe('角色名称'),
     color: z.number().optional().describe('颜色（RGB 十进制数值）'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('guild_owner')],
-  async execute({ endpoint_id, guild_id, name, color  }: { endpoint_id: string; guild_id: string; name: string; color?: number }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const role = await endpoint.createGuildRole(guild_id, name, color);
+  async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {
+    const client = context.$client;
+    const role = await client.createGuildRole(guild_id, name, color);
     return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
   },
 });

package/agent/tools/list_channels.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+export default defineAgentTool<{ guild_id: string }>({
   description: '获取 QQ 频道下的子频道列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('manage_channels')],
-  async execute({ endpoint_id, guild_id  }: { endpoint_id: string; guild_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const channels = await endpoint.getChannels(guild_id);
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const channels = await client.getChannels(guild_id);
     return { channels, count: channels.length };
   },
 });

package/agent/tools/list_guilds.ts

@@ -1,17 +1,14 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string }>({
+export default defineAgentTool<Record<string, never>>({
   description: '获取 QQ 频道列表',
-  inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
-  }),
-  platforms: ['qq'],
+  inputSchema: z.object({}),
+  adapter: 'qq',
   tags: ['qq'],
-  async execute({ endpoint_id  }: { endpoint_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const guilds = await endpoint.getGuilds();
+  async execute(_input, context) {
+    const client = context.$client;
+    const guilds = await client.getGuilds();
     return { guilds, count: guilds.length };
   },
 });

package/agent/tools/list_roles.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+export default defineAgentTool<{ guild_id: string }>({
   description: '获取 QQ 频道角色列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id  }: { endpoint_id: string; guild_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const roles = await endpoint.getGuildRoles(guild_id);
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const roles = await client.getGuildRoles(guild_id);
     return { roles, count: roles.length };
   },
 });

package/agent/tools/member_detail.ts

@@ -1,20 +1,18 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string }>({
+export default defineAgentTool<{ guild_id: string; user_id: string }>({
   description: '获取 QQ 频道中指定成员的详细信息',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
     user_id: z.string().describe('用户 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('guild_admin')],
-  async execute({ endpoint_id, guild_id, user_id  }: { endpoint_id: string; guild_id: string; user_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    return endpoint.getGuildMember(guild_id, user_id);
+  async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {
+    const client = context.$client;
+    return client.getGuildMember(guild_id, user_id);
   },
 });

package/agent/tools/remove_role.ts

@@ -1,23 +1,21 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getQqAgentDeps } from '../../src/qq-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; channel_id: string; user_id: string; role_id: string }>({
   description: '移除成员的 QQ 频道角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('频道 ID'),
     channel_id: z.string().describe('子频道 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['qq'],
+  adapter: 'qq',
   tags: ['qq'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, channel_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; channel_id: string; user_id: string; role_id: string }) {
-    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.removeMemberRole(guild_id, channel_id, user_id, role_id);
+  async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
     return { success, message: success ? '已移除成员的角色' : '操作失败' };
   },
 });

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { QqInboundMessage } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly qq: {
+            readonly client: QqBotTransport;
+            readonly events: QqClientEventMap;
+        };
+    }
+}
+export declare const qqClient: import("@zhin.js/adapter").EndpointClientToken<QqBotTransport, QqClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const qqClient = defineEndpointClient('qq');

package/lib/endpoint.d.ts

@@ -1,27 +1,26 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
-import { type CreateQqHttpBot } from './webhook.js';
-import { type CreateQqBot } from './ws.js';
+import { type CreateQqHttpBot, type QqHttpBotTransport } from './webhook.js';
+import { type CreateQqBot, type QqBotTransport } from './ws.js';
 export type { CreateQqBot, QqBotTransport } from './ws.js';
 export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
 export interface QqEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedQqWebsocketConfig;
     readonly createBot?: CreateQqBot;
 }
-export declare class QqWebsocketEndpoint implements EndpointInstance {
+export declare class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     #private;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: QqEndpointOptions);
+    get client(): QqBotTransport;
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name(): string;
     start(): Promise<void>;
@@ -32,29 +31,20 @@ export declare class QqWebsocketEndpoint implements EndpointInstance {
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: QqInboundMessage): void;
-    getGuilds(): Promise<unknown[]>;
-    getChannels(guildId: string): Promise<unknown[]>;
-    getChannelInfo(channelId: string): Promise<unknown>;
-    getGuildMember(guildId: string, userId: string): Promise<unknown>;
-    getGuildRoles(guildId: string): Promise<unknown[]>;
-    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
-    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
-    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
 }
 export interface QqHttpEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedQqHttpConfig;
     readonly createBot?: CreateQqHttpBot;
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
-export declare class QqHttpEndpoint implements EndpointInstance {
+export declare class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     #private;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: QqHttpEndpointOptions);
+    get client(): QqHttpBotTransport;
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name(): string;
     start(): Promise<void>;
@@ -64,12 +54,4 @@ export declare class QqHttpEndpoint implements EndpointInstance {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     admit(msg: QqInboundMessage): void;
-    getGuilds(): Promise<unknown[]>;
-    getChannels(guildId: string): Promise<unknown[]>;
-    getChannelInfo(channelId: string): Promise<unknown>;
-    getGuildMember(guildId: string, userId: string): Promise<unknown>;
-    getGuildRoles(guildId: string): Promise<unknown[]>;
-    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
-    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
-    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
 }

package/lib/endpoint.js

@@ -1,29 +1,32 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
 import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { formatOutbound } from './outbound.js';
-import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
 import { bindQqBotSideEvents, receiveQqSideEvent, } from './side-event-dispatch.js';
-export class QqWebsocketEndpoint {
+export class QqWebsocketEndpoint extends Endpoint {
     #logger;
     #options;
     #createBot;
     #bot = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
-    management = createQqEndpointManagement(this);
+    management = createQqEndpointManagement(() => this.#requireBot());
     control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
+    get client() {
+        return this.#requireBot();
+    }
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name() {
         return this.#options.config.id;
@@ -33,7 +36,6 @@ export class QqWebsocketEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
             this.#bot = this.#createBot(this.#options.config);
             this.#bindBot(this.#bot);
             await this.#bot.start();
@@ -54,8 +56,6 @@ export class QqWebsocketEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#bot) {
             try {
                 this.#bot.removeAllListeners();
@@ -130,7 +130,7 @@ export class QqWebsocketEndpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content,
@@ -156,38 +156,25 @@ export class QqWebsocketEndpoint {
             }));
         });
     }
-    getGuilds() {
-        return this.#requireBot().getGuilds();
-    }
-    getChannels(guildId) {
-        return this.#requireBot().getChannels(guildId);
-    }
-    getChannelInfo(channelId) {
-        return this.#requireBot().getChannelInfo(channelId);
-    }
-    getGuildMember(guildId, userId) {
-        return this.#requireBot().getGuildMember(guildId, userId);
-    }
-    getGuildRoles(guildId) {
-        return this.#requireBot().getGuildRoles(guildId);
-    }
-    createGuildRole(guildId, name, color) {
-        return this.#requireBot().createGuildRole(guildId, name, color);
-    }
-    addMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-    }
-    removeMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-    }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+            this.#emitPlatformEvent(eventName, raw);
+            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
     #requireBot() {
@@ -197,7 +184,7 @@ export class QqWebsocketEndpoint {
     }
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
-export class QqHttpEndpoint {
+export class QqHttpEndpoint extends Endpoint {
     #logger;
     #options;
     #createBot;
@@ -205,14 +192,17 @@ export class QqHttpEndpoint {
     #routeReleases = [];
     #open = false;
     #started = false;
-    #unregisterAgent;
-    management = createQqEndpointManagement(this);
+    management = createQqEndpointManagement(() => this.#requireBot());
     control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
+    get client() {
+        return this.#requireBot();
+    }
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name() {
         return this.#options.config.id;
@@ -222,7 +212,6 @@ export class QqHttpEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
             this.#setupRoutes();
             this.#bot = this.#createBot(this.#options.config);
             this.#bindBot(this.#bot);
@@ -245,8 +234,6 @@ export class QqHttpEndpoint {
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#bot) {
             try {
                 this.#bot.removeAllListeners();
@@ -320,7 +307,7 @@ export class QqHttpEndpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content,
@@ -346,30 +333,6 @@ export class QqHttpEndpoint {
             }));
         });
     }
-    getGuilds() {
-        return this.#requireBot().getGuilds();
-    }
-    getChannels(guildId) {
-        return this.#requireBot().getChannels(guildId);
-    }
-    getChannelInfo(channelId) {
-        return this.#requireBot().getChannelInfo(channelId);
-    }
-    getGuildMember(guildId, userId) {
-        return this.#requireBot().getGuildMember(guildId, userId);
-    }
-    getGuildRoles(guildId) {
-        return this.#requireBot().getGuildRoles(guildId);
-    }
-    createGuildRole(guildId, name, color) {
-        return this.#requireBot().createGuildRole(guildId, name, color);
-    }
-    addMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-    }
-    removeMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-    }
     #setupRoutes() {
         this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
             config: this.#options.config,
@@ -378,12 +341,23 @@ export class QqHttpEndpoint {
     }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+            this.#emitPlatformEvent(eventName, raw);
+            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
     #requireBot() {
@@ -392,18 +366,19 @@ export class QqHttpEndpoint {
         return this.#bot;
     }
 }
-function createQqEndpointManagement(endpoint) {
+function createQqEndpointManagement(requireClient) {
     return Object.freeze({
         async listChannels() {
             const channels = [];
-            const guilds = await endpoint.getGuilds();
+            const client = requireClient();
+            const guilds = await client.getGuilds();
             for (const guildValue of Array.isArray(guilds) ? guilds : []) {
                 const guild = asRecord(guildValue);
                 const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
                 if (!guildId)
                     continue;
                 const guildName = String(guild.name ?? guild.guild_name ?? guildId);
-                const rows = await endpoint.getChannels(guildId);
+                const rows = await client.getChannels(guildId);
                 for (const channelValue of Array.isArray(rows) ? rows : []) {
                     const channel = asRecord(channelValue);
                     const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');

package/lib/index.d.ts

@@ -4,5 +4,5 @@ export { formatOutbound, resolveMediaFile, type QqOutboundElem, type QqOutboundM
 export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, 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 { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, type QqAgentDeps, type QqAgentEndpoint, } from './qq-agent-deps.js';
+export { qqClient, type QqClientEventMap } from './client.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -4,5 +4,5 @@ export { formatOutbound, resolveMediaFile, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, } from './qq-agent-deps.js';
+export { qqClient } from './client.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

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

@@ -42,4 +42,4 @@ export declare function runQqEndpointRemove(_state: QqRuntimeState, id: string,
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
  */
-export declare const qqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const qqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/side-event-dispatch.d.ts

@@ -1,4 +1,4 @@
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { type getAdapterLogger } from '@zhin.js/logger';
 export interface QqSideEventCaller {
     approveGroupJoinRequest?(groupId: string, userId: string, options: {
@@ -10,4 +10,4 @@ export interface QqSideEventCaller {
 export declare function bindQqBotSideEvents(bot: {
     on(event: string, listener: (...args: unknown[]) => void): void;
 }, dispatch: (eventName: string, raw: unknown) => void): void;
-export declare function receiveQqSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;
+export declare function receiveQqSideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -51,8 +51,8 @@ function toOneBotLikeRaw(eventName, raw) {
     }
     return null;
 }
-export function receiveQqSideEvent(sideEvents, endpointKey, caller, eventName, raw, logger) {
-    if (!sideEvents)
+export function receiveQqSideEvent(emit, endpointKey, caller, eventName, raw, logger) {
+    if (!emit)
         return;
     const mapped = toOneBotLikeRaw(eventName, raw);
     if (!mapped)
@@ -61,7 +61,7 @@ export function receiveQqSideEvent(sideEvents, endpointKey, caller, eventName, r
     const joinRaw = isJoinRequest && raw && typeof raw === 'object'
         ? raw
         : undefined;
-    void receiveOneBotLikeSideEvent(sideEvents, {
+    void receiveOneBotLikeSideEvent(emit, {
         adapter: 'qq',
         endpointKey,
         platform: 'qq',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "8.0.0",
+  "version": "8.0.1",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,21 +35,22 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.3"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/permission": "1.0.4"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/middleware": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/middleware": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -73,9 +74,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/host-http": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "files": [
     "adapters",

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+import type { QqInboundMessage } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+
+export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly qq: {
+      readonly client: QqBotTransport;
+      readonly events: QqClientEventMap;
+    };
+  }
+}
+
+export const qqClient = defineEndpointClient<QqBotTransport, QqClientEventMap>('qq');

package/src/endpoint.ts

@@ -1,3 +1,4 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
@@ -5,16 +6,13 @@ import {
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointChannel,
-  type EndpointInstance,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { formatOutbound } from './outbound.js';
-import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import {
   formatInboundContent,
   parseCompoundMessageId,
@@ -50,13 +48,11 @@ export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
 
 export interface QqEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedQqWebsocketConfig;
   readonly createBot?: CreateQqBot;
 }
 
-export class QqWebsocketEndpoint implements EndpointInstance {
+export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: QqEndpointOptions;
@@ -64,16 +60,20 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   #bot: QqBotTransport | null = null;
   #open = false;
   #started = false;
-  #unregisterAgent?: () => void;
-  readonly management: EndpointManagement = createQqEndpointManagement(this);
+  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
 
   constructor(options: QqEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('qq', options.config.id);
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
 
+  get client(): QqBotTransport {
+    return this.#requireBot();
+  }
+
   /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
   get name(): string {
     return this.#options.config.id;
@@ -83,7 +83,6 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
-      this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
       this.#bot = this.#createBot(this.#options.config);
       this.#bindBot(this.#bot);
       await this.#bot.start();
@@ -111,8 +110,6 @@ export class QqWebsocketEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
     if (this.#bot) {
       try {
         this.#bot.removeAllListeners();
@@ -191,7 +188,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
       + (msg.mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(content, 80)}`,
     );
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
       content,
@@ -218,46 +215,16 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     });
   }
 
-  getGuilds() {
-    return this.#requireBot().getGuilds();
-  }
-
-  getChannels(guildId: string) {
-    return this.#requireBot().getChannels(guildId);
-  }
-
-  getChannelInfo(channelId: string) {
-    return this.#requireBot().getChannelInfo(channelId);
-  }
-
-  getGuildMember(guildId: string, userId: string) {
-    return this.#requireBot().getGuildMember(guildId, userId);
-  }
-
-  getGuildRoles(guildId: string) {
-    return this.#requireBot().getGuildRoles(guildId);
-  }
-
-  createGuildRole(guildId: string, name: string, color?: number) {
-    return this.#requireBot().createGuildRole(guildId, name, color);
-  }
-
-  addMemberRole(guildId: string, channelId: string, userId: string, roleId: string) {
-    return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-  }
-
-  removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string) {
-    return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-  }
-
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
+      this.#emitPlatformEvent('message', raw);
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
     bindQqBotSideEvents(bot, (eventName, raw) => {
+      this.#emitPlatformEvent(eventName, raw);
       receiveQqSideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
         bot as QqSideEventCaller,
         eventName,
@@ -267,6 +234,16 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     });
   }
 
+  #emitPlatformEvent(name: string, event: unknown): void {
+    void this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'qq_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
+
   #requireBot(): QqBotTransport {
     if (!this.#bot) throw new Error('QQ bot not connected');
     return this.#bot;
@@ -275,15 +252,13 @@ export class QqWebsocketEndpoint implements EndpointInstance {
 
 export interface QqHttpEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedQqHttpConfig;
   readonly createBot?: CreateQqHttpBot;
 }
 
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
-export class QqHttpEndpoint implements EndpointInstance {
+export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: QqHttpEndpointOptions;
@@ -292,16 +267,20 @@ export class QqHttpEndpoint implements EndpointInstance {
   #routeReleases: ReturnType<typeof registerQqWebhookRoutes> = [];
   #open = false;
   #started = false;
-  #unregisterAgent?: () => void;
-  readonly management: EndpointManagement = createQqEndpointManagement(this);
+  readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
 
   constructor(options: QqHttpEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('qq', options.config.id);
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateHttpBot;
   }
 
+  get client(): QqHttpBotTransport {
+    return this.#requireBot();
+  }
+
   /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
   get name(): string {
     return this.#options.config.id;
@@ -311,10 +290,6 @@ export class QqHttpEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
-      this.#unregisterAgent = registerQqAgentEndpoint(
-        this.#options.config.id,
-        this as unknown as QqWebsocketEndpoint,
-      );
       this.#setupRoutes();
       this.#bot = this.#createBot(this.#options.config);
       this.#bindBot(this.#bot);
@@ -340,8 +315,6 @@ export class QqHttpEndpoint implements EndpointInstance {
   async stop(): Promise<void> {
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
     if (this.#bot) {
       try {
         this.#bot.removeAllListeners();
@@ -419,7 +392,7 @@ export class QqHttpEndpoint implements EndpointInstance {
       + (msg.mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(content, 80)}`,
     );
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
       content,
@@ -446,38 +419,6 @@ export class QqHttpEndpoint implements EndpointInstance {
     });
   }
 
-  getGuilds() {
-    return this.#requireBot().getGuilds();
-  }
-
-  getChannels(guildId: string) {
-    return this.#requireBot().getChannels(guildId);
-  }
-
-  getChannelInfo(channelId: string) {
-    return this.#requireBot().getChannelInfo(channelId);
-  }
-
-  getGuildMember(guildId: string, userId: string) {
-    return this.#requireBot().getGuildMember(guildId, userId);
-  }
-
-  getGuildRoles(guildId: string) {
-    return this.#requireBot().getGuildRoles(guildId);
-  }
-
-  createGuildRole(guildId: string, name: string, color?: number) {
-    return this.#requireBot().createGuildRole(guildId, name, color);
-  }
-
-  addMemberRole(guildId: string, channelId: string, userId: string, roleId: string) {
-    return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-  }
-
-  removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string) {
-    return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-  }
-
   #setupRoutes(): void {
     this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
       config: this.#options.config,
@@ -487,12 +428,14 @@ export class QqHttpEndpoint implements EndpointInstance {
 
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
+      this.#emitPlatformEvent('message', raw);
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
     bindQqBotSideEvents(bot, (eventName, raw) => {
+      this.#emitPlatformEvent(eventName, raw);
       receiveQqSideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
         bot as QqSideEventCaller,
         eventName,
@@ -502,26 +445,36 @@ export class QqHttpEndpoint implements EndpointInstance {
     });
   }
 
-  #requireBot(): QqBotTransport {
+  #emitPlatformEvent(name: string, event: unknown): void {
+    void this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'qq_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
+
+  #requireBot(): QqHttpBotTransport {
     if (!this.#bot) throw new Error('QQ bot not connected');
     return this.#bot;
   }
 }
 
-function createQqEndpointManagement(endpoint: {
-  getGuilds(): Promise<unknown[]>;
-  getChannels(guildId: string): Promise<unknown[]>;
-}): EndpointManagement {
+function createQqEndpointManagement(
+  requireClient: () => Pick<QqBotTransport, 'getGuilds' | 'getChannels'>,
+): EndpointManagement {
   return Object.freeze<EndpointManagement>({
     async listChannels(): Promise<readonly EndpointChannel[]> {
       const channels: EndpointChannel[] = [];
-      const guilds = await endpoint.getGuilds();
+      const client = requireClient();
+      const guilds = await client.getGuilds();
       for (const guildValue of Array.isArray(guilds) ? guilds : []) {
         const guild = asRecord(guildValue);
         const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
         if (!guildId) continue;
         const guildName = String(guild.name ?? guild.guild_name ?? guildId);
-        const rows = await endpoint.getChannels(guildId);
+        const rows = await client.getChannels(guildId);
         for (const channelValue of Array.isArray(rows) ? rows : []) {
           const channel = asRecord(channelValue);
           const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');

package/src/index.ts

@@ -55,13 +55,7 @@ export {
   normalizeQqMessage,
 } from './ws.js';
 
-export {
-  getQqAgentDeps,
-  registerQqAgentEndpoint,
-  setQqAgentDeps,
-  type QqAgentDeps,
-  type QqAgentEndpoint,
-} from './qq-agent-deps.js';
+export { qqClient, type QqClientEventMap } from './client.js';
 
 export {
   checkQqPlatformPermit,

package/src/side-event-dispatch.ts

@@ -1,5 +1,5 @@
 import { receiveOneBotLikeSideEvent, type OneBotLikeRawEvent } from '@zhin.js/core';
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
 
 export interface QqSideEventCaller {
@@ -66,21 +66,21 @@ function toOneBotLikeRaw(eventName: string, raw: unknown): OneBotLikeRawEvent |
 }
 
 export function receiveQqSideEvent(
-  sideEvents: SideEventGateway | undefined,
+  emit: EndpointEventEmitter,
   endpointKey: string,
   caller: QqSideEventCaller,
   eventName: string,
   raw: unknown,
   logger: ReturnType<typeof getAdapterLogger>,
 ): void {
-  if (!sideEvents) return;
+  if (!emit) return;
   const mapped = toOneBotLikeRaw(eventName, raw);
   if (!mapped) return;
   const isJoinRequest = eventName === 'notice.group.join_request';
   const joinRaw = isJoinRequest && raw && typeof raw === 'object'
     ? raw as { group_id?: string | number; user_id?: string | number; join_request_id?: string | number }
     : undefined;
-  void receiveOneBotLikeSideEvent(sideEvents, {
+  void receiveOneBotLikeSideEvent(emit, {
     adapter: 'qq',
     endpointKey,
     platform: 'qq',

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

@@ -1,21 +0,0 @@
-/**
- * Agent tool deps for qq.
- * Endpoints register themselves on start; tools look up by config name / endpoint id.
- */
-export interface QqAgentEndpoint {
-    getGuilds(): Promise<unknown[]>;
-    getChannels(guildId: string): Promise<unknown[]>;
-    getChannelInfo(channelId: string): Promise<unknown>;
-    getGuildMember(guildId: string, userId: string): Promise<unknown>;
-    getGuildRoles(guildId: string): Promise<unknown[]>;
-    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
-    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
-    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
-}
-export interface QqAgentDeps {
-    getEndpoint: (endpointKey: string) => QqAgentEndpoint;
-}
-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

@@ -1,30 +0,0 @@
-/**
- * Agent tool deps for qq.
- * Endpoints register themselves on start; tools look up by config name / endpoint id.
- */
-const endpoints = new Map();
-let override = null;
-export function registerQqAgentEndpoint(endpointKey, endpoint) {
-    endpoints.set(endpointKey, endpoint);
-    return () => {
-        if (endpoints.get(endpointKey) === endpoint) {
-            endpoints.delete(endpointKey);
-        }
-    };
-}
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export function setQqAgentDeps(deps) {
-    override = deps;
-}
-export function getQqAgentDeps() {
-    if (override)
-        return override;
-    return {
-        getEndpoint(endpointKey) {
-            const registered = endpoints.get(endpointKey);
-            if (!registered)
-                throw new Error(`Endpoint ${endpointKey} 不存在`);
-            return registered;
-        },
-    };
-}

package/src/qq-agent-deps.ts

@@ -1,60 +0,0 @@
-/**
- * Agent tool deps for qq.
- * Endpoints register themselves on start; tools look up by config name / endpoint id.
- */
-
-export interface QqAgentEndpoint {
-  getGuilds(): Promise<unknown[]>;
-  getChannels(guildId: string): Promise<unknown[]>;
-  getChannelInfo(channelId: string): Promise<unknown>;
-  getGuildMember(guildId: string, userId: string): Promise<unknown>;
-  getGuildRoles(guildId: string): Promise<unknown[]>;
-  createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
-  addMemberRole(
-    guildId: string,
-    channelId: string,
-    userId: string,
-    roleId: string,
-  ): Promise<boolean>;
-  removeMemberRole(
-    guildId: string,
-    channelId: string,
-    userId: string,
-    roleId: string,
-  ): Promise<boolean>;
-}
-
-export interface QqAgentDeps {
-  getEndpoint: (endpointKey: string) => QqAgentEndpoint;
-}
-
-const endpoints = new Map<string, QqAgentEndpoint>();
-let override: QqAgentDeps | null = null;
-
-export function registerQqAgentEndpoint(
-  endpointKey: string,
-  endpoint: QqAgentEndpoint,
-): () => void {
-  endpoints.set(endpointKey, endpoint);
-  return () => {
-    if (endpoints.get(endpointKey) === endpoint) {
-      endpoints.delete(endpointKey);
-    }
-  };
-}
-
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export function setQqAgentDeps(deps: QqAgentDeps | null): void {
-  override = deps;
-}
-
-export function getQqAgentDeps(): QqAgentDeps {
-  if (override) return override;
-  return {
-    getEndpoint(endpointKey: string): QqAgentEndpoint {
-      const registered = endpoints.get(endpointKey);
-      if (!registered) throw new Error(`Endpoint ${endpointKey} 不存在`);
-      return registered;
-    },
-  };
-}