@zhin.js/adapter-napcat 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @zhin.js/adapter-napcat
 
+## 3.0.2
+
+### Patch Changes
+
+- 872c583: Slack 适配器 Phase 1/2：mrkdwn 出站、长消息切分、斜杠/按钮 ephemeral 反馈、入站 mrkdwn→Markdown、editMessage 对齐 core。
+
+  Logger 表格日志与 string-width 列宽；Agent AI Handler 框线表格与 introspection/MCP 导出；Core side-event 归一化；Schedule 时区规划；多适配器 side-event 与 API surface 更新。
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/contract@1.0.3
+  - @zhin.js/host-api@2.0.5
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -120,7 +120,6 @@ endpoints:
 
 ## AI 工具
 
-适配器自动注册 41 个 AI 工具（7 个群管理标准工具 + 34 个 NapCat 扩展工具），详见 `skills/napcat/SKILL.md`。
 
 ## full-bot L4 参考
 

package/agent/tools/ai_tts.ts

@@ -0,0 +1,21 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number; character: string; text: string }>({
+  description: 'AI 文字转语音，在群聊中发送 AI 语音消息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    character: z.string().describe('AI 语音角色 ID（可先用 napcat_get_ai_characters 查询）'),
+    text: z.string().describe('要转为语音的文字'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['AI语音', 'TTS', '文字转语音', 'ai record'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, character, text }: { endpoint_id: string; group_id: number; character: string; text: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.sendGroupAiRecord(group_id, character, text);
+  },
+});

package/agent/tools/del_group_notice.ts

@@ -0,0 +1,22 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number; notice_id: string }>({
+  description: '删除群公告。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    notice_id: z.string().describe('公告 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['删除公告', 'delete notice'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, notice_id }: { endpoint_id: string; group_id: number; notice_id: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteGroupNotice(group_id, notice_id);
+      return { success: true };
+  },
+});

package/agent/tools/delete_essence_msg.ts

@@ -0,0 +1,21 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; message_id: number }>({
+  description: '移除群精华消息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_id: z.number().describe('消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['取消精华', '移除精华', 'delete essence'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, message_id }: { endpoint_id: string; message_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteEssenceMsg(message_id);
+      return { success: true };
+  },
+});

package/agent/tools/delete_friend.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; user_id: number }>({
+  description: '删除好友。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('好友 QQ 号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['删除好友', 'delete friend', '删好友'],
+  permissions: ['platform(napcat,scene_admin)'],
+  async execute({ endpoint_id, user_id }: { endpoint_id: string; user_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteFriend(user_id);
+      return { success: true };
+  },
+});

package/agent/tools/download_file.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; url: string; thread_count?: number }>({
+  description: '下载文件到 NapCat 缓存目录，返回本地路径。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    url: z.string().describe('文件 URL'),
+    thread_count: z.number().optional().describe('下载线程数（可选，默认 1）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['下载', 'download', '下载文件'],
+  async execute({ endpoint_id, url, thread_count }: { endpoint_id: string; url: string; thread_count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.downloadFile(url, thread_count || 1);
+  },
+});

package/agent/tools/forward_single_msg.ts

@@ -0,0 +1,32 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  target_type: 'friend' | 'group';
+  target_id: number;
+  message_id: number;
+}>({
+  description: '转发单条消息到指定好友或群。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    target_type: z.enum(['friend', 'group']).describe('friend 或 group'),
+    target_id: z.number().describe('目标好友 QQ 号或群号'),
+    message_id: z.number().describe('要转发的消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['转发', 'forward', '单条转发'],
+  async execute({ endpoint_id, target_type, target_id, message_id }: {
+    endpoint_id: string;
+    target_type: 'friend' | 'group';
+    target_id: number;
+    message_id: number;
+  }) {
+    const endpoint = getEndpoint(endpoint_id);
+    if (target_type === 'friend') await endpoint.forwardFriendSingleMsg(target_id, message_id);
+    else await endpoint.forwardGroupSingleMsg(target_id, message_id);
+    return { success: true };
+  },
+});

package/agent/tools/get_ai_characters.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取 AI 语音角色列表，用于 napcat_ai_tts 的 character 参数。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['AI角色', 'ai characters', '语音角色'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getAiCharacters(group_id);
+  },
+});

package/agent/tools/get_essence_list.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群精华消息列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['精华列表', 'essence list'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getEssenceMsgList(group_id);
+  },
+});

package/agent/tools/get_friend_msg_history.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; user_id: number; message_seq?: number; count?: number }>({
+  description: '获取私聊消息历史记录。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('QQ 号'),
+    message_seq: z.number().optional().describe('起始消息序号（可选）'),
+    count: z.number().optional().describe('获取条数（可选）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['私聊记录', '好友聊天记录', 'friend history'],
+  async execute({ endpoint_id, user_id, message_seq, count }: { endpoint_id: string; user_id: number; message_seq?: number; count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getFriendMsgHistory(user_id, message_seq, count);
+  },
+});

package/agent/tools/get_group_file_url.ts

@@ -0,0 +1,21 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number; file_id: string; busid: number }>({
+  description: '获取群文件下载链接。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    file_id: z.string().describe('文件 ID'),
+    busid: z.number().describe('文件类型 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['文件链接', 'file url', '下载文件'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, file_id, busid }: { endpoint_id: string; group_id: number; file_id: string; busid: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupFileUrl(group_id, file_id, busid);
+  },
+});

package/agent/tools/get_group_info_ex.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群组额外详细信息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群详情', '群额外信息', 'group info ex'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupInfoEx(group_id);
+  },
+});

package/agent/tools/get_group_msg_history.ts

@@ -0,0 +1,21 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number; message_seq?: number; count?: number }>({
+  description: '获取群消息历史记录。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    message_seq: z.number().optional().describe('起始消息序号（可选，不传从最新开始）'),
+    count: z.number().optional().describe('获取条数（可选）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群消息历史', '聊天记录', 'message history'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, message_seq, count }: { endpoint_id: string; group_id: number; message_seq?: number; count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupMsgHistory(group_id, message_seq, count);
+  },
+});

package/agent/tools/get_group_notice.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群公告列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群公告', '获取公告', 'get notice'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupNotice(group_id);
+  },
+});

package/agent/tools/get_group_root_files.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群根目录文件列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群文件列表', 'group files'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupRootFiles(group_id);
+  },
+});

package/agent/tools/get_group_shut_list.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群禁言列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['禁言列表', 'shut list', '被禁言'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupShutList(group_id);
+  },
+});

package/agent/tools/get_mini_app_ark.ts

@@ -0,0 +1,22 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; type: string; title: string; desc: string; pic_url: string; jump_url: string }>({
+  description: '签名小程序卡片（如 B 站分享卡片等）。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    type: z.string().describe('卡片类型'),
+    title: z.string().describe('标题'),
+    desc: z.string().describe('描述'),
+    pic_url: z.string().describe('图片 URL'),
+    jump_url: z.string().describe('跳转 URL'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['小程序', 'mini app', '卡片', 'ark'],
+  async execute({ endpoint_id, type, title, desc, pic_url, jump_url }: { endpoint_id: string; type: string; title: string; desc: string; pic_url: string; jump_url: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getMiniAppArk(type, title, desc, pic_url, jump_url);
+  },
+});

package/agent/tools/get_user_status.ts

@@ -0,0 +1,18 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; user_id: number }>({
+  description: '获取用户在线状态。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('目标 QQ 号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['在线状态', '用户状态', 'online status'],
+  async execute({ endpoint_id, user_id }: { endpoint_id: string; user_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.ncGetUserStatus(user_id);
+  },
+});

package/agent/tools/group_sign.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number }>({
+  description: '群签到/群打卡。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['签到', '打卡', 'sign', 'check in'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.sendGroupSign(group_id);
+      return { success: true };
+  },
+});

package/agent/tools/mark_msg_as_read.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; message_id: number }>({
+  description: '标记消息为已读。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_id: z.number().describe('消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['已读', 'mark read', '标记已读'],
+  async execute({ endpoint_id, message_id }: { endpoint_id: string; message_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.markMsgAsRead(message_id);
+      return { success: true };
+  },
+});

package/agent/tools/ocr_image.ts

@@ -0,0 +1,18 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; image: string }>({
+  description: '图片 OCR 文字识别。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    image: z.string().describe('图片 file 参数（收到消息中的 file 字段或 URL）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['OCR', '文字识别', '图片识别', 'ocr'],
+  async execute({ endpoint_id, image }: { endpoint_id: string; image: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.ocrImage(image);
+  },
+});

package/agent/tools/send_forward_msg.ts

@@ -0,0 +1,31 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  message_type: 'private' | 'group';
+  id: number;
+  messages: string;
+}>({
+  description: '发送合并转发消息（群聊或私聊）。messages 为转发节点数组。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_type: z.enum(['private', 'group']).describe('private 或 group'),
+    id: z.number().describe('群号或 QQ 号'),
+    messages: z.string().describe('转发节点 JSON（node 数组）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['合并转发', 'forward', '转发消息'],
+  async execute({ endpoint_id, message_type, id, messages }: {
+    endpoint_id: string;
+    message_type: 'private' | 'group';
+    id: number;
+    messages: string;
+  }) {
+    const endpoint = getEndpoint(endpoint_id);
+    const nodes = typeof messages === 'string' ? JSON.parse(messages) : messages;
+    return endpoint.sendForwardMsg(message_type, id, nodes);
+  },
+});

package/agent/tools/send_group_notice.ts

@@ -0,0 +1,23 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; group_id: number; content: string; image?: string }>({
+  description: '发送群公告。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    content: z.string().describe('公告内容'),
+    image: z.string().optional().describe('图片（URL 或 base64，可选）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群公告', 'notice', '公告', '发公告'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, content, image }: { endpoint_id: string; group_id: number; content: string; image?: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.sendGroupNotice(group_id, content, image);
+      return { success: true };
+  },
+});

package/agent/tools/send_like.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; user_id: number; times?: number }>({
+  description: '给好友点赞（每人每天最多 10 次）。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('目标 QQ 号'),
+    times: z.number().optional().describe('点赞次数（1-10）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['点赞', 'like', '赞', '好友赞'],
+  async execute({ endpoint_id, user_id, times }: { endpoint_id: string; user_id: number; times?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.sendLike(user_id, times || 1);
+      return { success: true, message: `已给 ${user_id} 点赞 ${times || 1} 次` };
+  },
+});

package/agent/tools/send_poke.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; user_id: number; group_id?: number }>({
+  description: '戳一戳（群聊或私聊）。group_id 不传时为私聊戳一戳。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('目标用户 QQ 号'),
+    group_id: z.number().optional().describe('群号（不传则为私聊戳一戳）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['戳一戳', 'poke', '戳', '拍一拍'],
+  async execute({ endpoint_id, user_id, group_id }: { endpoint_id: string; user_id: number; group_id?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.sendPoke(user_id, group_id);
+      return { success: true, message: `已戳 ${user_id}` };
+  },
+});

package/agent/tools/set_avatar.ts

@@ -0,0 +1,19 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; file: string }>({
+  description: '修改 QQ 头像。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    file: z.string().describe('图片（URL 或 base64）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['头像', 'avatar', '设置头像', '换头像'],
+  async execute({ endpoint_id, file }: { endpoint_id: string; file: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.setQQAvatar(file);
+      return { success: true };
+  },
+});

package/agent/tools/set_emoji_reaction.ts

@@ -0,0 +1,20 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; message_id: number; emoji_id: string }>({
+  description: '为消息添加表情回应（贴表情）。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_id: z.number().describe('消息 ID'),
+    emoji_id: z.string().describe('表情 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['表情回应', 'reaction', '贴表情', 'emoji'],
+  async execute({ endpoint_id, message_id, emoji_id }: { endpoint_id: string; message_id: number; emoji_id: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.setMsgEmojiLike(message_id, emoji_id);
+      return { success: true };
+  },
+});

package/agent/tools/set_essence_msg.ts

@@ -0,0 +1,21 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineTool<{ endpoint_id: string; message_id: number }>({
+  description: '设置群精华消息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_id: z.number().describe('消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['精华', 'essence', '设精', '加精'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, message_id }: { endpoint_id: string; message_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.setEssenceMsg(message_id);
+      return { success: true };
+  },
+});