@zhin.js/adapter-icqq 1.1.11 → 1.1.12

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.12
+
+### Patch Changes
+
+- a3ab153: Adapters can declare `segments.model` per segment type (extra optional string fields the model may fill, plus a prompt hint) that only that platform's Agent replies see. icqq now declares the segment types its encoder supports and a share extension, so the Agent can send music share cards from tool results.
+- fe6555c: Messages mixing text with standalone ICQQ elements (share, file, voice, video, JSON card, forward) are now sent as ordered separate messages instead of failing with "must be sent as a standalone message". A failure after the first part is reported as `partial_delivery` with an unknown outcome so it is never resent.
+- fbfefb7: Share segments accept `data.platform` (the song's music service: qq, netease, kugou, kuwo, migu). icqq maps it to the matching music app id when `config.appid` is absent and offers it to the Agent; adapters that cannot render share app metadata reject it like `audio` and `config`.
+- Updated dependencies [1a11207]
+- Updated dependencies [9943df6]
+- Updated dependencies [5be09ae]
+- Updated dependencies [a3ab153]
+- Updated dependencies [e8f7309]
+- Updated dependencies [5afc18f]
+- Updated dependencies [d3563d9]
+- Updated dependencies [c618eb7]
+- Updated dependencies [fbfefb7]
+  - @zhin.js/tool@1.1.8
+  - @zhin.js/core@1.1.47
+  - @zhin.js/adapter@1.1.21
+  - @zhin.js/feature-kit@1.1.7
+  - @zhin.js/im-contract@1.1.5
+  - @zhin.js/agent-feature@1.1.8
+  - @zhin.js/skill@1.1.8
+
 ## 1.1.11
 
 ### Patch Changes

package/README.md

@@ -185,3 +185,10 @@ MIT
 发送成功回执只接受平台真实消息 ID。网络超时、断线、缺少消息 ID 的响应会报告 `deliveryUnknown`，框架不会自动重发；手动重发可能重复发送。
 
 ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID，因此报告投递结果未知。平台操作仍只执行一次。文件撤回应使用平台专用文件 API。
+
+### 独立元素按顺序拆分发送
+
+ICQQ 要求分享、文件、语音、视频、JSON 卡片和合并转发单独成条。一条消息里同时有文字和这些元素时（例如 Agent 回复“找到了：”加一张音乐分享卡片），适配器按原顺序拆成多条依次发送，引用只附在第一条普通消息上。
+
+- 回执的消息 ID 取第一条拿到 ID 的部分；所有部分都没有 ID（如单独一张分享）时，仍报告投递结果未知。
+- 第一条就失败时原样报告失败；后面的部分失败时报告 `partial_delivery`（结果未知），因为前面的部分已经送达，重发会重复。

package/adapters/icqq/index.js

@@ -12,8 +12,16 @@ export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall', 'reaction'],
     segments: {
+        // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
+        supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
         outboundMedia: ['base64', 'url', 'path'],
         interactive: 'text',
+        model: {
+            share: {
+                fields: ['description', 'image', 'audio', 'platform'],
+                hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+            },
+        },
     },
     create(context) {
         const config = resolveIcqqConfig(context.config);

package/adapters/icqq/index.ts

@@ -23,8 +23,16 @@ export default defineAdapter<IcqqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall', 'reaction'],
   segments: {
+    // Canonical types formatOutboundBody encodes; markdown / keyboard degrade to text first.
+    supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
     outboundMedia: ['base64', 'url', 'path'],
     interactive: 'text',
+    model: {
+      share: {
+        fields: ['description', 'image', 'audio', 'platform'],
+        hint: 'renders as a QQ link card. For a song, set audio to the playable link, image to the cover, description to the artist and platform to its music service (qq, netease, kugou, kuwo or migu), copied from tool results; leave a field "" when you have no real value.',
+      },
+    },
   },
   create(context) {
     const config = resolveIcqqConfig(context.config);

package/lib/endpoint.js

@@ -11,7 +11,7 @@ import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned,
 import { isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { formatInboundContent, formatOutboundBody, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+import { formatInboundContent, formatOutboundMessages, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
 const BOUND_EVENTS = [
     'message.private',
@@ -292,28 +292,39 @@ export class IcqqEndpoint extends Endpoint {
             ? prepareIcqqOutboundMedia(normalizeIcqqImageMedia(payload), mediaMode)
             : { content: payload, dispose() { } };
         try {
-            const message = formatOutboundBody(prepared.content);
-            const preview = formatIcqqSendablePreview(message);
+            // Standalone elements (share / file / …) are split into ordered messages.
+            const messages = formatOutboundMessages(prepared.content);
             const parsed = icqqOutboundTarget(conversation);
-            let result;
-            try {
-                result = await this.#sendNative(parsed, message);
-            }
-            catch (error) {
-                this.#logger.warn(formatCompact({
-                    op: 'icqq_send_failed',
-                    target: `${conversation.kind}:${conversation.id}`,
-                    error: describeUnknownError(error),
-                    preview: truncatePreview(preview, 120),
-                }));
-                throw error;
+            let messageId;
+            for (const [index, message] of messages.entries()) {
+                const preview = formatIcqqSendablePreview(message);
+                let result;
+                try {
+                    result = await this.#sendNative(parsed, message);
+                }
+                catch (error) {
+                    this.#logger.warn(formatCompact({
+                        op: 'icqq_send_failed',
+                        target: `${conversation.kind}:${conversation.id}`,
+                        part: messages.length > 1 ? `${index + 1}/${messages.length}` : undefined,
+                        error: describeUnknownError(error),
+                        preview: truncatePreview(preview, 120),
+                    }));
+                    if (index === 0)
+                        throw error;
+                    // Earlier parts are already delivered: a retry would duplicate them.
+                    throw new EndpointDeliveryError('partial_delivery', `ICQQ delivered ${index} of ${messages.length} message parts`, 'unknown', { cause: error });
+                }
+                const rawId = result?.message_id;
+                const id = (typeof rawId === 'string' || (typeof rawId === 'number' && Number.isFinite(rawId))) && String(rawId).trim() !== ''
+                    ? String(rawId) : undefined;
+                messageId ??= id;
+                this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${id ?? '-'} | ${truncatePreview(preview, 80)}`);
             }
-            const rawId = result?.message_id;
-            if ((typeof rawId !== 'string' && typeof rawId !== 'number') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
+            // Native share / file APIs return no id; the reply is confirmed by any part that has one.
+            if (!messageId) {
                 throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
             }
-            const messageId = String(rawId);
-            this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`);
             return messageId;
         }
         finally {

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, type ActionResult, type IcqqEndpointConfig, type IcqqInboundMessage, type IcqqWireSegment, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, icqqInboundConversation, icqqOutboundTarget, type ActionResult, type IcqqEndpointConfig, type IcqqInboundMessage, type IcqqWireSegment, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
 export { IcqqEndpoint, type IcqqEndpointOptions, } from './endpoint.js';
 export * from './types.js';
 export { icqqClient, type IcqqClient, type IcqqClientEventMap, } from './client.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, formatOutboundMessages, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 export { IcqqEndpoint, } from './endpoint.js';
 export * from './types.js';
 export { icqqClient, } from './client.js';

package/lib/protocol.d.ts

@@ -259,4 +259,11 @@ export declare function normalizeIcqqImageMedia(content: SendContent): SendConte
  * notation; passing that notation would send it as literal text.
  */
 export declare function formatOutboundBody(payload: unknown): Sendable;
+/**
+ * Like formatOutboundBody, but a payload mixing standalone elements (share,
+ * file, record, video, json, long_msg) with other content becomes several
+ * messages in the original order instead of an error. Groups left with only a
+ * quote or whitespace are dropped: a standalone element cannot carry the quote.
+ */
+export declare function formatOutboundMessages(payload: unknown): Sendable[];
 export declare function formatInboundContent(rawMessage: string): string;

package/lib/protocol.js

@@ -308,7 +308,44 @@ export function formatOutboundBody(payload) {
         const text = String(payload).trim();
         return text || '\u200b';
     }
-    const elements = payload.flatMap((seg) => {
+    const elements = formatOutboundElements(payload);
+    if (elements.length === 0)
+        return '\u200b';
+    const standalone = elements.find(isStandaloneElement);
+    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;
+}
+/**
+ * Like formatOutboundBody, but a payload mixing standalone elements (share,
+ * file, record, video, json, long_msg) with other content becomes several
+ * messages in the original order instead of an error. Groups left with only a
+ * quote or whitespace are dropped: a standalone element cannot carry the quote.
+ */
+export function formatOutboundMessages(payload) {
+    if (!Array.isArray(payload)) {
+        return isWireSegment(payload) ? formatOutboundMessages([payload]) : [formatOutboundBody(payload)];
+    }
+    const groups = [[]];
+    for (const element of formatOutboundElements(payload)) {
+        if (isStandaloneElement(element))
+            groups.push([element], []);
+        else
+            groups.at(-1).push(element);
+    }
+    const messages = groups.filter(group => group.some(element => typeof element === 'string'
+        ? element.trim() !== ''
+        : element.type !== 'reply'));
+    if (messages.length === 0)
+        return ['\u200b'];
+    return messages.map(group => group.length === 1 ? group[0] : group);
+}
+function isStandaloneElement(element) {
+    return typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type);
+}
+function formatOutboundElements(payload) {
+    return payload.flatMap((seg) => {
         if (typeof seg === 'string')
             return seg;
         const item = seg;
@@ -385,13 +422,6 @@ export function formatOutboundBody(payload) {
             }
         }
     }).filter((element) => typeof element !== 'string' || element.length > 0);
-    if (elements.length === 0)
-        return '\u200b';
-    const standalone = elements.find((element) => typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type));
-    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) {
     return rawMessage;
@@ -402,6 +432,14 @@ function isWireSegment(value) {
         && value !== null
         && typeof value.type === 'string';
 }
+/** Music service → ICQQ share app; ICQQ fills appname / appsign from its own table for these ids. */
+const ICQQ_MUSIC_APPIDS = {
+    qq: 100497308,
+    netease: 100495085,
+    kugou: 205141,
+    kuwo: 100243533,
+    migu: 1101053067,
+};
 function formatShare(data) {
     if (!data)
         throw new TypeError('ICQQ share segment requires data');
@@ -416,7 +454,7 @@ function formatShare(data) {
         const text = String(value ?? '').trim();
         return text || undefined;
     };
-    const appid = Number(config?.appid);
+    const appid = Number(config?.appid ?? ICQQ_MUSIC_APPIDS[String(data.platform ?? '').trim().toLowerCase()]);
     const appname = optionalString(config?.package);
     const appsign = optionalString(config?.sign);
     const shareConfig = Number.isSafeInteger(appid) && appid > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,24 +33,24 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.20",
-    "@zhin.js/agent-feature": "1.1.7",
-    "@zhin.js/core": "1.1.46",
-    "@zhin.js/feature-kit": "1.1.6",
-    "@zhin.js/im-contract": "1.1.4",
+    "@zhin.js/adapter": "1.1.21",
+    "@zhin.js/core": "1.1.47",
+    "@zhin.js/feature-kit": "1.1.7",
+    "@zhin.js/im-contract": "1.1.5",
+    "@zhin.js/agent-feature": "1.1.8",
     "@zhin.js/logger": "1.1.2",
     "@zhin.js/permission": "1.1.7",
-    "@zhin.js/skill": "1.1.7",
-    "@zhin.js/tool": "1.1.7"
+    "@zhin.js/skill": "1.1.8",
+    "@zhin.js/tool": "1.1.8"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.20",
-    "@zhin.js/command": "^1.1.8",
-    "@zhin.js/core": "^1.1.46",
-    "@zhin.js/prompt-section": "^1.1.6",
-    "zhin.js": "^1.1.11"
+    "@zhin.js/adapter": "^1.1.21",
+    "@zhin.js/command": "^1.1.9",
+    "@zhin.js/core": "^1.1.47",
+    "@zhin.js/prompt-section": "^1.1.7",
+    "zhin.js": "^1.1.12"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -75,8 +75,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.6",
-    "zhin.js": "1.1.11"
+    "@zhin.js/prompt-section": "1.1.7",
+    "zhin.js": "1.1.12"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -52,7 +52,7 @@ import {
 } from './outbound-media.js';
 import {
   formatInboundContent,
-  formatOutboundBody,
+  formatOutboundMessages,
   normalizeIcqqImageMedia,
   icqqInboundConversation,
   icqqOutboundTarget,
@@ -350,29 +350,39 @@ export class IcqqEndpoint extends Endpoint<Client> {
       ? prepareIcqqOutboundMedia(normalizeIcqqImageMedia(payload), mediaMode)
       : { content: payload, dispose() {} };
     try {
-      const message = formatOutboundBody(prepared.content);
-      const preview = formatIcqqSendablePreview(message);
+      // Standalone elements (share / file / …) are split into ordered messages.
+      const messages = formatOutboundMessages(prepared.content);
       const parsed = icqqOutboundTarget(conversation);
-      let result: { message_id?: unknown };
-      try {
-        result = await this.#sendNative(parsed, message);
-      } catch (error) {
-        this.#logger.warn(formatCompact({
-          op: 'icqq_send_failed',
-          target: `${conversation.kind}:${conversation.id}`,
-          error: describeUnknownError(error),
-          preview: truncatePreview(preview, 120),
-        }));
-        throw error;
+      let messageId: string | undefined;
+      for (const [index, message] of messages.entries()) {
+        const preview = formatIcqqSendablePreview(message);
+        let result: { message_id?: unknown };
+        try {
+          result = await this.#sendNative(parsed, message);
+        } catch (error) {
+          this.#logger.warn(formatCompact({
+            op: 'icqq_send_failed',
+            target: `${conversation.kind}:${conversation.id}`,
+            part: messages.length > 1 ? `${index + 1}/${messages.length}` : undefined,
+            error: describeUnknownError(error),
+            preview: truncatePreview(preview, 120),
+          }));
+          if (index === 0) throw error;
+          // Earlier parts are already delivered: a retry would duplicate them.
+          throw new EndpointDeliveryError('partial_delivery', `ICQQ delivered ${index} of ${messages.length} message parts`, 'unknown', { cause: error });
+        }
+        const rawId = result?.message_id;
+        const id = (typeof rawId === 'string' || (typeof rawId === 'number' && Number.isFinite(rawId))) && String(rawId).trim() !== ''
+          ? String(rawId) : undefined;
+        messageId ??= id;
+        this.#logger.info(
+          `send ${conversation.kind}:${conversation.id} | id: ${id ?? '-'} | ${truncatePreview(preview, 80)}`,
+        );
       }
-      const rawId = result?.message_id;
-      if ((typeof rawId !== 'string' && typeof rawId !== 'number') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
+      // Native share / file APIs return no id; the reply is confirmed by any part that has one.
+      if (!messageId) {
         throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
       }
-      const messageId = String(rawId);
-      this.#logger.info(
-        `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`,
-      );
       return messageId;
     } finally {
       prepared.dispose();

package/src/index.ts

@@ -2,6 +2,7 @@ export {
   Actions,
   formatInboundContent,
   formatOutboundBody,
+  formatOutboundMessages,
   icqqInboundConversation,
   icqqOutboundTarget,
   type ActionResult,

package/src/protocol.ts

@@ -435,7 +435,43 @@ export function formatOutboundBody(payload: unknown): Sendable {
     const text = String(payload).trim();
     return text || '\u200b';
   }
-  const elements = payload.flatMap<string | MessageElem>((seg) => {
+  const elements = formatOutboundElements(payload);
+  if (elements.length === 0) return '\u200b';
+  const standalone = elements.find(isStandaloneElement);
+  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;
+}
+
+/**
+ * Like formatOutboundBody, but a payload mixing standalone elements (share,
+ * file, record, video, json, long_msg) with other content becomes several
+ * messages in the original order instead of an error. Groups left with only a
+ * quote or whitespace are dropped: a standalone element cannot carry the quote.
+ */
+export function formatOutboundMessages(payload: unknown): Sendable[] {
+  if (!Array.isArray(payload)) {
+    return isWireSegment(payload) ? formatOutboundMessages([payload]) : [formatOutboundBody(payload)];
+  }
+  const groups: (string | MessageElem)[][] = [[]];
+  for (const element of formatOutboundElements(payload)) {
+    if (isStandaloneElement(element)) groups.push([element], []);
+    else groups.at(-1)!.push(element);
+  }
+  const messages = groups.filter(group => group.some(element => typeof element === 'string'
+    ? element.trim() !== ''
+    : element.type !== 'reply'));
+  if (messages.length === 0) return ['\u200b'];
+  return messages.map(group => group.length === 1 ? group[0]! : group);
+}
+
+function isStandaloneElement(element: string | MessageElem): element is MessageElem {
+  return typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type as never);
+}
+
+function formatOutboundElements(payload: readonly unknown[]): (string | MessageElem)[] {
+  return payload.flatMap<string | MessageElem>((seg) => {
     if (typeof seg === 'string') return seg;
     const item = seg as IcqqWireSegment;
     switch (item.type) {
@@ -503,16 +539,6 @@ export function formatOutboundBody(payload: unknown): Sendable {
       }
     }
   }).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 {
@@ -526,6 +552,15 @@ function isWireSegment(value: unknown): value is IcqqWireSegment {
     && typeof (value as { type?: unknown }).type === 'string';
 }
 
+/** Music service → ICQQ share app; ICQQ fills appname / appsign from its own table for these ids. */
+const ICQQ_MUSIC_APPIDS: Readonly<Record<string, number>> = {
+  qq: 100497308,
+  netease: 100495085,
+  kugou: 205141,
+  kuwo: 100243533,
+  migu: 1101053067,
+};
+
 function formatShare(data: Record<string, unknown> | undefined): ShareElem {
   if (!data) throw new TypeError('ICQQ share segment requires data');
   const config = data.config as {
@@ -542,7 +577,7 @@ function formatShare(data: Record<string, unknown> | undefined): ShareElem {
     const text = String(value ?? '').trim();
     return text || undefined;
   };
-  const appid = Number(config?.appid);
+  const appid = Number(config?.appid ?? ICQQ_MUSIC_APPIDS[String(data.platform ?? '').trim().toLowerCase()]);
   const appname = optionalString(config?.package);
   const appsign = optionalString(config?.sign);
   const shareConfig = Number.isSafeInteger(appid) && appid > 0