@zhin.js/adapter-telegram 1.1.0 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 1.1.3
+
+### Patch Changes
+
+- Updated dependencies [5b5d270]
+- Updated dependencies [36c2eb9]
+  - @zhin.js/im-contract@1.1.2
+  - @zhin.js/core@1.1.38
+  - @zhin.js/adapter@1.1.15
+  - @zhin.js/host-http@1.1.2
+  - @zhin.js/agent-feature@1.1.2
+  - @zhin.js/feature-kit@1.1.2
+  - @zhin.js/skill@1.1.2
+  - @zhin.js/tool@1.1.2
+
+## 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.