@zhin.js/adapter-napcat 1.1.25 → 1.1.27

package/agents/napcat/skills/napcat-messaging/tools/send_poke/index.js

@@ -1,19 +1,22 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentTarget } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '戳一戳（群聊或私聊）。group_id 不传时为私聊戳一戳。',
+    description: '在当前会话戳一戳：群聊中戳 user_id 指定的成员，私聊中戳对方。',
     inputSchema: z.object({
-        user_id: z.number().describe('目标用户 QQ 号'),
-        group_id: z.number().optional().describe('群号（不传则为私聊戳一戳）'),
+        user_id: z.number().optional().describe('群聊中要戳的成员 QQ 号（私聊中忽略，固定为对方）'),
     }),
     adapter: 'napcat',
     tags: ['napcat', 'qq'],
     keywords: ['戳一戳', 'poke', '戳', '拍一拍'],
-    async execute({ user_id, group_id }, context) {
-        const endpoint = context.$client;
-        await endpoint.sendPoke(user_id, group_id);
-        return { success: true, message: t(context.locale, 'userPoked', { p0: user_id }) };
+    async execute({ user_id }, context) {
+        const target = currentTarget(context);
+        const userId = target.type === 'group' ? user_id : target.id;
+        if (userId === undefined)
+            return { success: false, message: t(context.locale, 'pokeTargetRequired') };
+        await context.$client.sendPoke(userId, target.type === 'group' ? target.id : undefined);
+        return { success: true, message: t(context.locale, 'userPoked', { p0: userId }) };
     },
 });

package/agents/napcat/skills/napcat-messaging/tools/send_poke/index.ts

@@ -1,19 +1,21 @@
 import { messages as t } from "../../../../messages.js";
+import { currentTarget } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ user_id: number; group_id?: number }>({
-  description: '戳一戳（群聊或私聊）。group_id 不传时为私聊戳一戳。',
+export default defineAgentTool<{ user_id?: number }>({
+  description: '在当前会话戳一戳：群聊中戳 user_id 指定的成员，私聊中戳对方。',
   inputSchema: z.object({
-    user_id: z.number().describe('目标用户 QQ 号'),
-    group_id: z.number().optional().describe('群号（不传则为私聊戳一戳）'),
+    user_id: z.number().optional().describe('群聊中要戳的成员 QQ 号（私聊中忽略，固定为对方）'),
   }),
   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: t(context.locale, 'userPoked', { p0: user_id }) };
+  async execute({ user_id }, context) {
+    const target = currentTarget(context);
+    const userId = target.type === 'group' ? user_id : target.id;
+    if (userId === undefined) return { success: false, message: t(context.locale, 'pokeTargetRequired') };
+    await context.$client.sendPoke(userId, target.type === 'group' ? target.id : undefined);
+    return { success: true, message: t(context.locale, 'userPoked', { p0: userId }) };
   },
 });

package/agents/napcat/skills/napcat-private-history/tools/get_friend_msg_history/index.js

@@ -1,10 +1,10 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { currentPrivatePeer } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '获取私聊消息历史记录。',
+    description: '获取当前私聊的消息历史记录。',
     inputSchema: z.object({
-        user_id: z.number().describe('QQ 号'),
         message_seq: z.number().optional().describe('起始消息序号（可选）'),
         count: z.number().optional().describe('获取条数（可选）'),
     }),
@@ -12,8 +12,7 @@ export default defineAgentTool({
     scopes: ["private"],
     tags: ['napcat', 'qq'],
     keywords: ['私聊记录', '好友聊天记录', 'friend history'],
-    async execute({ user_id, message_seq, count }, context) {
-        const endpoint = context.$client;
-        return endpoint.getFriendMsgHistory(user_id, message_seq, count);
+    async execute({ message_seq, count }, context) {
+        return context.$client.getFriendMsgHistory(currentPrivatePeer(context), message_seq, count);
     },
 });

package/agents/napcat/skills/napcat-private-history/tools/get_friend_msg_history/index.ts

@@ -1,10 +1,10 @@
+import { currentPrivatePeer } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ user_id: number; message_seq?: number; count?: number }>({
-  description: '获取私聊消息历史记录。',
+export default defineAgentTool<{ message_seq?: number; count?: number }>({
+  description: '获取当前私聊的消息历史记录。',
   inputSchema: z.object({
-    user_id: z.number().describe('QQ 号'),
     message_seq: z.number().optional().describe('起始消息序号（可选）'),
     count: z.number().optional().describe('获取条数（可选）'),
   }),
@@ -12,8 +12,7 @@ export default defineAgentTool<{ user_id: number; message_seq?: number; count?:
   scopes: ["private"],
   tags: ['napcat', 'qq'],
   keywords: ['私聊记录', '好友聊天记录', 'friend history'],
-  async execute({ user_id, message_seq, count }: { user_id: number; message_seq?: number; count?: number }, context) {
-    const endpoint = context.$client;
-      return endpoint.getFriendMsgHistory(user_id, message_seq, count);
+  async execute({ message_seq, count }, context) {
+    return context.$client.getFriendMsgHistory(currentPrivatePeer(context), message_seq, count);
   },
 });

package/lib/console-spec.js

@@ -2,11 +2,58 @@ export const napcatConsoleSpec = {
     adapterKey: 'napcat',
     adapterDisplayName: 'NapCat',
     fields: [
-        { key: 'url', description: 'NapCat WebSocket URL（connection: ws 必填）', descriptionI18n: { en: 'NapCat WebSocket URL (required for connection: ws)' } },
-        { key: 'path', description: 'reverse-wss 路径（connection: wss）', descriptionI18n: { en: 'Reverse WebSocket path (connection: wss)' } },
-        { key: 'http_url', description: 'HTTP API base URL（connection: http 出站）', descriptionI18n: { en: 'HTTP API base URL (outbound connection: http)' } },
-        { key: 'post_path', description: 'HTTP POST 事件路径（connection: http 入站）', descriptionI18n: { en: 'HTTP POST event path (inbound connection: http)' } },
-        { key: 'access_token', env: true, description: 'NapCat access token' },
+        {
+            key: 'url',
+            label: '正向 WebSocket 地址',
+            labelI18n: { en: 'Forward WebSocket URL' },
+            group: '连接模式',
+            groupI18n: { en: 'Connection Mode' },
+            placeholder: 'ws://127.0.0.1:3001',
+            description: 'NapCat WebSocket URL（connection: ws 必填）',
+            descriptionI18n: { en: 'NapCat WebSocket URL (required for connection: ws)' },
+        },
+        {
+            key: 'path',
+            label: '反向 WebSocket 路径',
+            labelI18n: { en: 'Reverse WebSocket Path' },
+            group: '连接模式',
+            groupI18n: { en: 'Connection Mode' },
+            placeholder: '/napcat/ws',
+            description: 'reverse-wss 路径（connection: wss）',
+            descriptionI18n: { en: 'Reverse WebSocket path (connection: wss)' },
+        },
+        {
+            key: 'http_url',
+            label: 'HTTP API 地址',
+            labelI18n: { en: 'HTTP API Base URL' },
+            group: '连接模式',
+            groupI18n: { en: 'Connection Mode' },
+            placeholder: 'http://127.0.0.1:3000',
+            description: 'HTTP API base URL（connection: http 出站）',
+            descriptionI18n: { en: 'HTTP API base URL (outbound connection: http)' },
+        },
+        {
+            key: 'post_path',
+            label: 'HTTP 事件上报路径',
+            labelI18n: { en: 'HTTP Event Post Path' },
+            group: '连接模式',
+            groupI18n: { en: 'Connection Mode' },
+            placeholder: '/napcat/event',
+            description: 'HTTP POST 事件路径（connection: http 入站）',
+            descriptionI18n: { en: 'HTTP POST event path (inbound connection: http)' },
+        },
+        {
+            key: 'access_token',
+            env: true,
+            label: 'Access Token (访问令牌)',
+            labelI18n: { en: 'Access Token' },
+            group: '安全认证',
+            groupI18n: { en: 'Authentication' },
+            placeholder: '与 NapCat 服务端一致的 Token',
+            placeholderI18n: { en: 'Token matching NapCat server config' },
+            description: 'NapCat 接口鉴权令牌（Access Token）',
+            descriptionI18n: { en: 'NapCat access token' },
+        },
     ],
     docsUrl: 'https://zhin.js.org/adapters/napcat',
     readPermission: 'napcat:read',

package/lib/endpoint-management.js

@@ -1,5 +1,42 @@
+import { standingFromMemberRole } from '@zhin.js/im-contract';
+/** How long one `get_login_info` answer is reused (bursts only; see inspectSelfStanding). */
+const SELF_ID_TTL_MS = 5_000;
 export function createNapCatEndpointManagement(endpoint) {
+    // The login account can change across reconnects (or a different account on the same
+    // connection), so `get_login_info` is not remembered for the endpoint's lifetime: only briefly,
+    // to coalesce bursts, and never across a failed lookup.
+    let login;
+    const loginId = async (signal) => {
+        if (login && Date.now() - login.at < SELF_ID_TTL_MS)
+            return login.id;
+        login = undefined;
+        const info = asRecord(await endpoint.requestApi({ action: 'get_login_info', signal }));
+        const id = info.user_id;
+        const value = (typeof id === 'number' && id > 0) || (typeof id === 'string' && id.trim() !== '' && id !== '0') ? String(id) : undefined;
+        if (value)
+            login = { id: value, at: Date.now() };
+        return value;
+    };
     return Object.freeze({
+        /** ADR 0056 §1: the Bot's own group role (`get_login_info`, then `get_group_member_info` self). */
+        async inspectSelfStanding({ conversation, signal }) {
+            if (conversation.kind !== 'group')
+                return undefined;
+            const selfId = await loginId(signal);
+            if (!selfId)
+                return undefined;
+            let data;
+            try {
+                data = asRecord(await endpoint.requestApi({ action: 'get_group_member_info', signal, params: {
+                        group_id: toNumberId(conversation.id, 'group_id'), user_id: toNumberId(selfId, 'user_id'), no_cache: true,
+                    } }));
+            }
+            catch (error) {
+                login = undefined;
+                throw error;
+            }
+            return standingFromMemberRole(data.role);
+        },
         async listFriends(request = {}) {
             const data = await endpoint.requestApi({ action: 'get_friend_list', signal: request.signal });
             return toArray(data).map((value) => {

package/lib/http-endpoint.d.ts

@@ -1,3 +1,6 @@
+/**
+ * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
+ */
 import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';

package/lib/http-endpoint.js

@@ -1,15 +1,18 @@
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { toCanonicalSegments } from '@zhin.js/core';
+/**
+ * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
+ */
 import { createEndpointSpecification, endpointSpec, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, callNapCatHttpAction, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, callNapCatHttpAction, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, napcatSenderStanding, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
-import { readRequestBody } from './webhook.js';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 export class NapCatHttpEndpoint extends NapcatClient {
     [endpointSpec];
@@ -123,6 +126,7 @@ export class NapCatHttpEndpoint extends NapcatClient {
         const mentioned = isNapCatBotMentioned(ev);
         const quoteId = extractQuoteId(ev);
         const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+        const platform = napcatSenderStanding(ev);
         void this[endpointSpec].events.message({
             event: nativeEvent,
             ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -133,7 +137,7 @@ export class NapCatHttpEndpoint extends NapcatClient {
             sender: {
                 id: senderUserId(ev),
                 name: nickname,
-                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+                ...(platform ? { platform } : {}),
             },
             endpointId: this.#options.config.id,
             ...(mentioned ? { mentioned: true } : {}),
@@ -157,41 +161,31 @@ export class NapCatHttpEndpoint extends NapcatClient {
     }
     #setupRoutes() {
         const path = this.#options.config.post_path;
-        this.#routeReleases.push(this.#options.http.route('POST', path, async (request, response) => {
-            await this.#handlePost(request, response);
-        }, { summary: 'NapCat HTTP event callback', tags: ['napcat'] }));
+        this.#routeReleases.push(this.#options.http.route('POST', path, (request) => this.#handlePost(request), { summary: 'NapCat HTTP event callback', tags: ['napcat'] }));
     }
-    async #handlePost(request, response) {
+    async #handlePost(request) {
         try {
             if (!verifyNapCatAccessToken(this.#options.config.access_token, request)) {
-                response.writeHead(403, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ message: 'Unauthorized' }));
-                return;
+                return new Response(JSON.stringify({ message: 'Unauthorized' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
             }
-            const raw = await readRequestBody(request);
+            const raw = await readTextBody(request);
             let ev;
             try {
                 ev = JSON.parse(raw);
             }
             catch {
-                response.writeHead(400, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ message: 'Invalid JSON' }));
-                return;
+                return new Response(JSON.stringify({ message: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
             }
             if (this.#open) {
                 void this[endpointSpec].events.run(() => this.ingest(ev)).catch((error) => {
                     this.#logger.debug(formatCompact({ op: 'napcat_receive_failed', error: error instanceof Error ? error.message : String(error) }));
                 });
             }
-            response.writeHead(200, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ status: 'ok' }));
+            return new Response(JSON.stringify({ status: 'ok' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
         }
         catch (error) {
             this.#logger.error('NapCat HTTP webhook error:', error);
-            if (!response.headersSent) {
-                response.writeHead(500, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ message: 'Internal Server Error' }));
-            }
+            return new Response(JSON.stringify({ message: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
         }
     }
 }

package/lib/index.d.ts

@@ -9,4 +9,3 @@ export { NapCatHttpEndpoint, type NapCatHttpEndpointOptions, } from './http-endp
 export type { NapCatWsSocket, NapCatWsCreateOptions } from './ws-types.js';
 export { createNapCatRpc, decodeWsPayload, type NapCatRpc, type NapCatRpcOptions, } from './ws-transport.js';
 export { verifyNapCatAccessToken } from './wss-auth.js';
-export { readRequestBody } from './webhook.js';

package/lib/index.js

@@ -7,4 +7,3 @@ export { NapCatWssEndpoint, } from './wss-endpoint.js';
 export { NapCatHttpEndpoint, } from './http-endpoint.js';
 export { createNapCatRpc, decodeWsPayload, } from './ws-transport.js';
 export { verifyNapCatAccessToken } from './wss-auth.js';
-export { readRequestBody } from './webhook.js';

package/lib/protocol.d.ts

@@ -4,7 +4,7 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { type MediaRef, type ConversationRef, type PlatformStanding } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface NapCatEndpointConfig extends EndpointProfileConfiguration {
     readonly connection?: 'ws' | 'wss' | 'http';
@@ -116,6 +116,11 @@ export declare function formatInboundContent(ev: NapCatEvent): string;
  * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
  * 显示名走 metadata.nickname，见 senderNickname。
  */
+/**
+ * ADR 0056 §1：群消息 `sender.role`（owner / admin / member）→ `sender.platform.standing`。
+ * 私聊与未知角色词不上报；OneBot / NapCat 没有平台原生角色与权限位。
+ */
+export declare function napcatSenderStanding(ev: NapCatEvent): PlatformStanding | undefined;
 export declare function senderUserId(ev: NapCatEvent): string;
 /** 显示名（群名片 card 优先于 nickname），没有则 undefined。 */
 export declare function senderNickname(ev: NapCatEvent): string | undefined;

package/lib/protocol.js

@@ -149,6 +149,16 @@ function stripCqCodes(input) {
  * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
  * 显示名走 metadata.nickname，见 senderNickname。
  */
+/**
+ * ADR 0056 §1：群消息 `sender.role`（owner / admin / member）→ `sender.platform.standing`。
+ * 私聊与未知角色词不上报；OneBot / NapCat 没有平台原生角色与权限位。
+ */
+export function napcatSenderStanding(ev) {
+    if (ev.message_type !== 'group')
+        return undefined;
+    const role = ev.sender?.role;
+    return role === 'owner' || role === 'admin' || role === 'member' ? { standing: role } : undefined;
+}
 export function senderUserId(ev) {
     return ev.user_id != null ? String(ev.user_id) : '';
 }
@@ -252,6 +262,9 @@ function canonicalToOneBotSegment(segment) {
             return oneBotMediaSegment(segment.type, data);
         case 'audio':
             return oneBotMediaSegment('record', data);
+        case 'napcat:node':
+            // Agent-authored merged-forward node (napcat_send_forward_msg); NapCat sends `node` arrays as a forward.
+            return { type: 'node', data };
         default:
             return { type: segment.type, data };
     }

package/lib/ws-endpoint.js

@@ -9,7 +9,7 @@ import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, napcatSenderStanding, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
@@ -137,6 +137,7 @@ export class NapCatWsEndpoint extends NapcatClient {
         const mentioned = isNapCatBotMentioned(ev);
         const quoteId = extractQuoteId(ev);
         const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+        const platform = napcatSenderStanding(ev);
         void this[endpointSpec].events.message({
             event: nativeEvent,
             ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -147,7 +148,7 @@ export class NapCatWsEndpoint extends NapcatClient {
             sender: {
                 id: senderUserId(ev),
                 name: nickname,
-                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+                ...(platform ? { platform } : {}),
             },
             endpointId: this.#options.config.id,
             ...(mentioned ? { mentioned: true } : {}),

package/lib/ws-types.d.ts

@@ -1,3 +1,4 @@
+import type { WsConnection } from '@zhin.js/host-http';
 /** Minimal WS surface used by the endpoint (real `ws` or test mock). */
 export interface NapCatWsSocket {
     readonly readyState: number;
@@ -11,3 +12,8 @@ export interface NapCatWsCreateOptions {
     readonly headers?: Record<string, string>;
 }
 export declare const WS_OPEN = 1;
+/**
+ * A Host reverse-WebSocket connection seen through the NapCatWsSocket surface. Protocol
+ * keepalive (ping / pong) belongs to the Host transport, so `ping` is absent.
+ */
+export declare function socketOfConnection(connection: WsConnection): NapCatWsSocket;

package/lib/ws-types.js

@@ -1 +1,32 @@
 export const WS_OPEN = 1;
+/**
+ * A Host reverse-WebSocket connection seen through the NapCatWsSocket surface. Protocol
+ * keepalive (ping / pong) belongs to the Host transport, so `ping` is absent.
+ */
+export function socketOfConnection(connection) {
+    let readyState = 1;
+    connection.onClose(() => { readyState = 3; });
+    const subscriptions = new Map();
+    const off = (_event, listener) => {
+        subscriptions.get(listener)?.();
+        subscriptions.delete(listener);
+    };
+    return {
+        get readyState() { return readyState; },
+        send: (data) => connection.send(data),
+        close: (code, reason) => connection.close(code, reason),
+        on(event, listener) {
+            if (event === 'message') {
+                subscriptions.set(listener, connection.onMessage((data) => {
+                    listener(typeof data === 'string' ? data : Buffer.from(data));
+                }));
+            }
+            else if (event === 'close') {
+                subscriptions.set(listener, connection.onClose((code, reason) => listener(code, reason)));
+            }
+            // 'error' surfaces as a close on a WsConnection; 'open' already happened.
+        },
+        off,
+        removeListener: off,
+    };
+}

package/lib/wss-auth.d.ts

@@ -1,2 +1,2 @@
-import type { IncomingMessage } from 'node:http';
-export declare function verifyNapCatAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;
+import { type ProtocolAuthRequest } from '@zhin.js/host-http';
+export declare function verifyNapCatAccessToken(accessToken: string | undefined, request: ProtocolAuthRequest): boolean;

package/lib/wss-auth.js

@@ -1,16 +1,7 @@
+import { verifyProtocolAccessToken } from '@zhin.js/host-http';
 export function verifyNapCatAccessToken(accessToken, request) {
+    // Webhook semantics: no configured token admits any caller (reverse sockets use verifyProtocolAccessToken).
     if (!accessToken)
         return true;
-    const auth = request.headers.authorization ?? '';
-    if (auth === `Bearer ${accessToken}`)
-        return true;
-    try {
-        const url = new URL(request.url ?? '/', 'http://localhost');
-        if (url.searchParams.get('access_token') === accessToken)
-            return true;
-    }
-    catch {
-        /* ignore */
-    }
-    return false;
+    return verifyProtocolAccessToken(accessToken, request);
 }

package/lib/wss-endpoint.d.ts

@@ -2,7 +2,7 @@
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
-import type { HttpHost } from '@zhin.js/host-http';
+import { type HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type NapCatWssConfig } from './protocol.js';
 import { NapcatClient } from './client.js';

package/lib/wss-endpoint.js

@@ -4,15 +4,16 @@ import { toCanonicalSegments } from '@zhin.js/core';
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { verifyProtocolAccessToken } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, extractQuoteId, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, napcatSenderStanding, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
-import { verifyNapCatAccessToken } from './wss-auth.js';
+import { socketOfConnection } from './ws-types.js';
 export class NapCatWssEndpoint extends NapcatClient {
     [endpointSpec];
     #logger;
@@ -71,7 +72,17 @@ export class NapCatWssEndpoint extends NapcatClient {
             return;
         this.#stopped = false;
         this.#started = true;
-        const handle = this.#options.http.ws(this.#options.config.path);
+        if (!this.#options.config.access_token) {
+            // 未配 access_token 时只接受本机回环连接（verifyProtocolAccessToken）。
+            this.#logger.warn(formatCompact({
+                endpoint: this.#options.config.id,
+                mode: 'wss',
+                ok: false,
+                error: 'missing access_token: only loopback peers are accepted',
+            }));
+        }
+        // The peer authenticates with this endpoint's own access_token, not a Console credential.
+        const handle = this.#options.http.ws(this.#options.config.path, { auth: 'protocol' });
         this.#wsRelease = handle.onConnection((connection) => {
             this.#connectionTask = this.#connectionTask
                 .then(() => this.#acceptConnection(connection))
@@ -150,6 +161,7 @@ export class NapCatWssEndpoint extends NapcatClient {
         const mentioned = isNapCatBotMentioned(ev);
         const quoteId = extractQuoteId(ev);
         const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+        const platform = napcatSenderStanding(ev);
         void this[endpointSpec].events.message({
             event: nativeEvent,
             ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -160,7 +172,7 @@ export class NapCatWssEndpoint extends NapcatClient {
             sender: {
                 id: senderUserId(ev),
                 name: nickname,
-                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+                ...(platform ? { platform } : {}),
             },
             endpointId: this.#options.config.id,
             ...(mentioned ? { mentioned: true } : {}),
@@ -184,14 +196,14 @@ export class NapCatWssEndpoint extends NapcatClient {
     }
     async #acceptConnection(connection) {
         if (!this.#started || this.#stopped) {
-            connection.socket.close();
+            connection.close();
             return;
         }
-        if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
-            connection.socket.close(4003, 'Unauthorized');
+        if (!verifyProtocolAccessToken(this.#options.config.access_token, connection)) {
+            connection.close(4003, 'Unauthorized');
             return;
         }
-        const socket = connection.socket;
+        const socket = socketOfConnection(connection);
         await this.#connectionLifecycle.stop();
         this.rpc.disconnect('Connection replaced');
         await this.#connectionLifecycle.start(async (lifecycleHandle) => {
@@ -208,18 +220,7 @@ export class NapCatWssEndpoint extends NapcatClient {
                     /* ignore */
                 }
             });
-            this.#connectionLifecycle.startHeartbeat(() => {
-                try {
-                    socket.ping?.();
-                }
-                catch {
-                    /* ignore */
-                }
-            }, this.#options.config.heartbeat_interval);
-            socket.on('pong', () => {
-                if (this.transportSocket === socket)
-                    this.#connectionLifecycle.notifyHeartbeatAck();
-            });
+            // Dead-peer detection is the Host transport's keepalive (protocol ping / pong).
             socket.on('message', (data) => {
                 if (this.transportSocket !== socket || this.#connectionLifecycle.state === 'closed')
                     return;
@@ -242,7 +243,7 @@ export class NapCatWssEndpoint extends NapcatClient {
         this.#logger.debug(formatCompact({
             endpoint: this.#options.config.id,
             mode: 'wss',
-            peer: connection.request.socket.remoteAddress,
+            peer: connection.remoteAddress,
         }));
     }
 }