@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/src/index.ts

@@ -1,188 +1,58 @@
-/**
- * QQ 官方适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-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";
-import {
+export {
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundText,
+  parseSendTarget,
+  resolveOutboundMessageId,
+  resolveQqConfig,
+  senderDisplayName,
+  type ParsedSendTarget,
+  type QqAdapterConfig,
+  type QqChannelKind,
+  type QqInboundMessage,
+  type QqWireSegment,
+  type ResolvedQqConfig,
+  type ResolvedQqHttpConfig,
+  type ResolvedQqWebsocketConfig,
+} from './protocol.js';
+
+export {
+  QqHttpEndpoint,
+  QqWebsocketEndpoint,
+  type CreateQqBot,
+  type CreateQqHttpBot,
+  type QqBotTransport,
+  type QqEndpointOptions,
+  type QqHttpBotTransport,
+  type QqHttpEndpointOptions,
+} from './endpoint.js';
+
+export {
+  registerQqWebhookRoutes,
+  handleQqWebhookRequest,
+  readRequestBodyText,
+  defaultCreateHttpBot,
+  type QqWebhookHandler,
+} from './webhook.js';
+
+export {
+  bindQqBotInboundEvents,
+  defaultCreateBot,
+  normalizeQqMessage,
+} from './ws.js';
+
+export {
+  getQqAgentDeps,
+  registerQqAgentEndpoint,
+  setQqAgentDeps,
+  type QqAgentDeps,
+  type QqAgentEndpoint,
+} from './qq-agent-deps.js';
+
+export {
+  checkQqPlatformPermit,
+  normalizeQqGuildSenderForPermit,
+  platformPermit,
   qqGuildPermitResolver,
   registerQqPlatformPermitChecker,
-} from "./platform-permit.js";
-import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-import { setQqAgentDeps } from "./qq-agent-deps.js";
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-      router: Router;
-    }
-  }
-}
-
-declare module "zhin.js" {
-  interface Adapters {
-    qq: QQAdapter;
-  }
-}
-
-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, onDispose } = plugin;
-
-useContext("router", (router: Router) => {
-  provide({
-    name: "qq",
-    description: "QQ Official Endpoint Adapter",
-    mounted: async (p: Plugin) => {
-      const adapter = new QQAdapter(p, router);
-      await adapter.start();
-      return adapter;
-    },
-    dispose: async (adapter: QQAdapter) => {
-      await adapter.stop();
-    },
-  });
-});
-
-useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerQqPlatformPermitChecker());
-  setQqAgentDeps({
-    getEndpoint: (endpointId) => {
-      const endpoint = qq.endpoints.get(endpointId);
-      if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
-      return endpoint;
-    },
-    getAdapter: () => qq,
-  });
-  const sceneTools = createSceneManagementTools(
-    qq as unknown as ISceneManagement,
-    'qq',
-    { permitResolver: qqGuildPermitResolver, registerChecker: false },
-  );
-  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-
-  return () => disposers.forEach(d => d());
-});
-
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "qq",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "QQ" },
-  });
-});
-
-useContext("router", "qq", (router: any, qq: QQAdapter) => {
-  router.get("/api/qq/endpoints", async (ctx: any) => {
-    try {
-      const endpoints = Array.from(qq.endpoints.values());
-      const result = await Promise.all(endpoints.map(async (endpoint) => {
-        try {
-          let guildCount = 0;
-          try { const guilds = await endpoint.getGuilds(); guildCount = guilds?.length || 0; } catch {}
-          return {
-            name: endpoint.$config.name,
-            connected: endpoint.$connected || false,
-            guildCount,
-            status: endpoint.$connected ? "online" : "offline",
-          };
-        } catch {
-          return { name: endpoint.$config.name, connected: false, guildCount: 0, status: "error" };
-        }
-      }));
-      ctx.body = { success: true, data: result };
-    } catch {
-      ctx.status = 500;
-      ctx.body = { success: false, error: "获取 Endpoint 数据失败" };
-    }
-  });
-
-  // Endpoint 连接/断开
-  router.post("/api/qq/endpoints/:name/connect", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (endpoint.$connected) { ctx.body = { success: true, message: "已经在线" }; return; }
-      await endpoint.$connect();
-      ctx.body = { success: true, message: "连接成功" };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "连接失败" };
-    }
-  });
-
-  router.post("/api/qq/endpoints/:name/disconnect", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.body = { success: true, message: "已经离线" }; return; }
-      await endpoint.$disconnect();
-      ctx.body = { success: true, message: "已断开" };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "断开失败" };
-    }
-  });
-
-  // 频道列表（QQ 官方 API 返回 guild_id/guild_name，归一化为控制台用的 id/name）
-  router.get("/api/qq/endpoints/:name/guilds", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Endpoint 未连接" }; return; }
-      const raw = await endpoint.getGuilds();
-      const guilds = (raw || []).map((g: any) => ({
-        id: g.guild_id ?? g.id,
-        name: g.guild_name ?? g.name,
-        icon: g.icon,
-        description: g.description,
-        memberCount: g.member_count,
-        ownerId: g.owner_id,
-        owner: g.owner,
-        joinTime: g.join_time,
-      }));
-      ctx.body = { success: true, data: guilds };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "获取频道失败" };
-    }
-  });
-
-  // 子频道列表（QQ 官方 API 返回 channel_id/channel_name，归一化为 id/name）
-  router.get("/api/qq/endpoints/:name/guilds/:guildId/channels", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Endpoint 未连接" }; return; }
-      const raw = await endpoint.getChannels(ctx.params.guildId);
-      const channels = (raw || []).map((ch: any) => ({
-        id: ch.channel_id ?? ch.id,
-        name: ch.channel_name ?? ch.name,
-        type: ch.type,
-        subType: ch.sub_type,
-        position: ch.position,
-        parentId: ch.parent_id,
-      }));
-      ctx.body = { success: true, data: channels };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "获取子频道失败" };
-    }
-  });
-});
-
-onDispose(() => {
-  disposeQqEndpointProvision();
-});
+} from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,7 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import { registerPlatformPermitChecker, type Message } from 'zhin.js';
+import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
 
 const ADAPTER = 'qq';
 

package/src/protocol.ts

@@ -0,0 +1,229 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { pickCredential } from '@zhin.js/adapter';
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+  readonly name?: string;
+  readonly appid?: string;
+  readonly secret?: string;
+  /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+  readonly mode?: 'websocket' | 'webhook' | 'middleware';
+  readonly sandbox?: boolean;
+  readonly intents?: readonly string[];
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+  readonly webhookPath?: string;
+  readonly port?: number;
+  readonly path?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly name?: string;
+    readonly appid?: string;
+    readonly secret?: string;
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+    readonly port?: number;
+    readonly path?: string;
+  }>;
+}
+
+export interface ResolvedQqWebsocketConfig {
+  readonly context: 'qq';
+  readonly mode: 'websocket';
+  readonly name: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly sandbox: boolean;
+  readonly intents?: readonly string[];
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+}
+
+export interface ResolvedQqHttpConfig {
+  readonly context: 'qq';
+  readonly mode: 'webhook' | 'middleware';
+  readonly name: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly webhookPath: string;
+  readonly sandbox: boolean;
+}
+
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+
+export interface QqInboundMessage {
+  readonly id: string;
+  readonly content: string;
+  readonly channelKind: QqChannelKind;
+  readonly channelId: string;
+  readonly authorId: string;
+  readonly authorName: string;
+  readonly authorRoles?: string[];
+  readonly timestamp: number;
+  readonly guildId?: string;
+  readonly rawMessage?: string;
+  /**
+   * 入站即 @ 机器人（AT_MESSAGE_CREATE 的 mentions[].bot，或群 GROUP_AT_MESSAGE_CREATE
+   * 事件本身仅 @ 时下发）。新 Runtime 纯文本 content 需经 metadata 传递。
+   */
+  readonly mentioned?: boolean;
+}
+
+export interface QqWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface ParsedSendTarget {
+  readonly kind: QqChannelKind;
+  readonly id: string;
+}
+
+export function resolveQqConfig(config: QqAdapterConfig = {}): ResolvedQqConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+  const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+  const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+  if (!appid || !secret) {
+    throw new TypeError(
+      'QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)',
+    );
+  }
+  const name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || process.env.QQ_BOT_NAME
+    || 'qq-bot';
+  const mode = config.mode ?? entry?.mode ?? 'websocket';
+
+  if (mode === 'webhook' || mode === 'middleware') {
+    const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+    const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+    return {
+      context: 'qq',
+      mode,
+      name,
+      appid,
+      secret,
+      webhookPath,
+      sandbox: config.sandbox === true || entry?.sandbox === true,
+    };
+  }
+
+  return {
+    context: 'qq',
+    mode: 'websocket',
+    name,
+    appid,
+    secret,
+    sandbox: config.sandbox === true || entry?.sandbox === true,
+    intents: config.intents ?? entry?.intents,
+    accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+    gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+  };
+}
+
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export function formatInboundTarget(msg: QqInboundMessage): string {
+  return `${msg.channelKind}:${msg.channelId}`;
+}
+
+export function parseSendTarget(target: string): ParsedSendTarget {
+  const sep = target.indexOf(':');
+  if (sep <= 0) {
+    return { kind: 'private', id: target };
+  }
+  const head = target.slice(0, sep);
+  const rest = target.slice(sep + 1);
+  if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
+    return { kind: head, id: rest };
+  }
+  return { kind: 'private', id: target };
+}
+
+export function senderDisplayName(msg: QqInboundMessage): string {
+  return msg.authorName || msg.authorId;
+}
+
+export function formatInboundContent(msg: QqInboundMessage): string {
+  const text = (msg.content || msg.rawMessage || '').trim();
+  return text || '(Empty message)';
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload: unknown): string {
+  if (typeof payload === 'string') return payload;
+
+  const segments: Array<string | QqWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | QqWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as QqWireSegment]
+      : [];
+
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  return segments
+    .map((item) => {
+      if (typeof item === 'string') return item;
+      const data = item.data ?? {};
+      switch (item.type) {
+        case 'text':
+          return String(data.text ?? data.content ?? '');
+        case 'at': {
+          const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+          return id ? `<@!${id}>` : '';
+        }
+        case 'image':
+          return String(data.url || data.file || '');
+        case 'reply':
+          return '';
+        default:
+          return data.text != null ? String(data.text) : '';
+      }
+    })
+    .filter(Boolean)
+    .join('');
+}
+
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result: unknown): string {
+  if (!result || typeof result !== 'object') {
+    throw new Error('QQ 发送消息失败：响应为空');
+  }
+  const row = result as Record<string, unknown>;
+  const nested = row.data && typeof row.data === 'object'
+    ? row.data as Record<string, unknown>
+    : undefined;
+  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
+  const id = row.id ?? row.message_id ?? audit?.audit_id;
+  if (id == null || id === '') {
+    const code = row.code;
+    const msg = row.message;
+    throw new Error(
+      code != null
+        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+        : 'QQ 发送消息失败：响应缺少消息 ID',
+    );
+  }
+  return String(id);
+}

package/src/qq-agent-deps.ts

@@ -1,23 +1,60 @@
 /**
- * Shared runtime deps for qq agent/ authoring tools.
- * Set once from plugin index during init — never call getPlugin() from tool execute.
+ * Agent tool deps for qq.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
  */
-import type { QQAdapter } from './adapter.js';
-import type { QQEndpoint } from './endpoint.js';
-import type { ReceiverMode } from './types.js';
+
+export interface QqAgentEndpoint {
+  getGuilds(): Promise<unknown[]>;
+  getChannels(guildId: string): Promise<unknown[]>;
+  getChannelInfo(channelId: string): Promise<unknown>;
+  getGuildMember(guildId: string, userId: string): Promise<unknown>;
+  getGuildRoles(guildId: string): Promise<unknown[]>;
+  createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+  addMemberRole(
+    guildId: string,
+    channelId: string,
+    userId: string,
+    roleId: string,
+  ): Promise<boolean>;
+  removeMemberRole(
+    guildId: string,
+    channelId: string,
+    userId: string,
+    roleId: string,
+  ): Promise<boolean>;
+}
 
 export interface QqAgentDeps {
-  getEndpoint: (endpointId: string) => QQEndpoint<ReceiverMode>;
-  getAdapter: () => QQAdapter;
+  getEndpoint: (endpointId: string) => QqAgentEndpoint;
 }
 
-let _deps: QqAgentDeps | null = null;
+const endpoints = new Map<string, QqAgentEndpoint>();
+let override: QqAgentDeps | null = null;
+
+export function registerQqAgentEndpoint(
+  endpointId: string,
+  endpoint: QqAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
 
-export function setQqAgentDeps(deps: QqAgentDeps): void {
-  _deps = deps;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setQqAgentDeps(deps: QqAgentDeps | null): void {
+  override = deps;
 }
 
 export function getQqAgentDeps(): QqAgentDeps {
-  if (!_deps) throw new Error('qq agent deps not initialized');
-  return _deps;
+  if (override) return override;
+  return {
+    getEndpoint(endpointId: string): QqAgentEndpoint {
+      const registered = endpoints.get(endpointId);
+      if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+      return registered;
+    },
+  };
 }

package/src/qq-bind-persist.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { runtimeCwd } from 'zhin.js';
 
 export interface QqCredentialEnvKeys {
   appidKey: string;
@@ -9,7 +8,7 @@ export interface QqCredentialEnvKeys {
   secretRef: string;
 }
 
-/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MOCK_QQ_BOT_APPID`） */
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
 export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys {
   const slug = endpointName.replace(/[^a-zA-Z0-9_]/g, '_').toUpperCase();
   const appidKey = `QQ_${slug}_APPID`;
@@ -22,9 +21,10 @@ export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvK
   };
 }
 
-function resolveProjectRoot(): string {
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export function resolveProjectRoot(): string {
   const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
-  return path.resolve(envRoot || runtimeCwd());
+  return path.resolve(envRoot || process.cwd());
 }
 
 function escapeRegExp(text: string): string {