核心用法
tg-canvas 是一个 Node.js 服务器 skill，用于在 Telegram Mini App 中渲染 agent 生成的 HTML、Markdown 或 A2UI 内容。它包含三个核心组件：HTTP/WebSocket 服务器 (server.js)、命令行工具 (bin/tg-canvas.js) 和 Mini App 前端 (miniapp/)。
工作流程：
1. 部署后通过 Cloudflare 隧道暴露 HTTPS 端点
2. 用户通过 Telegram Bot 的菜单按钮进入 Mini App
3. 前端提交 initData 到 /auth 端点，服务端验证 HMAC-SHA256 并检查用户 ID 是否在 ALLOWED_USER_IDS 白名单中
4. 认证成功后下发 JWT，后续 WebSocket 或轮询获取内容状态
5. Agent 通过本地回环地址调用 POST /push 或 CLI tg-canvas push 实时更新画布内容
显著优点：
- Telegram 原生集成：利用 Mini App 框架，无需额外客户端，用户体验流畅
- 双重安全边界：Telegram
initData签名验证 + 用户白名单，防止未授权访问 - 本地化推送防护：
/push、/clear、/health等管理端点强制绑定127.0.0.1/::1，TCP 层拦截，无法通过 HTTP 头伪造（如X-Forwarded-For）绕过 - 实时更新：WebSocket 长连接实现内容秒级同步
- 多格式支持：原生 HTML、Markdown 转译、A2UI JSON 结构化渲染
潜在缺点与局限性：
- 部署复杂度高：依赖 Node.js + Cloudflare 隧道（或自有 HTTPS 反向代理），需要 Telegram Bot 配置和域名管理
- 单实例架构：无内置持久化与横向扩展方案，重启后画布内容丢失（内存存储）
- 网络依赖：Cloudflare 隧道稳定性直接影响可用性，部分地区可能存在连接问题
- 调试门槛：Telegram Mini App 需 HTTPS，本地开发需隧道工具，调试链路较长
适合人群：
- 已向 Telegram 生态投入的开发者或团队
- 需要为特定用户群（白名单）私域展示动态 AI 内容的场景
- 对实时推送有需求，且能接受自托管运维成本的用户
常规风险：
- JWT 泄露：若
JWT_SECRET强度不足或泄露，攻击者可伪造会话令牌访问状态端点 - BOT_TOKEN 泄露：可能导致攻击者伪造 Telegram 验证响应（虽
initData签名仍需 Telegram 服务器密钥，但 Bot API 滥用风险存在） - Cloudflare 隧道中间人：隧道 URL 若被猜测或泄露，攻击者可尝试访问公开端点（但
/auth白名单仍提供防护） - 本地推送绕过风险：若服务器被入侵，攻击者可直接调用回环地址推送恶意内容，需配合
PUSH_TOKEN纵深防御