@zhin.js/adapter-napcat 0.1.13 → 0.1.14

package/src/bot-ws-client.ts

@@ -6,6 +6,7 @@ import { formatCompact } from 'zhin.js';
 import { NapCatBotBase } from './bot-base.js';
 import type { NapCatWsClientConfig, ApiResponse } from './types.js';
 import type { NapCatAdapter } from './adapter.js';
+import { enableTypingIndicator } from './typing-indicator.js';
 
 export class NapCatWsClient extends NapCatBotBase {
   private ws?: WebSocket;
@@ -43,6 +44,7 @@ export class NapCatWsClient extends NapCatBotBase {
         }
         this.logger.info(formatCompact({ bot: this.$id, mode: 'ws' }));
         this.startHeartbeat();
+        this.initTypingIndicator();
         resolve();
       });
 
@@ -87,6 +89,7 @@ export class NapCatWsClient extends NapCatBotBase {
     for (const [, req] of this.pendingRequests) { clearTimeout(req.timeout); req.reject(new Error('Connection closed')); }
     this.pendingRequests.clear();
     if (this.ws) { this.ws.close(); this.ws = undefined; }
+    this.inboundDeduper.clear();
     this.$connected = false;
   }
 
@@ -127,4 +130,35 @@ export class NapCatWsClient extends NapCatBotBase {
       try { await this.$connect(); } catch { this.scheduleReconnect(); }
     }, interval);
   }
+
+  protected handleMeta(event: any): void {
+    if (event.meta_event_type === 'lifecycle' && event.sub_type === 'connect') {
+      this.logger.info(formatCompact({ bot: this.$id, lifecycle: 'connect', self_id: event.self_id }));
+    }
+  }
+
+  private initTypingIndicator(): void {
+    const tiConfig = this.$config.typingIndicator;
+    if (tiConfig && tiConfig.enabled !== false) {
+      enableTypingIndicator(this, {
+        enabled: tiConfig.enabled ?? true,
+        defaultEmoji: tiConfig.defaultEmoji || '128516',
+        autoRemove: true,
+        removeDelay: 5000,
+        privateConfig: tiConfig.privateConfig ? {
+          type: tiConfig.privateConfig.type || 'message',
+          message: tiConfig.privateConfig.message || '正在思考中...',
+          autoRemove: true,
+          removeDelay: 3000,
+        } : undefined,
+        groupConfig: tiConfig.groupConfig ? {
+          type: tiConfig.groupConfig.type || 'reaction',
+          emoji: tiConfig.groupConfig.emoji || '128516',
+          autoRemove: true,
+          removeDelay: 5000,
+        } : undefined,
+      });
+      this.logger.info(formatCompact({ bot: this.$id, typingIndicator: 'enabled' }));
+    }
+  }
 }

package/src/bot-ws-server.ts

@@ -8,6 +8,7 @@ import { NapCatBotBase } from './bot-base.js';
 import type { NapCatWsServerConfig, ApiResponse } from './types.js';
 import type { NapCatAdapter } from './adapter.js';
 import type { Router } from '@zhin.js/http';
+import { enableTypingIndicator } from './typing-indicator.js';
 
 export class NapCatWsServer extends NapCatBotBase {
   #wss?: WebSocketServer;
@@ -76,6 +77,7 @@ export class NapCatWsServer extends NapCatBotBase {
     if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = undefined; }
     for (const [, req] of this.pendingRequests) { clearTimeout(req.timeout); req.reject(new Error('Connection closed')); }
     this.pendingRequests.clear();
+    this.inboundDeduper.clear();
     this.$connected = false;
   }
 
@@ -118,6 +120,7 @@ export class NapCatWsServer extends NapCatBotBase {
       this.#clientMap.set(String(message.self_id), client);
       this.$connected = true;
       this.logger.info(formatCompact({ bot: this.$id, self_id: message.self_id }));
+      this.initTypingIndicator();
       return;
     }
     this.dispatchEvent(message);
@@ -132,4 +135,16 @@ export class NapCatWsServer extends NapCatBotBase {
       }
     }, interval);
   }
+
+  private initTypingIndicator(): void {
+    const tiConfig = (this.$config as any).typingIndicator;
+    if (tiConfig && tiConfig.enabled !== false) {
+      enableTypingIndicator(this, {
+        enabled: true,
+        defaultEmoji: tiConfig.defaultEmoji || '128516',
+        autoRemove: true,
+        removeDelay: 5000,
+      });
+    }
+  }
 }

package/src/index.ts

@@ -3,9 +3,23 @@
  * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
  * 连接方式：正向 WS / 反向 WS / HTTP
  */
-import { usePlugin, type Plugin, type Context, type IGroupManagement, createGroupManagementTools, type ToolFeature } from 'zhin.js';
+import path from 'path';
+import {
+  usePlugin,
+  type Plugin,
+  type Context,
+  type IGroupManagement,
+  createGroupManagementTools,
+  type ToolFeature,
+  registerAgentPromptContributor,
+  unregisterAgentPromptContributor,
+} from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import { PageManager } from '@zhin.js/console';
 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 './bot-ws-client.js';
@@ -13,11 +27,17 @@ export { NapCatWsServer } from './bot-ws-server.js';
 export { NapCatHttpBot } from './bot-http.js';
 export { NapCatAdapter, type NapCatBot } from './adapter.js';
 export { NapCatBotBase } from './bot-base.js';
+export {
+  NapCatTypingIndicatorManager,
+  enableTypingIndicator,
+  type NapCatTypingIndicatorConfig,
+} from './typing-indicator.js';
 
 declare module 'zhin.js' {
   namespace Plugin {
     interface Contexts {
-      router: import('@zhin.js/http').Router;
+      web: PageManager;
+      router: Router;
     }
   }
   interface Adapters {
@@ -28,19 +48,23 @@ declare module 'zhin.js' {
 const plugin = usePlugin();
 const { provide, useContext } = plugin;
 
+// ── 适配器注册 ─────────────────────────────────────────────────────
 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'>);
 
+// ── AI 工具注册 ────────────────────────────────────────────────────
 useContext('tool', 'napcat', (toolService: ToolFeature, napcat: NapCatAdapter) => {
   const disposers: (() => void)[] = [];
 
@@ -55,3 +79,18 @@ useContext('tool', 'napcat', (toolService: ToolFeature, napcat: NapCatAdapter) =
 
   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: Router, napcat: NapCatAdapter) => {
+  registerRoutes(router, napcat);
+});

package/src/napcat-inbound.ts

@@ -0,0 +1,57 @@
+/**
+ * NapCat 入站消息治理：去重、自发过滤、消息归一化
+ */
+import type { NapCatMessageEvent, MessageSegment } from './types.js';
+
+const DEDUPE_TTL_MS = 120_000;
+
+export class InboundMessageDeduper {
+  private readonly seen = new Map<string, number>();
+
+  shouldProcess(messageId: string): boolean {
+    const now = Date.now();
+    for (const [id, t] of this.seen) {
+      if (now - t > DEDUPE_TTL_MS) this.seen.delete(id);
+    }
+    if (this.seen.has(messageId)) return false;
+    this.seen.set(messageId, now);
+    return true;
+  }
+
+  clear(): void {
+    this.seen.clear();
+  }
+}
+
+/** 判断是否为 bot 自身发出的消息 */
+export function isSelfMessage(event: NapCatMessageEvent): 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);
+  }
+  return false;
+}
+
+/**
+ * 将 message 字段归一化为 MessageSegment[]。
+ * NapCat 通常返回数组，但某些配置下可能返回 CQ 字符串。
+ */
+export function normalizeMessage(message: MessageSegment[] | string): MessageSegment[] {
+  if (Array.isArray(message)) return message;
+  if (typeof message === 'string') {
+    return [{ type: 'text', data: { text: message } }];
+  }
+  return [];
+}
+
+/**
+ * 生成用于 notice / request 事件的去重 key
+ */
+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(':');
+}

package/src/onebot-get-msg.ts

@@ -0,0 +1,33 @@
+import type { MessageSegment, QuotedMessagePayload } from 'zhin.js';
+
+export function parseOneBotGetMsgResponse(
+  messageId: string,
+  data: unknown,
+): QuotedMessagePayload {
+  const record =
+    data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
+  let content: QuotedMessagePayload['content'] = [];
+  if (Array.isArray(record.message)) {
+    content = record.message as MessageSegment[];
+  } 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'];
+  if (senderRaw && typeof senderRaw === 'object') {
+    const s = senderRaw as Record<string, unknown>;
+    sender = {
+      id: String(s.user_id ?? ''),
+      name: String(s.nickname ?? s.card ?? ''),
+    };
+  }
+
+  return {
+    messageId,
+    sender,
+    content,
+    raw: typeof record.raw_message === 'string' ? record.raw_message : undefined,
+    time: typeof record.time === 'number' ? record.time : undefined,
+  };
+}

package/src/routes.ts

@@ -0,0 +1,61 @@
+import type { Router } from '@zhin.js/http';
+import type { NapCatAdapter } from './adapter.js';
+
+export function registerRoutes(router: Router, napcat: NapCatAdapter): void {
+  router.get('/api/napcat/bots', async (ctx) => {
+    try {
+      const bots = Array.from(napcat.bots.values());
+      if (bots.length === 0) {
+        ctx.body = { success: true, data: [], message: '暂无 NapCat 机器人实例' };
+        return;
+      }
+      const result = await Promise.all(
+        bots.map(async (bot) => {
+          try {
+            const connection = (bot.$config as any).connection ?? 'ws';
+            const base: Record<string, unknown> = {
+              name: bot.$config.name,
+              connected: bot.$connected || false,
+              connection,
+              status: bot.$connected ? 'online' : 'offline',
+              lastActivity: new Date().toISOString(),
+            };
+            if (bot.$connected) {
+              try {
+                const friends = await bot.getFriendList();
+                const groups = await bot.getGroupList();
+                base.friendCount = Array.isArray(friends) ? friends.length : 0;
+                base.groupCount = Array.isArray(groups) ? groups.length : 0;
+              } catch {
+                base.friendCount = 0;
+                base.groupCount = 0;
+              }
+            } else {
+              base.friendCount = 0;
+              base.groupCount = 0;
+            }
+            return base;
+          } catch {
+            return {
+              name: bot.$config.name,
+              connected: false,
+              connection: 'unknown',
+              status: 'error',
+              friendCount: 0,
+              groupCount: 0,
+            };
+          }
+        }),
+      );
+      ctx.body = { success: true, data: result, timestamp: new Date().toISOString() };
+    } catch (error) {
+      ctx.status = 500;
+      ctx.body = {
+        success: false,
+        error: 'NAPCAT_API_ERROR',
+        message: '获取机器人数据失败',
+        details: process.env.NODE_ENV === 'development' ? (error as Error).message : undefined,
+      };
+    }
+  });
+}

package/src/types.ts

@@ -5,10 +5,23 @@
 
 // ── 配置 ─────────────────────────────────────────────────────────────
 
+export interface TypingIndicatorConfig {
+  /** 是否启用（默认 true） */
+  enabled?: boolean;
+  /** 默认表情 ID */
+  defaultEmoji?: string;
+  /** 私聊配置 */
+  privateConfig?: { type?: 'message' | 'typing'; message?: string };
+  /** 群聊配置 */
+  groupConfig?: { type?: 'reaction'; emoji?: string };
+}
+
 export interface NapCatConfigBase {
   context: 'napcat';
   name: string;
   access_token?: string;
+  /** Typing Indicator 配置 */
+  typingIndicator?: TypingIndicatorConfig;
 }
 
 /** 正向 WebSocket */

package/src/typing-indicator.ts

@@ -0,0 +1,196 @@
+/**
+ * NapCat Typing Indicator 集成
+ *
+ * 群聊：set_msg_emoji_like（表情回应）
+ * 私聊：set_input_status（输入状态）或短暂提示消息
+ */
+
+import type { NapCatBotBase } from './bot-base.js';
+import {
+  TypingIndicatorManager,
+  ReactionTypingIndicatorAdapter,
+  type TypingIndicatorOptions,
+  type TypingIndicatorConfig,
+  type TypingIndicator,
+} from '@zhin.js/agent';
+
+export interface NapCatTypingIndicatorConfig {
+  enabled: boolean;
+  defaultEmoji: string;
+  autoRemove: boolean;
+  removeDelay: number;
+  privateConfig?: Partial<TypingIndicatorConfig>;
+  groupConfig?: Partial<TypingIndicatorConfig>;
+}
+
+const DEFAULT_CONFIG: NapCatTypingIndicatorConfig = {
+  enabled: true,
+  defaultEmoji: '128516',
+  autoRemove: true,
+  removeDelay: 5000,
+  privateConfig: {
+    type: 'message',
+    message: '正在思考中...',
+    autoRemove: true,
+    removeDelay: 3000,
+  },
+  groupConfig: {
+    type: 'reaction',
+    emoji: '128516',
+    autoRemove: true,
+    removeDelay: 5000,
+  },
+};
+
+export class NapCatTypingIndicatorManager {
+  private manager: TypingIndicatorManager;
+  private config: NapCatTypingIndicatorConfig;
+  private bot: NapCatBotBase;
+
+  private currentOptions?: {
+    messageId?: string;
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+    sceneType: 'private' | 'group';
+  };
+
+  constructor(bot: NapCatBotBase, config: Partial<NapCatTypingIndicatorConfig> = {}) {
+    this.bot = bot;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.manager = new TypingIndicatorManager({
+      type: 'reaction',
+      emoji: this.config.defaultEmoji,
+      autoRemove: this.config.autoRemove,
+      removeDelay: this.config.removeDelay,
+    });
+    this.registerAdapter();
+  }
+
+  private registerAdapter(): void {
+    const adapter = new ReactionTypingIndicatorAdapter(
+      async (messageId: string, emoji: string) => {
+        return await this.bot.$addReaction(messageId, emoji);
+      },
+      async (messageId: string, reactionId: string) => {
+        await this.bot.$removeReaction(messageId, reactionId);
+      },
+      async (sessionId: string, content: string) => {
+        try {
+          const options = this.currentOptions;
+          if (!options) return null;
+          if (options.sceneType === 'group' && options.groupId) {
+            return await this.bot.$sendMessage({
+              type: 'group',
+              id: options.groupId,
+              context: 'napcat',
+              bot: this.bot.$id,
+              content: [{ type: 'text', data: { text: content } }],
+            });
+          } else if (options.userId) {
+            return await this.bot.$sendMessage({
+              type: 'private',
+              id: options.userId,
+              context: 'napcat',
+              bot: this.bot.$id,
+              content: [{ type: 'text', data: { text: content } }],
+            });
+          }
+          return null;
+        } catch {
+          return null;
+        }
+      },
+      async (messageId: string) => {
+        try {
+          await this.bot.$recallMessage(messageId);
+        } catch { /* ignore */ }
+      },
+    );
+    this.manager.registerAdapter(adapter);
+  }
+
+  async start(options: {
+    messageId?: string;
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+    sceneType: 'private' | 'group';
+  }): Promise<TypingIndicator> {
+    this.bot.logger.debug('[NapCat:TypingIndicator] start called', {
+      enabled: this.config.enabled,
+      sceneType: options.sceneType,
+    });
+
+    if (!this.config.enabled) {
+      return {
+        start: async () => {},
+        stop: async () => {},
+        isActive: () => false,
+      };
+    }
+
+    this.currentOptions = options;
+
+    const config = options.sceneType === 'group'
+      ? this.config.groupConfig
+      : this.config.privateConfig;
+
+    const typingOptions: TypingIndicatorOptions = {
+      messageId: options.messageId,
+      sessionId: options.sessionId,
+      userId: options.userId,
+      groupId: options.groupId,
+      platform: 'napcat',
+      botId: this.bot.$id,
+      sceneType: options.sceneType,
+    };
+
+    return await this.manager.start(typingOptions, config);
+  }
+
+  async stop(options: {
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+  }): Promise<void> {
+    const typingOptions: TypingIndicatorOptions = {
+      sessionId: options.sessionId,
+      userId: options.userId,
+      groupId: options.groupId,
+      platform: 'napcat',
+      botId: this.bot.$id,
+      sceneType: 'private',
+    };
+    await this.manager.stop(typingOptions);
+    this.currentOptions = undefined;
+  }
+
+  async stopAll(): Promise<void> {
+    await this.manager.stopAll();
+  }
+
+  updateConfig(config: Partial<NapCatTypingIndicatorConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  getConfig(): NapCatTypingIndicatorConfig {
+    return { ...this.config };
+  }
+}
+
+declare module './bot-base.js' {
+  interface NapCatBotBase {
+    $typingIndicator?: NapCatTypingIndicatorManager;
+  }
+}
+
+export function enableTypingIndicator(
+  bot: NapCatBotBase,
+  config?: Partial<NapCatTypingIndicatorConfig>,
+): NapCatTypingIndicatorManager {
+  if (!(bot as any).$typingIndicator) {
+    (bot as any).$typingIndicator = new NapCatTypingIndicatorManager(bot, config);
+  }
+  return (bot as any).$typingIndicator;
+}