skyloom 1.19.0 → 1.21.0

package/dist/gateway/gateway.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export interface GatewayOptions {
+    port?: number;
+    host?: string;
+}
+export declare function startGateway(opts?: GatewayOptions): Promise<void>;
+//# sourceMappingURL=gateway.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/gateway/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyCH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4F3E"}

package/dist/gateway/gateway.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startGateway = startGateway;
+const http_1 = require("http");
+const logger_1 = require("../core/logger");
+const factory_1 = require("../core/factory");
+const registry_1 = require("./registry");
+const log = (0, logger_1.getLogger)('gateway');
+/** Collect the full request body. */
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+/** Run an agent turn for an inbound message and collect the final text reply. */
+async function runAgent(ctx, adapter, msg) {
+    const cfgChannels = ctx.config.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.type === 'content')
+                text += ev.text;
+        }
+    }
+    catch (e) {
+        log.warn('gateway_agent_failed', { channel: adapter.id, error: String(e) });
+        return `[出错了] ${String(e)}`;
+    }
+    return text.trim() || '(无回复)';
+}
+async function startGateway(opts = {}) {
+    const ctx = (0, factory_1.createSystemContext)();
+    const adapters = (0, registry_1.buildAdapters)(ctx.config.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 = (0, http_1.createServer)(async (req, res) => {
+        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 = {
+                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((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)); });
+}
+//# sourceMappingURL=gateway.js.map

package/dist/gateway/gateway.js.map

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

package/dist/gateway/helpers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function resolveSecret(value: unknown, env: NodeJS.ProcessEnv, envFallback?: string): string | undefined;
+/** POST JSON, return parsed JSON. Throws on non-2xx. */
+export declare function postJson(url: string, body: any, opts?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<any>;
+/** GET JSON, return parsed JSON. Throws on non-2xx. */
+export declare function getJson(url: string, opts?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<any>;
+/**
+ * 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 declare class TokenCache {
+    private fetcher;
+    private token;
+    private expiresAt;
+    constructor(fetcher: () => Promise<{
+        token: string;
+        expiresInSec: number;
+    }>);
+    get(): Promise<string>;
+    /** Force the next get() to refetch (e.g. after a 401). */
+    invalidate(): void;
+}
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/gateway/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAcpB;AAED,wDAAwD;AACxD,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,GAAG,EACT,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,OAAO,CAAC,GAAG,CAAC,CAOd;AAED,uDAAuD;AACvD,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,OAAO,CAAC,GAAG,CAAC,CAOd;AAED;;;;GAIG;AACH,qBAAa,UAAU;IAGT,OAAO,CAAC,OAAO;IAF3B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,SAAS,CAAK;gBACF,OAAO,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7E,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC;IAS5B,0DAA0D;IAC1D,UAAU,IAAI,IAAI;CACnB"}

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.19.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)")