@zhin.js/adapter-napcat 1.0.1 → 1.1.0

package/src/client.ts

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

package/src/endpoint-management.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from 'zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createNapCatEndpointManagement(
+  endpoint: NapCatManagementCaller,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      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(): Promise<readonly EndpointGroup[]> {
+      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: string): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi('get_group_member_list', {
+        group_id: toNumberId(groupId, 'group_id'),
+      });
+      return toArray(data);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`napcat ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}

package/src/http-endpoint.ts

@@ -0,0 +1,234 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+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,
+  type NapCatEvent,
+  type NapCatHttpConfig,
+} 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 { NapCatWsEndpoint } from './ws-endpoint.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+
+export interface NapCatHttpEndpointOptions {
+  readonly id: CapabilityId;
+  readonly http: HttpHost;
+  readonly config: NapCatHttpConfig;
+  readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+
+export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
+  readonly client = new NapcatClient((action, params) => this.#callApi(action, params));
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: NapCatHttpEndpointOptions;
+  readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly management: EndpointManagement = createNapCatEndpointManagement(this.client);
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content = createNapCatContentPort((action, params) => this.client.callApi(action, params));
+  readonly #callHttpAction: typeof callNapCatHttpAction;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+
+  constructor(options: NapCatHttpEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('napcat', options.config.id);
+    this.#options = options;
+    this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+  }
+
+  async start(): Promise<void> {
+    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(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  async stop(): Promise<void> {
+    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 }: EndpointSendRequest): Promise<string> {
+    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 as { message_id?: number | string } | undefined;
+    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: string): Promise<void> {
+    if (!messageId) return;
+    await this.client.callApi('delete_msg', { message_id: Number(messageId) });
+  }
+
+  #callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    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: NapCatEvent): void {
+    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(): void {
+    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: IncomingMessage, response: ServerResponse): Promise<void> {
+    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: NapCatEvent;
+      try {
+        ev = JSON.parse(raw) as NapCatEvent;
+      } 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: NapCatEvent): string {
+  return [ev.post_type, ev.message_type ?? ev.notice_type ?? ev.request_type, ev.sub_type]
+    .filter(Boolean)
+    .join('.');
+}

package/src/index.ts

@@ -1,98 +1,74 @@
-/**
- * NapCat 适配器入口
- * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
- * 连接方式：正向 WS / 反向 WS / HTTP
- */
-import path from 'path';
-import {
-  usePlugin,
-  type Plugin,
-  type Context,
-  type IGroupManagement,
-  createGroupManagementTools,
-  registerDefaultGroupPlatformPermitChecker,
-  type ToolFeature,
-  registerAgentPromptContributor,
-  unregisterAgentPromptContributor,
-} from 'zhin.js';
-import type { Router } from '@zhin.js/host-router';
-import { PageManager } from '@zhin.js/host-api';
-import { NapCatAdapter } from './adapter.js';
-import { createNapCatTools } from './tools.js';
-import { createNapCatAgentPromptContributor } from './agent-prompt.js';
-import { registerRoutes } from './routes.js';
+export {
+  buildSendAction,
+  buildWsConnectOptions,
+  callNapCatHttpAction,
+  formatInboundContent,
+  formatOutboundSegments,
+  getChannelId,
+  isMessageEvent,
+  mediaRefToOneBotFile,
+  napcatInboundConversation,
+  napcatOutboundTarget,
+  resolveNapCatConfig,
+  senderNickname,
+  senderUserId,
+  type MessageSegment,
+  type NapCatActionRequest,
+  type NapCatActionResponse,
+  type NapCatAdapterConfig,
+  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 * 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';
+  InboundMessageDeduper,
+  isNapCatBotMentioned,
+  isSelfMessage,
+  normalizeMessage,
+} from './napcat-inbound.js';
 
-declare module 'zhin.js' {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-      router: Router;
-    }
-  }
-  interface Adapters {
-    napcat: NapCatAdapter;
-  }
-}
+export {
+  napcatClient,
+  type NapcatClient,
+  type NapcatClientEventMap,
+} from './client.js';
 
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
+export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
 
-// ── 适配器注册 ─────────────────────────────────────────────────────
-provide({
-  name: 'napcat',
-  description: 'NapCatQQ 适配器（OneBot11 + go-cqhttp + NapCat 扩展，正向/反向 WS + HTTP）',
-  mounted: async (p: Plugin) => {
-    registerAgentPromptContributor(createNapCatAgentPromptContributor());
-    const adapter = new NapCatAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: NapCatAdapter) => {
-    unregisterAgentPromptContributor('napcat');
-    await adapter.stop();
-  },
-} as unknown as Context<'napcat'>);
+export {
+  NapCatWsEndpoint,
+  type NapCatWsEndpointOptions,
+} from './ws-endpoint.js';
 
-// ── AI 工具注册 ────────────────────────────────────────────────────
-useContext('tool', 'napcat', (toolService: ToolFeature, napcat: NapCatAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDefaultGroupPlatformPermitChecker('napcat'));
+export {
+  NapCatWssEndpoint,
+  type NapCatWssEndpointOptions,
+} from './wss-endpoint.js';
 
-  const groupTools = createGroupManagementTools(
-    napcat as unknown as IGroupManagement,
-    'napcat',
-  );
-  disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
+export {
+  NapCatHttpEndpoint,
+  type NapCatHttpEndpointOptions,
+} from './http-endpoint.js';
 
-  const napcatTools = createNapCatTools(napcat);
-  disposers.push(...napcatTools.map(t => toolService.addTool(t, plugin.name)));
+export type { NapCatWsSocket, NapCatWsCreateOptions } from './ws-types.js';
 
-  return () => disposers.forEach(d => d());
-});
+export {
+  callNapCatWsAction,
+  decodeWsPayload,
+  handleNapCatWsMessage,
+  rejectAllPending,
+  startNapCatHeartbeat,
+} from './ws-transport.js';
 
-// ── 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' },
-  });
-});
+export { verifyNapCatAccessToken } from './wss-auth.js';
 
-// ── HTTP 路由 ──────────────────────────────────────────────────────
-useContext('router', 'napcat', async (router: Router, napcat: NapCatAdapter) => {
-  registerRoutes(router, napcat);
-});
+export { readRequestBody } from './webhook.js';

package/src/napcat-endpoint-commands.ts

@@ -0,0 +1,26 @@
+/**
+ * `napcat.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { napcatRuntimeStateToken } from './napcat-runtime-state.js';
+
+export const napcatEndpointCommands = createEndpointCommands({
+  adapterKey: 'napcat',
+  adapterDisplayName: 'NapCat',
+  fields: [
+    { key: 'url', description: 'NapCat WebSocket URL（connection: ws 必填）' },
+    { key: 'path', description: 'reverse-wss 路径（connection: wss）' },
+    { key: 'http_url', description: 'HTTP API base URL（connection: http 出站）' },
+    { key: 'post_path', description: 'HTTP POST 事件路径（connection: http 入站）' },
+    { key: 'access_token', env: true, description: 'NapCat access token' },
+  ],
+  running: (use) => use(napcatRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => {
+    if (entry.url) return `url: ${String(entry.url)}`;
+    if (entry.path) return `path: ${String(entry.path)}`;
+    if (entry.http_url) return `http_url: ${String(entry.http_url)}`;
+    return '';
+  },
+}, defineCommand);

package/src/napcat-inbound.ts

@@ -1,7 +1,7 @@
 /**
  * NapCat 入站消息治理：去重、自发过滤、消息归一化
  */
-import type { NapCatMessageEvent, MessageSegment } from './types.js';
+import type { NapCatMessageEvent, MessageSegment } from './protocol.js';
 
 const DEDUPE_TTL_MS = 120_000;
 
@@ -24,7 +24,11 @@ export class InboundMessageDeduper {
 }
 
 /** 判断是否为 bot 自身发出的消息 */
-export function isSelfMessage(event: NapCatMessageEvent): boolean {
+export function isSelfMessage(event: NapCatMessageEvent | {
+  post_type?: string;
+  self_id?: number | string;
+  user_id?: number | string;
+}): boolean {
   if (event.post_type === 'message_sent') return true;
   if (event.self_id != null && event.user_id != null) {
     return Number(event.self_id) === Number(event.user_id);
@@ -44,14 +48,34 @@ export function normalizeMessage(message: MessageSegment[] | string): MessageSeg
   return [];
 }
 
+const CQ_AT_RE = /\[CQ:at,qq=([^\],\s]+)\]/g;
+
+function atTargetMatchesUin(target: unknown, uin: string): boolean {
+  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: any, prefix: string): string {
-  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: {
+  self_id?: number | string;
+  message?: MessageSegment[] | string;
+}): boolean {
+  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;
 }

package/src/napcat-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * 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');