@zhin.js/adapter-icqq 7.0.0 → 7.0.2

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @zhin.js/adapter-icqq
 
+## 7.0.2
+
+### Patch Changes
+
+- d5cd4aa: Publish Plugin Runtime entry points and convention modules as JavaScript so
+  installed npm plugins load on Node without TypeScript stripping. Workspace
+  development continues to prefer TypeScript sources for local HMR.
+
+  Remove the unconsumed legacy game hub APIs from game-kit; game navigation and
+  records now use ordinary convention commands owned by the game hub plugin.
+
+- Updated dependencies [d5cd4aa]
+  - @zhin.js/command@1.0.4
+  - zhin.js@5.0.2
+  - @zhin.js/adapter@1.1.2
+  - @zhin.js/core@1.4.2
+  - @zhin.js/agent@1.0.7
+
+## 7.0.1
+
+### Patch Changes
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
 ## 7.0.0
 
 ### Patch Changes

package/adapters/icqq.js

@@ -0,0 +1,89 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { databaseHostToken, INBOX_TABLE_NOTICE, INBOX_TABLE_REQUEST, runtimeEventPublisherToken, } from '@zhin.js/plugin-runtime';
+import { IcqqIpcEndpoint } from "../lib/endpoint.js";
+import { icqqRuntimeStateToken } from "../lib/icqq-runtime-state.js";
+import { resolveIcqqConfig, } from "../lib/protocol.js";
+export { IcqqIpcEndpoint } from "../lib/endpoint.js";
+const logger = getLogger('icqq');
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // 统一消息元素通道（UNI-Channel）：端点可消费 base64 / url / upload 媒体
+    // （path 由出站物化按 file/base64 模式转换，非声明消费形态）；
+    // 卡片/按钮等富交互段无原生承载，降级纯文本。
+    segments: {
+        outboundMedia: ['base64', 'url', 'upload'],
+        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 的"运行中"数据源）
+        context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
+            name: config.name,
+            mode: config.rpc ? 'rpc' : 'ipc',
+        });
+        const inbox = resolveInboxHooks(context);
+        return new IcqqIpcEndpoint({
+            id: context.id,
+            gateway: context.use(messageGatewayToken),
+            config,
+            ...(inbox ? { inbox } : {}),
+        });
+    },
+});
+/** 资源可选（轻量 Root 无 DatabaseHost / console hub）：缺失时降级为不写收件箱。 */
+function tryUse(context, token) {
+    try {
+        return context.use(token);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 收件箱钩子：写 unified_inbox_request/notice（按 platform_*_id 去重，
+ * 推送事件与 GET_SYSTEM_MSG 首拉可能重复同一请求），并经 console hub 广播。
+ */
+function resolveInboxHooks(context) {
+    const host = tryUse(context, databaseHostToken);
+    const publisher = tryUse(context, runtimeEventPublisherToken);
+    if (!host && !publisher)
+        return undefined;
+    const insertDeduped = async (table, idField, row) => {
+        const model = host?.models.get(table);
+        if (!model)
+            return;
+        try {
+            const existing = await model.select().where({
+                adapter: row.adapter,
+                endpoint_id: row.endpoint_id,
+                [idField]: row[idField],
+            });
+            if (Array.isArray(existing) && existing.length > 0)
+                return;
+            await model.insert(row);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'inbox_insert',
+                table,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    };
+    const publish = publisher;
+    return {
+        recordRequest: (row) => insertDeduped(INBOX_TABLE_REQUEST, 'platform_request_id', row),
+        recordNotice: (row) => insertDeduped(INBOX_TABLE_NOTICE, 'platform_notice_id', row),
+        ...(publish
+            ? { publish: (type, data) => publish.publish(type, data) }
+            : {}),
+    };
+}

package/adapters/icqq.ts

@@ -12,6 +12,7 @@ import {
   type Token,
 } from '@zhin.js/plugin-runtime';
 import { IcqqIpcEndpoint, type IcqqInboxHooks } from '../src/endpoint.js';
+import { icqqRuntimeStateToken } from '../src/icqq-runtime-state.js';
 import {
   resolveIcqqConfig,
   type IcqqAdapterConfig,
@@ -28,14 +29,27 @@ const logger = getLogger('icqq');
 
 export default defineAdapter<IcqqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 统一消息元素通道（UNI-Channel）：端点可消费 base64 / url / upload 媒体
+  // （path 由出站物化按 file/base64 模式转换，非声明消费形态）；
+  // 卡片/按钮等富交互段无原生承载，降级纯文本。
+  segments: {
+    outboundMedia: ['base64', 'url', 'upload'],
+    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 的"运行中"数据源）
+    context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.rpc ? 'rpc' : 'ipc',
+    });
     const inbox = resolveInboxHooks(context);
     return new IcqqIpcEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
-      config: resolveIcqqConfig(context.config),
+      config,
       ...(inbox ? { inbox } : {}),
     });
   },

package/commands/endpoint/add/[name:string=].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.add;

package/commands/endpoint/add/[name:string=].ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.list;

package/commands/endpoint/remove/[name:string].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.remove;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.remove;

package/lib/endpoint.js

@@ -494,14 +494,38 @@ export class IcqqIpcEndpoint {
     }
     /** Test / internal: admit when open. */
     admit(msg) {
-        if (!this.#open)
+        if (!this.#open) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'endpoint_closed',
+                endpoint: this.name,
+                id: msg.id,
+                target: msg.target,
+            }));
             return;
-        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）只能经 metadata 传递
-        const mentioned = isIcqqBotMentioned({ uin: this.name, rawMessage: msg.content });
+        }
+        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）经结构化段 / metadata 传递
+        const mentioned = isIcqqBotMentioned({
+            uin: this.name,
+            content: msg.segments,
+            rawMessage: msg.content,
+        });
+        logger.debug(formatCompact({
+            op: 'icqq_inbound_admit',
+            endpoint: this.name,
+            id: msg.id,
+            target: msg.target,
+            sender: msg.sender,
+            channelType: msg.channelType,
+            mentioned: mentioned || undefined,
+            preview: msg.content.slice(0, 80),
+            segments: summarizeSegmentTypes(msg.segments),
+        }));
         void this.#options.gateway.receive({
             adapter: this.#options.id,
             target: msg.target,
             content: msg.content,
+            ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
             id: msg.id,
             metadata: Object.freeze({
@@ -555,13 +579,36 @@ export class IcqqIpcEndpoint {
         if (!isIcqqMessagePostType(payload))
             return;
         const data = payload;
-        if (shouldSkipSelfInboundMessage(data))
+        if (shouldSkipSelfInboundMessage(data)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'self',
+                endpoint: this.name,
+                user_id: data.user_id,
+                self_id: data.self_id,
+            }));
             return;
+        }
         const normalized = normalizeIcqqInboundMessage(data);
-        if (!normalized)
+        if (!normalized) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'normalize_failed',
+                endpoint: this.name,
+                message_id: data.message_id,
+                message_type: data.message_type ?? data.type,
+            }));
             return;
-        if (!this.#inboundDeduper.shouldProcess(normalized.messageId))
+        }
+        if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.name,
+                id: normalized.messageId,
+            }));
             return;
+        }
         this.admit({
             id: normalized.messageId,
             target: formatInboundTarget({
@@ -570,6 +617,7 @@ export class IcqqIpcEndpoint {
                 channelParentGroupId: normalized.channelParentGroupId,
             }),
             content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
             sender: normalized.userId,
             channelType: normalized.channelType,
             metadata: buildIcqqQuoteMetadata(data, {
@@ -583,11 +631,24 @@ export class IcqqIpcEndpoint {
         if (!payload || typeof payload !== 'object')
             return;
         const normalized = normalizeIcqqGuildInboundMessage(payload);
-        if (!normalized)
+        if (!normalized) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'guild_normalize_failed',
+                endpoint: this.name,
+            }));
             return;
+        }
         this.#guildCatalog.upsertFromInbound(normalized.raw);
-        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`))
+        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.name,
+                id: `guild:${normalized.messageId}`,
+            }));
             return;
+        }
         this.admit({
             id: normalized.messageId,
             target: formatInboundTarget({
@@ -596,6 +657,7 @@ export class IcqqIpcEndpoint {
                 guildId: normalized.guildId,
             }),
             content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
             sender: normalized.userId,
             channelType: 'channel',
             metadata: {
@@ -706,6 +768,20 @@ function toNumericId(value, label) {
     }
     return n;
 }
+function summarizeSegmentTypes(segments) {
+    if (!segments?.length)
+        return undefined;
+    return segments
+        .map((segment) => {
+        if (typeof segment.type === 'string')
+            return segment.type;
+        if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
+            return String(segment.type.name);
+        }
+        return '?';
+    })
+        .join(',');
+}
 async function defaultCreateIpc(config) {
     const uin = Number(config.name);
     if (config.rpc) {

package/lib/icqq-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const icqqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/icqq-endpoint-commands.js

@@ -0,0 +1,35 @@
+/**
+ * `icqq endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ *
+ * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
+ * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
+ * 触发 login 的 action——扫码登录只能经 `icqq login <uin>` CLI 完成。
+ * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { name: '<uin>' }
+ * 追加到 plugins.icqq.endpoints，并引导用户先完成守护进程登录。
+ */
+import { addEndpointToConfig, createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { icqqRuntimeStateToken } from './icqq-runtime-state.js';
+export const icqqEndpointCommands = createEndpointCommands({
+    adapterKey: 'icqq',
+    adapterDisplayName: 'ICQQ',
+    running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => (entry.rpc ? 'rpc（远程守护进程）' : 'ipc（本地守护进程）'),
+    addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
+    bindFlow: ({ name }) => {
+        if (!name) {
+            return '用法：icqq endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
+        }
+        if (!/^\d+$/.test(name)) {
+            return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';
+        }
+        try {
+            const filePath = addEndpointToConfig('icqq', { name });
+            return (`✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
+                `⚠️ 请确保已执行 icqq login ${name} 启动守护进程并完成扫码登录；重启 zhin 后生效。`);
+        }
+        catch (error) {
+            return `添加失败：${error instanceof Error ? error.message : String(error)}`;
+        }
+    },
+}, defineCommand);

package/lib/icqq-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const icqqRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/icqq-runtime-state.js

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

package/lib/ipc-client.js

@@ -216,7 +216,7 @@ export class IpcClient {
             token = (await readFile(getTokenPath(uin), "utf-8")).trim();
         }
         catch {
-            throw new Error("无法读取认证 token，守护进程可能未运行");
+            throw new Error(`无法读取认证 token，守护进程可能未运行：请先执行 icqq login ${uin} 完成登录并启动守护进程`);
         }
         let rpcInfo;
         try {
@@ -224,7 +224,7 @@ export class IpcClient {
             rpcInfo = JSON.parse(raw);
         }
         catch {
-            throw new Error("RPC 未启用或守护进程未运行");
+            throw new Error(`RPC 未启用或守护进程未运行：请先执行 icqq login ${uin}，并确认守护进程已启用 RPC`);
         }
         return IpcClient.connectRpc({
             host: rpcInfo.host,

package/lib/outbound-media.d.ts

@@ -7,7 +7,8 @@ export type IcqqOutboundMediaMode = "file" | "base64";
  */
 export declare function resolveIcqqOutboundMediaMode(config: Pick<IcqqEndpointConfig, "rpc" | "outboundMedia">): IcqqOutboundMediaMode;
 /**
- * file 模式：将 segment.data.base64 物化为本机路径。
- * base64 模式：不改动（由 toCqString 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
+ * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
  */
 export declare function materializeOutboundBase64(content: SendContent, mode?: IcqqOutboundMediaMode): SendContent;

package/lib/outbound-media.js

@@ -33,8 +33,9 @@ export function resolveIcqqOutboundMediaMode(config) {
     return config.rpc ? "base64" : "file";
 }
 /**
- * file 模式：将 segment.data.base64 物化为本机路径。
- * base64 模式：不改动（由 toCqString 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
+ * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
  */
 export function materializeOutboundBase64(content, mode = "file") {
     if (mode === "base64")
@@ -45,16 +46,27 @@ export function materializeOutboundBase64(content, mode = "file") {
             return seg;
         const { type, data } = seg;
         const d = data;
-        const b64 = d.base64 ?? d.data;
-        if (typeof b64 !== "string" || !b64)
+        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 (!b64)
             return seg;
-        const mime = String(d.mime ?? d.mimeType ?? "");
+        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,
                 },

package/lib/protocol.d.ts

@@ -11,6 +11,7 @@
  *
  * 登录相关：**推送**走 IpcEvent（`system.login.*`）。
  */
+import type { MessageSegment } from "zhin.js";
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
     id: string;
@@ -237,6 +238,11 @@ export interface IcqqInboundMessage {
     readonly id: string;
     readonly target: string;
     readonly content: string;
+    /**
+     * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
+     * 与 content（CQ 原文纯文本视图）同源，随 gateway.receive 上送。
+     */
+    readonly segments?: readonly MessageSegment[];
     readonly sender: string;
     readonly channelType: 'private' | 'group' | 'channel';
     readonly metadata?: Record<string, unknown>;

package/lib/protocol.js

@@ -277,16 +277,16 @@ export function formatOutboundBody(payload) {
             case 'mention':
                 return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
             case 'image':
-                return `[image:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+                return `[image:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
             case 'face':
                 return `[face:${item.data?.id ?? ''}]`;
             case 'reply':
                 return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
             case 'record':
             case 'audio':
-                return `[record:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+                return `[record:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
             case 'video':
-                return `[video:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+                return `[video:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
             default:
                 return String(item.data?.text ?? '');
         }
@@ -301,6 +301,23 @@ 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.0",
+  "version": "7.0.2",
   "description": "Zhin.js ICQQ adapter for Plugin Runtime (IPC daemon client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,18 +34,19 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/command": "1.0.4",
+    "@zhin.js/core": "1.4.2",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/agent": "1.0.7",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -63,12 +64,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "zhin.js": "5.0.0"
+    "@zhin.js/agent": "1.0.7",
+    "zhin.js": "5.0.2"
   },
   "files": [
     "adapters",
-    "plugin.ts",
+    "commands",
+    "plugin.js",
     "schema.json",
     "src",
     "lib",
@@ -86,13 +88,17 @@
   "zhin": {
     "protocol": 1,
     "type": "plugin",
-    "entry": "./plugin.ts",
+    "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"
       }
     ],
     "plugins": []

package/plugin.js

@@ -0,0 +1,37 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { icqqRuntimeStateToken } from "./lib/icqq-runtime-state.js";
+// Module-level guard: multiple icqq instances (icqq, icqq-2, …) share this
+// module, but the prompt contributor is per-platform — register it once.
+let promptContributorRegistered = false;
+export default definePlugin({
+    name: 'icqq',
+    metadata: {
+        displayName: 'ICQQ Adapter',
+    },
+    setup(context) {
+        // 运行中 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.
+        if (promptContributorRegistered)
+            return;
+        let cancelled = false;
+        let unregister;
+        void Promise.all([
+            import('zhin.js/agent'),
+            import("./lib/agent-prompt.js"),
+        ]).then(([agent, prompt]) => {
+            if (cancelled || promptContributorRegistered)
+                return;
+            agent.registerAgentPromptContributor(prompt.createIcqqAgentPromptContributor());
+            promptContributorRegistered = true;
+            unregister = () => agent.unregisterAgentPromptContributor('icqq');
+        }).catch(() => { });
+        return () => {
+            cancelled = true;
+            unregister?.();
+        };
+    },
+});

package/src/endpoint.ts

@@ -624,13 +624,38 @@ export class IcqqIpcEndpoint implements EndpointInstance {
 
   /** Test / internal: admit when open. */
   admit(msg: IcqqInboundMessage): void {
-    if (!this.#open) return;
-    // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）只能经 metadata 传递
-    const mentioned = isIcqqBotMentioned({ uin: this.name, rawMessage: msg.content });
+    if (!this.#open) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'endpoint_closed',
+        endpoint: this.name,
+        id: msg.id,
+        target: msg.target,
+      }));
+      return;
+    }
+    // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）经结构化段 / metadata 传递
+    const mentioned = isIcqqBotMentioned({
+      uin: this.name,
+      content: msg.segments,
+      rawMessage: msg.content,
+    });
+    logger.debug(formatCompact({
+      op: 'icqq_inbound_admit',
+      endpoint: this.name,
+      id: msg.id,
+      target: msg.target,
+      sender: msg.sender,
+      channelType: msg.channelType,
+      mentioned: mentioned || undefined,
+      preview: msg.content.slice(0, 80),
+      segments: summarizeSegmentTypes(msg.segments),
+    }));
     void this.#options.gateway.receive({
       adapter: this.#options.id,
       target: msg.target,
       content: msg.content,
+      ...(msg.segments ? { segments: msg.segments } : {}),
       sender: msg.sender,
       id: msg.id,
       metadata: Object.freeze({
@@ -684,10 +709,36 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     if (!isIcqqMessagePostType(payload)) return;
     const data = payload as IcqqIpcMessageEvent;
-    if (shouldSkipSelfInboundMessage(data)) return;
+    if (shouldSkipSelfInboundMessage(data)) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'self',
+        endpoint: this.name,
+        user_id: data.user_id,
+        self_id: data.self_id,
+      }));
+      return;
+    }
     const normalized = normalizeIcqqInboundMessage(data);
-    if (!normalized) return;
-    if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) return;
+    if (!normalized) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'normalize_failed',
+        endpoint: this.name,
+        message_id: data.message_id,
+        message_type: data.message_type ?? data.type,
+      }));
+      return;
+    }
+    if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'dedupe',
+        endpoint: this.name,
+        id: normalized.messageId,
+      }));
+      return;
+    }
     this.admit({
       id: normalized.messageId,
       target: formatInboundTarget({
@@ -696,6 +747,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         channelParentGroupId: normalized.channelParentGroupId,
       }),
       content: formatInboundContent(normalized.rawMessage),
+      segments: normalized.content,
       sender: normalized.userId,
       channelType: normalized.channelType,
       metadata: buildIcqqQuoteMetadata(data, {
@@ -711,9 +763,24 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     const normalized = normalizeIcqqGuildInboundMessage(
       payload as Parameters<typeof normalizeIcqqGuildInboundMessage>[0],
     );
-    if (!normalized) return;
+    if (!normalized) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'guild_normalize_failed',
+        endpoint: this.name,
+      }));
+      return;
+    }
     this.#guildCatalog.upsertFromInbound(normalized.raw);
-    if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) return;
+    if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
+      logger.debug(formatCompact({
+        op: 'icqq_inbound_skip',
+        reason: 'dedupe',
+        endpoint: this.name,
+        id: `guild:${normalized.messageId}`,
+      }));
+      return;
+    }
     this.admit({
       id: normalized.messageId,
       target: formatInboundTarget({
@@ -722,6 +789,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         guildId: normalized.guildId,
       }),
       content: formatInboundContent(normalized.rawMessage),
+      segments: normalized.content,
       sender: normalized.userId,
       channelType: 'channel',
       metadata: {
@@ -834,6 +902,21 @@ function toNumericId(value: number | string, label: string): number {
   return n;
 }
 
+function summarizeSegmentTypes(
+  segments: readonly { readonly type?: unknown }[] | undefined,
+): string | undefined {
+  if (!segments?.length) return undefined;
+  return segments
+    .map((segment) => {
+      if (typeof segment.type === 'string') return segment.type;
+      if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
+        return String((segment.type as { name: unknown }).name);
+      }
+      return '?';
+    })
+    .join(',');
+}
+
 async function defaultCreateIpc(config: ResolvedIcqqConfig): Promise<IcqqIpcTransport> {
   const uin = Number(config.name);
   if (config.rpc) {

package/src/icqq-endpoint-commands.ts

@@ -0,0 +1,37 @@
+/**
+ * `icqq endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ *
+ * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
+ * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
+ * 触发 login 的 action——扫码登录只能经 `icqq login <uin>` CLI 完成。
+ * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { name: '<uin>' }
+ * 追加到 plugins.icqq.endpoints，并引导用户先完成守护进程登录。
+ */
+import { addEndpointToConfig, createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { icqqRuntimeStateToken } from './icqq-runtime-state.js';
+
+export const icqqEndpointCommands = createEndpointCommands({
+  adapterKey: 'icqq',
+  adapterDisplayName: 'ICQQ',
+  running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => (entry.rpc ? 'rpc（远程守护进程）' : 'ipc（本地守护进程）'),
+  addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
+  bindFlow: ({ name }) => {
+    if (!name) {
+      return '用法：icqq endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
+    }
+    if (!/^\d+$/.test(name)) {
+      return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';
+    }
+    try {
+      const filePath = addEndpointToConfig('icqq', { name });
+      return (
+        `✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
+        `⚠️ 请确保已执行 icqq login ${name} 启动守护进程并完成扫码登录；重启 zhin 后生效。`
+      );
+    } catch (error) {
+      return `添加失败：${error instanceof Error ? error.message : String(error)}`;
+    }
+  },
+}, defineCommand);

package/src/icqq-runtime-state.ts

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

package/src/ipc-client.ts

@@ -266,7 +266,7 @@ export class IpcClient {
     try {
       token = (await readFile(getTokenPath(uin), "utf-8")).trim();
     } catch {
-      throw new Error("无法读取认证 token，守护进程可能未运行");
+      throw new Error(`无法读取认证 token，守护进程可能未运行：请先执行 icqq login ${uin} 完成登录并启动守护进程`);
     }
 
     let rpcInfo: { host: string; port: number };
@@ -274,7 +274,7 @@ export class IpcClient {
       const raw = await readFile(getRpcPortPath(uin), "utf-8");
       rpcInfo = JSON.parse(raw);
     } catch {
-      throw new Error("RPC 未启用或守护进程未运行");
+      throw new Error(`RPC 未启用或守护进程未运行：请先执行 icqq login ${uin}，并确认守护进程已启用 RPC`);
     }
 
     return IpcClient.connectRpc({

package/src/outbound-media.ts

@@ -47,8 +47,9 @@ export function resolveIcqqOutboundMediaMode(
 }
 
 /**
- * file 模式：将 segment.data.base64 物化为本机路径。
- * base64 模式：不改动（由 toCqString 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
+ * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
  */
 export function materializeOutboundBase64(
   content: SendContent,
@@ -61,10 +62,22 @@ export function materializeOutboundBase64(
     if (typeof seg === "string") return seg;
     const { type, data } = seg as MessageSegment;
     const d = data as Record<string, unknown>;
-    const b64 = d.base64 ?? d.data;
-    if (typeof b64 !== "string" || !b64) return seg;
+    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);
+    if (!b64) return seg;
 
-    const mime = String(d.mime ?? d.mimeType ?? "");
+    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,
@@ -75,6 +88,11 @@ export function materializeOutboundBase64(
         type,
         data: {
           ...d,
+          media: {
+            kind: "path",
+            value: filePath,
+            ...(mime ? { mime_type: mime } : {}),
+          },
           file: filePath,
           url: filePath,
         },

package/src/protocol.ts

@@ -13,6 +13,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import type { MessageSegment } from "zhin.js";
 
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
@@ -313,6 +314,11 @@ export interface IcqqInboundMessage {
   readonly id: string;
   readonly target: string;
   readonly content: string;
+  /**
+   * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
+   * 与 content（CQ 原文纯文本视图）同源，随 gateway.receive 上送。
+   */
+  readonly segments?: readonly MessageSegment[];
   readonly sender: string;
   readonly channelType: 'private' | 'group' | 'channel';
   readonly metadata?: Record<string, unknown>;
@@ -422,16 +428,16 @@ export function formatOutboundBody(payload: unknown): string {
       case 'mention':
         return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
       case 'image':
-        return `[image:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[image:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       case 'face':
         return `[face:${item.data?.id ?? ''}]`;
       case 'reply':
         return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
       case 'record':
       case 'audio':
-        return `[record:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[record:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       case 'video':
-        return `[video:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[video:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       default:
         return String(item.data?.text ?? '');
     }
@@ -449,6 +455,22 @@ function base64Media(data: Record<string, unknown> | undefined): string | undefi
   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'

package/plugin.ts

@@ -1,32 +0,0 @@
-import { definePlugin } from '@zhin.js/plugin-runtime';
-
-// Module-level guard: multiple icqq instances (icqq, icqq-2, …) share this
-// module, but the prompt contributor is per-platform — register it once.
-let promptContributorRegistered = false;
-
-export default definePlugin({
-  name: 'icqq',
-  metadata: {
-    displayName: 'ICQQ Adapter',
-  },
-  setup() {
-    // Agent prompt contributor (orchestrator/deferred-worker ICQQ guidance).
-    // `zhin.js/agent` is an optional peer — skip silently on IM-only installs.
-    if (promptContributorRegistered) return;
-    let cancelled = false;
-    let unregister: (() => void) | undefined;
-    void Promise.all([
-      import('zhin.js/agent'),
-      import('./src/agent-prompt.js'),
-    ]).then(([agent, prompt]) => {
-      if (cancelled || promptContributorRegistered) return;
-      agent.registerAgentPromptContributor(prompt.createIcqqAgentPromptContributor());
-      promptContributorRegistered = true;
-      unregister = () => agent.unregisterAgentPromptContributor('icqq');
-    }).catch(() => { /* optional peer not installed */ });
-    return () => {
-      cancelled = true;
-      unregister?.();
-    };
-  },
-});