@zhin.js/adapter-napcat 6.0.13 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @zhin.js/adapter-napcat
 
+## 7.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
+## 6.0.14
+
+### Patch Changes
+
+- fccdbd7: Add canonical scoped message and merged-forward resolution through NapCat APIs.
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
 ## 6.0.13
 
 ### Patch Changes

package/README.md

@@ -67,7 +67,7 @@ plugins:
 
 ## 迁移说明（Plugin Runtime）
 
-- **notice / request 侧事件已移除**：旧 Adapter 对 `post_type: notice|request` 构建 `notice.receive` / `request.receive` 事件（含 `$approve` / `$reject`）；新 Plugin Runtime（`messageGatewayToken`）暂无侧事件总线，入站仅处理 `post_type: message`，notice / request 事件静默丢弃。加好友 / 加群请求审批可改用 `callApi('set_friend_add_request' | 'set_group_add_request')`。
+- **notice / request / meta 侧事件**：经 `sideEventGatewayToken` 归一后分发到 `handlers`（`notice.receive` / `request.receive` / `system.receive`），请求带 `$approve` / `$reject`。消息仍走 `messageGatewayToken`。
 - **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后 `agent/tools/` 仅覆盖 NapCat 扩展 API，其余群管能力可通过 `callApi`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
 - **平台权限门禁**：`plugin.ts` setup 已注册 `registerDefaultScenePlatformPermitChecker('napcat')`，`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`（owner / admin）判定。
 

package/adapters/napcat.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/napcat.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { NapCatHttpEndpoint } from "../lib/http-endpoint.js";
 import { resolveNapCatConfig } from "../lib/protocol.js";
@@ -15,6 +15,7 @@ export { NapCatWsEndpoint, } from "../lib/ws-endpoint.js";
 export { NapCatWssEndpoint, } from "../lib/wss-endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // OneBot file 参数原生消费 url / base64:// 媒体，file:// 本地路径由 NapCat 侧读盘；
     // 无卡片交互面，交互段降级纯文本。
     segments: {
@@ -24,17 +25,30 @@ export default defineAdapter({
     create(context) {
         const config = resolveNapCatConfig(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（napcat.endpoint list 的"运行中"数据源）
         context.use(napcatRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.connection,
         });
         if (config.connection === 'wss') {
-            return new NapCatWssEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+            return new NapCatWssEndpoint({
+                id: context.id,
+                gateway,
+                sideEvents,
+                http: context.use(httpHostToken),
+                config,
+            });
         }
         if (config.connection === 'http') {
-            return new NapCatHttpEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+            return new NapCatHttpEndpoint({
+                id: context.id,
+                gateway,
+                sideEvents,
+                http: context.use(httpHostToken),
+                config,
+            });
         }
-        return new NapCatWsEndpoint({ id: context.id, gateway, config });
+        return new NapCatWsEndpoint({ id: context.id, gateway, sideEvents, config });
     },
 });

package/adapters/napcat.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/napcat.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { NapCatHttpEndpoint } from '../src/http-endpoint.js';
 import { resolveNapCatConfig, type NapCatAdapterConfig } from '../src/protocol.js';
@@ -24,8 +24,15 @@ export {
 } from '../src/wss-endpoint.js';
 export type { NapCatWsSocket, NapCatWsCreateOptions } from '../src/ws-types.js';
 
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    napcat: import('../src/ws-endpoint.js').NapCatWsEndpoint;
+  }
+}
+
 export default defineAdapter<NapCatAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // OneBot file 参数原生消费 url / base64:// 媒体，file:// 本地路径由 NapCat 侧读盘；
   // 无卡片交互面，交互段降级纯文本。
   segments: {
@@ -35,17 +42,30 @@ export default defineAdapter<NapCatAdapterConfig>({
   create(context) {
     const config = resolveNapCatConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（napcat.endpoint list 的"运行中"数据源）
     context.use(napcatRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: config.connection,
     });
     if (config.connection === 'wss') {
-      return new NapCatWssEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+      return new NapCatWssEndpoint({
+        id: context.id,
+        gateway,
+        sideEvents,
+        http: context.use(httpHostToken),
+        config,
+      });
     }
     if (config.connection === 'http') {
-      return new NapCatHttpEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+      return new NapCatHttpEndpoint({
+        id: context.id,
+        gateway,
+        sideEvents,
+        http: context.use(httpHostToken),
+        config,
+      });
     }
-    return new NapCatWsEndpoint({ id: context.id, gateway, config });
+    return new NapCatWsEndpoint({ id: context.id, gateway, sideEvents, config });
   },
 });

package/lib/http-endpoint.d.ts

@@ -1,11 +1,12 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
 export interface NapCatHttpEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: NapCatHttpConfig;
     readonly callHttpAction?: typeof callNapCatHttpAction;
@@ -13,6 +14,8 @@ export interface NapCatHttpEndpointOptions {
 export declare class NapCatHttpEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatHttpEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/http-endpoint.js

@@ -1,8 +1,11 @@
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 import { readRequestBody } from './webhook.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 export class NapCatHttpEndpoint {
@@ -10,6 +13,8 @@ export class NapCatHttpEndpoint {
     #options;
     #inboundDeduper = new InboundMessageDeduper();
     management = createNapCatEndpointManagement(this);
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content = createNapCatContentPort((action, params) => this.callApi(action, params));
     #callHttpAction;
     #routeReleases = [];
     #open = false;
@@ -78,8 +83,12 @@ export class NapCatHttpEndpoint {
         }, action, params).then((resp) => resp.data);
     }
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveNapCatSideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         if (isSelfMessage(ev))
             return;
         const msgId = String(ev.message_id);

package/lib/onebot-get-msg.d.ts

@@ -1,4 +1,4 @@
-export interface QuotedMessagePayload {
+export interface NapcatMessageLookup {
     messageId: string;
     sender?: {
         id: string;
@@ -11,4 +11,6 @@ export interface QuotedMessagePayload {
     raw?: string;
     time?: number;
 }
-export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): QuotedMessagePayload;
+export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): NapcatMessageLookup;
+export declare function createNapCatContentPort(callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>): EndpointContentPort;
+import type { EndpointContentPort } from 'zhin.js/adapter';

package/lib/onebot-get-msg.js

@@ -24,3 +24,56 @@ export function parseOneBotGetMsgResponse(messageId, data) {
         time: typeof record.time === 'number' ? record.time : undefined,
     };
 }
+export function createNapCatContentPort(callApi) {
+    return Object.freeze({
+        async resolve(reference, context) {
+            try {
+                context.signal.throwIfAborted();
+                if (reference.kind === 'media') {
+                    return reference.media.kind === 'file'
+                        ? Object.freeze({ status: 'unsupported', code: 'napcat_opaque_media_requires_platform_file_metadata' })
+                        : Object.freeze({ status: 'resolved', reference, value: reference.media });
+                }
+                if (reference.kind === 'message') {
+                    const parsed = parseOneBotGetMsgResponse(reference.message.id, await callApi('get_msg', { message_id: reference.message.id }));
+                    context.signal.throwIfAborted();
+                    const value = Object.freeze({
+                        ref: reference.message,
+                        ...(parsed.sender?.id ? { actor: Object.freeze({ id: parsed.sender.id, ...(parsed.sender.name ? { displayName: parsed.sender.name } : {}) }) } : {}),
+                        segments: canonicalSegments(parsed.content),
+                        timestamp: toMillis(parsed.time),
+                    });
+                    return Object.freeze({ status: 'resolved', reference, value });
+                }
+                const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId });
+                context.signal.throwIfAborted();
+                const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+                const value = Object.freeze(nodes.map((node) => {
+                    const row = node;
+                    const sender = row.sender;
+                    return Object.freeze({
+                        ...(sender?.user_id != null ? { actor: Object.freeze({ id: String(sender.user_id), ...(sender.nickname ? { displayName: String(sender.nickname) } : {}) }) } : {}),
+                        segments: canonicalSegments(Array.isArray(row.content) ? row.content : []),
+                        timestamp: toMillis(row.time),
+                    });
+                }));
+                return Object.freeze({ status: 'resolved', reference, value });
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+                return Object.freeze({ status: 'failed', code: 'napcat_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+}
+function canonicalSegments(content) {
+    return Object.freeze(content.map((segment) => Object.freeze({
+        type: segment.type,
+        data: Object.freeze(segment.data ?? {}),
+    })));
+}
+function toMillis(value) {
+    const time = Number(value);
+    return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

package/lib/protocol.js

@@ -106,16 +106,16 @@ export function napcatOutboundTarget(conversation) {
     };
 }
 export function formatInboundContent(ev) {
-    if (typeof ev.raw_message === 'string' && ev.raw_message)
-        return ev.raw_message;
     if (Array.isArray(ev.message)) {
         return ev.message
             .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
             .join('');
     }
     if (typeof ev.message === 'string')
-        return ev.message;
-    return '';
+        return ev.message.replace(/\[CQ:[^\]]+\]/g, '').trim();
+    return typeof ev.raw_message === 'string'
+        ? ev.raw_message.replace(/\[CQ:[^\]]+\]/g, '').trim()
+        : '';
 }
 /**
  * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,7 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import type { NapCatEvent } from './protocol.js';
+export interface NapCatSideEventCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function receiveNapCatSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: NapCatSideEventCaller, raw: NapCatEvent, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -0,0 +1,36 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+export function receiveNapCatSideEvent(sideEvents, endpointKey, caller, raw, logger) {
+    if (!sideEvents)
+        return;
+    const record = raw;
+    const postType = String(record.post_type ?? '');
+    const requestType = String(record.request_type ?? '');
+    const isRequest = postType === 'request' || postType.startsWith('request.');
+    const isFriend = requestType === 'friend' || postType.includes('friend');
+    void receiveOneBotLikeSideEvent(sideEvents, {
+        adapter: 'napcat',
+        endpointKey,
+        platform: 'napcat',
+        raw: record,
+        ...(isRequest ? {
+            approve: async (flag, remark) => {
+                await (isFriend
+                    ? caller.callApi('set_friend_add_request', { flag, approve: true, remark })
+                    : caller.callApi('set_group_add_request', { flag, approve: true, reason: remark }));
+            },
+            reject: async (flag, reason) => {
+                await (isFriend
+                    ? caller.callApi('set_friend_add_request', { flag, approve: false })
+                    : caller.callApi('set_group_add_request', { flag, approve: false, reason }));
+            },
+        } : {}),
+    }).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'napcat_side_event_failed',
+            endpoint: endpointKey,
+            post_type: postType || undefined,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

package/lib/ws-endpoint.d.ts

@@ -1,17 +1,20 @@
-import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from 'zhin.js';
 import { type NapCatEvent, type NapCatWsConfig } from './protocol.js';
 import { type NapCatWsCreateOptions, type NapCatWsSocket } from './ws-types.js';
 export interface NapCatWsEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: NapCatWsConfig;
     readonly createWebSocket?: (url: string, options: NapCatWsCreateOptions) => NapCatWsSocket;
 }
 export declare class NapCatWsEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatWsEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/ws-endpoint.js

@@ -2,18 +2,22 @@
  * NapCat WS client endpoint — outbound connect to NapCat.
  */
 import WebSocket from 'ws';
-import { createEndpointLifecycle, } from 'zhin.js/adapter';
+import { createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, } from './ws-transport.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 export class NapCatWsEndpoint {
     #logger;
     #options;
     #inboundDeduper = new InboundMessageDeduper();
     management = createNapCatEndpointManagement(this);
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content = createNapCatContentPort((action, params) => this.callApi(action, params));
     #lifecycle;
     #ws;
     #requestId = { value: 0 };
@@ -228,8 +232,12 @@ export class NapCatWsEndpoint {
     }
     /** Test / internal: admit a parsed event when the endpoint is open. */
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveNapCatSideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         if (isSelfMessage(ev))
             return;
         const msgId = String(ev.message_id);

package/lib/wss-endpoint.d.ts

@@ -1,17 +1,20 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type NapCatEvent, type NapCatWssConfig } from './protocol.js';
 export interface NapCatWssEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: NapCatWssConfig;
 }
 export declare class NapCatWssEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatWssEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/wss-endpoint.js

@@ -2,11 +2,14 @@
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import { clearInterval } from 'node:timers';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 export class NapCatWssEndpoint {
@@ -14,6 +17,8 @@ export class NapCatWssEndpoint {
     #options;
     #inboundDeduper = new InboundMessageDeduper();
     management = createNapCatEndpointManagement(this);
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content = createNapCatContentPort((action, params) => this.callApi(action, params));
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -86,8 +91,12 @@ export class NapCatWssEndpoint {
         return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveNapCatSideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         if (isSelfMessage(ev))
             return;
         const msgId = String(ev.message_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "6.0.13",
+  "version": "7.0.0",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,12 +43,12 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.2"
+    "@zhin.js/permission": "1.0.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -56,17 +56,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.11"
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/host-http": "1.0.12",
+    "zhin.js": "6.0.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.11",
-    "zhin.js": "6.0.11"
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.13",
+    "zhin.js": "6.0.13"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {

package/src/http-endpoint.ts

@@ -2,8 +2,14 @@
  * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointInstance,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -28,6 +34,8 @@ import {
   type NapCatEvent,
   type NapCatHttpConfig,
 } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 import { readRequestBody } from './webhook.js';
 import { NapCatWsEndpoint } from './ws-endpoint.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
@@ -35,6 +43,7 @@ import { verifyNapCatAccessToken } from './wss-auth.js';
 export interface NapCatHttpEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: NapCatHttpConfig;
   readonly callHttpAction?: typeof callNapCatHttpAction;
@@ -46,6 +55,8 @@ export class NapCatHttpEndpoint implements EndpointInstance {
   readonly #options: NapCatHttpEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
   readonly management: EndpointManagement = createNapCatEndpointManagement(this);
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content = createNapCatContentPort((action, params) => this.callApi(action, params));
   readonly #callHttpAction: typeof callNapCatHttpAction;
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
@@ -131,7 +142,17 @@ export class NapCatHttpEndpoint implements EndpointInstance {
   }
 
   admit(ev: NapCatEvent): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveNapCatSideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     if (isSelfMessage(ev)) return;
     const msgId = String(ev.message_id);
     if (!this.#inboundDeduper.shouldProcess(msgId)) return;

package/src/onebot-get-msg.ts

@@ -1,4 +1,4 @@
-export interface QuotedMessagePayload {
+export interface NapcatMessageLookup {
   messageId: string;
   sender?: { id: string; name: string };
   content: Array<{ type: string; data?: Record<string, unknown> }>;
@@ -9,18 +9,18 @@ export interface QuotedMessagePayload {
 export function parseOneBotGetMsgResponse(
   messageId: string,
   data: unknown,
-): QuotedMessagePayload {
+): NapcatMessageLookup {
   const record =
     data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
-  let content: QuotedMessagePayload['content'] = [];
+  let content: NapcatMessageLookup['content'] = [];
   if (Array.isArray(record.message)) {
-    content = record.message as QuotedMessagePayload['content'];
+    content = record.message as NapcatMessageLookup['content'];
   } else if (typeof record.raw_message === 'string' && record.raw_message) {
     content = [{ type: 'text', data: { text: record.raw_message } }];
   }
 
   const senderRaw = record.sender;
-  let sender: QuotedMessagePayload['sender'];
+  let sender: NapcatMessageLookup['sender'];
   if (senderRaw && typeof senderRaw === 'object') {
     const s = senderRaw as Record<string, unknown>;
     sender = {
@@ -37,3 +37,61 @@ export function parseOneBotGetMsgResponse(
     time: typeof record.time === 'number' ? record.time : undefined,
   };
 }
+
+export function createNapCatContentPort(
+  callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>,
+): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'napcat_opaque_media_requires_platform_file_metadata' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        if (reference.kind === 'message') {
+          const parsed = parseOneBotGetMsgResponse(reference.message.id, await callApi('get_msg', { message_id: reference.message.id }));
+          context.signal.throwIfAborted();
+          const value: ConversationMessage = Object.freeze({
+            ref: reference.message,
+            ...(parsed.sender?.id ? { actor: Object.freeze({ id: parsed.sender.id, ...(parsed.sender.name ? { displayName: parsed.sender.name } : {}) }) } : {}),
+            segments: canonicalSegments(parsed.content),
+            timestamp: toMillis(parsed.time),
+          });
+          return Object.freeze({ status: 'resolved' as const, reference, value });
+        }
+        const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+        const value: readonly ForwardEntry[] = Object.freeze(nodes.map((node) => {
+          const row = node as Record<string, unknown>;
+          const sender = row.sender as Record<string, unknown> | undefined;
+          return Object.freeze({
+            ...(sender?.user_id != null ? { actor: Object.freeze({ id: String(sender.user_id), ...(sender.nickname ? { displayName: String(sender.nickname) } : {}) }) } : {}),
+            segments: canonicalSegments(Array.isArray(row.content) ? row.content as never[] : []),
+            timestamp: toMillis(row.time),
+          });
+        }));
+        return Object.freeze({ status: 'resolved' as const, reference, value });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'napcat_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function canonicalSegments(content: Array<{ type: string; data?: Record<string, unknown> }>) {
+  return Object.freeze(content.map((segment) => Object.freeze({
+    type: segment.type,
+    data: Object.freeze(segment.data ?? {}),
+  })));
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { ConversationMessage, ConversationReference, ForwardEntry } from '@zhin.js/im-contract';

package/src/protocol.ts

@@ -244,14 +244,15 @@ export function napcatOutboundTarget(conversation: ConversationRef): ParsedSendT
 }
 
 export function formatInboundContent(ev: NapCatEvent): string {
-  if (typeof ev.raw_message === 'string' && ev.raw_message) return ev.raw_message;
   if (Array.isArray(ev.message)) {
     return ev.message
       .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
       .join('');
   }
-  if (typeof ev.message === 'string') return ev.message;
-  return '';
+  if (typeof ev.message === 'string') return ev.message.replace(/\[CQ:[^\]]+\]/g, '').trim();
+  return typeof ev.raw_message === 'string'
+    ? ev.raw_message.replace(/\[CQ:[^\]]+\]/g, '').trim()
+    : '';
 }
 
 /**

package/src/side-event-dispatch.ts

@@ -0,0 +1,48 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import type { NapCatEvent } from './protocol.js';
+
+export interface NapCatSideEventCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function receiveNapCatSideEvent(
+  sideEvents: SideEventGateway | undefined,
+  endpointKey: string,
+  caller: NapCatSideEventCaller,
+  raw: NapCatEvent,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!sideEvents) return;
+  const record = raw as Record<string, unknown>;
+  const postType = String(record.post_type ?? '');
+  const requestType = String(record.request_type ?? '');
+  const isRequest = postType === 'request' || postType.startsWith('request.');
+  const isFriend = requestType === 'friend' || postType.includes('friend');
+  void receiveOneBotLikeSideEvent(sideEvents, {
+    adapter: 'napcat',
+    endpointKey,
+    platform: 'napcat',
+    raw: record,
+    ...(isRequest ? {
+      approve: async (flag, remark) => {
+        await (isFriend
+          ? caller.callApi('set_friend_add_request', { flag, approve: true, remark })
+          : caller.callApi('set_group_add_request', { flag, approve: true, reason: remark }));
+      },
+      reject: async (flag, reason) => {
+        await (isFriend
+          ? caller.callApi('set_friend_add_request', { flag, approve: false })
+          : caller.callApi('set_group_add_request', { flag, approve: false, reason }));
+      },
+    } : {}),
+  }).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'napcat_side_event_failed',
+      endpoint: endpointKey,
+      post_type: postType || undefined,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}

package/src/ws-endpoint.ts

@@ -3,14 +3,16 @@
  */
 import WebSocket from 'ws';
 import {
+  createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
+  type EndpointControl,
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
@@ -34,6 +36,7 @@ import {
   type NapCatEvent,
   type NapCatWsConfig,
 } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import {
   callNapCatWsAction,
   handleNapCatWsMessage,
@@ -44,10 +47,12 @@ import {
   type NapCatWsCreateOptions,
   type NapCatWsSocket,
 } from './ws-types.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 
 export interface NapCatWsEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: NapCatWsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -61,6 +66,8 @@ export class NapCatWsEndpoint implements EndpointInstance {
   readonly #options: NapCatWsEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
   readonly management: EndpointManagement = createNapCatEndpointManagement(this);
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content = createNapCatContentPort((action, params) => this.callApi(action, params));
   readonly #lifecycle: EndpointLifecycle;
   #ws?: NapCatWsSocket;
   #requestId = { value: 0 };
@@ -322,7 +329,17 @@ export class NapCatWsEndpoint implements EndpointInstance {
 
   /** Test / internal: admit a parsed event when the endpoint is open. */
   admit(ev: NapCatEvent): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveNapCatSideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     if (isSelfMessage(ev)) return;
     const msgId = String(ev.message_id);
     if (!this.#inboundDeduper.shouldProcess(msgId)) return;

package/src/wss-endpoint.ts

@@ -2,8 +2,14 @@
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import { clearInterval } from 'node:timers';
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointInstance,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -27,6 +33,8 @@ import {
   type NapCatEvent,
   type NapCatWssConfig,
 } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
 import {
   callNapCatWsAction,
   handleNapCatWsMessage,
@@ -43,6 +51,7 @@ import { verifyNapCatAccessToken } from './wss-auth.js';
 export interface NapCatWssEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: NapCatWssConfig;
 }
@@ -53,6 +62,8 @@ export class NapCatWssEndpoint implements EndpointInstance {
   readonly #options: NapCatWssEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
   readonly management: EndpointManagement = createNapCatEndpointManagement(this);
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content = createNapCatContentPort((action, params) => this.callApi(action, params));
   #ws?: NapCatWsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -134,7 +145,17 @@ export class NapCatWssEndpoint implements EndpointInstance {
   }
 
   admit(ev: NapCatEvent): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveNapCatSideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     if (isSelfMessage(ev)) return;
     const msgId = String(ev.message_id);
     if (!this.#inboundDeduper.shouldProcess(msgId)) return;