@downcity/plugins 1.0.4

package/src/chat/channels/telegram/Bot.ts

@@ -0,0 +1,357 @@
+/**
+ * Telegram 渠道门面。
+ *
+ * 关键点（中文）
+ * - `TelegramBot` 只保留入站授权、命令分发、消息入队与回复编排。
+ * - polling、runtime 状态、webhook 清理、自愈重试已下沉到 `TelegramPlatformClient`。
+ * - chatKey / audit / mention 清理 / 附件保存已下沉到 `TelegramInbound`。
+ */
+
+import { BaseChatChannel } from "@/chat/channels/BaseChatChannel.js";
+import type {
+  ChannelChatKeyParams,
+  ChannelSendActionParams,
+  ChannelSendTextParams,
+} from "@/chat/channels/BaseChatChannel.js";
+import {
+  handleTelegramCallbackQuery,
+  handleTelegramCommand,
+} from "./Handlers.js";
+import {
+  type TelegramConfig,
+  type TelegramUpdate,
+  type TelegramUser,
+} from "./Shared.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { ChatChannelTestResult } from "@/chat/types/ChannelStatus.js";
+import {
+  buildTelegramChatKey,
+  parseTelegramMessageId,
+} from "./TelegramInbound.js";
+import { TelegramPlatformClient } from "./TelegramPlatformClient.js";
+import {
+  drainTelegramPendingUpdatesToHistory,
+  type TelegramPendingDrainReason,
+} from "./TelegramPendingUpdates.js";
+import { handleTelegramMessage } from "./TelegramMessageHandler.js";
+
+/**
+ * Telegram 平台适配器。
+ */
+export class TelegramBot extends BaseChatChannel {
+  /**
+   * 入站确认 reaction。
+   */
+  private static readonly INBOUND_ACK_EMOJI = "👀";
+
+  private readonly botToken: string;
+  private readonly platform: TelegramPlatformClient;
+
+  constructor(context: AgentContext, botToken: string) {
+    super({ channel: "telegram", context });
+    this.botToken = botToken;
+    this.platform = new TelegramPlatformClient({
+      context,
+      botToken,
+      onMessage: async (message) => {
+        await this.handleMessage(message);
+      },
+      onCallbackQuery: async (callbackQuery) => {
+        await this.handleCallbackQuery(callbackQuery);
+      },
+      onWebhookConflictResolved: async () => {
+        await this.drainPendingUpdatesToHistory({ reason: "webhook_conflict" });
+      },
+    });
+  }
+
+  protected getChatKey(params: ChannelChatKeyParams): string {
+    return buildTelegramChatKey(params.chatId, params.messageThreadId);
+  }
+
+  protected async sendTextToPlatform(
+    params: ChannelSendTextParams,
+  ): Promise<void> {
+    const replyToMessageId =
+      params.replyToMessage === true
+        ? parseTelegramMessageId(params.messageId)
+        : undefined;
+    await this.sendMessage(params.chatId, params.text, {
+      messageThreadId: params.messageThreadId,
+      ...(typeof replyToMessageId === "number" ? { replyToMessageId } : {}),
+    });
+  }
+
+  /**
+   * Telegram 支持 chat action（typing / react）。
+   */
+  protected async sendActionToPlatform(
+    params: ChannelSendActionParams,
+  ): Promise<void> {
+    if (params.action === "typing") {
+      await this.platform.sendChatAction(params.chatId, "typing", {
+        messageThreadId: params.messageThreadId,
+      });
+      return;
+    }
+    if (params.action !== "react") return;
+
+    const messageId = parseTelegramMessageId(params.messageId);
+    if (!messageId) {
+      throw new Error(
+        "Telegram reaction requires a numeric messageId. Provide --message-id or ensure chat meta has latest messageId.",
+      );
+    }
+    await this.platform.setMessageReaction(params.chatId, messageId, {
+      emoji: params.reactionEmoji,
+      isBig: params.reactionIsBig === true,
+    });
+  }
+
+  /**
+   * 兼容旧的 per-chat locking 入口。
+   */
+  private runInChat(_chatKey: string, fn: () => Promise<void>): Promise<void> {
+    return fn();
+  }
+
+  /**
+   * 读取 runtime 快照。
+   */
+  getExecutorStatus(): {
+    running: boolean;
+    linkState: "connected" | "disconnected" | "unknown";
+    statusText: string;
+    detail: Record<string, string | number | boolean | null>;
+  } {
+    return this.platform.getExecutorStatus();
+  }
+
+  /**
+   * 连接性测试。
+   */
+  async testConnection(): Promise<ChatChannelTestResult> {
+    return await this.platform.testConnection();
+  }
+
+  /**
+   * 启动 Telegram polling。
+   */
+  async start(): Promise<void> {
+    if (!this.botToken) {
+      this.logger.warn("Telegram Bot Token not configured, skipping startup");
+      return;
+    }
+
+    this.logger.info("🤖 Starting Telegram Bot...");
+    try {
+      await this.platform.preparePolling();
+      await this.drainPendingUpdatesToHistory({ reason: "startup" });
+      this.platform.startPollingLoop();
+    } catch (error) {
+      this.logger.error("Failed to start Telegram Bot", {
+        error: String(error),
+      });
+      await this.platform.stop();
+    }
+  }
+
+  /**
+   * 把离线期间积压 updates 只入队，不执行/不回复。
+   */
+  private async drainPendingUpdatesToHistory(params: {
+    reason: TelegramPendingDrainReason;
+  }): Promise<void> {
+    await drainTelegramPendingUpdatesToHistory({
+      reason: params.reason,
+      platform: this.platform,
+      logger: this.logger,
+      enqueueAuditMessage: async (message) => {
+        await this.enqueueAuditMessage(message);
+      },
+    });
+  }
+
+  /**
+   * 处理普通消息。
+   */
+  private async handleMessage(
+    message: TelegramUpdate["message"],
+  ): Promise<void> {
+    await handleTelegramMessage(
+      {
+        context: this.context,
+        rootPath: this.rootPath,
+        logger: this.logger,
+        inboundAckEmoji: TelegramBot.INBOUND_ACK_EMOJI,
+        platform: this.platform,
+        observeIncomingAuthorization: async (params) => {
+          await this.observeIncomingAuthorization(params);
+        },
+        evaluateIncomingAuthorization: async (params) =>
+          await this.evaluateIncomingAuthorization(params),
+        sendAuthorizationText: async (params) => {
+          await this.sendAuthorizationText(params);
+        },
+        buildUnauthorizedBlockedText: (params) =>
+          this.buildUnauthorizedBlockedText(params),
+        enqueueAuditMessage: async (params) => {
+          await this.enqueueAuditMessage(params);
+        },
+        runInChat: async (chatKey, fn) => {
+          await this.runInChat(chatKey, fn);
+        },
+        handleCommand: async (params) => {
+          await this.handleCommand(
+            params.chatId,
+            params.command,
+            params.from,
+            params.messageThreadId,
+          );
+        },
+        executeAndReply: async (params) => {
+          await this.executeAndReply(
+            params.chatId,
+            params.instructions,
+            params.from,
+            params.chatTitle,
+            params.messageId,
+            params.chatType,
+            params.messageThreadId,
+            params.extra,
+          );
+        },
+      },
+      message,
+    );
+  }
+
+  /**
+   * 命令分发。
+   */
+  private async handleCommand(
+    chatId: string,
+    command: string,
+    from?: TelegramUser,
+    messageThreadId?: number,
+  ): Promise<void> {
+    await handleTelegramCommand(
+      {
+        logger: this.logger,
+        sendMessage: (chatIdInput, text, opts) =>
+          this.sendMessage(chatIdInput, text, opts),
+        clearChat: async (chatIdInput, threadIdInput) => {
+          await this.clearChatByTarget({
+            chatId: chatIdInput,
+            ...(typeof threadIdInput === "number"
+              ? { messageThreadId: threadIdInput }
+              : {}),
+          });
+        },
+      },
+      { chatId, command, from, messageThreadId },
+    );
+  }
+
+  /**
+   * callback_query 分发。
+   */
+  private async handleCallbackQuery(
+    callbackQuery: TelegramUpdate["callback_query"],
+  ): Promise<void> {
+    await handleTelegramCallbackQuery(
+      {
+        logger: this.logger,
+        sendMessage: (chatIdInput, text, opts) =>
+          this.sendMessage(chatIdInput, text, opts),
+        clearChat: async (chatIdInput, threadIdInput) => {
+          await this.clearChatByTarget({
+            chatId: chatIdInput,
+            ...(typeof threadIdInput === "number"
+              ? { messageThreadId: threadIdInput }
+              : {}),
+          });
+        },
+      },
+      callbackQuery,
+    );
+  }
+
+  /**
+   * 执行并回复。
+   */
+  private async executeAndReply(
+    chatId: string,
+    instructions: string,
+    from?: TelegramUser,
+    chatTitle?: string,
+    messageId?: string,
+    chatType?: NonNullable<TelegramUpdate["message"]>["chat"]["type"],
+    messageThreadId?: number,
+    extra?: JsonObject,
+  ): Promise<void> {
+    try {
+      const userId = from?.id ? String(from.id) : undefined;
+      const username = from?.username ? String(from.username) : undefined;
+      await this.enqueueMessage({
+        chatId,
+        text: instructions,
+        chatType,
+        messageId,
+        messageThreadId,
+        userId,
+        username,
+        chatTitle,
+        ...(extra ? { extra } : {}),
+      });
+    } catch (error) {
+      await this.sendMessage(chatId, `❌ Execution error: ${String(error)}`, {
+        messageThreadId,
+      });
+    }
+  }
+
+  /**
+   * 发送普通消息。
+   */
+  async sendMessage(
+    chatId: string,
+    text: string,
+    opts?: { messageThreadId?: number; replyToMessageId?: number },
+  ): Promise<void> {
+    await this.platform.sendMessage(chatId, text, opts);
+  }
+
+  /**
+   * 发送 inline keyboard。
+   */
+  async sendMessageWithInlineKeyboard(
+    chatId: string,
+    text: string,
+    buttons: Array<{ text: string; callback_data: string }>,
+    opts?: { messageThreadId?: number },
+  ): Promise<void> {
+    await this.platform.sendMessageWithInlineKeyboard(chatId, text, buttons, opts);
+  }
+
+  /**
+   * 停止 Telegram bot。
+   */
+  async stop(): Promise<void> {
+    await this.platform.stop();
+  }
+}
+
+/**
+ * 创建 Telegram bot。
+ */
+export function createTelegramBot(
+  config: TelegramConfig,
+  context: AgentContext,
+): TelegramBot | null {
+  if (!config.enabled || !config.botToken || config.botToken === "${}") {
+    return null;
+  }
+  return new TelegramBot(context, config.botToken);
+}

package/src/chat/channels/telegram/BotInfo.ts

@@ -0,0 +1,92 @@
+/**
+ * Telegram Bot 信息探测实现。
+ *
+ * 关键点（中文）
+ * - 基于 `getMe` 接口验证 token 有效性。
+ * - 返回统一结构，供 channel account 创建流程复用。
+ */
+
+import type {
+  ChatBotInfoCredentialInput,
+  ChatBotInfoResult,
+  ChatChannelBotInfoProvider,
+} from "@/chat/types/BotInfo.js";
+
+function pickFirstNonEmpty(inputs: unknown[]): string {
+  for (const input of inputs) {
+    const text = String(input || "").trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * Telegram 渠道 Bot 信息探测器。
+ */
+export class TelegramBotInfoProvider implements ChatChannelBotInfoProvider {
+  readonly channel = "telegram" as const;
+
+  /**
+   * 探测 Telegram bot 信息。
+   */
+  async resolve(credentials: ChatBotInfoCredentialInput): Promise<ChatBotInfoResult> {
+    const botToken = String(credentials.botToken || "").trim();
+    if (!botToken) {
+      throw new Error("Missing botToken");
+    }
+
+    const response = await fetch(`https://api.telegram.org/bot${botToken}/getMe`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+    });
+    const raw = await response.text();
+    let payload: {
+      ok?: boolean;
+      result?: {
+        id?: number | string;
+        username?: string;
+        first_name?: string;
+        last_name?: string;
+      };
+      description?: string;
+      error_code?: number;
+    } = {};
+    try {
+      payload = JSON.parse(raw) as typeof payload;
+    } catch {
+      payload = {};
+    }
+
+    if (!response.ok || payload.ok !== true) {
+      const details = String(payload.description || raw || "unknown error").trim();
+      throw new Error(`Telegram bot info probe failed: ${details}`);
+    }
+
+    const botUserId = String(payload.result?.id || "").trim();
+    const username = String(payload.result?.username || "").trim();
+    const firstName = String(payload.result?.first_name || "").trim();
+    const lastName = String(payload.result?.last_name || "").trim();
+    const fullName = [firstName, lastName].filter(Boolean).join(" ").trim();
+
+    const name = pickFirstNonEmpty([
+      username ? `@${username.replace(/^@+/, "")}` : "",
+      fullName,
+      botUserId ? `Telegram Bot ${botUserId.slice(-6)}` : "",
+      "Telegram Bot",
+    ]);
+    const identity = pickFirstNonEmpty([
+      username ? `@${username.replace(/^@+/, "")}` : "",
+      botUserId,
+    ]);
+
+    return {
+      channel: this.channel,
+      name,
+      identity: identity || undefined,
+      botUserId: botUserId || undefined,
+      idSeed: pickFirstNonEmpty([username, botUserId, "bot"]),
+      message: "Telegram bot profile fetched",
+    };
+  }
+}

package/src/chat/channels/telegram/Configuration.ts

@@ -0,0 +1,65 @@
+/**
+ * Telegram 渠道配置描述。
+ *
+ * 关键点（中文）
+ * - ship 层只绑定 `enabled` 与 `channelAccountId`。
+ * - 真实密钥由 channel account 统一托管。
+ */
+
+import { ChatChannelConfiguration } from "@/chat/channels/Configuration.js";
+import type { ChatChannelConfigurationDescriptor } from "@/chat/types/ChannelConfiguration.js";
+
+/**
+ * Telegram 渠道配置描述器。
+ */
+export class TelegramChannelConfiguration extends ChatChannelConfiguration {
+  readonly channel = "telegram" as const;
+
+  describe(): ChatChannelConfigurationDescriptor {
+    return {
+      channel: this.channel,
+      title: "Telegram Channel Configuration",
+      description:
+        "Bind a Telegram channel account and control runtime enable/disable state.",
+      version: "1.0.0",
+      capabilities: {
+        canToggleEnabled: true,
+        canBindChannelAccount: true,
+        canConfigure: true,
+      },
+      fields: {
+        ship: [
+          {
+            key: "enabled",
+            label: "Enabled",
+            description:
+              "Whether telegram channel should be started by runtime.",
+            type: "boolean",
+            source: "ship_json",
+            required: false,
+            nullable: false,
+            writable: true,
+            restartRequired: true,
+            defaultValue: false,
+            example: true,
+          },
+          {
+            key: "channelAccountId",
+            label: "Channel Account ID",
+            description:
+              "Bind channel to a channel account row in ~/.downcity/downcity.db channel_accounts.",
+            type: "string",
+            source: "ship_json",
+            required: false,
+            nullable: true,
+            writable: true,
+            restartRequired: true,
+            example: "telegram-main",
+          },
+        ],
+        channelAccount: [],
+        envFallback: [],
+      },
+    };
+  }
+}

package/src/chat/channels/telegram/Handlers.ts

@@ -0,0 +1,91 @@
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { TelegramUpdate, TelegramUser } from "./Shared.js";
+
+/**
+ * Telegram command/callback handlers。
+ *
+ * 关键点（中文）
+ * - handler 通过参数接收 logger，不依赖全局 runtime
+ * - 方便在不同运行环境复用（server / test）
+ */
+
+/**
+ * Telegram 指令处理上下文。
+ *
+ * 说明（中文）
+ * - 采用显式注入，避免 handler 反向依赖 server / core 单例
+ */
+export type TelegramHandlerContext = {
+  logger: Logger;
+  sendMessage: (
+    chatId: string,
+    text: string,
+    opts?: { messageThreadId?: number },
+  ) => Promise<void>;
+  clearChat: (chatId: string, messageThreadId?: number) => Promise<void>;
+};
+
+/**
+ * 处理 Telegram 斜杠命令。
+ *
+ * 说明（中文）
+ * - 当前只处理少量内置命令，其他消息走常规会话链路
+ */
+export async function handleTelegramCommand(
+  ctx: TelegramHandlerContext,
+  params: {
+    chatId: string;
+    command: string;
+    from?: TelegramUser;
+    messageThreadId?: number;
+  },
+): Promise<void> {
+  const username = params.from?.username || "Unknown";
+  ctx.logger.info(`Received command: ${params.command} (${username})`);
+
+  const [commandToken] = params.command.trim().split(/\s+/);
+  const cmd = (commandToken || "").split("@")[0]?.toLowerCase();
+
+  switch (cmd) {
+    case "/start":
+    case "/help":
+      await ctx.sendMessage(
+        params.chatId,
+        `🤖 Downcity Bot
+
+Available commands:
+- /status - View agent status
+- /clear - Delete conversation completely
+- <any message> - Execute instruction`,
+      );
+      break;
+
+    case "/status":
+      await ctx.sendMessage(params.chatId, "📊 Agent status: Running");
+      break;
+
+    case "/clear":
+      await ctx.clearChat(params.chatId, params.messageThreadId);
+      await ctx.sendMessage(params.chatId, "✅ Conversation deleted completely", {
+        messageThreadId: params.messageThreadId,
+      });
+      break;
+
+    default:
+      await ctx.sendMessage(params.chatId, `Unknown command: ${params.command}`);
+  }
+}
+
+/**
+ * 处理 callback_query（按钮回调）。
+ *
+ * 当前策略（中文）
+ * - 预留扩展点；默认不执行任何业务逻辑
+ */
+export async function handleTelegramCallbackQuery(
+  ctx: TelegramHandlerContext,
+  callbackQuery: TelegramUpdate["callback_query"],
+): Promise<void> {
+  void ctx;
+  void callbackQuery;
+}

package/src/chat/channels/telegram/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/chat/channels/telegram/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "\n\n";
+
+export default TEXT_MODULE_CONTENT;

package/src/chat/channels/telegram/PROMPT.direct.ts.txt

@@ -0,0 +1,2 @@
+
+

package/src/chat/channels/telegram/ReplyContext.ts

@@ -0,0 +1,76 @@
+/**
+ * Telegram reply 引用上下文提取。
+ *
+ * 关键点（中文）
+ * - 直接从 `reply_to_message` / `quote` 提取可执行上下文。
+ * - 不依赖额外 API 回查，保证处理链路轻量稳定。
+ */
+
+import type { InboundReplyContext } from "@/chat/types/ReplyContext.js";
+import {
+  getActorName,
+  type TelegramUpdate,
+} from "./Shared.js";
+
+type TelegramReplyMessageLike = {
+  text?: string;
+  caption?: string;
+  document?: unknown;
+  photo?: unknown[];
+  voice?: unknown;
+  audio?: unknown;
+  video?: unknown;
+};
+
+function describeTelegramMessage(
+  message: TelegramReplyMessageLike | undefined,
+): string | undefined {
+  const rawText =
+    typeof message?.text === "string"
+      ? message.text
+      : typeof message?.caption === "string"
+        ? message.caption
+        : "";
+  const normalizedText = rawText.trim();
+  if (normalizedText) return normalizedText;
+
+  const attachmentTypes: string[] = [];
+  if (message?.document) attachmentTypes.push("document");
+  if (Array.isArray(message?.photo) && message.photo.length > 0) {
+    attachmentTypes.push("photo");
+  }
+  if (message?.voice) attachmentTypes.push("voice");
+  if (message?.audio) attachmentTypes.push("audio");
+  if (message?.video) attachmentTypes.push("video");
+
+  const uniqTypes = Array.from(new Set(attachmentTypes)).filter(Boolean);
+  if (uniqTypes.length === 0) return undefined;
+  return `[attachment] (${uniqTypes.join(", ")})`;
+}
+
+/**
+ * 提取 Telegram reply 上下文。
+ */
+export function extractTelegramReplyContext(
+  message: TelegramUpdate["message"] | undefined,
+): InboundReplyContext | undefined {
+  const replied = message?.reply_to_message;
+  if (!replied) return undefined;
+
+  const messageId =
+    typeof replied.message_id === "number" && Number.isFinite(replied.message_id)
+      ? String(replied.message_id)
+      : undefined;
+  const actorName = getActorName(replied.from);
+  const text = describeTelegramMessage(replied);
+  const quoteText =
+    typeof message?.quote?.text === "string" ? message.quote.text.trim() : undefined;
+
+  if (!messageId && !actorName && !text && !quoteText) return undefined;
+  return {
+    ...(messageId ? { messageId } : {}),
+    ...(actorName ? { actorName } : {}),
+    ...(text ? { text } : {}),
+    ...(quoteText ? { quoteText } : {}),
+  };
+}