@zhin.js/adapter-qq 5.0.3 → 6.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "5.0.3",
+  "version": "6.0.1",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,19 +35,20 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@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": {
@@ -65,12 +66,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/host-http": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -96,6 +98,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,15 @@
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerQqPlatformPermitChecker } from './src/platform-permit.js';
+import { createQqRuntimeState, qqRuntimeStateToken } from './src/qq-runtime-state.js';
 
 export default definePlugin({
   name: 'qq',
   metadata: {
     displayName: 'QQ Official WebSocket Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表 + 扫码绑定单例，供 adapter create 与 `qq endpoint` 命令共享
+    context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
     // 平台权限门禁：guild_owner / guild_admin / manage_roles / manage_channels（agent 工具 platformPermit）
     return registerQqPlatformPermitChecker();
   },

package/schema.json

@@ -3,19 +3,13 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "qq-bot"
-    },
-    "appid": {
-      "type": "string"
-    },
-    "secret": {
-      "type": "string"
-    },
     "mode": {
       "type": "string",
-      "enum": ["websocket", "webhook", "middleware"],
+      "enum": [
+        "websocket",
+        "webhook",
+        "middleware"
+      ],
       "default": "websocket",
       "description": "WebSocket gateway (default). webhook/middleware use httpHostToken POST."
     },
@@ -23,9 +17,15 @@
       "type": "boolean",
       "default": false
     },
+    "master": {
+      "type": ["string", "number"],
+      "description": "Endpoint Owner（qq endpoint 管理命令权限、AI master 角色）；endpoints[i] 可逐项覆盖"
+    },
     "intents": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     },
     "accessTokenUrl": {
       "type": "string"
@@ -45,7 +45,41 @@
     "path": {
       "type": "string",
       "description": "Legacy standalone webhook path (unused with httpHostToken)."
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "QQ bot name"
+          },
+          "appid": {
+            "type": "string",
+            "description": "QQ official bot app ID"
+          },
+          "secret": {
+            "type": "string",
+            "description": "QQ official bot secret"
+          }
+        },
+        "required": [
+          "name",
+          "appid",
+          "secret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["appid", "secret"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -1,16 +1,20 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type {
+  EndpointChannel,
+  EndpointInstance,
+  EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import {
   formatInboundContent,
   formatInboundTarget,
-  formatOutboundText,
   parseSendTarget,
   resolveOutboundMessageId,
   senderDisplayName,
@@ -51,12 +55,18 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqEndpointOptions) {
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
 
+  /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+  get name(): string {
+    return this.#options.config.name;
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -74,7 +84,11 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     } catch (error) {
       await this.stop();
       logger.error('Failed to connect QQ websocket:', error);
-      throw error;
+      const raw = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
+        { cause: error },
+      );
     }
   }
 
@@ -104,7 +118,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const body = formatOutboundText(payload);
+    const body = formatOutbound(payload);
     const parsed = parseSendTarget(target);
     const bot = this.#requireBot();
     let result: unknown;
@@ -227,12 +241,18 @@ export class QqHttpEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqHttpEndpointOptions) {
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateHttpBot;
   }
 
+  /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+  get name(): string {
+    return this.#options.config.name;
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -285,7 +305,7 @@ export class QqHttpEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const body = formatOutboundText(payload);
+    const body = formatOutbound(payload);
     const parsed = parseSendTarget(target);
     const bot = this.#requireBot();
     let result: unknown;
@@ -387,3 +407,39 @@ export class QqHttpEndpoint implements EndpointInstance {
     return this.#bot;
   }
 }
+
+function createQqEndpointManagement(endpoint: {
+  getGuilds(): Promise<unknown[]>;
+  getChannels(guildId: string): Promise<unknown[]>;
+}): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listChannels(): Promise<readonly EndpointChannel[]> {
+      const channels: EndpointChannel[] = [];
+      const guilds = await endpoint.getGuilds();
+      for (const guildValue of Array.isArray(guilds) ? guilds : []) {
+        const guild = asRecord(guildValue);
+        const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
+        if (!guildId) continue;
+        const guildName = String(guild.name ?? guild.guild_name ?? guildId);
+        const rows = await endpoint.getChannels(guildId);
+        for (const channelValue of Array.isArray(rows) ? rows : []) {
+          const channel = asRecord(channelValue);
+          const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');
+          if (!id) continue;
+          channels.push({
+            id,
+            name: String(channel.name ?? channel.channel_name ?? id),
+            parent: { type: 'guild', id: guildId, name: guildName },
+          });
+        }
+      }
+      return channels;
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}

package/src/index.ts

@@ -16,6 +16,13 @@ export {
   type ResolvedQqWebsocketConfig,
 } from './protocol.js';
 
+export {
+  formatOutbound,
+  resolveMediaFile,
+  type QqOutboundElem,
+  type QqOutboundMessage,
+} from './outbound.js';
+
 export {
   QqHttpEndpoint,
   QqWebsocketEndpoint,

package/src/outbound.ts

@@ -0,0 +1,262 @@
+/**
+ * QQ 官方出站富媒体归一化：把渲染后的 payload 转为 qq-official-bot 可识别的
+ * Sendable 结构（文本串 + 消息段）。移植自 legacy 版 outbound-media /
+ * outbound-markdown / outbound-keyboard。
+ *
+ * 移植面：
+ * - image：http(s) URL 直发（data.url）；base64://、data:...;base64、本地路径
+ *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
+ * - markdown：data.content 原文，或 custom_template_id + params 模板。
+ * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
+ *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   data.id 模板键盘原样透传。
+ * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { QqWireSegment } from './protocol.js';
+
+const logger = getLogger('qq');
+
+/** qq-official-bot Sendable 的最小结构子集（字符串模板或消息段）。 */
+export interface QqOutboundElem {
+  readonly type: string;
+  readonly data: Record<string, unknown>;
+}
+
+export type QqOutboundMessage = string | QqOutboundElem | readonly (string | QqOutboundElem)[];
+
+interface QqOutboundButtonSpec {
+  readonly id?: string;
+  readonly label?: string;
+  readonly payload?: string;
+  readonly disabled?: boolean;
+  readonly mode?: string;
+  readonly command?: { readonly enter?: boolean; readonly reply?: boolean };
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineBase64(value: string): boolean {
+  return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+
+/**
+ * 解析 image/audio/video/file 段的本地或内联 payload。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL；
+ * base64:// / data:...;base64 / 本地路径须走 data.file 才会解析为 file_data。
+ */
+export function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+  const url = typeof data.url === 'string' ? data.url : undefined;
+  const file = typeof data.file === 'string' ? data.file : undefined;
+  const base64 = typeof data.base64 === 'string' ? data.base64 : undefined;
+
+  if (file && !isRemoteUrl(file)) return file;
+  if (url && isInlineBase64(url)) return url;
+  if (url && !isRemoteUrl(url) && (url.startsWith('file://') || url.startsWith('/'))) return url;
+  if (base64) return base64.startsWith('base64://') ? base64 : `base64://${base64}`;
+  return undefined;
+}
+
+function normalizeMediaSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = { ...(seg.data ?? {}) };
+  const file = resolveMediaFile(data);
+  if (file) {
+    delete data.url;
+    delete data.base64;
+    data.file = file;
+    return { type: seg.type, data };
+  }
+  const url = typeof data.url === 'string' ? data.url
+    : typeof data.file === 'string' ? data.file
+      : undefined;
+  if (url && isRemoteUrl(url)) {
+    delete data.base64;
+    return { type: seg.type, data: { ...data, url } };
+  }
+  // 既无远程 URL 也无本地上传源：无法投递，降级留痕
+  logger.warn(formatCompact({
+    op: 'qq_outbound_media_dropped',
+    type: seg.type,
+    reason: 'missing_source',
+  }));
+  return null;
+}
+
+function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = seg.data ?? {};
+  const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+    ? data.custom_template_id
+    : typeof data.template_id === 'string' && data.template_id
+      ? data.template_id
+      : undefined;
+  if (templateId) {
+    return {
+      type: 'markdown',
+      data: {
+        custom_template_id: templateId,
+        params: Array.isArray(data.params) ? data.params : [],
+      },
+    };
+  }
+  const content = String(data.content ?? data.text ?? '');
+  if (!content.trim()) {
+    logger.warn(formatCompact({ op: 'qq_outbound_markdown_dropped', reason: 'empty_content' }));
+    return null;
+  }
+  return { type: 'markdown', data: { content } };
+}
+
+function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
+  const isCommand = btn.mode === 'command';
+  const action: Record<string, unknown> = {
+    type: isCommand ? 2 : 1,
+    permission: { type: 2 },
+    data: btn.payload ?? '',
+    click_limit: btn.disabled ? 0 : 10,
+    unsupport_tips: btn.disabled ? '该按钮不可用' : '',
+  };
+  if (isCommand) {
+    if (btn.command?.enter != null) action.enter = btn.command.enter;
+    if (btn.command?.reply != null) action.reply = btn.command.reply;
+  }
+  return {
+    id: btn.id ?? '',
+    render_data: {
+      label: btn.label ?? '',
+      visited_label: btn.label ?? '',
+      style: 0,
+    },
+    action,
+  };
+}
+
+/** keyboard 段 → 模板键盘（data.id）或 button 行段（data.rows） */
+function expandKeyboardSegment(seg: QqWireSegment): QqOutboundElem[] {
+  const data = seg.data ?? {};
+  if (typeof data.id === 'string' && data.id) {
+    return [{ type: 'keyboard', data: { id: data.id } }];
+  }
+  if (!Array.isArray(data.rows)) {
+    logger.warn(formatCompact({ op: 'qq_outbound_keyboard_dropped', reason: 'missing_rows' }));
+    return [];
+  }
+  const out: QqOutboundElem[] = [];
+  for (const row of data.rows) {
+    if (!Array.isArray(row)) continue;
+    out.push({
+      type: 'button',
+      data: {
+        buttons: row.map((btn) => coreButtonToQq((btn ?? {}) as QqOutboundButtonSpec)),
+      },
+    });
+  }
+  return out;
+}
+
+function toSegmentList(payload: unknown): Array<string | QqWireSegment> {
+  if (Array.isArray(payload)) return payload as Array<string | QqWireSegment>;
+  if (payload && typeof payload === 'object' && 'type' in payload) {
+    return [payload as QqWireSegment];
+  }
+  return [];
+}
+
+function textFromUnknownSegment(seg: QqWireSegment): string {
+  const data = seg.data ?? {};
+  return data.text != null ? String(data.text) : '';
+}
+
+/**
+ * 渲染后 payload → QQ Sendable。
+ * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
+ */
+export function formatOutbound(payload: unknown): QqOutboundMessage {
+  if (typeof payload === 'string') return payload;
+
+  const segments = toSegmentList(payload);
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+  const hasKeyboard = segments.some(
+    (item) => typeof item !== 'string' && item.type === 'keyboard',
+  );
+
+  const parts: Array<string | QqOutboundElem> = [];
+  let textBuf = '';
+  const flushText = (): void => {
+    if (!textBuf) return;
+    parts.push(hasKeyboard
+      ? { type: 'markdown', data: { content: textBuf } }
+      : textBuf);
+    textBuf = '';
+  };
+
+  for (const item of segments) {
+    if (typeof item === 'string') {
+      textBuf += item;
+      continue;
+    }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'text':
+        textBuf += String(data.text ?? data.content ?? '');
+        break;
+      case 'at': {
+        const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+        if (!id) break;
+        flushText();
+        parts.push({ type: 'at', data: { user_id: id } });
+        break;
+      }
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'file': {
+        flushText();
+        const media = normalizeMediaSegment(item);
+        if (media) parts.push(media);
+        break;
+      }
+      case 'markdown': {
+        flushText();
+        const markdown = normalizeMarkdownSegment(item);
+        if (markdown) parts.push(markdown);
+        break;
+      }
+      case 'keyboard': {
+        flushText();
+        parts.push(...expandKeyboardSegment(item));
+        break;
+      }
+      case 'reply': {
+        const id = data.id ?? data.event_id;
+        if (id == null || id === '') break;
+        flushText();
+        parts.push({
+          type: 'reply',
+          data: data.event_id != null
+            ? { event_id: String(data.event_id) }
+            : { id: String(id) },
+        });
+        break;
+      }
+      default:
+        // 未识别段：保持既有文本降级
+        textBuf += textFromUnknownSegment(item);
+        break;
+    }
+  }
+  flushText();
+
+  if (parts.length === 0) return '';
+  if (parts.length === 1) return parts[0]!;
+  return parts;
+}

package/src/protocol.ts

@@ -4,6 +4,9 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('qq');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface QqAdapterConfig {
@@ -193,8 +196,19 @@ export function formatOutboundText(payload: unknown): string {
           const id = String(data.user_id ?? data.qq ?? data.id ?? '');
           return id ? `<@!${id}>` : '';
         }
-        case 'image':
-          return String(data.url || data.file || '');
+        case 'image': {
+          const src = String(data.url || data.file || '');
+          // base64/本地路径由 formatOutbound 走媒体上传，文本视图静默省略；
+          // 仅当彻底缺少来源时留痕，避免出站静默降级排障无头绪。
+          if (!src) {
+            logger.warn(formatCompact({
+              op: 'qq_outbound_image_dropped',
+              reason: 'missing_source',
+            }));
+            return '';
+          }
+          return /^https?:\/\//.test(src) ? src : '';
+        }
         case 'reply':
           return '';
         default: