@zhin.js/adapter-napcat 1.1.17 → 1.1.18

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zhin.js/adapter-napcat
 
+## 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

@@ -87,6 +87,16 @@ endpoint 配置，不会从环境变量推断 endpoint id。
 - [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
 - [适配器概览](https://zhin.js.org/essentials/adapters)
 
+## Console 页面
+
+启动后打开 Console 的「NapCat」页（地址 `/napcat`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 增删 `plugins.napcat.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
+
+读取需要 `napcat:read`，写操作需要 `napcat:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `napcat endpoint add`。
+
 ## 故障排查
 
 | 现象 | 排查 |

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;

package/lib/console.js

@@ -0,0 +1,16 @@
+/**
+ * NapCat Console RPC：运行状态 + endpoint 增删（原 `napcat endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import { napcatRuntimeStateToken } from './napcat-runtime-state.js';
+import { napcatConsoleSpec } from './console-spec.js';
+export function createNapcatConsoleRpc(resources, getConfig) {
+    const state = resources.use(napcatRuntimeStateToken);
+    return createAdapterConsoleRpc({
+        ...napcatConsoleSpec,
+        running: () => state.endpoints.values(),
+        getConfig,
+    }, resources);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -44,16 +45,19 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.24",
+    "@zhin.js/adapter": "1.1.25",
     "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
+    "@zhin.js/client": "1.1.21",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.53",
     "@zhin.js/feature-kit": "1.1.9",
     "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
+    "@zhin.js/page": "1.1.10",
     "@zhin.js/permission": "1.1.9",
     "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/tool": "1.1.12"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -62,14 +66,14 @@
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
     "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "zhin.js": "1.1.18"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
+    "@zhin.js/adapter": "^1.1.25",
     "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/core": "^1.1.53",
+    "zhin.js": "^1.1.18"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -120,6 +124,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'NapCat',
+    titleI18n: { en: 'NapCat' },
+    icon: 'Cat',
+    order: 69,
+    requiredPermissions: ['napcat:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/napcat`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('napcat');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'NapCat',
+  titleI18n: { en: 'NapCat' },
+  icon: 'Cat',
+  order: 69,
+  requiredPermissions: ['napcat:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/napcat`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('napcat');

package/plugin.js

@@ -1,8 +1,9 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin } from 'zhin.js';
+import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
 import { napcatRuntimeStateToken } from "./lib/napcat-runtime-state.js";
+import { createNapcatConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'napcat',
     metadata: {
@@ -10,6 +11,7 @@ export default definePlugin({
     },
     setup(context) {
         context.resources.provide(napcatRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createNapcatConsoleRpc(context.resources, () => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);
             return host.registerPlatform('napcat', createSceneRolePlatformChecker());

package/src/console-spec.ts

@@ -0,0 +1,19 @@
+/**
+ * NapCat Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+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' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/napcat',
+  readPermission: 'napcat:read',
+  writePermission: 'napcat:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,21 @@
+/**
+ * NapCat Console RPC：运行状态 + endpoint 增删（原 `napcat endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { napcatRuntimeStateToken } from './napcat-runtime-state.js';
+import { napcatConsoleSpec } from './console-spec.js';
+
+export function createNapcatConsoleRpc(
+  resources: AdapterConsoleResources,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  const state = resources.use(napcatRuntimeStateToken);
+  return createAdapterConsoleRpc({
+    ...napcatConsoleSpec,
+    running: () => state.endpoints.values(),
+    getConfig,
+  }, resources);
+}