@zhin.js/adapter-napcat 3.0.2 → 5.0.0

package/src/http-endpoint.ts

@@ -0,0 +1,197 @@
+/**
+ * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
+import {
+  InboundMessageDeduper,
+  isNapCatBotMentioned,
+  isSelfMessage,
+  normalizeMessage,
+} from './napcat-inbound.js';
+import {
+  buildSendAction,
+  callNapCatHttpAction,
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundSegments,
+  isMessageEvent,
+  senderNickname,
+  senderUserId,
+  type NapCatEvent,
+  type NapCatHttpConfig,
+} from './protocol.js';
+import { readRequestBody } from './webhook.js';
+import { NapCatWsEndpoint } from './ws-endpoint.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+
+const logger = getLogger('napcat');
+
+export interface NapCatHttpEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly http: HttpHost;
+  readonly config: NapCatHttpConfig;
+  readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+
+export class NapCatHttpEndpoint implements EndpointInstance {
+  readonly #options: NapCatHttpEndpointOptions;
+  readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly #callHttpAction: typeof callNapCatHttpAction;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+  #unregisterAgent?: () => void;
+
+  constructor(options: NapCatHttpEndpointOptions) {
+    this.#options = options;
+    this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    this.#unregisterAgent = registerNapcatAgentEndpoint(
+      this.#options.config.name,
+      this as unknown as NapCatWsEndpoint,
+    );
+    this.#setupRoutes();
+    logger.info(formatCompact({
+      op: 'listen',
+      endpoint: this.#options.config.name,
+      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.#unregisterAgent?.();
+    this.#unregisterAgent = undefined;
+    this.#inboundDeduper.clear();
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+  }
+
+  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+    const message = formatOutboundSegments(payload);
+    const { action, params } = buildSendAction(target, 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) : '';
+    logger.debug(formatCompact({
+      op: 'napcat_send',
+      endpoint: this.#options.config.name,
+      target,
+      messageId,
+    }));
+    return 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 || !isMessageEvent(ev)) 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 target = formatInboundTarget(ev);
+    const nickname = senderNickname(ev);
+    const mentioned = isNapCatBotMentioned(ev);
+    void this.#options.gateway.receive({
+      adapter: this.#options.id,
+      target,
+      content: formatInboundContent(ev),
+      sender: senderUserId(ev),
+      id: msgId,
+      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,
+        endpoint: this.#options.config.name,
+        time: ev.time,
+        self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+        role: ev.sender?.role,
+        ...(nickname ? { nickname } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
+      }),
+    }).catch((err) => {
+      logger.warn(formatCompact({
+        op: 'napcat_gateway_receive_failed',
+        target,
+        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) {
+      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' }));
+      }
+    }
+  }
+}

package/src/index.ts

@@ -1,91 +1,76 @@
-/**
- * NapCat 适配器入口
- * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
- * 连接方式：正向 WS / 反向 WS / HTTP
- */
-import path from 'path';
-import {
-  usePlugin,
-  type Plugin,
-  type Context,
-  type ISceneManagement,
-  createSceneManagementTools,
-  registerDefaultScenePlatformPermitChecker,
-  type ToolFeature,
-} from 'zhin.js';
-import { registerAgentPromptContributor, unregisterAgentPromptContributor } from 'zhin.js/agent';
-import type { Router } from '@zhin.js/host-router';
-import { PageManager } from '@zhin.js/host-api';
-import { NapCatAdapter } from './adapter.js';
-import { createNapCatAgentPromptContributor } from './agent-prompt.js';
-import { registerRoutes } from './routes.js';
-import { setNapcatAgentDeps } from './napcat-agent-deps.js';
+export {
+  buildSendAction,
+  buildWsConnectOptions,
+  callNapCatHttpAction,
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundSegments,
+  getChannelId,
+  isMessageEvent,
+  parseSendTarget,
+  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 {
+  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 {
+  getEndpoint,
+  getNapcatAgentDeps,
+  registerNapcatAgentEndpoint,
+  setNapcatAgentDeps,
+  type NapcatAgentDeps,
+  type NapcatAgentEndpoint,
+} from './napcat-agent-deps.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 工具注册（场景治理；扩展工具见 agent/tools/）────────────────
-useContext('tool', 'napcat', (toolService: ToolFeature, napcat: NapCatAdapter) => {
-  setNapcatAgentDeps({ getAdapter: () => napcat });
+export {
+  NapCatWssEndpoint,
+  type NapCatWssEndpointOptions,
+} from './wss-endpoint.js';
 
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDefaultScenePlatformPermitChecker('napcat'));
+export {
+  NapCatHttpEndpoint,
+  type NapCatHttpEndpointOptions,
+} from './http-endpoint.js';
 
-  const sceneTools = createSceneManagementTools(
-    napcat as unknown as ISceneManagement,
-    'napcat',
-  );
-  disposers.push(...sceneTools.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-agent-deps.ts

@@ -1,29 +1,95 @@
 /**
- * Shared runtime deps for napcat agent/ authoring tools.
+ * Agent tool deps for napcat.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
  */
-import type { NapCatAdapter, NapCatEndpoint } from './adapter.js';
+
+export interface NapcatAgentEndpoint {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+  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 interface NapcatAgentDeps {
-  getAdapter: () => NapCatAdapter;
+  getEndpoint: (endpointId: string) => NapcatAgentEndpoint;
 }
 
-let _deps: NapcatAgentDeps | null = null;
+const endpoints = new Map<string, NapcatAgentEndpoint>();
+let override: NapcatAgentDeps | null = null;
 
-export function setNapcatAgentDeps(deps: NapcatAgentDeps): void {
-  _deps = deps;
+export function registerNapcatAgentEndpoint(
+  endpointId: string,
+  endpoint: NapcatAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
 }
 
-export function getNapcatAgentDeps(): NapcatAgentDeps {
-  if (!_deps) throw new Error('napcat agent deps not initialized');
-  return _deps;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setNapcatAgentDeps(deps: NapcatAgentDeps | null): void {
+  override = deps;
 }
 
-export function getAdapter(): NapCatAdapter {
-  return getNapcatAgentDeps().getAdapter();
+function lookup(endpointId: string): NapcatAgentEndpoint {
+  const registered = endpoints.get(endpointId);
+  if (!registered) throw new Error(`Endpoint ${endpointId} not found`);
+  return registered;
+}
+
+export function getNapcatAgentDeps(): NapcatAgentDeps {
+  if (override) return override;
+  return { getEndpoint: lookup };
 }
 
-export function getEndpoint(endpointId: string): NapCatEndpoint {
-  const endpoint = getAdapter().endpoints.get(endpointId);
-  if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-  return endpoint;
+/** Convenience for agent/tools (unchanged call sites). */
+export function getEndpoint(endpointId: string): NapcatAgentEndpoint {
+  return getNapcatAgentDeps().getEndpoint(endpointId);
 }

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/onebot-get-msg.ts

@@ -1,4 +1,10 @@
-import type { MessageSegment, QuotedMessagePayload } from 'zhin.js';
+export interface QuotedMessagePayload {
+  messageId: string;
+  sender?: { id: string; name: string };
+  content: Array<{ type: string; data?: Record<string, unknown> }>;
+  raw?: string;
+  time?: number;
+}
 
 export function parseOneBotGetMsgResponse(
   messageId: string,
@@ -8,7 +14,7 @@ export function parseOneBotGetMsgResponse(
     data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
   let content: QuotedMessagePayload['content'] = [];
   if (Array.isArray(record.message)) {
-    content = record.message as MessageSegment[];
+    content = record.message as QuotedMessagePayload['content'];
   } else if (typeof record.raw_message === 'string' && record.raw_message) {
     content = [{ type: 'text', data: { text: record.raw_message } }];
   }