skyloom 1.20.0 → 1.22.0

package/dist/gateway/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Channel gateway contract — the minimal, channel-agnostic interface every
+ * messaging integration (Feishu / WeCom / QQ / …) implements.
+ *
+ * Distilled from OpenClaw's channel architecture (which spans ~250 files per
+ * channel) down to the essence: a channel receives an inbound webhook, the
+ * gateway normalizes it to an InboundMessage, routes it to an agent, and the
+ * channel sends the reply back out. Signature verification and the platform's
+ * URL-verification handshake live behind `handleWebhook`, so the gateway core
+ * stays platform-neutral.
+ */
+import type { IncomingHttpHeaders } from 'http';
+/** A normalized inbound message from any channel. */
+export interface InboundMessage {
+    /** Channel id, e.g. 'feishu'. */
+    channel: string;
+    /** Stable conversation/session key (chat id or user id) for memory routing. */
+    conversationId: string;
+    /** Platform user id of the sender. */
+    userId: string;
+    /** Plain text the user sent (media/stripped to text where possible). */
+    text: string;
+    /** Where to send the reply (channel-specific opaque target). */
+    replyTo: ReplyTarget;
+    /** Media attachments on this message (image / audio / file / …). */
+    media?: MediaAttachment[];
+    /** Raw event for adapters that need more than the normalized fields. */
+    raw?: unknown;
+}
+/** A non-text attachment, normalized across channels. */
+export interface MediaAttachment {
+    kind: 'image' | 'audio' | 'video' | 'file' | 'sticker' | 'other';
+    /** Channel-specific id/key used to fetch the binary (image_key, media_id, url…). */
+    ref?: string;
+    /** Original filename, when the platform provides one. */
+    filename?: string;
+    /** MIME type, when known. */
+    mimeType?: string;
+    /** Direct URL, when the platform provides one. */
+    url?: string;
+}
+/** Render a media list into a compact, model-readable description line. */
+export declare function describeMedia(media: MediaAttachment[] | undefined): string;
+/** Opaque, channel-specific destination for an outbound reply. */
+export interface ReplyTarget {
+    channel: string;
+    [key: string]: unknown;
+}
+/**
+ * The result of an adapter handling a raw webhook request. Exactly one of:
+ *  - `response`: reply immediately to the HTTP request (URL verification
+ *    challenge, ack, or signature failure) and do NOT route to an agent.
+ *  - `message`: a normalized inbound message to route to an agent. `response`
+ *    may also be set to ack the webhook synchronously (most platforms require a
+ *    fast 200) while the agent reply is delivered asynchronously via `send`.
+ *  - neither: nothing to do (duplicate/ignored event); gateway returns 200.
+ */
+export interface WebhookOutcome {
+    response?: HttpResponse;
+    message?: InboundMessage;
+}
+export interface HttpResponse {
+    status: number;
+    body?: string;
+    contentType?: string;
+}
+/** The raw HTTP request passed to an adapter's webhook handler. */
+export interface RawRequest {
+    method: string;
+    headers: IncomingHttpHeaders;
+    query: URLSearchParams;
+    body: Buffer;
+}
+/** A channel integration. Constructed from its config block by a factory. */
+export interface ChannelAdapter {
+    /** Channel id (matches the /webhook/<id> route and config key). */
+    readonly id: string;
+    /** Human label for logs/status. */
+    readonly name: string;
+    /** Default agent to route this channel's messages to (config override wins). */
+    readonly defaultAgent?: string;
+    /** Optional one-time setup (token prefetch, websocket connect, …). */
+    start?(): Promise<void>;
+    /** Optional teardown on gateway shutdown. */
+    stop?(): Promise<void>;
+    /**
+     * Handle a raw webhook request: verify signature, answer the platform's
+     * URL-verification handshake, decrypt if needed, and either return an
+     * immediate HTTP response and/or a normalized message to route.
+     */
+    handleWebhook(req: RawRequest): Promise<WebhookOutcome>;
+    /** Send a text reply back to the channel. */
+    send(target: ReplyTarget, text: string): Promise<void>;
+    /**
+     * Optional streaming reply: consume the agent's text chunks and render them
+     * progressively (e.g. a Feishu card patched as text accumulates). When an
+     * adapter implements this, the gateway prefers it over `send`. Implementations
+     * should throttle their own updates and tolerate an empty/aborted stream.
+     */
+    sendStreaming?(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<void>;
+}
+/** Factory signature: build an adapter from its config block (or null if disabled/misconfigured). */
+export type ChannelFactory = (cfg: any, env: NodeJS.ProcessEnv) => ChannelAdapter | null;
+//# sourceMappingURL=types.d.ts.map

package/dist/gateway/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gateway/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAEhD,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,wEAAwE;IACxE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACjE,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,SAAS,GAAG,MAAM,CAQ1E;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,sEAAsE;IACtE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,6CAA6C;IAC7C,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAExD,6CAA6C;IAC7C,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,aAAa,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,GAAG,IAAI,CAAC"}

package/dist/gateway/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Channel gateway contract — the minimal, channel-agnostic interface every
+ * messaging integration (Feishu / WeCom / QQ / …) implements.
+ *
+ * Distilled from OpenClaw's channel architecture (which spans ~250 files per
+ * channel) down to the essence: a channel receives an inbound webhook, the
+ * gateway normalizes it to an InboundMessage, routes it to an agent, and the
+ * channel sends the reply back out. Signature verification and the platform's
+ * URL-verification handshake live behind `handleWebhook`, so the gateway core
+ * stays platform-neutral.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeMedia = describeMedia;
+/** Render a media list into a compact, model-readable description line. */
+function describeMedia(media) {
+    if (!media || media.length === 0)
+        return '';
+    const parts = media.map((m) => {
+        const label = m.filename || m.ref || m.url || '';
+        const tag = label ? `${m.kind}: ${label}` : m.kind;
+        return `[${tag}]`;
+    });
+    return parts.join(' ');
+}
+//# sourceMappingURL=types.js.map

package/dist/gateway/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/gateway/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAoCH,sCAQC;AATD,2EAA2E;AAC3E,SAAgB,aAAa,CAAC,KAAoC;IAChE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACnD,OAAO,IAAI,GAAG,GAAG,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skyloom",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
   "preferGlobal": true,
   "type": "commonjs",

package/src/cli/main.ts

@@ -35,6 +35,9 @@ program.command("task").argument("[goal]", "task goal")
 program.command("web").option("-p,--port <p>", "port", "7777")
   .action((o: { port?: string }) => { import("../web/server").then(m => m.startWebServer(parseInt(o.port || "7777"))); });
 program.command("mcp").action(() => { import("../core/mcp_server").then(m => m.startMCPServer()); });
+program.command("gateway").description("Run the channel gateway (Feishu / WeCom / QQ)")
+  .option("-p,--port <p>", "port", "8848")
+  .action((o: { port?: string }) => { import("../gateway/gateway").then(m => m.startGateway({ port: parseInt(o.port || "8848") })); });
 program.command("config").action(() => { const c = loadConfig(); process.stdout.write(chalk.cyan("\nConfig: ") + USER_CONFIG_DIR + "\n"); for (const [n, a] of Object.entries(c.agents || {})) process.stdout.write(`  ${chalk.bold(n)}: ${(a as any).model || "default"}\n`); });
 program.command("init").action(() => { if (!fs.existsSync(USER_CONFIG_DIR)) fs.mkdirSync(USER_CONFIG_DIR, { recursive: true }); process.stdout.write(chalk.green("✓ ") + USER_CONFIG_DIR + "\n"); });
 program.command("apikey").description("Manage API keys (persisted to ~/.skyloom/config.yaml)")

package/src/gateway/channels/feishu.ts

@@ -0,0 +1,242 @@
+/**
+ * Feishu / Lark channel adapter.
+ *
+ * Inbound: the event-subscription webhook (v2 schema). Handles the
+ * url_verification challenge, optional AES-encrypted payloads, and the optional
+ * verification-token check, then normalizes im.message.receive_v1 events.
+ *
+ * Outbound: obtains a tenant_access_token (cached) and replies via the
+ * im/v1/messages API (text by default).
+ *
+ * Config (channels.feishu): { appId, appSecret, encryptKey?, verificationToken?,
+ *   domain?: 'feishu'|'lark', agent? }. Env fallback: FEISHU_APP_ID,
+ *   FEISHU_APP_SECRET, FEISHU_ENCRYPT_KEY, FEISHU_VERIFICATION_TOKEN.
+ */
+
+import * as crypto from 'crypto';
+import { getLogger } from '../../core/logger';
+import { resolveSecret, postJson, TokenCache } from '../helpers';
+import type { ChannelAdapter, MediaAttachment, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+
+const log = getLogger('channel-feishu');
+
+/** Decrypt a Feishu AES-256-CBC encrypted event body. */
+export function decryptFeishu(encrypt: string, encryptKey: string): string {
+  const key = crypto.createHash('sha256').update(encryptKey).digest();
+  const data = Buffer.from(encrypt, 'base64');
+  const iv = data.subarray(0, 16);
+  const ciphertext = data.subarray(16);
+  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  decipher.setAutoPadding(false);
+  let out = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  // PKCS#7 unpad
+  const pad = out[out.length - 1];
+  if (pad > 0 && pad <= 16) out = out.subarray(0, out.length - pad);
+  return out.toString('utf8');
+}
+
+export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapter | null {
+  const appId = resolveSecret(cfg.appId, env, 'FEISHU_APP_ID');
+  const appSecret = resolveSecret(cfg.appSecret, env, 'FEISHU_APP_SECRET');
+  if (!appId || !appSecret) return null; // not configured
+
+  const encryptKey = resolveSecret(cfg.encryptKey, env, 'FEISHU_ENCRYPT_KEY');
+  const verificationToken = resolveSecret(cfg.verificationToken, env, 'FEISHU_VERIFICATION_TOKEN');
+  const base = cfg.domain === 'lark' ? 'https://open.larksuite.com' : 'https://open.feishu.cn';
+  // 'card' replies render as an interactive card (supports streaming patches);
+  // 'raw' forces plain text; 'auto' (default) uses a card so streaming works.
+  const renderMode: 'auto' | 'raw' | 'card' = cfg.renderMode || 'auto';
+  const useCard = renderMode === 'card' || renderMode === 'auto';
+
+  const tokenCache = new TokenCache(async () => {
+    const data = await postJson(`${base}/open-apis/auth/v3/tenant_access_token/internal`, {
+      app_id: appId, app_secret: appSecret,
+    });
+    if (data.code !== 0) throw new Error(`feishu token error ${data.code}: ${data.msg}`);
+    return { token: data.tenant_access_token, expiresInSec: data.expire ?? 7200 };
+  });
+
+  const authHeader = async () => ({ Authorization: `Bearer ${await tokenCache.get()}` });
+  const onTokenError = (code: number) => { if (code === 99991663 || code === 99991661) tokenCache.invalidate(); };
+
+  /** A minimal interactive card carrying a single markdown body. */
+  const cardContent = (text: string): string => JSON.stringify({
+    config: { wide_screen_mode: true, update_multi: true },
+    elements: [{ tag: 'markdown', content: text || ' ' }],
+  });
+
+  /** Create a card message in a chat; returns its message_id for later patches. */
+  const createCard = async (chatId: string, text: string): Promise<string | null> => {
+    const data = await postJson(
+      `${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+      { receive_id: chatId, msg_type: 'interactive', content: cardContent(text) },
+      { headers: await authHeader() },
+    );
+    if (data.code !== 0) { onTokenError(data.code); throw new Error(`feishu card create ${data.code}: ${data.msg}`); }
+    return data.data?.message_id || null;
+  };
+
+  /** Patch an existing card message with new content. */
+  const patchCard = async (messageId: string, text: string): Promise<void> => {
+    const data = await postJson(
+      `${base}/open-apis/im/v1/messages/${messageId}`,
+      { content: cardContent(text) },
+      { headers: await authHeader() },
+    ).catch((e) => ({ code: -1, msg: String(e) }));
+    if (data && data.code !== 0) onTokenError(data.code);
+  };
+
+  // De-dupe redelivered events (Feishu retries on slow ack).
+  const seen = new Set<string>();
+  const remember = (id: string): boolean => {
+    if (!id) return false;
+    if (seen.has(id)) return true;
+    seen.add(id);
+    if (seen.size > 2000) seen.clear();
+    return false;
+  };
+
+  return {
+    id: 'feishu',
+    name: 'Feishu/Lark',
+    defaultAgent: cfg.agent || 'fair',
+
+    async handleWebhook(req: RawRequest): Promise<WebhookOutcome> {
+      let payload: any;
+      try { payload = JSON.parse(req.body.toString('utf8') || '{}'); } catch { return { response: { status: 400, body: 'bad json' } }; }
+
+      // Encrypted transport: { encrypt: "..." } → decrypt to the real payload.
+      if (payload.encrypt) {
+        if (!encryptKey) return { response: { status: 400, body: 'encrypt key not configured' } };
+        try { payload = JSON.parse(decryptFeishu(payload.encrypt, encryptKey)); }
+        catch (e) { log.warn('feishu_decrypt_failed', { error: String(e) }); return { response: { status: 400, body: 'decrypt failed' } }; }
+      }
+
+      // URL verification handshake.
+      if (payload.type === 'url_verification') {
+        if (verificationToken && payload.token && payload.token !== verificationToken) {
+          return { response: { status: 403, body: 'bad token' } };
+        }
+        return { response: { status: 200, contentType: 'application/json', body: JSON.stringify({ challenge: payload.challenge }) } };
+      }
+
+      // Verification token check (v2 puts it in header.token).
+      const token = payload.header?.token ?? payload.token;
+      if (verificationToken && token && token !== verificationToken) {
+        return { response: { status: 403, body: 'bad token' } };
+      }
+
+      const eventId = payload.header?.event_id;
+      if (remember(eventId)) return {}; // duplicate redelivery
+
+      const eventType = payload.header?.event_type ?? payload.event?.type;
+      if (eventType !== 'im.message.receive_v1') return {}; // only handle message receipts
+
+      const message = payload.event?.message;
+      if (!message) return {};
+      const chatId = message.chat_id as string;
+      const msgType = message.message_type as string;
+      let text = '';
+      const media: MediaAttachment[] = [];
+      let content: any = {};
+      try { content = JSON.parse(message.content || '{}'); } catch { /* ignore */ }
+      switch (msgType) {
+        case 'text':
+          text = (content.text || '').replace(/@_user_\d+/g, '').trim(); // strip @mentions
+          break;
+        case 'image':
+          media.push({ kind: 'image', ref: content.image_key });
+          break;
+        case 'audio':
+          media.push({ kind: 'audio', ref: content.file_key });
+          break;
+        case 'media': // short video
+          media.push({ kind: 'video', ref: content.file_key, filename: content.file_name });
+          break;
+        case 'file':
+          media.push({ kind: 'file', ref: content.file_key, filename: content.file_name });
+          break;
+        case 'sticker':
+          media.push({ kind: 'sticker', ref: content.file_key });
+          break;
+        case 'post': { // rich text: pull plain text + embedded images
+          const blocks = content?.content;
+          if (Array.isArray(blocks)) {
+            for (const row of blocks) {
+              for (const el of row || []) {
+                if (el?.tag === 'text' && el.text) text += el.text;
+                else if (el?.tag === 'a' && el.text) text += el.text;
+                else if (el?.tag === 'img' && el.image_key) media.push({ kind: 'image', ref: el.image_key });
+              }
+              text += '\n';
+            }
+          }
+          text = text.trim();
+          break;
+        }
+        default:
+          text = `[${msgType} 消息]`;
+      }
+      const senderId = payload.event?.sender?.sender_id?.open_id || payload.event?.sender?.sender_id?.user_id || 'unknown';
+
+      return {
+        message: {
+          channel: 'feishu',
+          conversationId: chatId || senderId,
+          userId: senderId,
+          text,
+          media: media.length ? media : undefined,
+          replyTo: { channel: 'feishu', chatId },
+          raw: payload,
+        },
+      };
+    },
+
+    async send(target: ReplyTarget, text: string): Promise<void> {
+      const chatId = target.chatId as string;
+      if (!chatId) return;
+      if (useCard) { await createCard(chatId, text); return; }
+      const data = await postJson(
+        `${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+        { receive_id: chatId, msg_type: 'text', content: JSON.stringify({ text }) },
+        { headers: await authHeader() },
+      );
+      if (data.code !== 0) { onTokenError(data.code); throw new Error(`feishu send error ${data.code}: ${data.msg}`); }
+    },
+
+    // Streaming reply: post a placeholder card, then patch it as text arrives —
+    // throttled (≥600ms apart) to stay well under Feishu's update rate limit.
+    async sendStreaming(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<void> {
+      const chatId = target.chatId as string;
+      if (!chatId) return;
+      if (!useCard) { // plain-text mode can't patch; collect then send once
+        let all = '';
+        for await (const c of chunks) all += c;
+        await this.send(target, all.trim() || '(无回复)');
+        return;
+      }
+      let messageId: string | null = null;
+      let acc = '';
+      let lastPatch = 0;
+      let dirty = false;
+      const MIN_INTERVAL = 600;
+      try {
+        messageId = await createCard(chatId, '思考中…');
+      } catch (e) { log.warn('feishu_card_create_failed', { error: String(e) }); return; }
+      if (!messageId) return;
+
+      for await (const chunk of chunks) {
+        acc += chunk;
+        dirty = true;
+        const now = Date.now();
+        if (now - lastPatch >= MIN_INTERVAL) {
+          lastPatch = now;
+          dirty = false;
+          await patchCard(messageId, acc);
+        }
+      }
+      // Final flush so the last tokens always land.
+      if (dirty || acc) await patchCard(messageId, acc.trim() || '(无回复)');
+    },
+  };
+}

package/src/gateway/channels/qq.ts

@@ -0,0 +1,151 @@
+/**
+ * QQ official-bot channel adapter (webhook mode, QQ 频道/群 机器人).
+ *
+ * Auth/crypto: QQ uses Ed25519. The signing seed is the bot secret repeated to
+ * 32 bytes. Two webhook concerns:
+ *   - validation (op 13): the platform sends { d: { plain_token, event_ts } };
+ *     we reply { plain_token, signature } where signature = ed25519(event_ts +
+ *     plain_token).
+ *   - event signature: each push carries X-Signature-Ed25519 (hex) and
+ *     X-Signature-Timestamp; verify ed25519 over (timestamp + body).
+ *
+ * Inbound message events: GROUP_AT_MESSAGE_CREATE / C2C_MESSAGE_CREATE /
+ * AT_MESSAGE_CREATE. Outbound: getAppAccessToken (cached) then the v2 messages
+ * API (passive reply via msg_id). Config (channels.qq): { appId, secret,
+ *   agent? }. Env fallback: QQ_BOT_APPID, QQ_BOT_SECRET.
+ */
+
+import * as crypto from 'crypto';
+import { getLogger } from '../../core/logger';
+import { resolveSecret, postJson, TokenCache } from '../helpers';
+import type { ChannelAdapter, MediaAttachment, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+
+const log = getLogger('channel-qq');
+
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+
+/** Repeat the bot secret to a 32-byte Ed25519 seed (QQ's scheme). */
+export function qqSeed(secret: string): Buffer {
+  let s = secret;
+  while (s.length < 32) s = s + s;
+  return Buffer.from(s.slice(0, 32), 'utf8');
+}
+
+function privKeyFromSeed(seed: Buffer): crypto.KeyObject {
+  return crypto.createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, seed]), format: 'der', type: 'pkcs8' });
+}
+
+/** Sign `event_ts + plain_token` for the validation handshake; returns hex. */
+export function qqSignValidation(secret: string, eventTs: string, plainToken: string): string {
+  const priv = privKeyFromSeed(qqSeed(secret));
+  return crypto.sign(null, Buffer.from(eventTs + plainToken, 'utf8'), priv).toString('hex');
+}
+
+/** Verify an event push signature (hex) over `timestamp + body`. */
+export function qqVerify(secret: string, timestamp: string, body: Buffer, signatureHex: string): boolean {
+  try {
+    const pub = crypto.createPublicKey(privKeyFromSeed(qqSeed(secret)));
+    const msg = Buffer.concat([Buffer.from(timestamp, 'utf8'), body]);
+    return crypto.verify(null, msg, pub, Buffer.from(signatureHex, 'hex'));
+  } catch (e) {
+    log.warn('qq_verify_error', { error: String(e) });
+    return false;
+  }
+}
+
+export function createQQAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapter | null {
+  const appId = resolveSecret(cfg.appId != null ? String(cfg.appId) : undefined, env, 'QQ_BOT_APPID');
+  const secret = resolveSecret(cfg.secret, env, 'QQ_BOT_SECRET');
+  if (!appId || !secret) return null;
+
+  const tokenCache = new TokenCache(async () => {
+    const data = await postJson('https://bots.qq.com/app/getAppAccessToken', {
+      appId, clientSecret: secret,
+    });
+    if (!data.access_token) throw new Error(`qq token error: ${JSON.stringify(data).slice(0, 120)}`);
+    return { token: data.access_token, expiresInSec: Number(data.expires_in) || 7200 };
+  });
+
+  const authHeaders = async () => ({ Authorization: `QQBot ${await tokenCache.get()}`, 'X-Union-Appid': appId });
+
+  return {
+    id: 'qq',
+    name: 'QQ Bot',
+    defaultAgent: cfg.agent || 'fair',
+
+    async handleWebhook(req: RawRequest): Promise<WebhookOutcome> {
+      let payload: any;
+      try { payload = JSON.parse(req.body.toString('utf8') || '{}'); } catch { return { response: { status: 400, body: 'bad json' } }; }
+
+      // Validation handshake (op 13) — no signature header on this one.
+      if (payload.op === 13 && payload.d?.plain_token && payload.d?.event_ts) {
+        const signature = qqSignValidation(secret, String(payload.d.event_ts), String(payload.d.plain_token));
+        return { response: { status: 200, contentType: 'application/json', body: JSON.stringify({ plain_token: payload.d.plain_token, signature }) } };
+      }
+
+      // Verify the event push signature.
+      const sig = (req.headers['x-signature-ed25519'] as string) || '';
+      const ts = (req.headers['x-signature-timestamp'] as string) || '';
+      if (sig && ts && !qqVerify(secret, ts, req.body, sig)) {
+        return { response: { status: 403, body: 'bad signature' } };
+      }
+
+      if (payload.op !== 0) return { response: { status: 200, body: '' } }; // not a dispatch
+
+      const t = payload.t as string;
+      const d = payload.d || {};
+      const content = String(d.content || '').replace(/<@!?\d+>/g, '').trim();
+      const msgId = d.id as string;
+
+      let replyTo: ReplyTarget | null = null;
+      if (t === 'GROUP_AT_MESSAGE_CREATE') replyTo = { channel: 'qq', kind: 'group', groupOpenid: d.group_openid, msgId };
+      else if (t === 'C2C_MESSAGE_CREATE') replyTo = { channel: 'qq', kind: 'c2c', userOpenid: d.author?.user_openid, msgId };
+      else if (t === 'AT_MESSAGE_CREATE' || t === 'MESSAGE_CREATE') replyTo = { channel: 'qq', kind: 'channel', channelId: d.channel_id, msgId };
+
+      // QQ delivers images/files as an attachments array on the event.
+      const media: MediaAttachment[] = [];
+      for (const att of (Array.isArray(d.attachments) ? d.attachments : [])) {
+        const ct = String(att?.content_type || '');
+        const kind: MediaAttachment['kind'] = ct.startsWith('image') ? 'image'
+          : ct.startsWith('audio') || ct.startsWith('voice') ? 'audio'
+          : ct.startsWith('video') ? 'video' : 'file';
+        media.push({ kind, ref: att?.id, filename: att?.filename, mimeType: att?.content_type, url: att?.url });
+      }
+
+      if (!replyTo || (!content && media.length === 0)) return { response: { status: 200, body: '' } };
+
+      const userId = d.author?.user_openid || d.author?.id || d.author?.member_openid || 'unknown';
+      return {
+        response: { status: 200, body: '' },
+        message: {
+          channel: 'qq',
+          conversationId: (replyTo.groupOpenid as string) || (replyTo.channelId as string) || (userId as string),
+          userId,
+          text: content,
+          media: media.length ? media : undefined,
+          replyTo,
+          raw: payload,
+        },
+      };
+    },
+
+    async send(target: ReplyTarget, text: string): Promise<void> {
+      const headers = { ...(await authHeaders()), 'Content-Type': 'application/json' };
+      const msgId = target.msgId as string | undefined;
+      const payload: any = { msg_type: 0, content: text };
+      if (msgId) payload.msg_id = msgId; // passive reply within the allowed window
+
+      let url: string;
+      if (target.kind === 'group') url = `https://api.sgroup.qq.com/v2/groups/${target.groupOpenid}/messages`;
+      else if (target.kind === 'c2c') url = `https://api.sgroup.qq.com/v2/users/${target.userOpenid}/messages`;
+      else url = `https://api.sgroup.qq.com/channels/${target.channelId}/messages`;
+
+      try {
+        await postJson(url, payload, { headers });
+      } catch (e: any) {
+        if (e?.response?.status === 401) tokenCache.invalidate();
+        throw new Error(`qq send error: ${e?.response?.status || ''} ${String(e?.message || e).slice(0, 120)}`);
+      }
+    },
+  };
+}