@zhin.js/adapter-qq 5.0.0 → 5.0.1

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 {

package/src/qq-bind-api.ts

@@ -102,6 +102,26 @@ export interface PollBindResultOk {
   status: BindStatus;
   botAppId: string;
   botEncryptSecret: string;
+  /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+  userOpenId: string;
+}
+
+export function parsePollBindResultData(data: {
+  status?: number;
+  bot_appid?: string | number;
+  bot_encrypt_secret?: string;
+  user_openid?: string;
+  userOpenid?: string;
+  openid?: string;
+} | undefined): PollBindResultOk {
+  return {
+    status: (data?.status ?? BindStatus.NONE) as BindStatus,
+    botAppId: String(data?.bot_appid ?? ''),
+    botEncryptSecret: data?.bot_encrypt_secret ?? '',
+    userOpenId: String(
+      data?.user_openid ?? data?.userOpenid ?? data?.openid ?? '',
+    ),
+  };
 }
 
 export async function pollBindResult(
@@ -114,13 +134,12 @@ export async function pollBindResult(
     status?: number;
     bot_appid?: string | number;
     bot_encrypt_secret?: string;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
   }>(url, { task_id: taskId }, timeoutMs);
   if (res.retcode !== 0) {
     throw new Error(res.msg ?? 'poll_bind_result failed');
   }
-  return {
-    status: (res.data?.status ?? BindStatus.NONE) as BindStatus,
-    botAppId: String(res.data?.bot_appid ?? ''),
-    botEncryptSecret: res.data?.bot_encrypt_secret ?? '',
-  };
+  return parsePollBindResultData(res.data);
 }

package/src/qq-bind-flow.ts

@@ -14,6 +14,7 @@ const POLL_INTERVAL_MS = 2000;
 export interface QqBindCredentials {
   appId: string;
   appSecret: string;
+  userOpenId?: string;
 }
 
 export interface QqBindCallbacks {
@@ -50,7 +51,7 @@ async function pollUntilResult(
   taskId: string,
   key: string,
   signal?: AbortSignal,
-): Promise<{ outcome: 'scanned'; appId: string; appSecret: string } | { outcome: 'expired' }> {
+): Promise<{ outcome: 'scanned'; appId: string; appSecret: string; userOpenId: string } | { outcome: 'expired' }> {
   while (!signal?.aborted) {
     let result;
     try {
@@ -61,7 +62,12 @@ async function pollUntilResult(
     }
     if (result.status === BindStatus.COMPLETED) {
       const appSecret = decryptSecret(result.botEncryptSecret, key);
-      return { outcome: 'scanned', appId: result.botAppId, appSecret };
+      return {
+        outcome: 'scanned',
+        appId: result.botAppId,
+        appSecret,
+        userOpenId: result.userOpenId,
+      };
     }
     if (result.status === BindStatus.EXPIRED) {
       return { outcome: 'expired' };
@@ -101,7 +107,11 @@ export function startQqBindFlow(
       await callbacks.onQrDisplayed?.(connectUrl);
       const pollResult = await pollUntilResult(task.taskId, task.key, signal);
       if (pollResult.outcome === 'scanned') {
-        callbacks.onSuccess([{ appId: pollResult.appId, appSecret: pollResult.appSecret }]);
+        callbacks.onSuccess([{
+          appId: pollResult.appId,
+          appSecret: pollResult.appSecret,
+          userOpenId: pollResult.userOpenId || undefined,
+        }]);
         return;
       }
       await callbacks.onQrExpired?.();

package/src/qq-bind-persist.ts

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimeCwd } from 'zhin.js';
+
+export interface QqCredentialEnvKeys {
+  appidKey: string;
+  secretKey: string;
+  appidRef: string;
+  secretRef: string;
+}
+
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MOCK_QQ_BOT_APPID`） */
+export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys {
+  const slug = endpointName.replace(/[^a-zA-Z0-9_]/g, '_').toUpperCase();
+  const appidKey = `QQ_${slug}_APPID`;
+  const secretKey = `QQ_${slug}_SECRET`;
+  return {
+    appidKey,
+    secretKey,
+    appidRef: `\${${appidKey}}`,
+    secretRef: `\${${secretKey}}`,
+  };
+}
+
+function resolveProjectRoot(): string {
+  const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+  return path.resolve(envRoot || runtimeCwd());
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function upsertEnvLine(content: string, key: string, value: string): string {
+  const lineRe = new RegExp(`^${escapeRegExp(key)}\\s*=.*$`, 'm');
+  const newLine = `${key}=${value}`;
+  if (lineRe.test(content)) {
+    return content.replace(lineRe, newLine);
+  }
+  const trimmed = content.replace(/\s*$/, '');
+  if (trimmed.length === 0) {
+    return `${newLine}\n`;
+  }
+  return `${trimmed}\n${newLine}\n`;
+}
+
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(
+  endpointName: string,
+  appId: string,
+  appSecret: string,
+  projectRoot?: string,
+): QqCredentialEnvKeys {
+  const keys = buildQqCredentialEnvKeys(endpointName);
+  const root = projectRoot ?? resolveProjectRoot();
+  const envPath = path.join(root, '.env');
+  let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
+
+  const entries: Record<string, string> = {
+    [keys.appidKey]: appId,
+    [keys.secretKey]: appSecret,
+  };
+
+  for (const [key, value] of Object.entries(entries)) {
+    content = upsertEnvLine(content, key, value);
+    process.env[key] = value;
+  }
+
+  fs.writeFileSync(envPath, content);
+  return keys;
+}

package/src/qq-endpoint-manager.ts

@@ -7,6 +7,7 @@ import type { QQAdapter } from './adapter.js';
 import type { QQEndpointConfig, ReceiverMode } from './types.js';
 import { ReceiverMode as QQReceiverMode } from './types.js';
 import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
 
 const DEFAULT_INTENTS = [
   'GUILDS',
@@ -20,10 +21,19 @@ const DEFAULT_INTENTS = [
   'PUBLIC_GUILD_MESSAGES',
 ] as const;
 
+function clonePlainConfig<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
 function resolveQqEndpointTemplate(root: ProvisionContext['root']): Partial<QQEndpointConfig<ReceiverMode>> {
-  const configService = root.inject('config') as { getPrimary?: () => { endpoints?: Array<Record<string, unknown>> } } | undefined;
-  const doc = configService?.getPrimary?.();
-  const existing = doc?.endpoints?.find((e) => e.context === 'qq');
+  const configService = root.inject('config') as {
+    getRaw?: (f: string) => { endpoints?: Array<Record<string, unknown>> };
+    primaryFile?: string;
+  } | undefined;
+  const raw = configService?.primaryFile && configService.getRaw
+    ? configService.getRaw(configService.primaryFile)
+    : undefined;
+  const existing = raw?.endpoints?.find((e) => e.context === 'qq');
   if (!existing) {
     return {
       mode: QQReceiverMode.WEBSOCKET,
@@ -34,7 +44,44 @@ function resolveQqEndpointTemplate(root: ProvisionContext['root']): Partial<QQEn
     };
   }
   const { name: _n, appid: _a, secret: _s, context: _c, ...rest } = existing;
-  return rest as Partial<QQEndpointConfig<ReceiverMode>>;
+  return clonePlainConfig(rest) as Partial<QQEndpointConfig<ReceiverMode>>;
+}
+
+function resolveBindOperatorId(
+  userOpenId: string | undefined,
+  ctx: ProvisionContext,
+): string {
+  const fromApi = userOpenId?.trim();
+  if (fromApi) return fromApi;
+  return ctx.message.$sender?.id?.trim() ?? '';
+}
+
+function applyBindOwnership(
+  template: Partial<QQEndpointConfig<ReceiverMode>>,
+  operatorId: string,
+): Partial<QQEndpointConfig<ReceiverMode>> {
+  const { master: _m, aiAccess, ...rest } = template as Record<string, unknown>;
+  if (!operatorId) {
+    return rest as Partial<QQEndpointConfig<ReceiverMode>>;
+  }
+  const prior = aiAccess as {
+    mode?: string;
+    groups?: string[];
+    denyMessage?: string;
+  } | undefined;
+  return {
+    ...rest,
+    master: operatorId,
+    aiAccess: {
+      mode: prior?.mode ?? 'whitelist',
+      users: [operatorId],
+      groups: Array.isArray(prior?.groups) ? [...prior.groups] : [],
+      denyMessage:
+        typeof prior?.denyMessage === 'string'
+          ? prior.denyMessage
+          : '当前用户尚未开放 AI 功能，请联系开启。',
+    },
+  } as Partial<QQEndpointConfig<ReceiverMode>>;
 }
 
 function readQqConfigs(root: ProvisionContext['root']): EndpointConfigRecord[] {
@@ -80,7 +127,7 @@ export class QqEndpointManager implements EndpointManager {
       const stopFlow = startQqBindFlow(
         {
           onQrDisplayed: async (url) => {
-            await ctx.onStatusUpdate('请用手机 QQ 扫描下方二维码完成机器人绑定（source=zhin）。', {
+            await ctx.onStatusUpdate('请用手机 QQ 扫描二维码完成机器人绑定。', {
               qrcode: url,
             });
           },
@@ -89,15 +136,21 @@ export class QqEndpointManager implements EndpointManager {
           },
           onSuccess: async (credentials) => {
             activeStopFlow = null;
-            const [{ appId, appSecret }] = credentials;
+            const [{ appId, appSecret, userOpenId }] = credentials;
             const name = endpointName?.trim() || appId;
+            await ctx.onStatusUpdate(
+              '凭据绑定成功，正在写入配置…',
+            );
+            const envKeys = persistQqCredentialsToEnv(name, appId, appSecret);
             const template = resolveQqEndpointTemplate(ctx.root);
+            const operatorId = resolveBindOperatorId(userOpenId, ctx);
+            const owned = applyBindOwnership(template, operatorId);
             resolve({
               context: 'qq',
               name,
-              appid: appId,
-              secret: appSecret,
-              ...template,
+              appid: envKeys.appidRef,
+              secret: envKeys.secretRef,
+              ...owned,
             } as EndpointConfigRecord);
           },
           onFailure: async (error) => {

package/src/segment-mapper.ts

@@ -0,0 +1 @@
+export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';

package/src/types.ts

@@ -36,6 +36,13 @@ export type QQEndpointConfig<
    * - `false`：保持纯文本
    */
   outboundMarkdown?: boolean | "auto";
+  /** 本 Endpoint AI 访问控制（见 docs/advanced/content-moderation.md） */
+  aiAccess?: {
+    mode?: 'open' | 'closed' | 'whitelist';
+    users?: string[];
+    groups?: string[];
+    denyMessage?: string;
+  };
 };
 
 export interface QQEndpoint<