Telegram Compose

核心功能

Telegram Compose 技能通过直接调用 Telegram Bot API，实现超越 Clawdbot 原生 Markdown 支持的富格式消息编排。核心特性包括：

• 完整 HTML 格式：支持粗体、斜体、下划线、删除线、行内代码、代码块、剧透文本、引用块（含可展开折叠）、用户 ID 提及等
• 结构化模板：提供状态更新、告警通知、任务清单等标准格式模式
• 视觉层级设计：EMOJI 锚点 + 全大写伪标题 + 标签-值对齐，确保消息可扫描性
• 直接 API 调用：使用 curl 配合 parse_mode: "HTML" 绕过中间转换层

显著优势

1. 格式完备性：原生解决 Clawdbot Markdown 转换无法处理的 <u> 下划线、<tg-spoiler> 剧透、<blockquote expandable> 可展开引用等场景
2. 专业呈现：预设的结构模式（Status/Alert/List）使通知具备产品级视觉规范
3. 权限隔离：支持从 Clawdbot 配置中动态读取不同 bot 账号 token（alerts/main 等），实现消息渠道分离
4. 字符限制清晰：明确区分 4096 字符消息上限与 1024 字符标题上限

局限性与风险

• 依赖外部配置：需预配置 ~/.clawdbot/clawdbot.json 中的 bot token，无配置时完全失效
• 手动转义负担：HTML 特殊字符 <>& 需手动转义为 <>&，易因疏忽导致格式解析失败
• 无响应处理：示例代码仅使用 curl -s，未展示错误处理或 API 限流应对
• 令牌暴露风险：jq 提取 token 后通过环境变量传递，在共享环境或日志中可能存在泄露隐患

适用人群

• 需要向 Telegram 频道发送结构化运维告警、任务状态报告的技术团队
• 追求消息可读性与专业视觉呈现的 Bot 开发者
• 已使用 Clawdbot 生态，需突破其 Markdown 格式限制的高级用户

常规风险提示

| 风险类型 | 说明 |

|---------|------|

| 配置依赖 | 严格依赖本地 JSON 配置文件，路径和字段结构错误将导致技能失效 |

| 注入隐患 | HTML 内容若包含用户输入未转义，可能引发意外标签解析或 XSS 类展示问题 |

| API 限制 | Telegram Bot API 存在速率限制，高频场景需自行实现退避逻辑 |

| 令牌安全 | Bot token 属于敏感凭证，脚本中硬编码或日志输出均存在泄露风险 |

核心用法

telegram-compose 是一个纯 Markdown 文档型技能，提供了一套完整的 Telegram 富消息编排规范。用户通过直接调用 api.telegram.org/bot${TOKEN}/sendMessage API，配合 parse_mode: "HTML" 参数，即可发送结构化消息。

关键功能特性

• 8 种 HTML 格式标签：粗体 <b>、斜体 <i>、下划线 <u>、删除线 <s>、行内代码 <code>、代码块 <pre>、剧透 <tg-spoiler>、两种引用块 <blockquote> / <blockquote expandable>、链接 <a>、用户提及 <a href="tg://user?id=123">
• 结构化模板：提供状态更新、告警、列表三大类示例，包含「表情符号+大写粗体标题」的视觉锚点模式
• 容量限制：消息 4,096 字符、图片标题 1,024 字符

显著优点

1. 视觉层级清晰：强制要求空行分隔区块、1-3 个表情符号作为视觉锚点，大幅提升长消息的可读性
2. Clawdbot 原生不支持的能力：下划线、剧透遮罩、可展开引用块、通过 ID 提及用户，这些是标准 Markdown 转换无法实现的
3. 零依赖零配置：纯文档技能，无需安装任何运行时或依赖库
4. 凭证管理规范：botToken 强制从 ~/.clawdbot/clawdbot.json 配置读取，示例代码中无硬编码密钥

潜在缺点与局限性

• 手动 API 调用：需自行处理 curl 命令、JSON 转义、错误响应，相比 Clawdbot 原生消息工具门槛更高
• 无自动重试机制：网络异常或 Telegram 限流时需自行实现退避逻辑
• HTML 转义负担：<>& 需手动转义为 < > &，在动态生成内容时容易遗漏
• 平台锁定：HTML 格式 Telegram 专用，无法直接迁移至其他 IM 平台

适合人群

• 运维工程师发送带状态指示器的结构化告警
• 产品经理输出带可折叠详情的周报/日报
• 需要「下划线」「剧透」等特殊格式的内容创作者
• 追求消息「专业感」和「可扫描性」的高级用户

常规风险

• Token 泄露风险：若用户误将 BOT_TOKEN 变量硬编码到脚本中并提交到版本控制
• HTML 注入风险：动态内容未转义 <>& 可能导致格式错乱或意外的标签解析
• API 限流：Telegram Bot API 限制为每分钟 30 条消息，突发流量可能触发 429 错误