@zhin.js/adapter-napcat 1.0.0 → 1.1.0

package/agent/tools/get_mini_app_ark.ts

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

package/agent/tools/get_user_status.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ user_id: number }>({
+  description: '获取用户在线状态。',
+  inputSchema: z.object({
+    user_id: z.number().describe('目标 QQ 号'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['在线状态', '用户状态', 'online status'],
+  async execute({ user_id }: { user_id: number }, context) {
+    const endpoint = context.$client;
+      return endpoint.ncGetUserStatus(user_id);
+  },
+});

package/agent/tools/group_sign.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number }>({
+  description: '群签到/群打卡。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['签到', '打卡', 'sign', 'check in'],
+  scopes: ['group'],
+  async execute({ group_id }: { group_id: number }, context) {
+    const endpoint = context.$client;
+      await endpoint.sendGroupSign(group_id);
+      return { success: true };
+  },
+});

package/agent/tools/mark_msg_as_read.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ message_id: number }>({
+  description: '标记消息为已读。',
+  inputSchema: z.object({
+    message_id: z.number().describe('消息 ID'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['已读', 'mark read', '标记已读'],
+  async execute({ message_id }: { message_id: number }, context) {
+    const endpoint = context.$client;
+      await endpoint.markMsgAsRead(message_id);
+      return { success: true };
+  },
+});

package/agent/tools/ocr_image.ts

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

package/agent/tools/send_forward_msg.ts

@@ -0,0 +1,27 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{
+  message_type: 'private' | 'group';
+  id: number;
+  messages: string;
+}>({
+  description: '发送合并转发消息（群聊或私聊）。messages 为转发节点数组。',
+  inputSchema: z.object({
+    message_type: z.enum(['private', 'group']).describe('private 或 group'),
+    id: z.number().describe('群号或 QQ 号'),
+    messages: z.string().describe('转发节点 JSON（node 数组）'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['合并转发', 'forward', '转发消息'],
+  async execute({ message_type, id, messages }: {
+    message_type: 'private' | 'group';
+    id: number;
+    messages: string;
+  }, context) {
+    const endpoint = context.$client;
+    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,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number; content: string; image?: string }>({
+  description: '发送群公告。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+    content: z.string().describe('公告内容'),
+    image: z.string().optional().describe('图片（URL 或 base64，可选）'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['群公告', 'notice', '公告', '发公告'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ group_id, content, image }: { group_id: number; content: string; image?: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.sendGroupNotice(group_id, content, image);
+      return { success: true };
+  },
+});

package/agent/tools/send_like.ts

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

package/agent/tools/send_poke.ts

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

package/agent/tools/set_avatar.ts

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

package/agent/tools/set_emoji_reaction.ts

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

package/agent/tools/set_essence_msg.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ message_id: number }>({
+  description: '设置群精华消息。',
+  inputSchema: z.object({
+    message_id: z.number().describe('消息 ID'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['精华', 'essence', '设精', '加精'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ message_id }: { message_id: number }, context) {
+    const endpoint = context.$client;
+      await endpoint.setEssenceMsg(message_id);
+      return { success: true };
+  },
+});

package/agent/tools/set_group_portrait.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number; file: string }>({
+  description: '设置群头像。file 为图片 URL 或 base64。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+    file: z.string().describe('图片（URL 或 base64）'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['群头像', 'group portrait', '设置群头像'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ group_id, file }: { group_id: number; file: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.setGroupPortrait(group_id, file);
+      return { success: true };
+  },
+});

package/agent/tools/set_online_status.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ status: number; ext_status?: number }>({
+  description: '设置在线状态（在线、隐身、忙碌等）。',
+  inputSchema: z.object({
+    status: z.number().describe('状态码（11=在线, 21=离开, 31=隐身, 41=忙碌, 50=请勿打扰, 60=Q我吧）'),
+    ext_status: z.number().optional().describe('扩展状态码'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['在线状态', '隐身', '忙碌', 'online', 'status'],
+  async execute({ status, ext_status }: { status: number; ext_status?: number }, context) {
+    const endpoint = context.$client;
+      await endpoint.setOnlineStatus(status, ext_status || 0);
+      return { success: true };
+  },
+});

package/agent/tools/set_profile.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ nickname: string; company?: string; email?: string; college?: string; personal_note?: string }>({
+  description: '修改 QQ 资料（昵称等）。',
+  inputSchema: z.object({
+    nickname: z.string().describe('昵称'),
+    company: z.string().optional().describe('公司（可选）'),
+    email: z.string().optional().describe('邮箱（可选）'),
+    college: z.string().optional().describe('学校（可选）'),
+    personal_note: z.string().optional().describe('个人说明（可选）'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['修改资料', '设置昵称', 'profile', 'set profile'],
+  async execute({ nickname, company, email, college, personal_note }: { nickname: string; company?: string; email?: string; college?: string; personal_note?: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.setQQProfile(nickname, company, email, college, personal_note);
+      return { success: true };
+  },
+});

package/agent/tools/set_signature.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ signature: string }>({
+  description: '设置个人签名（个性签名）。',
+  inputSchema: z.object({
+    signature: z.string().describe('签名内容'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['签名', '个性签名', 'signature', 'longnick'],
+  async execute({ signature }: { signature: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.setSelfLongnick(signature);
+      return { success: true };
+  },
+});

package/agent/tools/set_title.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number; user_id: number; title: string }>({
+  description: '设置群成员专属头衔。需要群主权限。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+    user_id: z.number().describe('目标成员 QQ 号'),
+    title: z.string().describe('头衔文字'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['头衔', 'title', '专属头衔', '设置头衔'],
+  permissions: ['platform(napcat,scene_owner)'],
+  scopes: ['group'],
+  async execute({ group_id, user_id, title }: { group_id: number; user_id: number; title: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.setTitle(group_id, user_id, title);
+      return { success: true, message: `已设置 ${user_id} 头衔为 "${title}"` };
+  },
+});

package/agent/tools/translate.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ text: string }>({
+  description: '英译中翻译。',
+  inputSchema: z.object({
+    text: z.string().describe('要翻译的英文文本'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['翻译', 'translate', '英译中'],
+  async execute({ text }: { text: string }, context) {
+    const endpoint = context.$client;
+      return endpoint.translateEn2Zh(text);
+  },
+});

package/agent/tools/upload_group_file.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number; file: string; name: string; folder?: string }>({
+  description: '上传文件到群。file 为本地路径或 URL。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+    file: z.string().describe('文件路径或 URL'),
+    name: z.string().describe('文件名'),
+    folder: z.string().optional().describe('目标文件夹 ID（可选）'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['上传文件', 'upload file', '群文件'],
+  scopes: ['group'],
+  async execute({ group_id, file, name, folder }: { group_id: number; file: string; name: string; folder?: string }, context) {
+    const endpoint = context.$client;
+      await endpoint.uploadGroupFile(group_id, file, name, folder);
+      return { success: true };
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { napcatEndpointCommands } from "../../../lib/napcat-endpoint-commands.js";
+export default napcatEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { napcatEndpointCommands } from '../../../src/napcat-endpoint-commands.js';
+
+export default napcatEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { napcatEndpointCommands } from "../../lib/napcat-endpoint-commands.js";
+export default napcatEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { napcatEndpointCommands } from '../../src/napcat-endpoint-commands.js';
+
+export default napcatEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { napcatEndpointCommands } from "../../../lib/napcat-endpoint-commands.js";
+export default napcatEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { napcatEndpointCommands } from '../../../src/napcat-endpoint-commands.js';
+
+export default napcatEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,52 @@
+import type { NapCatEvent } from './protocol.js';
+export type NapcatApiCall = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+/** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
+export declare class NapcatClient {
+    readonly callApi: NapcatApiCall;
+    constructor(callApi: NapcatApiCall);
+    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 type NapcatClientEventMap = Record<string, NapCatEvent>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly napcat: {
+            readonly client: NapcatClient;
+            readonly events: NapcatClientEventMap;
+        };
+    }
+}
+export declare const napcatClient: import("@zhin.js/adapter").EndpointClientToken<NapcatClient, NapcatClientEventMap>;

package/lib/client.js

@@ -0,0 +1,62 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
+export class NapcatClient {
+    callApi;
+    constructor(callApi) {
+        this.callApi = callApi;
+    }
+    async setTitle(groupId, userId, title, duration = -1) {
+        await this.callApi('set_group_special_title', {
+            group_id: groupId,
+            user_id: userId,
+            special_title: title,
+            duration,
+        });
+        return true;
+    }
+    sendLike(userId, times = 1) { return this.callApi('send_like', { user_id: userId, times }); }
+    deleteFriend(userId) { return this.callApi('delete_friend', { user_id: userId }); }
+    markMsgAsRead(messageId) { return this.callApi('mark_msg_as_read', { message_id: messageId }); }
+    ocrImage(image) { return this.callApi('ocr_image', { image }); }
+    setQQProfile(nickname, company, email, college, personalNote) {
+        return this.callApi('set_qq_profile', { nickname, company, email, college, personal_note: personalNote });
+    }
+    setGroupPortrait(groupId, file) { return this.callApi('set_group_portrait', { group_id: groupId, file }); }
+    setEssenceMsg(messageId) { return this.callApi('set_essence_msg', { message_id: messageId }); }
+    deleteEssenceMsg(messageId) { return this.callApi('delete_essence_msg', { message_id: messageId }); }
+    getEssenceMsgList(groupId) { return this.callApi('get_essence_msg_list', { group_id: groupId }); }
+    sendGroupSign(groupId) { return this.callApi('send_group_sign', { group_id: groupId }); }
+    sendGroupNotice(groupId, content, image) { return this.callApi('_send_group_notice', { group_id: groupId, content, image }); }
+    getGroupNotice(groupId) { return this.callApi('_get_group_notice', { group_id: groupId }); }
+    deleteGroupNotice(groupId, noticeId) { return this.callApi('_del_group_notice', { group_id: groupId, notice_id: noticeId }); }
+    uploadGroupFile(groupId, file, name, folder) { return this.callApi('upload_group_file', { group_id: groupId, file, name, folder }); }
+    getGroupRootFiles(groupId) { return this.callApi('get_group_root_files', { group_id: groupId }); }
+    getGroupFileUrl(groupId, fileId, busid) { return this.callApi('get_group_file_url', { group_id: groupId, file_id: fileId, busid }); }
+    downloadFile(url, threadCount = 1, headers) { return this.callApi('download_file', { url, thread_count: threadCount, headers }); }
+    setOnlineStatus(status, extStatus) { return this.callApi('set_online_status', { status, ext_status: extStatus }); }
+    setQQAvatar(file) { return this.callApi('set_qq_avatar', { file }); }
+    forwardFriendSingleMsg(userId, messageId) { return this.callApi('forward_friend_single_msg', { user_id: userId, message_id: messageId }); }
+    forwardGroupSingleMsg(groupId, messageId) { return this.callApi('forward_group_single_msg', { group_id: groupId, message_id: messageId }); }
+    translateEn2Zh(sourceText) { return this.callApi('translate_en2zh', { source_text: sourceText }); }
+    setMsgEmojiLike(messageId, emojiId) { return this.callApi('set_msg_emoji_like', { message_id: messageId, emoji_id: emojiId }); }
+    sendForwardMsg(messageType, id, messages) {
+        return this.callApi('send_forward_msg', {
+            message_type: messageType,
+            [messageType === 'group' ? 'group_id' : 'user_id']: id,
+            messages,
+        });
+    }
+    getFriendMsgHistory(userId, messageSeq, count) { return this.callApi('get_friend_msg_history', { user_id: userId, message_seq: messageSeq, count }); }
+    getGroupMsgHistory(groupId, messageSeq, count) { return this.callApi('get_group_msg_history', { group_id: groupId, message_seq: messageSeq, count }); }
+    setSelfLongnick(longnick) { return this.callApi('set_self_longnick', { longNick: longnick }); }
+    getGroupInfoEx(groupId) { return this.callApi('get_group_info_ex', { group_id: groupId }); }
+    sendPoke(userId, groupId) { return this.callApi('send_poke', { user_id: userId, group_id: groupId }); }
+    ncGetUserStatus(userId) { return this.callApi('nc_get_user_status', { user_id: userId }); }
+    getGroupShutList(groupId) { return this.callApi('get_group_shut_list', { group_id: groupId }); }
+    getMiniAppArk(type, title, desc, picUrl, jumpUrl) { return this.callApi('get_mini_app_ark', { type, title, desc, picUrl, jumpUrl }); }
+    getAiCharacters(groupId) { return this.callApi('get_ai_characters', { group_id: groupId }); }
+    sendGroupAiRecord(groupId, characterId, text) {
+        return this.callApi('send_group_ai_record', { group_id: groupId, character: characterId, text });
+    }
+}
+export const napcatClient = defineEndpointClient('napcat');

package/lib/endpoint-management.d.ts

@@ -0,0 +1,15 @@
+/**
+ * NapCat endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OneBot11 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from 'zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createNapCatEndpointManagement(endpoint: NapCatManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createNapCatEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = await endpoint.callApi('get_friend_list');
+            return toArray(data).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.nickname ?? ''),
+                    remark: String(friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = await endpoint.callApi('get_group_list');
+            return toArray(data).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = await endpoint.callApi('get_group_member_list', {
+                group_id: toNumberId(groupId, 'group_id'),
+            });
+            return toArray(data);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`napcat ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/http-endpoint.d.ts

@@ -0,0 +1,27 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
+import { NapcatClient } from './client.js';
+export interface NapCatHttpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: NapCatHttpConfig;
+    readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+export declare class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
+    #private;
+    readonly client: NapcatClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    constructor(options: NapCatHttpEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+    admit(ev: NapCatEvent): void;
+}