@zhin.js/adapter-telegram 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 1.1.2
+
+### Patch Changes
+
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- 25a845a: Unify Skills on `skills/<name>/SKILL.md`, support Agent-private Skills and nested Skill-private Tools, publish and mount existing plugin Skills, add governed Skill metadata and Turn access filtering, unlock only already-admitted same-owner Tools, and make `on-risk` and `once` approval behavior precise.
+- ddbb92e: Isolate adapter Skills under platform-specific Agents and automatically select the matching platform Agent for IM ingress, preventing unrelated adapter Skills from entering another platform's prompt surface.
+- 40d2c8f: Reduce the default Agent Tool surface by moving process diagnostics into a Skill and splitting broad platform Skills into focused task domains. Restore ICQQ friend and group directory tools with `on-risk` approval and explicit owner, administrator, master, or trusted access.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- 7b47680: Require the canonical expanded Telegram endpoint configuration. The protocol no longer reinterprets nested `endpoints` or reads endpoint identity, token, and webhook secret from `process.env`. The public config type is now `TelegramEndpointConfig`.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- 33ea736: Use `tools/<name>/index.ts` and `defineAgentTool` from `@zhin.js/tool` as the sole Agent Tool authoring model. Remove the duplicate `@zhin.js/tools` definition, context, bridge, export, and discovery path; migrate plugin manifests, examples, scaffolding, HMR, and prepack compilation to the generation-owned Tool Feature.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [244e475]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [63d1f7a]
+- Updated dependencies [25a845a]
+- Updated dependencies [103f2c3]
+- Updated dependencies [9110ab8]
+- Updated dependencies [cd2a888]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [535fed1]
+- Updated dependencies [73a24b7]
+- Updated dependencies [2dbbc15]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [6b70e46]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [baef56b]
+- Updated dependencies [698f16f]
+- Updated dependencies [da0a8e3]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [33ea736]
+- Updated dependencies [507d602]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/tool@1.1.1
+  - @zhin.js/host-http@1.1.1
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/agent-feature@1.1.1
+  - @zhin.js/skill@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ pnpm add @zhin.js/adapter-telegram
 
 ## Plugin Runtime
 
-- `@zhin.js/adapter` — 约定式 `adapters/telegram.ts`（`defineAdapter`）
+- `@zhin.js/adapter` — 约定式 `adapters/telegram/index.ts`（`defineAdapter`）
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
@@ -62,8 +62,8 @@ plugins:
 
 | 变量 | 说明 |
 |------|------|
-| `TELEGRAM_TOKEN` / `TELEGRAM_BOT_TOKEN` | Bot Token |
-| `TELEGRAM_BOT_NAME` | 可选，默认 endpoint 名 |
+| `TELEGRAM_TOKEN` | 示例中由 YAML `${TELEGRAM_TOKEN}` 引用的 Bot Token；变量名可自行定义 |
+| `TELEGRAM_WEBHOOK_SECRET` | 示例中由 YAML `${TELEGRAM_WEBHOOK_SECRET}` 引用的 webhook secret；变量名可自行定义 |
 
 ## Webhook
 
@@ -115,8 +115,8 @@ Webhook 接收确认不等于业务处理完成；需要幂等性的业务应自
 
 | Kind | Path |
 |------|------|
-| Platform tools (10) | `agent/tools/`（invite / pin / admins / sticker / poll 等） |
-| Skill doc | `agent/skills/telegram.md` |
+| Platform tools (10) | `tools/`（invite / pin / admins / sticker / poll 等） |
+| Skill doc | `agents/telegram/skills/telegram-chat-admin/SKILL.md`, `agents/telegram/skills/telegram-messages/SKILL.md` |
 
 ## 故障排查
 

package/adapters/{telegram.js → telegram/index.js}

@@ -1,13 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
+ * Convention entry: discover `adapters/telegram/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { httpHostToken } from '@zhin.js/host-http';
-import { TelegramEndpoint } from "../lib/endpoint.js";
-import { resolveTelegramConfig, } from "../lib/protocol.js";
-import { telegramRuntimeStateToken } from "../lib/telegram-runtime-state.js";
-export { TelegramEndpoint } from "../lib/endpoint.js";
+import { TelegramEndpoint } from "../../lib/endpoint.js";
+import { resolveTelegramConfig, } from "../../lib/protocol.js";
+import { telegramRuntimeStateToken } from "../../lib/telegram-runtime-state.js";
+export { TelegramEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall'],
@@ -20,7 +20,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveTelegramConfig(context.config);
-        // 注册到插件运行时状态（telegram.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
         context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.mode,

package/adapters/{telegram.ts → telegram/index.ts}

@@ -1,19 +1,19 @@
 /**
- * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
+ * Convention entry: discover `adapters/telegram/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { httpHostToken } from '@zhin.js/host-http';
-import { TelegramEndpoint } from '../src/endpoint.js';
+import { TelegramEndpoint } from '../../src/endpoint.js';
 import {
   resolveTelegramConfig,
-  type TelegramAdapterConfig,
-} from '../src/protocol.js';
-import { telegramRuntimeStateToken } from '../src/telegram-runtime-state.js';
+  type TelegramEndpointConfig,
+} from '../../src/protocol.js';
+import { telegramRuntimeStateToken } from '../../src/telegram-runtime-state.js';
 
-export { TelegramEndpoint } from '../src/endpoint.js';
-export type { TelegramEndpointOptions, TelegramFetch } from '../src/endpoint.js';
+export { TelegramEndpoint } from '../../src/endpoint.js';
+export type { TelegramEndpointOptions, TelegramFetch } from '../../src/endpoint.js';
 
-export default defineAdapter<TelegramAdapterConfig>({
+export default defineAdapter<TelegramEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
   // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
@@ -25,7 +25,7 @@ export default defineAdapter<TelegramAdapterConfig>({
   },
   create(context) {
     const config = resolveTelegramConfig(context.config);
-    // 注册到插件运行时状态（telegram.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
     context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: config.mode,

package/agents/telegram/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "TELEGRAM Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles telegram platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "telegram",
+      "adapter:telegram"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "telegram"
+  ]
+}

package/agents/telegram/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active telegram endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/telegram/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/telegram/skills/telegram-chat-admin/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: telegram-chat-admin
+platforms:
+  - telegram
+description: Telegram 管理员查询、成员数、邀请、置顶和群权限设置能力。
+keywords:
+  - "telegram"
+  - "admin"
+  - "invite"
+  - "pin"
+  - "permissions"
+tools:
+  - "pin_message"
+  - "unpin_message"
+  - "list_admins"
+  - "member_count"
+  - "create_invite"
+  - "set_permissions"
+  - "set_description"
+---
+
+# telegram-chat-admin
+
+先读取管理员与成员状态，再执行邀请、置顶或权限变更。群设置写操作遵守审批策略。

package/agents/telegram/skills/telegram-chat-admin/tools/create_invite/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '创建 Telegram 群组邀请链接',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    permissions: [platformPermission('telegram', 'chat_administrator')],
+    async execute({ chat_id }, context) {
+        const endpoint = context.$client;
+        const link = await endpoint.createInviteLink(Number(chat_id));
+        return { invite_link: link, message: `邀请链接: ${link}` };
+    },
+});

package/{agent/tools/create_invite.ts → agents/telegram/skills/telegram-chat-admin/tools/create_invite/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ chat_id: string }>({
   description: '创建 Telegram 群组邀请链接',
@@ -9,7 +9,7 @@ export default defineAgentTool<{ chat_id: string }>({
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  permissions: [platformPermit('chat_administrator')],
+  permissions: [platformPermission('telegram', 'chat_administrator')],
   async execute({ chat_id  }: { chat_id: string }, context) {
     const endpoint = context.$client;
     const link = await endpoint.createInviteLink(Number(chat_id));

package/agents/telegram/skills/telegram-chat-admin/tools/list_admins/index.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取 Telegram 群组管理员列表',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id }, context) {
+        const endpoint = context.$client;
+        const admins = await endpoint.getChatAdmins(Number(chat_id));
+        return {
+            admins: admins.map((a) => ({
+                user_id: a.user.id,
+                username: a.user.username,
+                first_name: a.user.first_name,
+                status: a.status,
+            })),
+            count: admins.length,
+        };
+    },
+});

package/{agent/tools/list_admins.ts → agents/telegram/skills/telegram-chat-admin/tools/list_admins/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string }>({

package/agents/telegram/skills/telegram-chat-admin/tools/member_count/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取 Telegram 群组成员数量',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id }, context) {
+        const endpoint = context.$client;
+        const count = await endpoint.getChatMemberCount(Number(chat_id));
+        return { count, message: `群组共有 ${count} 名成员` };
+    },
+});

package/{agent/tools/member_count.ts → agents/telegram/skills/telegram-chat-admin/tools/member_count/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string }>({

package/agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '置顶 Telegram 群组消息',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        message_id: z.string().describe('消息 ID'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    permissions: [platformPermission('telegram', 'pin_messages')],
+    async execute({ chat_id, message_id }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.pinMessage(Number(chat_id), Number(message_id));
+        return { success, message: success ? '消息已置顶' : '操作失败' };
+    },
+});

package/{agent/tools/pin_message.ts → agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ chat_id: string; message_id: string }>({
   description: '置顶 Telegram 群组消息',
@@ -10,7 +10,7 @@ export default defineAgentTool<{ chat_id: string; message_id: string }>({
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  permissions: [platformPermit('pin_messages')],
+  permissions: [platformPermission('telegram', 'pin_messages')],
   async execute({ chat_id, message_id  }: { chat_id: string; message_id: string }, context) {
     const endpoint = context.$client;
     const success = await endpoint.pinMessage(Number(chat_id), Number(message_id));

package/agents/telegram/skills/telegram-chat-admin/tools/set_description/index.js

@@ -0,0 +1,17 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '设置 Telegram 群组描述',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        description: z.string().describe('群描述文字'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, description }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.setChatDescription(Number(chat_id), description);
+        return { success, message: success ? '群描述已更新' : '操作失败' };
+    },
+});

package/{agent/tools/set_description.ts → agents/telegram/skills/telegram-chat-admin/tools/set_description/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string; description: string }>({

package/agents/telegram/skills/telegram-chat-admin/tools/set_permissions/index.js

@@ -0,0 +1,32 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '设置 Telegram 群组的默认成员权限',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        can_send_messages: z.boolean().optional().describe('是否可以发消息'),
+        can_send_photos: z.boolean().optional().describe('是否可以发图片'),
+        can_send_videos: z.boolean().optional().describe('是否可以发视频'),
+        can_send_polls: z.boolean().optional().describe('是否可以发投票'),
+        can_send_other_messages: z.boolean().optional().describe('是否可以发贴纸/GIF等'),
+        can_add_web_page_previews: z.boolean().optional().describe('是否可以添加网页预览'),
+        can_change_info: z.boolean().optional().describe('是否可以改群信息'),
+        can_invite_users: z.boolean().optional().describe('是否可以邀请用户'),
+        can_pin_messages: z.boolean().optional().describe('是否可以置顶消息'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    permissions: [platformPermission('telegram', 'manage_chat')],
+    async execute({ chat_id, ...perms }, context) {
+        const endpoint = context.$client;
+        const permissions = {};
+        for (const [k, v] of Object.entries(perms)) {
+            if (typeof v === 'boolean')
+                permissions[k] = v;
+        }
+        const success = await endpoint.setChatPermissionsAll(Number(chat_id), permissions);
+        return { success, message: success ? '群权限已更新' : '操作失败' };
+    },
+});

package/{agent/tools/set_permissions.ts → agents/telegram/skills/telegram-chat-admin/tools/set_permissions/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }>({
   description: '设置 Telegram 群组的默认成员权限',
@@ -18,7 +18,7 @@ export default defineAgentTool<{ chat_id: string; can_send_messages?: boolean; c
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  permissions: [platformPermit('manage_chat')],
+  permissions: [platformPermission('telegram', 'manage_chat')],
   async execute({ chat_id, ...perms  }: { chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }, context) {
     const endpoint = context.$client;
     const permissions: Record<string, boolean> = {};

package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '取消置顶 Telegram 群组消息',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        message_id: z.string().optional().describe('消息 ID（可选，不提供则取消所有置顶）'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    permissions: [platformPermission('telegram', 'pin_messages')],
+    async execute({ chat_id, message_id }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);
+        return { success, message: success ? '已取消置顶' : '操作失败' };
+    },
+});

package/{agent/tools/unpin_message.ts → agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ chat_id: string; message_id?: string }>({
   description: '取消置顶 Telegram 群组消息',
@@ -10,7 +10,7 @@ export default defineAgentTool<{ chat_id: string; message_id?: string }>({
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  permissions: [platformPermit('pin_messages')],
+  permissions: [platformPermission('telegram', 'pin_messages')],
   async execute({ chat_id, message_id  }: { chat_id: string; message_id?: string }, context) {
     const endpoint = context.$client;
     const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);

package/agents/telegram/skills/telegram-messages/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: telegram-messages
+platforms:
+  - telegram
+description: Telegram 投票、reaction 和贴纸消息能力。
+keywords:
+  - "telegram"
+  - "poll"
+  - "reaction"
+  - "sticker"
+tools:
+  - "send_poll"
+  - "react"
+  - "send_sticker"
+---
+
+# telegram-messages
+
+用于消息互动。确认聊天和目标消息后调用，避免重复发送。

package/agents/telegram/skills/telegram-messages/tools/react/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '对 Telegram 消息添加表情反应',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        message_id: z.string().describe('消息 ID'),
+        reaction: z.string().describe('反应表情（如 👍、❤️、🔥）'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, message_id, reaction }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.setMessageReaction(Number(chat_id), Number(message_id), reaction);
+        return { success, message: success ? `已添加反应 ${reaction}` : '操作失败' };
+    },
+});

package/{agent/tools/react.ts → agents/telegram/skills/telegram-messages/tools/react/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string; message_id: string; reaction: string }>({

package/agents/telegram/skills/telegram-messages/tools/send_poll/index.js

@@ -0,0 +1,30 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '在 Telegram 群组中发起投票',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        question: z.string().describe('投票问题'),
+        options: z.string().describe('选项 JSON 数组，如 ["A","B","C"]'),
+        is_anonymous: z.boolean().optional().describe('是否匿名投票，默认 true'),
+        allows_multiple: z.boolean().optional().describe('是否允许多选，默认 false'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, question, options, is_anonymous, allows_multiple }, context) {
+        const endpoint = context.$client;
+        let optList;
+        try {
+            optList = JSON.parse(options);
+        }
+        catch {
+            return { success: false, message: 'options 格式错误，应为 JSON 数组' };
+        }
+        if (!Array.isArray(optList) || optList.length < 2) {
+            return { success: false, message: '至少需要 2 个选项' };
+        }
+        const result = await endpoint.sendPoll(Number(chat_id), question, optList, is_anonymous ?? true, allows_multiple ?? false);
+        return { success: true, message_id: result.message_id, message: '投票已发送' };
+    },
+});

package/{agent/tools/send_poll.ts → agents/telegram/skills/telegram-messages/tools/send_poll/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({

package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.js

@@ -0,0 +1,17 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '发送 Telegram 贴纸',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        sticker: z.string().describe('贴纸 file_id 或 URL'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, sticker }, context) {
+        const endpoint = context.$client;
+        const result = await endpoint.sendStickerMessage(Number(chat_id), sticker);
+        return { success: true, message_id: result.message_id, message: '贴纸已发送' };
+    },
+});

package/{agent/tools/send_sticker.ts → agents/telegram/skills/telegram-messages/tools/send_sticker/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ chat_id: string; sticker: string }>({

package/agents/telegram/system.md

@@ -0,0 +1,3 @@
+# TELEGRAM Platform Agent
+
+You are the telegram platform specialist. Interpret requests in the current telegram conversation and load only the narrowest private Skill needed for the task.

package/commands/{endpoint/add/[id].js → telegram/endpoint/add/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
+import { telegramEndpointCommands } from '../../definition.js';
 export default telegramEndpointCommands.add;

package/commands/telegram/endpoint/add/[id]/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../definition.js';
+
+export default telegramEndpointCommands.add;

package/{lib/telegram-endpoint-commands.js → commands/telegram/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `telegram.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
+import { telegramRuntimeStateToken } from "../../../lib/telegram-runtime-state.js";
 export const telegramEndpointCommands = createEndpointCommands({
     adapterKey: 'telegram',
     adapterDisplayName: 'Telegram',

package/{src/telegram-endpoint-commands.ts → commands/telegram/endpoint/definition.ts}

@@ -1,10 +1,10 @@
 /**
- * `telegram.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
+import { telegramRuntimeStateToken } from '../../../src/telegram-runtime-state.js';
 
 export const telegramEndpointCommands = createEndpointCommands({
   adapterKey: 'telegram',

package/commands/{endpoint/list.js → telegram/endpoint/list/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { telegramEndpointCommands } from "../../lib/telegram-endpoint-commands.js";
+import { telegramEndpointCommands } from '../definition.js';
 export default telegramEndpointCommands.list;

package/commands/telegram/endpoint/list/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../definition.js';
+
+export default telegramEndpointCommands.list;

package/commands/{endpoint/remove/[id].js → telegram/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
+import { telegramEndpointCommands } from '../../definition.js';
 export default telegramEndpointCommands.remove;

package/commands/telegram/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../definition.js';
+
+export default telegramEndpointCommands.remove;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { TelegramClient, TelegramEndpoint, type TelegramClientApi, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.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 { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramEndpointConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
 export { telegramClient, type TelegramClientEventMap } from './client.js';
 export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/protocol.d.ts

@@ -3,12 +3,12 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import { type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 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 id?: string;
-    readonly token?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface TelegramEndpointConfig {
+    readonly id: string;
+    readonly token: string;
     /** Default true. `false` selects webhook mode (requires httpHostToken). */
     readonly polling?: boolean;
     readonly webhook?: {
@@ -18,14 +18,6 @@ export interface TelegramAdapterConfig {
     };
     readonly allowedUpdates?: readonly string[];
     readonly apiBaseUrl?: string;
-    /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
-    readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
-        readonly context?: string;
-        readonly polling?: boolean;
-        readonly webhook?: TelegramAdapterConfig['webhook'];
-        readonly allowedUpdates?: readonly string[];
-        readonly apiBaseUrl?: string;
-    }>;
 }
 export interface ResolvedTelegramConfig {
     readonly context: 'telegram';
@@ -236,7 +228,7 @@ export type TelegramOutboundAction = {
         };
     };
 };
-export declare function resolveTelegramConfig(config?: TelegramAdapterConfig): ResolvedTelegramConfig;
+export declare function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig;
 export declare function normalizeWebhookPath(path: string): string;
 export declare function buildWebhookUrl(webhook: NonNullable<ResolvedTelegramConfig['webhook']>): string;
 export declare function readTextBody(request: IncomingMessage, options?: {

package/lib/protocol.js

@@ -2,40 +2,23 @@
  * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
 const logger = getLogger('telegram');
-export function resolveTelegramConfig(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'telegram');
-    const token = config.token
-        ?? entry?.token
-        ?? process.env.TELEGRAM_TOKEN
-        ?? process.env.TELEGRAM_BOT_TOKEN;
-    if (!token) {
-        throw new TypeError('Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)');
-    }
-    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;
-    const webhookSource = config.webhook ?? entry?.webhook;
-    // Match legacy: polling defaults true; webhook only when polling === false.
+export function resolveTelegramConfig(config) {
+    const id = requiredEndpointField(config.id, 'id');
+    const token = requiredEndpointField(config.token, 'token');
+    const polling = config.polling;
+    const webhookSource = config.webhook;
     const mode = polling === false ? 'webhook' : 'polling';
-    const apiBaseUrl = (config.apiBaseUrl
-        ?? entry?.apiBaseUrl
-        ?? 'https://api.telegram.org').replace(/\/$/, '');
-    const allowedUpdates = config.allowedUpdates
-        ?? entry?.allowedUpdates
-        ?? ['message', 'callback_query'];
+    const apiBaseUrl = (config.apiBaseUrl ?? 'https://api.telegram.org').replace(/\/$/, '');
+    const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query'];
     const webhook = mode === 'webhook'
         ? {
             domain: webhookSource?.domain ?? '',
             path: normalizeWebhookPath(webhookSource?.path ?? '/telegram/webhook'),
-            secretToken: webhookSource?.secretToken
-                ?? process.env.TELEGRAM_WEBHOOK_SECRET
-                ?? undefined,
+            secretToken: webhookSource?.secretToken,
         }
         : undefined;
     return {
@@ -48,6 +31,12 @@ export function resolveTelegramConfig(config = {}) {
         webhook,
     };
 }
+function requiredEndpointField(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Telegram endpoint requires a non-empty ${field}`);
+    }
+    return value.trim();
+}
 export function normalizeWebhookPath(path) {
     const trimmed = path.trim() || '/telegram/webhook';
     return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;

package/lib/telegram-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * Telegram 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `telegram.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `telegram endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 export const telegramRuntimeStateToken = defineEndpointRuntimeStateToken('telegram');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,26 +32,25 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.12",
-    "@zhin.js/core": "1.1.35",
-    "@zhin.js/feature-kit": "1.1.0",
-    "@zhin.js/host-http": "1.1.0",
-    "@zhin.js/im-contract": "1.1.0",
-    "@zhin.js/logger": "1.1.0"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/agent-feature": "1.1.1",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.1",
+    "@zhin.js/tool": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.12",
-    "@zhin.js/agent": "^1.1.23",
-    "@zhin.js/command": "^1.1.0",
-    "@zhin.js/core": "^1.1.35",
-    "@zhin.js/permission": "^1.1.0",
-    "zhin.js": "^1.1.0"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "@zhin.js/permission": "^1.1.1",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
-      "optional": true
-    },
     "@zhin.js/command": {
       "optional": true
     },
@@ -67,9 +66,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.23",
-    "@zhin.js/host-http": "1.1.0",
-    "zhin.js": "1.1.0"
+    "@zhin.js/host-http": "1.1.1",
+    "zhin.js": "1.1.2"
   },
   "files": [
     "adapters",
@@ -78,9 +76,11 @@
     "schema.json",
     "src",
     "lib",
-    "agent",
+    "tools",
+    "agents",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PERMITS.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -103,6 +103,18 @@
       {
         "package": "@zhin.js/command",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/agent-feature",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/schema.json

@@ -60,10 +60,11 @@
     },
     "endpoints": {
       "type": "array",
+      "minItems": 1,
       "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": false,
         "properties": {
           "master": {
             "type": [
@@ -87,6 +88,36 @@
             "type": "string",
             "description": "Telegram bot token"
           },
+          "polling": {
+            "type": "boolean"
+          },
+          "webhook": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "domain": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "secretToken": {
+                "type": "string"
+              }
+            }
+          },
+          "allowedUpdates": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "apiBaseUrl": {
+            "type": "string"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
           "id": {
             "type": "string",
             "description": "Telegram bot name"

package/src/index.ts

@@ -16,7 +16,7 @@ export {
   resolveTelegramConfig,
   senderDisplayName,
   type ResolvedTelegramConfig,
-  type TelegramAdapterConfig,
+  type TelegramEndpointConfig,
   type TelegramCallbackQuery,
   type TelegramChat,
   type TelegramChatMember,

package/src/protocol.ts

@@ -4,18 +4,17 @@
  */
 
 import type { IncomingMessage } from 'node:http';
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
-import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
 
 const logger = getLogger('telegram');
 
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface TelegramAdapterConfig {
-  readonly id?: string;
-  readonly token?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface TelegramEndpointConfig {
+  readonly id: string;
+  readonly token: string;
   /** Default true. `false` selects webhook mode (requires httpHostToken). */
   readonly polling?: boolean;
   readonly webhook?: {
@@ -25,14 +24,6 @@ export interface TelegramAdapterConfig {
   };
   readonly allowedUpdates?: readonly string[];
   readonly apiBaseUrl?: string;
-  /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
-  readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
-    readonly context?: string;
-    readonly polling?: boolean;
-    readonly webhook?: TelegramAdapterConfig['webhook'];
-    readonly allowedUpdates?: readonly string[];
-    readonly apiBaseUrl?: string;
-  }>;
 }
 
 export interface ResolvedTelegramConfig {
@@ -246,40 +237,19 @@ export type TelegramOutboundAction =
     };
   };
 
-export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): ResolvedTelegramConfig {
-  const entry = config.endpoints?.find((item) => item.context === 'telegram');
-  const token = config.token
-    ?? entry?.token
-    ?? process.env.TELEGRAM_TOKEN
-    ?? process.env.TELEGRAM_BOT_TOKEN;
-  if (!token) {
-    throw new TypeError(
-      'Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)',
-    );
-  }
-  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;
-  const webhookSource = config.webhook ?? entry?.webhook;
-  // Match legacy: polling defaults true; webhook only when polling === false.
+export function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig {
+  const id = requiredEndpointField(config.id, 'id');
+  const token = requiredEndpointField(config.token, 'token');
+  const polling = config.polling;
+  const webhookSource = config.webhook;
   const mode: 'polling' | 'webhook' = polling === false ? 'webhook' : 'polling';
-  const apiBaseUrl = (
-    config.apiBaseUrl
-    ?? entry?.apiBaseUrl
-    ?? 'https://api.telegram.org'
-  ).replace(/\/$/, '');
-  const allowedUpdates = config.allowedUpdates
-    ?? entry?.allowedUpdates
-    ?? ['message', 'callback_query'];
+  const apiBaseUrl = (config.apiBaseUrl ?? 'https://api.telegram.org').replace(/\/$/, '');
+  const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query'];
   const webhook = mode === 'webhook'
     ? {
       domain: webhookSource?.domain ?? '',
       path: normalizeWebhookPath(webhookSource?.path ?? '/telegram/webhook'),
-      secretToken: webhookSource?.secretToken
-        ?? process.env.TELEGRAM_WEBHOOK_SECRET
-        ?? undefined,
+      secretToken: webhookSource?.secretToken,
     }
     : undefined;
   return {
@@ -293,6 +263,13 @@ export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): Resol
   };
 }
 
+function requiredEndpointField(value: unknown, field: 'id' | 'token'): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`Telegram endpoint requires a non-empty ${field}`);
+  }
+  return value.trim();
+}
+
 export function normalizeWebhookPath(path: string): string {
   const trimmed = path.trim() || '/telegram/webhook';
   return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;

package/src/telegram-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * Telegram 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `telegram.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `telegram endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 

package/agent/skills/telegram.md

@@ -1,103 +0,0 @@
----
-name: telegram
-platforms:
-  - telegram
-description: >-
-  Telegram 群组全功能管理。当用户在 Telegram 群中请求群管（踢人、封禁、解封、禁言、
-  设管理员、改群名/描述）、消息管理（置顶/取消置顶）、社交互动（投票、表情反应、贴纸）、
-  或群权限设置时使用。即使用户没有提到 Telegram，只要上下文是 Telegram 群组场景
-  且涉及上述操作，就应触发。仅有用户名时必须先查成员列表获取 user_id。
-keywords:
-  - telegram
-  - tg
-  - adapter:telegram
-  - 群管理
-  - 置顶
-  - 投票
-  - 反应
-  - 贴纸
-  - 权限
-  - 封禁
-  - 禁言
-  - list_members
-tags:
-  - group
-  - management
-  - im
-tools:
-  - telegram_pin_message
-  - telegram_unpin_message
-  - telegram_list_admins
-  - telegram_member_count
-  - telegram_create_invite
-  - telegram_send_poll
-  - telegram_react
-  - telegram_send_sticker
-  - telegram_set_permissions
-  - telegram_set_description
-  - telegram_kick_member
-  - telegram_unban_member
-  - telegram_mute_member
-  - telegram_set_admin
-  - telegram_set_group_name
-  - telegram_get_group_info
----
-
-# Telegram 群组管理技能
-
-Telegram 的群组管理模型与 QQ 不同：没有「群名片」概念，有封禁（ban）/解封（unban）机制，权限体系更细粒度。
-
-## 核心原则
-
-### 先查后操作
-
-Telegram 的 user_id 是纯数字，用户通常只知道用户名（@xxx）。操作具体成员前，用 `telegram_list_admins` 或从消息上下文获取 user_id。
-
-### Telegram 权限模型
-
-Telegram 的权限不是简单的 owner/admin/member 三级，而是细粒度的权限集合。通过 `telegram_set_permissions` 可以控制：发消息、发媒体、发投票、添加成员、置顶消息等。
-
-## 工具分类
-
-### 群管基础
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `telegram_kick_member` | 踢出成员 | 踢出后用户仍可重新加入 |
-| `telegram_unban_member` | 解除封禁 | 被 ban 的用户无法加入群组 |
-| `telegram_mute_member` | 禁言 | duration 单位秒，**0=永久限制** |
-| `telegram_set_admin` | 设/取消管理员 | — |
-| `telegram_set_group_name` | 改群名 | — |
-| `telegram_set_description` | 设群描述 | — |
-| `telegram_set_permissions` | 设群权限 | 影响所有普通成员，管理员不受限 |
-| `telegram_get_group_info` | 群信息 | — |
-| `telegram_list_admins` | 管理员列表 | — |
-| `telegram_member_count` | 成员数量 | — |
-
-### 消息与社交
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `telegram_pin_message` | 置顶消息 | 需管理员权限 |
-| `telegram_unpin_message` | 取消置顶 | — |
-| `telegram_create_invite` | 创建邀请链接 | 需管理员权限 |
-| `telegram_send_poll` | 发起投票 | 支持匿名 + 多选 |
-| `telegram_react` | 表情反应 | 对消息贴 emoji |
-| `telegram_send_sticker` | 发贴纸 | — |
-
-## 与 QQ 群管的关键差异
-
-| 概念 | QQ（OneBot11） | Telegram |
-|------|---------------|----------|
-| 禁言 duration=0 | **解禁** | **永久限制** |
-| 踢出 | 踢出 = 移除 | 踢出 ≠ 封禁，可重新加入 |
-| 封禁 | 无独立概念 | `ban` 阻止加入 |
-| 群名片 | 支持 | 不支持 |
-| 群权限 | admin/member 二分 | 细粒度权限集 |
-
-## 易错点
-
-1. **禁言 duration=0 在 Telegram 是永久限制**，与 QQ 的「解禁」含义相反。
-2. **踢人不等于封禁**：`kick_member` 移除但不阻止重新加入；要永久禁止需要 ban。
-3. **投票支持匿名和多选**：用户说「发个投票」时确认是否需要匿名/多选。
-4. **权限设置影响全体普通成员**，不是针对个人。管理员不受影响。

package/commands/endpoint/add/[id].ts

@@ -1,3 +0,0 @@
-import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
-
-export default telegramEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -1,3 +0,0 @@
-import { telegramEndpointCommands } from '../../src/telegram-endpoint-commands.js';
-
-export default telegramEndpointCommands.list;

package/commands/endpoint/remove/[id].ts

@@ -1,3 +0,0 @@
-import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
-
-export default telegramEndpointCommands.remove;

package/lib/telegram-endpoint-commands.d.ts

@@ -1 +0,0 @@
-export declare const telegramEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;