@downcity/plugins 1.0.4

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

@@ -0,0 +1,404 @@
+import path from "path";
+import { parseChatMessageMarkup } from "@downcity/agent/internal/executor/messages/ChatMessageMarkup.js";
+
+/**
+ * Telegram 集成配置。
+ */
+export interface TelegramConfig {
+  botToken?: string;
+  enabled: boolean;
+}
+
+/**
+ * Telegram Update 结构（仅保留当前项目需要字段）。
+ */
+export interface TelegramUpdate {
+  update_id: number;
+  message?: {
+    message_id?: number;
+    message_thread_id?: number;
+    text?: string;
+    caption?: string;
+    quote?: {
+      text?: string;
+    };
+    chat: {
+      id: number;
+      type?: "private" | "group" | "supergroup" | "channel";
+      title?: string;
+      username?: string;
+      first_name?: string;
+      last_name?: string;
+    };
+    document?: {
+      file_id: string;
+      file_name?: string;
+      mime_type?: string;
+      file_size?: number;
+    };
+    photo?: Array<{
+      file_id: string;
+      width?: number;
+      height?: number;
+      file_size?: number;
+    }>;
+    voice?: {
+      file_id: string;
+      mime_type?: string;
+      file_size?: number;
+      duration?: number;
+    };
+    audio?: {
+      file_id: string;
+      file_name?: string;
+      mime_type?: string;
+      file_size?: number;
+      duration?: number;
+    };
+    video?: {
+      file_id: string;
+      file_name?: string;
+      mime_type?: string;
+      file_size?: number;
+      duration?: number;
+      width?: number;
+      height?: number;
+    };
+    reply_to_message?: {
+      message_id?: number;
+      text?: string;
+      caption?: string;
+      document?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+        file_size?: number;
+      };
+      photo?: Array<{
+        file_id: string;
+        width?: number;
+        height?: number;
+        file_size?: number;
+      }>;
+      voice?: {
+        file_id: string;
+        mime_type?: string;
+        file_size?: number;
+        duration?: number;
+      };
+      audio?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+        file_size?: number;
+        duration?: number;
+      };
+      video?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+        file_size?: number;
+        duration?: number;
+        width?: number;
+        height?: number;
+      };
+      from?: {
+        id: number;
+        username?: string;
+        first_name?: string;
+        last_name?: string;
+      };
+    };
+    from?: {
+      id: number;
+      is_bot?: boolean;
+      username?: string;
+      first_name?: string;
+      last_name?: string;
+    };
+    entities?: Array<{
+      type: string;
+      offset: number;
+      length: number;
+      user?: { id: number; username?: string };
+    }>;
+    caption_entities?: Array<{
+      type: string;
+      offset: number;
+      length: number;
+      user?: { id: number; username?: string };
+    }>;
+  };
+  callback_query?: {
+    id: string;
+    data: string;
+    from?: {
+      id: number;
+      username?: string;
+      first_name?: string;
+      last_name?: string;
+    };
+    message: {
+      message_thread_id?: number;
+      chat: {
+        id: number;
+      };
+    };
+  };
+}
+
+export type TelegramUser = {
+  id: number;
+  is_bot?: boolean;
+  username?: string;
+  first_name?: string;
+  last_name?: string;
+};
+
+/**
+ * Telegram Bot API 通用响应。
+ */
+export interface TelegramApiResponse<T> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+  error_code?: number;
+}
+
+export type TelegramAttachmentType =
+  | "photo"
+  | "document"
+  | "voice"
+  | "audio"
+  | "video";
+
+/**
+ * 清洗用户可见文本，避免直接回显冗长工具日志。
+ */
+export function sanitizeChatText(text: string): string {
+  if (!text) return text;
+
+  let out = text;
+
+  // Remove/compact tool-log style dumps if present
+  out = out.replace(
+    /(^|\n)Tool Result:[\s\S]*?(?=\n{2,}|$)/g,
+    "\n[工具输出已省略：我已在后台读取并提炼关键信息]\n",
+  );
+
+  return out;
+}
+
+export function guessMimeType(fileName: string): string | undefined {
+  const ext = (path.extname(fileName) || "").toLowerCase();
+  switch (ext) {
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    case ".gif":
+      return "image/gif";
+    case ".pdf":
+      return "application/pdf";
+    case ".zip":
+      return "application/zip";
+    case ".mp3":
+      return "audio/mpeg";
+    case ".m4a":
+      return "audio/mp4";
+    case ".ogg":
+      return "audio/ogg";
+    case ".opus":
+      return "audio/opus";
+    case ".mp4":
+      return "video/mp4";
+    case ".mov":
+      return "video/quicktime";
+    case ".webm":
+      return "video/webm";
+    case ".m4v":
+      return "video/x-m4v";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * 从文本中解析 `<file ...>` 附件标签。
+ *
+ * 说明（中文）
+ * - 返回“清理后的正文 + 附件列表 + 有序 segments”
+ * - `<file>` 标签会从正文中移除，便于自然语言与附件混写
+ * - `segments` 会保留正文与附件的真实顺序，供出站逐段发送
+ */
+export function parseTelegramAttachments(text: string): {
+  text: string;
+  attachments: Array<{
+    type: TelegramAttachmentType;
+    pathOrUrl: string;
+    caption?: string;
+  }>;
+  segments: Array<
+    | {
+        kind: "text";
+        text: string;
+      }
+    | {
+        kind: "attachment";
+        attachment: {
+          type: TelegramAttachmentType;
+          pathOrUrl: string;
+          caption?: string;
+        };
+      }
+  >;
+} {
+  const parsed = parseChatMessageMarkup(text);
+  const attachments: Array<{
+    type: TelegramAttachmentType;
+    pathOrUrl: string;
+    caption?: string;
+  }> = parsed.files.map((file) => {
+    const kindRaw = String(file.type || "").toLowerCase();
+    const type: TelegramAttachmentType =
+      kindRaw === "image" || kindRaw === "photo"
+        ? "photo"
+        : kindRaw === "file" || kindRaw === "document"
+          ? "document"
+          : kindRaw === "video"
+            ? "video"
+          : kindRaw === "audio"
+            ? "audio"
+            : "voice";
+
+    const pathOrUrl = String(file.path || "").trim();
+    const caption =
+      typeof file.caption === "string" ? String(file.caption).trim() : undefined;
+    return {
+      type,
+      pathOrUrl,
+      ...(caption ? { caption } : {}),
+    };
+  }).filter((item) => item.pathOrUrl);
+
+  const segments: Array<
+    | {
+        kind: "text";
+        text: string;
+      }
+    | {
+        kind: "attachment";
+        attachment: {
+          type: TelegramAttachmentType;
+          pathOrUrl: string;
+          caption?: string;
+        };
+      }
+  > = [];
+  for (const segment of parsed.segments) {
+    if (segment.kind === "text") {
+      if (segment.text) {
+        segments.push({
+          kind: "text",
+          text: segment.text,
+        });
+      }
+      continue;
+    }
+    const kindRaw = String(segment.file.type || "").toLowerCase();
+    const type: TelegramAttachmentType =
+      kindRaw === "image" || kindRaw === "photo"
+        ? "photo"
+        : kindRaw === "file" || kindRaw === "document"
+          ? "document"
+          : kindRaw === "video"
+            ? "video"
+            : kindRaw === "audio"
+              ? "audio"
+              : "voice";
+    const pathOrUrl = String(segment.file.path || "").trim();
+    if (!pathOrUrl) continue;
+    const caption =
+      typeof segment.file.caption === "string"
+        ? String(segment.file.caption).trim()
+        : undefined;
+    segments.push({
+      kind: "attachment",
+      attachment: {
+        type,
+        pathOrUrl,
+        ...(caption ? { caption } : {}),
+      },
+    });
+  }
+
+  return { text: parsed.bodyText, attachments, segments };
+}
+
+function formatActorName(name: string): string {
+  return name
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/[\[\]]/g, "")
+    .trim();
+}
+
+export function getActorName(from?: {
+  first_name?: string;
+  last_name?: string;
+}): string | undefined {
+  const first = typeof from?.first_name === "string" ? from.first_name.trim() : "";
+  const last = typeof from?.last_name === "string" ? from.last_name.trim() : "";
+  const raw = [first, last].filter(Boolean).join(" ").trim();
+  if (!raw) return undefined;
+  return formatActorName(raw);
+}
+
+/**
+ * 提取 Telegram 会话展示名（群名/频道名/私聊对象名）。
+ *
+ * 关键点（中文）
+ * - 群聊/频道优先取 `chat.title`。
+ * - 私聊优先 username，再回退 first/last name。
+ */
+export function getTelegramChatTitle(chat?: {
+  title?: string;
+  username?: string;
+  first_name?: string;
+  last_name?: string;
+}): string | undefined {
+  const title = typeof chat?.title === "string" ? chat.title.trim() : "";
+  if (title) return title;
+
+  const username = typeof chat?.username === "string" ? chat.username.trim() : "";
+  if (username) return `@${username.replace(/^@+/, "")}`;
+
+  const first = typeof chat?.first_name === "string" ? chat.first_name.trim() : "";
+  const last = typeof chat?.last_name === "string" ? chat.last_name.trim() : "";
+  const full = formatActorName([first, last].filter(Boolean).join(" ").trim());
+  return full || undefined;
+}
+
+/**
+ * 拆分超长消息，避免触发 Telegram 4096 限制。
+ */
+export function splitTelegramMessage(text: string): string[] {
+  const MAX = 3900; // keep headroom under Telegram's 4096 limit
+  if (text.length <= MAX) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > MAX) {
+    let cut = remaining.lastIndexOf("\n", MAX);
+    if (cut < MAX * 0.6) cut = MAX;
+    chunks.push(remaining.slice(0, cut));
+    remaining = remaining.slice(cut);
+  }
+
+  if (remaining.length > 0) chunks.push(remaining);
+  return chunks;
+}

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

@@ -0,0 +1,58 @@
+import path from "path";
+import fs from "fs-extra";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * Telegram 轮询模式的持久化状态存储。
+ *
+ * 关键点（中文）
+ * - 保存 lastUpdateId，避免重启后重复消费
+ * - 所有 I/O 都是 best-effort，不能阻断主流程
+ *
+ * Persistent state for Telegram polling mode.
+ *
+ * Telegram's getUpdates polling relies on a monotonic `offset`. Persisting the
+ * last processed update id avoids re-processing after restarts.
+ *
+ * All I/O in this module is best-effort: failures should not break the bot.
+ */
+export class TelegramStateStore {
+  private readonly lastUpdateIdFile: string;
+
+  constructor(projectRoot: string) {
+    const dir = path.join(projectRoot, ".downcity", ".cache", "telegram");
+    this.lastUpdateIdFile = path.join(dir, "lastUpdateId.json");
+  }
+
+  /**
+   * 读取最后一次处理的 update_id。
+   */
+  async loadLastUpdateId(): Promise<number | undefined> {
+    try {
+      if (!(await fs.pathExists(this.lastUpdateIdFile))) return undefined;
+      const data = (await fs.readJson(this.lastUpdateIdFile)) as JsonObject;
+      const value = Number(data?.lastUpdateId);
+      if (Number.isFinite(value) && value > 0) return value;
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * 持久化最后一次处理的 update_id。
+   */
+  async saveLastUpdateId(lastUpdateId: number): Promise<void> {
+    try {
+      await fs.ensureDir(path.dirname(this.lastUpdateIdFile));
+      await fs.writeJson(
+        this.lastUpdateIdFile,
+        { lastUpdateId },
+        { spaces: 2 },
+      );
+    } catch {
+      // ignore
+    }
+  }
+
+}

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

@@ -0,0 +1,186 @@
+/**
+ * TelegramInbound：Telegram 入站辅助逻辑。
+ *
+ * 关键点（中文）
+ * - 只负责消息 ID 解析、chatKey 构造、审计文本、mention 清理、附件保存。
+ * - 不承担授权、命令分发、消息入队等主流程职责。
+ */
+
+import type { TelegramAttachmentType, TelegramUpdate } from "./Shared.js";
+
+/**
+ * 构建 lane 维度 chatKey。
+ */
+export function buildTelegramChatKey(
+  chatId: string,
+  messageThreadId?: number,
+): string {
+  if (
+    typeof messageThreadId === "number" &&
+    Number.isFinite(messageThreadId) &&
+    messageThreadId > 0
+  ) {
+    return `telegram-chat-${chatId}-topic-${messageThreadId}`;
+  }
+  return `telegram-chat-${chatId}`;
+}
+
+/**
+ * 解析 Telegram 消息 ID。
+ */
+export function parseTelegramMessageId(messageId?: string): number | undefined {
+  const raw = String(messageId || "").trim();
+  if (!raw || !/^\d+$/.test(raw)) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    return undefined;
+  }
+  return parsed;
+}
+
+/**
+ * 是否为群聊。
+ */
+export function isTelegramGroupChat(chatType?: string): boolean {
+  return chatType === "group" || chatType === "supergroup";
+}
+
+/**
+ * 构建可落盘的审计文本。
+ */
+export function buildTelegramAuditText(params: {
+  rawText: string;
+  hasIncomingAttachment: boolean;
+  message: TelegramUpdate["message"];
+}): string {
+  const rawText = String(params.rawText ?? "");
+  if (rawText.trim()) return rawText;
+  if (!params.hasIncomingAttachment) return "[message] (no_text_or_supported_attachment)";
+
+  const types: string[] = [];
+  const message = params.message;
+  if (message?.document) types.push("document");
+  if (Array.isArray(message?.photo) && message.photo.length > 0) types.push("photo");
+  if (message?.voice) types.push("voice");
+  if (message?.audio) types.push("audio");
+  if (message?.video) types.push("video");
+
+  const uniq = Array.from(new Set(types)).filter(Boolean);
+  const suffix = uniq.length > 0 ? ` (${uniq.join(", ")})` : "";
+  return `[attachment]${suffix}`;
+}
+
+/**
+ * 清理 bot mention。
+ */
+export function stripTelegramBotMention(
+  text: string,
+  botUsername?: string,
+): string {
+  if (!text) return text;
+  if (!botUsername) return text.trim();
+  const re = new RegExp(`\\s*@${escapeRegExp(botUsername)}\\b`, "ig");
+  return text.replace(re, " ").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * 保存入站附件到本地缓存。
+ */
+export async function saveTelegramIncomingAttachments(params: {
+  downloader: {
+    downloadTelegramFile: (
+      fileId: string,
+      suggestedName?: string,
+    ) => Promise<string>;
+  };
+  message: TelegramUpdate["message"];
+}): Promise<Array<{ type: TelegramAttachmentType; path: string; desc?: string }>> {
+  const message = params.message;
+  if (!message) return [];
+
+  const items: Array<{
+    type: TelegramAttachmentType;
+    fileId: string;
+    fileName?: string;
+    desc?: string;
+  }> = [];
+
+  if (message.document?.file_id) {
+    items.push({
+      type: "document",
+      fileId: message.document.file_id,
+      fileName: message.document.file_name,
+      desc: message.document.file_name,
+    });
+  }
+
+  const bestPhotoId = pickBestTelegramPhotoFileId(message.photo);
+  if (bestPhotoId) {
+    items.push({
+      type: "photo",
+      fileId: bestPhotoId,
+      fileName: "photo.jpg",
+      desc: "photo",
+    });
+  }
+
+  if (message.voice?.file_id) {
+    items.push({
+      type: "voice",
+      fileId: message.voice.file_id,
+      fileName: "voice.ogg",
+      desc: "voice",
+    });
+  }
+
+  if (message.audio?.file_id) {
+    items.push({
+      type: "audio",
+      fileId: message.audio.file_id,
+      fileName: message.audio.file_name || "audio",
+      desc: message.audio.file_name || "audio",
+    });
+  }
+
+  if (message.video?.file_id) {
+    items.push({
+      type: "video",
+      fileId: message.video.file_id,
+      fileName: message.video.file_name || "video.mp4",
+      desc: message.video.file_name || "video",
+    });
+  }
+
+  if (items.length === 0) return [];
+
+  const out: Array<{ type: TelegramAttachmentType; path: string; desc?: string }> = [];
+  for (const item of items) {
+    const saved = await params.downloader.downloadTelegramFile(
+      item.fileId,
+      item.fileName,
+    );
+    out.push({ type: item.type, path: saved, desc: item.desc });
+  }
+  return out;
+}
+
+/**
+ * 选出最佳 photo file_id。
+ */
+function pickBestTelegramPhotoFileId(
+  photo?: Array<{ file_id?: string; file_size?: number }>,
+): string | undefined {
+  if (!Array.isArray(photo) || photo.length === 0) return undefined;
+  const sorted = [...photo].sort(
+    (a, b) => Number(a?.file_size || 0) - Number(b?.file_size || 0),
+  );
+  const best = sorted[sorted.length - 1];
+  return typeof best?.file_id === "string" ? best.file_id : undefined;
+}
+
+/**
+ * 正则转义。
+ */
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}