@zhin.js/adapter-qq 5.0.1 → 5.0.3

package/agent/tools/list_channels.ts

@@ -0,0 +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 }>({
+  description: '获取 QQ 频道下的子频道列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('频道 ID'),
+  }),
+  platforms: ['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);
+    return { channels, count: channels.length };
+  },
+});

package/agent/tools/list_guilds.ts

@@ -0,0 +1,17 @@
+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 }>({
+  description: '获取 QQ 频道列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+  }),
+  platforms: ['qq'],
+  tags: ['qq'],
+  async execute({ endpoint_id  }: { endpoint_id: string }) {
+    const endpoint = getQqAgentDeps().getEndpoint(endpoint_id);
+    const guilds = await endpoint.getGuilds();
+    return { guilds, count: guilds.length };
+  },
+});

package/agent/tools/list_roles.ts

@@ -0,0 +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 }>({
+  description: '获取 QQ 频道角色列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('频道 ID'),
+  }),
+  platforms: ['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);
+    return { roles, count: roles.length };
+  },
+});

package/agent/tools/member_detail.ts

@@ -0,0 +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; 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'],
+  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);
+  },
+});

package/agent/tools/remove_role.ts

@@ -0,0 +1,23 @@
+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 }>({
+  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'],
+  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);
+    return { success, message: success ? '已移除成员的角色' : '操作失败' };
+  },
+});

package/lib/endpoint.d.ts

@@ -1,125 +1,69 @@
 /**
- * QQ 官方 Endpoint 实现
+ * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { Bot as QQOfficialClient, PrivateMessageEvent, GroupMessageEvent } from "qq-official-bot";
-import { Endpoint, Message, SendOptions } from 'zhin.js';
-import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
-import type { QQAdapter } from "./adapter.js";
-import { type QqWsPacket } from "./inbound-normalize.js";
-/** 从 qq-official-bot SendResult / 审核回包中解析出站消息 ID */
-export declare function resolveOutboundMessageId(result: unknown): string;
-export declare class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform> extends QQOfficialClient implements Endpoint<QQEndpointConfig<T, M>, PrivateMessageEvent | GroupMessageEvent> {
-    adapter: QQAdapter;
-    $connected: boolean;
-    $config: QQEndpointConfig<T, M>;
-    /** 平台侧机器人 user_id，用于 @ 触发匹配 */
-    $platformUserId?: string;
-    get pluginLogger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: QQAdapter, config: QQEndpointConfig<T, M>);
-    /** 出站 QQ API 请求附带 SDK 版本，便于平台侧日志排查 */
-    private attachSdkVersionHeader;
-    /** 归一化 QQ API v2 群聊字段后再交给 qq-official-bot 解析 */
-    dispatchEvent(event: string, wsRes: QqWsPacket): void;
-    private guildMemberCache;
-    private guildOwnerCache;
-    private enrichGuildSender;
-    private handleQQMessage;
-    private handleQQAction;
-    private handleGroupNotice;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private resolveWebhookPath;
-    /**
-     * Webhook 入站：middleware（挂 host-router）或独立 HTTP 端口（qq-official-bot 内置服务）。
-     */
-    private mountWebhookReceiver;
-    private toWireSendContent;
-    $formatMessage(msg: PrivateMessageEvent | GroupMessageEvent): Message<PrivateMessageEvent | GroupMessageEvent>;
-    $sendMessage(options: SendOptions): Promise<string>;
-    /** 内联图 + 文本：上传 file_info 后以 msg_type=7 图文混排发送（二维码等场景） */
-    private $sendTextImageMixedMedia;
-    private resolveV2EndpointPath;
-    $recallMessage(id: string): Promise<void>;
-    /**
-     * 获取频道列表
-     */
-    getGuilds(): Promise<any[]>;
-    /**
-     * 获取频道详情
-     * @param guildId 频道 ID
-     */
-    getGuildInfo(guildId: string): Promise<any>;
-    /**
-     * 获取子频道列表
-     * @param guildId 频道 ID
-     */
-    getChannels(guildId: string): Promise<any[]>;
-    /**
-     * 获取子频道详情
-     * @param channelId 子频道 ID
-     */
-    getChannelInfo(channelId: string): Promise<any>;
-    /**
-     * 获取频道成员列表
-     * @param guildId 频道 ID
-     */
-    getGuildMembers(guildId: string): Promise<any[]>;
-    /**
-     * 获取频道成员详情
-     * @param guildId 频道 ID
-     * @param userId 用户 ID
-     */
-    getGuildMember(guildId: string, userId: string): Promise<any>;
-    /**
-     * 删除频道成员（踢出）
-     * @param guildId 频道 ID
-     * @param userId 用户 ID
-     * @param addBlacklist 是否加入黑名单
-     * @param deleteHistoryMsg 删除历史消息天数 (-1不删除，0全部删除，3/7/15/30)
-     */
-    removeGuildMember(guildId: string, userId: string, addBlacklist?: boolean, deleteHistoryMsg?: -1 | 0 | 3 | 7 | 15 | 30): Promise<boolean>;
-    /**
-     * 获取频道角色列表
-     * @param guildId 频道 ID
-     */
-    getGuildRoles(guildId: string): Promise<any[]>;
-    /**
-     * 创建频道角色
-     * @param guildId 频道 ID
-     * @param name 角色名
-     * @param color 颜色
-     * @param hoist 是否在成员列表中单独展示 (0 或 1)
-     */
-    createGuildRole(guildId: string, name: string, color?: number, hoist?: 0 | 1): Promise<any>;
-    /**
-     * 给成员添加角色
-     * @param guildId 频道 ID
-     * @param channelId 子频道 ID
-     * @param userId 用户 ID
-     * @param roleId 角色 ID
-     */
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
+import { type CreateQqHttpBot } from './webhook.js';
+import { type CreateQqBot } 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 config: ResolvedQqWebsocketConfig;
+    readonly createBot?: CreateQqBot;
+}
+export declare class QqWebsocketEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: QqEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** 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 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 {
+    #private;
+    constructor(options: QqHttpEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    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>;
-    /**
-     * 移除成员角色
-     * @param guildId 频道 ID
-     * @param channelId 子频道 ID
-     * @param userId 用户 ID
-     * @param roleId 角色 ID
-     */
     removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
-    /**
-     * 禁言成员（批量）
-     * @param guildId 频道 ID
-     * @param userIds 用户 ID 列表
-     * @param muteSeconds 禁言时长（秒），0 表示解除禁言
-     */
-    muteMembers(guildId: string, userIds: string[], muteSeconds: number): Promise<boolean>;
-    /**
-     * 全员禁言
-     * @param guildId 频道 ID
-     * @param muteSeconds 禁言时长（秒），0 表示解除禁言
-     */
-    muteAll(guildId: string, muteSeconds: number): Promise<boolean>;
 }
-//# sourceMappingURL=endpoint.d.ts.map