第十二章：人机协作——用 Telegram 实时介入
📌 本章李明轩在做什么：他希望在地铁上、在饭桌上、在茶水间也能给正在跑的 Ralph 循环"塞一句话"进去。这一章讲怎么通过 Telegram 和 Ralph 实时对话，随时随地把自己变成循环的一部分。
自动化的边界
Ralph 的设计哲学鼓励你"让 Ralph 自己 Ralph"——启动循环，然后去做别的事。但现实中总有一些情况，AI 需要你的输入：
- AI 遇到了不确定的设计决策：两种方案都可行，它不知道哪个更符合你的偏好
- AI 需要一个只有你知道的信息：特定的业务规则、某个系统的访问权限
- 你突然有了新的想法，想在循环中途调整方向
当你不在电脑旁边，这些情况就很麻烦。
**RObot（Robot Operator）**是 Ralph 的人机协作功能，通过 Telegram 把你连接到正在运行的循环上，无论你在哪里，都可以实时介入。
配置 Telegram 机器人
第一步：创建 Telegram 机器人
- 在 Telegram 里搜索
@BotFather - 发送
/newbot - 按照提示设置机器人名称和用户名
- BotFather 会给你一个 Token，类似
1234567890:ABCdefGHI...
记下这个 Token，稍后需要用到。
第二步：配置 Ralph
运行引导配置命令：
# Ralph 目前的 bot 就是 Telegram 机器人，onboard 无需额外 flag
ralph bot onboard
这个命令会引导你：
- 输入刚才得到的 Telegram Bot Token
- 给机器人发送第一条消息（这样 Ralph 就知道你的 Chat ID）
- 测试连接是否正常
或者直接编辑 ralph.yml：
RObot:
enabled: true
timeout_seconds: 300 # 等待你回复的最长时间（秒）
telegram:
bot_token: "1234567890:ABCdefGHI..." # 或用环境变量
更安全的方式是使用环境变量，避免 Token 出现在配置文件里：
export RALPH_TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHI..."
RObot:
enabled: true
timeout_seconds: 300
telegram:
# bot_token 会自动从 RALPH_TELEGRAM_BOT_TOKEN 环境变量读取
第三步：验证配置
ralph bot status # 检查连接状态
ralph bot test # 发送测试消息到你的 Telegram
三种交互模式
RObot 支持三种交互事件，覆盖了不同的人机协作场景：
模式一：AI 提问，人类回答（human.interact）
当 AI 遇到需要你做决策的情况时，它会发出 human.interact 事件，循环会暂停等待你的回答。
AI 端（在帽子执行中发出）：
ralph emit "human.interact" "Decision needed: REST API vs GraphQL for multi-client support.
Options: (A) REST — simpler, wider support; (B) GraphQL — flexible for multiple frontends.
Default if no response in 5 min: REST."
你会收到这条 Telegram 消息：
🤖 Ralph 需要你的输入：
应该使用 REST API 还是 GraphQL？
项目需要支持多种前端（Web、iOS、Android）。
回复 'REST' 或 'GraphQL'，或者简单说明你的偏好。
⏰ 将在 5 分钟后超时（使用默认值）
你回复后，循环自动继续，AI 拿到你的答案继续工作。
如果超时没有回复，Ralph 会选择"安全默认值"（比如选择更简单的方案）并继续，不会卡死。
模式二：人类主动发消息（human.guidance）
你可以随时向正在运行的循环发送指导消息，不需要等 AI 提问。
在 Telegram 里给机器人发任何消息，比如：
注意：这个项目不允许使用第三方库，只用标准库
这条消息会被注入到循环里，在下次迭代时作为"指引"出现在 AI 的上下文中：
## ROBOT GUIDANCE
1. 注意：这个项目不允许使用第三方库，只用标准库
AI 会在后续工作中遵循这个指引。
模式三：非阻塞进度通知（ralph tools interact progress）
AI 可以发送不需要回复的进度更新：
ralph tools interact progress "All tests passing — starting integration phase"
这条消息会发送给你，让你了解进度，但不会暂停循环。适合阶段完成、里程碑提示等 FYI 类通知。
该命令依赖 Telegram 通道：必须先跑过
ralph bot onboard完成配置，并在ralph.yml里启用 RObot（或设置RALPH_TELEGRAM_BOT_TOKEN），否则命令本身不会报错，但消息不会真正发出去。
实际使用场景
场景一：设计决策咨询
你启动了一个功能开发任务，Ralph 在设计阶段遇到了架构问题：
收到来自 Ralph 的消息：
🤖 遇到设计决策需要确认：
我在规划用户通知系统时，有两个方案：
方案A：实时推送（WebSocket）
- 优点：实时性好
- 缺点：服务器需要维持长连接，资源消耗较大
方案B：轮询（每隔 30 秒检查一次）
- 优点：实现简单，服务器资源消耗小
- 缺点：通知有延迟
请问你更倾向哪种方案？如果用户量不大（<1000人），我建议方案B。
你回复：用方案A，用户体验更重要
循环继续，AI 按照你的选择实现 WebSocket 方案。
场景二：在外出时监控并干预
你在公司外面开会，Ralph 在你的电脑上跑着一个复杂的重构任务。你收到通知：
🤖 Ralph 进度更新：
已完成 step-01（重构数据层）
已完成 step-02（重构业务逻辑层）
当前正在进行 step-03（重构 API 层）
预计还需要 30 分钟
你看到消息，觉得进展顺利，不需要干预。继续开会。
20 分钟后：
⚠️ Ralph 遇到问题，需要你的帮助：
在重构 API 层时，发现有一个旧的认证中间件（legacy_auth.py）
被很多地方引用，但注释显示它"不应该在新代码里使用"。
我有两个选择：
A. 保留旧中间件，只在新代码里用新认证方式
B. 迁移所有调用到新认证方式（工作量更大，但更彻底）
你的偏好？默认 5 分钟后我会选择方案A。
你在会议间隙快速回复：选B，做彻底一点
循环继续按你的指示完成迁移。
场景三：紧急调整方向
循环跑到一半，你突然想到一个重要的约束条件：
你直接给机器人发消息：
紧急：用户认证部分绝对不能用第三方库，
这是法律合规要求，只能用系统自带的 hashlib。
AI 在下次迭代时会看到这个指引，立刻调整实现方向。
多循环场景下的消息路由
当你同时运行多个并行循环时，Telegram 的消息路由规则是：
- 发给主循环：直接发消息（默认路由到主循环）
- 发给特定循环：消息开头加
@loop-id，如@loop-abc 改用方案B - 广播给所有循环：消息开头加
@all（谨慎使用）
# 查看所有循环的 ID
ralph loops
# 输出：
# loop-main (主循环) - 添加登录功能
# loop-abc - 修复性能问题
# loop-def - 添加测试
安全注意事项
Telegram 机器人 Token 是敏感信息，需要妥善保管：
- 不要把 Token 提交到代码库：确保
ralph.yml里没有硬编码的 Token，用环境变量 - 不要分享 Token：任何人拿到 Token 都能发消息给你的机器人
- 必要时轮换 Token：如果 Token 泄露，通过 BotFather 生成新的 Token
- 检查 Chat ID：确保只有你的 Chat ID 能与机器人交互
不使用 Telegram 的替代方案
如果你不想配置 Telegram，也可以用更简单的方式手动注入指引：
# 在另一个终端，手动注入事件
ralph emit human.guidance "请用中文写代码注释"
# 查看所有循环的状态
ralph loops list
本章小结
- RObot 通过 Telegram 把你连接到正在运行的 Ralph 循环上
- 三种交互模式：AI 提问（阻塞）、人类主动发指引（非阻塞）、进度通知
- 超时没有回复时，循环会用"安全默认值"继续，不会卡死
- 支持多循环场景下的消息定向路由
- Token 等敏感信息用环境变量存储，不要写进配置文件
第四章到第十二章，李明轩的每个痛点都一个个被解掉了。下一章我们把这些碎片重新拼起来：跟着李明轩跑完从一个选题到 4 平台全面上线的完整一天，看看前面所有机制是怎么协同工作的。