@zhin.js/adapter-napcat 1.1.17 → 1.1.19

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @zhin.js/adapter-napcat
 
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/agent-feature@1.1.11
+  - @zhin.js/skill@1.1.11
+  - @zhin.js/tool@1.1.13
+  - @zhin.js/permission@1.1.10
+
+## 1.1.18
+
+### Patch Changes
+
+- 6345a38: feat(adapters): add per-adapter Console pages
+
+  Every platform adapter now ships a `pages/index` Console page backed by a shared
+  `createAdapterConsolePage` component and `createAdapterConsoleRpc` server helper:
+
+  - See running endpoints, test connectivity, and manage
+    `plugins.<adapter>.endpoints` (add/remove writes `.env` references) from the
+    Console instead of chat commands.
+  - Surface LoginAssist pending tasks (QR / slider / SMS / device) so ICQQ login no
+    longer requires the terminal.
+  - QQ moves its QR binding flow (`qq endpoint add`) into Console actions with
+    public/private selection.
+  - Pages are permission-gated by `<adapter>:read`; writes need `<adapter>:write`.
+
+- Updated dependencies [6345a38]
+- Updated dependencies [ff3efe7]
+- Updated dependencies [c58c589]
+  - @zhin.js/adapter@1.1.25
+  - @zhin.js/client@1.1.21
+  - @zhin.js/core@1.1.53
+  - @zhin.js/im-contract@1.1.9
+  - @zhin.js/tool@1.1.12
+
 ## 1.1.17
 
 ### Patch Changes

package/README.md

@@ -2,13 +2,15 @@
 
 Zhin.js [NapCatQQ](https://github.com/NapNeko/NapCatQQ) 适配器（Plugin Runtime，OneBot 11 + NapCat 扩展）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **反向 WS** 与 **HTTP POST 上报**（经 `httpHostToken`）。
 
+账号由 `NapcatAdapter` 管理。Endpoint 直接继承实际 `NapcatClient`，保留原生方法与事件；框架生命周期、规范入站与发送经 `endpointSpec` 和 AdapterIndex 接入，不占用 Client 的原生 `start` / `stop` / `send` 方法。
+
 ## 功能特性
 
 - OneBot 11 + go-cqhttp 扩展 + NapCat 独有 API
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连 NapCat WS
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `Endpoint.emit(...)`（去重 + 自发过滤）；出站 `send({ conversation, payload })`
+- 入站经 `endpointSpec.events`（去重 + 自发过滤）；出站 `send({ conversation, payload })`
 - 41 个 AI 工具（`tools/`）
 
 ## 安装
@@ -20,11 +22,12 @@ pnpm add @zhin.js/adapter-napcat
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/napcat/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpointSpec.events` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 
-入站：`gateway.receive({ conversation, message: { conversation, id }, content, sender, metadata })`（`conversation` 为 ConversationRef：私聊 `kind: 'private'`、群聊 `kind: 'group'`，临时会话群容器进 `parent`）  
+入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation, message: { conversation, id }, content, sender, metadata })`（`conversation` 为 ConversationRef：私聊 `kind: 'private'`、群聊 `kind: 'group'`，临时会话群容器进 `parent`）
+
 出站：`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`
 
 ## 前置条件
@@ -78,7 +81,7 @@ endpoint 配置，不会从环境变量推断 endpoint id。
 
 ## 迁移说明（Plugin Runtime）
 
-- **notice / request / meta 侧事件**：经 the unified `Endpoint.emit(...)` ingress 归一后分发到 `handlers`（`notice.receive` / `request.receive` / `system.receive`），请求带 `$approve` / `$reject`。消息仍走 `outboundMessageToken`。
+- **notice / request / meta 侧事件**：经统一 `endpointSpec.events` 归一后分发到 `handlers`（`notice.receive` / `request.receive` / `system.receive`），请求带 `$approve` / `$reject`。消息仍走 `outboundMessageToken`。
 - **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后 `tools/` 仅覆盖 NapCat 扩展 API，其余群管能力可通过 `callApi`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
 - **平台权限门禁**：`plugin.ts` setup 通过 generation-owned `permissionHostToken` 调用 `host.registerPlatform('napcat', createSceneRolePlatformChecker())`，`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`（owner / admin）判定。
 
@@ -87,6 +90,16 @@ endpoint 配置，不会从环境变量推断 endpoint id。
 - [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
 - [适配器概览](https://zhin.js.org/essentials/adapters)
 
+## Console 页面
+
+启动后打开 Console 的「NapCat」页（地址 `/napcat`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 经所属 Adapter 增删持久化账号、启停单个 Endpoint；凭据由 Host 加密仓储保存，不改启动 YAML 或 `.env`，不重启进程；
+- 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
+
+读取需要 `napcat:read`，写操作需要 `napcat:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `napcat endpoint add`。
+
 ## 故障排查
 
 | 现象 | 排查 |

package/adapters/napcat/index.js

@@ -3,12 +3,7 @@
  * Convention entry: discover `adapters/napcat/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { NapCatHttpEndpoint } from "../../lib/http-endpoint.js";
-import { resolveNapCatConfig } from "../../lib/protocol.js";
-import { NapCatWsEndpoint } from "../../lib/ws-endpoint.js";
-import { NapCatWssEndpoint } from "../../lib/wss-endpoint.js";
-import { napcatRuntimeStateToken } from "../../lib/napcat-runtime-state.js";
+import { NapcatAdapter } from "../../lib/adapter.js";
 export { NapCatHttpEndpoint, } from "../../lib/http-endpoint.js";
 export { NapCatWsEndpoint, } from "../../lib/ws-endpoint.js";
 export { NapCatWssEndpoint, } from "../../lib/wss-endpoint.js";
@@ -21,27 +16,5 @@ export default defineAdapter({
         outboundMedia: ['url', 'base64', 'path'],
         interactive: 'text',
     },
-    create(context) {
-        const config = resolveNapCatConfig(context.config);
-        // 注册到插件运行时状态（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,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        if (config.connection === 'http') {
-            return new NapCatHttpEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        return new NapCatWsEndpoint({ id: context.id, config });
-    },
+    createAdapter: context => new NapcatAdapter(context),
 });

package/adapters/napcat/index.ts

@@ -2,12 +2,8 @@
  * Convention entry: discover `adapters/napcat/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { NapCatHttpEndpoint } from '../../src/http-endpoint.js';
-import { resolveNapCatConfig, type NapCatEndpointConfig } from '../../src/protocol.js';
-import { NapCatWsEndpoint } from '../../src/ws-endpoint.js';
-import { NapCatWssEndpoint } from '../../src/wss-endpoint.js';
-import { napcatRuntimeStateToken } from '../../src/napcat-runtime-state.js';
+import { NapcatAdapter } from '../../src/adapter.js';
+import type { NapCatEndpointConfig } from '../../src/protocol.js';
 
 export {
   NapCatHttpEndpoint,
@@ -23,12 +19,6 @@ 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<NapCatEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
@@ -38,27 +28,5 @@ export default defineAdapter<NapCatEndpointConfig>({
     outboundMedia: ['url', 'base64', 'path'],
     interactive: 'text',
   },
-  create(context) {
-    const config = resolveNapCatConfig(context.config);
-    // 注册到插件运行时状态（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,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    if (config.connection === 'http') {
-      return new NapCatHttpEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    return new NapCatWsEndpoint({ id: context.id, config });
-  },
+  createAdapter: context => new NapcatAdapter(context),
 });

package/agents/napcat/skills/napcat-account/tools/set_profile/index.js

@@ -15,7 +15,7 @@ export default defineAgentTool({
     keywords: ['修改资料', '设置昵称', 'profile', 'set profile'],
     async execute({ nickname, company, email, college, personal_note }, context) {
         const endpoint = context.$client;
-        await endpoint.setQQProfile(nickname, company, email, college, personal_note);
+        await endpoint.setQQProfile({ nickname, company, email, college, personalNote: personal_note });
         return { success: true };
     },
 });

package/agents/napcat/skills/napcat-account/tools/set_profile/index.ts

@@ -15,7 +15,7 @@ export default defineAgentTool<{ nickname: string; company?: string; email?: str
   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);
+      await endpoint.setQQProfile({ nickname, company, email, college, personalNote: personal_note });
       return { success: true };
   },
 });

package/agents/napcat/skills/napcat-group-files-history/tools/upload_group_file/index.js

@@ -15,7 +15,7 @@ export default defineAgentTool({
     scopes: ['group'],
     async execute({ group_id, file, name, folder }, context) {
         const endpoint = context.$client;
-        await endpoint.uploadGroupFile(group_id, file, name, folder);
+        await endpoint.uploadGroupFile({ groupId: group_id, file, name, folder });
         return { success: true };
     },
 });

package/agents/napcat/skills/napcat-group-files-history/tools/upload_group_file/index.ts

@@ -15,7 +15,7 @@ export default defineAgentTool<{ group_id: number; file: string; name: string; f
   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);
+      await endpoint.uploadGroupFile({ groupId: group_id, file, name, folder });
       return { success: true };
   },
 });

package/agents/napcat/skills/napcat-group-settings/tools/set_title/index.js

@@ -16,7 +16,7 @@ export default defineAgentTool({
     scopes: ['group'],
     async execute({ group_id, user_id, title }, context) {
         const endpoint = context.$client;
-        await endpoint.setTitle(group_id, user_id, title);
+        await endpoint.setTitle({ groupId: group_id, userId: user_id, title });
         return { success: true, message: t(context.locale, 'memberTitleSet', { p0: user_id, p1: title }) };
     },
 });

package/agents/napcat/skills/napcat-group-settings/tools/set_title/index.ts

@@ -16,7 +16,7 @@ export default defineAgentTool<{ group_id: number; user_id: number; title: strin
   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);
+      await endpoint.setTitle({ groupId: group_id, userId: user_id, title });
       return { success: true, message: t(context.locale, 'memberTitleSet', { p0: user_id, p1: title }) };
   },
 });

package/agents/napcat/skills/napcat-media/tools/get_mini_app_ark/index.js

@@ -15,6 +15,6 @@ export default defineAgentTool({
     keywords: ['小程序', 'mini app', '卡片', 'ark'],
     async execute({ type, title, desc, pic_url, jump_url }, context) {
         const endpoint = context.$client;
-        return endpoint.getMiniAppArk(type, title, desc, pic_url, jump_url);
+        return endpoint.getMiniAppArk({ type, title, desc, picUrl: pic_url, jumpUrl: jump_url });
     },
 });

package/agents/napcat/skills/napcat-media/tools/get_mini_app_ark/index.ts

@@ -15,6 +15,6 @@ export default defineAgentTool<{ type: string; title: string; desc: string; pic_
   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);
+      return endpoint.getMiniAppArk({ type, title, desc, picUrl: pic_url, jumpUrl: jump_url });
   },
 });

package/commands/napcat/endpoint/definition.js

@@ -5,7 +5,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { napcatRuntimeStateToken } from "../../../lib/napcat-runtime-state.js";
 export const napcatEndpointCommands = createEndpointCommands({
     adapterKey: 'napcat',
     adapterDisplayName: 'NapCat',
@@ -16,7 +15,6 @@ export const napcatEndpointCommands = createEndpointCommands({
         { 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' },
     ],
-    running: (use) => use(napcatRuntimeStateToken).endpoints.values(),
     describeEntry: (entry) => {
         if (entry.url)
             return `url: ${String(entry.url)}`;

package/commands/napcat/endpoint/definition.ts

@@ -4,7 +4,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { napcatRuntimeStateToken } from '../../../src/napcat-runtime-state.js';
 
 export const napcatEndpointCommands = createEndpointCommands({
   adapterKey: 'napcat',
@@ -16,7 +15,6 @@ export const napcatEndpointCommands = createEndpointCommands({
     { 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' },
   ],
-  running: (use) => use(napcatRuntimeStateToken).endpoints.values(),
   describeEntry: (entry) => {
     if (entry.url) return `url: ${String(entry.url)}`;
     if (entry.path) return `path: ${String(entry.path)}`;

package/lib/adapter.d.ts

@@ -0,0 +1,23 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { type NapCatEndpointConfig } from './protocol.js';
+import { NapCatWsEndpoint } from './ws-endpoint.js';
+import { NapCatWssEndpoint } from './wss-endpoint.js';
+import { NapCatHttpEndpoint } from './http-endpoint.js';
+import type { NapcatClientEventMap } from './client.js';
+type NapcatEndpoint = NapCatWsEndpoint | NapCatWssEndpoint | NapCatHttpEndpoint;
+export declare class NapcatAdapter extends Adapter<NapcatEndpoint, NapCatEndpointConfig, NapcatClientEventMap> {
+    #private;
+    constructor(context: AdapterContext<NapCatEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(config: NapCatEndpointConfig): void;
+    protected identifyConfiguration(input: NapCatEndpointConfig, signal: AbortSignal): Promise<string | undefined>;
+    protected createEndpoint(input: NapCatEndpointConfig, execution: EndpointCreationContext): NapcatEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly napcat: NapcatAdapter;
+    }
+}
+export {};

package/lib/adapter.js

@@ -0,0 +1,42 @@
+import { Adapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { callNapCatHttpAction, resolveNapCatConfig } from './protocol.js';
+import { NapCatWsEndpoint } from './ws-endpoint.js';
+import { NapCatWssEndpoint } from './wss-endpoint.js';
+import { NapCatHttpEndpoint } from './http-endpoint.js';
+import { probeNapcatIdentity } from './identity.js';
+export class NapcatAdapter extends Adapter {
+    #context;
+    constructor(context) { super(); this.#context = context; }
+    get configurationIdentityFields() { return ['id']; }
+    get configurationIdentityProbeFields() { return ['connection', 'access_token', 'url', 'http_url']; }
+    get configurationUpdateFields() {
+        return ['connection', 'url', 'path', 'http_url', 'post_path', 'access_token', 'reconnect_interval', 'heartbeat_interval', 'poll_interval'];
+    }
+    validateConfiguration(config) { resolveNapCatConfig(config); }
+    async identifyConfiguration(input, signal) {
+        const config = resolveNapCatConfig(input);
+        if (config.connection === 'ws')
+            return probeNapcatIdentity(config, signal);
+        if (config.connection === 'wss')
+            return undefined;
+        signal.throwIfAborted();
+        const response = await callNapCatHttpAction({ ...config, signal }, 'get_login_info');
+        signal.throwIfAborted();
+        const data = response.data;
+        if (data?.user_id === 0 || data?.user_id === '0' || (typeof data?.user_id === 'string' && !data.user_id.trim()))
+            return undefined;
+        if ((typeof data?.user_id !== 'string' && typeof data?.user_id !== 'number') || !String(data.user_id).trim()) {
+            throw new Error('NapCat login identity is unavailable');
+        }
+        return `qq:${data.user_id}`;
+    }
+    createEndpoint(input, execution) {
+        const config = resolveNapCatConfig(input), id = execution.canonicalId, signal = execution.signal;
+        switch (config.connection) {
+            case 'wss': return new NapCatWssEndpoint({ id, signal, config, http: this.#context.use(httpHostToken) });
+            case 'http': return new NapCatHttpEndpoint({ id, signal, config, http: this.#context.use(httpHostToken) });
+            case 'ws': return new NapCatWsEndpoint({ id, signal, config });
+        }
+    }
+}

package/lib/client.d.ts

@@ -1,15 +1,61 @@
-import type { NapCatEvent } from './protocol.js';
+import { EventEmitter } from 'node:events';
+import { callNapCatHttpAction, type NapCatEvent, type ResolvedNapCatConfig } from './protocol.js';
+import { type NapCatRpc } from './ws-transport.js';
+import type { PendingRpcRequest } from 'zhin.js/adapter';
+import type { NapCatWsSocket } from './ws-types.js';
 export type NapcatApiCall = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+/** Platform actions use one named payload; wire field names stay inside this Client. */
+export interface NapcatMemberTitleRequest {
+    readonly groupId: number;
+    readonly userId: number;
+    readonly title: string;
+    /** Platform duration; omission retains the existing indefinite value (-1). */
+    readonly duration?: number;
+}
+export interface NapcatProfileRequest {
+    readonly nickname: string;
+    readonly company?: string;
+    readonly email?: string;
+    readonly college?: string;
+    readonly personalNote?: string;
+}
+export interface NapcatGroupFileRequest {
+    readonly groupId: number;
+    readonly file: string;
+    readonly name: string;
+    readonly folder?: string;
+}
+export interface NapcatMiniAppRequest {
+    readonly type: string;
+    readonly title: string;
+    readonly desc: string;
+    readonly picUrl: string;
+    readonly jumpUrl: string;
+}
+export interface NapcatClientOptions {
+    readonly config: ResolvedNapCatConfig;
+    readonly httpAction?: typeof callNapCatHttpAction;
+    readonly signal?: AbortSignal;
+}
 /** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
-export declare class NapcatClient {
+export declare class NapcatClient extends EventEmitter<Record<string, [NapCatEvent]>> {
+    #private;
+    protected transportSocket?: NapCatWsSocket;
+    protected readonly rpc: NapCatRpc;
+    protected readonly protocolConfig: ResolvedNapCatConfig;
+    constructor(options: NapcatClientOptions);
+    ingest(event: NapCatEvent): void;
+    protected get actionSocket(): NapCatWsSocket | undefined;
+    /** Existing platform methods retain their native action/params calling convention. */
     readonly callApi: NapcatApiCall;
-    constructor(callApi: NapcatApiCall);
-    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
+    /** A semantic operation supplies its caller lifetime to the same native protocol owner. */
+    requestApi(request: PendingRpcRequest): Promise<unknown>;
+    setTitle({ groupId, userId, title, duration }: NapcatMemberTitleRequest): 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>;
+    setQQProfile({ nickname, company, email, college, personalNote }: NapcatProfileRequest): Promise<unknown>;
     setGroupPortrait(groupId: number, file: string): Promise<unknown>;
     setEssenceMsg(messageId: number): Promise<unknown>;
     deleteEssenceMsg(messageId: number): Promise<unknown>;
@@ -18,7 +64,7 @@ export declare class NapcatClient {
     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>;
+    uploadGroupFile({ groupId, file, name, folder }: NapcatGroupFileRequest): 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>;
@@ -36,17 +82,8 @@ export declare class NapcatClient {
     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>;
+    getMiniAppArk({ type, title, desc, picUrl, jumpUrl }: NapcatMiniAppRequest): 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

@@ -1,11 +1,55 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
+import { EventEmitter } from 'node:events';
+import { callNapCatHttpAction, readNapCatActionResponse } from './protocol.js';
+import { createNapCatRpc } from './ws-transport.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
-export class NapcatClient {
-    callApi;
-    constructor(callApi) {
-        this.callApi = callApi;
+export class NapcatClient extends EventEmitter {
+    transportSocket;
+    rpc;
+    protocolConfig;
+    #httpAction;
+    #executionSignal;
+    constructor(options) {
+        super();
+        this.protocolConfig = options.config;
+        this.#httpAction = options.httpAction ?? callNapCatHttpAction;
+        this.#executionSignal = options.signal;
+        this.rpc = createNapCatRpc({ endpointId: options.config.id, signal: options.signal,
+            socket: () => this.actionSocket });
     }
-    async setTitle(groupId, userId, title, duration = -1) {
+    ingest(event) {
+        this.emit('event', event);
+        const name = [event.post_type, event.message_type ?? event.notice_type ?? event.request_type, event.sub_type].filter(Boolean).join('.');
+        if (name && name !== 'event')
+            this.emit(name, event);
+    }
+    get actionSocket() { return this.transportSocket; }
+    /** Existing platform methods retain their native action/params calling convention. */
+    callApi = (action, params = {}) => this.requestApi({ action, params });
+    /** A semantic operation supplies its caller lifetime to the same native protocol owner. */
+    async requestApi(request) {
+        const signals = [this.#executionSignal, request.signal].filter((signal) => !!signal);
+        const signal = signals.length ? AbortSignal.any(signals) : undefined;
+        if (signal?.aborted)
+            throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation ended', 'not_sent');
+        if (this.protocolConfig.connection === 'http') {
+            try {
+                const response = await this.#httpAction({ http_url: this.protocolConfig.http_url,
+                    access_token: this.protocolConfig.access_token, signal }, request.action, request.params ?? {});
+                if (signal?.aborted)
+                    throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'unknown');
+                return readNapCatActionResponse(response).data;
+            }
+            catch (cause) {
+                if (cause instanceof EndpointDeliveryError)
+                    throw cause;
+                throw new EndpointDeliveryError('delivery_unconfirmed', cause instanceof Error ? cause.message : String(cause), 'unknown', { cause });
+            }
+        }
+        const response = await this.rpc.call({ ...request, signal });
+        return readNapCatActionResponse(response).data;
+    }
+    async setTitle({ groupId, userId, title, duration = -1 }) {
         await this.callApi('set_group_special_title', {
             group_id: groupId,
             user_id: userId,
@@ -18,7 +62,7 @@ export class NapcatClient {
     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) {
+    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 }); }
@@ -29,7 +73,7 @@ export class NapcatClient {
     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 }); }
+    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 }); }
@@ -53,10 +97,9 @@ export class NapcatClient {
     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 }); }
+    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/console-spec.d.ts

@@ -0,0 +1,12 @@
+/**
+ * NapCat Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+export declare const napcatConsoleSpec: {
+    readonly adapterKey: "napcat";
+    readonly adapterDisplayName: "NapCat";
+    readonly fields: readonly AdapterConsoleField[];
+    readonly docsUrl: "https://zhin.js.org/adapters/napcat";
+    readonly readPermission: "napcat:read";
+    readonly writePermission: "napcat:write";
+};

package/lib/console-spec.js

@@ -0,0 +1,14 @@
+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' },
+    ],
+    docsUrl: 'https://zhin.js.org/adapters/napcat',
+    readPermission: 'napcat:read',
+    writePermission: 'napcat:write',
+};

package/lib/console.d.ts

@@ -0,0 +1,8 @@
+/**
+ * NapCat Console RPC：运行状态 + endpoint 增删（原 `napcat endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+export declare function createNapcatConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;