skyloom 1.20.0 → 1.21.0

package/dist/gateway/helpers.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Shared helpers for channel adapters: secret resolution (config value or env
+ * fallback), and a tiny JSON HTTP client. Kept dependency-light (axios is
+ * already a project dep) and injectable-free — adapters call these directly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenCache = void 0;
+exports.resolveSecret = resolveSecret;
+exports.postJson = postJson;
+exports.getJson = getJson;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Resolve a secret/config value. Accepts a literal string, or an env-ref object
+ * `{ source: 'env', id: 'NAME' }` (OpenClaw-compatible), falling back to the
+ * given env var name. Returns undefined if unresolved.
+ */
+function resolveSecret(value, env, envFallback) {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (value && typeof value === 'object') {
+        const v = value;
+        if (v.source === 'env' && typeof v.id === 'string') {
+            const got = env[v.id];
+            if (got && got.trim())
+                return got.trim();
+        }
+    }
+    if (envFallback) {
+        const got = env[envFallback];
+        if (got && got.trim())
+            return got.trim();
+    }
+    return undefined;
+}
+/** POST JSON, return parsed JSON. Throws on non-2xx. */
+async function postJson(url, body, opts) {
+    const res = await axios_1.default.post(url, body, {
+        headers: { 'Content-Type': 'application/json', ...(opts?.headers || {}) },
+        timeout: opts?.timeoutMs ?? 15000,
+        validateStatus: (s) => s >= 200 && s < 300,
+    });
+    return res.data;
+}
+/** GET JSON, return parsed JSON. Throws on non-2xx. */
+async function getJson(url, opts) {
+    const res = await axios_1.default.get(url, {
+        headers: { Accept: 'application/json', ...(opts?.headers || {}) },
+        timeout: opts?.timeoutMs ?? 15000,
+        validateStatus: (s) => s >= 200 && s < 300,
+    });
+    return res.data;
+}
+/**
+ * A small token cache: fetch an access token via `fetcher`, cache it until it
+ * is near expiry, and refresh transparently. Channels (Feishu/WeCom) all need
+ * a short-lived tenant/access token; this avoids re-fetching per message.
+ */
+class TokenCache {
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+        this.token = null;
+        this.expiresAt = 0;
+    }
+    async get() {
+        const now = Date.now();
+        if (this.token && now < this.expiresAt - 60000)
+            return this.token;
+        const { token, expiresInSec } = await this.fetcher();
+        this.token = token;
+        this.expiresAt = now + Math.max(60, expiresInSec) * 1000;
+        return token;
+    }
+    /** Force the next get() to refetch (e.g. after a 401). */
+    invalidate() { this.token = null; this.expiresAt = 0; }
+}
+exports.TokenCache = TokenCache;
+//# sourceMappingURL=helpers.js.map

package/dist/gateway/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/gateway/helpers.ts"],"names":[],"mappings":"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"}

package/dist/gateway/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Channel registry — maps channel ids to their adapter factories and builds the
+ * set of enabled adapters from the `channels` config block.
+ *
+ * A channel is enabled when its config block exists and is not `enabled: false`
+ * and the factory can resolve its required credentials (from config or env).
+ */
+import type { ChannelAdapter } from './types';
+/** Build all enabled, well-configured adapters from the channels config. */
+export declare function buildAdapters(channelsCfg: Record<string, any>, env: NodeJS.ProcessEnv): Map<string, ChannelAdapter>;
+export declare const SUPPORTED_CHANNELS: string[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/gateway/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,SAAS,CAAC;AAa9D,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAChC,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAgB7B;AAED,eAAO,MAAM,kBAAkB,UAAyB,CAAC"}

package/dist/gateway/registry.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Channel registry — maps channel ids to their adapter factories and builds the
+ * set of enabled adapters from the `channels` config block.
+ *
+ * A channel is enabled when its config block exists and is not `enabled: false`
+ * and the factory can resolve its required credentials (from config or env).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_CHANNELS = void 0;
+exports.buildAdapters = buildAdapters;
+const logger_1 = require("../core/logger");
+const feishu_1 = require("./channels/feishu");
+const wecom_1 = require("./channels/wecom");
+const qq_1 = require("./channels/qq");
+const log = (0, logger_1.getLogger)('gateway-registry');
+const FACTORIES = {
+    feishu: feishu_1.createFeishuAdapter,
+    wecom: wecom_1.createWecomAdapter,
+    qq: qq_1.createQQAdapter,
+};
+/** Build all enabled, well-configured adapters from the channels config. */
+function buildAdapters(channelsCfg, env) {
+    const adapters = new Map();
+    for (const [id, factory] of Object.entries(FACTORIES)) {
+        const cfg = channelsCfg[id];
+        // A channel can be enabled purely via env vars (no config block) — pass an
+        // empty object so the factory still tries env fallback. Skip only when the
+        // block is explicitly disabled.
+        if (cfg && cfg.enabled === false)
+            continue;
+        try {
+            const adapter = factory(cfg || {}, env);
+            if (adapter)
+                adapters.set(id, adapter);
+        }
+        catch (e) {
+            log.warn('adapter_build_failed', { channel: id, error: String(e) });
+        }
+    }
+    return adapters;
+}
+exports.SUPPORTED_CHANNELS = Object.keys(FACTORIES);
+//# sourceMappingURL=registry.js.map

package/dist/gateway/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/gateway/registry.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAiBH,sCAmBC;AAlCD,2CAA2C;AAE3C,8CAAwD;AACxD,4CAAsD;AACtD,sCAAgD;AAEhD,MAAM,GAAG,GAAG,IAAA,kBAAS,EAAC,kBAAkB,CAAC,CAAC;AAE1C,MAAM,SAAS,GAAmC;IAChD,MAAM,EAAE,4BAAmB;IAC3B,KAAK,EAAE,0BAAkB;IACzB,EAAE,EAAE,oBAAe;CACpB,CAAC;AAEF,4EAA4E;AAC5E,SAAgB,aAAa,CAC3B,WAAgC,EAChC,GAAsB;IAEtB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IACnD,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACtD,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC5B,2EAA2E;QAC3E,2EAA2E;QAC3E,gCAAgC;QAChC,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK;YAAE,SAAS;QAC3C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;YACxC,IAAI,OAAO;gBAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAEY,QAAA,kBAAkB,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC"}

package/dist/gateway/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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;
+    /** Raw event for adapters that need more than the normalized fields. */
+    raw?: unknown;
+}
+/** 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>;
+}
+/** 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,wEAAwE;IACxE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;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;CACxD;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,14 @@
+"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 });
+//# 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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skyloom",
-  "version": "1.20.0",
+  "version": "1.21.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,142 @@
+/**
+ * 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, 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';
+
+  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 };
+  });
+
+  // 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 = '';
+      if (msgType === 'text') {
+        try { text = JSON.parse(message.content || '{}').text || ''; } catch { text = ''; }
+        // Strip @mentions like "@_user_1 ".
+        text = text.replace(/@_user_\d+/g, '').trim();
+      } else {
+        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,
+          replyTo: { channel: 'feishu', chatId },
+          raw: payload,
+        },
+      };
+    },
+
+    async send(target: ReplyTarget, text: string): Promise<void> {
+      const chatId = target.chatId as string;
+      if (!chatId) return;
+      const token = await tokenCache.get();
+      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: { Authorization: `Bearer ${token}` } },
+      );
+      if (data.code !== 0) {
+        if (data.code === 99991663 || data.code === 99991661) tokenCache.invalidate(); // token expired
+        throw new Error(`feishu send error ${data.code}: ${data.msg}`);
+      }
+    },
+  };
+}

package/src/gateway/channels/qq.ts

@@ -0,0 +1,140 @@
+/**
+ * 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, 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 };
+
+      if (!replyTo || !content) 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,
+          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)}`);
+      }
+    },
+  };
+}