@zhin.js/adapter-telegram 1.1.0 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +5 -5
  3. package/adapters/{telegram.js → telegram/index.js} +6 -6
  4. package/adapters/{telegram.ts → telegram/index.ts} +9 -9
  5. package/agents/telegram/agent.json +20 -0
  6. package/agents/telegram/boundaries.md +3 -0
  7. package/agents/telegram/conventions.md +3 -0
  8. package/agents/telegram/skills/telegram-chat-admin/SKILL.md +24 -0
  9. package/agents/telegram/skills/telegram-chat-admin/tools/create_invite/index.js +18 -0
  10. package/{agent/tools/create_invite.ts → agents/telegram/skills/telegram-chat-admin/tools/create_invite/index.ts} +3 -3
  11. package/agents/telegram/skills/telegram-chat-admin/tools/list_admins/index.js +24 -0
  12. package/{agent/tools/list_admins.ts → agents/telegram/skills/telegram-chat-admin/tools/list_admins/index.ts} +1 -1
  13. package/agents/telegram/skills/telegram-chat-admin/tools/member_count/index.js +16 -0
  14. package/{agent/tools/member_count.ts → agents/telegram/skills/telegram-chat-admin/tools/member_count/index.ts} +1 -1
  15. package/agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.js +19 -0
  16. package/{agent/tools/pin_message.ts → agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.ts} +3 -3
  17. package/agents/telegram/skills/telegram-chat-admin/tools/set_description/index.js +17 -0
  18. package/{agent/tools/set_description.ts → agents/telegram/skills/telegram-chat-admin/tools/set_description/index.ts} +1 -1
  19. package/agents/telegram/skills/telegram-chat-admin/tools/set_permissions/index.js +32 -0
  20. package/{agent/tools/set_permissions.ts → agents/telegram/skills/telegram-chat-admin/tools/set_permissions/index.ts} +3 -3
  21. package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.js +19 -0
  22. package/{agent/tools/unpin_message.ts → agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.ts} +3 -3
  23. package/agents/telegram/skills/telegram-messages/SKILL.md +19 -0
  24. package/agents/telegram/skills/telegram-messages/tools/react/index.js +18 -0
  25. package/{agent/tools/react.ts → agents/telegram/skills/telegram-messages/tools/react/index.ts} +1 -1
  26. package/agents/telegram/skills/telegram-messages/tools/send_poll/index.js +30 -0
  27. package/{agent/tools/send_poll.ts → agents/telegram/skills/telegram-messages/tools/send_poll/index.ts} +1 -1
  28. package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.js +17 -0
  29. package/{agent/tools/send_sticker.ts → agents/telegram/skills/telegram-messages/tools/send_sticker/index.ts} +1 -1
  30. package/agents/telegram/system.md +3 -0
  31. package/commands/{endpoint/add/[id].js → telegram/endpoint/add/[id]/index.js} +1 -1
  32. package/commands/telegram/endpoint/add/[id]/index.ts +3 -0
  33. package/{lib/telegram-endpoint-commands.js → commands/telegram/endpoint/definition.js} +4 -3
  34. package/{src/telegram-endpoint-commands.ts → commands/telegram/endpoint/definition.ts} +3 -3
  35. package/commands/{endpoint/list.js → telegram/endpoint/list/index.js} +1 -1
  36. package/commands/telegram/endpoint/list/index.ts +3 -0
  37. package/commands/{endpoint/remove/[id].js → telegram/endpoint/remove/[id]/index.js} +1 -1
  38. package/commands/telegram/endpoint/remove/[id]/index.ts +3 -0
  39. package/lib/index.d.ts +1 -1
  40. package/lib/protocol.d.ts +6 -14
  41. package/lib/protocol.js +15 -26
  42. package/lib/telegram-runtime-state.js +1 -1
  43. package/package.json +33 -21
  44. package/schema.json +32 -1
  45. package/src/index.ts +1 -1
  46. package/src/protocol.ts +20 -43
  47. package/src/telegram-runtime-state.ts +1 -1
  48. package/agent/skills/telegram.md +0 -103
  49. package/commands/endpoint/add/[id].ts +0 -3
  50. package/commands/endpoint/list.ts +0 -3
  51. package/commands/endpoint/remove/[id].ts +0 -3
  52. package/lib/telegram-endpoint-commands.d.ts +0 -1
  53. /package/{agent/PERMITS.md → PERMITS.md} +0 -0
@@ -1,3 +1,3 @@
1
1
  // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
- import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
2
+ import { telegramEndpointCommands } from '../../definition.js';
3
3
  export default telegramEndpointCommands.add;
@@ -0,0 +1,3 @@
1
+ import { telegramEndpointCommands } from '../../definition.js';
2
+
3
+ export default telegramEndpointCommands.add;
@@ -1,10 +1,11 @@
1
+ // Generated by build-plugin-runtime-entries.mjs. Do not edit.
1
2
  /**
2
- * `telegram.endpoint` 命令族:由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
3
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
3
+ * `telegram endpoint` 命令族:由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
4
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
4
5
  */
5
6
  import { createEndpointCommands } from 'zhin.js/adapter';
6
7
  import { defineCommand } from 'zhin.js/command';
7
- import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
8
+ import { telegramRuntimeStateToken } from "../../../lib/telegram-runtime-state.js";
8
9
  export const telegramEndpointCommands = createEndpointCommands({
9
10
  adapterKey: 'telegram',
10
11
  adapterDisplayName: 'Telegram',
@@ -1,10 +1,10 @@
1
1
  /**
2
- * `telegram.endpoint` 命令族:由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
3
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
2
+ * `telegram endpoint` 命令族:由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
3
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
4
4
  */
5
5
  import { createEndpointCommands } from 'zhin.js/adapter';
6
6
  import { defineCommand } from 'zhin.js/command';
7
- import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
7
+ import { telegramRuntimeStateToken } from '../../../src/telegram-runtime-state.js';
8
8
 
9
9
  export const telegramEndpointCommands = createEndpointCommands({
10
10
  adapterKey: 'telegram',
@@ -1,3 +1,3 @@
1
1
  // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
- import { telegramEndpointCommands } from "../../lib/telegram-endpoint-commands.js";
2
+ import { telegramEndpointCommands } from '../definition.js';
3
3
  export default telegramEndpointCommands.list;
@@ -0,0 +1,3 @@
1
+ import { telegramEndpointCommands } from '../definition.js';
2
+
3
+ export default telegramEndpointCommands.list;
@@ -1,3 +1,3 @@
1
1
  // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
- import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
2
+ import { telegramEndpointCommands } from '../../definition.js';
3
3
  export default telegramEndpointCommands.remove;
@@ -0,0 +1,3 @@
1
+ import { telegramEndpointCommands } from '../../definition.js';
2
+
3
+ export default telegramEndpointCommands.remove;
package/lib/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
1
  export { TelegramClient, TelegramEndpoint, type TelegramClientApi, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
2
- 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';
2
+ 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';
3
3
  export { telegramClient, type TelegramClientEventMap } from './client.js';
4
4
  export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';
package/lib/protocol.d.ts CHANGED
@@ -3,12 +3,12 @@
3
3
  * Canonicalization is owned by gateway/core before endpoint.send.
4
4
  */
5
5
  import type { IncomingMessage } from 'node:http';
6
+ import { type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
6
7
  import type { Segment } from '@zhin.js/core/runtime';
7
- import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
8
- /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
9
- export interface TelegramAdapterConfig {
10
- readonly id?: string;
11
- readonly token?: string;
8
+ /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
9
+ export interface TelegramEndpointConfig {
10
+ readonly id: string;
11
+ readonly token: string;
12
12
  /** Default true. `false` selects webhook mode (requires httpHostToken). */
13
13
  readonly polling?: boolean;
14
14
  readonly webhook?: {
@@ -18,14 +18,6 @@ export interface TelegramAdapterConfig {
18
18
  };
19
19
  readonly allowedUpdates?: readonly string[];
20
20
  readonly apiBaseUrl?: string;
21
- /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
22
- readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
23
- readonly context?: string;
24
- readonly polling?: boolean;
25
- readonly webhook?: TelegramAdapterConfig['webhook'];
26
- readonly allowedUpdates?: readonly string[];
27
- readonly apiBaseUrl?: string;
28
- }>;
29
21
  }
30
22
  export interface ResolvedTelegramConfig {
31
23
  readonly context: 'telegram';
@@ -236,7 +228,7 @@ export type TelegramOutboundAction = {
236
228
  };
237
229
  };
238
230
  };
239
- export declare function resolveTelegramConfig(config?: TelegramAdapterConfig): ResolvedTelegramConfig;
231
+ export declare function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig;
240
232
  export declare function normalizeWebhookPath(path: string): string;
241
233
  export declare function buildWebhookUrl(webhook: NonNullable<ResolvedTelegramConfig['webhook']>): string;
242
234
  export declare function readTextBody(request: IncomingMessage, options?: {
package/lib/protocol.js CHANGED
@@ -2,40 +2,23 @@
2
2
  * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
3
3
  * Canonicalization is owned by gateway/core before endpoint.send.
4
4
  */
5
- import { isMediaRef } from '@zhin.js/core';
5
+ import { isMediaRef } from '@zhin.js/im-contract';
6
6
  import { formatCompact, getLogger } from '@zhin.js/logger';
7
7
  import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
8
8
  const logger = getLogger('telegram');
9
- export function resolveTelegramConfig(config = {}) {
10
- const entry = config.endpoints?.find((item) => item.context === 'telegram');
11
- const token = config.token
12
- ?? entry?.token
13
- ?? process.env.TELEGRAM_TOKEN
14
- ?? process.env.TELEGRAM_BOT_TOKEN;
15
- if (!token) {
16
- throw new TypeError('Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)');
17
- }
18
- const id = (typeof config.id === 'string' && config.id)
19
- || (typeof entry?.id === 'string' && entry.id)
20
- || process.env.TELEGRAM_BOT_NAME
21
- || 'telegram-bot';
22
- const polling = config.polling ?? entry?.polling;
23
- const webhookSource = config.webhook ?? entry?.webhook;
24
- // Match legacy: polling defaults true; webhook only when polling === false.
9
+ export function resolveTelegramConfig(config) {
10
+ const id = requiredEndpointField(config.id, 'id');
11
+ const token = requiredEndpointField(config.token, 'token');
12
+ const polling = config.polling;
13
+ const webhookSource = config.webhook;
25
14
  const mode = polling === false ? 'webhook' : 'polling';
26
- const apiBaseUrl = (config.apiBaseUrl
27
- ?? entry?.apiBaseUrl
28
- ?? 'https://api.telegram.org').replace(/\/$/, '');
29
- const allowedUpdates = config.allowedUpdates
30
- ?? entry?.allowedUpdates
31
- ?? ['message', 'callback_query'];
15
+ const apiBaseUrl = (config.apiBaseUrl ?? 'https://api.telegram.org').replace(/\/$/, '');
16
+ const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query'];
32
17
  const webhook = mode === 'webhook'
33
18
  ? {
34
19
  domain: webhookSource?.domain ?? '',
35
20
  path: normalizeWebhookPath(webhookSource?.path ?? '/telegram/webhook'),
36
- secretToken: webhookSource?.secretToken
37
- ?? process.env.TELEGRAM_WEBHOOK_SECRET
38
- ?? undefined,
21
+ secretToken: webhookSource?.secretToken,
39
22
  }
40
23
  : undefined;
41
24
  return {
@@ -48,6 +31,12 @@ export function resolveTelegramConfig(config = {}) {
48
31
  webhook,
49
32
  };
50
33
  }
34
+ function requiredEndpointField(value, field) {
35
+ if (typeof value !== 'string' || !value.trim()) {
36
+ throw new TypeError(`Telegram endpoint requires a non-empty ${field}`);
37
+ }
38
+ return value.trim();
39
+ }
51
40
  export function normalizeWebhookPath(path) {
52
41
  const trimmed = path.trim() || '/telegram/webhook';
53
42
  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Telegram 插件实例的运行时状态:adapter create() 注册的 endpoint 列表。
3
- * 由 plugin.ts setup() provide,adapter create 与 `telegram.endpoint` 命令共享(同一 owner generation)。
3
+ * 由 plugin.ts setup() provide,adapter create 与 `telegram endpoint` 命令共享(同一 owner generation)。
4
4
  */
5
5
  import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
6
6
  export const telegramRuntimeStateToken = defineEndpointRuntimeStateToken('telegram');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/adapter-telegram",
3
- "version": "1.1.0",
3
+ "version": "1.1.3",
4
4
  "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -32,26 +32,25 @@
32
32
  "directory": "plugins/adapters/telegram"
33
33
  },
34
34
  "dependencies": {
35
- "@zhin.js/adapter": "1.1.12",
36
- "@zhin.js/core": "1.1.35",
37
- "@zhin.js/feature-kit": "1.1.0",
38
- "@zhin.js/host-http": "1.1.0",
39
- "@zhin.js/im-contract": "1.1.0",
40
- "@zhin.js/logger": "1.1.0"
35
+ "@zhin.js/adapter": "1.1.15",
36
+ "@zhin.js/agent-feature": "1.1.2",
37
+ "@zhin.js/core": "1.1.38",
38
+ "@zhin.js/feature-kit": "1.1.2",
39
+ "@zhin.js/host-http": "1.1.2",
40
+ "@zhin.js/im-contract": "1.1.2",
41
+ "@zhin.js/logger": "1.1.1",
42
+ "@zhin.js/skill": "1.1.2",
43
+ "@zhin.js/tool": "1.1.2"
41
44
  },
42
45
  "peerDependencies": {
43
46
  "zod": "^4.0.0",
44
- "@zhin.js/adapter": "^1.1.12",
45
- "@zhin.js/agent": "^1.1.23",
46
- "@zhin.js/command": "^1.1.0",
47
- "@zhin.js/core": "^1.1.35",
48
- "@zhin.js/permission": "^1.1.0",
49
- "zhin.js": "^1.1.0"
47
+ "@zhin.js/adapter": "^1.1.15",
48
+ "@zhin.js/command": "^1.1.2",
49
+ "@zhin.js/core": "^1.1.38",
50
+ "@zhin.js/permission": "^1.1.2",
51
+ "zhin.js": "^1.1.3"
50
52
  },
51
53
  "peerDependenciesMeta": {
52
- "@zhin.js/agent": {
53
- "optional": true
54
- },
55
54
  "@zhin.js/command": {
56
55
  "optional": true
57
56
  },
@@ -67,9 +66,8 @@
67
66
  "typescript": "^6.0.3",
68
67
  "vitest": "^4.1.10",
69
68
  "zod": "^4.4.3",
70
- "@zhin.js/agent": "1.1.23",
71
- "@zhin.js/host-http": "1.1.0",
72
- "zhin.js": "1.1.0"
69
+ "@zhin.js/host-http": "1.1.2",
70
+ "zhin.js": "1.1.3"
73
71
  },
74
72
  "files": [
75
73
  "adapters",
@@ -78,9 +76,11 @@
78
76
  "schema.json",
79
77
  "src",
80
78
  "lib",
81
- "agent",
79
+ "tools",
80
+ "agents",
82
81
  "README.md",
83
- "CHANGELOG.md"
82
+ "CHANGELOG.md",
83
+ "PERMITS.md"
84
84
  ],
85
85
  "publishConfig": {
86
86
  "access": "public",
@@ -103,6 +103,18 @@
103
103
  {
104
104
  "package": "@zhin.js/command",
105
105
  "api": "^1.0.0"
106
+ },
107
+ {
108
+ "package": "@zhin.js/tool",
109
+ "api": "^1.0.0"
110
+ },
111
+ {
112
+ "package": "@zhin.js/skill",
113
+ "api": "^1.0.0"
114
+ },
115
+ {
116
+ "package": "@zhin.js/agent-feature",
117
+ "api": "^1.0.0"
106
118
  }
107
119
  ],
108
120
  "plugins": []
package/schema.json CHANGED
@@ -60,10 +60,11 @@
60
60
  },
61
61
  "endpoints": {
62
62
  "type": "array",
63
+ "minItems": 1,
63
64
  "description": "多账号:一个插件实例挂多个 endpoint。每项与顶层字段同构(id 必填,其余覆盖顶层)",
64
65
  "items": {
65
66
  "type": "object",
66
- "additionalProperties": true,
67
+ "additionalProperties": false,
67
68
  "properties": {
68
69
  "master": {
69
70
  "type": [
@@ -87,6 +88,36 @@
87
88
  "type": "string",
88
89
  "description": "Telegram bot token"
89
90
  },
91
+ "polling": {
92
+ "type": "boolean"
93
+ },
94
+ "webhook": {
95
+ "type": "object",
96
+ "additionalProperties": false,
97
+ "properties": {
98
+ "domain": {
99
+ "type": "string"
100
+ },
101
+ "path": {
102
+ "type": "string"
103
+ },
104
+ "secretToken": {
105
+ "type": "string"
106
+ }
107
+ }
108
+ },
109
+ "allowedUpdates": {
110
+ "type": "array",
111
+ "items": {
112
+ "type": "string"
113
+ }
114
+ },
115
+ "apiBaseUrl": {
116
+ "type": "string"
117
+ },
118
+ "commandPrefix": {
119
+ "type": "string"
120
+ },
90
121
  "id": {
91
122
  "type": "string",
92
123
  "description": "Telegram bot name"
package/src/index.ts CHANGED
@@ -16,7 +16,7 @@ export {
16
16
  resolveTelegramConfig,
17
17
  senderDisplayName,
18
18
  type ResolvedTelegramConfig,
19
- type TelegramAdapterConfig,
19
+ type TelegramEndpointConfig,
20
20
  type TelegramCallbackQuery,
21
21
  type TelegramChat,
22
22
  type TelegramChatMember,
package/src/protocol.ts CHANGED
@@ -4,18 +4,17 @@
4
4
  */
5
5
 
6
6
  import type { IncomingMessage } from 'node:http';
7
- import { isMediaRef } from '@zhin.js/core';
7
+ import { isMediaRef, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
8
8
  import type { Segment } from '@zhin.js/core/runtime';
9
- import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
10
9
  import { formatCompact, getLogger } from '@zhin.js/logger';
11
10
  import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
12
11
 
13
12
  const logger = getLogger('telegram');
14
13
 
15
- /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
16
- export interface TelegramAdapterConfig {
17
- readonly id?: string;
18
- readonly token?: string;
14
+ /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
15
+ export interface TelegramEndpointConfig {
16
+ readonly id: string;
17
+ readonly token: string;
19
18
  /** Default true. `false` selects webhook mode (requires httpHostToken). */
20
19
  readonly polling?: boolean;
21
20
  readonly webhook?: {
@@ -25,14 +24,6 @@ export interface TelegramAdapterConfig {
25
24
  };
26
25
  readonly allowedUpdates?: readonly string[];
27
26
  readonly apiBaseUrl?: string;
28
- /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
29
- readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
30
- readonly context?: string;
31
- readonly polling?: boolean;
32
- readonly webhook?: TelegramAdapterConfig['webhook'];
33
- readonly allowedUpdates?: readonly string[];
34
- readonly apiBaseUrl?: string;
35
- }>;
36
27
  }
37
28
 
38
29
  export interface ResolvedTelegramConfig {
@@ -246,40 +237,19 @@ export type TelegramOutboundAction =
246
237
  };
247
238
  };
248
239
 
249
- export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): ResolvedTelegramConfig {
250
- const entry = config.endpoints?.find((item) => item.context === 'telegram');
251
- const token = config.token
252
- ?? entry?.token
253
- ?? process.env.TELEGRAM_TOKEN
254
- ?? process.env.TELEGRAM_BOT_TOKEN;
255
- if (!token) {
256
- throw new TypeError(
257
- 'Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)',
258
- );
259
- }
260
- const id = (typeof config.id === 'string' && config.id)
261
- || (typeof entry?.id === 'string' && entry.id)
262
- || process.env.TELEGRAM_BOT_NAME
263
- || 'telegram-bot';
264
- const polling = config.polling ?? entry?.polling;
265
- const webhookSource = config.webhook ?? entry?.webhook;
266
- // Match legacy: polling defaults true; webhook only when polling === false.
240
+ export function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig {
241
+ const id = requiredEndpointField(config.id, 'id');
242
+ const token = requiredEndpointField(config.token, 'token');
243
+ const polling = config.polling;
244
+ const webhookSource = config.webhook;
267
245
  const mode: 'polling' | 'webhook' = polling === false ? 'webhook' : 'polling';
268
- const apiBaseUrl = (
269
- config.apiBaseUrl
270
- ?? entry?.apiBaseUrl
271
- ?? 'https://api.telegram.org'
272
- ).replace(/\/$/, '');
273
- const allowedUpdates = config.allowedUpdates
274
- ?? entry?.allowedUpdates
275
- ?? ['message', 'callback_query'];
246
+ const apiBaseUrl = (config.apiBaseUrl ?? 'https://api.telegram.org').replace(/\/$/, '');
247
+ const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query'];
276
248
  const webhook = mode === 'webhook'
277
249
  ? {
278
250
  domain: webhookSource?.domain ?? '',
279
251
  path: normalizeWebhookPath(webhookSource?.path ?? '/telegram/webhook'),
280
- secretToken: webhookSource?.secretToken
281
- ?? process.env.TELEGRAM_WEBHOOK_SECRET
282
- ?? undefined,
252
+ secretToken: webhookSource?.secretToken,
283
253
  }
284
254
  : undefined;
285
255
  return {
@@ -293,6 +263,13 @@ export function resolveTelegramConfig(config: TelegramAdapterConfig = {}): Resol
293
263
  };
294
264
  }
295
265
 
266
+ function requiredEndpointField(value: unknown, field: 'id' | 'token'): string {
267
+ if (typeof value !== 'string' || !value.trim()) {
268
+ throw new TypeError(`Telegram endpoint requires a non-empty ${field}`);
269
+ }
270
+ return value.trim();
271
+ }
272
+
296
273
  export function normalizeWebhookPath(path: string): string {
297
274
  const trimmed = path.trim() || '/telegram/webhook';
298
275
  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Telegram 插件实例的运行时状态:adapter create() 注册的 endpoint 列表。
3
- * 由 plugin.ts setup() provide,adapter create 与 `telegram.endpoint` 命令共享(同一 owner generation)。
3
+ * 由 plugin.ts setup() provide,adapter create 与 `telegram endpoint` 命令共享(同一 owner generation)。
4
4
  */
5
5
  import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
6
6
 
@@ -1,103 +0,0 @@
1
- ---
2
- name: telegram
3
- platforms:
4
- - telegram
5
- description: >-
6
- Telegram 群组全功能管理。当用户在 Telegram 群中请求群管(踢人、封禁、解封、禁言、
7
- 设管理员、改群名/描述)、消息管理(置顶/取消置顶)、社交互动(投票、表情反应、贴纸)、
8
- 或群权限设置时使用。即使用户没有提到 Telegram,只要上下文是 Telegram 群组场景
9
- 且涉及上述操作,就应触发。仅有用户名时必须先查成员列表获取 user_id。
10
- keywords:
11
- - telegram
12
- - tg
13
- - adapter:telegram
14
- - 群管理
15
- - 置顶
16
- - 投票
17
- - 反应
18
- - 贴纸
19
- - 权限
20
- - 封禁
21
- - 禁言
22
- - list_members
23
- tags:
24
- - group
25
- - management
26
- - im
27
- tools:
28
- - telegram_pin_message
29
- - telegram_unpin_message
30
- - telegram_list_admins
31
- - telegram_member_count
32
- - telegram_create_invite
33
- - telegram_send_poll
34
- - telegram_react
35
- - telegram_send_sticker
36
- - telegram_set_permissions
37
- - telegram_set_description
38
- - telegram_kick_member
39
- - telegram_unban_member
40
- - telegram_mute_member
41
- - telegram_set_admin
42
- - telegram_set_group_name
43
- - telegram_get_group_info
44
- ---
45
-
46
- # Telegram 群组管理技能
47
-
48
- Telegram 的群组管理模型与 QQ 不同:没有「群名片」概念,有封禁(ban)/解封(unban)机制,权限体系更细粒度。
49
-
50
- ## 核心原则
51
-
52
- ### 先查后操作
53
-
54
- Telegram 的 user_id 是纯数字,用户通常只知道用户名(@xxx)。操作具体成员前,用 `telegram_list_admins` 或从消息上下文获取 user_id。
55
-
56
- ### Telegram 权限模型
57
-
58
- Telegram 的权限不是简单的 owner/admin/member 三级,而是细粒度的权限集合。通过 `telegram_set_permissions` 可以控制:发消息、发媒体、发投票、添加成员、置顶消息等。
59
-
60
- ## 工具分类
61
-
62
- ### 群管基础
63
-
64
- | 工具 | 用途 | 说明 |
65
- |------|------|------|
66
- | `telegram_kick_member` | 踢出成员 | 踢出后用户仍可重新加入 |
67
- | `telegram_unban_member` | 解除封禁 | 被 ban 的用户无法加入群组 |
68
- | `telegram_mute_member` | 禁言 | duration 单位秒,**0=永久限制** |
69
- | `telegram_set_admin` | 设/取消管理员 | — |
70
- | `telegram_set_group_name` | 改群名 | — |
71
- | `telegram_set_description` | 设群描述 | — |
72
- | `telegram_set_permissions` | 设群权限 | 影响所有普通成员,管理员不受限 |
73
- | `telegram_get_group_info` | 群信息 | — |
74
- | `telegram_list_admins` | 管理员列表 | — |
75
- | `telegram_member_count` | 成员数量 | — |
76
-
77
- ### 消息与社交
78
-
79
- | 工具 | 用途 | 说明 |
80
- |------|------|------|
81
- | `telegram_pin_message` | 置顶消息 | 需管理员权限 |
82
- | `telegram_unpin_message` | 取消置顶 | — |
83
- | `telegram_create_invite` | 创建邀请链接 | 需管理员权限 |
84
- | `telegram_send_poll` | 发起投票 | 支持匿名 + 多选 |
85
- | `telegram_react` | 表情反应 | 对消息贴 emoji |
86
- | `telegram_send_sticker` | 发贴纸 | — |
87
-
88
- ## 与 QQ 群管的关键差异
89
-
90
- | 概念 | QQ(OneBot11) | Telegram |
91
- |------|---------------|----------|
92
- | 禁言 duration=0 | **解禁** | **永久限制** |
93
- | 踢出 | 踢出 = 移除 | 踢出 ≠ 封禁,可重新加入 |
94
- | 封禁 | 无独立概念 | `ban` 阻止加入 |
95
- | 群名片 | 支持 | 不支持 |
96
- | 群权限 | admin/member 二分 | 细粒度权限集 |
97
-
98
- ## 易错点
99
-
100
- 1. **禁言 duration=0 在 Telegram 是永久限制**,与 QQ 的「解禁」含义相反。
101
- 2. **踢人不等于封禁**:`kick_member` 移除但不阻止重新加入;要永久禁止需要 ban。
102
- 3. **投票支持匿名和多选**:用户说「发个投票」时确认是否需要匿名/多选。
103
- 4. **权限设置影响全体普通成员**,不是针对个人。管理员不受影响。
@@ -1,3 +0,0 @@
1
- import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
2
-
3
- export default telegramEndpointCommands.add;
@@ -1,3 +0,0 @@
1
- import { telegramEndpointCommands } from '../../src/telegram-endpoint-commands.js';
2
-
3
- export default telegramEndpointCommands.list;
@@ -1,3 +0,0 @@
1
- import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
2
-
3
- export default telegramEndpointCommands.remove;
@@ -1 +0,0 @@
1
- export declare const telegramEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;
File without changes