@zhin.js/adapter-telegram 3.0.0 → 4.0.0

package/lib/platform-permit.js

@@ -0,0 +1,59 @@
+import { registerPlatformPermitChecker } from 'zhin.js';
+const ADAPTER = 'telegram';
+export function platformPermit(perm) {
+    return `platform(${ADAPTER},${perm})`;
+}
+const FACTORY_PERM_MAP = {
+    group_admin: 'chat_administrator',
+    group_owner: 'chat_creator',
+};
+export function telegramGroupPermitResolver(logicalPerm) {
+    return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+export function normalizeTelegramChatMember(member) {
+    const permissions = [];
+    const status = member.status;
+    if (status === 'creator') {
+        permissions.push('chat_creator', 'chat_administrator', 'restrict_members', 'pin_messages');
+        return { role: 'creator', permissions };
+    }
+    if (status === 'administrator') {
+        permissions.push('chat_administrator');
+        if (member.can_restrict_members)
+            permissions.push('restrict_members');
+        if (member.can_pin_messages)
+            permissions.push('pin_messages');
+        if (member.can_delete_messages)
+            permissions.push('delete_messages');
+        if (member.can_manage_chat)
+            permissions.push('manage_chat');
+        return { role: 'administrator', permissions };
+    }
+    return { role: 'member', permissions };
+}
+function senderPermits(message) {
+    const sender = message.$sender;
+    return { role: sender.role, permissions: sender.permissions ?? [] };
+}
+export function checkTelegramPlatformPermit(perm, message) {
+    const { role, permissions } = senderPermits(message);
+    const has = (t) => permissions.includes(t);
+    switch (perm) {
+        case 'chat_creator':
+            return role === 'creator' || has('chat_creator');
+        case 'chat_administrator':
+            return role === 'creator' || role === 'administrator' || has('chat_administrator');
+        case 'restrict_members':
+            return has('restrict_members') || role === 'creator';
+        case 'pin_messages':
+            return has('pin_messages') || role === 'creator';
+        case 'manage_chat':
+            return has('manage_chat') || role === 'creator';
+        default:
+            return false;
+    }
+}
+export function registerTelegramPlatformPermitChecker() {
+    return registerPlatformPermitChecker(ADAPTER, checkTelegramPlatformPermit);
+}
+//# sourceMappingURL=platform-permit.js.map

package/lib/platform-permit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-permit.js","sourceRoot":"","sources":["../src/platform-permit.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,OAAO,GAAG,UAAU,CAAC;AAE3B,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,YAAY,OAAO,IAAI,IAAI,GAAG,CAAC;AACxC,CAAC;AAED,MAAM,gBAAgB,GAA2B;IAC/C,WAAW,EAAE,oBAAoB;IACjC,WAAW,EAAE,cAAc;CAC5B,CAAC;AAEF,MAAM,UAAU,2BAA2B,CAAC,WAAmB;IAC7D,OAAO,cAAc,CAAC,gBAAgB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,MAM3C;IACC,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,WAAW,CAAC,IAAI,CAAC,cAAc,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,cAAc,CAAC,CAAC;QAC3F,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QAC/B,WAAW,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvC,IAAI,MAAM,CAAC,oBAAoB;YAAE,WAAW,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,gBAAgB;YAAE,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,mBAAmB;YAAE,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,eAAe;YAAE,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5D,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,aAAa,CAAC,OAAqB;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAoD,CAAC;IAC5E,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,IAAY,EAAE,OAAqB;IAC7E,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEnD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,cAAc;YACjB,OAAO,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;QACnD,KAAK,oBAAoB;YACvB,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,eAAe,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;QACrF,KAAK,kBAAkB;YACrB,OAAO,GAAG,CAAC,kBAAkB,CAAC,IAAI,IAAI,KAAK,SAAS,CAAC;QACvD,KAAK,cAAc;YACjB,OAAO,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,KAAK,SAAS,CAAC;QACnD,KAAK,aAAa;YAChB,OAAO,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,KAAK,SAAS,CAAC;QAClD;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qCAAqC;IACnD,OAAO,6BAA6B,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC;AAC7E,CAAC"}

package/lib/types.d.ts

@@ -11,7 +11,7 @@ export interface TelegramSenderInfo {
     isAdmin?: boolean;
     status?: string;
 }
-export interface TelegramBotConfig {
+export interface TelegramEndpointConfig {
     context: "telegram";
     token: string;
     name: string;
@@ -23,7 +23,7 @@ export interface TelegramBotConfig {
     };
     allowedUpdates?: string[];
 }
-export interface TelegramBot {
-    $config: TelegramBotConfig;
+export interface TelegramEndpoint {
+    $config: TelegramEndpointConfig;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjE,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,iBAAiB,CAAC;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjE,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,sBAAsB,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Zhin.js adapter for Telegram",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,23 +35,26 @@
     "telegraf": "^4.16.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "lucide-react": "^1.17.0",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.88",
-    "@zhin.js/host-api": "1.0.0",
+    "@zhin.js/client": "2.0.3",
+    "@zhin.js/cli": "1.0.89",
     "@zhin.js/contract": "1.0.1",
-    "zhin.js": "2.0.0"
+    "@zhin.js/host-api": "2.0.0",
+    "@zhin.js/host-router": "2.0.0",
+    "@zhin.js/logger": "0.1.71",
+    "zhin.js": "3.0.0"
   },
   "peerDependencies": {
-    "@zhin.js/client": "2.0.2",
+    "@zhin.js/client": "2.0.3",
+    "@zhin.js/host-api": "2.0.0",
     "@zhin.js/contract": "1.0.1",
-    "@zhin.js/host-api": "1.0.0",
-    "@zhin.js/host-router": "1.0.0",
-    "@zhin.js/logger": "0.1.70",
-    "zhin.js": "2.0.0"
+    "@zhin.js/host-router": "2.0.0",
+    "zhin.js": "3.0.0",
+    "@zhin.js/logger": "0.1.71"
   },
   "peerDependenciesMeta": {
     "@zhin.js/client": {

package/skills/telegram/PERMITS.md

@@ -0,0 +1,24 @@
+# Telegram Platform Permits
+
+## 入站字段
+
+群/超级群消息经 `getChatMember`（TTL 60s）写入：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `creator` · `administrator` · `member` |
+| `$sender.permissions` | `chat_creator` · `chat_administrator` · `restrict_members` · `pin_messages` · `manage_chat` · … |
+
+## Permit 词汇表
+
+| `platform(telegram,…)` | 含义 |
+|------------------------|------|
+| `chat_creator` | 群主 |
+| `chat_administrator` | 管理员 |
+| `restrict_members` | 可禁言成员 |
+| `pin_messages` | 可置顶 |
+| `manage_chat` | 可改群默认权限 |
+
+## 工厂映射
+
+`group_admin` → `chat_administrator` · `group_owner` → `chat_creator`

package/src/adapter.ts

@@ -5,54 +5,56 @@ import {
   Adapter,
   Plugin,
 } from "zhin.js";
-import { TelegramBot } from "./bot.js";
-import type { TelegramBotConfig } from "./types.js";
+import { TelegramEndpoint } from "./endpoint.js";
+import type { TelegramEndpointConfig } from "./types.js";
+
+export class TelegramAdapter extends Adapter<TelegramEndpoint> {
+  static override readonly capabilities = ['inbound', 'outbound'] as const;
 
-export class TelegramAdapter extends Adapter<TelegramBot> {
   constructor(plugin: Plugin) {
     super(plugin, "telegram", []);
   }
 
-  createBot(config: TelegramBotConfig): TelegramBot {
-    return new TelegramBot(this, config);
+  createEndpoint(config: TelegramEndpointConfig): TelegramEndpoint {
+    return new TelegramEndpoint(this, config);
   }
 
   // ── IGroupManagement 标准群管方法 ──────────────────────────────────
 
-  async kickMember(botId: string, sceneId: string, userId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.kickMember(Number(sceneId), Number(userId));
+  async kickMember(endpointId: string, sceneId: string, userId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.kickMember(Number(sceneId), Number(userId));
   }
 
-  async unbanMember(botId: string, sceneId: string, userId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.unbanMember(Number(sceneId), Number(userId));
+  async unbanMember(endpointId: string, sceneId: string, userId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.unbanMember(Number(sceneId), Number(userId));
   }
 
-  async muteMember(botId: string, sceneId: string, userId: string, duration = 600) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.muteMember(Number(sceneId), Number(userId), duration);
+  async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.muteMember(Number(sceneId), Number(userId), duration);
   }
 
-  async setAdmin(botId: string, sceneId: string, userId: string, enable = true) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.setAdmin(Number(sceneId), Number(userId), enable);
+  async setAdmin(endpointId: string, sceneId: string, userId: string, enable = true) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.setAdmin(Number(sceneId), Number(userId), enable);
   }
 
-  async setGroupName(botId: string, sceneId: string, name: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.setChatTitle(Number(sceneId), name);
+  async setGroupName(endpointId: string, sceneId: string, name: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.setChatTitle(Number(sceneId), name);
   }
 
-  async getGroupInfo(botId: string, sceneId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.getChatInfo(Number(sceneId));
+  async getGroupInfo(endpointId: string, sceneId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.getChatInfo(Number(sceneId));
   }
 
   // ── 生命周期 ───────────────────────────────────────────────────────

package/src/{bot.ts → endpoint.ts}

@@ -1,10 +1,10 @@
 /**
- * Telegram Bot 实现
+ * Telegram Endpoint 实现
  */
 import { Telegraf, type Context as TelegrafContext } from "telegraf";
 import type { Message as TelegramMessage, Update, MessageEntity, ChatMember } from "telegraf/types";
 import {
-  Bot,
+  Endpoint,
   Message,
   SendOptions,
   SendContent,
@@ -12,10 +12,11 @@ import {
   segment,
   type QuotedMessagePayload,
 } from "zhin.js";
-import type { TelegramBotConfig, TelegramSenderInfo } from "./types.js";
+import type { TelegramEndpointConfig, TelegramSenderInfo } from "./types.js";
 import type { TelegramAdapter } from "./adapter.js";
+import { normalizeTelegramChatMember } from "./platform-permit.js";
 
-export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, TelegramMessage> {
+export class TelegramEndpoint extends Telegraf implements Endpoint<TelegramEndpointConfig, TelegramMessage> {
   $connected: boolean = false;
   /** message_id -> chat_id，用于在仅有 message_id 的场景执行 reaction 操作 */
   private readonly messageChatMap = new Map<string, string>();
@@ -30,7 +31,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     return this.$config.name;
   }
 
-  constructor(public adapter: TelegramAdapter, public $config: TelegramBotConfig) {
+  constructor(public adapter: TelegramAdapter, public $config: TelegramEndpointConfig) {
     super($config.token);
   }
 
@@ -77,7 +78,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
       this.$connected = true;
       const me = await this.telegram.getMe();
       this.pluginLogger.info(
-        `Telegram bot ${this.$config.name} connected successfully as @${me.username}`
+        `Telegram endpoint ${this.$config.name} connected successfully as @${me.username}`
       );
     } catch (error) {
       this.pluginLogger.error("Failed to connect Telegram bot:", error);
@@ -91,17 +92,52 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
       (this as unknown as import('node:events').EventEmitter).removeAllListeners();
       await this.stop();
       this.$connected = false;
-      this.pluginLogger.info(`Telegram bot ${this.$config.name} disconnected`);
+      this.pluginLogger.info(`Telegram endpoint ${this.$config.name} disconnected`);
     } catch (error) {
       this.pluginLogger.error("Error disconnecting Telegram bot:", error);
       throw error;
     }
   }
 
+  private chatMemberCache = new Map<string, { at: number; role?: string; permissions: string[] }>();
+
+  private async enrichGroupSender(
+    message: Message<TelegramMessage>,
+    msg: TelegramMessage,
+  ): Promise<void> {
+    if (message.$channel.type !== "group" || !msg.from?.id) return;
+    const chatId = Number(msg.chat.id);
+    const userId = msg.from.id;
+    const key = `${chatId}:${userId}`;
+    const now = Date.now();
+    const cached = this.chatMemberCache.get(key);
+    if (cached && now - cached.at < 60_000) {
+      message.$sender.role = cached.role;
+      message.$sender.permissions = cached.permissions;
+      return;
+    }
+    try {
+      const member = await this.getChatMember(chatId, userId);
+      const normalized = normalizeTelegramChatMember(member as {
+        status?: string;
+        can_restrict_members?: boolean;
+        can_pin_messages?: boolean;
+        can_delete_messages?: boolean;
+        can_manage_chat?: boolean;
+      });
+      this.chatMemberCache.set(key, { at: now, ...normalized });
+      message.$sender.role = normalized.role;
+      message.$sender.permissions = normalized.permissions;
+    } catch {
+      // 保守拒绝：无角色快照
+    }
+  }
+
   private async handleTelegramMessage(ctx: TelegrafContext): Promise<void> {
     if (!ctx.message) return;
 
     const message = this.$formatMessage(ctx.message as TelegramMessage);
+    await this.enrichGroupSender(message, ctx.message as TelegramMessage);
     this.adapter.emit("message.receive", message);
     this.pluginLogger.debug(
       `${this.$config.name} recv  ${message.$channel.type}(${message.$channel.id}): ${segment.raw(message.$content)}`
@@ -121,7 +157,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     const result = Message.from(msg, {
       $id: msg.message_id.toString(),
       $adapter: "telegram",
-      $bot: this.$config.name,
+      $endpoint: this.$config.name,
       $sender: {
         id: msg.from?.id.toString() || "",
         name: msg.from?.username || msg.from?.first_name || "Unknown",
@@ -155,7 +191,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
 
         return await this.adapter.sendMessage({
           context: "telegram",
-          bot: this.$config.name,
+          endpoint: this.$config.name,
           id: channelId,
           type: channelType,
           content: content,
@@ -207,7 +243,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     const result = Message.from(query, {
       $id: query.id,
       $adapter: "telegram",
-      $bot: this.$config.name,
+      $endpoint: this.$config.name,
       $sender: {
         id: query.from.id.toString(),
         name: query.from.username || query.from.first_name,
@@ -648,15 +684,15 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     }
 
     // If neither media nor text was sent, this is an error
-    throw new Error("TelegramBot.$sendMessage: No media or text content to send.");
+    throw new Error("TelegramEndpoint.$sendMessage: No media or text content to send.");
   }
 
   async $recallMessage(id: string): Promise<void> {
     // Telegram requires both chat_id and message_id to delete a message
-    // The Bot interface only provides message_id, making recall impossible
+    // The Endpoint interface only provides message_id, making recall impossible
     // Users should use message.$recall() instead, which has the full context
     throw new Error(
-      "TelegramBot.$recallMessage: Message recall not supported without chat_id. " +
+      "TelegramEndpoint.$recallMessage: Message recall not supported without chat_id. " +
       "Use message.$recall() method instead, which contains the required context."
     );
   }
@@ -683,7 +719,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async $addReaction(messageId: string, emoji: string): Promise<string | null> {
     const ref = this.resolveTelegramMessageRef(messageId);
     if (!ref) {
-      this.pluginLogger.warn(`Telegram Bot ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 addReaction`);
+      this.pluginLogger.warn(`Telegram Endpoint ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 addReaction`);
       return null;
     }
 
@@ -691,7 +727,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
       await this.setMessageReaction(ref.chatId, ref.msgId, emoji);
       return emoji;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 添加 reaction 失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 添加 reaction 失败:`, error);
       return null;
     }
   }
@@ -699,7 +735,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async $removeReaction(messageId: string, _reactionId: string): Promise<void> {
     const ref = this.resolveTelegramMessageRef(messageId);
     if (!ref) {
-      this.pluginLogger.warn(`Telegram Bot ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 removeReaction`);
+      this.pluginLogger.warn(`Telegram Endpoint ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 removeReaction`);
       return;
     }
 
@@ -710,7 +746,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
         reaction: [],
       });
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 移除 reaction 失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 移除 reaction 失败:`, error);
     }
   }
   // ==================== 群组管理 API ====================
@@ -724,10 +760,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async kickMember(chatId: number, userId: number, untilDate?: number): Promise<boolean> {
     try {
       await this.telegram.banChatMember(chatId, userId, untilDate);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 踢出用户 ${userId} 从聊天 ${chatId}`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 踢出用户 ${userId} 从聊天 ${chatId}`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 踢出用户失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 踢出用户失败:`, error);
       throw error;
     }
   }
@@ -740,10 +776,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async unbanMember(chatId: number, userId: number): Promise<boolean> {
     try {
       await this.telegram.unbanChatMember(chatId, userId, { only_if_banned: true });
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 解除用户 ${userId} 的封禁（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 解除用户 ${userId} 的封禁（聊天 ${chatId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 解除封禁失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 解除封禁失败:`, error);
       throw error;
     }
   }
@@ -770,10 +806,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
         permissions,
         until_date: untilDate,
       });
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 限制用户 ${userId} 权限（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 限制用户 ${userId} 权限（聊天 ${chatId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 限制权限失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 限制权限失败:`, error);
       throw error;
     }
   }
@@ -802,7 +838,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
             can_add_web_page_previews: true,
           },
         });
-        this.pluginLogger.info(`Telegram Bot ${this.$id} 解除用户 ${userId} 禁言（聊天 ${chatId}）`);
+        this.pluginLogger.info(`Telegram Endpoint ${this.$id} 解除用户 ${userId} 禁言（聊天 ${chatId}）`);
       } else {
         const untilDate = Math.floor(Date.now() / 1000) + duration;
         await this.telegram.restrictChatMember(chatId, userId, {
@@ -820,11 +856,11 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
           },
           until_date: untilDate,
         });
-        this.pluginLogger.info(`Telegram Bot ${this.$id} 禁言用户 ${userId} ${duration}秒（聊天 ${chatId}）`);
+        this.pluginLogger.info(`Telegram Endpoint ${this.$id} 禁言用户 ${userId} ${duration}秒（聊天 ${chatId}）`);
       }
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 禁言操作失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 禁言操作失败:`, error);
       throw error;
     }
   }
@@ -860,10 +896,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
           can_pin_messages: false,
         });
       }
-      this.pluginLogger.info(`Telegram Bot ${this.$id} ${promote ? '提升' : '降级'}用户 ${userId} 为管理员（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} ${promote ? '提升' : '降级'}用户 ${userId} 为管理员（聊天 ${chatId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 设置管理员失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置管理员失败:`, error);
       throw error;
     }
   }
@@ -876,10 +912,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async setChatTitle(chatId: number, title: string): Promise<boolean> {
     try {
       await this.telegram.setChatTitle(chatId, title);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 设置聊天 ${chatId} 标题为 "${title}"`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 标题为 "${title}"`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 设置标题失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置标题失败:`, error);
       throw error;
     }
   }
@@ -892,10 +928,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async setChatDescription(chatId: number, description: string): Promise<boolean> {
     try {
       await this.telegram.setChatDescription(chatId, description);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 设置聊天 ${chatId} 描述`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 描述`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 设置描述失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置描述失败:`, error);
       throw error;
     }
   }
@@ -908,10 +944,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async pinMessage(chatId: number, messageId: number): Promise<boolean> {
     try {
       await this.telegram.pinChatMessage(chatId, messageId);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 置顶消息 ${messageId}（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 置顶消息 ${messageId}（聊天 ${chatId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 置顶消息失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 置顶消息失败:`, error);
       throw error;
     }
   }
@@ -928,10 +964,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
       } else {
         await this.telegram.unpinAllChatMessages(chatId);
       }
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 取消置顶消息（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 取消置顶消息（聊天 ${chatId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 取消置顶失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 取消置顶失败:`, error);
       throw error;
     }
   }
@@ -944,7 +980,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     try {
       return await this.telegram.getChat(chatId);
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 获取聊天信息失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取聊天信息失败:`, error);
       throw error;
     }
   }
@@ -958,7 +994,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     try {
       return await this.telegram.getChatMember(chatId, userId);
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 获取成员信息失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取成员信息失败:`, error);
       throw error;
     }
   }
@@ -971,7 +1007,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     try {
       return await this.telegram.getChatAdministrators(chatId);
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 获取管理员列表失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取管理员列表失败:`, error);
       throw error;
     }
   }
@@ -984,7 +1020,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
     try {
       return await this.telegram.getChatMembersCount(chatId);
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 获取成员数量失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取成员数量失败:`, error);
       throw error;
     }
   }
@@ -996,10 +1032,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async createInviteLink(chatId: number): Promise<string> {
     try {
       const link = await this.telegram.createChatInviteLink(chatId, {});
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 创建邀请链接（聊天 ${chatId}）`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 创建邀请链接（聊天 ${chatId}）`);
       return link.invite_link;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 创建邀请链接失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 创建邀请链接失败:`, error);
       throw error;
     }
   }
@@ -1010,10 +1046,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
         is_anonymous: isAnonymous,
         allows_multiple_answers: allowsMultipleAnswers,
       } as any);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 发送投票到 ${chatId}`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 发送投票到 ${chatId}`);
       return result;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 发送投票失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 发送投票失败:`, error);
       throw error;
     }
   }
@@ -1027,7 +1063,7 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
       });
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 设置反应失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置反应失败:`, error);
       throw error;
     }
   }
@@ -1035,10 +1071,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   async sendStickerMessage(chatId: number, sticker: string): Promise<TelegramMessage> {
     try {
       const result = await this.telegram.sendSticker(chatId, sticker);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 发送贴纸到 ${chatId}`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 发送贴纸到 ${chatId}`);
       return result;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 发送贴纸失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 发送贴纸失败:`, error);
       throw error;
     }
   }
@@ -1061,10 +1097,10 @@ export class TelegramBot extends Telegraf implements Bot<TelegramBotConfig, Tele
   }): Promise<boolean> {
     try {
       await this.telegram.setChatPermissions(chatId, permissions);
-      this.pluginLogger.info(`Telegram Bot ${this.$id} 设置聊天 ${chatId} 权限`);
+      this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 权限`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`Telegram Bot ${this.$id} 设置聊天权限失败:`, error);
+      this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置聊天权限失败:`, error);
       throw error;
     }
   }