@zhin.js/adapter-telegram 1.1.10 → 1.1.11

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.1.11
+
+### Patch Changes
+
+- c407bd2: 安装 HTML 渲染能力时，内置指令菜单通过统一发送链生成菜单图；渲染失败或平台无法投递图片时保留原有文本菜单。菜单采用可自定义标题、配色与背景的三列主题，每页最多 30 项，支持根菜单与插件菜单翻页。平台同时支持原生 Markdown 与按钮时自动附加上一页、下一页控件，在边界禁用；其他平台保留文本导航。Telegram 禁用按钮映射为 Bot API 10.3 DisabledButton。补充中英文文档。
+- 9816c18: 将应用插件装配改为 configVersion: 2：主配置 plugins 映射实例名到包，disable_plugins 控制启停，业务配置使用顶层同名块。package.json 继续保留 features、entry、engine 等包契约，并支持静态 displayName/icon。
+
+  这是配置格式的破坏性更新：旧配置不能继续运行，请先停止 Bot，运行 `zhin migrate instances` 预览，再使用 `--apply` 转换；提供备份与中断继续/回滚，无法无损转换的嵌套、optional 和别名碰撞需人工迁移。Runtime、Console、CLI 与创建向导统一使用新声明。
+
+  保留框架顶层 `menuKeyword` / `menuStyle`，通过当前 generation 的 Root 配置视图供 Command Feature 消费；严格校验和配置修改不会丢失菜单设置，子实例配置保持隔离。
+
+- Updated dependencies [c407bd2]
+- Updated dependencies [064b06d]
+- Updated dependencies [2b4d6dc]
+- Updated dependencies [b58548a]
+- Updated dependencies [e914a93]
+- Updated dependencies [e914a93]
+- Updated dependencies [064b06d]
+  - @zhin.js/core@1.1.46
+  - @zhin.js/feature-kit@1.1.6
+  - @zhin.js/host-http@1.1.7
+  - @zhin.js/adapter@1.1.20
+  - @zhin.js/agent-feature@1.1.7
+  - @zhin.js/skill@1.1.7
+  - @zhin.js/tool@1.1.7
+
 ## 1.1.10
 
 ### Patch Changes

package/README.md

@@ -34,7 +34,7 @@ pnpm add @zhin.js/adapter-telegram
 - `@zhin.js/adapter` — 约定式 `adapters/telegram/index.ts`（`defineAdapter`）
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
-- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 - **无需** `@zhin.js/host-http`（polling 路径）
 
 入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef，由 `telegramInboundConversation` 归一化）  
@@ -59,16 +59,18 @@ pnpm add @zhin.js/adapter-telegram
 ## 最小配置
 
 ```yaml
+configVersion: 2
 # zhin.config.yml（Plugin Runtime）
 plugins:
-  telegram:
-    # polling: true   # 默认
-    endpoints:
-      - id: my-telegram-bot
-        token: ${TELEGRAM_TOKEN}
+  telegram: "@zhin.js/adapter-telegram"
+telegram:
+  # polling: true   # 默认
+  endpoints:
+    - id: my-telegram-bot
+      token: ${TELEGRAM_TOKEN}
 ```
 
-根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
+主配置 `plugins` 映射需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
 
 ## 环境变量
 
@@ -83,19 +85,21 @@ plugins:
 `webhook.path` 必须与反向代理转发路径一致，多账号使用不同路径。
 
 ```yaml
+configVersion: 2
 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}
+  telegram: "@zhin.js/adapter-telegram"
+telegram:
+  polling: false
+  endpoints:
+    - id: my-telegram-bot
+      token: ${TELEGRAM_TOKEN}
+  webhook:
+    domain: https://bot.example.com
+    path: /telegram/webhook
+    secretToken: ${TELEGRAM_WEBHOOK_SECRET}
 ```
 
 启动时注册 Host 路由并调用 `setWebhook`；停止时释放路由。
@@ -147,3 +151,7 @@ Webhook 接收确认不等于业务处理完成；需要幂等性的业务应自
 ## License
 
 MIT
+
+### 禁用按钮
+
+canonical keyboard 的 `disabled: true` 按钮映射为 Telegram Bot API 10.3 的 `disabled: {}`，不携带 `callback_data`；启用按钮仍使用原回调数据，并保留 1–64 UTF-8 字节校验。自建 Bot API Server 需支持该版本，见 [DisabledButton](https://core.telegram.org/bots/api#disabledbutton)。

package/lib/protocol.d.ts

@@ -138,7 +138,9 @@ export interface TelegramWireSegment {
 }
 export interface TelegramInlineButton {
     readonly text: string;
-    readonly callback_data: string;
+    readonly callback_data?: string;
+    /** Bot API 10.3+: mutually exclusive with callback_data. */
+    readonly disabled?: Record<string, never>;
 }
 export type TelegramOutboundAction = {
     readonly method: 'sendMessage';

package/lib/protocol.js

@@ -335,9 +335,13 @@ function buildOutboundActions(target, payload, uploads) {
                             : {};
                         const text = String(record.label ?? record.text ?? '');
                         const callback = String(record.payload ?? record.callback_data ?? '');
-                        if (record.disabled || record.mode === 'command')
-                            throw new EndpointDeliveryError('unsupported_operation', 'Telegram disabled/command buttons are not implemented', 'not_sent');
-                        if (!text.trim() || Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
+                        if (record.mode === 'command')
+                            throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
+                        if (!text.trim())
+                            throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
+                        if (record.disabled)
+                            return { text, disabled: {} };
+                        if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
                             throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
                         return {
                             text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,23 +31,23 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.19",
-    "@zhin.js/agent-feature": "1.1.6",
-    "@zhin.js/core": "1.1.45",
-    "@zhin.js/feature-kit": "1.1.5",
-    "@zhin.js/host-http": "1.1.6",
+    "@zhin.js/adapter": "1.1.20",
+    "@zhin.js/agent-feature": "1.1.7",
+    "@zhin.js/core": "1.1.46",
+    "@zhin.js/feature-kit": "1.1.6",
+    "@zhin.js/host-http": "1.1.7",
     "@zhin.js/im-contract": "1.1.4",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/skill": "1.1.6",
-    "@zhin.js/tool": "1.1.6"
+    "@zhin.js/skill": "1.1.7",
+    "@zhin.js/tool": "1.1.7"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.19",
-    "@zhin.js/command": "^1.1.7",
-    "@zhin.js/core": "^1.1.45",
-    "@zhin.js/permission": "^1.1.6",
-    "zhin.js": "^1.1.10"
+    "@zhin.js/adapter": "^1.1.20",
+    "@zhin.js/command": "^1.1.8",
+    "@zhin.js/core": "^1.1.46",
+    "@zhin.js/permission": "^1.1.7",
+    "zhin.js": "^1.1.11"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -65,8 +65,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.6",
-    "zhin.js": "1.1.10"
+    "@zhin.js/host-http": "1.1.7",
+    "zhin.js": "1.1.11"
   },
   "files": [
     "adapters",

package/src/protocol.ts

@@ -155,7 +155,9 @@ export interface TelegramWireSegment {
 
 export interface TelegramInlineButton {
   readonly text: string;
-  readonly callback_data: string;
+  readonly callback_data?: string;
+  /** Bot API 10.3+: mutually exclusive with callback_data. */
+  readonly disabled?: Record<string, never>;
 }
 
 export type TelegramOutboundAction =
@@ -604,8 +606,10 @@ function buildOutboundActions(
               : {};
             const text = String(record.label ?? record.text ?? '');
             const callback = String(record.payload ?? record.callback_data ?? '');
-            if (record.disabled || record.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'Telegram disabled/command buttons are not implemented', 'not_sent');
-            if (!text.trim() || Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64) throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
+            if (record.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
+            if (!text.trim()) throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
+            if (record.disabled) return { text, disabled: {} };
+            if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64) throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
             return {
               text,
               callback_data: callback,