@zhin.js/adapter-icqq 8.0.13 → 9.0.0

package/src/icqq-login-assist.ts

@@ -0,0 +1,132 @@
+import type { LoginAssist, LoginAssistType, PendingLoginTaskPayload } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+
+type IcqqLoginClient = {
+  login(password?: string): Promise<unknown>;
+  submitSlider(ticket: string): Promise<unknown>;
+  sendSmsCode(): Promise<unknown>;
+  submitSmsCode(code: string): Promise<unknown>;
+};
+
+type Logger = {
+  info(message: string): void;
+  warn(message: string): void;
+};
+
+/**
+ * Drive ICQQ login challenges through LoginAssist (refresh-safe pending tasks).
+ * Mirrors the classic stdin flow: qrcode/auth → login(); slider → submitSlider;
+ * device → sendSmsCode then submitSmsCode.
+ */
+export async function runIcqqLoginAssistStep(input: {
+  assist: LoginAssist;
+  client: IcqqLoginClient;
+  adapter: string;
+  endpointKey: string;
+  owner: object;
+  logger: Logger;
+  step: LoginAssistType;
+  event: unknown;
+}): Promise<void> {
+  const { assist, client, adapter, endpointKey, owner, logger, step, event } = input;
+  assist.cancelOwned(owner, `replaced_by_${step}`);
+
+  const payload = buildPayload(step, event);
+  logger.info(formatCompact({
+    op: 'login_assist_pending',
+    endpoint: endpointKey,
+    type: step,
+    message: payload.message,
+    ...(typeof payload.url === 'string' ? { url: payload.url } : {}),
+  }));
+
+  try {
+    if (step === 'device') {
+      try {
+        await client.sendSmsCode();
+      } catch (error) {
+        logger.warn(formatCompact({
+          op: 'login_assist_send_sms_failed',
+          endpoint: endpointKey,
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    }
+
+    const value = await assist.waitForInput(adapter, endpointKey, step, payload, { owner });
+    const text = normalizeSubmitValue(value);
+
+    switch (step) {
+      case 'qrcode':
+      case 'auth':
+        await client.login();
+        break;
+      case 'slider':
+        await client.submitSlider(text);
+        break;
+      case 'device':
+      case 'sms':
+        await client.submitSmsCode(text);
+        break;
+      default:
+        await client.login();
+        break;
+    }
+  } catch (error) {
+    logger.warn(formatCompact({
+      op: 'login_assist_failed',
+      endpoint: endpointKey,
+      type: step,
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+}
+
+function buildPayload(step: LoginAssistType, event: unknown): PendingLoginTaskPayload {
+  const raw = event && typeof event === 'object' ? event as Record<string, unknown> : {};
+  switch (step) {
+    case 'qrcode':
+      return {
+        message: '扫码登录：请在手机 QQ 扫描二维码，完成后在 Console / 终端确认继续',
+        image: bufferToDataUrl(raw.image),
+      };
+    case 'slider':
+      return {
+        message: '滑动验证：打开链接完成滑块，将返回的 ticket（可含 randstr）提交继续',
+        url: typeof raw.url === 'string' ? raw.url : undefined,
+      };
+    case 'device':
+      return {
+        message: '设备锁：已请求短信验证码，请提交短信验证码继续',
+        url: typeof raw.url === 'string' ? raw.url : undefined,
+        phone: raw.phone,
+      };
+    case 'auth':
+      return {
+        message: '身份验证：完成后在 Console / 终端确认继续',
+        url: typeof raw.url === 'string' ? raw.url : undefined,
+        device: raw.device,
+      };
+    default:
+      return { message: `登录辅助（${step}）` };
+  }
+}
+
+function normalizeSubmitValue(value: string | Record<string, unknown>): string {
+  if (typeof value === 'string') return value.trim();
+  if (typeof value.ticket === 'string') return value.ticket.trim();
+  if (typeof value.code === 'string') return value.code.trim();
+  if (typeof value.value === 'string') return value.value.trim();
+  return JSON.stringify(value);
+}
+
+function bufferToDataUrl(image: unknown): string | undefined {
+  if (Buffer.isBuffer(image)) {
+    return `data:image/png;base64,${image.toString('base64')}`;
+  }
+  if (image instanceof Uint8Array) {
+    return `data:image/png;base64,${Buffer.from(image).toString('base64')}`;
+  }
+  if (typeof image === 'string' && image.trim()) return image.trim();
+  return undefined;
+}

package/src/index.ts

@@ -15,7 +15,6 @@ export {
 export {
   IcqqEndpoint,
   type IcqqEndpointOptions,
-  type IcqqInboxHooks,
 } from './endpoint.js';
 
 export * from './types.js';

package/src/outbound-media.ts

@@ -46,18 +46,26 @@ export function resolveIcqqOutboundMediaMode(
 /**
  * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
  * 并把 media 改写为 path 引用（icqq 客户端直接读盘）。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://）。
+ * base64 模式：不改动（由 native Sendable projection 生成 base64:// file）。
  */
-export function materializeOutboundBase64(
+export interface PreparedIcqqOutboundMedia {
+  readonly content: SendContent;
+  dispose(): void;
+}
+
+export function prepareIcqqOutboundMedia(
   content: SendContent,
   mode: IcqqOutboundMediaMode = "file",
-): SendContent {
-  if (mode === "base64") return content;
+): PreparedIcqqOutboundMedia {
+  if (mode === "base64") return { content, dispose() {} };
 
+  const createdFiles: string[] = [];
+  const inputWasArray = Array.isArray(content);
   const segments = Array.isArray(content) ? content : [content];
-  return segments.map((seg) => {
+  const materialized = segments.map((seg) => {
     if (typeof seg === "string") return seg;
     const { type, data } = seg as MessageSegment;
+    if (!data || typeof data !== "object") return seg;
     const d = data as Record<string, unknown>;
     const media = d.media;
     if (!isMediaRef(media) || media.kind !== "base64") return seg;
@@ -73,6 +81,7 @@ export function materializeOutboundBase64(
       mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"),
       type === "record" || type === "audio" ? "audio" : type,
     );
+    createdFiles.push(filePath);
     return {
       type,
       data: {
@@ -85,4 +94,10 @@ export function materializeOutboundBase64(
       },
     } as MessageSegment;
   });
+  return {
+    content: inputWasArray ? materialized : materialized[0]!,
+    dispose() {
+      for (const filePath of createdFiles) fs.rmSync(filePath, { force: true });
+    },
+  };
 }

package/src/protocol.ts

@@ -1,7 +1,8 @@
 import { pickCredential } from 'zhin.js/adapter';
+import type { MessageElem, Sendable } from '@icqqjs/icqq';
 import type { ConversationRef } from '@zhin.js/im-contract';
 import type { MessageSegment } from "zhin.js";
-import { resolveCqMediaArg } from "./cq-message.js";
+import { resolveIcqqMediaFile } from "./cq-message.js";
 
 export type ActionResult = {
   id: string;
@@ -301,6 +302,7 @@ export interface IcqqInboundMessage {
   readonly sender: { readonly id: string; readonly name?: string };
   readonly channelType: 'private' | 'group' | 'channel';
   readonly metadata?: Record<string, unknown>;
+  readonly replyTo?: { readonly id: string };
 }
 
 export type ParsedIcqqSendTarget =
@@ -404,7 +406,20 @@ export function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSen
   return { kind: 'channel', guildId, channelId: conversation.id };
 }
 
-export function formatOutboundBody(payload: unknown): string {
+const ICQQ_STANDALONE_ELEMENTS = new Set([
+  'record',
+  'video',
+  'file',
+  'json',
+  'long_msg',
+] as const);
+
+/**
+ * Project canonical Zhin segments directly into the native ICQQ Sendable
+ * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
+ * notation; passing that notation would send it as literal text.
+ */
+export function formatOutboundBody(payload: unknown): Sendable {
   if (typeof payload === 'string') {
     const text = payload.trim();
     return text || '\u200b';
@@ -422,39 +437,84 @@ export function formatOutboundBody(payload: unknown): string {
     const text = String(payload).trim();
     return text || '\u200b';
   }
-  const joined = payload.map((seg) => {
+  const elements = payload.flatMap<string | MessageElem>((seg) => {
     if (typeof seg === 'string') return seg;
     const item = seg as IcqqWireSegment;
     switch (item.type) {
       case 'text':
         return String(item.data?.text ?? '');
       case 'at':
-      case 'mention':
-        return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
+      case 'mention': {
+        const target = item.data?.qq ?? item.data?.id ?? item.data?.target;
+        if (target === 'all') return { type: 'at', qq: 'all' };
+        const qq = Number(target);
+        if (!Number.isSafeInteger(qq) || qq <= 0) {
+          throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
+        }
+        return { type: 'at', qq };
+      }
       case 'image': {
-        const arg = resolveCqMediaArg('image', item.data);
-        return arg ? `[image:${arg}]` : '';
+        const arg = resolveIcqqMediaFile(item.data);
+        if (!arg) throw new TypeError('ICQQ image segment requires canonical data.media');
+        return { type: 'image', file: arg };
+      }
+      case 'face': {
+        const id = Number(item.data?.id);
+        if (!Number.isSafeInteger(id) || id < 0) {
+          throw new TypeError(`Invalid ICQQ face id: ${String(item.data?.id ?? '')}`);
+        }
+        return { type: 'face', id };
+      }
+      case 'reply': {
+        const id = String(item.data?.message_id ?? item.data?.id ?? '').trim();
+        if (!id) throw new TypeError('ICQQ reply segment requires message_id');
+        return { type: 'reply', id };
       }
-      case 'face':
-        return `[face:${item.data?.id ?? ''}]`;
-      case 'reply':
-        return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
       case 'record':
       case 'audio': {
-        const arg = resolveCqMediaArg('record', item.data);
-        return arg ? `[record:${arg}]` : '';
+        const arg = resolveIcqqMediaFile(item.data);
+        if (!arg) throw new TypeError('ICQQ audio segment requires canonical data.media');
+        return { type: 'record', file: arg };
       }
       case 'video': {
-        const arg = resolveCqMediaArg('video', item.data);
-        return arg ? `[video:${arg}]` : '';
+        const arg = resolveIcqqMediaFile(item.data);
+        if (!arg) throw new TypeError('ICQQ video segment requires canonical data.media');
+        return { type: 'video', file: arg };
+      }
+      case 'file': {
+        const arg = resolveIcqqMediaFile(item.data);
+        if (!arg) throw new TypeError('ICQQ file segment requires canonical data.media');
+        const name = String(item.data?.name ?? '').trim();
+        return { type: 'file', file: arg, ...(name ? { name } : {}) };
+      }
+      case 'dice':
+        return { type: 'dice' };
+      case 'rps':
+        return { type: 'rps' };
+      case 'forward': {
+        const resid = String(item.data?.forward_id ?? item.data?.resid ?? item.data?.id ?? '').trim();
+        if (!resid) throw new TypeError('ICQQ forward segment requires forward_id');
+        return { type: 'long_msg', resid };
       }
       case 'share':
         return formatMusicShareJson(item.data);
-      default:
-        return String(item.data?.text ?? '');
+      default: {
+        const text = item.data?.text;
+        if (typeof text === 'string' && text) return text;
+        throw new TypeError(`Unsupported ICQQ outbound segment: ${item.type}`);
+      }
     }
-  }).join('').trim();
-  return joined || '\u200b';
+  }).filter((element) => typeof element !== 'string' || element.length > 0);
+
+  if (elements.length === 0) return '\u200b';
+  const standalone = elements.find(
+    (element): element is MessageElem =>
+      typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type as never),
+  );
+  if (standalone && elements.length !== 1) {
+    throw new TypeError(`ICQQ ${standalone.type} element must be sent as a standalone message`);
+  }
+  return elements.length === 1 ? elements[0]! : elements;
 }
 
 export function formatInboundContent(rawMessage: string): string {
@@ -468,8 +528,8 @@ function isWireSegment(value: unknown): value is IcqqWireSegment {
     && typeof (value as { type?: unknown }).type === 'string';
 }
 
-function formatMusicShareJson(data: Record<string, unknown> | undefined): string {
-  if (!data) return '';
+function formatMusicShareJson(data: Record<string, unknown> | undefined): MessageElem {
+  if (!data) throw new TypeError('ICQQ share segment requires data');
   const config = data.config as {
     appid?: number;
     package?: string;
@@ -511,5 +571,5 @@ function formatMusicShareJson(data: Record<string, unknown> | undefined): string
       },
     },
   };
-  return `[json:${JSON.stringify(json)}]`;
+  return { type: 'json', data: json };
 }

package/tools/announce.js

@@ -10,7 +10,7 @@ export default defineAgentTool({
         content: z.string().describe('公告内容'),
     }),
     platforms: ['icqq'],
-    permissions: ['platform(icqq,scene_admin)'],
+    permissions: ['role(master,admin,trusted,owner)'],
     async execute({ endpoint_id, group_id, content }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
         await endpoint.sendGroupNotice(group_id, content);

package/tools/announce.ts

@@ -9,7 +9,7 @@ export default defineAgentTool<{ endpoint_id: string; group_id: number; content:
     content: z.string().describe('公告内容'),
   }),
   platforms: ['icqq'],
-  permissions: ['platform(icqq,scene_admin)'],
+  permissions: ['role(master,admin,trusted,owner)'],
   async execute({ endpoint_id, group_id, content }: { endpoint_id: string; group_id: number; content: string }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
     await endpoint.sendGroupNotice(group_id, content);

package/tools/essence.js

@@ -10,7 +10,7 @@ export default defineAgentTool({
         action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
     }),
     platforms: ['icqq'],
-    permissions: ['platform(icqq,scene_admin)'],
+    approval: 'always',
     async execute({ endpoint_id, message_id, action }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
         if (action === 'add') {

package/tools/essence.ts

@@ -9,7 +9,7 @@ export default defineAgentTool<{ endpoint_id: string; message_id: string; action
     action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
   }),
   platforms: ['icqq'],
-  permissions: ['platform(icqq,scene_admin)'],
+  approval: 'always',
   async execute({ endpoint_id, message_id, action }: { endpoint_id: string; message_id: string; action: 'add' | 'remove' }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
     if (action === 'add') {

package/tools/friend_list.js

@@ -11,10 +11,11 @@ export default defineAgentTool({
     approval: 'never',
     async execute({ endpoint_id }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
-        const fl = endpoint.fl;
-        const friends = Array.from(fl.values()).map((f) => ({
-            user_id: f.user_id, nickname: f.nickname, remark: f.remark,
+        const friends = Array.from(endpoint.fl.values()).map((friend) => ({
+            user_id: friend.user_id,
+            nickname: friend.nickname,
+            remark: friend.remark,
         }));
-        return { friends: friends.slice(0, 50), count: fl.size };
+        return { friends: friends.slice(0, 50), count: endpoint.fl.size };
     },
 });

package/tools/friend_list.ts

@@ -1,6 +1,7 @@
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { getIcqqAgentDeps } from '../src/icqq-agent-deps.js';
+
 export default defineAgentTool<{ endpoint_id: string }>({
   description: '获取 QQ 好友列表',
   inputSchema: z.object({
@@ -8,12 +9,13 @@ export default defineAgentTool<{ endpoint_id: string }>({
   }),
   platforms: ['icqq'],
   approval: 'never',
-  async execute({ endpoint_id }: { endpoint_id: string }) {
+  async execute({ endpoint_id }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
-    const fl = endpoint.fl;
-    const friends = Array.from(fl.values()).map((f) => ({
-      user_id: f.user_id, nickname: f.nickname, remark: f.remark,
+    const friends = Array.from(endpoint.fl.values()).map((friend) => ({
+      user_id: friend.user_id,
+      nickname: friend.nickname,
+      remark: friend.remark,
     }));
-    return { friends: friends.slice(0, 50), count: fl.size };
+    return { friends: friends.slice(0, 50), count: endpoint.fl.size };
   },
 });

package/tools/group_list.js

@@ -11,11 +11,12 @@ export default defineAgentTool({
     approval: 'never',
     async execute({ endpoint_id }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
-        const gl = endpoint.gl;
-        const groups = Array.from(gl.values()).map((g) => ({
-            group_id: g.group_id, group_name: g.group_name,
-            member_count: g.member_count, max_member_count: g.max_member_count,
+        const groups = Array.from(endpoint.gl.values()).map((group) => ({
+            group_id: group.group_id,
+            group_name: group.group_name,
+            member_count: group.member_count,
+            max_member_count: group.max_member_count,
         }));
-        return { groups: groups.slice(0, 50), count: gl.size };
+        return { groups: groups.slice(0, 50), count: endpoint.gl.size };
     },
 });

package/tools/group_list.ts

@@ -1,6 +1,7 @@
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { getIcqqAgentDeps } from '../src/icqq-agent-deps.js';
+
 export default defineAgentTool<{ endpoint_id: string }>({
   description: '获取 Endpoint 的 QQ 群列表',
   inputSchema: z.object({
@@ -8,13 +9,14 @@ export default defineAgentTool<{ endpoint_id: string }>({
   }),
   platforms: ['icqq'],
   approval: 'never',
-  async execute({ endpoint_id }: { endpoint_id: string }) {
+  async execute({ endpoint_id }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
-    const gl = endpoint.gl;
-    const groups = Array.from(gl.values()).map((g) => ({
-      group_id: g.group_id, group_name: g.group_name,
-      member_count: g.member_count, max_member_count: g.max_member_count,
+    const groups = Array.from(endpoint.gl.values()).map((group) => ({
+      group_id: group.group_id,
+      group_name: group.group_name,
+      member_count: group.member_count,
+      max_member_count: group.max_member_count,
     }));
-    return { groups: groups.slice(0, 50), count: gl.size };
+    return { groups: groups.slice(0, 50), count: endpoint.gl.size };
   },
 });

package/tools/group_member_info.js

@@ -0,0 +1,27 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { getIcqqAgentDeps } from "../lib/icqq-agent-deps.js";
+export default defineAgentTool({
+    description: '获取 QQ 群成员信息',
+    inputSchema: z.object({
+        endpoint_id: z.string().describe('Endpoint QQ号'),
+        group_id: z.number().describe('目标群号'),
+        user_id: z.number().describe('目标成员 QQ号'),
+    }),
+    platforms: ['icqq'],
+    approval: 'never',
+    async execute({ endpoint_id, group_id, user_id }) {
+        const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
+        const group = endpoint.pickGroup(group_id);
+        if (!group)
+            return { success: false, message: '目标群不存在' };
+        const memberInfo = group.pickMember(user_id);
+        if (!memberInfo)
+            return { success: false, message: '目标成员不存在' };
+        return {
+            success: true,
+            member: memberInfo,
+        };
+    },
+});

package/tools/group_member_info.ts

@@ -0,0 +1,30 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { getIcqqAgentDeps } from '../src/icqq-agent-deps.js';
+interface GroupMemberInfoInput {
+  endpoint_id: string;
+  group_id: number;
+  user_id: number;
+}
+
+export default defineAgentTool<GroupMemberInfoInput>({
+  description: '获取 QQ 群成员信息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint QQ号'),
+    group_id: z.number().describe('目标群号'),
+    user_id: z.number().describe('目标成员 QQ号'),
+  }),
+  platforms: ['icqq'],
+  approval: 'never',
+  async execute({ endpoint_id, group_id, user_id }) {
+    const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
+    const group = endpoint.pickGroup(group_id);
+    if (!group) return { success: false, message: '目标群不存在' };
+    const memberInfo = group.pickMember(user_id);
+    if (!memberInfo) return { success: false, message: '目标成员不存在' };
+    return {
+      success: true,
+      member: memberInfo,
+    };
+  },
+});

package/tools/set_mute.js

@@ -11,7 +11,7 @@ export default defineAgentTool({
         duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
     }),
     platforms: ['icqq'],
-    permissions: ['role(master,trusted,admin,owner)'],
+    approval: 'always',
     async execute({ endpoint_id, group_id, user_id, duration }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
         const selfInfo = endpoint.pickMember(group_id, endpoint.uin);

package/tools/set_mute.ts

@@ -10,7 +10,7 @@ export default defineAgentTool<{ endpoint_id: string; group_id: number; user_id:
     duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
   }),
   platforms: ['icqq'],
-  permissions: ['role(master,trusted,admin,owner)'],
+  approval: 'always',
   async execute({ endpoint_id, group_id, user_id, duration }: { endpoint_id: string; group_id: number; user_id: number; duration?: number }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
     const selfInfo= endpoint.pickMember(group_id,endpoint.uin);

package/tools/set_title.js

@@ -12,7 +12,7 @@ export default defineAgentTool({
         duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
     }),
     platforms: ['icqq'],
-    permissions: ['role(master,trusted)'],
+    approval: 'always',
     async execute({ endpoint_id, group_id, user_id, title, duration }) {
         const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
         const selfInfo = endpoint.pickMember(group_id, endpoint.uin);

package/tools/set_title.ts

@@ -11,7 +11,7 @@ export default defineAgentTool<{ endpoint_id: string; group_id: number; user_id:
     duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
   }),
   platforms: ['icqq'],
-  permissions: ['role(master,trusted)'],
+  approval: 'always',
   async execute({ endpoint_id, group_id, user_id, title, duration }: { endpoint_id: string; group_id: number; user_id: number; title: string; duration?: number }) {
     const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
     const selfInfo= endpoint.pickMember(group_id,endpoint.uin);