Pranith-Jain/telegram-preview-parser

# telegram-preview-parser [](https://github.com/Pranith-Jain/telegram-preview-parser/actions/workflows/ci.yml) [](LICENSE) 将 Telegram 频道预览页面（`https://t.me/s/`）解析为结构化的 JSON。无需 Bot API 密钥——直接使用公开的预览页面，该页面会展示任何公开频道最近的约 30-50 条消息。 最初提取自 [pranithjain.qzz.io](https://pranithjain.qzz.io) 威胁情报平台，该平台每 30 分钟追踪约 16 个网络安全频道。 ## 安装 ``` npm install telegram-preview-parser ``` ## 快速开始 ``` import { fetchAndParse, scoreChannel } from 'telegram-preview-parser'; // One-call fetch + parse. const messages = await fetchAndParse('telegram'); if (!messages) { console.error('channel not found / fetch failed'); process.exit(1); } console.log(`${messages.length} recent messages`); for (const m of messages.slice(0, 5)) { console.log(m.datetime, m.permalink, '\n ', m.text.slice(0, 80)); } // Quality signal for the channel. const q = scoreChannel(messages); console.log(`channel quality: ${q.score}/100`, q.signals); ``` 如果你已经有了 HTML（已缓存，或自行获取的）： ``` import { parseChannelHtml } from 'telegram-preview-parser'; const messages = parseChannelHtml(html, { maxAgeDays: 7, maxMessages: 50, maxTextLength: 400, }); ``` ## API ### `fetchAndParse(handle, opts?) → Promise` 一次调用完成获取和解析。当频道不存在、请求失败，或者 HTML 中缺少预期的 wrapper 标记时，返回 `null`（而不是抛出异常）。 ``` interface FetchOptions { maxTextLength?: number; // default 400; truncates with '…' maxAgeDays?: number; // default 7 maxMessages?: number; // default 50 timeoutMs?: number; // default 8000 userAgent?: string; // default identifies this package signal?: AbortSignal; // caller-side cancellation } ``` ### `parseChannelHtml(html, opts?) → ParsedMessage[]` 纯转换函数。传入完整的 t.me/s/ HTML，返回按最新优先排序的结构化消息。如果 HTML 中缺少预期的 wrapper 标记，则返回 `[]`——Telegram 有时会为无效频道返回主页 HTML，此函数会将其视为“无消息”，而不是抛出错误。 ### `scoreChannel(messages) → ChannelQuality` 基于四个信号计算的 0-100 分频道质量得分： - `recent_pct` — 最近 30 天内发布的消息比例（死频道下降很快） - `dupe_pct` — 重复消息比例（垃圾信息/转载信号） - `median_text_len` — 内容深度代理指标（<50 字符被视为仅含标题） - `posts_per_day` — 发布频率合理性检测（极低和极高都会被扣分） 这用于辅助决策，而不是硬性截断。在信息流中，评分为 35 的频道应该排在 80 的后面，但你可能仍然希望让其消息可见。 ### `decodeEntities(s)` / `stripHtml(s)` 基础构建辅助函数，导出供希望在解析输出基础上实现自定义渲染器的调用者使用。 ## `ParsedMessage` 结构 ``` interface ParsedMessage { permalink: string; // 'https://t.me//' datetime: string; // ISO 8601, from views?: string; // 'k'/'M' formatted as Telegram displays text: string; // decoded plaintext,
→ newline, capped at maxTextLength } ``` ## 设计选择 - **无 DOM 解析器依赖。** 基于 Regex，可随处运行（Cloudflare Workers、Node、浏览器）。Telegram 的预览 HTML 足够稳定，只需一次 regex 扫描即可满足需求——引入 `cheerio` 或 `jsdom` 依赖会使包体积增加一倍以上，而收益微乎其微。 - **时间窗口与静默回退机制。** 默认过滤至最近的 `maxAgeDays` 时间窗口。如果频道在窗口期之前就已静默，依然会返回原始消息，以确保该频道不会从信息流中被完全剔除。 - **最新优先。** Telegram 的 HTML 渲染是旧消息在前；解析器会进行反转，以便调用者可以直接使用 `.slice(0, N)` 获取最新消息。 - **频道不存在时返回 `null`，而不是抛出异常。** 对于无效的 handle，Telegram 会返回主页 HTML。我们通过 wrapper 标记进行检测并返回 `null`，而不是解析后返回空结果（这会掩盖 bug）。 - **无重试机制。** 由调用者决定重试策略。本包只返回成功结果或 `null`。 ## 明确不做的事情 - **不使用 Bot API。** 那需要 token + 会带来速率限制 + 需要明确的频道管理员权限。使用预览页面的意义就在于为公开频道跳过所有限制。 - **不下载图片/视频。** 仅返回消息文本和元数据。如果你自行重新解析 HTML，依然可以访问媒体 URL。 - **不对输出进行消除威胁处理。** 按照 Telegram 渲染时的原样返回纯文本。 - **不提供频道发现/搜索功能。** 你传入一个 handle，获取其消息。列出频道不在本项目的范围内。 ## 测试 ``` npm test ``` 15 个 vitest 测试用例涵盖了实体解码、HTML 剥离、最近窗口过滤、静默回退、文本截断、缺失字段跳过以及四项质量信号评分规则。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：CMS安全, GNU通用公共许可证, JavaScript, Node.js, Telegram, 数据可视化, 数据解析, 暗色界面, 自动化攻击