@zhin.js/adapter-napcat 0.1.13 → 0.1.15

package/src/agent-prompt.ts

@@ -0,0 +1,115 @@
+import type {
+  AgentPromptBuildContext,
+  AgentPromptContributor,
+  AgentPromptSection,
+  AgentTool,
+} from 'zhin.js';
+import { filterTools } from 'zhin.js';
+
+function isNapCatDelegatedTask(query: string, goal: string): boolean {
+  const text = `${query} ${goal}`;
+  if (/\bnapcat\b|napcat_|mcp_napcat/i.test(text)) return true;
+  if (/戳一戳|poke|表情回应|emoji.*reaction/i.test(text)) return true;
+  if (/精华消息|essence|群公告|group.*notice/i.test(text)) return true;
+  if (/AI语音|ai.*record|tts|文字转语音/i.test(text)) return true;
+  if (/群文件|upload.*file|群签到|group.*sign/i.test(text)) return true;
+  if (/合并转发|forward.*msg|转发消息/i.test(text)) return true;
+  if (/点赞/.test(text) && /qq|好友|\d{5,}/i.test(text)) return true;
+  return false;
+}
+
+function selectNapCatDeferredTools(
+  query: string,
+  goal: string,
+  deferredCatalog: AgentTool[],
+  maxTools: number,
+): AgentTool[] {
+  const pool = deferredCatalog.filter(
+    t => !t.name.startsWith('mcp_filesystem') && !t.name.startsWith('mcp_memory_'),
+  );
+  const napcatTools = pool.filter(t => t.name.startsWith('napcat_'));
+  const pinned: AgentTool[] = [];
+  const preferOrder = [
+    'napcat_send_poke',
+    'napcat_set_emoji_reaction',
+    'napcat_send_like',
+    'napcat_set_essence_msg',
+    'napcat_send_group_notice',
+    'napcat_ai_tts',
+  ];
+  for (const name of preferOrder) {
+    const t = napcatTools.find(x => x.name === name);
+    if (t) pinned.push(t);
+  }
+  for (const t of napcatTools) {
+    if (pinned.length >= maxTools) break;
+    if (!pinned.some(p => p.name === t.name)) pinned.push(t);
+  }
+
+  const extra = filterTools(query, pool, { maxTools, minScore: 0.08 })
+    .filter(t => !pinned.some(p => p.name === t.name));
+
+  const merged: AgentTool[] = [...pinned];
+  for (const t of extra) {
+    if (merged.length >= maxTools) break;
+    merged.push(t);
+  }
+  return merged.slice(0, maxTools);
+}
+
+const ORCHESTRATOR_NAPCAT = [
+  'On napcat/QQ: use run_deferred_task with tool_query "napcat_send_poke" or "napcat_set_emoji_reaction".',
+  'NapCat supports: poke, emoji reaction, forward msg, essence, group notice, AI TTS, OCR, group files.',
+  'Skip tool_search when the user clearly asks for QQ-specific features like poke, reaction, or group management.',
+].join('\n');
+
+const WORKER_NAPCAT = [
+  '- Use `napcat_send_poke` for poke/戳一戳.',
+  '- Use `napcat_set_emoji_reaction` for emoji reaction/表情回应.',
+  '- Use `napcat_send_like` for friend like/点赞.',
+  '- Use `napcat_ai_tts` for AI voice/AI语音.',
+  '- Use `napcat_set_essence_msg` / `napcat_delete_essence_msg` for essence messages.',
+  '- Use `napcat_send_group_notice` for group announcements.',
+  '- Do NOT use mcp_filesystem_* or explore node_modules for QQ tasks.',
+].join('\n');
+
+export function createNapCatAgentPromptContributor(): AgentPromptContributor {
+  return {
+    platform: 'napcat',
+
+    async buildSections(ctx: AgentPromptBuildContext): Promise<AgentPromptSection[] | null> {
+      if (ctx.slot === 'orchestrator') {
+        if (!ctx.toolSearch) return null;
+        return [{
+          id: 'platform.napcat.orchestrator',
+          title: '## napcat / QQ',
+          body: ORCHESTRATOR_NAPCAT,
+          priority: 50,
+        }];
+      }
+      if (ctx.slot === 'deferred_worker') {
+        const query = ctx.deferred?.toolQuery ?? ctx.deferred?.goal ?? '';
+        const goal = ctx.deferred?.goal ?? '';
+        if (!isNapCatDelegatedTask(query, goal)) return null;
+        return [{
+          id: 'platform.napcat.deferred_worker',
+          title: '## napcat / QQ（本任务）',
+          body: WORKER_NAPCAT,
+          priority: 50,
+        }];
+      }
+      return null;
+    },
+
+    matchesDeferredTask(ctx: AgentPromptBuildContext): boolean {
+      const query = ctx.deferred?.toolQuery ?? ctx.deferred?.goal ?? ctx.userMessagePreview ?? '';
+      const goal = ctx.deferred?.goal ?? ctx.userMessagePreview ?? '';
+      return isNapCatDelegatedTask(query, goal);
+    },
+
+    selectDeferredTools(query, goal, catalog, maxTools) {
+      if (!isNapCatDelegatedTask(query, goal)) return null;
+      return selectNapCatDeferredTools(query, goal, catalog, maxTools);
+    },
+  };
+}

package/src/bot-base.ts

@@ -10,12 +10,16 @@ import {
   segment,
   Notice,
   Request,
+  type QuotedMessagePayload,
 } from 'zhin.js';
+import { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
 import type { NapCatBotConfig, NapCatMessageEvent, MessageSegment, ApiResponse } from './types.js';
 import type { NapCatAdapter } from './adapter.js';
+import { InboundMessageDeduper, isSelfMessage, normalizeMessage, resolveSideEventDedupeKey } from './napcat-inbound.js';
 
 export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBotConfig, NapCatMessageEvent> {
   $connected = false;
+  protected readonly inboundDeduper = new InboundMessageDeduper();
 
   get logger() { return this.adapter.plugin.logger; }
   get $id() { return this.$config.name; }
@@ -33,6 +37,10 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
   // ══════════════════════════════════════════════════════════════════
 
   $formatMessage(ev: NapCatMessageEvent): Message<NapCatMessageEvent> {
+    const content = normalizeMessage(ev.message);
+    const quoteId = Message.quoteIdFromContent(content);
+    Message.alignReplySegments(content, quoteId);
+
     const message = Message.from(ev, {
       $id: ev.message_id.toString(),
       $adapter: 'napcat',
@@ -46,7 +54,8 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
         id: (ev.group_id || ev.user_id).toString(),
         type: ev.group_id ? 'group' : 'private',
       },
-      $content: ev.message,
+      $content: content,
+      $quote_id: quoteId,
       $raw: ev.raw_message,
       $timestamp: ev.time,
       $recall: async () => { await this.deleteMsg(ev.message_id); },
@@ -83,6 +92,18 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
     await this.deleteMsg(parseInt(id));
   }
 
+  async $addReaction(messageId: string, emojiId: string): Promise<string> {
+    await this.setMsgEmojiLike(parseInt(messageId), emojiId);
+    return `reaction:${messageId}:${emojiId}`;
+  }
+
+  async $removeReaction(messageId: string, _reactionId: string): Promise<void> {
+    // NapCat 的 set_msg_emoji_like 是 toggle 行为，再调一次即取消
+    const parts = _reactionId.split(':');
+    const emojiId = parts[2] || parts[0];
+    await this.setMsgEmojiLike(parseInt(messageId), emojiId);
+  }
+
   // ══════════════════════════════════════════════════════════════════
   // 事件分发
   // ══════════════════════════════════════════════════════════════════
@@ -102,12 +123,18 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
   }
 
   private handleMessage(ev: NapCatMessageEvent): void {
+    if (isSelfMessage(ev)) return;
+    const msgId = ev.message_id.toString();
+    if (!this.inboundDeduper.shouldProcess(msgId)) return;
+    ev.message = normalizeMessage(ev.message);
     const message = this.$formatMessage(ev);
     this.adapter.emit('message.receive', message);
     this.logger.debug(`${this.$id} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
   }
 
   private handleNotice(event: any): void {
+    const dedupeKey = resolveSideEventDedupeKey(event, 'notice');
+    if (!this.inboundDeduper.shouldProcess(dedupeKey)) return;
     const noticeTypeMap: Record<string, string> = {
       group_increase: 'group_member_increase',
       group_decrease: 'group_member_decrease',
@@ -152,6 +179,8 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
   }
 
   private handleRequest(event: any): void {
+    const dedupeKey = resolveSideEventDedupeKey(event, 'request');
+    if (!this.inboundDeduper.shouldProcess(dedupeKey)) return;
     const typeMap: Record<string, string> = {
       friend: 'friend_add',
       group: event.sub_type === 'invite' ? 'group_invite' : 'group_add',
@@ -199,6 +228,12 @@ export abstract class NapCatBotBase extends EventEmitter implements Bot<NapCatBo
   }
   async deleteMsg(messageId: number) { return this.callApi('delete_msg', { message_id: messageId }); }
   async getMsg(messageId: number) { return this.callApi('get_msg', { message_id: messageId }); }
+
+  async $getMsg(messageId: string): Promise<QuotedMessagePayload> {
+    const idParam = /^\d+$/.test(messageId) ? Number(messageId) : messageId;
+    const data = await this.callApi('get_msg', { message_id: idParam });
+    return parseOneBotGetMsgResponse(messageId, data);
+  }
   async getForwardMsg(id: string) { return this.callApi('get_forward_msg', { id }); }
   async sendLike(userId: number, times = 1) { return this.callApi('send_like', { user_id: userId, times }); }
 

package/src/bot-http.ts

@@ -7,8 +7,9 @@ import { formatCompact } from 'zhin.js';
 import { NapCatBotBase } from './bot-base.js';
 import type { NapCatHttpConfig, ApiResponse } from './types.js';
 import type { NapCatAdapter } from './adapter.js';
-import { registerFetchRoute, type Router, type RouterContext } from '@zhin.js/http/router';
+import { registerFetchRoute, type Router, type RouterContext } from '@zhin.js/host-router/router';
 import * as crypto from 'crypto';
+import { enableTypingIndicator } from './typing-indicator.js';
 
 export class NapCatHttpBot extends NapCatBotBase {
   private pollTimer?: NodeJS.Timeout;
@@ -24,11 +25,13 @@ export class NapCatHttpBot extends NapCatBotBase {
     await this.checkConnection();
     this.startPoll();
     this.$connected = true;
+    this.initTypingIndicator();
     this.logger.info(formatCompact({ bot: this.$id, mode: 'http' }));
   }
 
   async $disconnect(): Promise<void> {
     if (this.pollTimer) { clearInterval(this.pollTimer); this.pollTimer = undefined; }
+    this.inboundDeduper.clear();
     this.$connected = false;
   }
 
@@ -54,9 +57,12 @@ export class NapCatHttpBot extends NapCatBotBase {
 
       if (this.$config.access_token) {
         const sig = ctx.get('x-signature');
+        const authHeader = ctx.get('authorization');
         if (sig) {
           const expected = 'sha1=' + crypto.createHmac('sha1', this.$config.access_token).update(JSON.stringify(body)).digest('hex');
           if (sig !== expected) { ctx.status = 403; ctx.body = { error: 'signature mismatch' }; return; }
+        } else if (authHeader) {
+          if (authHeader !== `Bearer ${this.$config.access_token}`) { ctx.status = 403; ctx.body = { error: 'auth failed' }; return; }
         }
       }
 
@@ -88,4 +94,16 @@ export class NapCatHttpBot 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/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

@@ -7,7 +7,8 @@ import type { IncomingMessage } from 'http';
 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 type { Router } from '@zhin.js/host-router';
+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/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 * 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/host-router';
+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 */