@zhin.js/adapter-icqq 6.0.3 → 7.0.1

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/lib/types.d.ts

@@ -70,3 +70,18 @@ export interface IpcMemberInfo {
     last_sent_time?: number;
     shutup_time?: number;
 }
+/**
+ * GET_SYSTEM_MSG 归一后的待处理请求（@icqqjs/cli NormalizedSystemMessage）。
+ * friendRequests 与 groupRequests 均为该形状，按 flag 处理。
+ */
+export interface IpcSystemMessage {
+    type: string;
+    user_id?: number;
+    nickname?: string;
+    group_id?: number;
+    group_name?: string;
+    comment?: string;
+    flag?: string;
+    seq?: number;
+    time?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "6.0.3",
+  "version": "7.0.1",
   "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.0.1",
-    "@zhin.js/core": "1.3.5",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -63,11 +64,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -93,6 +95,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,4 +1,6 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
+import { icqqRuntimeStateToken } from './src/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.
@@ -9,7 +11,9 @@ export default definePlugin({
   metadata: {
     displayName: 'ICQQ Adapter',
   },
-  setup() {
+  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;

package/schema.json

@@ -3,33 +3,102 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "description": "QQ uin (must match icqq login account)"
-    },
     "master": {
-      "type": ["string", "number"],
+      "type": [
+        "string",
+        "number"
+      ],
       "description": "Endpoint Owner QQ uin (for /approve bash and master role)"
     },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted QQ uin"
+      },
+      "description": "Trusted QQ uin list"
+    },
     "autoReconnect": {
       "type": "boolean",
       "default": true
     },
     "outboundMedia": {
       "type": "string",
-      "enum": ["file", "base64"],
+      "enum": [
+        "file",
+        "base64"
+      ],
       "description": "file=local path (same host as daemon); base64=CQ base64:// (default when rpc set)"
     },
-    "rpc": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "host": { "type": "string" },
-        "port": { "type": "number" },
-        "token": { "type": "string" }
-      },
-      "required": ["host", "port", "token"]
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "QQ uin (must match icqq login account)"
+          },
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Endpoint Owner QQ uin (for /approve bash and master role)"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted QQ uin"
+            },
+            "description": "Trusted QQ uin list"
+          },
+          "rpc": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host": {
+                "type": "string",
+                "description": "RPC host"
+              },
+              "port": {
+                "type": "number",
+                "description": "RPC port"
+              },
+              "token": {
+                "type": "string",
+                "description": "RPC token"
+              }
+            },
+            "required": [
+              "host",
+              "port",
+              "token"
+            ]
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["name"]
-}
+  "required": [
+    "master",
+    "endpoints"
+  ]
+}