02-核心能力验证 (Capability Verification)

Telegram Bot API 能力分析

官方 API 概览

Telegram Bot API 提供了一系列 HTTP 接口供开发者与 Telegram 服务器通信。官方文档地址：https://core.telegram.org/bots/api

核心 API 方法

发送消息相关：

• sendMessage - 发送文本消息
• sendPhoto / sendDocument - 发送媒体文件
• sendLocation - 发送地理位置
• sendChatAction - 发送”正在输入…”状态

接收更新相关：

• getUpdates - 获取消息更新（Long Polling）
• setWebhook / deleteWebhook - 配置 Webhook

Slash Command 的本质

经过对 Telegram Bot API 文档的深入分析，得出以下关键结论：

1. Slash Command 是客户端功能

用户在 Telegram 客户端输入：
/command arg1 arg2

客户端行为：
- 显示命令提示菜单
- 高亮命令文本
- 发送消息到服务器

服务器收到的实际消息对象：
{
  "message_id": 123,
  "from": { ... },
  "chat": { ... },
  "text": "/command arg1 arg2",
  "entities": [{
    "type": "bot_command",
    "offset": 0,
    "length": 8
  }]
}

2. Bot API 无法模拟用户行为

官方文档明确指出：

• Bot 无法”伪装”成用户发送消息
• Bot 发送的消息会标记为 from: { "is_bot": true }
• 没有任何 API 方法可以让 Bot 触发 Slash Command 菜单

3. 可用的替代方案

虽然无法直接发送 Slash Command，但 Bot 可以：

• 使用 sendMessage 发送包含 /command 文本的消息
• 接收方看到普通文本（不会触发命令菜单）
• 配合 parse_mode: "Markdown" 可以格式化文本

API 调用示例

发送消息（GitHub Actions 可用）：

# 使用 curl 调用 Telegram API
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "<CHAT_ID>",
    "text": "🔔 构建状态通知\\n\\n仓库: my-repo\\n状态: ✅ 成功",
    "parse_mode": "Markdown"
  }'

响应格式：

{
  "ok": true,
  "result": {
    "message_id": 456,
    "date": 1708291200,
    "chat": { ... },
    "text": "🔔 构建状态通知..."
  }
}

GitHub Actions 能力分析

GitHub Actions 执行环境

网络访问能力：

• ✅ 可以访问公网 HTTP/HTTPS 端点
• ✅ 支持 curl, wget, httpie 等工具
• ✅ 可以使用任何语言的 HTTP 客户端库

Secrets 管理：

• ✅ 支持 Repository Secrets 和 Environment Secrets
• ✅ Secrets 在日志中自动脱敏（显示为 ***）
• ✅ 可以在 Workflow 中通过 ${{ secrets.SECRET_NAME }} 引用

常用 HTTP 调用方式：

# 方式 1: 使用 curl
- name: Send Telegram Notification
  run: |
    curl -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_TOKEN }}/sendMessage" \
      -H "Content-Type: application/json" \
      -d "{\"chat_id\":\"${{ secrets.TELEGRAM_CHAT_ID }}\",\"text\":\"Build completed\"}"

# 方式 2: 使用 GitHub Action 市场组件
- name: Send Telegram Message
  uses: appleboy/telegram-action@master
  with:
    to: ${{ secrets.TELEGRAM_CHAT_ID }}
    token: ${{ secrets.TELEGRAM_TOKEN }}
    message: "Build completed!"

“Gap” 分析（能力缺口）

问题核心

变通方案验证

方案 1：发送格式化消息替代

Bot 可以接收并解析普通消息：

// Bot 端代码示例（Node.js + node-telegram-bot-api）
bot.on('message', (msg) => {
  const text = msg.text;
  
  // 识别来自 GitHub Actions 的消息
  if (msg.from.is_bot && text.startsWith('🔔')) {
    // 处理 CI/CD 通知
    handleCINotification(msg);
  }
});

方案 2：使用 Inline Keyboard

虽然不能发送 Slash Command，但可以用按钮实现类似交互：

{
  "chat_id": "<CHAT_ID>",
  "text": "构建完成，请选择操作：",
  "reply_markup": {
    "inline_keyboard": [
      [{"text": "查看日志", "callback_data": "view_logs"}],
      [{"text": "重新部署", "callback_data": "redeploy"}]
    ]
  }
}

验证方法总结

黑盒测试建议

测试 1：基础连通性测试

# 在 GitHub Actions 中测试能否访问 Telegram API
curl -s "https://api.telegram.org/bot<TOKEN>/getMe"

测试 2：消息发送测试

# 测试 sendMessage API
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<CHAT_ID>&text=Test from GitHub Actions"

测试 3：模拟 Slash Command 测试

# 尝试发送包含 /command 的消息
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<CHAT_ID>&text=/test_command"
# 预期结果：消息显示为普通文本，不会触发命令菜单

验证结论

直接回答用户问题：

GitHub Actions 是否可以发送 Telegram Slash Command?

答案：

1. ❌ 技术上不能：Telegram Bot API 不支持 Bot “模拟用户”发送 Slash Command
2. ✅ 功能上可行：可以通过变通方案实现类似效果
3. 🔧 推荐做法：直接调用 sendMessage API 发送通知消息，在 Bot 端做消息解析

下一步：查看解决方案设计（03-solution-design.md）