@zhin.js/adapter-napcat 3.0.1 → 4.0.1

package/src/index.ts

@@ -1,92 +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 { createNapCatTools } from './tools.js';
-import { createNapCatAgentPromptContributor } from './agent-prompt.js';
-import { registerRoutes } from './routes.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 工具注册 ────────────────────────────────────────────────────
-useContext('tool', 'napcat', (toolService: ToolFeature, napcat: NapCatAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDefaultScenePlatformPermitChecker('napcat'));
+export {
+  NapCatWssEndpoint,
+  type NapCatWssEndpointOptions,
+} from './wss-endpoint.js';
 
-  const sceneTools = createSceneManagementTools(
-    napcat as unknown as ISceneManagement,
-    'napcat',
-  );
-  disposers.push(...sceneTools.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-agent-deps.ts

@@ -0,0 +1,95 @@
+/**
+ * Agent tool deps for napcat.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+
+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 {
+  getEndpoint: (endpointId: string) => NapcatAgentEndpoint;
+}
+
+const endpoints = new Map<string, NapcatAgentEndpoint>();
+let override: NapcatAgentDeps | null = null;
+
+export function registerNapcatAgentEndpoint(
+  endpointId: string,
+  endpoint: NapcatAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
+
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setNapcatAgentDeps(deps: NapcatAgentDeps | null): void {
+  override = deps;
+}
+
+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 };
+}
+
+/** 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 } }];
   }