核心用法
tg-canvas 是一个 Telegram Mini App 服务器技能，旨在为 AI Agent 提供一个安全的可视化画布。它通过本地 HTTP/WebSocket 服务器运行，将 Agent 生成的 HTML、Markdown 或结构化内容实时渲染到 Telegram Mini App 中。
工作流程：
1. 配置 Telegram Bot Token 与环境变量，启动 Node.js 服务器
2. 使用 cloudflared 建立 HTTPS 隧道，满足 Telegram Mini App 的 HTTPS 要求
3. 通过 CLI (tg-canvas push --html "<h1>内容</h1>") 或 HTTP API (POST /push) 推送内容
4. 用户通过 Telegram Bot 菜单按钮打开 Mini App，经 initData 验证身份后查看内容
显著优点：
- 无缝集成 Telegram 生态：原生支持 Telegram 的 Mini App 框架和认证机制
- 实时更新：WebSocket 推送确保画布内容即时同步，无需用户刷新
- 多格式支持：HTML、Markdown、纯文本、A2UI 结构化数据均可渲染
- 细粒度访问控制：通过 Telegram User ID 白名单严格限制可见用户
- Agent 友好：提供 CLI 工具，便于自动化脚本和 AI Agent 直接调用
潜在缺点与局限性：
- 依赖外部隧道：必须使用
cloudflared等工具暴露 HTTPS，增加了运维复杂度 - Node.js 环境依赖：需要 Node 18+ 运行时，对纯 Python 或其他语言生态的用户不够友好
- 单实例设计：无内置多租户或持久化存储，重启后画布内容丢失
- Telegram 生态绑定：脱离 Telegram 则完全无法使用，平台锁定性强
适合人群：
- 开发 Telegram Bot 的开发者，需要为 AI Agent 提供可视化交互界面
- 需要实时展示 Agent 思考过程、生成内容或状态监控的场景
- 追求低门槛、无需自建前端团队即可实现 Mini App 体验的项目
常规风险：
- 隧道绕过风险：
cloudflared将远程请求转为本地 TCP 连接，导致 IP 白名单失效，必须依赖PUSH_TOKEN进行认证 - Token 泄露风险：
BOT_TOKEN、JWT_SECRET、PUSH_TOKEN任一泄露都可能导致未授权访问或内容篡改 - 中间人攻击：若 Cloudflare 隧道配置不当或使用非官方 tunnel，存在流量劫持可能
- DoS 暴露面：公共暴露的
/和/auth端点虽无敏感数据，但仍可被探测