@zhin.js/adapter-napcat 1.0.1 → 1.1.2

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,73 @@
-/**
- * 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 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-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');

package/src/onebot-get-msg.ts

@@ -1,20 +1,26 @@
-import type { MessageSegment, QuotedMessagePayload } from 'zhin.js';
+export interface NapcatMessageLookup {
+  messageId: string;
+  sender?: { id: string; name: string };
+  content: Array<{ type: string; data?: Record<string, unknown> }>;
+  raw?: string;
+  time?: number;
+}
 
 export function parseOneBotGetMsgResponse(
   messageId: string,
   data: unknown,
-): QuotedMessagePayload {
+): NapcatMessageLookup {
   const record =
     data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
-  let content: QuotedMessagePayload['content'] = [];
+  let content: NapcatMessageLookup['content'] = [];
   if (Array.isArray(record.message)) {
-    content = record.message as MessageSegment[];
+    content = record.message as NapcatMessageLookup['content'];
   } else if (typeof record.raw_message === 'string' && record.raw_message) {
     content = [{ type: 'text', data: { text: record.raw_message } }];
   }
 
   const senderRaw = record.sender;
-  let sender: QuotedMessagePayload['sender'];
+  let sender: NapcatMessageLookup['sender'];
   if (senderRaw && typeof senderRaw === 'object') {
     const s = senderRaw as Record<string, unknown>;
     sender = {
@@ -31,3 +37,61 @@ export function parseOneBotGetMsgResponse(
     time: typeof record.time === 'number' ? record.time : undefined,
   };
 }
+
+export function createNapCatContentPort(
+  callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>,
+): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'napcat_opaque_media_requires_platform_file_metadata' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        if (reference.kind === 'message') {
+          const parsed = parseOneBotGetMsgResponse(reference.message.id, await callApi('get_msg', { message_id: reference.message.id }));
+          context.signal.throwIfAborted();
+          const value: ConversationMessage = Object.freeze({
+            ref: reference.message,
+            ...(parsed.sender?.id ? { actor: Object.freeze({ id: parsed.sender.id, ...(parsed.sender.name ? { displayName: parsed.sender.name } : {}) }) } : {}),
+            segments: canonicalSegments(parsed.content),
+            timestamp: toMillis(parsed.time),
+          });
+          return Object.freeze({ status: 'resolved' as const, reference, value });
+        }
+        const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+        const value: readonly ForwardEntry[] = Object.freeze(nodes.map((node) => {
+          const row = node as Record<string, unknown>;
+          const sender = row.sender as Record<string, unknown> | undefined;
+          return Object.freeze({
+            ...(sender?.user_id != null ? { actor: Object.freeze({ id: String(sender.user_id), ...(sender.nickname ? { displayName: String(sender.nickname) } : {}) }) } : {}),
+            segments: canonicalSegments(Array.isArray(row.content) ? row.content as never[] : []),
+            timestamp: toMillis(row.time),
+          });
+        }));
+        return Object.freeze({ status: 'resolved' as const, reference, value });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'napcat_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function canonicalSegments(content: Array<{ type: string; data?: Record<string, unknown> }>) {
+  return Object.freeze(content.map((segment) => Object.freeze({
+    type: segment.type,
+    data: Object.freeze(segment.data ?? {}),
+  })));
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { ConversationMessage, ConversationReference, ForwardEntry } from '@zhin.js/im-contract';