@zhin.js/adapter-telegram 1.0.69 → 1.1.2

package/PERMITS.md

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

package/README.md

@@ -1,107 +1,136 @@
 # @zhin.js/adapter-telegram
 
-Telegram adapter for zhin.js framework.
+Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮询 `getUpdates`** 收发消息（无需 host）。
 
-## Installation
+## 功能
+
+- 长轮询 `getUpdates` 入站（默认；无需公网 IP / host-http）
+- 解析 text / image / video / audio / voice / document / sticker / location / callback_query
+- 支持私聊与群组
+- 出站 `send({ conversation, payload })` → Bot API（Markdown→安全 HTML / media / keyboard）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Webhook 模式通过 `httpHostToken` 注册回调路由，支持 secretToken 校验
+
+## 安装
 
 ```bash
 pnpm add @zhin.js/adapter-telegram
 ```
 
-## Configuration
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  bots: [
-    {
-      name: 'my-telegram-bot',
-      context: 'telegram',
-      token: 'YOUR_BOT_TOKEN', // Get from @BotFather
-      polling: true, // Use long polling (default)
-      // OR use webhooks:
-      // polling: false,
-      // webhook: {
-      //   domain: 'https://yourdomain.com',
-      //   path: '/telegram-webhook',
-      //   port: 8443
-      // }
-    }
-  ]
-})
-```
+## Plugin Runtime
 
-## Features
+- `@zhin.js/adapter` — 约定式 `adapters/telegram/index.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http`（polling 路径）
 
-- ✅ Send and receive text messages
-- ✅ Support for rich media (images, videos, audio, documents)
-- ✅ Message formatting (bold, italic, code, links)
-- ✅ Reply to messages
-- ✅ Mentions (@username)
-- ✅ Stickers and locations
-- ✅ Callback queries (inline buttons)
-- ✅ Long polling and webhook modes
-- ✅ Private and group chats
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef，由 `telegramInboundConversation` 归一化）  
+出站：`send({ conversation, payload })` → Telegram Bot API
 
-## Getting Your Bot Token
+### 平台权限（platform permit）
 
-1. Talk to [@BotFather](https://t.me/botfather) on Telegram
-2. Send `/newbot` and follow the instructions
-3. Copy the bot token provided
-4. Add the token to your configuration
+- sender role 已恢复：群消息入站时经 `getChatMember`（60s 缓存）解析，写入 `metadata.senderRole` / `metadata.senderPermissions`。
+- `plugin.ts` 在 generation setup 注册 checker，并在 dispose 注销；Plugin Runtime CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费 `permissions`。
 
-## Usage Examples
+## 前置条件
 
-### Basic Message Handling
+| 要求 | 说明 |
+|------|------|
+| **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 创建并获取 Token |
+| **Polling（默认）** | 本地/生产均可；主动拉取更新，无需公网 HTTPS |
+| **网络** | 出站可访问 `api.telegram.org` |
+| **host-http** | Polling **不需要**；Webhook **需要** CLI HTTP Host |
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+必填字段（`endpoints[i]`）：`id`、`token`。
 
-const { addCommand } = usePlugin()
+## 最小配置
 
-addCommand(new MessageCommand('hello')
-  .action(async (message) => {
-    return 'Hello from Telegram!'
-  })
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  telegram:
+    # polling: true   # 默认
+    endpoints:
+      - id: my-telegram-bot
+        token: ${TELEGRAM_TOKEN}
 ```
 
-### Send Rich Media
-
-```typescript
-addCommand(new MessageCommand('photo')
-  .action(async (message) => {
-    return [
-      { type: 'image', data: { url: 'https://example.com/photo.jpg' } },
-      { type: 'text', data: { text: 'Check out this photo!' } }
-    ]
-  })
-)
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `TELEGRAM_TOKEN` | 示例中由 YAML `${TELEGRAM_TOKEN}` 引用的 Bot Token；变量名可自行定义 |
+| `TELEGRAM_WEBHOOK_SECRET` | 示例中由 YAML `${TELEGRAM_WEBHOOK_SECRET}` 引用的 webhook secret；变量名可自行定义 |
+
+## Webhook
+
+配置 `polling: false`，启用 CLI HTTP Host，并提供公网 HTTPS 回调地址。
+`webhook.path` 必须与反向代理转发路径一致，多账号使用不同路径。
+
+```yaml
+http:
+  host: 127.0.0.1
+  port: 8086
+plugins:
+  telegram:
+    polling: false
+    endpoints:
+      - id: my-telegram-bot
+        token: ${TELEGRAM_TOKEN}
+    webhook:
+      domain: https://bot.example.com
+      path: /telegram/webhook
+      secretToken: ${TELEGRAM_WEBHOOK_SECRET}
 ```
 
-### Reply to Messages
+启动时注册 Host 路由并调用 `setWebhook`；停止时释放路由。
+配置 `secretToken` 后，回调须携带匹配的 `X-Telegram-Bot-Api-Secret-Token`，否则返回 403。
 
-```typescript
-addCommand(new MessageCommand('quote <text:text>')
-  .action(async (message, result) => {
-    await message.$reply(`You said: ${result.params.text}`, true) // true = quote original message
-  })
-)
-```
+## 稳定化范围
+
+当前为 **Advanced / 首批升档候选**，完整适配器测试已纳入 `pnpm check:stable`。
+长轮询停止会中止请求与退避；即使传输层在中止后返回更新，也不会派发或推进 offset。
+轮询 offset 仅保存在当前 Endpoint 内存中，不承诺跨重启去重或业务处理恰好一次。
+Webhook 接收确认不等于业务处理完成；需要幂等性的业务应自行持久化去重。
+详见[平台稳定验收](https://github.com/zhinjs/zhin/blob/main/docs/contributing/platform-acceptance.md)。
+
+## 消息类型映射
+
+| Telegram | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | sendMessage |
+| markdown | 原文 | sendMessage（`parse_mode: HTML`） |
+| photo | `[image]` / caption | sendPhoto（`file_id` / `url`） |
+| video | `[video]` | sendVideo |
+| audio / voice | `[audio]` / `[voice]` | sendAudio / sendVoice |
+| document | `[file: name]` | sendDocument |
+| sticker | `[sticker: …]` | sendSticker |
+| location | `[location: lat,lon]` | sendLocation |
+| callback_query | `[action: data]` | — |
+
+## AI tools
 
-## Telegram-Specific Features
+| Kind | Path |
+|------|------|
+| 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` |
 
-### Callback Queries
+## 故障排查
 
-The adapter automatically handles callback queries (from inline keyboards) as special messages.
+| 现象 | 排查 |
+|------|------|
+| 收不到消息 | Token 是否正确；进程已 `open()`；同一 Token 勿多进程同时 polling |
+| Polling 报错 | 检查能否访问 `api.telegram.org`；查看日志 `op: poll` |
+| Webhook 配置报错 | 检查 HTTP Host、公网 HTTPS、反向代理路径与 secretToken |
+| 发送失败 | Token 是否被撤销；查看 Bot API 错误描述 |
 
-### File Handling
+## Documentation
 
-You can send files using:
-- `file_id` (from received messages)
-- URL
-- Local file path
+- [Telegram adapter on zhin.js.org](https://zhin.js.org/adapters/telegram)
+- [Adapters overview](https://zhin.js.org/essentials/adapters)
 
 ## License
 

package/adapters/telegram/index.js

@@ -0,0 +1,34 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * 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";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
+    // inline keyboard 原生按钮承载交互段。
+    segments: {
+        outboundMedia: ['url', 'upload'],
+        interactive: 'native',
+        markdown: 'native',
+    },
+    create(context) {
+        const config = resolveTelegramConfig(context.config);
+        // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
+        context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.mode,
+        });
+        return new TelegramEndpoint({
+            id: context.id,
+            config,
+            http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
+        });
+    },
+});

package/adapters/telegram/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 {
+  resolveTelegramConfig,
+  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 default defineAdapter<TelegramEndpointConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
+  // inline keyboard 原生按钮承载交互段。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+    markdown: 'native',
+  },
+  create(context) {
+    const config = resolveTelegramConfig(context.config);
+    // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
+    context.use(telegramRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.mode,
+    });
+    return new TelegramEndpoint({
+      id: context.id,
+      config,
+      http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
+    });
+  },
+});

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/agents/telegram/skills/telegram-chat-admin/tools/create_invite/index.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string }>({
+  description: '创建 Telegram 群组邀请链接',
+  inputSchema: z.object({
+    chat_id: z.string().describe('聊天 ID'),
+  }),
+  adapter: 'telegram',
+  tags: ['telegram'],
+  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));
+    return { invite_link: link, message: `邀请链接: ${link}` };
+  },
+});

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/agents/telegram/skills/telegram-chat-admin/tools/list_admins/index.ts

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

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/agents/telegram/skills/telegram-chat-admin/tools/member_count/index.ts

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

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/agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; message_id: string }>({
+  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  }: { chat_id: string; message_id: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.pinMessage(Number(chat_id), Number(message_id));
+    return { success, message: success ? '消息已置顶' : '操作失败' };
+  },
+});

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/agents/telegram/skills/telegram-chat-admin/tools/set_description/index.ts

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

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/agents/telegram/skills/telegram-chat-admin/tools/set_permissions/index.ts

@@ -0,0 +1,31 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+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 群组的默认成员权限',
+  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  }: { 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> = {};
+    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 ? '群权限已更新' : '操作失败' };
+  },
+});