skyloom 1.20.0 → 1.21.0

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

package/src/gateway/gateway.ts

@@ -0,0 +1,151 @@
+/**
+ * Channel gateway — runs the registered channel adapters behind one HTTP server
+ * and bridges inbound platform messages to Skyloom agents.
+ *
+ *   platform → POST /webhook/<channel> → adapter.handleWebhook (verify+normalize)
+ *            → route to agent → agent.chatStream → adapter.send (reply)
+ *
+ * The HTTP layer mirrors web/server.ts. Each channel handles its own signature
+ * verification and URL-verification handshake inside handleWebhook, so the
+ * gateway core never knows platform specifics. Agent replies are delivered
+ * asynchronously (after the webhook is acked) because all three platforms
+ * require a fast 200.
+ */
+
+import { createServer, IncomingMessage, ServerResponse } from 'http';
+import { getLogger } from '../core/logger';
+import { createSystemContext } from '../core/factory';
+import { buildAdapters } from './registry';
+import type { ChannelAdapter, InboundMessage, RawRequest } from './types';
+
+const log = getLogger('gateway');
+
+/** Collect the full request body. */
+async function readBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks);
+}
+
+/** Run an agent turn for an inbound message and collect the final text reply. */
+async function runAgent(
+  ctx: ReturnType<typeof createSystemContext>,
+  adapter: ChannelAdapter,
+  msg: InboundMessage,
+): Promise<string> {
+  const cfgChannels = (ctx.config as any).channels || {};
+  const agentName = cfgChannels[adapter.id]?.agent || adapter.defaultAgent || 'fair';
+  const agent = ctx.agentMap.get(agentName) || ctx.agentMap.get('fair') || [...ctx.agentMap.values()][0];
+  if (!agent) throw new Error('no agent available');
+
+  await agent.init();
+  let text = '';
+  try {
+    for await (const ev of agent.chatStream(msg.text)) {
+      if ((ev as any).type === 'content') text += (ev as any).text;
+    }
+  } catch (e) {
+    log.warn('gateway_agent_failed', { channel: adapter.id, error: String(e) });
+    return `[出错了] ${String(e)}`;
+  }
+  return text.trim() || '(无回复)';
+}
+
+export interface GatewayOptions {
+  port?: number;
+  host?: string;
+}
+
+export async function startGateway(opts: GatewayOptions = {}): Promise<void> {
+  const ctx = createSystemContext();
+  const adapters = buildAdapters((ctx.config as any).channels || {}, process.env);
+
+  if (adapters.size === 0) {
+    log.warn('gateway_no_channels', {});
+    process.stdout.write(
+      '\n  ⚠ 没有启用任何渠道。在 ~/.skyloom/config.yaml 配置 channels.feishu / channels.wecom / channels.qq,\n' +
+      '    或设置对应环境变量(如 FEISHU_APP_ID/FEISHU_APP_SECRET)。\n\n',
+    );
+    return;
+  }
+
+  for (const adapter of adapters.values()) {
+    if (adapter.start) {
+      try { await adapter.start(); } catch (e) { log.warn('adapter_start_failed', { channel: adapter.id, error: String(e) }); }
+    }
+  }
+
+  const port = opts.port ?? Number(process.env.SKYLOOM_GATEWAY_PORT) ?? 8848;
+  // Gateways receive inbound webhooks from the platform's servers, so unlike the
+  // local web UI they must bind to a reachable interface by default.
+  const host = opts.host || process.env.SKYLOOM_GATEWAY_HOST || '0.0.0.0';
+
+  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url || '/', `http://${req.headers.host}`);
+    try {
+      if (url.pathname === '/health' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+          .end(JSON.stringify({ ok: true, channels: [...adapters.keys()] }));
+        return;
+      }
+      const m = url.pathname.match(/^\/webhook\/([a-z0-9_-]+)$/i);
+      if (!m) { res.writeHead(404).end('Not found'); return; }
+      const adapter = adapters.get(m[1].toLowerCase());
+      if (!adapter) { res.writeHead(404).end(`Unknown channel: ${m[1]}`); return; }
+
+      const raw: RawRequest = {
+        method: req.method || 'POST',
+        headers: req.headers,
+        query: url.searchParams,
+        body: await readBody(req),
+      };
+
+      const outcome = await adapter.handleWebhook(raw);
+
+      // Immediate HTTP response (challenge / ack / signature failure).
+      if (outcome.response) {
+        res.writeHead(outcome.response.status, {
+          'Content-Type': outcome.response.contentType || 'text/plain; charset=utf-8',
+        }).end(outcome.response.body ?? '');
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' }).end('{}');
+      }
+
+      // Route to an agent and deliver the reply asynchronously (after the ack).
+      if (outcome.message) {
+        const msg = outcome.message;
+        void (async () => {
+          try {
+            const reply = await runAgent(ctx, adapter, msg);
+            await adapter.send(msg.replyTo, reply);
+          } catch (e) {
+            log.warn('gateway_dispatch_failed', { channel: adapter.id, error: String(e) });
+          }
+        })();
+      }
+    } catch (e) {
+      log.warn('gateway_request_error', { error: String(e) });
+      if (!res.headersSent) res.writeHead(500).end('error');
+    }
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(port, host, () => {
+      const list = [...adapters.values()].map((a) => `${a.name}(/webhook/${a.id})`).join(' · ');
+      process.stdout.write(
+        `\n  天空织机 · 渠道网关  ·  http://${host}:${port}\n  已启用: ${list}\n` +
+        `  把对应平台的事件回调 URL 指向 http(s)://<你的域名>:${port}/webhook/<channel>\n\n`,
+      );
+      log.info('gateway_started', { port, host, channels: [...adapters.keys()] });
+      resolve();
+    });
+  });
+
+  const shutdown = async () => {
+    for (const a of adapters.values()) { try { await a.stop?.(); } catch { /* ignore */ } }
+    try { await ctx.closeAll(); } catch { /* ignore */ }
+    server.close();
+  };
+  process.on('SIGINT', () => { void shutdown().then(() => process.exit(0)); });
+  process.on('SIGTERM', () => { void shutdown().then(() => process.exit(0)); });
+}

package/src/gateway/helpers.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+
+import axios from '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.
+ */
+export function resolveSecret(
+  value: unknown,
+  env: NodeJS.ProcessEnv,
+  envFallback?: string,
+): string | undefined {
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  if (value && typeof value === 'object') {
+    const v = value as any;
+    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. */
+export async function postJson(
+  url: string,
+  body: any,
+  opts?: { headers?: Record<string, string>; timeoutMs?: number },
+): Promise<any> {
+  const res = await axios.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. */
+export async function getJson(
+  url: string,
+  opts?: { headers?: Record<string, string>; timeoutMs?: number },
+): Promise<any> {
+  const res = await axios.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.
+ */
+export class TokenCache {
+  private token: string | null = null;
+  private expiresAt = 0;
+  constructor(private fetcher: () => Promise<{ token: string; expiresInSec: number }>) {}
+
+  async get(): Promise<string> {
+    const now = Date.now();
+    if (this.token && now < this.expiresAt - 60_000) 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(): void { this.token = null; this.expiresAt = 0; }
+}

package/src/gateway/registry.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { getLogger } from '../core/logger';
+import type { ChannelAdapter, ChannelFactory } from './types';
+import { createFeishuAdapter } from './channels/feishu';
+import { createWecomAdapter } from './channels/wecom';
+import { createQQAdapter } from './channels/qq';
+
+const log = getLogger('gateway-registry');
+
+const FACTORIES: Record<string, ChannelFactory> = {
+  feishu: createFeishuAdapter,
+  wecom: createWecomAdapter,
+  qq: createQQAdapter,
+};
+
+/** Build all enabled, well-configured adapters from the channels config. */
+export function buildAdapters(
+  channelsCfg: Record<string, any>,
+  env: NodeJS.ProcessEnv,
+): Map<string, ChannelAdapter> {
+  const adapters = new Map<string, ChannelAdapter>();
+  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;
+}
+
+export const SUPPORTED_CHANNELS = Object.keys(FACTORIES);

package/src/gateway/types.ts

@@ -0,0 +1,91 @@
+/**
+ * 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;