@zhin.js/adapter-qq 4.0.2 → 5.0.1

package/src/index.ts

@@ -2,7 +2,7 @@
  * QQ 官方适配器入口：类型扩展、导出、注册
  */
 import path from "node:path";
-import { usePlugin, type Plugin, type IGroupManagement, createGroupManagementTools, type ToolFeature } from "zhin.js";
+import { usePlugin, type Plugin, type ISceneManagement, createSceneManagementTools, type ToolFeature } from "zhin.js";
 import type { Router } from "@zhin.js/host-router";
 import { QQAdapter } from "./adapter.js";
 import { PageManager } from "@zhin.js/host-api";
@@ -11,6 +11,7 @@ import {
   qqGuildPermitResolver,
   registerQqPlatformPermitChecker,
 } from "./platform-permit.js";
+import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
 
 declare module "zhin.js" {
   namespace Plugin {
@@ -30,9 +31,12 @@ declare module "zhin.js" {
 export * from "./types.js";
 export { QQEndpoint } from "./endpoint.js";
 export { QQAdapter } from "./adapter.js";
+export { startQqBindFlow } from "./qq-bind-flow.js";
+export * from "./qq-bind-api.js";
+export { QqEndpointManager, disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
 
 const plugin = usePlugin();
-const { provide, useContext } = plugin;
+const { provide, useContext, onDispose } = plugin;
 
 useContext("router", (router: Router) => {
   provide({
@@ -52,12 +56,12 @@ useContext("router", (router: Router) => {
 useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {
   const disposers: (() => void)[] = [];
   disposers.push(registerQqPlatformPermitChecker());
-  const groupTools = createGroupManagementTools(
-    qq as unknown as IGroupManagement,
+  const sceneTools = createSceneManagementTools(
+    qq as unknown as ISceneManagement,
     'qq',
     { permitResolver: qqGuildPermitResolver, registerChecker: false },
   );
-  disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
+  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
 
   // 获取频道列表
   disposers.push(toolService.addTool({
@@ -361,3 +365,7 @@ useContext("router", "qq", (router: any, qq: QQAdapter) => {
     }
   });
 });
+
+onDispose(() => {
+  disposeQqEndpointProvision();
+});

package/src/mention-enrich.ts

@@ -0,0 +1,71 @@
+import type { Segment } from 'zhin.js';
+import type { QQAdapter } from './adapter.js';
+
+type MentionWire = {
+  id?: string;
+  member_openid?: string;
+  username?: string;
+  nickname?: string;
+};
+
+type QQEndpointLike = {
+  $id: string;
+  $platformUserId?: string;
+  $config: { name?: string; appid?: string; nickname?: string };
+};
+
+function mentionWireId(row: MentionWire): string {
+  return String(row.id ?? row.member_openid ?? '').trim();
+}
+
+function mentionWireName(row: MentionWire): string | undefined {
+  const name = row.username ?? row.nickname;
+  return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+}
+
+function endpointLookupIds(endpoint: QQEndpointLike): string[] {
+  const cfg = endpoint.$config;
+  return [
+    endpoint.$platformUserId,
+    cfg.appid,
+    cfg.name,
+    endpoint.$id,
+  ].filter((id): id is string => Boolean(id)).map(String);
+}
+
+function resolveEndpointDisplayName(endpoint: QQEndpointLike): string | undefined {
+  const cfg = endpoint.$config;
+  return cfg.nickname?.trim() || cfg.name?.trim() || endpoint.$id;
+}
+
+/** 为 canonical mention 段补齐展示名（平台 payload / endpoint 配置）。 */
+export function enrichCanonicalMentionNames(
+  segments: Segment[],
+  adapter: QQAdapter,
+  wireMentions?: MentionWire[],
+): Segment[] {
+  const nameById = new Map<string, string>();
+  for (const row of wireMentions ?? []) {
+    const id = mentionWireId(row);
+    const name = mentionWireName(row);
+    if (id && name) nameById.set(id, name);
+  }
+
+  for (const endpoint of adapter.endpoints.values()) {
+    const display = resolveEndpointDisplayName(endpoint);
+    if (!display) continue;
+    for (const id of endpointLookupIds(endpoint)) {
+      if (!nameById.has(id)) nameById.set(id, display);
+    }
+  }
+
+  return segments.map((seg) => {
+    if (seg.type !== 'mention') return seg;
+    const data = seg.data as { target?: string; name?: string };
+    const target = String(data.target ?? '').trim();
+    if (!target || data.name) return seg;
+    const name = nameById.get(target);
+    if (!name) return seg;
+    return { ...seg, data: { target, name } };
+  });
+}

package/src/outbound-keyboard.ts

@@ -0,0 +1,118 @@
+/**
+ * 将 core keyboard 段转为 qq-official-bot 可识别的 button / markdown 段。
+ * @see https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/msg-btn.html
+ */
+import type { ButtonData, KeyboardSegmentData } from "zhin.js";
+import type { MessageSegment, SendContent } from "zhin.js";
+import { isKeyboardSegment, KeyboardSegment } from "zhin.js";
+
+function asKeyboardData(item: unknown): KeyboardSegmentData | null {
+  if (item instanceof KeyboardSegment) return item.data;
+  if (item != null && typeof item === "object" && isKeyboardSegment(item as MessageSegment)) {
+    return (item as MessageSegment).data as KeyboardSegmentData;
+  }
+  return null;
+}
+
+type QqButton = {
+  id: string;
+  render_data: { label: string; visited_label: string; style: number };
+  action: {
+    type: number;
+    permission: { type: number };
+    data: string;
+    click_limit: number;
+    unsupport_tips: string;
+    enter?: boolean;
+    reply?: boolean;
+  };
+};
+
+function coreButtonToQq(btn: ButtonData): QqButton {
+  const isCommand = btn.mode === 'command';
+  const action: QqButton['action'] = {
+    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,
+  };
+}
+
+function keyboardDataToQqSegments(data: KeyboardSegmentData): MessageSegment[] {
+  const out: MessageSegment[] = [];
+  for (const row of data.rows) {
+    out.push({
+      type: "button",
+      data: {
+        buttons: row.map(coreButtonToQq),
+      },
+    } as MessageSegment);
+  }
+  return out;
+}
+
+/** QQ 官方出站：keyboard → button 行；前置 text 合并为 markdown（按钮消息需带 markdown） */
+export function expandKeyboardSegmentsForQq(content: SendContent): SendContent {
+  const items = Array.isArray(content) ? content : [content];
+  const out: (string | MessageSegment)[] = [];
+  const textParts: string[] = [];
+
+  for (const item of items) {
+    if (typeof item === "string") {
+      textParts.push(item);
+      continue;
+    }
+    const keyboardData = asKeyboardData(item);
+    if (keyboardData) {
+      if (textParts.length > 0) {
+        out.push({
+          type: "markdown",
+          data: { content: textParts.join("\n") },
+        } as MessageSegment);
+        textParts.length = 0;
+      }
+      out.push(...keyboardDataToQqSegments(keyboardData));
+      continue;
+    }
+
+    if (item.type === "text") {
+      const t = item.data?.text ?? item.data?.content ?? "";
+      if (t) textParts.push(String(t));
+      continue;
+    }
+
+    if (textParts.length > 0) {
+      out.push({
+        type: "markdown",
+        data: { content: textParts.join("\n") },
+      } as MessageSegment);
+      textParts.length = 0;
+    }
+    out.push(item as MessageSegment);
+  }
+
+  if (textParts.length > 0) {
+    out.push({
+      type: "markdown",
+      data: { content: textParts.join("\n") },
+    } as MessageSegment);
+  }
+
+  if (out.length === 0) return { type: "text", data: { text: "" } };
+  if (out.length === 1) return out[0]!;
+  return out;
+}

package/src/outbound-markdown.ts

@@ -1,8 +1,9 @@
 /**
  * 将 AI 出站纯文本段合并为 QQ Markdown 消息（msg_type=2）。
- * 官方已开放全量 Markdown，避免 **bold** 等语法以纯文本展示。
+ * 图文混排时合并为单条 Markdown（图片语法见 QQ 官方文档）。
  */
 import { segment, type MessageElement, type MessageSegment, type SendContent } from "zhin.js";
+import { resolveMediaFile } from "./outbound-media.js";
 
 function isMessageSegment(seg: MessageElement): seg is MessageSegment {
   return typeof seg.type === "string";
@@ -14,8 +15,7 @@ export type OutboundMarkdownMode = boolean | "auto";
 const MARKDOWN_HINT =
   /(?:\*\*|__|`|\[.+\]\(.+\)|^#{1,6}\s|^>\s|^\s*[-*+]\s|^```|\|.+\|)/m;
 
-const BODY_RICH_TYPES = new Set([
-  "image",
+const BLOCKING_RICH_TYPES = new Set([
   "audio",
   "video",
   "file",
@@ -27,11 +27,13 @@ const BODY_RICH_TYPES = new Set([
   "face",
 ]);
 
+const TEXT_IMAGE_MIX_TYPES = new Set(["text", "at", "image"]);
+
 function textSegment(text: string): MessageSegment {
   return { type: "text", data: { text } };
 }
 
-function asSegments(content: SendContent): MessageSegment[] {
+export function asOutboundSegments(content: SendContent): MessageSegment[] {
   if (typeof content === "string") return [textSegment(content)];
   if (!Array.isArray(content)) {
     return isMessageSegment(content) ? [content] : [];
@@ -41,39 +43,147 @@ function asSegments(content: SendContent): MessageSegment[] {
   );
 }
 
+export function splitReplyPrefix(segments: MessageSegment[]): {
+  prefix: MessageSegment[];
+  body: MessageSegment[];
+} {
+  const prefix: MessageSegment[] = [];
+  let i = 0;
+  while (i < segments.length && segments[i].type === "reply") {
+    prefix.push(segments[i]);
+    i++;
+  }
+  return { prefix, body: segments.slice(i) };
+}
+
 function textFromSegment(seg: MessageSegment): string {
   if (seg.type !== "text") return "";
   return seg.data.text ?? seg.data.content ?? "";
 }
 
-function shouldConvert(mode: OutboundMarkdownMode | undefined, bodyText: string): boolean {
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineMedia(value: string): boolean {
+  return value.startsWith("base64://")
+    || /^data:[^/]+\/[^;]+;base64,/i.test(value)
+    || value.startsWith("file://")
+    || (value.startsWith("/") && !isRemoteUrl(value));
+}
+
+/** QQ Markdown 图片语法：![说明 #宽 #高](公网 URL) */
+export function formatQqMarkdownImage(
+  url: string,
+  data: Record<string, unknown> = {},
+): string {
+  const width = typeof data.width === "number" && data.width > 0 ? data.width : 200;
+  const height = typeof data.height === "number" && data.height > 0 ? data.height : width;
+  const label = typeof data.name === "string" && data.name.trim() ? data.name.trim() : "图片";
+  return `![${label} #${width}px #${height}px](${url})`;
+}
+
+/** 将 image 段解析为 Markdown 可嵌入的 URL（https 或 data URI） */
+export function resolveImageMarkdownUrl(data: Record<string, unknown>): string | null {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = resolveMediaFile(data);
+
+  if (url && isRemoteUrl(url)) return url;
+  if (file && isRemoteUrl(file)) return file;
+
+  const inline = file ?? (url && isInlineMedia(url) ? url : undefined);
+  if (!inline) return null;
+
+  if (inline.startsWith("base64://")) {
+    return `data:image/png;base64,${inline.slice(9)}`;
+  }
+  if (/^data:[^/]+\/[^;]+;base64,/i.test(inline)) {
+    return inline;
+  }
+  return null;
+}
+
+export function isTextImageMixedBody(body: MessageSegment[]): boolean {
+  if (body.length === 0) return false;
+  if (body.some((seg) => !TEXT_IMAGE_MIX_TYPES.has(seg.type))) return false;
+  const hasImage = body.some((seg) => seg.type === "image");
+  const hasText = body.some((seg) => seg.type === "text" || seg.type === "at");
+  return hasImage && hasText;
+}
+
+/** 图文混排且含 base64/本地图（无法直接嵌入 Markdown 公网 URL） */
+export function isTextImageMixedWithInlineMedia(body: MessageSegment[]): boolean {
+  if (!isTextImageMixedBody(body)) return false;
+  return body.some((seg) => {
+    if (seg.type !== "image") return false;
+    const url = typeof seg.data.url === "string" ? seg.data.url : undefined;
+    const file = resolveMediaFile(seg.data);
+    if (url && isRemoteUrl(url)) return false;
+    if (file && isRemoteUrl(file)) return false;
+    return Boolean(resolveMediaFile(seg.data) || (url && isInlineMedia(url)));
+  });
+}
+
+function segmentToMarkdownPart(seg: MessageSegment): string {
+  if (seg.type === "text") return textFromSegment(seg);
+  if (seg.type === "at") return `<@${String(seg.data.user_id ?? "")}>`;
+  if (seg.type === "image") {
+    const src = resolveImageMarkdownUrl(seg.data);
+    return src ? formatQqMarkdownImage(src, seg.data) : "";
+  }
+  return "";
+}
+
+function shouldConvertTextOnly(mode: OutboundMarkdownMode | undefined, bodyText: string): boolean {
   if (mode === false) return false;
   if (mode === true) return bodyText.trim().length > 0;
   return MARKDOWN_HINT.test(bodyText);
 }
 
+function mergeTextImageToMarkdown(
+  prefix: MessageSegment[],
+  body: MessageSegment[],
+): SendContent | null {
+  if (body.some((seg) => seg.type === "image" && !resolveImageMarkdownUrl(seg.data))) {
+    return null;
+  }
+  const merged = body.map(segmentToMarkdownPart).join("");
+  if (!merged.trim()) return null;
+  return [...prefix, segment("markdown", { content: merged })];
+}
+
 /**
- * 出站归一化：保留 leading `reply`，将连续 text 合并为单条 markdown 段。
- * 含图片/文件等富媒体时原样返回，避免破坏分条发送。
+ * 出站归一化：保留 leading `reply`，将连续 text 或 text+image 合并为单条 markdown 段。
+ * 含内联 base64 图的图文混排须走 outbound-mixed-media（msg_type=7），此处不处理。
  */
 export function normalizeOutboundMarkdown(
   content: SendContent,
   mode: OutboundMarkdownMode | undefined = "auto",
 ): SendContent {
-  const segments = asSegments(content);
+  const segments = asOutboundSegments(content);
   if (segments.length === 0) return content;
 
-  const prefix: MessageSegment[] = [];
-  let i = 0;
-  while (i < segments.length && segments[i].type === "reply") {
-    prefix.push(segments[i]);
-    i++;
+  const { prefix, body } = splitReplyPrefix(segments);
+  if (body.length === 0) return content;
+  if (mode === false) return content;
+
+  if (body.some((seg) => BLOCKING_RICH_TYPES.has(seg.type))) {
+    return content;
   }
 
-  const body = segments.slice(i);
-  if (body.length === 0) return content;
+  if (body.some((seg) => seg.type === "markdown")) {
+    return content;
+  }
+
+  if (isTextImageMixedBody(body)) {
+    if (isTextImageMixedWithInlineMedia(body)) {
+      return content;
+    }
+    const mixed = mergeTextImageToMarkdown(prefix, body);
+    return mixed ?? content;
+  }
 
-  if (body.some((seg) => BODY_RICH_TYPES.has(seg.type))) {
+  if (body.some((seg) => seg.type === "image")) {
     return content;
   }
 
@@ -87,7 +197,7 @@ export function normalizeOutboundMarkdown(
       : textFromSegment(seg)))
     .join("");
 
-  if (!shouldConvert(mode, merged)) return content;
+  if (!shouldConvertTextOnly(mode, merged)) return content;
 
   return [...prefix, segment("markdown", { content: merged })];
 }

package/src/outbound-media.ts

@@ -19,7 +19,8 @@ function isInlineBase64(value: string): boolean {
   return value.startsWith("base64://") || /^data:[^/]+\/[^;]+;base64,/i.test(value);
 }
 
-function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+/** 解析 image/audio/video/file 段的本地或内联 payload（供 mixed-media 上传复用） */
+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;

package/src/outbound-mixed-media.ts

@@ -0,0 +1,101 @@
+/**
+ * QQ 群/私聊图文混排（msg_type=7）。
+ * 内联 base64 图无法作为 Markdown 公网 URL，须先上传 file_info 再与文本同条发送。
+ */
+import { randomInt } from "node:crypto";
+import type { MessageSegment, SendContent } from "zhin.js";
+import {
+  asOutboundSegments,
+  isTextImageMixedWithInlineMedia,
+  splitReplyPrefix,
+} from "./outbound-markdown.js";
+import { resolveMediaFile } from "./outbound-media.js";
+
+function textFromSegment(seg: MessageSegment): string {
+  if (seg.type !== "text") return "";
+  return seg.data.text ?? seg.data.content ?? "";
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function extractInlineFileData(source: string): string {
+  if (source.startsWith("base64://")) return source.slice(9);
+  if (/^data:[^/]+\/[^;]+;base64,/i.test(source)) {
+    return source.replace(/^data:[^/]+\/[^;]+;base64,/i, "");
+  }
+  return source;
+}
+
+export function buildQqImageUploadPayload(
+  imageSeg: MessageSegment,
+): { file_type: 1; url?: string; file_data?: string } {
+  const data = imageSeg.data;
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = resolveMediaFile(data);
+  const remote = [url, file].find((item) => item && isRemoteUrl(item));
+  if (remote) {
+    return { file_type: 1, url: remote };
+  }
+  const inline = file ?? url;
+  if (!inline) {
+    throw new Error("QQ 图文混排：图片段缺少 url/file/base64");
+  }
+  return { file_type: 1, file_data: extractInlineFileData(inline) };
+}
+
+export function buildTextImageMixedBodyText(body: MessageSegment[]): string {
+  return body
+    .map((seg) => {
+      if (seg.type === "text") return textFromSegment(seg);
+      if (seg.type === "at") return `<@${String(seg.data.user_id ?? "")}>`;
+      return "";
+    })
+    .join("");
+}
+
+export function firstImageSegment(body: MessageSegment[]): MessageSegment | undefined {
+  return body.find((seg) => seg.type === "image");
+}
+
+export function shouldSendTextImageMixedMedia(
+  content: SendContent,
+  mode: boolean | "auto" | undefined,
+): boolean {
+  if (mode === false) return false;
+  const { body } = splitReplyPrefix(asOutboundSegments(content));
+  return isTextImageMixedWithInlineMedia(body);
+}
+
+export interface QqMixedMediaMessagePayload {
+  msg_type: 7;
+  content: string;
+  media: { file_info: string };
+  msg_seq: number;
+  msg_id?: string;
+  event_id?: string;
+}
+
+export function buildMixedMediaMessagePayload(
+  content: SendContent,
+  fileInfo: string,
+): QqMixedMediaMessagePayload {
+  const segments = asOutboundSegments(content);
+  const { prefix, body } = splitReplyPrefix(segments);
+  const payload: QqMixedMediaMessagePayload = {
+    msg_type: 7,
+    content: buildTextImageMixedBodyText(body),
+    media: { file_info: fileInfo },
+    msg_seq: randomInt(1, 1_000_000),
+  };
+  const reply = prefix[prefix.length - 1];
+  if (reply?.type === "reply") {
+    if (typeof reply.data.event_id === "string") {
+      payload.event_id = reply.data.event_id;
+    } else if (reply.data.id != null) {
+      payload.msg_id = String(reply.data.id);
+    }
+  }
+  return payload;
+}

package/src/platform-permit.ts

@@ -12,8 +12,8 @@ export function platformPermit(perm: string): string {
 
 /** 官方频道工厂工具：映射到 guild 语义，不用 group_* */
 const FACTORY_PERM_MAP: Record<string, string> = {
-  group_admin: 'guild_admin',
-  group_owner: 'guild_owner',
+  scene_admin: 'guild_admin',
+  scene_owner: 'guild_owner',
 };
 
 export function qqGuildPermitResolver(logicalPerm: string): string {