@zhin.js/adapter-icqq 1.0.71 → 1.1.2

package/lib/types.d.ts

@@ -1,8 +1,4 @@
-/**
- * ICQQ 适配器类型与配置
- */
-import type { Config, GroupRole, MemberInfo } from "@icqqjs/icqq";
-export type { Config, GroupRole, MemberInfo };
+export type GroupRole = "owner" | "admin" | "member";
 export interface IcqqSenderInfo {
     id: string;
     name: string;
@@ -13,13 +9,37 @@ export interface IcqqSenderInfo {
     card?: string;
     title?: string;
 }
-export interface IcqqBotConfig extends Config {
-    context: "icqq";
-    name: `${number}`;
-    password?: string;
-    scope?: string;
+export interface FriendInfo {
+    user_id: number;
+    nickname: string;
+    remark?: string;
+    class_id?: number;
 }
-export interface IcqqBot {
-    $config: IcqqBotConfig;
+export interface GroupInfo {
+    group_id: number;
+    group_name: string;
+    member_count: number;
+    max_member_count: number;
+    owner_id?: number;
+}
+export interface MemberInfo {
+    user_id: number;
+    nickname: string;
+    card: string;
+    role: GroupRole;
+    title: string;
+    join_time?: number;
+    last_sent_time?: number;
+    shutup_time?: number;
+}
+export interface SystemMessage {
+    type: string;
+    user_id?: number;
+    nickname?: string;
+    group_id?: number;
+    group_name?: string;
+    comment?: string;
+    flag?: string;
+    seq?: number;
+    time?: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.0.71",
-  "description": "Zhin.js adapter for ICQQ (QQ Bot)",
+  "version": "1.1.2",
+  "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -33,52 +33,106 @@
     "type": "git",
     "directory": "plugins/adapters/icqq"
   },
-  "files": [
-    "src",
-    "lib",
-    "client",
-    "dist",
-    "skills",
-    "README.md",
-    "CHANGELOG.md"
-  ],
   "dependencies": {
-    "@icqqjs/icqq": "^1.10.18"
-  },
-  "devDependencies": {
-    "@radix-ui/themes": "^3.2.1",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.1",
-    "lucide-react": "^0.469.0",
-    "radix-ui": "^1.4.3",
-    "typescript": "^5.3.0",
-    "@zhin.js/console": "1.0.59",
-    "zhin.js": "1.0.57"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/agent-feature": "1.1.1",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/permission": "1.1.1",
+    "@zhin.js/skill": "1.1.1",
+    "@zhin.js/tool": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/client": "1.0.14",
-    "@zhin.js/console": "1.0.59",
-    "@zhin.js/core": "1.0.57",
-    "@zhin.js/http": "1.0.52",
-    "zhin.js": "1.0.57"
+    "@icqqjs/icqq": "^1.12.2",
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "@zhin.js/prompt-section": "^1.1.1",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/client": {
+    "@icqqjs/icqq": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/prompt-section": {
       "optional": true
     },
-    "@zhin.js/http": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/console": {
+    "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@icqqjs/icqq": "^1.12.2",
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/prompt-section": "1.1.1",
+    "zhin.js": "1.1.2"
+  },
+  "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
+    "src",
+    "lib",
+    "agents",
+    "README.md",
+    "CHANGELOG.md",
+    "PERMITS.md",
+    "prompt-sections"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/agent-feature",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "tsc && (test -f ../../services/console/lib/bin.js && node ../../services/console/lib/bin.js build || echo 'Skipping client build: console not built yet')",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "pnpm run test:types && NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/icqq/tests",
+    "test:types": "tsc -p tsconfig.type-tests.json"
   }
 }

package/plugin.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
+import { icqqRuntimeStateToken } from "./lib/icqq-runtime-state.js";
+export default definePlugin({
+    name: 'icqq',
+    metadata: {
+        displayName: 'ICQQ Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（icqq endpoint list 的"运行中"数据源）
+        context.resources.provide(icqqRuntimeStateToken, createEndpointRuntimeState());
+        const disposePlatform = context.resources.has(permissionHostToken)
+            ? context.resources.use(permissionHostToken).registerPlatform('icqq', createSceneRolePlatformChecker())
+            : undefined;
+        return disposePlatform;
+    },
+});

package/prompt-sections/platform/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentPromptSection } from '@zhin.js/prompt-section';
+export default defineAgentPromptSection({
+    title: 'ICQQ / QQ',
+    content: [
+        'ICQQ capabilities are grouped into directory, interaction, group-admin, and group-state Skills.',
+        'Use discover for the user intent, then load only the matching Skill before calling its private Tool.',
+        'The current IM operation selects the bot Client automatically; never guess user_id or group_id.',
+    ].join('\n'),
+    layer: 'tools',
+    order: 70,
+    retention: 'preferred',
+    maxChars: 1200,
+    profiles: ['interactive'],
+    platforms: ['icqq'],
+});

package/prompt-sections/platform/index.ts

@@ -0,0 +1,16 @@
+import { defineAgentPromptSection } from '@zhin.js/prompt-section';
+
+export default defineAgentPromptSection({
+  title: 'ICQQ / QQ',
+  content: [
+    'ICQQ capabilities are grouped into directory, interaction, group-admin, and group-state Skills.',
+    'Use discover for the user intent, then load only the matching Skill before calling its private Tool.',
+    'The current IM operation selects the bot Client automatically; never guess user_id or group_id.',
+  ].join('\n'),
+  layer: 'tools',
+  order: 70,
+  retention: 'preferred',
+  maxChars: 1200,
+  profiles: ['interactive'],
+  platforms: ['icqq'],
+});

package/schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "master": {
+      "type": ["string", "number"],
+      "description": "框架 master QQ uin（/approve、AI/工具权限）；endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": { "type": ["string", "number"] },
+      "description": "框架 trusted QQ uin 列表（弱于 master）"
+    },
+    "password": {
+      "type": "string",
+      "description": "QQ 密码（可选，不填则扫码登录）"
+    },
+    "platform": {
+      "type": "number",
+      "enum": [1, 2, 3, 4, 5, 6, 7],
+      "default": 1,
+      "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom"
+    },
+    "ver": {
+      "type": "string",
+      "description": "协议版本号，仅在对应 platform 有多个版本时有效，不填则使用最新版本"
+    },
+    "signApiAddr": {
+      "type": "string",
+      "description": "签名服务器地址；未配置时若安装了 @icqqjs/qqsign 则自动使用本地签名"
+    },
+    "dataDir": {
+      "type": "string",
+      "description": "数据存储文件夹路径，默认为主模块下的 data 文件夹"
+    },
+    "autoReconnect": {
+      "type": "boolean",
+      "default": true,
+      "description": "断线后是否自动重连（默认 true）"
+    },
+    "outboundMedia": {
+      "type": "string",
+      "enum": ["file", "base64"],
+      "default": "file",
+      "description": "出站媒体模式：file=落盘本地路径（默认）; base64=CQ base64:// 内联"
+    },
+    "ignoreSelf": {
+      "type": "boolean",
+      "default": true,
+      "description": "群聊和频道中是否过滤自己的消息（默认 true）"
+    },
+    "resend": {
+      "type": "boolean",
+      "default": false,
+      "description": "被风控时是否尝试用分片发送（默认 false）"
+    },
+    "cacheGroupMember": {
+      "type": "boolean",
+      "default": true,
+      "description": "是否缓存群员列表（默认 true）；群多时（500+）会多占约 100MB+ 内存"
+    },
+    "autoServer": {
+      "type": "boolean",
+      "default": true,
+      "description": "是否自动选择最优服务器（默认 true）"
+    },
+    "qqnt": {
+      "type": "boolean",
+      "default": true,
+      "description": "是否使用 QQNT 协议（默认 true）"
+    },
+    "ntLogin": {
+      "type": "boolean",
+      "description": "是否使用 NT 登录方式"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[0-9]+$",
+            "description": "QQ uin"
+          },
+          "master": {
+            "type": ["string", "number"],
+            "description": "本 endpoint 的 master QQ uin；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": { "type": ["string", "number"] },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "password": {
+            "type": "string",
+            "description": "本 endpoint 的 QQ 密码"
+          },
+          "platform": {
+            "type": "number",
+            "enum": [1, 2, 3, 4, 5, 6, 7],
+            "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom"
+          },
+          "ver": {
+            "type": "string",
+            "description": "协议版本号"
+          },
+          "signApiAddr": {
+            "type": "string",
+            "description": "签名服务器地址"
+          },
+          "dataDir": {
+            "type": "string",
+            "description": "数据存储文件夹路径"
+          },
+          "autoReconnect": {
+            "type": "boolean",
+            "description": "断线后是否自动重连"
+          },
+          "outboundMedia": {
+            "type": "string",
+            "enum": ["file", "base64"],
+            "description": "出站媒体模式"
+          },
+          "ignoreSelf": {
+            "type": "boolean",
+            "description": "是否过滤自己的消息"
+          },
+          "resend": {
+            "type": "boolean",
+            "description": "被风控时是否分片发送"
+          },
+          "cacheGroupMember": {
+            "type": "boolean",
+            "description": "是否缓存群员列表"
+          },
+          "autoServer": {
+            "type": "boolean",
+            "description": "是否自动选择最优服务器"
+          },
+          "qqnt": {
+            "type": "boolean",
+            "description": "是否使用 QQNT 协议"
+          },
+          "ntLogin": {
+            "type": "boolean",
+            "description": "是否使用 NT 登录方式"
+          },
+          "commandPrefix": {
+            "type": "string",
+            "description": "本 endpoint 的命令前缀"
+          }
+        },
+        "required": ["id"]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": ["master", "endpoints"]
+}

package/src/client.ts

@@ -0,0 +1,29 @@
+import type { Client, EventMap } from '@icqqjs/icqq';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+type EventPayload<TListener> = TListener extends (
+  event: infer TEvent,
+  ...rest: readonly unknown[]
+) => unknown
+  ? TEvent
+  : never;
+
+/** The actual ICQQ SDK instance exposed by every ICQQ Endpoint event. */
+export type IcqqClient = Client;
+
+/** Native ICQQ event-name → first public event payload, derived from the SDK SSOT. */
+export type IcqqClientEventMap = {
+  readonly [TName in keyof EventMap]: EventPayload<EventMap[TName]>;
+};
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly icqq: {
+      readonly client: IcqqClient;
+      readonly events: IcqqClientEventMap;
+    };
+  }
+}
+
+/** Typed, generation-checked identity used by handlers, commands, tools and schedules. */
+export const icqqClient = defineEndpointClient<IcqqClient, IcqqClientEventMap>('icqq');

package/src/content-resolver.ts

@@ -0,0 +1,131 @@
+import type { Client } from '@icqqjs/icqq';
+import type {
+  EndpointContentPort,
+  EndpointContentResolveContext,
+} from 'zhin.js/adapter';
+import type {
+  ConversationMessage,
+  ConversationReference,
+  ForwardEntry,
+  Segment,
+} from '@zhin.js/im-contract';
+import { normalizeForwardMsgResponse } from './forward-msg.js';
+
+/** Owns ICQQ-observed message content and recursive merged-forward expansion. */
+export class IcqqContentResolver {
+  readonly #client: Client;
+  readonly #messages = new Map<string, ConversationMessage>();
+
+  readonly port: EndpointContentPort = Object.freeze({
+    resolve: (
+      reference: ConversationReference,
+      context: EndpointContentResolveContext,
+    ) => this.#resolve(reference, context),
+  });
+
+  constructor(client: Client) {
+    this.#client = client;
+  }
+
+  remember(messageId: string, message: ConversationMessage): void {
+    this.#messages.set(messageId, message);
+  }
+
+  async #resolve(
+    reference: ConversationReference,
+    context: EndpointContentResolveContext,
+  ) {
+    context.signal.throwIfAborted();
+    if (reference.kind === 'message') {
+      const cached = this.#messages.get(reference.message.id);
+      return cached
+        ? Object.freeze({ status: 'resolved' as const, reference, value: cached })
+        : Object.freeze({ status: 'not_found' as const, code: 'icqq_message_not_observed' });
+    }
+    if (reference.kind === 'forward') {
+      try {
+        const entries = await this.#resolveForwardEntries(
+          reference.forwardId,
+          context,
+          { remainingEntries: context.maxEntries, path: new Set<string>() },
+          0,
+        );
+        if (entries.length === 0) {
+          return Object.freeze({ status: 'not_found' as const, code: 'icqq_forward_not_found' });
+        }
+        return Object.freeze({
+          status: 'resolved' as const,
+          reference,
+          value: Object.freeze(entries),
+        });
+      } catch (error) {
+        if (context.signal.aborted) throw error;
+        return Object.freeze({
+          status: 'failed' as const,
+          code: 'icqq_forward_fetch_failed',
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    if (
+      reference.media.kind === 'url'
+      || reference.media.kind === 'base64'
+      || reference.media.kind === 'path'
+    ) {
+      return Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+    }
+    return Object.freeze({
+      status: 'unsupported' as const,
+      code: 'icqq_media_reference_unsupported',
+    });
+  }
+
+  async #resolveForwardEntries(
+    forwardId: string,
+    context: EndpointContentResolveContext,
+    state: { remainingEntries: number; readonly path: Set<string> },
+    depth: number,
+  ): Promise<readonly ForwardEntry[]> {
+    context.signal.throwIfAborted();
+    if (state.remainingEntries <= 0 || state.path.has(forwardId)) return Object.freeze([]);
+    state.path.add(forwardId);
+    try {
+      // ICQQ has no cancellable getForwardMsg API. Keep the generation lease
+      // until the native operation settles, then honor cancellation.
+      const raw = await this.#client.getForwardMsg(forwardId);
+      context.signal.throwIfAborted();
+      const entries = normalizeForwardMsgResponse(raw).slice(0, state.remainingEntries);
+      state.remainingEntries -= entries.length;
+      const expanded: ForwardEntry[] = [];
+      for (const entry of entries) {
+        context.signal.throwIfAborted();
+        const segments: Segment[] = [];
+        for (const segment of entry.segments) {
+          if (segment.type !== 'forward' || depth >= context.maxDepth) {
+            segments.push(segment);
+            continue;
+          }
+          const nestedId = String(
+            (segment.data as { forward_id?: unknown }).forward_id ?? '',
+          ).trim();
+          if (!nestedId || state.path.has(nestedId) || state.remainingEntries <= 0) {
+            segments.push(segment);
+            continue;
+          }
+          const nested = await this.#resolveForwardEntries(nestedId, context, state, depth + 1);
+          segments.push(Object.freeze({
+            ...segment,
+            data: Object.freeze({
+              ...segment.data,
+              ...(nested.length > 0 ? { entries: nested } : {}),
+            }),
+          }));
+        }
+        expanded.push(Object.freeze({ ...entry, segments: Object.freeze(segments) }));
+      }
+      return Object.freeze(expanded);
+    } finally {
+      state.path.delete(forwardId);
+    }
+  }
+}