@zhin.js/adapter-telegram 7.0.2 → 7.0.5

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 7.0.5
+
+### Patch Changes
+
+- 51015d6: refactor(adapters): migrate platform-permit to PermissionSubject
+
+  All adapter platform-permit checkers now accept PermissionSubject
+  (duck-typed from Message/CommandSession) instead of Message directly.
+  registerPlatformPermitChecker is replaced by host.registerPlatform in
+  the adapter plugin setup. activity-feedback service updated for new
+  PermissionHost integration.
+
+- Updated dependencies [6f9c366]
+- Updated dependencies [373a56b]
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [b08f7fe]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [a9fa72e]
+- Updated dependencies [c8de3ef]
+- Updated dependencies [60f0fc8]
+- Updated dependencies [574c990]
+- Updated dependencies [d096f16]
+- Updated dependencies [3f29623]
+- Updated dependencies [2916852]
+- Updated dependencies [d047869]
+- Updated dependencies [162fa34]
+- Updated dependencies [e62561e]
+- Updated dependencies [3eeeb46]
+- Updated dependencies [85d0f82]
+- Updated dependencies [61bfc1c]
+- Updated dependencies [04bad47]
+- Updated dependencies [e40b048]
+- Updated dependencies [5a5b1bb]
+- Updated dependencies [f1708c3]
+- Updated dependencies [d254a81]
+- Updated dependencies [7123c47]
+- Updated dependencies [05befc1]
+- Updated dependencies [0663b6a]
+- Updated dependencies [f28f9b3]
+- Updated dependencies [9f340f7]
+- Updated dependencies [e53444f]
+- Updated dependencies [5eedd26]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [f919b6f]
+- Updated dependencies [098e411]
+- Updated dependencies [e1b7c01]
+- Updated dependencies [9b94f87]
+- Updated dependencies [a7df753]
+  - @zhin.js/agent@1.1.5
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/permission@1.0.1
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 7.0.4
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/agent@1.1.4
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 7.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 7.0.2
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮
 - 长轮询 `getUpdates` 入站（默认；无需公网 IP / host-http）
 - 解析 text / image / video / audio / voice / document / sticker / location / callback_query
 - 支持私聊与群组
-- 出站 `send({ target, payload })` → Bot API（text / media / keyboard）
+- 出站 `send({ conversation, payload })` → Bot API（text / media / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Webhook 模式延期（需 `httpHostToken`）；配置 `polling: false` 会明确报错
 
@@ -25,8 +25,8 @@ pnpm add @zhin.js/adapter-telegram
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http`（polling 路径）
 
-入站：`gateway.receive({ adapter, target: chatId, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → Telegram Bot API
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef，由 `telegramInboundConversation` 归一化）  
+出站：`send({ conversation, payload })` → Telegram Bot API
 
 ### 平台权限（platform permit）
 

package/adapters/telegram.js

@@ -21,8 +21,8 @@ export default defineAdapter({
     create(context) {
         const config = resolveTelegramConfig(context.config);
         // 注册到插件运行时状态（telegram.endpoint list 的"运行中"数据源）
-        context.use(telegramRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.mode,
         });
         return new TelegramEndpoint({

package/adapters/telegram.ts

@@ -26,8 +26,8 @@ export default defineAdapter<TelegramAdapterConfig>({
   create(context) {
     const config = resolveTelegramConfig(context.config);
     // 注册到插件运行时状态（telegram.endpoint list 的"运行中"数据源）
-    context.use(telegramRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.mode,
     });
     return new TelegramEndpoint({

package/lib/endpoint.d.ts

@@ -40,7 +40,7 @@ export declare class TelegramEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: TelegramMessage): void;

package/lib/endpoint.js

@@ -2,14 +2,13 @@
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
-import { formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatLegacyMessageRef, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
-import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveChannel, senderDisplayName, } from './protocol.js';
+import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
 import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
-const logger = getLogger('telegram');
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
 /**
@@ -18,6 +17,7 @@ const CHAT_MEMBER_CACHE_MAX = 2_000;
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
 export class TelegramEndpoint {
+    #logger;
     #options;
     #fetch;
     #pollAbort;
@@ -34,6 +34,7 @@ export class TelegramEndpoint {
         recall: (messageId) => this.recallMessage(messageId),
     });
     constructor(options) {
+        this.#logger = getAdapterLogger('telegram', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
@@ -58,7 +59,7 @@ export class TelegramEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerTelegramAgentEndpoint(this.#options.config.name, this);
+            this.#unregisterAgent = registerTelegramAgentEndpoint(this.#options.config.id, this);
             const me = await this.callApi('getMe');
             this.#botUserId = me.id;
             this.#botUsername = me.username;
@@ -70,9 +71,9 @@ export class TelegramEndpoint {
                 const webhook = this.#options.config.webhook;
                 if (!webhook.secretToken) {
                     // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
-                    logger.warn(formatCompact({
+                    this.#logger.warn(formatCompact({
                         op: 'webhook_no_secret',
-                        endpoint: this.#options.config.name,
+                        endpoint: this.#options.config.id,
                         path: webhook.path,
                         hint: 'set webhook.secretToken to authenticate Telegram callbacks',
                     }));
@@ -83,9 +84,9 @@ export class TelegramEndpoint {
                     allowed_updates: this.#options.config.allowedUpdates,
                     ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
                 });
-                logger.info(formatCompact({
+                this.#logger.info(formatCompact({
                     op: 'connect',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     mode: 'webhook',
                     path: webhook.path,
                     username: me.username,
@@ -95,16 +96,16 @@ export class TelegramEndpoint {
             await this.callApi('deleteWebhook', { drop_pending_updates: false });
             this.#pollAbort = new AbortController();
             this.#pollPromise = runTelegramPollLoop(this, this.#pollAbort.signal);
-            logger.info(formatCompact({
+            this.#logger.info(formatCompact({
                 op: 'connect',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 mode: 'polling',
                 username: me.username,
             }));
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect Telegram bot:', error);
+            this.#logger.error('Failed to connect Telegram bot:', error);
             throw error;
         }
     }
@@ -129,11 +130,10 @@ export class TelegramEndpoint {
         this.#unregisterAgent = undefined;
         this.#chatMemberCache.clear();
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ target, conversation, payload }) {
-        const chatId = nativeConversationId(target, conversation);
-        const plan = formatOutboundPlan(chatId, payload);
+    async send({ conversation, payload }) {
+        const plan = formatOutboundPlan(conversation.id, payload);
         let lastId = '';
         for (const action of plan.actions) {
             const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -145,7 +145,7 @@ export class TelegramEndpoint {
         }
         if (!lastId)
             return `telegram-${Date.now()}`;
-        return formatLegacyMessageReference({ target, messageId: lastId });
+        return formatLegacyMessageRef({ conversation, id: lastId });
     }
     async recallMessage(messageId) {
         if (!messageId || messageId.startsWith('telegram-'))
@@ -188,37 +188,38 @@ export class TelegramEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const { channelId } = resolveChannel(msg);
-        void this.#admitWithSenderRole(msg, channelId).catch((err) => {
-            logger.warn(formatCompact({
+        const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+        void this.#admitWithSenderRole(msg, conversation).catch((err) => {
+            this.#logger.warn(formatCompact({
                 op: 'telegram_gateway_receive_failed',
-                target: channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
     }
-    async #admitWithSenderRole(msg, channelId) {
+    async #admitWithSenderRole(msg, conversation) {
         const permit = await this.#resolveGroupSenderPermit(msg);
         // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
         const mentioned = this.#isBotMentioned(msg);
         await this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: channelId,
+            conversation,
+            message: { conversation, id: String(msg.message_id) },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
-            sender: senderDisplayName(msg.from),
-            id: String(msg.message_id),
+            sender: {
+                id: String(msg.from?.id ?? ''),
+                name: senderDisplayName(msg.from) || undefined,
+                ...(permit?.role ? { roles: [permit.role] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
-                // Preserve Telegram's native value below, but publish the canonical
-                // scene kind so every Runtime consumer sees the same conversation type.
                 channelType: resolveTelegramChannelType(msg.chat.type),
                 chatType: msg.chat.type,
                 userId: msg.from?.id,
                 date: msg.date,
                 ...(permit?.role ? { senderRole: permit.role } : {}),
                 ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
-                ...(mentioned ? { mentioned: true } : {}),
             }),
         });
     }
@@ -287,25 +288,28 @@ export class TelegramEndpoint {
     admitCallback(query) {
         if (!this.#open)
             return;
+        const endpointKey = String(this.#options.id);
         const msg = query.message;
-        const channelId = msg ? resolveChannel(msg).channelId : String(query.from.id);
+        // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
+        const conversation = msg
+            ? telegramInboundConversation(endpointKey, msg.chat)
+            : telegramInboundConversation(endpointKey, { id: query.from.id, type: 'private' });
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: channelId,
+            conversation,
+            message: { conversation, id: query.id },
             content: formatCallbackContent(query),
             segments: formatCallbackSegments(query),
-            sender: senderDisplayName(query.from),
-            id: query.id,
+            sender: { id: String(query.from?.id ?? ''), name: senderDisplayName(query.from) || undefined },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
                 eventType: 'callback_query',
                 payload: query.data,
                 sourceMessageId: msg ? String(msg.message_id) : undefined,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'telegram_gateway_receive_failed',
-                target: channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -413,10 +417,3 @@ export class TelegramEndpoint {
         });
     }
 }
-function resolveTelegramChannelType(chatType) {
-    if (chatType === 'private')
-        return 'private';
-    if (chatType === 'channel')
-        return 'channel';
-    return 'group';
-}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
 export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, type TelegramAgentDeps, type TelegramAgentEndpoint, } from './telegram-agent-deps.js';
-export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
 export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, } from './telegram-agent-deps.js';
-export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram platform permit — ChatMember 状态 + 细粒度权限
  */
-import { type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 export declare function platformPermit(perm: string): string;
 export declare function telegramGroupPermitResolver(logicalPerm: string): string;
 export declare function normalizeTelegramChatMember(member: {
@@ -14,5 +14,4 @@ export declare function normalizeTelegramChatMember(member: {
     role?: string;
     permissions: string[];
 };
-export declare function checkTelegramPlatformPermit(perm: string, message: Message<any>): boolean;
-export declare function registerTelegramPlatformPermitChecker(): () => void;
+export declare function checkTelegramPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -1,7 +1,3 @@
-/**
- * Telegram platform permit — ChatMember 状态 + 细粒度权限
- */
-import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'telegram';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -34,12 +30,9 @@ export function normalizeTelegramChatMember(member) {
     }
     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);
+export function checkTelegramPlatformPermit(perm, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
     const has = (t) => permissions.includes(t);
     switch (perm) {
         case 'chat_creator':
@@ -56,6 +49,3 @@ export function checkTelegramPlatformPermit(perm, message) {
             return false;
     }
 }
-export function registerTelegramPlatformPermitChecker() {
-    return registerPlatformPermitChecker(ADAPTER, checkTelegramPlatformPermit);
-}

package/lib/protocol.d.ts

@@ -4,9 +4,10 @@
  */
 import type { IncomingMessage } from 'node:http';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly token?: string;
     /** Default true. `false` selects webhook mode (requires httpHostToken). */
     readonly polling?: boolean;
@@ -28,7 +29,7 @@ export interface TelegramAdapterConfig {
 }
 export interface ResolvedTelegramConfig {
     readonly context: 'telegram';
-    readonly name: string;
+    readonly id: string;
     readonly token: string;
     readonly mode: 'polling' | 'webhook';
     readonly allowedUpdates: readonly string[];
@@ -236,10 +237,13 @@ export declare function readTextBody(request: IncomingMessage, options?: {
     readonly limit?: number;
 }): Promise<string>;
 export declare function botApiUrl(config: Pick<ResolvedTelegramConfig, 'apiBaseUrl' | 'token'>, method: string): string;
-export declare function resolveChannel(msg: Pick<TelegramMessage, 'chat'>): {
-    readonly channelType: 'private' | 'group';
-    readonly channelId: string;
-};
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export declare function resolveTelegramChannelType(chatType: TelegramChat['type']): ConversationKind;
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export declare function telegramInboundConversation(endpointKey: string, chat: Pick<TelegramChat, 'id' | 'type'>): ConversationRef;
 export declare function senderDisplayName(user?: TelegramUser): string;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: TelegramMessage): string;

package/lib/protocol.js

@@ -14,8 +14,8 @@ export function resolveTelegramConfig(config = {}) {
     if (!token) {
         throw new TypeError('Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.TELEGRAM_BOT_NAME
         || 'telegram-bot';
     const polling = config.polling ?? entry?.polling;
@@ -39,7 +39,7 @@ export function resolveTelegramConfig(config = {}) {
         : undefined;
     return {
         context: 'telegram',
-        name,
+        id,
         token,
         mode,
         allowedUpdates: [...allowedUpdates],
@@ -76,10 +76,23 @@ export async function readTextBody(request, options = {}) {
 export function botApiUrl(config, method) {
     return `${config.apiBaseUrl}/bot${config.token}/${method}`;
 }
-export function resolveChannel(msg) {
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export function resolveTelegramChannelType(chatType) {
+    if (chatType === 'private')
+        return 'private';
+    if (chatType === 'channel')
+        return 'channel';
+    return 'group';
+}
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export function telegramInboundConversation(endpointKey, chat) {
     return {
-        channelType: msg.chat.type === 'private' ? 'private' : 'group',
-        channelId: String(msg.chat.id),
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: resolveTelegramChannelType(chat.type),
+        id: String(chat.id),
     };
 }
 export function senderDisplayName(user) {

package/lib/telegram-agent-deps.d.ts

@@ -20,9 +20,9 @@ export interface TelegramAgentEndpoint {
     }>;
 }
 export interface TelegramAgentDeps {
-    getEndpoint: (endpointId: string) => TelegramAgentEndpoint;
+    getEndpoint: (endpointKey: string) => TelegramAgentEndpoint;
 }
-export declare function registerTelegramAgentEndpoint(endpointId: string, endpoint: TelegramAgentEndpoint): () => void;
+export declare function registerTelegramAgentEndpoint(endpointKey: string, endpoint: TelegramAgentEndpoint): () => void;
 /** Optional override used by tests / transitional callers. Pass `null` to clear. */
 export declare function setTelegramAgentDeps(deps: TelegramAgentDeps | null): void;
 export declare function getTelegramAgentDeps(): TelegramAgentDeps;

package/lib/telegram-agent-deps.js

@@ -4,11 +4,11 @@
  */
 const endpoints = new Map();
 let override = null;
-export function registerTelegramAgentEndpoint(endpointId, endpoint) {
-    endpoints.set(endpointId, endpoint);
+export function registerTelegramAgentEndpoint(endpointKey, endpoint) {
+    endpoints.set(endpointKey, endpoint);
     return () => {
-        if (endpoints.get(endpointId) === endpoint) {
-            endpoints.delete(endpointId);
+        if (endpoints.get(endpointKey) === endpoint) {
+            endpoints.delete(endpointKey);
         }
     };
 }
@@ -20,10 +20,10 @@ export function getTelegramAgentDeps() {
     if (override)
         return override;
     return {
-        getEndpoint(endpointId) {
-            const registered = endpoints.get(endpointId);
+        getEndpoint(endpointKey) {
+            const registered = endpoints.get(endpointKey);
             if (!registered)
-                throw new Error(`Endpoint ${endpointId} 不存在`);
+                throw new Error(`Endpoint ${endpointKey} 不存在`);
             return registered;
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "7.0.2",
+  "version": "7.0.5",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,21 +32,22 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/im-contract": "1.0.0",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/permission": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -64,9 +65,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/host-http": "1.0.5",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/host-http": "1.0.8",
+    "zhin.js": "6.0.4"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -1,7 +1,8 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
-import { registerTelegramPlatformPermitChecker } from "./lib/platform-permit.js";
+import { permissionHostToken } from '@zhin.js/permission';
+import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
 import { telegramRuntimeStateToken } from "./lib/telegram-runtime-state.js";
 export default definePlugin({
     name: 'telegram',
@@ -9,9 +10,10 @@ export default definePlugin({
         displayName: 'Telegram Bot API Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（telegram.endpoint list 的"运行中"数据源）
         context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState());
-        // 平台权限门禁：chat_creator / chat_administrator / pin_messages 等（agent 工具 platformPermit）
-        return registerTelegramPlatformPermitChecker();
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('telegram', checkTelegramPlatformPermit);
+        }
     },
 });

package/schema.json

@@ -40,24 +40,60 @@
       "type": "string",
       "default": "https://api.telegram.org"
     },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（Telegram user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted Telegram user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "Telegram bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（Telegram user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted Telegram user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "token": {
             "type": "string",
             "description": "Telegram bot token"
+          },
+          "id": {
+            "type": "string",
+            "description": "Telegram bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "token"
         ]
       }

package/src/endpoint.ts

@@ -6,11 +6,12 @@ import type { EndpointControl, EndpointInstance, EndpointSendRequest } from '@zh
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
-  formatLegacyMessageReference,
+  formatLegacyMessageRef,
   nativeConversationId,
   parseLegacyMessageReference,
+  type ConversationRef,
 } from '@zhin.js/im-contract';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { runTelegramPollLoop } from './polling.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
@@ -22,8 +23,9 @@ import {
   formatInboundContent,
   formatInboundSegments,
   formatOutboundPlan,
-  resolveChannel,
+  resolveTelegramChannelType,
   senderDisplayName,
+  telegramInboundConversation,
   type ResolvedTelegramConfig,
   type TelegramCallbackQuery,
   type TelegramChatMember,
@@ -34,8 +36,6 @@ import {
 import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
 
-const logger = getLogger('telegram');
-
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
 
@@ -85,6 +85,8 @@ interface TelegramApiErr {
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
 export class TelegramEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: TelegramEndpointOptions;
   readonly #fetch: TelegramFetch;
   #pollAbort?: AbortController;
@@ -102,6 +104,7 @@ export class TelegramEndpoint implements EndpointInstance {
   });
 
   constructor(options: TelegramEndpointOptions) {
+    this.#logger = getAdapterLogger('telegram', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? globalThis.fetch;
   }
@@ -131,7 +134,7 @@ export class TelegramEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
-      this.#unregisterAgent = registerTelegramAgentEndpoint(this.#options.config.name, this);
+      this.#unregisterAgent = registerTelegramAgentEndpoint(this.#options.config.id, this);
       const me = await this.callApi<{ id?: number; username?: string; first_name?: string }>('getMe');
       this.#botUserId = me.id;
       this.#botUsername = me.username;
@@ -144,9 +147,9 @@ export class TelegramEndpoint implements EndpointInstance {
         const webhook = this.#options.config.webhook!;
         if (!webhook.secretToken) {
           // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
-          logger.warn(formatCompact({
+          this.#logger.warn(formatCompact({
             op: 'webhook_no_secret',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             path: webhook.path,
             hint: 'set webhook.secretToken to authenticate Telegram callbacks',
           }));
@@ -157,9 +160,9 @@ export class TelegramEndpoint implements EndpointInstance {
           allowed_updates: this.#options.config.allowedUpdates,
           ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
         });
-        logger.info(formatCompact({
+        this.#logger.info(formatCompact({
           op: 'connect',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           mode: 'webhook',
           path: webhook.path,
           username: me.username,
@@ -170,15 +173,15 @@ export class TelegramEndpoint implements EndpointInstance {
       await this.callApi('deleteWebhook', { drop_pending_updates: false });
       this.#pollAbort = new AbortController();
       this.#pollPromise = runTelegramPollLoop(this, this.#pollAbort.signal);
-      logger.info(formatCompact({
+      this.#logger.info(formatCompact({
         op: 'connect',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
         mode: 'polling',
         username: me.username,
       }));
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect Telegram bot:', error);
+      this.#logger.error('Failed to connect Telegram bot:', error);
       throw error;
     }
   }
@@ -204,12 +207,11 @@ export class TelegramEndpoint implements EndpointInstance {
     this.#unregisterAgent = undefined;
     this.#chatMemberCache.clear();
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
-    const chatId = nativeConversationId(target, conversation);
-    const plan = formatOutboundPlan(chatId, payload);
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const plan = formatOutboundPlan(conversation.id, payload);
     let lastId = '';
     for (const action of plan.actions) {
       const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -219,7 +221,7 @@ export class TelegramEndpoint implements EndpointInstance {
       if (result.message_id != null) lastId = String(result.message_id);
     }
     if (!lastId) return `telegram-${Date.now()}`;
-    return formatLegacyMessageReference({ target, messageId: lastId });
+    return formatLegacyMessageRef({ conversation, id: lastId });
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -266,38 +268,39 @@ export class TelegramEndpoint implements EndpointInstance {
   /** Test / internal: admit a message when open. */
   admit(msg: TelegramMessage): void {
     if (!this.#open) return;
-    const { channelId } = resolveChannel(msg);
-    void this.#admitWithSenderRole(msg, channelId).catch((err) => {
-      logger.warn(formatCompact({
+    const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+    void this.#admitWithSenderRole(msg, conversation).catch((err) => {
+      this.#logger.warn(formatCompact({
         op: 'telegram_gateway_receive_failed',
-        target: channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
   }
 
-  async #admitWithSenderRole(msg: TelegramMessage, channelId: string): Promise<void> {
+  async #admitWithSenderRole(msg: TelegramMessage, conversation: ConversationRef): Promise<void> {
     const permit = await this.#resolveGroupSenderPermit(msg);
     // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
     const mentioned = this.#isBotMentioned(msg);
     await this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: channelId,
+      conversation,
+      message: { conversation, id: String(msg.message_id) },
       content: formatInboundContent(msg),
       segments: formatInboundSegments(msg),
-      sender: senderDisplayName(msg.from),
-      id: String(msg.message_id),
+      sender: {
+        id: String(msg.from?.id ?? ''),
+        name: senderDisplayName(msg.from) || undefined,
+        ...(permit?.role ? { roles: [permit.role] } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
-        // Preserve Telegram's native value below, but publish the canonical
-        // scene kind so every Runtime consumer sees the same conversation type.
         channelType: resolveTelegramChannelType(msg.chat.type),
         chatType: msg.chat.type,
         userId: msg.from?.id,
         date: msg.date,
         ...(permit?.role ? { senderRole: permit.role } : {}),
         ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
-        ...(mentioned ? { mentioned: true } : {}),
       }),
     });
   }
@@ -360,25 +363,28 @@ export class TelegramEndpoint implements EndpointInstance {
   /** Test / internal: admit a callback query when open. */
   admitCallback(query: TelegramCallbackQuery): void {
     if (!this.#open) return;
+    const endpointKey = String(this.#options.id);
     const msg = query.message;
-    const channelId = msg ? resolveChannel(msg).channelId : String(query.from.id);
+    // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
+    const conversation = msg
+      ? telegramInboundConversation(endpointKey, msg.chat)
+      : telegramInboundConversation(endpointKey, { id: query.from.id, type: 'private' });
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: channelId,
+      conversation,
+      message: { conversation, id: query.id },
       content: formatCallbackContent(query),
       segments: formatCallbackSegments(query),
-      sender: senderDisplayName(query.from),
-      id: query.id,
+      sender: { id: String(query.from?.id ?? ''), name: senderDisplayName(query.from) || undefined },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         eventType: 'callback_query',
         payload: query.data,
         sourceMessageId: msg ? String(msg.message_id) : undefined,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'telegram_gateway_receive_failed',
-        target: channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -521,11 +527,3 @@ export class TelegramEndpoint implements EndpointInstance {
     });
   }
 }
-
-function resolveTelegramChannelType(
-  chatType: TelegramMessage['chat']['type'],
-): 'private' | 'group' | 'channel' {
-  if (chatType === 'private') return 'private';
-  if (chatType === 'channel') return 'channel';
-  return 'group';
-}

package/src/index.ts

@@ -11,7 +11,6 @@ export {
   formatOutboundActions,
   formatOutboundPlan,
   normalizeWebhookPath,
-  resolveChannel,
   resolveTelegramConfig,
   senderDisplayName,
   type ResolvedTelegramConfig,
@@ -40,6 +39,5 @@ export {
   checkTelegramPlatformPermit,
   normalizeTelegramChatMember,
   platformPermit,
-  registerTelegramPlatformPermitChecker,
   telegramGroupPermitResolver,
 } from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram platform permit — ChatMember 状态 + 细粒度权限
  */
-import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 
 const ADAPTER = 'telegram';
 
@@ -42,13 +42,9 @@ export function normalizeTelegramChatMember(member: {
   return { role: 'member', permissions };
 }
 
-function senderPermits(message: Message<any>): { role?: string; permissions: string[] } {
-  const sender = message.$sender as { role?: string; permissions?: string[] };
-  return { role: sender.role, permissions: sender.permissions ?? [] };
-}
-
-export function checkTelegramPlatformPermit(perm: string, message: Message<any>): boolean {
-  const { role, permissions } = senderPermits(message);
+export function checkTelegramPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
   const has = (t: string) => permissions.includes(t);
 
   switch (perm) {
@@ -67,6 +63,3 @@ export function checkTelegramPlatformPermit(perm: string, message: Message<any>)
   }
 }
 
-export function registerTelegramPlatformPermitChecker(): () => void {
-  return registerPlatformPermitChecker(ADAPTER, checkTelegramPlatformPermit);
-}

package/src/protocol.ts

@@ -6,13 +6,14 @@
 import type { IncomingMessage } from 'node:http';
 import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('telegram');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly token?: string;
   /** Default true. `false` selects webhook mode (requires httpHostToken). */
   readonly polling?: boolean;
@@ -35,7 +36,7 @@ export interface TelegramAdapterConfig {
 
 export interface ResolvedTelegramConfig {
   readonly context: 'telegram';
-  readonly name: string;
+  readonly id: string;
   readonly token: string;
   readonly mode: 'polling' | 'webhook';
   readonly allowedUpdates: readonly string[];
@@ -249,8 +250,8 @@ export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): Resol
       'Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.TELEGRAM_BOT_NAME
     || 'telegram-bot';
   const polling = config.polling ?? entry?.polling;
@@ -276,7 +277,7 @@ export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): Resol
     : undefined;
   return {
     context: 'telegram',
-    name,
+    id,
     token,
     mode,
     allowedUpdates: [...allowedUpdates],
@@ -321,13 +322,27 @@ export function botApiUrl(config: Pick<ResolvedTelegramConfig, 'apiBaseUrl' | 't
   return `${config.apiBaseUrl}/bot${config.token}/${method}`;
 }
 
-export function resolveChannel(msg: Pick<TelegramMessage, 'chat'>): {
-  readonly channelType: 'private' | 'group';
-  readonly channelId: string;
-} {
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export function resolveTelegramChannelType(
+  chatType: TelegramChat['type'],
+): ConversationKind {
+  if (chatType === 'private') return 'private';
+  if (chatType === 'channel') return 'channel';
+  return 'group';
+}
+
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export function telegramInboundConversation(
+  endpointKey: string,
+  chat: Pick<TelegramChat, 'id' | 'type'>,
+): ConversationRef {
   return {
-    channelType: msg.chat.type === 'private' ? 'private' : 'group',
-    channelId: String(msg.chat.id),
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: resolveTelegramChannelType(chat.type),
+    id: String(chat.id),
   };
 }
 

package/src/telegram-agent-deps.ts

@@ -28,20 +28,20 @@ export interface TelegramAgentEndpoint {
 }
 
 export interface TelegramAgentDeps {
-  getEndpoint: (endpointId: string) => TelegramAgentEndpoint;
+  getEndpoint: (endpointKey: string) => TelegramAgentEndpoint;
 }
 
 const endpoints = new Map<string, TelegramAgentEndpoint>();
 let override: TelegramAgentDeps | null = null;
 
 export function registerTelegramAgentEndpoint(
-  endpointId: string,
+  endpointKey: string,
   endpoint: TelegramAgentEndpoint,
 ): () => void {
-  endpoints.set(endpointId, endpoint);
+  endpoints.set(endpointKey, endpoint);
   return () => {
-    if (endpoints.get(endpointId) === endpoint) {
-      endpoints.delete(endpointId);
+    if (endpoints.get(endpointKey) === endpoint) {
+      endpoints.delete(endpointKey);
     }
   };
 }
@@ -54,9 +54,9 @@ export function setTelegramAgentDeps(deps: TelegramAgentDeps | null): void {
 export function getTelegramAgentDeps(): TelegramAgentDeps {
   if (override) return override;
   return {
-    getEndpoint(endpointId: string): TelegramAgentEndpoint {
-      const registered = endpoints.get(endpointId);
-      if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+    getEndpoint(endpointKey: string): TelegramAgentEndpoint {
+      const registered = endpoints.get(endpointKey);
+      if (!registered) throw new Error(`Endpoint ${endpointKey} 不存在`);
       return registered;
     },
   };