@zhin.js/adapter-napcat 1.0.1 → 1.1.2

package/commands/napcat/endpoint/remove/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { napcatEndpointCommands } from '../../definition.js';
+export default napcatEndpointCommands.remove;

package/commands/napcat/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { napcatEndpointCommands } from '../../definition.js';
+
+export default napcatEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,52 @@
+import type { NapCatEvent } from './protocol.js';
+export type NapcatApiCall = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+/** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
+export declare class NapcatClient {
+    readonly callApi: NapcatApiCall;
+    constructor(callApi: NapcatApiCall);
+    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
+    sendLike(userId: number, times?: number): Promise<unknown>;
+    deleteFriend(userId: number): Promise<unknown>;
+    markMsgAsRead(messageId: number): Promise<unknown>;
+    ocrImage(image: string): Promise<unknown>;
+    setQQProfile(nickname: string, company?: string, email?: string, college?: string, personalNote?: string): Promise<unknown>;
+    setGroupPortrait(groupId: number, file: string): Promise<unknown>;
+    setEssenceMsg(messageId: number): Promise<unknown>;
+    deleteEssenceMsg(messageId: number): Promise<unknown>;
+    getEssenceMsgList(groupId: number): Promise<unknown>;
+    sendGroupSign(groupId: number): Promise<unknown>;
+    sendGroupNotice(groupId: number, content: string, image?: string): Promise<unknown>;
+    getGroupNotice(groupId: number): Promise<unknown>;
+    deleteGroupNotice(groupId: number, noticeId: string): Promise<unknown>;
+    uploadGroupFile(groupId: number, file: string, name: string, folder?: string): Promise<unknown>;
+    getGroupRootFiles(groupId: number): Promise<unknown>;
+    getGroupFileUrl(groupId: number, fileId: string, busid: number): Promise<unknown>;
+    downloadFile(url: string, threadCount?: number, headers?: string[]): Promise<unknown>;
+    setOnlineStatus(status: number, extStatus: number): Promise<unknown>;
+    setQQAvatar(file: string): Promise<unknown>;
+    forwardFriendSingleMsg(userId: number, messageId: number): Promise<unknown>;
+    forwardGroupSingleMsg(groupId: number, messageId: number): Promise<unknown>;
+    translateEn2Zh(sourceText: string): Promise<unknown>;
+    setMsgEmojiLike(messageId: number, emojiId: string): Promise<unknown>;
+    sendForwardMsg(messageType: 'private' | 'group', id: number, messages: unknown[]): Promise<unknown>;
+    getFriendMsgHistory(userId: number, messageSeq?: number, count?: number): Promise<unknown>;
+    getGroupMsgHistory(groupId: number, messageSeq?: number, count?: number): Promise<unknown>;
+    setSelfLongnick(longnick: string): Promise<unknown>;
+    getGroupInfoEx(groupId: number): Promise<unknown>;
+    sendPoke(userId: number, groupId?: number): Promise<unknown>;
+    ncGetUserStatus(userId: number): Promise<unknown>;
+    getGroupShutList(groupId: number): Promise<unknown>;
+    getMiniAppArk(type: string, title: string, desc: string, picUrl: string, jumpUrl: string): Promise<unknown>;
+    getAiCharacters(groupId: number): Promise<unknown>;
+    sendGroupAiRecord(groupId: number, characterId: string, text: string): Promise<unknown>;
+}
+export type NapcatClientEventMap = Record<string, NapCatEvent>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly napcat: {
+            readonly client: NapcatClient;
+            readonly events: NapcatClientEventMap;
+        };
+    }
+}
+export declare const napcatClient: import("@zhin.js/adapter").EndpointClientToken<NapcatClient, NapcatClientEventMap>;

package/lib/client.js

@@ -0,0 +1,62 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
+export class NapcatClient {
+    callApi;
+    constructor(callApi) {
+        this.callApi = callApi;
+    }
+    async setTitle(groupId, userId, title, duration = -1) {
+        await this.callApi('set_group_special_title', {
+            group_id: groupId,
+            user_id: userId,
+            special_title: title,
+            duration,
+        });
+        return true;
+    }
+    sendLike(userId, times = 1) { return this.callApi('send_like', { user_id: userId, times }); }
+    deleteFriend(userId) { return this.callApi('delete_friend', { user_id: userId }); }
+    markMsgAsRead(messageId) { return this.callApi('mark_msg_as_read', { message_id: messageId }); }
+    ocrImage(image) { return this.callApi('ocr_image', { image }); }
+    setQQProfile(nickname, company, email, college, personalNote) {
+        return this.callApi('set_qq_profile', { nickname, company, email, college, personal_note: personalNote });
+    }
+    setGroupPortrait(groupId, file) { return this.callApi('set_group_portrait', { group_id: groupId, file }); }
+    setEssenceMsg(messageId) { return this.callApi('set_essence_msg', { message_id: messageId }); }
+    deleteEssenceMsg(messageId) { return this.callApi('delete_essence_msg', { message_id: messageId }); }
+    getEssenceMsgList(groupId) { return this.callApi('get_essence_msg_list', { group_id: groupId }); }
+    sendGroupSign(groupId) { return this.callApi('send_group_sign', { group_id: groupId }); }
+    sendGroupNotice(groupId, content, image) { return this.callApi('_send_group_notice', { group_id: groupId, content, image }); }
+    getGroupNotice(groupId) { return this.callApi('_get_group_notice', { group_id: groupId }); }
+    deleteGroupNotice(groupId, noticeId) { return this.callApi('_del_group_notice', { group_id: groupId, notice_id: noticeId }); }
+    uploadGroupFile(groupId, file, name, folder) { return this.callApi('upload_group_file', { group_id: groupId, file, name, folder }); }
+    getGroupRootFiles(groupId) { return this.callApi('get_group_root_files', { group_id: groupId }); }
+    getGroupFileUrl(groupId, fileId, busid) { return this.callApi('get_group_file_url', { group_id: groupId, file_id: fileId, busid }); }
+    downloadFile(url, threadCount = 1, headers) { return this.callApi('download_file', { url, thread_count: threadCount, headers }); }
+    setOnlineStatus(status, extStatus) { return this.callApi('set_online_status', { status, ext_status: extStatus }); }
+    setQQAvatar(file) { return this.callApi('set_qq_avatar', { file }); }
+    forwardFriendSingleMsg(userId, messageId) { return this.callApi('forward_friend_single_msg', { user_id: userId, message_id: messageId }); }
+    forwardGroupSingleMsg(groupId, messageId) { return this.callApi('forward_group_single_msg', { group_id: groupId, message_id: messageId }); }
+    translateEn2Zh(sourceText) { return this.callApi('translate_en2zh', { source_text: sourceText }); }
+    setMsgEmojiLike(messageId, emojiId) { return this.callApi('set_msg_emoji_like', { message_id: messageId, emoji_id: emojiId }); }
+    sendForwardMsg(messageType, id, messages) {
+        return this.callApi('send_forward_msg', {
+            message_type: messageType,
+            [messageType === 'group' ? 'group_id' : 'user_id']: id,
+            messages,
+        });
+    }
+    getFriendMsgHistory(userId, messageSeq, count) { return this.callApi('get_friend_msg_history', { user_id: userId, message_seq: messageSeq, count }); }
+    getGroupMsgHistory(groupId, messageSeq, count) { return this.callApi('get_group_msg_history', { group_id: groupId, message_seq: messageSeq, count }); }
+    setSelfLongnick(longnick) { return this.callApi('set_self_longnick', { longNick: longnick }); }
+    getGroupInfoEx(groupId) { return this.callApi('get_group_info_ex', { group_id: groupId }); }
+    sendPoke(userId, groupId) { return this.callApi('send_poke', { user_id: userId, group_id: groupId }); }
+    ncGetUserStatus(userId) { return this.callApi('nc_get_user_status', { user_id: userId }); }
+    getGroupShutList(groupId) { return this.callApi('get_group_shut_list', { group_id: groupId }); }
+    getMiniAppArk(type, title, desc, picUrl, jumpUrl) { return this.callApi('get_mini_app_ark', { type, title, desc, picUrl, jumpUrl }); }
+    getAiCharacters(groupId) { return this.callApi('get_ai_characters', { group_id: groupId }); }
+    sendGroupAiRecord(groupId, characterId, text) {
+        return this.callApi('send_group_ai_record', { group_id: groupId, character: characterId, text });
+    }
+}
+export const napcatClient = defineEndpointClient('napcat');

package/lib/endpoint-management.d.ts

@@ -0,0 +1,15 @@
+/**
+ * NapCat endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OneBot11 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from 'zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createNapCatEndpointManagement(endpoint: NapCatManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createNapCatEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = await endpoint.callApi('get_friend_list');
+            return toArray(data).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.nickname ?? ''),
+                    remark: String(friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = await endpoint.callApi('get_group_list');
+            return toArray(data).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = await endpoint.callApi('get_group_member_list', {
+                group_id: toNumberId(groupId, 'group_id'),
+            });
+            return toArray(data);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`napcat ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/http-endpoint.d.ts

@@ -0,0 +1,27 @@
+import { Endpoint } from 'zhin.js/adapter';
+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 { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
+import { NapcatClient } from './client.js';
+export interface NapCatHttpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: NapCatHttpConfig;
+    readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+export declare class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
+    #private;
+    readonly client: NapcatClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    constructor(options: NapCatHttpEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+    admit(ev: NapCatEvent): void;
+}

package/lib/http-endpoint.js

@@ -0,0 +1,177 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
+import { NapcatClient } from './client.js';
+import { readRequestBody } from './webhook.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+export class NapCatHttpEndpoint extends Endpoint {
+    client = new NapcatClient((action, params) => this.#callApi(action, params));
+    #logger;
+    #options;
+    #inboundDeduper = new InboundMessageDeduper();
+    management = createNapCatEndpointManagement(this.client);
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content = createNapCatContentPort((action, params) => this.client.callApi(action, params));
+    #callHttpAction;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('napcat', options.config.id);
+        this.#options = options;
+        this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#setupRoutes();
+        this.#logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'http',
+            path: this.#options.config.post_path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#inboundDeduper.clear();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
+        const resp = await this.#callHttpAction({
+            http_url: this.#options.config.http_url,
+            access_token: this.#options.config.access_token,
+        }, action, params);
+        const data = resp.data;
+        const messageId = data?.message_id != null ? String(data.message_id) : '';
+        this.#logger.debug(formatCompact({
+            op: 'napcat_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.client.callApi('delete_msg', { message_id: Number(messageId) });
+    }
+    #callApi(action, params = {}) {
+        return this.#callHttpAction({
+            http_url: this.#options.config.http_url,
+            access_token: this.#options.config.access_token,
+        }, action, params).then((resp) => resp.data);
+    }
+    admit(ev) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(napCatPlatformEventName(ev), ev).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'napcat_platform_event_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (!isMessageEvent(ev)) {
+            receiveNapCatSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, this.client, ev, this.#logger);
+            return;
+        }
+        if (isSelfMessage(ev))
+            return;
+        const msgId = String(ev.message_id);
+        if (!this.#inboundDeduper.shouldProcess(msgId))
+            return;
+        if (Array.isArray(ev.message) || typeof ev.message === 'string') {
+            ev = { ...ev, message: normalizeMessage(ev.message) };
+        }
+        const conversation = napcatInboundConversation(String(this.#options.id), ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isNapCatBotMentioned(ev);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msgId },
+            content: formatInboundContent(ev),
+            sender: {
+                id: senderUserId(ev),
+                name: nickname,
+                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                message_type: ev.message_type,
+                user_id: ev.user_id != null ? String(ev.user_id) : undefined,
+                group_id: ev.group_id != null ? String(ev.group_id) : undefined,
+                time: ev.time,
+                self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+                role: ev.sender?.role,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'napcat_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #setupRoutes() {
+        const path = this.#options.config.post_path;
+        this.#routeReleases.push(this.#options.http.route('POST', path, async (request, response) => {
+            await this.#handlePost(request, response);
+        }, { summary: 'NapCat HTTP event callback', tags: ['napcat'] }));
+    }
+    async #handlePost(request, response) {
+        try {
+            if (!verifyNapCatAccessToken(this.#options.config.access_token, request)) {
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Unauthorized' }));
+                return;
+            }
+            const raw = await readRequestBody(request);
+            let ev;
+            try {
+                ev = JSON.parse(raw);
+            }
+            catch {
+                response.writeHead(400, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Invalid JSON' }));
+                return;
+            }
+            if (this.#open)
+                this.admit(ev);
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ status: 'ok' }));
+        }
+        catch (error) {
+            this.#logger.error('NapCat HTTP webhook error:', error);
+            if (!response.headersSent) {
+                response.writeHead(500, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Internal Server Error' }));
+            }
+        }
+    }
+}
+function napCatPlatformEventName(ev) {
+    return [ev.post_type, ev.message_type ?? ev.notice_type ?? ev.request_type, ev.sub_type]
+        .filter(Boolean)
+        .join('.');
+}

package/lib/index.d.ts

@@ -1,22 +1,11 @@
-import type { Router } from '@zhin.js/host-router';
-import { PageManager } from '@zhin.js/host-api';
-import { NapCatAdapter } from './adapter.js';
-export * from './types.js';
-export { NapCatWsClient } from './endpoint-ws-client.js';
-export { NapCatWsServer } from './endpoint-ws-server.js';
-export { NapCatHttpEndpoint } from './endpoint-http.js';
-export { NapCatAdapter, type NapCatEndpoint } from './adapter.js';
-export { NapCatEndpointBase } from './endpoint-base.js';
-export { NapCatTypingIndicatorManager, enableTypingIndicator, type NapCatTypingIndicatorConfig, } from './typing-indicator.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-            router: Router;
-        }
-    }
-    interface Adapters {
-        napcat: NapCatAdapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
+export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+export { napcatClient, type NapcatClient, type NapcatClientEventMap, } from './client.js';
+export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
+export { NapCatWsEndpoint, type NapCatWsEndpointOptions, } from './ws-endpoint.js';
+export { NapCatWssEndpoint, type NapCatWssEndpointOptions, } from './wss-endpoint.js';
+export { NapCatHttpEndpoint, type NapCatHttpEndpointOptions, } from './http-endpoint.js';
+export type { NapCatWsSocket, NapCatWsCreateOptions } from './ws-types.js';
+export { callNapCatWsAction, decodeWsPayload, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+export { verifyNapCatAccessToken } from './wss-auth.js';
+export { readRequestBody } from './webhook.js';

package/lib/index.js

@@ -1,59 +1,10 @@
-/**
- * NapCat 适配器入口
- * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
- * 连接方式：正向 WS / 反向 WS / HTTP
- */
-import path from 'path';
-import { usePlugin, createGroupManagementTools, registerDefaultGroupPlatformPermitChecker, registerAgentPromptContributor, unregisterAgentPromptContributor, } from 'zhin.js';
-import { NapCatAdapter } from './adapter.js';
-import { createNapCatTools } from './tools.js';
-import { createNapCatAgentPromptContributor } from './agent-prompt.js';
-import { registerRoutes } from './routes.js';
-export * from './types.js';
-export { NapCatWsClient } from './endpoint-ws-client.js';
-export { NapCatWsServer } from './endpoint-ws-server.js';
-export { NapCatHttpEndpoint } from './endpoint-http.js';
-export { NapCatAdapter } from './adapter.js';
-export { NapCatEndpointBase } from './endpoint-base.js';
-export { NapCatTypingIndicatorManager, enableTypingIndicator, } from './typing-indicator.js';
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-// ── 适配器注册 ─────────────────────────────────────────────────────
-provide({
-    name: 'napcat',
-    description: 'NapCatQQ 适配器（OneBot11 + go-cqhttp + NapCat 扩展，正向/反向 WS + HTTP）',
-    mounted: async (p) => {
-        registerAgentPromptContributor(createNapCatAgentPromptContributor());
-        const adapter = new NapCatAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        unregisterAgentPromptContributor('napcat');
-        await adapter.stop();
-    },
-});
-// ── AI 工具注册 ────────────────────────────────────────────────────
-useContext('tool', 'napcat', (toolService, napcat) => {
-    const disposers = [];
-    disposers.push(registerDefaultGroupPlatformPermitChecker('napcat'));
-    const groupTools = createGroupManagementTools(napcat, 'napcat');
-    disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
-    const napcatTools = createNapCatTools(napcat);
-    disposers.push(...napcatTools.map(t => toolService.addTool(t, plugin.name)));
-    return () => disposers.forEach(d => d());
-});
-// ── Web 控制台入口 ─────────────────────────────────────────────────
-useContext('web', (pageManager) => {
-    pageManager.addEntry({
-        id: 'napcat',
-        development: path.resolve(import.meta.dirname, '../client/index.tsx'),
-        production: path.resolve(import.meta.dirname, '../dist/index.js'),
-        meta: { name: 'NapCat' },
-    });
-});
-// ── HTTP 路由 ──────────────────────────────────────────────────────
-useContext('router', 'napcat', async (router, napcat) => {
-    registerRoutes(router, napcat);
-});
-//# sourceMappingURL=index.js.map
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+export { napcatClient, } from './client.js';
+export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
+export { NapCatWsEndpoint, } from './ws-endpoint.js';
+export { NapCatWssEndpoint, } from './wss-endpoint.js';
+export { NapCatHttpEndpoint, } from './http-endpoint.js';
+export { callNapCatWsAction, decodeWsPayload, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+export { verifyNapCatAccessToken } from './wss-auth.js';
+export { readRequestBody } from './webhook.js';

package/lib/napcat-inbound.d.ts

@@ -1,21 +1,28 @@
 /**
  * NapCat 入站消息治理：去重、自发过滤、消息归一化
  */
-import type { NapCatMessageEvent, MessageSegment } from './types.js';
+import type { NapCatMessageEvent, MessageSegment } from './protocol.js';
 export declare class InboundMessageDeduper {
     private readonly seen;
     shouldProcess(messageId: string): boolean;
     clear(): void;
 }
 /** 判断是否为 bot 自身发出的消息 */
-export declare function isSelfMessage(event: NapCatMessageEvent): boolean;
+export declare function isSelfMessage(event: NapCatMessageEvent | {
+    post_type?: string;
+    self_id?: number | string;
+    user_id?: number | string;
+}): boolean;
 /**
  * 将 message 字段归一化为 MessageSegment[]。
  * NapCat 通常返回数组，但某些配置下可能返回 CQ 字符串。
  */
 export declare function normalizeMessage(message: MessageSegment[] | string): MessageSegment[];
 /**
- * 生成用于 notice / request 事件的去重 key
+ * OneBot11 mentioned 判定：消息段 {type:'at', data:{qq}} 的 qq 等于本机 uin
+ * （事件 self_id）时为 true；`qq === 'all'` 不算。兼容 CQ 字符串形式。
  */
-export declare function resolveSideEventDedupeKey(event: any, prefix: string): string;
-//# sourceMappingURL=napcat-inbound.d.ts.map
+export declare function isNapCatBotMentioned(ev: {
+    self_id?: number | string;
+    message?: MessageSegment[] | string;
+}): boolean;

package/lib/napcat-inbound.js

@@ -37,19 +37,34 @@ export function normalizeMessage(message) {
     }
     return [];
 }
+const CQ_AT_RE = /\[CQ:at,qq=([^\],\s]+)\]/g;
+function atTargetMatchesUin(target, uin) {
+    const qq = String(target ?? '').trim();
+    return Boolean(qq) && qq !== 'all' && Number(qq) === Number(uin);
+}
 /**
- * 生成用于 notice / request 事件的去重 key
+ * OneBot11 mentioned 判定：消息段 {type:'at', data:{qq}} 的 qq 等于本机 uin
+ * （事件 self_id）时为 true；`qq === 'all'` 不算。兼容 CQ 字符串形式。
  */
-export function resolveSideEventDedupeKey(event, prefix) {
-    const parts = [prefix, event.time, event.notice_type || event.request_type];
-    if (event.group_id)
-        parts.push(event.group_id);
-    if (event.user_id)
-        parts.push(event.user_id);
-    if (event.message_id)
-        parts.push(event.message_id);
-    if (event.flag)
-        parts.push(event.flag);
-    return parts.join(':');
+export function isNapCatBotMentioned(ev) {
+    if (ev.self_id == null)
+        return false;
+    const uin = String(ev.self_id).trim();
+    if (!uin)
+        return false;
+    const segments = normalizeMessage(ev.message ?? []);
+    for (const seg of segments) {
+        if (seg.type === 'at' && atTargetMatchesUin(seg.data?.qq, uin))
+            return true;
+    }
+    const text = segments
+        .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
+        .join('');
+    if (!text)
+        return false;
+    for (const match of text.matchAll(CQ_AT_RE)) {
+        if (atTargetMatchesUin(match[1], uin))
+            return true;
+    }
+    return false;
 }
-//# sourceMappingURL=napcat-inbound.js.map

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

@@ -0,0 +1 @@
+export declare const napcatRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/napcat-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * NapCat 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `napcat endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const napcatRuntimeStateToken = defineEndpointRuntimeStateToken('napcat');

package/lib/onebot-get-msg.d.ts

@@ -1,3 +1,16 @@
-import type { QuotedMessagePayload } from 'zhin.js';
-export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): QuotedMessagePayload;
-//# sourceMappingURL=onebot-get-msg.d.ts.map
+export interface NapcatMessageLookup {
+    messageId: string;
+    sender?: {
+        id: string;
+        name: string;
+    };
+    content: Array<{
+        type: string;
+        data?: Record<string, unknown>;
+    }>;
+    raw?: string;
+    time?: number;
+}
+export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): NapcatMessageLookup;
+export declare function createNapCatContentPort(callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>): EndpointContentPort;
+import type { EndpointContentPort } from 'zhin.js/adapter';