@zhin.js/adapter-icqq 7.0.4 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @zhin.js/adapter-icqq
 
+## 8.0.0
+
+### Patch Changes
+
+- 7c1e63a: feat(command)!: 命令名前缀分隔符由空格改为点号（BREAKING）
+
+  非 root 插件命令的自动前缀从空格改为点号：`qq endpoint list` → `qq.endpoint list`，多级挂载 `b a foo` → `b.a.foo`；root 插件命令不变。点号前缀同时消除了旧规则下 root 目录段与子插件 owner 段的命名冲突（`child status` vs `child.status` 现在可共存）。配套的 endpoint 管理命令套件（`createEndpointCommands`）及 QQ/ICQQ 适配器的用户可见用法文案同步更新为新风格。迁移：用户与文档中所有 `<adapter> <command>` 形式的指令改为 `<adapter>.<command>`。
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - @zhin.js/agent@1.1.0
+  - zhin.js@6.0.0
+
+## 7.0.5
+
+### Patch Changes
+
+- @zhin.js/agent@1.0.10
+- @zhin.js/core@1.4.3
+- zhin.js@5.0.3
+
 ## 7.0.4
 
 ### Patch Changes

package/adapters/icqq.js

@@ -13,18 +13,19 @@ export { IcqqIpcEndpoint } from "../lib/endpoint.js";
 const logger = getLogger('icqq');
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // 统一消息元素通道（UNI-Channel）：端点可消费 base64 / url / upload 媒体
-    // （path 由出站物化按 file/base64 模式转换，非声明消费形态）；
+    operations: ['recall', 'reaction'],
+    // 统一消息元素通道（UNI-Channel）：端点可消费 base64（CQ base64:// 守护进程解码）
+    // / url（CQ 直发）/ path（同机守护进程读盘；file 模式出站物化产物）媒体；
     // 卡片/按钮等富交互段无原生承载，降级纯文本。
     segments: {
-        outboundMedia: ['base64', 'url', 'upload'],
+        outboundMedia: ['base64', 'url', 'path'],
         interactive: 'text',
     },
     create(context) {
         // Client-library / IPC daemon path — no httpHostToken.
         // Console loginAssist + host-router routes deferred.
         const config = resolveIcqqConfig(context.config);
-        // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
         context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.rpc ? 'rpc' : 'ipc',

package/adapters/icqq.ts

@@ -29,18 +29,19 @@ const logger = getLogger('icqq');
 
 export default defineAdapter<IcqqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // 统一消息元素通道（UNI-Channel）：端点可消费 base64 / url / upload 媒体
-  // （path 由出站物化按 file/base64 模式转换，非声明消费形态）；
+  operations: ['recall', 'reaction'],
+  // 统一消息元素通道（UNI-Channel）：端点可消费 base64（CQ base64:// 守护进程解码）
+  // / url（CQ 直发）/ path（同机守护进程读盘；file 模式出站物化产物）媒体；
   // 卡片/按钮等富交互段无原生承载，降级纯文本。
   segments: {
-    outboundMedia: ['base64', 'url', 'upload'],
+    outboundMedia: ['base64', 'url', 'path'],
     interactive: 'text',
   },
   create(context) {
     // Client-library / IPC daemon path — no httpHostToken.
     // Console loginAssist + host-router routes deferred.
     const config = resolveIcqqConfig(context.config);
-    // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
     context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.rpc ? 'rpc' : 'ipc',

package/lib/cq-message.d.ts

@@ -1,8 +1,21 @@
 /**
  * CQ 码与 MessageSegment 互转。
  * 出站：@icqqjs/cli 要求 message 为非空字符串；引用段编码为 [reply:id]（需 cli parse-message 支持 reply，见 scripts/patch-icqq-cli-reply.mjs）。
+ * 媒体段双向均为 canonical MediaRef（`data.media`），无 legacy url/file/base64 字段。
  */
+import { type MediaRef } from "@zhin.js/core";
 import { MessageSegment, SendContent } from "zhin.js";
+/**
+ * CQ 媒体参数 / 入站元素媒体值 → canonical MediaRef：
+ * `base64://` → base64；http(s) → url；本机路径 → path；其余视为平台不透明引用（file）。
+ */
+export declare function icqqMediaRefFromString(value: string): MediaRef;
+/**
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ CQ 媒体参数：
+ * base64 → `base64://` 前缀（守护进程解码）；url/path/file 原样直出。
+ * 无 canonical 媒体引用时 warn 并返回 undefined（调用方丢弃该段）。
+ */
+export declare function resolveCqMediaArg(type: string, data: Record<string, unknown> | undefined): string | undefined;
 export declare function parseCqMessage(raw: string): MessageSegment[];
 /** 构建 icqq IPC send_*_msg 的 message 字符串（非空） */
 export declare function buildIcqqIpcMessage(content: SendContent): string;

package/lib/cq-message.js

@@ -1,16 +1,56 @@
 /**
  * CQ 码与 MessageSegment 互转。
  * 出站：@icqqjs/cli 要求 message 为非空字符串；引用段编码为 [reply:id]（需 cli parse-message 支持 reply，见 scripts/patch-icqq-cli-reply.mjs）。
+ * 媒体段双向均为 canonical MediaRef（`data.media`），无 legacy url/file/base64 字段。
  */
+import { isMediaRef } from "@zhin.js/core";
+import { formatCompact, getLogger } from "@zhin.js/logger";
 import { segment } from "zhin.js";
+const logger = getLogger("icqq");
 const MAX_CQ_PARSE_LEN = 256_000;
+/**
+ * CQ 媒体参数 / 入站元素媒体值 → canonical MediaRef：
+ * `base64://` → base64；http(s) → url；本机路径 → path；其余视为平台不透明引用（file）。
+ */
+export function icqqMediaRefFromString(value) {
+    if (value.startsWith("base64://")) {
+        return { kind: "base64", value: value.slice("base64://".length) };
+    }
+    if (value.startsWith("http://") || value.startsWith("https://")) {
+        return { kind: "url", value };
+    }
+    if (value.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(value)) {
+        return { kind: "path", value };
+    }
+    return { kind: "file", value };
+}
+/**
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ CQ 媒体参数：
+ * base64 → `base64://` 前缀（守护进程解码）；url/path/file 原样直出。
+ * 无 canonical 媒体引用时 warn 并返回 undefined（调用方丢弃该段）。
+ */
+export function resolveCqMediaArg(type, data) {
+    const media = data?.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: "icqq_outbound_media_dropped",
+            type,
+            reason: "missing_media_ref",
+        }));
+        return undefined;
+    }
+    if (media.kind === "base64") {
+        return media.value.startsWith("base64://") ? media.value : `base64://${media.value}`;
+    }
+    return media.value;
+}
 function pushCqSegment(segments, type, arg) {
     switch (type) {
         case "face":
             segments.push({ type: "face", data: { id: Number(arg) } });
             break;
         case "image":
-            segments.push({ type: "image", data: { url: arg, file: arg } });
+            segments.push({ type: "image", data: { media: icqqMediaRefFromString(arg) } });
             break;
         case "at":
             if (arg === "all") {
@@ -28,10 +68,10 @@ function pushCqSegment(segments, type, arg) {
             break;
         case "record":
         case "audio":
-            segments.push({ type: "record", data: { file: arg } });
+            segments.push({ type: "record", data: { media: icqqMediaRefFromString(arg) } });
             break;
         case "video":
-            segments.push({ type: "video", data: { file: arg } });
+            segments.push({ type: "video", data: { media: icqqMediaRefFromString(arg) } });
             break;
         case "reply":
             segments.push({ type: "reply", data: { message_id: arg } });
@@ -96,20 +136,8 @@ export function toCqString(content) {
             case "face":
                 return `[face:${data.id}]`;
             case "image": {
-                const media = data.media;
-                if (media?.value) {
-                    if (media.kind === "base64")
-                        return `[image:base64://${media.value}]`;
-                    return `[image:${media.value}]`;
-                }
-                const b64 = typeof data.base64 === "string"
-                    ? data.base64
-                    : typeof data.data === "string"
-                        ? data.data
-                        : undefined;
-                if (b64)
-                    return `[image:base64://${b64}]`;
-                return `[image:${data.file || data.url || data.src}]`;
+                const arg = resolveCqMediaArg("image", data);
+                return arg ? `[image:${arg}]` : "";
             }
             case "at":
             case "mention": {
@@ -122,20 +150,12 @@ export function toCqString(content) {
                 return "[rps]";
             case "record":
             case "audio": {
-                const b64 = typeof data.base64 === "string"
-                    ? data.base64
-                    : typeof data.data === "string"
-                        ? data.data
-                        : undefined;
-                if (b64)
-                    return `[record:base64://${b64}]`;
-                return `[record:${data.file || data.url}]`;
+                const arg = resolveCqMediaArg("record", data);
+                return arg ? `[record:${arg}]` : "";
             }
             case "video": {
-                const b64 = typeof data.base64 === "string" ? data.base64 : undefined;
-                if (b64)
-                    return `[video:base64://${b64}]`;
-                return `[video:${data.file || data.url}]`;
+                const arg = resolveCqMediaArg("video", data);
+                return arg ? `[video:${arg}]` : "";
             }
             case "reply":
                 return `[reply:${data.message_id ?? data.id}]`;

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type IcqqInboundMessage, type IpcEvent, type IpcResponse, type ResolvedIcqqConfig } from './protocol.js';
@@ -41,6 +41,7 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     readonly friends: Map<number, IpcFriendInfo>;
     readonly groups: Map<number, IpcGroupInfo>;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: IcqqEndpointOptions);
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
     start(): Promise<void>;

package/lib/endpoint.js

@@ -31,6 +31,11 @@ export class IcqqIpcEndpoint {
         setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
         deleteFriend: (userId) => this.deleteFriend(userId),
     });
+    control = Object.freeze({
+        recall: (messageId) => this.recallMessage(messageId),
+        addReaction: (messageId, emoji) => this.addReaction(messageId, emoji),
+        removeReaction: (messageId, reactionId) => this.removeReaction(messageId, reactionId),
+    });
     #open = false;
     #started = false;
     #subscriptions = [];

package/lib/icqq-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `icqq endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `icqq.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  *
  * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
  * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
@@ -18,7 +18,7 @@ export const icqqEndpointCommands = createEndpointCommands({
     addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
     bindFlow: ({ name }) => {
         if (!name) {
-            return '用法：icqq endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
+            return '用法：icqq.endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
         }
         if (!/^\d+$/.test(name)) {
             return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';

package/lib/icqq-inbound.js

@@ -2,7 +2,7 @@
  * icqq 守护进程 IPC 入站事件归一化（post_type / message_type / message 段）
  */
 import { Message, toCanonicalSegments } from "zhin.js";
-import { parseCqMessage } from "./cq-message.js";
+import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 const DEDUPE_TTL_MS = 120_000;
 const ICQQ_GROUP_ROLES = new Set(["owner", "admin", "member"]);
@@ -210,15 +210,14 @@ export function icqqElementsToSegments(elements) {
             case "face":
                 out.push({ type: "face", data: { id: Number(el.id) } });
                 break;
-            case "image":
+            case "image": {
+                const value = String(el.url ?? el.file ?? "");
                 out.push({
                     type: "image",
-                    data: {
-                        url: String(el.url ?? el.file ?? ""),
-                        file: String(el.file ?? el.url ?? ""),
-                    },
+                    data: { media: icqqMediaRefFromString(value) },
                 });
                 break;
+            }
             case "forward": {
                 const forwardResid = String(el.id ?? el.resid ?? el.res_id ?? el.file ?? "").trim();
                 if (forwardResid) {
@@ -281,18 +280,22 @@ export function icqqElementsToSegments(elements) {
                 break;
             }
             case "record":
-            case "audio":
+            case "audio": {
+                const value = String(el.file ?? el.url ?? "");
                 out.push({
                     type: "record",
-                    data: { file: String(el.file ?? el.url ?? "") },
+                    data: { media: icqqMediaRefFromString(value) },
                 });
                 break;
-            case "video":
+            }
+            case "video": {
+                const value = String(el.file ?? el.url ?? "");
                 out.push({
                     type: "video",
-                    data: { file: String(el.file ?? el.url ?? "") },
+                    data: { media: icqqMediaRefFromString(value) },
                 });
                 break;
+            }
             default:
                 if (el.text != null && el.text !== "") {
                     out.push({ type: "text", data: { text: String(el.text) } });

package/lib/icqq-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `icqq.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 export const icqqRuntimeStateToken = defineEndpointRuntimeStateToken('icqq');

package/lib/outbound-media.d.ts

@@ -3,12 +3,13 @@ import type { IcqqEndpointConfig } from "./types.js";
 export type IcqqOutboundMediaMode = "file" | "base64";
 /**
  * 出站媒体模式：file=本机落盘后 CQ [image:path]（与 icqq 同机时可用）；
- * base64=保留 segment.base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
+ * base64=保留 MediaRef base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
  */
 export declare function resolveIcqqOutboundMediaMode(config: Pick<IcqqEndpointConfig, "rpc" | "outboundMedia">): IcqqOutboundMediaMode;
 /**
- * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
- * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
+ * 并把 media 改写为 path 引用（与 icqq 同机时守护进程直接读盘）。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程解码）。
+ * 无 canonical MediaRef 的段原样保留（不可投递，由下游 CQ 序列化 warn + 丢弃）。
  */
 export declare function materializeOutboundBase64(content: SendContent, mode?: IcqqOutboundMediaMode): SendContent;

package/lib/outbound-media.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
+import { isMediaRef } from "@zhin.js/core";
 function extForMime(mime, fallback) {
     const map = {
         "image/jpeg": ".jpg",
@@ -24,7 +25,7 @@ function spoolBase64ToFile(base64, mime, kind) {
 }
 /**
  * 出站媒体模式：file=本机落盘后 CQ [image:path]（与 icqq 同机时可用）；
- * base64=保留 segment.base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
+ * base64=保留 MediaRef base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
  */
 export function resolveIcqqOutboundMediaMode(config) {
     if (config.outboundMedia === "base64" || config.outboundMedia === "file") {
@@ -33,9 +34,10 @@ export function resolveIcqqOutboundMediaMode(config) {
     return config.rpc ? "base64" : "file";
 }
 /**
- * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
- * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
+ * 并把 media 改写为 path 引用（与 icqq 同机时守护进程直接读盘）。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程解码）。
+ * 无 canonical MediaRef 的段原样保留（不可投递，由下游 CQ 序列化 warn + 丢弃）。
  */
 export function materializeOutboundBase64(content, mode = "file") {
     if (mode === "base64")
@@ -47,31 +49,26 @@ export function materializeOutboundBase64(content, mode = "file") {
         const { type, data } = seg;
         const d = data;
         const media = d.media;
-        const mediaBase64 = media && media.kind === "base64" && typeof media.value === "string" && media.value
-            ? media.value.replace(/^base64:\/\//, "")
-            : undefined;
-        const legacyBase64 = d.base64 ?? d.data;
-        const b64 = mediaBase64 ??
-            (typeof legacyBase64 === "string" && legacyBase64 ? legacyBase64 : undefined);
+        if (!isMediaRef(media) || media.kind !== "base64")
+            return seg;
+        const b64 = media.value.replace(/^base64:\/\//, "");
         if (!b64)
             return seg;
-        const mime = String(d.mime ?? d.mimeType ?? (typeof media?.mime_type === "string" ? media.mime_type : "") ?? "");
-        if (type === "image" || type === "record" || type === "audio" || type === "video") {
-            const filePath = spoolBase64ToFile(b64, mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"), type === "record" || type === "audio" ? "audio" : type);
-            return {
-                type,
-                data: {
-                    ...d,
-                    media: {
-                        kind: "path",
-                        value: filePath,
-                        ...(mime ? { mime_type: mime } : {}),
-                    },
-                    file: filePath,
-                    url: filePath,
-                },
-            };
+        if (type !== "image" && type !== "record" && type !== "audio" && type !== "video") {
+            return seg;
         }
-        return seg;
+        const mime = media.mime_type ?? "";
+        const filePath = spoolBase64ToFile(b64, mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"), type === "record" || type === "audio" ? "audio" : type);
+        return {
+            type,
+            data: {
+                ...d,
+                media: {
+                    kind: "path",
+                    value: filePath,
+                    ...(mime ? { mime_type: mime } : {}),
+                },
+            },
+        };
     });
 }

package/lib/protocol.js

@@ -12,6 +12,7 @@
  * 登录相关：**推送**走 IpcEvent（`system.login.*`）。
  */
 import { pickCredential } from '@zhin.js/adapter';
+import { resolveCqMediaArg } from "./cq-message.js";
 /** 从 IPC 入站 payload 解析可用于引用/撤回的消息 ID */
 export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
 /**
@@ -276,17 +277,23 @@ export function formatOutboundBody(payload) {
             case 'at':
             case 'mention':
                 return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
-            case 'image':
-                return `[image:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+            case 'image': {
+                const arg = resolveCqMediaArg('image', item.data);
+                return arg ? `[image:${arg}]` : '';
+            }
             case 'face':
                 return `[face:${item.data?.id ?? ''}]`;
             case 'reply':
                 return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
             case 'record':
-            case 'audio':
-                return `[record:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
-            case 'video':
-                return `[video:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+            case 'audio': {
+                const arg = resolveCqMediaArg('record', item.data);
+                return arg ? `[record:${arg}]` : '';
+            }
+            case 'video': {
+                const arg = resolveCqMediaArg('video', item.data);
+                return arg ? `[video:${arg}]` : '';
+            }
             default:
                 return String(item.data?.text ?? '');
         }
@@ -296,28 +303,6 @@ export function formatOutboundBody(payload) {
 export function formatInboundContent(rawMessage) {
     return rawMessage;
 }
-/** base64 媒体回退：CQ `base64://` 由守护进程解码（异机 RPC 场景）。 */
-function base64Media(data) {
-    const b64 = data?.base64;
-    return typeof b64 === 'string' && b64 ? `base64://${b64}` : undefined;
-}
-/**
- * canonical MediaRef（`data.media`，见 built/segment-contract）→ CQ 媒体值：
- * base64 → `base64://` 前缀（守护进程解码）；url/path 直出。
- * file 模式下 materializeOutboundBase64 已把 base64 落盘并把 media 改写为 path 引用。
- */
-function mediaRefValue(data) {
-    const media = data?.media;
-    if (!media || typeof media !== 'object' || Array.isArray(media))
-        return undefined;
-    const { kind, value } = media;
-    if (typeof value !== 'string' || !value)
-        return undefined;
-    if (kind === 'base64') {
-        return value.startsWith('base64://') ? value : `base64://${value}`;
-    }
-    return value;
-}
 /** 段对象判定：`{ type: string, data? }`（非数组 payload 的防御入口）。 */
 function isWireSegment(value) {
     return typeof value === 'object'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "7.0.4",
+  "version": "8.0.0",
   "description": "Zhin.js ICQQ adapter for Plugin Runtime (IPC daemon client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,19 +34,19 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.9",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -60,12 +60,12 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.9",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0",
+    "@zhin.js/agent": "1.1.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -11,7 +11,7 @@ export default definePlugin({
         displayName: 'ICQQ Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（icqq endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（icqq.endpoint list 的"运行中"数据源）
         context.resources.provide(icqqRuntimeStateToken, createEndpointRuntimeState());
         // Agent prompt contributor (orchestrator/deferred-worker ICQQ guidance).
         // `zhin.js/agent` is an optional peer — skip silently on IM-only installs.

package/src/cq-message.ts

@@ -1,18 +1,64 @@
 /**
  * CQ 码与 MessageSegment 互转。
  * 出站：@icqqjs/cli 要求 message 为非空字符串；引用段编码为 [reply:id]（需 cli parse-message 支持 reply，见 scripts/patch-icqq-cli-reply.mjs）。
+ * 媒体段双向均为 canonical MediaRef（`data.media`），无 legacy url/file/base64 字段。
  */
+import { isMediaRef, type MediaRef } from "@zhin.js/core";
+import { formatCompact, getLogger } from "@zhin.js/logger";
 import { MessageSegment, segment, SendContent } from "zhin.js";
 
+const logger = getLogger("icqq");
+
 const MAX_CQ_PARSE_LEN = 256_000;
 
+/**
+ * CQ 媒体参数 / 入站元素媒体值 → canonical MediaRef：
+ * `base64://` → base64；http(s) → url；本机路径 → path；其余视为平台不透明引用（file）。
+ */
+export function icqqMediaRefFromString(value: string): MediaRef {
+  if (value.startsWith("base64://")) {
+    return { kind: "base64", value: value.slice("base64://".length) };
+  }
+  if (value.startsWith("http://") || value.startsWith("https://")) {
+    return { kind: "url", value };
+  }
+  if (value.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(value)) {
+    return { kind: "path", value };
+  }
+  return { kind: "file", value };
+}
+
+/**
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ CQ 媒体参数：
+ * base64 → `base64://` 前缀（守护进程解码）；url/path/file 原样直出。
+ * 无 canonical 媒体引用时 warn 并返回 undefined（调用方丢弃该段）。
+ */
+export function resolveCqMediaArg(
+  type: string,
+  data: Record<string, unknown> | undefined,
+): string | undefined {
+  const media = data?.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: "icqq_outbound_media_dropped",
+      type,
+      reason: "missing_media_ref",
+    }));
+    return undefined;
+  }
+  if (media.kind === "base64") {
+    return media.value.startsWith("base64://") ? media.value : `base64://${media.value}`;
+  }
+  return media.value;
+}
+
 function pushCqSegment(segments: MessageSegment[], type: string, arg: string): void {
   switch (type) {
     case "face":
       segments.push({ type: "face", data: { id: Number(arg) } });
       break;
     case "image":
-      segments.push({ type: "image", data: { url: arg, file: arg } });
+      segments.push({ type: "image", data: { media: icqqMediaRefFromString(arg) } });
       break;
     case "at":
       if (arg === "all") {
@@ -29,10 +75,10 @@ function pushCqSegment(segments: MessageSegment[], type: string, arg: string): v
       break;
     case "record":
     case "audio":
-      segments.push({ type: "record", data: { file: arg } });
+      segments.push({ type: "record", data: { media: icqqMediaRefFromString(arg) } });
       break;
     case "video":
-      segments.push({ type: "video", data: { file: arg } });
+      segments.push({ type: "video", data: { media: icqqMediaRefFromString(arg) } });
       break;
     case "reply":
       segments.push({ type: "reply", data: { message_id: arg } });
@@ -98,19 +144,8 @@ export function toCqString(content: SendContent): string {
         case "face":
           return `[face:${data.id}]`;
         case "image": {
-          const media = data.media as { kind?: string; value?: string } | undefined;
-          if (media?.value) {
-            if (media.kind === "base64") return `[image:base64://${media.value}]`;
-            return `[image:${media.value}]`;
-          }
-          const b64 =
-            typeof data.base64 === "string"
-              ? data.base64
-              : typeof data.data === "string"
-                ? data.data
-                : undefined;
-          if (b64) return `[image:base64://${b64}]`;
-          return `[image:${data.file || data.url || data.src}]`;
+          const arg = resolveCqMediaArg("image", data);
+          return arg ? `[image:${arg}]` : "";
         }
         case "at":
         case "mention": {
@@ -123,19 +158,12 @@ export function toCqString(content: SendContent): string {
           return "[rps]";
         case "record":
         case "audio": {
-          const b64 =
-            typeof data.base64 === "string"
-              ? data.base64
-              : typeof data.data === "string"
-                ? data.data
-                : undefined;
-          if (b64) return `[record:base64://${b64}]`;
-          return `[record:${data.file || data.url}]`;
+          const arg = resolveCqMediaArg("record", data);
+          return arg ? `[record:${arg}]` : "";
         }
         case "video": {
-          const b64 = typeof data.base64 === "string" ? data.base64 : undefined;
-          if (b64) return `[video:base64://${b64}]`;
-          return `[video:${data.file || data.url}]`;
+          const arg = resolveCqMediaArg("video", data);
+          return arg ? `[video:${arg}]` : "";
         }
         case "reply":
           return `[reply:${data.message_id ?? data.id}]`;

package/src/endpoint.ts

@@ -1,7 +1,7 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -107,6 +107,12 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
     deleteFriend: (userId) => this.deleteFriend(userId),
   });
+  readonly control: EndpointControl = Object.freeze({
+    recall: (messageId: string) => this.recallMessage(messageId),
+    addReaction: (messageId: string, emoji: string) => this.addReaction(messageId, emoji),
+    removeReaction: (messageId: string, reactionId: string) =>
+      this.removeReaction(messageId, reactionId),
+  });
   #open = false;
   #started = false;
   #subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];

package/src/icqq-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `icqq endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `icqq.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  *
  * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
  * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
@@ -19,7 +19,7 @@ export const icqqEndpointCommands = createEndpointCommands({
   addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
   bindFlow: ({ name }) => {
     if (!name) {
-      return '用法：icqq endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
+      return '用法：icqq.endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
     }
     if (!/^\d+$/.test(name)) {
       return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';

package/src/icqq-inbound.ts

@@ -2,7 +2,7 @@
  * icqq 守护进程 IPC 入站事件归一化（post_type / message_type / message 段）
  */
 import { Message, toCanonicalSegments, type MessageSegment, type QuotedMessagePayload } from "zhin.js";
-import { parseCqMessage } from "./cq-message.js";
+import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 import type { GroupRole } from "./types.js";
 
@@ -341,15 +341,14 @@ export function icqqElementsToSegments(
       case "face":
         out.push({ type: "face", data: { id: Number(el.id) } });
         break;
-      case "image":
+      case "image": {
+        const value = String(el.url ?? el.file ?? "");
         out.push({
           type: "image",
-          data: {
-            url: String(el.url ?? el.file ?? ""),
-            file: String(el.file ?? el.url ?? ""),
-          },
+          data: { media: icqqMediaRefFromString(value) },
         });
         break;
+      }
       case "forward": {
         const forwardResid = String(
           el.id ?? el.resid ?? el.res_id ?? el.file ?? "",
@@ -410,18 +409,22 @@ export function icqqElementsToSegments(
         break;
       }
       case "record":
-      case "audio":
+      case "audio": {
+        const value = String(el.file ?? el.url ?? "");
         out.push({
           type: "record",
-          data: { file: String(el.file ?? el.url ?? "") },
+          data: { media: icqqMediaRefFromString(value) },
         });
         break;
-      case "video":
+      }
+      case "video": {
+        const value = String(el.file ?? el.url ?? "");
         out.push({
           type: "video",
-          data: { file: String(el.file ?? el.url ?? "") },
+          data: { media: icqqMediaRefFromString(value) },
         });
         break;
+      }
       default:
         if (el.text != null && el.text !== "") {
           out.push({ type: "text", data: { text: String(el.text) } });

package/src/icqq-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `icqq.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 

package/src/outbound-media.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
+import { isMediaRef } from "@zhin.js/core";
 import type { MessageSegment, SendContent } from "zhin.js";
 import type { IcqqEndpointConfig } from "./types.js";
 
@@ -35,7 +36,7 @@ function spoolBase64ToFile(
 
 /**
  * 出站媒体模式：file=本机落盘后 CQ [image:path]（与 icqq 同机时可用）；
- * base64=保留 segment.base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
+ * base64=保留 MediaRef base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
  */
 export function resolveIcqqOutboundMediaMode(
   config: Pick<IcqqEndpointConfig, "rpc" | "outboundMedia">,
@@ -47,9 +48,10 @@ export function resolveIcqqOutboundMediaMode(
 }
 
 /**
- * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
- * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
+ * 并把 media 改写为 path 引用（与 icqq 同机时守护进程直接读盘）。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程解码）。
+ * 无 canonical MediaRef 的段原样保留（不可投递，由下游 CQ 序列化 warn + 丢弃）。
  */
 export function materializeOutboundBase64(
   content: SendContent,
@@ -62,42 +64,30 @@ export function materializeOutboundBase64(
     if (typeof seg === "string") return seg;
     const { type, data } = seg as MessageSegment;
     const d = data as Record<string, unknown>;
-    const media = d.media as
-      | { kind?: unknown; value?: unknown; mime_type?: unknown }
-      | undefined;
-    const mediaBase64 =
-      media && media.kind === "base64" && typeof media.value === "string" && media.value
-        ? media.value.replace(/^base64:\/\//, "")
-        : undefined;
-    const legacyBase64 = d.base64 ?? d.data;
-    const b64 =
-      mediaBase64 ??
-      (typeof legacyBase64 === "string" && legacyBase64 ? legacyBase64 : undefined);
+    const media = d.media;
+    if (!isMediaRef(media) || media.kind !== "base64") return seg;
+    const b64 = media.value.replace(/^base64:\/\//, "");
     if (!b64) return seg;
+    if (type !== "image" && type !== "record" && type !== "audio" && type !== "video") {
+      return seg;
+    }
 
-    const mime = String(
-      d.mime ?? d.mimeType ?? (typeof media?.mime_type === "string" ? media.mime_type : "") ?? "",
+    const mime = media.mime_type ?? "";
+    const filePath = spoolBase64ToFile(
+      b64,
+      mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"),
+      type === "record" || type === "audio" ? "audio" : type,
     );
-    if (type === "image" || type === "record" || type === "audio" || type === "video") {
-      const filePath = spoolBase64ToFile(
-        b64,
-        mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"),
-        type === "record" || type === "audio" ? "audio" : type,
-      );
-      return {
-        type,
-        data: {
-          ...d,
-          media: {
-            kind: "path",
-            value: filePath,
-            ...(mime ? { mime_type: mime } : {}),
-          },
-          file: filePath,
-          url: filePath,
+    return {
+      type,
+      data: {
+        ...d,
+        media: {
+          kind: "path",
+          value: filePath,
+          ...(mime ? { mime_type: mime } : {}),
         },
-      } as MessageSegment;
-    }
-    return seg;
+      },
+    } as MessageSegment;
   });
 }

package/src/protocol.ts

@@ -14,6 +14,7 @@
 
 import { pickCredential } from '@zhin.js/adapter';
 import type { MessageSegment } from "zhin.js";
+import { resolveCqMediaArg } from "./cq-message.js";
 
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
@@ -427,17 +428,23 @@ export function formatOutboundBody(payload: unknown): string {
       case 'at':
       case 'mention':
         return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
-      case 'image':
-        return `[image:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+      case 'image': {
+        const arg = resolveCqMediaArg('image', item.data);
+        return arg ? `[image:${arg}]` : '';
+      }
       case 'face':
         return `[face:${item.data?.id ?? ''}]`;
       case 'reply':
         return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
       case 'record':
-      case 'audio':
-        return `[record:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
-      case 'video':
-        return `[video:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+      case 'audio': {
+        const arg = resolveCqMediaArg('record', item.data);
+        return arg ? `[record:${arg}]` : '';
+      }
+      case 'video': {
+        const arg = resolveCqMediaArg('video', item.data);
+        return arg ? `[video:${arg}]` : '';
+      }
       default:
         return String(item.data?.text ?? '');
     }
@@ -449,28 +456,6 @@ export function formatInboundContent(rawMessage: string): string {
   return rawMessage;
 }
 
-/** base64 媒体回退：CQ `base64://` 由守护进程解码（异机 RPC 场景）。 */
-function base64Media(data: Record<string, unknown> | undefined): string | undefined {
-  const b64 = data?.base64;
-  return typeof b64 === 'string' && b64 ? `base64://${b64}` : undefined;
-}
-
-/**
- * canonical MediaRef（`data.media`，见 built/segment-contract）→ CQ 媒体值：
- * base64 → `base64://` 前缀（守护进程解码）；url/path 直出。
- * file 模式下 materializeOutboundBase64 已把 base64 落盘并把 media 改写为 path 引用。
- */
-function mediaRefValue(data: Record<string, unknown> | undefined): string | undefined {
-  const media = data?.media;
-  if (!media || typeof media !== 'object' || Array.isArray(media)) return undefined;
-  const { kind, value } = media as { kind?: unknown; value?: unknown };
-  if (typeof value !== 'string' || !value) return undefined;
-  if (kind === 'base64') {
-    return value.startsWith('base64://') ? value : `base64://${value}`;
-  }
-  return value;
-}
-
 /** 段对象判定：`{ type: string, data? }`（非数组 payload 的防御入口）。 */
 function isWireSegment(value: unknown): value is IcqqWireSegment {
   return typeof value === 'object'