@downcity/plugins 1.0.4

package/bin/chat/channels/telegram/TelegramPendingUpdates.js

@@ -0,0 +1,125 @@
+/**
+ * Telegram 积压 updates 补录逻辑。
+ *
+ * 关键点（中文）
+ * - 只负责把 polling 启动前/冲突恢复后的积压 update 写入 audit history。
+ * - 不执行 agent、不发送回复，避免离线消息在重连时集中触发执行。
+ * - `TelegramBot` 只传入平台能力与队列写入能力，保持门面轻量。
+ */
+import { getTelegramChatTitle, } from "./Shared.js";
+import { buildTelegramAuditText, buildTelegramChatKey, isTelegramGroupChat, } from "./TelegramInbound.js";
+/**
+ * 补录 Telegram 积压 updates 到 audit history。
+ */
+export async function drainTelegramPendingUpdatesToHistory(params) {
+    const drained = await params.platform.drainPendingUpdates({
+        reason: params.reason,
+        handleUpdate: async (update) => {
+            await enqueuePendingUpdate({
+                update,
+                reason: params.reason,
+                platform: params.platform,
+                enqueueAuditMessage: params.enqueueAuditMessage,
+            });
+        },
+    });
+    if (drained > 0) {
+        params.logger.info(`Drained ${drained} pending Telegram updates to queue`, {
+            reason: params.reason,
+        });
+    }
+}
+/**
+ * 单条 update 的 audit 写入分发。
+ */
+async function enqueuePendingUpdate(params) {
+    if (params.update.message?.chat?.id) {
+        await enqueuePendingMessage(params);
+        return;
+    }
+    if (params.update.callback_query?.from?.id) {
+        await enqueuePendingCallbackQuery(params);
+    }
+}
+/**
+ * 补录普通 message。
+ */
+async function enqueuePendingMessage(params) {
+    const message = params.update.message;
+    if (!message?.chat?.id)
+        return;
+    const chatId = message.chat.id.toString();
+    const messageThreadId = typeof message.message_thread_id === "number"
+        ? message.message_thread_id
+        : undefined;
+    const chatKey = buildTelegramChatKey(chatId, messageThreadId);
+    const from = message.from;
+    const chatTitle = getTelegramChatTitle(message.chat);
+    const botId = params.platform.getBotId();
+    const botUsername = params.platform.getBotUsername();
+    const fromIsBot = from?.is_bot === true ||
+        (!!botId && typeof from?.id === "number" && from.id === botId) ||
+        (!!botUsername &&
+            typeof from?.username === "string" &&
+            from.username.toLowerCase() === botUsername.toLowerCase());
+    const isGroup = isTelegramGroupChat(message.chat.type);
+    if (fromIsBot && !isGroup)
+        return;
+    const rawText = typeof message.text === "string"
+        ? message.text
+        : typeof message.caption === "string"
+            ? message.caption
+            : "";
+    const hasIncomingAttachment = !!message.document ||
+        (Array.isArray(message.photo) && message.photo.length > 0) ||
+        !!message.voice ||
+        !!message.audio ||
+        !!message.video;
+    const messageId = typeof message.message_id === "number" ? String(message.message_id) : undefined;
+    const actorId = from?.id ? String(from.id) : undefined;
+    await params.enqueueAuditMessage({
+        chatId,
+        messageId,
+        userId: actorId,
+        text: buildTelegramAuditText({ rawText, hasIncomingAttachment, message }),
+        meta: {
+            kind: "pending",
+            pendingReason: params.reason,
+            updateId: params.update.update_id,
+            chatType: message.chat.type,
+            chatTitle,
+            messageThreadId,
+            username: from?.username,
+            fromIsBot,
+            chatKey,
+        },
+    });
+}
+/**
+ * 补录 callback_query。
+ */
+async function enqueuePendingCallbackQuery(params) {
+    const query = params.update.callback_query;
+    if (!query?.from?.id)
+        return;
+    const chatId = query.message?.chat?.id?.toString?.() || "";
+    if (!chatId)
+        return;
+    const messageThreadId = typeof query.message?.message_thread_id === "number"
+        ? query.message.message_thread_id
+        : undefined;
+    await params.enqueueAuditMessage({
+        chatId,
+        messageId: undefined,
+        userId: query.from?.id ? String(query.from.id) : undefined,
+        text: `[callback_query] ${String(query.data || "").slice(0, 1000)}`.trim(),
+        meta: {
+            kind: "pending",
+            pendingReason: params.reason,
+            updateId: params.update.update_id,
+            messageThreadId,
+            username: query.from?.username,
+        },
+    });
+}
+//# sourceMappingURL=TelegramPendingUpdates.js.map

package/bin/chat/channels/telegram/TelegramPendingUpdates.js.map

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

package/bin/chat/channels/telegram/TelegramPlatformClient.d.ts

@@ -0,0 +1,161 @@
+/**
+ * TelegramPlatformClient：Telegram 平台运行时与 API 门面。
+ *
+ * 关键点（中文）
+ * - 负责 polling、webhook 清理、自愈重试、Bot 信息获取、runtime 状态输出。
+ * - 同时统一封装 Telegram API client 的消息发送与附件下载能力。
+ * - `TelegramBot` 只保留入站授权、命令分发、消息入队等业务编排。
+ */
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatChannelTestResult } from "../../../chat/types/ChannelStatus.js";
+import type { TelegramConfig, TelegramUpdate } from "./Shared.js";
+/**
+ * Telegram 平台 client 构造参数。
+ */
+export interface TelegramPlatformClientOptions {
+    /**
+     * 当前执行上下文。
+     */
+    context: AgentContext;
+    /**
+     * Telegram bot token。
+     */
+    botToken: string;
+    /**
+     * 普通消息回调。
+     */
+    onMessage: (message: TelegramUpdate["message"]) => Promise<void>;
+    /**
+     * callback_query 回调。
+     */
+    onCallbackQuery: (callbackQuery: TelegramUpdate["callback_query"]) => Promise<void>;
+    /**
+     * webhook 冲突自愈后的补偿回调。
+     */
+    onWebhookConflictResolved?: () => Promise<void>;
+}
+/**
+ * Telegram 平台运行时。
+ */
+export declare class TelegramPlatformClient {
+    private readonly logger;
+    private readonly api;
+    private readonly stateStore;
+    private readonly onMessage;
+    private readonly onCallbackQuery;
+    private readonly onWebhookConflictResolved?;
+    private readonly botToken;
+    private lastUpdateId;
+    private pollingInterval;
+    private isRunning;
+    private pollInFlight;
+    private lastDrainAttemptAt;
+    private consecutivePollErrors;
+    private nextPollAllowedAt;
+    private botUsername?;
+    private botId?;
+    private clearedWebhookOnce;
+    constructor(options: TelegramPlatformClientOptions);
+    /**
+     * 返回只读 runtime 快照。
+     */
+    getExecutorStatus(): {
+        running: boolean;
+        linkState: "connected" | "disconnected" | "unknown";
+        statusText: string;
+        detail: Record<string, string | number | boolean | null>;
+    };
+    /**
+     * 获取 bot 用户名。
+     */
+    getBotUsername(): string | undefined;
+    /**
+     * 获取 bot ID。
+     */
+    getBotId(): number | undefined;
+    /**
+     * 连接性测试。
+     */
+    testConnection(): Promise<ChatChannelTestResult>;
+    /**
+     * 启动 polling 前的准备阶段。
+     */
+    preparePolling(): Promise<void>;
+    /**
+     * 启动轮询循环。
+     */
+    startPollingLoop(): void;
+    /**
+     * 拉取当前积压 updates 并交给外部 handler 处理。
+     */
+    drainPendingUpdates(params: {
+        reason: "startup" | "webhook_conflict";
+        handleUpdate: (update: TelegramUpdate) => Promise<void>;
+    }): Promise<number>;
+    /**
+     * 入站轻量 ack reaction。
+     */
+    sendInboundAckReaction(params: {
+        chatId: string;
+        messageId?: number;
+        emoji: string;
+    }): Promise<void>;
+    /**
+     * 发送文本消息。
+     */
+    sendMessage(chatId: string, text: string, opts?: {
+        messageThreadId?: number;
+        replyToMessageId?: number;
+    }): Promise<void>;
+    /**
+     * 发送 inline keyboard 消息。
+     */
+    sendMessageWithInlineKeyboard(chatId: string, text: string, buttons: Array<{
+        text: string;
+        callback_data: string;
+    }>, opts?: {
+        messageThreadId?: number;
+    }): Promise<void>;
+    /**
+     * 发送 chat action。
+     */
+    sendChatAction(chatId: string, action: "typing", opts?: {
+        messageThreadId?: number;
+    }): Promise<void>;
+    /**
+     * 设置消息 reaction。
+     */
+    setMessageReaction(chatId: string, messageId: number, opts?: {
+        emoji?: string;
+        isBig?: boolean;
+    }): Promise<void>;
+    /**
+     * 下载 Telegram 文件。
+     */
+    downloadTelegramFile(fileId: string, suggestedName?: string): Promise<string>;
+    /**
+     * 停止平台运行时。
+     */
+    stop(): Promise<void>;
+    /**
+     * 长轮询入口。
+     */
+    private pollUpdates;
+    /**
+     * 是否属于 polling timeout。
+     */
+    private isPollingTimeoutError;
+    /**
+     * 是否更像网络抖动类错误。
+     */
+    private isLikelyNetworkError;
+    /**
+     * 计算 polling 失败退避时间。
+     */
+    private computePollBackoffMs;
+}
+/**
+ * 创建 Telegram 平台 client。
+ */
+export declare function createTelegramPlatformClient(config: TelegramConfig, options: Omit<TelegramPlatformClientOptions, "botToken">): TelegramPlatformClient | null;
+//# sourceMappingURL=TelegramPlatformClient.d.ts.map

package/bin/chat/channels/telegram/TelegramPlatformClient.d.ts.map

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

package/bin/chat/channels/telegram/TelegramPlatformClient.js

@@ -0,0 +1,366 @@
+/**
+ * TelegramPlatformClient：Telegram 平台运行时与 API 门面。
+ *
+ * 关键点（中文）
+ * - 负责 polling、webhook 清理、自愈重试、Bot 信息获取、runtime 状态输出。
+ * - 同时统一封装 Telegram API client 的消息发送与附件下载能力。
+ * - `TelegramBot` 只保留入站授权、命令分发、消息入队等业务编排。
+ */
+import { TelegramApiClient } from "./ApiClient.js";
+import { TelegramStateStore } from "./StateStore.js";
+/**
+ * Telegram 平台运行时。
+ */
+export class TelegramPlatformClient {
+    logger;
+    api;
+    stateStore;
+    onMessage;
+    onCallbackQuery;
+    onWebhookConflictResolved;
+    botToken;
+    lastUpdateId = 0;
+    pollingInterval = null;
+    isRunning = false;
+    pollInFlight = false;
+    lastDrainAttemptAt = 0;
+    consecutivePollErrors = 0;
+    nextPollAllowedAt = 0;
+    botUsername;
+    botId;
+    clearedWebhookOnce = false;
+    constructor(options) {
+        this.logger = options.context.logger;
+        this.botToken = options.botToken;
+        this.api = new TelegramApiClient({
+            botToken: options.botToken,
+            projectRoot: options.context.rootPath,
+            logger: options.context.logger,
+        });
+        this.stateStore = new TelegramStateStore(options.context.rootPath);
+        this.onMessage = options.onMessage;
+        this.onCallbackQuery = options.onCallbackQuery;
+        this.onWebhookConflictResolved = options.onWebhookConflictResolved;
+    }
+    /**
+     * 返回只读 runtime 快照。
+     */
+    getExecutorStatus() {
+        const running = this.isRunning;
+        const linkState = running && (typeof this.botId === "number" || !!this.botUsername)
+            ? "connected"
+            : running
+                ? "unknown"
+                : "disconnected";
+        return {
+            running,
+            linkState,
+            statusText: linkState === "connected"
+                ? "polling"
+                : linkState === "unknown"
+                    ? "starting"
+                    : "stopped",
+            detail: {
+                pollInFlight: this.pollInFlight,
+                lastUpdateId: this.lastUpdateId,
+                consecutivePollErrors: this.consecutivePollErrors,
+                nextPollAllowedAt: this.nextPollAllowedAt || null,
+                botUsername: this.botUsername || null,
+                botId: typeof this.botId === "number" ? this.botId : null,
+            },
+        };
+    }
+    /**
+     * 获取 bot 用户名。
+     */
+    getBotUsername() {
+        return this.botUsername;
+    }
+    /**
+     * 获取 bot ID。
+     */
+    getBotId() {
+        return this.botId;
+    }
+    /**
+     * 连接性测试。
+     */
+    async testConnection() {
+        const startedAt = Date.now();
+        if (!this.botToken) {
+            return {
+                channel: "telegram",
+                success: false,
+                testedAtMs: startedAt,
+                message: "Bot token is missing",
+            };
+        }
+        try {
+            const me = await this.api.requestJson("getMe", {});
+            const now = Date.now();
+            return {
+                channel: "telegram",
+                success: true,
+                testedAtMs: now,
+                latencyMs: now - startedAt,
+                message: `Connected as @${String(me.username || "unknown")}`,
+                detail: {
+                    botId: typeof me.id === "number" ? me.id : null,
+                    botUsername: me.username || null,
+                },
+            };
+        }
+        catch (error) {
+            const now = Date.now();
+            return {
+                channel: "telegram",
+                success: false,
+                testedAtMs: now,
+                latencyMs: now - startedAt,
+                message: `Telegram API check failed: ${String(error)}`,
+            };
+        }
+    }
+    /**
+     * 启动 polling 前的准备阶段。
+     */
+    async preparePolling() {
+        this.isRunning = true;
+        const lastUpdateId = await this.stateStore.loadLastUpdateId();
+        if (typeof lastUpdateId === "number" && lastUpdateId > 0) {
+            this.lastUpdateId = lastUpdateId;
+        }
+        try {
+            await this.api.requestJson("deleteWebhook", {
+                drop_pending_updates: false,
+            });
+            this.clearedWebhookOnce = true;
+            this.logger.info("Telegram webhook cleared (polling mode)");
+        }
+        catch (error) {
+            this.logger.warn("Failed to clear Telegram webhook (continuing)", {
+                error: String(error),
+            });
+        }
+        const me = await this.api.requestJson("getMe", {});
+        this.botUsername = me.username || undefined;
+        this.botId = typeof me.id === "number" ? me.id : undefined;
+        this.logger.info(`Bot username: @${me.username || "unknown"}`);
+    }
+    /**
+     * 启动轮询循环。
+     */
+    startPollingLoop() {
+        this.consecutivePollErrors = 0;
+        this.nextPollAllowedAt = 0;
+        this.pollingInterval = setInterval(() => {
+            void this.pollUpdates();
+        }, 1000);
+        this.logger.info("Telegram Bot started");
+    }
+    /**
+     * 拉取当前积压 updates 并交给外部 handler 处理。
+     */
+    async drainPendingUpdates(params) {
+        const now = Date.now();
+        if (now - this.lastDrainAttemptAt < 30_000)
+            return 0;
+        this.lastDrainAttemptAt = now;
+        let drained = 0;
+        try {
+            for (let i = 0; i < 50; i++) {
+                const updates = await this.api.requestJson("getUpdates", {
+                    offset: this.lastUpdateId + 1,
+                    limit: 100,
+                    timeout: 0,
+                });
+                if (!Array.isArray(updates) || updates.length === 0)
+                    break;
+                for (const update of updates) {
+                    this.lastUpdateId = Math.max(this.lastUpdateId, update.update_id);
+                    await params.handleUpdate(update);
+                }
+                drained += updates.length;
+            }
+            await this.stateStore.saveLastUpdateId(this.lastUpdateId);
+            return drained;
+        }
+        catch (error) {
+            this.logger.warn("Failed to drain pending Telegram updates to queue", {
+                error: String(error),
+                reason: params.reason,
+            });
+            return drained;
+        }
+    }
+    /**
+     * 入站轻量 ack reaction。
+     */
+    async sendInboundAckReaction(params) {
+        if (!params.messageId)
+            return;
+        try {
+            await this.api.setMessageReaction(params.chatId, params.messageId, {
+                emoji: params.emoji,
+            });
+        }
+        catch (error) {
+            this.logger.warn("Telegram 入站 ack reaction 失败，继续处理消息", {
+                chatId: params.chatId,
+                messageId: params.messageId,
+                error: String(error),
+            });
+        }
+    }
+    /**
+     * 发送文本消息。
+     */
+    async sendMessage(chatId, text, opts) {
+        await this.api.sendMessage(chatId, text, opts);
+    }
+    /**
+     * 发送 inline keyboard 消息。
+     */
+    async sendMessageWithInlineKeyboard(chatId, text, buttons, opts) {
+        await this.api.sendMessageWithInlineKeyboard(chatId, text, buttons, opts);
+    }
+    /**
+     * 发送 chat action。
+     */
+    async sendChatAction(chatId, action, opts) {
+        await this.api.sendChatAction(chatId, action, opts);
+    }
+    /**
+     * 设置消息 reaction。
+     */
+    async setMessageReaction(chatId, messageId, opts) {
+        await this.api.setMessageReaction(chatId, messageId, opts);
+    }
+    /**
+     * 下载 Telegram 文件。
+     */
+    async downloadTelegramFile(fileId, suggestedName) {
+        return await this.api.downloadTelegramFile(fileId, suggestedName);
+    }
+    /**
+     * 停止平台运行时。
+     */
+    async stop() {
+        this.isRunning = false;
+        if (this.pollingInterval) {
+            clearInterval(this.pollingInterval);
+        }
+        this.consecutivePollErrors = 0;
+        this.nextPollAllowedAt = 0;
+        this.logger.info("Telegram Bot stopped");
+    }
+    /**
+     * 长轮询入口。
+     */
+    async pollUpdates() {
+        if (!this.isRunning)
+            return;
+        if (this.pollInFlight)
+            return;
+        if (Date.now() < this.nextPollAllowedAt)
+            return;
+        this.pollInFlight = true;
+        try {
+            const updates = await this.api.requestJson("getUpdates", {
+                offset: this.lastUpdateId + 1,
+                limit: 10,
+                timeout: 30,
+            });
+            if (this.consecutivePollErrors > 0) {
+                this.logger.info(`Telegram polling recovered after ${this.consecutivePollErrors} failed attempt(s)`);
+            }
+            this.consecutivePollErrors = 0;
+            this.nextPollAllowedAt = 0;
+            for (const update of updates) {
+                this.lastUpdateId = Math.max(this.lastUpdateId, update.update_id);
+            }
+            await this.stateStore.saveLastUpdateId(this.lastUpdateId);
+            for (const update of updates) {
+                try {
+                    if (update.message) {
+                        await this.onMessage(update.message);
+                    }
+                    else if (update.callback_query) {
+                        await this.onCallbackQuery(update.callback_query);
+                    }
+                }
+                catch (error) {
+                    this.logger.error(`Failed to process message (update_id: ${update.update_id})`, { error: String(error) });
+                }
+            }
+        }
+        catch (error) {
+            const msg = error?.message || String(error);
+            if (!this.isPollingTimeoutError(msg)) {
+                const looksLikeWebhookConflict = /webhook/i.test(msg) || /Conflict/i.test(msg) || /getUpdates/i.test(msg);
+                if (!this.clearedWebhookOnce && looksLikeWebhookConflict) {
+                    try {
+                        await this.api.requestJson("deleteWebhook", {
+                            drop_pending_updates: false,
+                        });
+                        this.clearedWebhookOnce = true;
+                        this.logger.warn("Telegram polling conflict detected; cleared webhook and will retry", { error: msg });
+                        await this.onWebhookConflictResolved?.();
+                        this.consecutivePollErrors = 0;
+                        this.nextPollAllowedAt = 0;
+                        return;
+                    }
+                    catch (clearError) {
+                        this.logger.error("Telegram polling conflict detected; failed to clear webhook", { error: msg, clearError: String(clearError) });
+                    }
+                }
+                this.consecutivePollErrors += 1;
+                const backoffMs = this.computePollBackoffMs(this.consecutivePollErrors);
+                this.nextPollAllowedAt = Date.now() + backoffMs;
+                const retryInSeconds = Math.ceil(backoffMs / 1000);
+                if (this.isLikelyNetworkError(msg)) {
+                    this.logger.warn(`Telegram polling network error, retrying in ${retryInSeconds}s: ${msg}`);
+                }
+                else {
+                    this.logger.error(`Telegram polling error, retrying in ${retryInSeconds}s: ${msg}`);
+                }
+            }
+        }
+        finally {
+            this.pollInFlight = false;
+        }
+    }
+    /**
+     * 是否属于 polling timeout。
+     */
+    isPollingTimeoutError(message) {
+        return /timeout/i.test(String(message || ""));
+    }
+    /**
+     * 是否更像网络抖动类错误。
+     */
+    isLikelyNetworkError(message) {
+        return /fetch failed|network|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up|TLS/i.test(String(message || ""));
+    }
+    /**
+     * 计算 polling 失败退避时间。
+     */
+    computePollBackoffMs(failureCount) {
+        const safeFailureCount = Number.isFinite(failureCount) ? failureCount : 1;
+        const exponent = Math.max(0, safeFailureCount - 1);
+        return Math.min(30_000, 1_000 * Math.pow(2, exponent));
+    }
+}
+/**
+ * 创建 Telegram 平台 client。
+ */
+export function createTelegramPlatformClient(config, options) {
+    if (!config.enabled || !config.botToken || config.botToken === "${}") {
+        return null;
+    }
+    return new TelegramPlatformClient({
+        ...options,
+        botToken: config.botToken,
+    });
+}
+//# sourceMappingURL=TelegramPlatformClient.js.map