01-需求拆解 (Requirement Analysis)

用户目标 (User Goal)

用户希望实现以下工作流：

核心需求：在 GitHub Actions 工作流执行过程中，能够向 Telegram Bot 发送指令（Slash Command），触发 Telegram Bot 执行特定操作。

典型使用场景

1. CI/CD 通知场景

   • 当 GitHub Actions 构建失败时，自动发送 /notify_fail 到 Telegram Bot
   • 通知运维团队或开发者及时处理问题

2. 自动化任务触发

   • 在部署完成后，发送 /deploy_complete 触发 Telegram Bot 执行后续操作
   • 例如：更新状态页面、记录部署日志、通知相关人员

3. 监控与告警

   • 定时任务检测到异常时，通过 Slash Command 触发告警流程
   • 集成到现有的 Telegram 运维机器人工具体系

关键路径识别 (Critical Path)

技术挑战分析

挑战 1：Bot 主动发送 vs 用户发送的混淆

这是最容易混淆的概念。需要明确区分：

关键发现：

• Slash Command 本质上是 Telegram 用户 发送的特殊格式消息（以 / 开头）
• Bot 不能”模拟用户” 发送 Slash Command 给自己或其他 Bot
• 但 Bot 可以通过 API 主动发送普通消息 或 调用自定义方法

挑战 2：认证与安全

• 需要安全存储 Telegram Bot Token
• GitHub Actions 需要使用 Secrets 机制保护敏感信息
• 避免在日志中暴露 Token

挑战 3：网络连通性

• GitHub Actions 运行环境需要能够访问 Telegram API（api.telegram.org）
• 某些企业环境可能有出站流量限制

需求澄清与边界定义

可行的方案（推荐）

由于 Bot 无法”模拟”用户发送 Slash Command，实际可实现的方案是：

1. 方案 A：直接调用 Bot API 发送消息

   • GitHub Actions 调用 sendMessage API
   • 发送格式化的通知消息（非 Slash Command）
   • Bot 可以解析消息内容执行相应逻辑

2. 方案 B：调用中间服务

   • GitHub Actions 调用自己的后端服务
   • 后端服务再调用 Telegram API
   • 可以实现更复杂的业务逻辑

3. 方案 C：使用 Webhook 反向触发

   • 如果 Bot 支持 Webhook 接收外部事件
   • GitHub Actions 调用 Bot 的 Webhook 端点
   • 这实际上是 Plan B 的变种

不可行的方案

❌ 直接发送 Slash Command 给 Bot：技术上不可能，因为：

• Telegram API 没有提供让 Bot 模拟用户发送消息的能力
• Slash Command 是客户端功能，Bot API 无法触发

结论与建议

核心结论：用户可能混淆了”发送 Slash Command”和”发送消息触发 Bot 行为”这两个概念。

建议的替代方案：

1. 在 GitHub Actions 中直接调用 Telegram Bot API 发送消息
2. 在 Bot 端设计专门的逻辑来识别和处理来自 GitHub Actions 的消息
3. 使用特定的消息格式或命令前缀来区分不同来源的请求

下一步行动：

• 验证 Telegram Bot API 的具体能力（见 02-capability-verification.md）
• 设计具体的集成方案（见 03-solution-design.md）