skyloom 1.19.0 → 1.21.0

package/src/core/agent.ts

@@ -90,8 +90,12 @@ export class BaseAgent {
   protected _skillTools: Map<string, string[]> = new Map();
   protected _skillConfigOverrides: Map<string, Record<string, any>> = new Map();
   protected _baseSystemPrompt: string = '';
+  /** @deprecated stopping is progress-based now; kept for back-compat only. */
   protected _maxToolRounds: number = 50;
-  protected _maxToolRoundsHardCap: number = 200;
+  /** Last-resort backstop against runaway; not the normal stop path. */
+  protected _maxToolRoundsHardCap: number = 1000;
+  /** Stop after this many consecutive rounds with no progress (see chatStreamImpl). */
+  protected _maxNoProgressRounds: number = 6;
   protected _userTurnsSinceExtract: number = 0;
   protected _pendingExtracts: Set<Promise<any>> = new Set();
   protected _pendingRequests: Map<string, { resolve: (value: string) => void; reject: (err: Error) => void }> = new Map();
@@ -132,27 +136,28 @@ export class BaseAgent {
       maxPersistedMessages: mc.maxPersistedMessages || mc.max_persisted_messages,
     }, this.name);
 
-    // Tool-round budget. The LoopGuard is the real safety net (it stops genuine
-    // loops — repeated signatures, all-failing calls, search storms — at any
-    // round count), so this cap exists only as a last-resort ceiling against
-    // pathological cases the guard misses. Defaults are generous so normal long
-    // tasks (big refactors across many files) never hit it; configurable via
-    // config.llm.max_tool_rounds / max_tool_rounds_hard_cap. Setting
-    // max_tool_rounds to 0 (or negative) means "unlimited" — a very high ceiling
-    // so a guard-less runaway still can't burn tokens forever.
+    // Stopping is PROGRESS-based, not round-count based (OpenClaw-style): a task
+    // runs as long as it keeps making progress. The agent stops when it makes no
+    // progress for `_maxNoProgressRounds` rounds in a row, or when the LoopGuard
+    // detects a genuine loop. `_maxToolRoundsHardCap` is only a last-resort
+    // backstop against pathological runaway and is set very high so normal long
+    // tasks never reach it. All three are configurable under config.llm.
     const lc: any = (config as any).llm || {};
-    const soft = Number(lc.max_tool_rounds ?? lc.maxToolRounds);
     const hard = Number(lc.max_tool_rounds_hard_cap ?? lc.maxToolRoundsHardCap);
-    const UNLIMITED = 100000;
-    if (Number.isFinite(soft) && soft <= 0) {
-      // Unlimited: rely entirely on the LoopGuard + Ctrl-C + context compaction.
-      this._maxToolRounds = UNLIMITED;
-      this._maxToolRoundsHardCap = UNLIMITED;
-    } else {
-      this._maxToolRounds = Number.isFinite(soft) && soft > 0 ? Math.floor(soft) : 50;
-      this._maxToolRoundsHardCap = Number.isFinite(hard) && hard > 0
-        ? Math.max(Math.floor(hard), this._maxToolRounds)
-        : Math.max(200, this._maxToolRounds);
+    const noProg = Number(lc.max_no_progress_rounds ?? lc.maxNoProgressRounds);
+    if (Number.isFinite(hard) && hard <= 0) {
+      this._maxToolRoundsHardCap = 1_000_000; // effectively unlimited
+    } else if (Number.isFinite(hard) && hard > 0) {
+      this._maxToolRoundsHardCap = Math.floor(hard);
+    } // else keep the generous default (1000)
+    if (Number.isFinite(noProg) && noProg > 0) {
+      this._maxNoProgressRounds = Math.floor(noProg);
+    }
+    // Back-compat: max_tool_rounds is no longer a hard stop, but if someone set
+    // it we honor it as the hard cap so existing configs still bound the run.
+    const legacySoft = Number(lc.max_tool_rounds ?? lc.maxToolRounds);
+    if (Number.isFinite(legacySoft) && legacySoft > 0) {
+      this._maxToolRoundsHardCap = Math.max(this._maxToolRoundsHardCap, Math.floor(legacySoft));
     }
   }
 
@@ -359,22 +364,9 @@ export class BaseAgent {
       },
     });
 
-    this.toolRegistry.register({
-      name: 'extend_rounds',
-      description: 'Extend the tool-call budget for the current turn.',
-      parameters: [{
-        name: 'n',
-        type: 'number',
-        description: 'Number of additional rounds to add (default 10)',
-        required: false,
-      }],
-      handler: async (kwargs: Record<string, any>) => {
-        const n = (kwargs.n as number) || 10;
-        const old = this._maxToolRounds;
-        this._maxToolRounds += n;
-        return `✓ Tool-round limit extended by ${n} (was ${old}, now ${this._maxToolRounds}).`;
-      },
-    });
+    // Note: the old `extend_rounds` tool was removed — stopping is now
+    // progress-based (see chatStreamImpl), so there is no per-turn round budget
+    // to extend. A productive task simply keeps running.
 
     // ── Self-evolve tool: analyze failures and suggest prompt improvements ──
     this.toolRegistry.register({
@@ -967,8 +959,13 @@ export class BaseAgent {
 
     try {
       let fullContent = '';
-      let roundLimit = this._maxToolRounds;
       let roundCount = 0;
+      // Progress-based stopping (OpenClaw-style): we don't cap by round count —
+      // a long task that keeps making progress runs as long as it needs. We
+      // stop when the agent makes no progress for several rounds in a row (pure
+      // spinning), or when the LoopGuard detects a genuine loop. The hard round
+      // cap is only a last-resort backstop against pathological runaway.
+      let consecutiveNoProgress = 0;
 
       while (true) {
         // User interrupt between rounds (Ctrl-C): stop before another LLM call.
@@ -984,16 +981,10 @@ export class BaseAgent {
           yield { type: 'done' };
           return;
         }
-        if (roundCount >= roundLimit) {
-          if (roundLimit >= this._maxToolRoundsHardCap) break;
-          const extendBy = Math.min(15, this._maxToolRoundsHardCap - roundLimit);
-          roundLimit += extendBy;
-          this._maxToolRounds = roundLimit;
-          this.memory.addMessage('system', `[Auto-extended tool-round limit by ${extendBy} to ${roundLimit}. Continue working.]`);
-          continue;
-        }
+        // Last-resort backstop: only trips in pathological cases the progress
+        // detector and LoopGuard both miss. Normal long tasks never reach it.
+        if (roundCount >= this._maxToolRoundsHardCap) break;
         roundCount++;
-        roundLimit = Math.max(roundLimit, this._maxToolRounds);
 
         const messages = await this.messagesWithRecall();
         const toolNames = resolveToolNames();
@@ -1124,9 +1115,38 @@ export class BaseAgent {
           yield { type: 'done' };
           return;
         }
+
+        // ── Progress-based stopping ──
+        // A round made progress if at least one tool call SUCCEEDED (state
+        // advanced) or the model produced new text this round. Pure spinning —
+        // no successful tool, no text — increments the no-progress counter; any
+        // progress resets it. Stop only after several no-progress rounds in a
+        // row, so a long, productive task is never cut off by a round count.
+        const madeProgress =
+          execResults.some(r => r.success && r.toolName !== 'task_done') ||
+          roundContent.trim().length > 0;
+        if (madeProgress) {
+          consecutiveNoProgress = 0;
+        } else {
+          consecutiveNoProgress++;
+          if (consecutiveNoProgress === this._maxNoProgressRounds - 1) {
+            this.memory.addMessage('system',
+              '[No progress] Your recent rounds produced no successful tool result and no text. Either take a concrete next action, output the final answer, or call task_done. One more empty round will end the turn.');
+          }
+          if (consecutiveNoProgress >= this._maxNoProgressRounds) {
+            if (!assistantStored && fullContent.trim()) {
+              this.memory.addMessage('assistant', fullContent);
+              assistantStored = true;
+            }
+            await this.setState(AgentState.IDLE);
+            yield { type: 'content', text: `\n\n[stalled] ${consecutiveNoProgress} rounds without progress — stopping.` };
+            yield { type: 'done' };
+            return;
+          }
+        }
       }
 
-      // Max iterations reached
+      // Hard-cap backstop reached (pathological runaway only).
       if (!assistantStored) this.popLastUserMessage();
       await this.setState(AgentState.IDLE);
       if (!fullContent.trim() && delegations.length > 0) {
@@ -1136,7 +1156,7 @@ export class BaseAgent {
       }
       yield {
         type: 'truncated',
-        reason: `safety ceiling of ${this._maxToolRoundsHardCap} tool rounds reached — the task may be unfinished. Send "continue" to resume, or raise llm.max_tool_rounds in config (0 = unlimited).`,
+        reason: `safety ceiling of ${this._maxToolRoundsHardCap} tool rounds reached — the task may be unfinished. Send "continue" to resume, or raise llm.max_tool_rounds_hard_cap in config.`,
       };
       yield { type: 'done' };
     } catch (e: any) {
@@ -1380,11 +1400,9 @@ export class BaseAgent {
   }
 
   protected async llmLoop(options?: {
-    maxIterations?: number;
     onStatus?: ((status: string) => void) | null;
     ephemeral?: boolean;
   }): Promise<LLMResponse> {
-    const maxIterations = options?.maxIterations ?? this._maxToolRounds;
     const ephemeral = options?.ephemeral ?? false;
     const onStatus = options?.onStatus ?? null;
 
@@ -1403,19 +1421,14 @@ export class BaseAgent {
     );
 
     try {
-      let limit = maxIterations;
+      // Progress-based stopping (mirrors chatStreamImpl): no round-count limit —
+      // run while making progress, stop after _maxNoProgressRounds empty rounds.
+      // The hard cap is only a last-resort backstop against runaway.
       let rounds = 0;
+      let consecutiveNoProgress = 0;
       while (true) {
-        if (rounds >= limit) {
-          if (limit >= this._maxToolRoundsHardCap) break;
-          const extendBy = Math.min(15, this._maxToolRoundsHardCap - limit);
-          limit += extendBy;
-          this._maxToolRounds = limit;
-          this.memory.addMessage('system', `[Auto-extended limit by ${extendBy} to ${limit}.]`);
-          continue;
-        }
+        if (rounds >= this._maxToolRoundsHardCap) break;
         rounds++;
-        limit = Math.max(limit, this._maxToolRounds);
 
         const messages = await this.messagesWithRecall();
         if (onStatus) onStatus('thinking...');
@@ -1441,13 +1454,21 @@ export class BaseAgent {
         });
 
         // ── Execute all tools via shared pipeline ──
-        await this.executeToolCalls(response.toolCalls, { dedupCacheable: true, onStatus: onStatus ?? undefined, ephemeral });
+        const execResults = await this.executeToolCalls(response.toolCalls, { dedupCacheable: true, onStatus: onStatus ?? undefined, ephemeral });
         await this.setState(AgentState.THINKING);
+
+        // Progress check: any successful tool or produced text resets the
+        // counter; otherwise count an empty round and stop after the threshold.
+        const madeProgress =
+          execResults.some(r => r.success && r.toolName !== 'task_done') ||
+          (response.content || '').trim().length > 0;
+        consecutiveNoProgress = madeProgress ? 0 : consecutiveNoProgress + 1;
+        if (consecutiveNoProgress >= this._maxNoProgressRounds) break;
       }
 
       response.truncated = true;
       if (!response.content) {
-        response.content = `[truncated] max tool rounds (${maxIterations}) reached.`;
+        response.content = `[stopped] no progress for ${this._maxNoProgressRounds} rounds (or backstop reached).`;
       }
       return response;
     } catch (e) {

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)}`);
+      }
+    },
+  };
+}

package/src/gateway/channels/wecom.ts

@@ -0,0 +1,142 @@
+/**
+ * WeCom (企业微信) channel adapter.
+ *
+ * Uses the official "receive messages" callback with the standard WeWork
+ * crypto: msg_signature = sha1(sort(token, timestamp, nonce, echostr|encrypt)),
+ * and AES-256-CBC (PKCS7) where the key is base64(EncodingAESKey + "=") and the
+ * plaintext is [16B random][4B big-endian msg-len][msg][receiveid].
+ *
+ * Inbound is XML. GET verifies the callback URL (echo the decrypted echostr);
+ * POST carries the encrypted message. We extract text from <Content>.
+ *
+ * Outbound uses the application message API (message/send) with the agent's
+ * gettoken. Config (channels.wecom): { corpId, corpSecret, token, encodingAesKey,
+ *   agentId, agent? }. Env fallback: WECOM_CORP_ID, WECOM_CORP_SECRET,
+ *   WECOM_TOKEN, WECOM_AES_KEY, WECOM_AGENT_ID.
+ */
+
+import * as crypto from 'crypto';
+import { getLogger } from '../../core/logger';
+import { resolveSecret, postJson, getJson, TokenCache } from '../helpers';
+import type { ChannelAdapter, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+
+const log = getLogger('channel-wecom');
+
+/** WeWork msg_signature: sha1 over the sorted concatenation. */
+export function wecomSignature(token: string, timestamp: string, nonce: string, encrypt: string): string {
+  const arr = [token, timestamp, nonce, encrypt].sort();
+  return crypto.createHash('sha1').update(arr.join('')).digest('hex');
+}
+
+/** Decrypt a WeWork AES message. Returns { message, receiveId }. */
+export function decryptWecom(encrypt: string, encodingAesKey: string): { message: string; receiveId: string } {
+  const key = Buffer.from(encodingAesKey + '=', 'base64'); // 32 bytes
+  const iv = key.subarray(0, 16);
+  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  decipher.setAutoPadding(false);
+  let decrypted = Buffer.concat([decipher.update(Buffer.from(encrypt, 'base64')), decipher.final()]);
+  // PKCS7 unpad
+  const pad = decrypted[decrypted.length - 1];
+  if (pad > 0 && pad <= 32) decrypted = decrypted.subarray(0, decrypted.length - pad);
+  // [16B random][4B msg len BE][msg][receiveid]
+  const content = decrypted.subarray(16);
+  const msgLen = content.readUInt32BE(0);
+  const message = content.subarray(4, 4 + msgLen).toString('utf8');
+  const receiveId = content.subarray(4 + msgLen).toString('utf8');
+  return { message, receiveId };
+}
+
+function xmlField(xml: string, tag: string): string {
+  const cdata = xml.match(new RegExp(`<${tag}><!\\[CDATA\\[([\\s\\S]*?)\\]\\]></${tag}>`));
+  if (cdata) return cdata[1];
+  const plain = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+  return plain ? plain[1] : '';
+}
+
+export function createWecomAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapter | null {
+  const corpId = resolveSecret(cfg.corpId, env, 'WECOM_CORP_ID');
+  const corpSecret = resolveSecret(cfg.corpSecret, env, 'WECOM_CORP_SECRET');
+  const token = resolveSecret(cfg.token, env, 'WECOM_TOKEN');
+  const aesKey = resolveSecret(cfg.encodingAesKey, env, 'WECOM_AES_KEY');
+  const agentId = resolveSecret(cfg.agentId != null ? String(cfg.agentId) : undefined, env, 'WECOM_AGENT_ID');
+  if (!corpId || !corpSecret || !token || !aesKey) return null;
+
+  const tokenCache = new TokenCache(async () => {
+    const data = await getJson(
+      `https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${encodeURIComponent(corpId)}&corpsecret=${encodeURIComponent(corpSecret)}`,
+    );
+    if (data.errcode !== 0) throw new Error(`wecom token error ${data.errcode}: ${data.errmsg}`);
+    return { token: data.access_token, expiresInSec: data.expires_in ?? 7200 };
+  });
+
+  const verify = (req: RawRequest, encrypt: string): boolean => {
+    const sig = req.query.get('msg_signature') || '';
+    const ts = req.query.get('timestamp') || '';
+    const nonce = req.query.get('nonce') || '';
+    return sig === wecomSignature(token, ts, nonce, encrypt);
+  };
+
+  return {
+    id: 'wecom',
+    name: 'WeCom (企业微信)',
+    defaultAgent: cfg.agent || 'fair',
+
+    async handleWebhook(req: RawRequest): Promise<WebhookOutcome> {
+      // URL verification: GET with echostr.
+      if (req.method === 'GET') {
+        const echostr = req.query.get('echostr') || '';
+        if (!verify(req, echostr)) return { response: { status: 403, body: 'bad signature' } };
+        try {
+          const { message } = decryptWecom(echostr, aesKey);
+          return { response: { status: 200, body: message } };
+        } catch (e) {
+          log.warn('wecom_echostr_decrypt_failed', { error: String(e) });
+          return { response: { status: 400, body: 'decrypt failed' } };
+        }
+      }
+
+      // Message callback: POST with <Encrypt> XML.
+      const xml = req.body.toString('utf8');
+      const encrypt = xmlField(xml, 'Encrypt');
+      if (!encrypt) return { response: { status: 400, body: 'no encrypt' } };
+      if (!verify(req, encrypt)) return { response: { status: 403, body: 'bad signature' } };
+
+      let inner: string;
+      try { inner = decryptWecom(encrypt, aesKey).message; }
+      catch (e) { log.warn('wecom_decrypt_failed', { error: String(e) }); return { response: { status: 400, body: 'decrypt failed' } }; }
+
+      const msgType = xmlField(inner, 'MsgType');
+      const fromUser = xmlField(inner, 'FromUserName');
+      let text = '';
+      if (msgType === 'text') text = xmlField(inner, 'Content').trim();
+      else text = `[${msgType} 消息]`;
+
+      // Ack the callback immediately (empty 200); reply is pushed via the API.
+      return {
+        response: { status: 200, body: '' },
+        message: text ? {
+          channel: 'wecom',
+          conversationId: fromUser,
+          userId: fromUser,
+          text,
+          replyTo: { channel: 'wecom', toUser: fromUser },
+          raw: inner,
+        } : undefined,
+      };
+    },
+
+    async send(target: ReplyTarget, text: string): Promise<void> {
+      const toUser = target.toUser as string;
+      if (!toUser || !agentId) return;
+      const accessToken = await tokenCache.get();
+      const data = await postJson(
+        `https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${encodeURIComponent(accessToken)}`,
+        { touser: toUser, msgtype: 'text', agentid: Number(agentId), text: { content: text } },
+      );
+      if (data.errcode !== 0) {
+        if (data.errcode === 42001 || data.errcode === 40014) tokenCache.invalidate();
+        throw new Error(`wecom send error ${data.errcode}: ${data.errmsg}`);
+      }
+    },
+  };
+}