boss/docs/superpowers/plans/2026-04-19-telegram-gateway-integration.md

Telegram Gateway Integration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 为 Boss 增加可用的 Telegram 对话入口，让 Telegram 用户能安全地与主 Agent 对话，并在主 Agent 异步完成任务后把结果回推回 Telegram。

Architecture: 在 src/lib 新增一个轻量 Telegram gateway，负责 update 归一化、访问控制、消息分流和 Telegram Bot API 调用；Next.js 暴露 webhook 与管理员配置接口，仍然复用现有 boss-master-agent 与 boss-data 主链，不复制对话业务。异步回复依赖现有 /api/v1/master-agent/tasks/[taskId]/complete 完成回调，在任务落盘后立即尝试发回 Telegram。

Tech Stack: Next.js App Router、TypeScript、文件型状态 data/boss-state.json、原生 fetch、Node test runner + tsx --test

---

Task 1: 定义 Telegram 状态与配置模型

Files:

• Create: src/lib/telegram-gateway.ts

• Modify: src/lib/boss-data.ts

• Test: tests/telegram-gateway.test.ts

• Step 1: 写 Telegram 配置/状态的失败测试

• Step 2: 运行测试确认因接口缺失而失败

• Step 3: 在 boss-data.ts 增加 Telegram 配置与任务外部回推字段

• Step 4: 在 telegram-gateway.ts 增加归一化、mask、session key、chunk 等纯函数

• Step 5: 重新运行测试确认通过

Task 2: 打通 webhook 与主 Agent 桥接

Files:

• Create: src/app/api/v1/integrations/telegram/webhook/route.ts

• Modify: src/lib/telegram-gateway.ts

• Modify: src/lib/boss-master-agent.ts

• Test: tests/telegram-gateway.test.ts

• Step 1: 写 webhook 接收、secret 校验、allowlist、主 Agent 快速回复 的失败测试

• Step 2: 跑测试确认 RED

• Step 3: 实现 webhook handler，把 Telegram 文本桥接到 master-agent

• Step 4: 对快速回复直接回 Telegram；对排队任务保存外部回推目标

• Step 5: 跑测试确认 GREEN

Task 3: 打通任务完成后的 Telegram 异步回推

Files:

• Modify: src/lib/boss-data.ts

• Modify: src/app/api/v1/master-agent/tasks/[taskId]/complete/route.ts

• Modify: src/lib/telegram-gateway.ts

• Test: tests/telegram-gateway.test.ts

• Step 1: 写任务完成后自动回推 Telegram 的失败测试

• Step 2: 跑测试确认 RED

• Step 3: 在任务模型中加入 externalReplyTarget 并在 complete route 中触发 Telegram 发信

• Step 4: 补充发送成功/失败去重保护

• Step 5: 跑测试确认 GREEN

Task 4: 增加管理员配置接口

Files:

• Create: src/app/api/v1/integrations/telegram/route.ts

• Modify: src/lib/telegram-gateway.ts

• Test: tests/telegram-integration-route.test.ts

• Step 1: 写 GET/POST 配置接口失败测试

• Step 2: 跑测试确认 RED

• Step 3: 实现管理员鉴权、配置读取、保存、token 掩码与 getMe 探测

• Step 4: 跑测试确认 GREEN

Task 5: 文档与回归验证

Files:

• Modify: README.md

• Modify: docs/architecture/api_and_service_inventory_cn.md

• Modify: docs/architecture/current_runtime_and_deploy_status_cn.md

• Step 1: 更新 Boss 当前能力文档，写清 Telegram 接入方式、能力边界与部署方式

• Step 2: 运行 tsx --test、npm run lint、npm run build

• Step 3: 记录未完成项与后续扩展点（群聊策略、pairing、Feishu/Telegram 复用层）