@zhin.js/adapter-napcat 1.0.1 → 1.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.0.1",
-  "description": "Zhin.js adapter for NapCatQQ (OneBot11 superset with go-cqhttp & NapCat extensions)",
+  "version": "1.1.2",
+  "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,14 +13,17 @@
     }
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "tools",
+    "agents",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PERMITS.md"
   ],
   "keywords": [
     "zhin",
@@ -34,58 +37,97 @@
     "qq",
     "chatbot"
   ],
-  "author": {
-    "name": "lc-cn",
-    "email": "admin@liucl.cn",
-    "url": "https://github.com/lc-cn"
-  },
   "license": "MIT",
   "repository": {
-    "url": "git+https://github.com/zhinjs/zhin.git",
     "type": "git",
+    "url": "https://github.com/zhinjs/zhin",
     "directory": "plugins/adapters/napcat"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "ws": "^8.21.1",
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/agent-feature": "1.1.1",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/permission": "1.1.1",
+    "@zhin.js/skill": "1.1.1",
+    "@zhin.js/tool": "1.1.1"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
-    "@types/react": "^19.2.15",
-    "@types/react-dom": "^19.2.3",
+    "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
-    "lucide-react": "^1.17.0",
     "typescript": "^6.0.3",
-    "@zhin.js/agent": "0.2.1",
-    "@zhin.js/cli": "1.0.89",
-    "@zhin.js/contract": "1.0.1",
-    "@zhin.js/host-api": "1.0.1",
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/host-http": "1.1.1",
+    "zhin.js": "1.1.2"
   },
   "peerDependencies": {
-    "@zhin.js/agent": "0.2.1",
-    "@zhin.js/host-api": "1.0.1",
-    "@zhin.js/contract": "1.0.1",
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
+    "@zhin.js/command": {
       "optional": true
     },
-    "@zhin.js/host-api": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/host-router": {
+    "zod": {
       "optional": true
     }
   },
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/agent-feature",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/napcat/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
+import { napcatRuntimeStateToken } from "./lib/napcat-runtime-state.js";
+export default definePlugin({
+    name: 'napcat',
+    metadata: {
+        displayName: 'NapCat Adapter',
+    },
+    setup(context) {
+        context.resources.provide(napcatRuntimeStateToken, createEndpointRuntimeState());
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('napcat', createSceneRolePlatformChecker());
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": [
+        "ws",
+        "wss",
+        "http"
+      ],
+      "default": "ws",
+      "description": "ws (default), wss (reverse WS), or http (POST webhook + HTTP API outbound)"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    },
+    "poll_interval": {
+      "type": "number",
+      "default": 30000
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（QQ uin；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted QQ uin"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（QQ uin）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted QQ uin"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "ws",
+              "wss",
+              "http"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "description": "NapCat WebSocket URL (required for connection: ws)"
+          },
+          "path": {
+            "type": "string",
+            "description": "WS path for reverse-wss"
+          },
+          "http_url": {
+            "type": "string",
+            "description": "HTTP API base URL (connection: http outbound)"
+          },
+          "post_path": {
+            "type": "string",
+            "description": "HTTP POST event path (connection: http inbound)"
+          },
+          "access_token": {
+            "type": "string",
+            "description": "NapCat access token"
+          },
+          "reconnect_interval": {
+            "type": "number"
+          },
+          "heartbeat_interval": {
+            "type": "number"
+          },
+          "poll_interval": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "NapCat bot name"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

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

package/src/endpoint-management.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from 'zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createNapCatEndpointManagement(
+  endpoint: NapCatManagementCaller,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      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(): Promise<readonly EndpointGroup[]> {
+      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: string): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi('get_group_member_list', {
+        group_id: toNumberId(groupId, 'group_id'),
+      });
+      return toArray(data);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`napcat ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}