@zhin.js/adapter-qq 8.0.0 → 8.0.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-qq
 
+## 8.0.2
+
+### Patch Changes
+
+- Updated dependencies [736fa04]
+  - @zhin.js/agent@1.1.17
+  - zhin.js@6.0.14
+
+## 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>;
 }